# 变更日志

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [Cargo.toml](file://Cargo.toml)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
- [crates/rcoder/src/handler/proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs)
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs)
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs)
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs)
- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件旨在系统化梳理 RCoder 项目在版本迭代中的变更，围绕功能更新、缺陷修复与架构演进，结合代码库中的实际实现，解释变更日志在版本控制、升级路径与向后兼容性中的作用，并提供升级评估与问题排查的最佳实践。由于仓库未包含 CHANGELOG.md 文件，本文将基于现有 README 与源码，对 v0.1.0 版本的现状与关键特性进行总结，并给出面向未来的变更日志模板与生成建议，以便团队在后续版本中持续完善。

## 项目结构
RCoder 采用多 crate 的工作区组织，核心模块包括：
- 主应用与路由：rcodes/rcoder
- Pingora 反向代理封装：crates/pingora-proxy
- Docker 容器管理：crates/docker_manager
- 共享类型与协议：crates/shared_types
- 代理适配器与示例：acp_adapter、claude-code-agent、codex-acp-agent 等

```mermaid
graph TB
subgraph "工作区"
A["crates/rcoder<br/>主应用/路由/配置/代理启动"]
B["crates/pingora-proxy<br/>Pingora 反向代理库"]
C["crates/docker_manager<br/>Docker 管理器/镜像选择/全局实例"]
D["crates/shared_types<br/>共享模型/多镜像配置"]
E["crates/acp_adapter<br/>ACP 协议适配"]
F["crates/claude-code-agent<br/>Claude 代理示例"]
G["crates/codex-acp-agent<br/>Codex 代理示例"]
end
A --> B
A --> C
A --> D
A --> E
A --> F
A --> G
```

图表来源
- [Cargo.toml](file://Cargo.toml#L1-L20)
- [README.md](file://README.md#L269-L378)

章节来源
- [Cargo.toml](file://Cargo.toml#L1-L20)
- [README.md](file://README.md#L269-L378)

## 核心组件
- 主应用与配置系统：命令行参数、环境变量、配置文件三段式优先级，支持代理与 Docker 配置的加载与覆盖。
- Pingora 反向代理：Axum + Pingora 的双服务架构，主服务提供 API/SSE，Pingora 独立监听代理端口，路径前缀路由到目标后端。
- Docker 管理器：全局单例、镜像选择策略、容器生命周期管理、清理任务与网络/挂载配置。
- 共享类型：多镜像配置结构、服务类型枚举、镜像选择器与缓存策略。

章节来源
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L1-L120)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L160-L210)
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L120)
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L140-L211)
- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L40-L120)

## 架构总览
RCoder 采用“主服务 + Pingora 代理”的双服务架构：
- 主服务（Axum）：提供健康检查、聊天、SSE 实时进度、代理状态/配置/统计等接口。
- Pingora 代理：独立监听代理端口，按路径前缀 /proxy/{port}/{path} 转发到指定后端，支持动态后端发现与健康检查。

```mermaid
graph TB
Client["客户端"] --> Axum["主服务(Axum)<br/>端口: config.port"]
Client --> Pingora["Pingora 代理<br/>端口: proxy_config.listen_port"]
Axum --> API["业务 API/SSE"]
Axum --> ProxyDocs["/proxy/* 文档接口"]
Pingora --> Backend["后端服务<br/>127.0.0.1:{port}"]
```

图表来源
- [README.md](file://README.md#L133-L206)
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)

章节来源
- [README.md](file://README.md#L133-L206)
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)

## 详细组件分析

### 变更日志模板与生成建议
为保证变更日志的可追溯性与可维护性，建议采用如下模板（示例，非仓库既有内容）：
- 版本号：vX.Y.Z
- 发布日期：YYYY-MM-DD
- 关键变更
  - 新增：新增 API 端点、代理支持类型扩展、配置系统优化、可观测性增强等
  - 修复：缺陷修复、兼容性问题修正、性能回归修复等
  - 变更：架构调整、依赖升级、行为变更、弃用项等
- 升级指引：影响范围、破坏性变更、迁移步骤、兼容性说明
- 问题排查：常见问题、诊断方法、相关日志位置

