497 lines
15 KiB
Markdown
497 lines
15 KiB
Markdown
# 项目概述
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [README.md](file://README.md)
|
||
- [Cargo.toml](file://Cargo.toml)
|
||
- [crates/rcoder/Cargo.toml](file://crates/rcoder/Cargo.toml)
|
||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
|
||
- [crates/rcoder/src/lib.rs](file://crates/rcoder/src/lib.rs)
|
||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
|
||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
|
||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs)
|
||
- [crates/acp_adapter/src/lib.rs](file://crates/acp_adapter/src/lib.rs)
|
||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
|
||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs)
|
||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs)
|
||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构概览](#架构概览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [配置系统](#配置系统)
|
||
8. [API接口](#api接口)
|
||
9. [使用示例](#使用示例)
|
||
10. [故障排除](#故障排除)
|
||
|
||
## 简介
|
||
|
||
RCoder 是一个基于 Rust 构建的现代化 AI 驱动开发平台，通过 ACP (Agent Client Protocol) 协议实现与多种 AI 代理的统一交互。平台提供简洁的 HTTP API 接口，让开发者能够轻松集成和管理 AI 辅助开发功能。
|
||
|
||
RCoder 采用模块化设计，通过 Rust 的 Workspace 特性组织多个功能组件，包括主应用、代理运行器、Docker 管理器、Pingora 反向代理等。平台支持多种 AI 代理，如 Codex 和 Claude Code，并通过反向代理机制实现高性能的端口路由。
|
||
|
||
**本文档引用的文件**
|
||
- [README.md](file://README.md#L1-L652)
|
||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||
|
||
## 项目结构
|
||
|
||
RCoder 项目采用 Rust Workspace 结构，将不同功能模块分离到独立的 crate 中，实现高内聚低耦合的设计。
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[crates/] --> B[rcoder]
|
||
A --> C[agent_runner]
|
||
A --> D[shared_types]
|
||
A --> E[acp_adapter]
|
||
A --> F[pingora-proxy]
|
||
A --> G[docker_manager]
|
||
A --> H[claude-code-agent]
|
||
A --> I[codex-acp-agent]
|
||
B --> J[src/]
|
||
C --> K[src/]
|
||
D --> L[src/]
|
||
E --> M[src/]
|
||
F --> N[src/]
|
||
G --> O[src/]
|
||
J --> P[main.rs]
|
||
J --> Q[router.rs]
|
||
J --> R[config.rs]
|
||
J --> S[handler/]
|
||
J --> T[service/]
|
||
K --> U[proxy_agent/]
|
||
K --> V[service/]
|
||
L --> W[model/]
|
||
M --> X[types.rs]
|
||
N --> Y[server.rs]
|
||
O --> Z[manager.rs]
|
||
```
|
||
|
||
**图表来源**
|
||
- [README.md](file://README.md#L269-L377)
|
||
|
||
**本文档引用的文件**
|
||
- [README.md](file://README.md#L269-L377)
|
||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||
|
||
## 核心组件
|
||
|
||
RCoder 的核心组件包括主应用、代理适配器、反向代理和 Docker 管理器。这些组件协同工作，提供完整的 AI 代理管理功能。
|
||
|
||
主应用（rcoder）负责处理 HTTP 请求、管理会话状态和协调各个组件。代理适配器（acp_adapter）提供与 ACP 协议兼容的通信功能。反向代理（pingora-proxy）基于 Cloudflare Pingora 实现高性能的端口路由。Docker 管理器（docker_manager）负责容器的生命周期管理。
|
||
|
||
**本文档引用的文件**
|
||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||
- [crates/acp_adapter/src/lib.rs](file://crates/acp_adapter/src/lib.rs#L1-L13)
|
||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L250)
|
||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L1-L211)
|
||
|
||
## 架构概览
|
||
|
||
RCoder 采用分层架构设计，各组件职责明确，通过清晰的接口进行通信。
|
||
|
||
```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}]
|
||
D --> G[Handler Modules]
|
||
G --> H[Container Manager]
|
||
H --> I[Docker Manager]
|
||
I --> J[Docker Engine]
|
||
G --> K[Session Cache]
|
||
G --> L[Config Manager]
|
||
```
|
||
|
||
**图表来源**
|
||
- [README.md](file://README.md#L18-L25)
|
||
|
||
**本文档引用的文件**
|
||
- [README.md](file://README.md#L16-L25)
|
||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L31-L451)
|
||
|
||
## 详细组件分析
|
||
|
||
### 主应用分析
|
||
|
||
主应用是 RCoder 的核心，负责启动服务、处理请求和协调各个组件。
|
||
|
||
#### 主函数分析
|
||
```mermaid
|
||
flowchart TD
|
||
Start([启动 RCoder]) --> InitTelemetry["初始化遥测系统"]
|
||
InitTelemetry --> ParseArgs["解析命令行参数"]
|
||
ParseArgs --> LoadConfig["加载配置文件"]
|
||
LoadConfig --> CreateDir["创建项目目录"]
|
||
CreateDir --> InitPathResolver["初始化路径解析器"]
|
||
InitPathResolver --> InitDockerManager["初始化 Docker Manager"]
|
||
InitDockerManager --> CleanupContainers["清理遗留容器"]
|
||
CleanupContainers --> StartProxy["启动 Pingora 代理"]
|
||
StartProxy --> SetupSignal["设置信号处理器"]
|
||
SetupSignal --> CreateState["创建应用状态"]
|
||
CreateState --> StartCleanup["启动清理任务"]
|
||
CreateState --> CreateRouter["创建路由"]
|
||
CreateRouter --> StartServer["启动 HTTP 服务器"]
|
||
StartServer --> WaitShutdown["等待关闭信号"]
|
||
WaitShutdown --> CleanupAll["清理所有容器"]
|
||
CleanupAll --> End([服务关闭])
|
||
```
|
||
|
||
**图表来源**
|
||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L31-L451)
|
||
|
||
**本文档引用的文件**
|
||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L31-L451)
|
||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L1-L403)
|
||
|
||
#### 配置系统分析
|
||
```mermaid
|
||
classDiagram
|
||
class AppConfig {
|
||
+default_agent : AgentType
|
||
+projects_dir : PathBuf
|
||
+port : u16
|
||
+proxy_config : Option<ProxyConfig>
|
||
+docker_config : Option<DockerConfig>
|
||
}
|
||
class CliArgs {
|
||
+port : Option<u16>
|
||
+projects_dir : Option<String>
|
||
+enable_proxy : bool
|
||
+proxy_port : Option<u16>
|
||
+default_backend_port : Option<u16>
|
||
}
|
||
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 : "包含"
|
||
DockerConfig --> MultiImageConfig : "包含"
|
||
```
|
||
|
||
**图表来源**
|
||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L38-L109)
|
||
|
||
**本文档引用的文件**
|
||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L1-L403)
|
||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L513)
|
||
|
||
### 聊天处理器分析
|
||
|
||
聊天处理器负责处理用户发送的聊天消息，并将其转发到相应的 AI 代理。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as "客户端"
|
||
participant Handler as "ChatHandler"
|
||
participant Container as "ContainerManager"
|
||
participant Docker as "DockerManager"
|
||
participant Agent as "AgentRunner"
|
||
Client->>Handler : POST /chat
|
||
Handler->>Container : get_or_create_container()
|
||
Container->>Docker : create_container()
|
||
Docker-->>Container : ContainerInfo
|
||
Container-->>Handler : ContainerInfo
|
||
Handler->>Agent : 转发聊天请求
|
||
Agent-->>Handler : 返回响应
|
||
Handler->>Client : 返回响应
|
||
```
|
||
|
||
**图表来源**
|
||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L1-L431)
|
||
|
||
**本文档引用的文件**
|
||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L1-L431)
|
||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs)
|
||
|
||
### SSE 通知处理器分析
|
||
|
||
SSE 通知处理器负责处理 Server-Sent Events (SSE) 连接，实现实时进度流。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[收到SSE连接请求] --> B{找到对应容器?}
|
||
B --> |是| C[获取容器SSE端点URL]
|
||
B --> |否| D[返回404错误]
|
||
C --> E[建立SSE代理连接]
|
||
E --> F[转发SSE事件]
|
||
F --> G[客户端接收实时消息]
|
||
D --> H[客户端收到错误]
|
||
```
|
||
|
||
**图表来源**
|
||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L1-L378)
|
||
|
||
**本文档引用的文件**
|
||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L1-L378)
|
||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs)
|
||
|
||
## 依赖关系分析
|
||
|
||
RCoder 项目采用依赖注入和模块化设计，各组件之间的依赖关系清晰。
|
||
|
||
```mermaid
|
||
graph LR
|
||
A[rcoder] --> B[shared_types]
|
||
A --> C[acp_adapter]
|
||
A --> D[pingora-proxy]
|
||
A --> E[docker_manager]
|
||
A --> F[claude-code-agent]
|
||
B --> G[agent-client-protocol]
|
||
C --> G
|
||
D --> H[pingora]
|
||
E --> I[bollard]
|
||
F --> J[serde]
|
||
F --> K[reqwest]
|
||
A --> L[axum]
|
||
A --> M[tokio]
|
||
A --> N[tracing]
|
||
L --> O[tower]
|
||
M --> P[futures]
|
||
N --> Q[tracing-subscriber]
|
||
```
|
||
|
||
**图表来源**
|
||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||
- [crates/rcoder/Cargo.toml](file://crates/rcoder/Cargo.toml#L1-L91)
|
||
|
||
**本文档引用的文件**
|
||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||
- [crates/rcoder/Cargo.toml](file://crates/rcoder/Cargo.toml#L1-L91)
|
||
- [crates/agent_runner/Cargo.toml](file://crates/agent_runner/Cargo.toml#L1-L79)
|
||
|
||
## 配置系统
|
||
|
||
RCoder 提供灵活的配置系统，支持多种配置方式，优先级从高到低为：命令行参数 > 环境变量 > 配置文件 > 默认配置。
|
||
|
||
### 配置优先级
|
||
```mermaid
|
||
flowchart TD
|
||
A[命令行参数] --> B[环境变量]
|
||
B --> C[配置文件]
|
||
C --> D[默认配置]
|
||
D --> E[最终配置]
|
||
```
|
||
|
||
### 配置文件结构
|
||
```yaml
|
||
# rcoder 配置文件
|
||
|
||
# 默认使用的 AI 代理类型
|
||
# 可选值: "Codex", "Claude"
|
||
default_agent: Codex
|
||
|
||
# 项目工作的根目录
|
||
projects_dir: "./project_workspace"
|
||
|
||
# 服务端口
|
||
port: 3000
|
||
|
||
# 反向代理配置
|
||
proxy_config:
|
||
listen_port: 8088
|
||
default_backend_port: 8086
|
||
backend_host: "127.0.0.1"
|
||
port_param: "port"
|
||
health_check:
|
||
enabled: true
|
||
interval_seconds: 5
|
||
timeout_seconds: 1
|
||
healthy_threshold: 2
|
||
unhealthy_threshold: 3
|
||
|
||
# Docker 配置
|
||
docker_config:
|
||
multi_image_config:
|
||
services:
|
||
rcoder:
|
||
image: null
|
||
arm64_image: "registry.yichamao.com/rcoder:latest-arm64"
|
||
amd64_image: "registry.yichamao.com/rcoder:latest-amd64"
|
||
default_image: "registry.yichamao.com/rcoder:latest"
|
||
image_tag_prefix: "rcoder"
|
||
enabled: true
|
||
environment:
|
||
RUST_LOG: "info"
|
||
SERVICE_MODE: "full"
|
||
API_PORT: "8086"
|
||
mounts: []
|
||
command:
|
||
- "/app/bin/agent_runner"
|
||
- "--port"
|
||
- "8086"
|
||
entrypoint: null
|
||
resource_limits:
|
||
memory_limit: 2147483648
|
||
cpu_limit: 2
|
||
swap_limit: 4294967296
|
||
disk_limit: null
|
||
process_limit: null
|
||
work_dir: "/app"
|
||
network_mode: "bridge"
|
||
container_path_template: "/app/project_workspace/{project_id}"
|
||
agent-runner:
|
||
image: null
|
||
arm64_image: "registry.yichamao.com/rcoder-agent-runner:latest-arm64"
|
||
amd64_image: "registry.yichamao.com/rcoder-agent-runner:latest-amd64"
|
||
default_image: "registry.yichamao.com/rcoder-agent-runner:latest"
|
||
image_tag_prefix: "rcoder-agent-runner"
|
||
enabled: false
|
||
environment:
|
||
RUST_LOG: "debug"
|
||
SERVICE_MODE: "agent-only"
|
||
AGENT_PORT: "8086"
|
||
mounts: []
|
||
command:
|
||
- "/app/bin/agent_runner"
|
||
- "--port"
|
||
- "8086"
|
||
entrypoint: null
|
||
resource_limits:
|
||
memory_limit: 4294967296
|
||
cpu_limit: 3
|
||
swap_limit: 8589934592
|
||
disk_limit: null
|
||
process_limit: null
|
||
work_dir: "/app"
|
||
network_mode: "bridge"
|
||
container_path_template: "/app/project_workspace/{project_id}"
|
||
global_defaults:
|
||
image: null
|
||
arm64_image: null
|
||
amd64_image: null
|
||
default_image: null
|
||
registry_prefix: null
|
||
selection_strategy: ServiceOnly
|
||
cache_config:
|
||
enabled: true
|
||
ttl_seconds: 3600
|
||
max_entries: 100
|
||
network_mode: "bridge"
|
||
work_dir: "/app"
|
||
auto_cleanup: true
|
||
container_ttl_seconds: 3600
|
||
```
|
||
|
||
**本文档引用的文件**
|
||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L1-L403)
|
||
- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml)
|
||
|
||
## API接口
|
||
|
||
RCoder 提供 RESTful API 接口，支持健康检查、聊天交互、进度流等功能。
|
||
|
||
### 核心端点
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/health` | GET | 健康检查 |
|
||
| `/chat` | POST | 发送聊天消息给 AI 代理 |
|
||
| `/agent/progress/{session_id}` | GET (SSE) | 获取统一实时进度流 |
|
||
| `/agent/session/cancel` | POST | 取消正在执行的任务 |
|
||
| `/agent/stop` | POST | 停止当前 Agent |
|
||
| `/agent/status/{project_id}` | GET | 查询 Agent 状态 |
|
||
| `/api/docs` | GET | Swagger UI API 文档 |
|
||
|
||
### Pingora 代理相关端点
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/proxy/status` | GET | 查看代理服务状态 |
|
||
| `/proxy/config` | GET | 查看代理配置 |
|
||
| `/proxy/stats` | GET | 查看代理统计信息 |
|
||
| `/proxy/{port}/{path}` | GET | 代理到指定端口的服务 |
|
||
|
||
**本文档引用的文件**
|
||
- [README.md](file://README.md#L209-L227)
|
||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||
|
||
## 使用示例
|
||
|
||
### 启动服务
|
||
```bash
|
||
# 使用默认端口 3000
|
||
cargo run --bin rcoder
|
||
|
||
# 指定端口和项目目录
|
||
cargo run --bin rcoder -- --port 8087 --projects-dir ./my-projects
|
||
|
||
# 启用并运行 Pingora 反向代理
|
||
cargo run --bin rcoder -- --enable-proxy --proxy-port 8080
|
||
|
||
# 指定默认后端端口
|
||
cargo run --bin rcoder -- --enable-proxy --proxy-port 8080 --default-backend-port 3000
|
||
```
|
||
|
||
### API 调用示例
|
||
```bash
|
||
# 健康检查
|
||
curl -X GET http://localhost:3000/health
|
||
|
||
# 发送聊天消息
|
||
curl -X POST http://localhost:3000/chat \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"prompt": "你好，请帮我创建一个 Rust Web API 项目",
|
||
"project_id": "my-rust-project"
|
||
}'
|
||
|
||
# 获取实时进度流
|
||
curl -X GET http://localhost:3000/agent/progress/your-session-id \
|
||
-H "Accept: text/event-stream"
|
||
|
||
# 代理请求示例
|
||
curl "http://127.0.0.1:8080/proxy/5173/page/1977625137029189632/prod/"
|
||
```
|
||
|
||
**本文档引用的文件**
|
||
- [README.md](file://README.md#L61-L198)
|
||
- [http_test.rest](file://http_test.rest)
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
- **端口被占用**: 使用 `--port` 参数指定其他端口
|
||
- **AI 代理连接失败**: 检查 API 密钥和网络连接
|
||
- **配置文件错误**: 检查 YAML 格式和字段名称
|
||
- **容器自检测失败**: 检查 Docker socket 路径和权限
|
||
|
||
### Docker 配置帮助
|
||
```bash
|
||
# 确保 docker-compose.yml 包含以下配置
|
||
services:
|
||
rcoder:
|
||
environment:
|
||
- DOCKER_SOCKET_PATH=/var/run/docker.sock
|
||
volumes:
|
||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||
- ./data/rcoder/project_workspace:/app/project_workspace
|
||
```
|
||
|
||
**本文档引用的文件**
|
||
- [README.md](file://README.md#L611-L626)
|
||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L322-L350) |