byy/qiming
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
09d65701a30ede4ccbc0ab7dc0eaf70770a120f0
qiming/qiming-rcoder/.qoder/repowiki/zh/content/项目概述.md
Codex 4b1a580132 添加qiming-rcoder模块
2026-06-01 13:54:52 +08:00

497 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 项目概述
<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)
Reference in New Issue View Git Blame Copy Permalink