# 开发指南

<cite>
**本文档引用的文件**
- [Cargo.toml](file://Cargo.toml)
- [README.md](file://README.md)
- [config.yml](file://config.yml)
- [main.rs](file://crates/rcoder/src/main.rs)
- [agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
- [config.rs](file://crates/rcoder/src/config.rs)
- [agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs)
- [router.rs](file://crates/rcoder/src/router.rs)
- [agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
- [agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs)
- [mod.rs](file://crates/rcoder/src/proxy_agent/mod.rs)
- [shared_types/src/lib.rs](file://crates/shared_types/src/lib.rs)
- [shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs)
- [docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)

## 简介
RCoder 是一个基于 Rust 构建的现代化 AI 驱动开发平台，通过 ACP (Agent Client Protocol) 协议实现与多种 AI 代理的统一交互。平台提供简洁的 HTTP API 接口，让开发者能够轻松集成和管理 AI 辅助开发功能。

**Section sources**
- [README.md](file://README.md#L1-L652)

## 项目结构
项目采用 Rust workspace 结构，包含多个 crates，每个 crate 负责特定功能：

```
.
├── crates/
│   ├── acp_adapter/           # ACP 协议适配器
│   ├── agent_runner/          # 代理运行器核心
│   ├── claude-code-agent/     # Claude Code 代理实现
│   ├── codex-acp-agent/       # Codex ACP 代理实现
│   ├── docker_manager/        # Docker 管理器
│   ├── pingora-proxy/         # Pingora 反向代理封装
│   ├── rcoder/                # 主应用（Axum 路由、业务、配置）
│   └── shared_types/          # 共享类型定义
├── docker/                    # Docker 相关脚本和配置
├── specs/                     # 设计文档
├── .dockerignore
├── .gitignore
├── CLAUDE.md
├── Cargo.lock
├── Cargo.toml                 # Workspace 配置
├── Makefile
├── README.md
├── config.yml                 # 默认配置文件
├── http_test.rest
├── install.md
└── test_auto_arch_detection.sh
```

**Section sources**
- [README.md](file://README.md#L269-L377)

## 核心组件
系统由多个核心组件构成，包括主应用、代理运行器、Docker 管理器、Pingora 反向代理和共享类型。

**Section sources**
- [Cargo.toml](file://Cargo.toml#L1-L205)
- [README.md](file://README.md#L380-L382)

## 架构概述
系统采用微服务架构，主要组件包括主服务、代理运行器和反向代理。

```mermaid
graph TB
A[Client] --> B[Axum HTTP Server]
A --> C[Pingora Proxy]
B --> D[API Routes]
B --> E[Agent Worker (LocalSet)]
C --> F[Backends: 127.0.0.1:{port}]
```

**Diagram sources**
- [README.md](file://README.md#L18-L25)

## 详细组件分析

### 配置系统分析
配置系统支持多层优先级配置，从高到低为：命令行参数 > 环境变量 > 配置文件 > 默认配置。

#### 配置结构
```mermaid
classDiagram
class AppConfig {
+default_agent : AgentType
+projects_dir : PathBuf
+port : u16
+proxy_config : Option<ProxyConfig>
+docker_config : Option<DockerConfig>
}
class ProxyConfig {
+listen_port : u16
+default_backend_port : u16
+backend_host : String
+port_param : String
+health_check : HealthCheckConfig
}
class DockerConfig {
+multi_image_config : Option<MultiImageConfig>
+network_mode : Option<String>
+work_dir : Option<String>
+auto_cleanup : Option<bool>
+container_ttl_seconds : Option<u64>
}
class HealthCheckConfig {
+enabled : bool
+interval_seconds : u64
+timeout_seconds : u64
+healthy_threshold : u32
+unhealthy_threshold : u32
}
AppConfig --> ProxyConfig : "包含"
AppConfig --> DockerConfig : "包含"
ProxyConfig --> HealthCheckConfig : "包含"
```

**Diagram sources**
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L38-L96)
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L39-L73)

#### 配置加载流程
```mermaid
flowchart TD
Start([开始加载配置]) --> CheckFile["检查配置文件是否存在"]
CheckFile --> |存在| LoadFromFile["从文件加载配置"]
CheckFile --> |不存在| CreateDefault["创建默认配置文件"]
LoadFromFile --> ApplyEnv["应用环境变量覆盖"]
CreateDefault --> ApplyEnv
ApplyEnv --> ApplyCli["应用命令行参数覆盖"]
ApplyCli --> Validate["验证配置"]
Validate --> End([返回最终配置])
```

**Diagram sources**
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L254-L331)
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L111-L191)

### 主应用分析
主应用负责处理 HTTP 请求、管理会话状态和协调其他组件。

#### 主应用启动流程
```mermaid
sequenceDiagram
participant Main as main()
participant Config as load_config_with_args()
participant PathResolver as HostPathResolver
participant DockerManager as DockerManager
participant Cleanup as startup_cleanup_containers()
participant Proxy as PingoraServerManager
participant Server as Axum Server
Main->>Config : 解析命令行参数并加载配置
Config-->>Main : 返回配置对象
Main->>PathResolver : 初始化宿主机路径解析器
PathResolver-->>Main : 返回路径解析器
Main->>DockerManager : 初始化全局 DockerManager
DockerManager-->>Main : 返回 DockerManager 实例
Main->>Cleanup : 启动时清理遗留容器
Cleanup-->>Main : 清理结果
Main->>Proxy : 启动 Pingora 反向代理如果启用
Proxy-->>Main : 代理服务句柄
Main->>Server : 创建路由并启动 HTTP 服务器
Server-->>Main : 服务器句柄
Main->>Main : 等待关闭信号
Main->>Main : 执行优雅关闭
```

**Diagram sources**
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L32-L451)

### 路由系统分析
路由系统使用 Axum 框架，提供 REST API 和 SSE 流接口。

#### 路由结构
```mermaid
classDiagram
class AppState {
+config : AppConfig
+sessions : DashMap<String, Arc<ProjectAndContainerInfo>>
+project_and_agent_map : DashMap<String, Arc<ProjectAndContainerInfo>>
+pingora_service : Option<Arc<PingoraProxyService>>
}
class Router {
+create_router(state : Arc<AppState>) Router
+create_swagger_ui() SwaggerUi
}
class SessionInfo {
+session_id : String
+user_id : String
+project_id : Option<String>
+created_at : DateTime<Utc>
+last_activity : DateTime<Utc>
}
Router --> AppState : "使用"
AppState --> SessionInfo : "包含"
```

**Diagram sources**
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L26-L36)
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L26-L38)

#### API 路由流程
```mermaid
flowchart TD
Start([HTTP 请求]) --> MatchRoute["匹配路由"]
MatchRoute --> |/health| HealthCheck["健康检查处理器"]
MatchRoute --> |/chat| ChatHandler["聊天处理器"]
MatchRoute --> |/agent/progress/{session_id}| SSEHandler["SSE 通知处理器"]
MatchRoute --> |/agent/session/cancel| CancelHandler["会话取消处理器"]
MatchRoute --> |/agent/stop| StopHandler["代理停止处理器"]
MatchRoute --> |/agent/status/{project_id}| StatusHandler["状态查询处理器"]
MatchRoute --> |/proxy/*| ProxyHandler["代理处理器"]
HealthCheck --> Response["返回健康状态"]
ChatHandler --> Response
SSEHandler --> Response
CancelHandler --> Response
StopHandler --> Response
StatusHandler --> Response
ProxyHandler --> Response
```

**Diagram sources**
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L53-L83)
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L41-L69)

### 聊天处理器分析
聊天处理器负责处理用户聊天请求，转发到容器化代理服务。

#### 聊天请求处理流程
```mermaid
sequenceDiagram
participant Client as 客户端
participant Handler as handle_chat
participant Container as ContainerManager
participant Forward as forward_request_to_container_service
participant Agent as agent_runner
Client->>Handler : 发送聊天请求
Handler->>Container : 获取或创建容器
Container-->>Handler : 返回容器信息
Handler->>Handler : 更新项目状态映射
Handler->>Forward : 转发请求到容器服务
Forward->>Agent : 发送 HTTP 请求到 agent_runner
Agent-->>Forward : 返回处理结果
Forward-->>Handler : 返回解析结果
Handler->>Handler : 更新会话状态
Handler-->>Client : 返回响应
```

**Diagram sources**
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L108-L321)

### SSE 通知处理器分析
SSE 通知处理器负责建立服务器发送事件连接，实时推送代理执行进度。

#### SSE 代理流程
```mermaid
flowchart TD
Start([SSE 连接请求]) --> FindContainer["查找对应容器"]
FindContainer --> |找到| GetSSEURL["获取容器 SSE 端点 URL"]
FindContainer --> |未找到| ReturnError["返回 404 错误"]
GetSSEURL --> |成功| CreateStream["创建 SSE 代理流"]
GetSSEURL --> |失败| ReturnError
CreateStream --> ConnectContainer["连接到容器 SSE 端点"]
ConnectContainer --> |成功| ForwardEvents["转发 SSE 事件"]
ConnectContainer --> |失败| SendErrorEvent["发送错误事件"]
ForwardEvents --> Client["客户端接收事件"]
SendErrorEvent --> Client
```

**Diagram sources**
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L97-L153)

### Docker 管理器分析
Docker 管理器负责容器的创建、启动、停止和删除操作。

#### 多镜像配置结构
```mermaid
classDiagram
class MultiImageConfig {
+global_defaults : GlobalImageDefaults
+services : HashMap<String, ServiceImageConfig>
+selection_strategy : ImageSelectionStrategy
+cache_config : ImageCacheConfig
}
class GlobalImageDefaults {
+image : Option<String>
+arm64_image : Option<String>
+amd64_image : Option<String>
+default_image : Option<String>
+registry_prefix : Option<String>
}
class ServiceImageConfig {
+service_type : ServiceType
+image : Option<String>
+arm64_image : Option<String>
+amd64_image : Option<String>
+default_image : Option<String>
+image_tag_prefix : String
+enabled : bool
+environment : HashMap<String, String>
+command : Vec<String>
+entrypoint : Option<Vec<String>>
+resource_limits : ResourceLimits
+work_dir : String
+network_mode : String
+mounts : Vec<ServiceMountConfig>
}
class ImageSelectionStrategy {
+ServiceOnly
}
class ImageCacheConfig {
+enabled : bool
+ttl_seconds : u64
+max_entries : usize
}
MultiImageConfig --> GlobalImageDefaults : "包含"
MultiImageConfig --> ServiceImageConfig : "包含多个"
MultiImageConfig --> ImageSelectionStrategy : "包含"
MultiImageConfig --> ImageCacheConfig : "包含"
```

**Diagram sources**
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L17-L26)

#### 全局 DockerManager 结构
```mermaid
classDiagram
class DockerManager {
+config : DockerManagerConfig
+docker : Docker
+image_selector : ImageSelector
}
class DockerManagerConfig {
+multi_image_config : MultiImageConfig
+auto_cleanup : bool
+container_ttl_seconds : Option<u64>
}
class ImageSelector {
+select_image(service_type : ServiceType) String
}
class global {
+init_global_docker_manager() DockerResult<()>
+init_global_docker_manager_with_config(config : DockerManagerConfig) DockerResult<()>
+get_global_docker_manager() DockerResult<Arc<DockerManager>>
+with_global_docker_manager(f : FnOnce(&Arc<DockerManager>) -> R) DockerResult<R>
}
DockerManager --> DockerManagerConfig : "使用"
DockerManager --> ImageSelector : "使用"
global --> DockerManager : "管理单例"
```

**Diagram sources**
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L144-L210)

## 依赖分析
项目依赖关系复杂，主要依赖包括：

```mermaid
graph TB
subgraph "主应用"
Rcoder[rcoder]
AgentRunner[agent_runner]
end
subgraph "基础设施"
Pingora[pingora-proxy]
DockerManager[docker_manager]
SharedTypes[shared_types]
end
subgraph "协议适配"
AcpAdapter[acp_adapter]
ClaudeAgent[claude-code-agent]
CodexAgent[codex-acp-agent]
end
Rcoder --> AgentRunner
Rcoder --> Pingora
Rcoder --> DockerManager
Rcoder --> SharedTypes
AgentRunner --> Pingora
AgentRunner --> DockerManager
AgentRunner --> SharedTypes
AcpAdapter --> SharedTypes
ClaudeAgent --> AcpAdapter
CodexAgent --> AcpAdapter
style Rcoder fill:#f9f,stroke:#333
style AgentRunner fill:#f9f,stroke:#333
```

**Diagram sources**
- [Cargo.toml](file://Cargo.toml#L1-L205)

## 性能考虑
系统在设计时考虑了多项性能优化：

1. **异步架构**：使用 Tokio 异步运行时，支持高并发处理
2. **状态管理**：使用 DashMap 实现高效的并发状态管理
3. **连接复用**：使用 reqwest 客户端复用 HTTP 连接
4. **日志优化**：使用 tracing 和 JSON 格式日志，便于后续分析
5. **资源清理**：定期清理闲置容器，释放系统资源

**Section sources**
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L160-L164)
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L158-L164)

## 故障排除指南
常见问题及解决方案：

### 容器自检测失败
当容器自检测失败时，检查以下配置：
- Docker socket 路径是否正确
- Docker socket 是否已挂载到容器
- 容器是否有权限访问 Docker API
- 项目工作目录是否正确挂载

### 端口被占用
使用 `--port` 参数指定其他端口：
```bash
cargo run --bin rcoder -- --port 8087
```

### AI 代理连接失败
检查 API 密钥和网络连接，确保相关服务已正确配置。

### 配置文件错误
检查 YAML 格式和字段名称，确保配置文件语法正确。

**Section sources**
- [README.md](file://README.md#L620-L626)

## 结论
RCoder 是一个功能强大的 AI 驱动开发平台，通过模块化设计和现代化技术栈实现了高效的 AI 代理集成。系统具有良好的可扩展性和维护性，适合进一步开发和定制。