byy/qiming

Files

2026-06-01 13:54:52 +08:00

14 KiB

Raw Blame History

开发指南

**本文档引用的文件** - [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)

简介

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

Section sources

README.md

项目结构

项目采用 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

核心组件

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

Section sources

架构概述

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

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

详细组件分析

配置系统分析

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

配置结构

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

配置加载流程

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

Diagram sources

主应用分析

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

主应用启动流程

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

路由系统分析

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

路由结构

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

API 路由流程

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

聊天处理器分析

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

聊天请求处理流程

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

SSE 通知处理器分析

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

SSE 代理流程

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

Docker 管理器分析

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

多镜像配置结构

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

全局 DockerManager 结构

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

依赖分析

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

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

性能考虑

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

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

Section sources

故障排除指南

常见问题及解决方案：

容器自检测失败

当容器自检测失败时，检查以下配置：

Docker socket 路径是否正确
Docker socket 是否已挂载到容器
容器是否有权限访问 Docker API
项目工作目录是否正确挂载

端口被占用

使用 --port 参数指定其他端口：

cargo run --bin rcoder -- --port 8087

AI 代理连接失败

检查 API 密钥和网络连接，确保相关服务已正确配置。

配置文件错误

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

Section sources

README.md

结论

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

14 KiB Raw Blame History Unescape Escape

开发指南

目录

简介

项目结构

核心组件

架构概述

详细组件分析

配置系统分析

配置结构

配置加载流程

主应用分析

主应用启动流程

路由系统分析

路由结构

API 路由流程

聊天处理器分析

聊天请求处理流程

SSE 通知处理器分析

SSE 代理流程

Docker 管理器分析

多镜像配置结构

全局 DockerManager 结构

依赖分析

性能考虑

故障排除指南

容器自检测失败

端口被占用

AI 代理连接失败

配置文件错误

结论

14 KiB

Raw Blame History