添加qiming-rcoder模块
This commit is contained in:
Codex
446
qiming-rcoder/.qoder/repowiki/zh/content/开发指南.md
Normal file
446
qiming-rcoder/.qoder/repowiki/zh/content/开发指南.md
Normal file
@@ -0,0 +1,446 @@
|
||||
# 开发指南
|
||||
|
||||
<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 代理集成。系统具有良好的可扩展性和维护性，适合进一步开发和定制。
|
||||
Reference in New Issue
Block a user