446 lines
14 KiB
Markdown
446 lines
14 KiB
Markdown
# 开发指南
|
||
|
||
<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 代理集成。系统具有良好的可扩展性和维护性，适合进一步开发和定制。 |