说明：本仓库未包含 CHANGELOG.md 文件，本文基于现有 README 与源码总结 v0.1.0 的现状与关键特性，作为后续版本变更日志的参考。

章节来源
- [README.md](file://README.md#L627-L652)

### v0.1.0 版本要点（基于现有 README 与源码）
- 新增功能
  - 基于 ACP 协议的 AI 代理统一管理（Codex、Claude Code）
  - HTTP API 接口与统一 SSE 进度流
  - 多层配置系统（命令行 > 环境变量 > 配置文件 > 默认）
  - OpenTelemetry 集成与分布式追踪
  - Swagger UI API 文档
  - 项目文件解析器（Nuwax Parser）
- 技术特性
  - 基于 Rust 2024 Edition
  - 异步架构（Tokio）
  - 模块化设计（Workspace Crates）
  - 实时通信（SSE）
  - 结构化日志（Tracing）

章节来源
- [README.md](file://README.md#L627-L652)

### Pingora 反向代理能力与变更要点
- 能力概述
  - 独立监听代理端口，路径前缀路由到目标后端
  - 支持动态后端发现与健康检查
  - 提供状态、配置、统计等查询接口（Axum 文档接口）
- 关键实现
  - 主应用在启动时根据配置创建 Pingora 服务器管理器，并在后台启动
  - 路由中提供 /proxy/* 文档接口，真实代理请求需直接发送到 Pingora 端口
  - 代理库提供便捷函数与错误类型，支持快速启动与错误处理

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Axum as "主服务(Axum)"
participant Router as "路由"
participant Pingora as "Pingora 代理"
participant Backend as "后端服务"
Client->>Axum : "GET /proxy/status"
Axum->>Router : "匹配 /proxy/*"
Router-->>Client : "返回状态/配置/统计(文档接口)"
Client->>Pingora : "GET /proxy/{port}/{path}"
Pingora->>Backend : "转发到 127.0.0.1 : {port}"
Backend-->>Pingora : "响应"
Pingora-->>Client : "返回代理响应"
```

图表来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L67-L79)
- [crates/rcoder/src/handler/proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L1-L120)
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L120)

章节来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L67-L79)
- [crates/rcoder/src/handler/proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L1-L120)
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L120)

### Docker 容器管理与镜像选择能力
- 能力概述
  - 全局 DockerManager 单例，支持自动检测平台、镜像选择与缓存
  - 多镜像配置结构，支持服务类型（rcoder/agent-runner）与架构（arm64/amd64）选择
  - 项目级镜像覆盖与环境变量注入
- 关键实现
  - DockerManagerConfig 默认配置与全局初始化
  - ImageSelector 选择策略（ServiceOnly），支持缓存与校验
  - 容器生命周期管理、清理任务与网络/挂载配置

```mermaid
classDiagram
class DockerManager {
+new(config)
+create_container(config)
+get_multi_image_config()
}
class DockerManagerConfig {
+docker_host
+default_image
+default_platform
+default_network_mode
+default_work_dir
+auto_cleanup
+container_ttl_seconds
+multi_image_config
}
class ImageSelector {
+select_image(service_type, project_overrides)
+get_service_config(service_type)
}
class MultiImageConfig {
+services
+global_defaults
+selection_strategy
+cache_config
}
DockerManager --> DockerManagerConfig : "使用"
DockerManager --> ImageSelector : "创建并使用"
ImageSelector --> MultiImageConfig : "读取配置"
```

图表来源
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L140-L211)
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L175-L233)
- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L120-L200)

章节来源
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L140-L211)
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L175-L233)
- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L120-L200)

### 配置系统与升级影响评估
- 配置优先级
  - 命令行参数 > 环境变量 > 配置文件 > 默认配置
- 代理配置
  - 主应用根据命令行与配置文件决定是否启用 Pingora 代理及其监听端口、默认后端端口等
- 升级影响评估
  - 若新增代理端口参数或健康检查配置项，需确保命令行与环境变量覆盖逻辑一致
  - Docker 配置新增字段时，应提供默认值与校验逻辑，避免破坏性变更

```mermaid
flowchart TD
Start(["启动"]) --> ParseCLI["解析命令行参数"]
ParseCLI --> LoadFile["加载配置文件(若存在)"]
LoadFile --> ApplyEnv["应用环境变量覆盖"]
ApplyEnv --> MergeProxy["合并代理配置(端口/默认后端)"]
MergeProxy --> Validate["验证配置(含 Docker 多镜像)"]
Validate --> InitDocker["初始化 DockerManager(全局单例)"]
InitDocker --> StartProxy{"是否启用代理?"}
StartProxy --> |是| RunProxy["启动 Pingora 代理服务"]
StartProxy --> |否| RunMain["启动主服务(Axum)"]
RunProxy --> Done(["完成"])
RunMain --> Done
```

图表来源
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)

章节来源
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)

## 依赖关系分析
- 工作区与依赖
  - 工作区包含多个 crate，主应用默认成员包含 rcoder、agent_runner、shared_types、docker_manager、acp_adapter、claude-code-agent、pingora-proxy
  - 依赖包括 axum、tokio、clap、utoipa、pingora、bollard 等
- 组件耦合
  - rcoder 依赖 pingora-proxy 与 docker_manager，通过配置与全局实例进行解耦
  - 共享类型在 rcoder 与 docker_manager 之间传递，避免重复定义

```mermaid
graph LR
rcoder["rcoder"] --> pingora_proxy["pingora-proxy"]
rcoder --> docker_manager["docker_manager"]
rcoder --> shared_types["shared_types"]
docker_manager --> shared_types
```

图表来源
- [Cargo.toml](file://Cargo.toml#L1-L20)

章节来源
- [Cargo.toml](file://Cargo.toml#L1-L20)

## 性能考量
- 双服务架构
  - 主服务与 Pingora 代理并行运行，互不阻塞，提高吞吐与隔离性
- 代理性能
  - 基于 Rust 异步 I/O 的高性能代理，支持动态后端发现与健康检查
- 观测性
  - OpenTelemetry 与 Tracing 集成，便于定位性能瓶颈与异常

章节来源
- [README.md](file://README.md#L133-L206)
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L120)

## 故障排查指南
- 代理请求未转发
  - 确认请求是否发送到 Pingora 监听端口，而非主服务端口
  - 检查路径前缀是否符合 /proxy/{port}/{path}
- 后端不可达
  - 确认目标后端端口已启动且可访问
- Docker 相关
  - 检查 Docker socket 路径、权限与挂载
  - 查看全局 DockerManager 初始化日志与清理任务输出

章节来源
- [README.md](file://README.md#L193-L206)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L322-L351)

## 结论
- v0.1.0 版本已具备核心能力：统一 AI 代理接入、HTTP API 与 SSE、Pingora 反向代理、Docker 容器管理与多镜像配置、可观测性与文档化。
- 变更日志应聚焦于功能新增、缺陷修复与架构变更，并提供升级指引与兼容性说明。
- 建议在后续版本中补充 CHANGELOG.md，并建立自动化生成与校验流程，确保变更可追溯、可审计。

## 附录

### 变更日志生成最佳实践
- 自动化生成
  - 使用 Git 标签与提交信息生成候选条目
  - 通过 CI 校验变更类型（feat/fix/refactor/chore）与语义化版本
- 人工审核
  - 评审破坏性变更与迁移成本
  - 补充升级指引与兼容性说明
- 模板字段
  - 版本号、发布日期、变更类型、影响范围、修复问题、相关 PR/Issue

### 代码级变更示例（基于现有实现）
- 代理端口与默认后端端口
  - 主应用根据配置创建 Pingora 服务器管理器并启动
  - 路由提供 /proxy/* 文档接口，真实代理请求需直接发送到 Pingora 端口
- Docker 镜像选择
  - ImageSelector 采用 ServiceOnly 策略，优先使用服务特定镜像，支持缓存与校验
  - DockerManagerConfig 默认配置与全局初始化，支持项目级镜像覆盖

章节来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L67-L79)
- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L250-L415)