添加qiming-rcoder模块

2026-06-01 13:54:52 +08:00
parent 8092c4b1f8
commit 4b1a580132
539 changed files with 151650 additions and 0 deletions
--- a/qiming-rcoder/.qoder/repowiki/zh/content/快速开始.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/快速开始.md
@@ -0,0 +1,380 @@
+# 快速开始
+
+<cite>
+**本文引用的文件**
+- [README.md](file://README.md)
+- [install.md](file://install.md)
+- [Cargo.toml](file://Cargo.toml)
+- [config.yml](file://config.yml)
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
+- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
+- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
+- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs)
+- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs)
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
+- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
+- [docker/Dockerfile](file://docker/Dockerfile)
+- [docker/docker-compose.yml](file://docker/docker-compose.yml)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能与可用性](#性能与可用性)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+RCoder 是一个基于 Rust 构建的现代化 AI 驱动开发平台，通过 ACP（Agent Client Protocol）协议实现与多种 AI 代理的统一交互。平台提供简洁的 HTTP API 接口，支持聊天、SSE 实时进度流、代理服务与容器化工作流，适用于本地开发与生产部署。
+
+- 核心能力：反向代理（Cloudflare Pingora）、HTTP API（Axum）、多代理支持（Codex、Claude Code）、异步架构（Tokio）、可观测性（Tracing + OpenTelemetry）、Swagger UI 文档。
+- 快速开始：克隆仓库、构建、运行主服务、可选启用 Pingora 反向代理、使用 curl 或 Swagger UI 调用 API。
+
+**章节来源**
+- file://README.md#L1-L60
+
+## 项目结构
+RCoder 采用多 crate Workspace 组织，核心模块包括：
+- 主应用（rcoder）：Axum 路由、业务处理、配置加载、代理启动
+- 代理运行器（agent_runner）：独立运行 AI 代理工作流，支持本地任务通道与 Pingora 代理
+- Pingora 代理封装（pingora-proxy）：代理配置、服务管理
+- 共享类型（shared_types）：模型、错误、协议类型
+- Claude Code 代理（claude-code-agent）
+- Codex ACP 代理（codex-acp-agent）
+- Docker 管理（docker_manager）
+
+```mermaid
+graph TB
+subgraph "主应用 rcoder"
+A["crates/rcoder/src/main.rs"]
+B["crates/rcoder/src/router.rs"]
+C["crates/rcoder/src/config.rs"]
+D["crates/rcoder/src/handler/chat_handler.rs"]
+end
+subgraph "代理运行器 agent_runner"
+E["crates/agent_runner/src/main.rs"]
+F["crates/agent_runner/src/config.rs"]
+end
+subgraph "代理封装 pingora-proxy"
+G["crates/pingora-proxy/src/config.rs"]
+end
+subgraph "共享类型 shared_types"
+H["crates/shared_types/src/lib.rs"]
+end
+A --> B
+A --> C
+A --> D
+E --> F
+A --> G
+B --> H
+D --> H
+```
+
+**图表来源**
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L120)
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
+- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L1-L120)
+- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L1-L120)
+- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L1-L120)
+- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L1-L120)
+- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L1-L60)
+- [crates/shared_types/src/lib.rs](file://crates/shared_types/src/lib.rs#L1-L50)
+
+**章节来源**
+- file://README.md#L269-L383
+
+## 核心组件
+- 命令行参数与配置优先级：命令行 > 环境变量 > 配置文件 > 默认配置
+- 主服务（rcoder）：启动 Axum HTTP 服务器、加载配置、可选启动 Pingora 代理、注册路由、SSE 进度流、健康检查
+- 代理运行器（agent_runner）：独立运行 AI 代理工作流，支持本地任务通道、Pingora 代理
+- Pingora 代理：高性能反向代理，路径前缀 /proxy/{port}/{path} 转发到指定后端
+- Docker 管理：自动检测宿主机路径、容器清理、镜像多配置与资源限制
+
+**章节来源**
+- file://crates/rcoder/src/config.rs#L1-L120
+- file://crates/agent_runner/src/config.rs#L1-L120
+- file://crates/pingora-proxy/src/config.rs#L1-L60
+- file://crates/rcoder/src/main.rs#L1-L120
+
+## 架构总览
+RCoder 采用双服务架构：
+- Axum 主服务：提供业务 API、SSE 进度流、代理状态文档路由
+- Pingora 代理：独立监听端口，按路径前缀转发到任意后端端口
+
+```mermaid
+graph TB
+Client["客户端"] --> Axum["Axum 主服务"]
+Client --> Proxy["Pingora 代理"]
+Axum --> Routes["API 路由"]
+Axum --> SSE["SSE 进度流"]
+Proxy --> Backend["后端服务: 127.0.0.1:{port}"]
+```
+
+**图表来源**
+- [README.md](file://README.md#L16-L31)
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L160-L210)
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
+
+**章节来源**
+- file://README.md#L16-L31
+
+## 详细组件分析
+
+### 环境要求与安装
+- 环境要求：Rust 1.75+（2024 Edition），可选 Claude Code CLI、OpenAI Codex
+- 安装步骤：克隆仓库、构建工作区、运行主服务、可选启用 Pingora 代理
+- 命令行参数：端口、项目目录、启用代理、代理端口、默认后端端口
+
+```mermaid
+flowchart TD
+Start(["开始"]) --> Clone["克隆仓库"]
+Clone --> Build["构建工作区"]
+Build --> RunMain["运行主服务"]
+RunMain --> EnableProxy{"是否启用代理?"}
+EnableProxy --> |是| RunProxy["启动 Pingora 代理"]
+EnableProxy --> |否| Done(["完成"])
+RunProxy --> Done
+```
+
+**图表来源**
+- [README.md](file://README.md#L44-L105)
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L210-L272)
+
+**章节来源**
+- file://README.md#L44-L105
+
+### 配置系统与优先级
+- 配置优先级：命令行参数 > 环境变量 > 配置文件 > 默认配置
+- 配置文件：首次启动自动生成默认配置文件；支持默认代理类型、项目目录、主服务端口、Pingora 代理配置、Docker 多镜像配置
+- 环境变量：RCODER_PORT、DATABASE_URL、CLAUDE_CODE_PATH、RUST_LOG 等
+
+```mermaid
+flowchart TD
+A["默认配置"] --> B["读取配置文件"]
+B --> C{"文件存在?"}
+C --> |是| D["加载配置文件"]
+C --> |否| E["创建默认配置文件"]
+D --> F["应用环境变量覆盖"]
+E --> F
+F --> G["应用命令行参数覆盖"]
+G --> H["最终配置生效"]
+```
+
+**图表来源**
+- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
+- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L110-L192)
+- [config.yml](file://config.yml#L1-L60)
+
+**章节来源**
+- file://crates/rcoder/src/config.rs#L253-L332
+- file://crates/agent_runner/src/config.rs#L110-L192
+- file://README.md#L384-L450
+
+### 命令行参数与运行方式
+- rcoder 主服务常用参数：
+  - --port/-p：设置主服务端口
+  - --projects-dir/-d：设置项目工作目录
+  - --enable-proxy：启用 Pingora 反向代理
+  - --proxy-port：设置代理监听端口
+  - --default-backend-port：未指定端口时的默认后端端口
+- agent_runner 服务参数与 rcoder 类似，支持独立运行
+
+```mermaid
+sequenceDiagram
+participant U as "用户"
+participant CLI as "命令行参数"
+participant CFG as "配置加载"
+participant MAIN as "主服务启动"
+participant AXUM as "Axum 服务器"
+participant PING as "Pingora 代理"
+U->>CLI : 传入参数
+CLI->>CFG : 解析并合并配置
+CFG->>MAIN : 返回最终配置
+MAIN->>AXUM : 绑定端口并启动
+MAIN->>PING : 可选启动代理
+AXUM-->>U : 提供 API 文档与路由
+PING-->>U : 提供 /proxy/{port}/{path} 代理
+```
+
+**图表来源**
+- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L11-L36)
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L210-L272)
+- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L11-L36)
+- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L80-L178)
+
+**章节来源**
+- file://README.md#L88-L105
+- file://crates/rcoder/src/config.rs#L11-L36
+- file://crates/agent_runner/src/config.rs#L11-L36
+
+### API 与代理使用
+- 核心端点：
+  - GET /health：健康检查
+  - POST /chat：发送聊天消息给 AI 代理
+  - GET /agent/progress/{session_id}：SSE 实时进度流
+  - POST /agent/session/cancel：取消会话任务
+  - POST /agent/stop：停止当前 Agent
+  - GET /agent/status/{project_id}：查询 Agent 状态
+  - GET /api/docs：Swagger UI API 文档
+- Pingora 代理：
+  - 路由规则：/proxy/{port}/{path}
+  - 状态查询：/proxy/status、/proxy/config、/proxy/stats
+  - 真实代理请求需直接发送到 Pingora 监听端口
+
+```mermaid
+sequenceDiagram
+participant C as "客户端"
+participant AX as "Axum 主服务"
+participant PR as "Pingora 代理"
+participant BE as "后端服务"
+C->>PR : GET /proxy/{port}/{path}
+PR->>BE : 转发到 127.0.0.1 : {port}
+BE-->>PR : 响应
+PR-->>C : 代理响应
+note over AX,PR : 状态查询接口仅用于文档与状态，真实代理请求请直接到 Pingora
+```
+
+**图表来源**
+- [README.md](file://README.md#L209-L242)
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
+
+**章节来源**
+- file://README.md#L209-L242
+- file://crates/rcoder/src/router.rs#L52-L84
+
+### 聊天与容器化工作流
+- /chat 接口：将请求转发到容器内的 agent_runner 服务，由后者处理会话、项目隔离与 AI 代理
+- 容器管理：根据 project_id 动态创建或复用容器，支持 ServiceType::RCoder
+- SSE 进度流：统一通过 /agent/progress/{session_id} 推送执行进度
+
+```mermaid
+sequenceDiagram
+participant U as "用户"
+participant RC as "rcoder 主服务"
+participant CM as "容器管理"
+participant AR as "agent_runner 容器"
+participant SSE as "SSE 进度流"
+U->>RC : POST /chat
+RC->>CM : 获取/创建容器
+CM-->>RC : 返回容器信息
+RC->>AR : 转发原始请求
+AR-->>RC : 返回处理结果
+RC-->>U : 返回最终响应
+RC->>SSE : 建立 /agent/progress/{session_id} 连接
+AR-->>SSE : 推送进度事件
+```
+
+**图表来源**
+- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L108-L170)
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
+
+**章节来源**
+- file://crates/rcoder/src/handler/chat_handler.rs#L108-L170
+- file://crates/rcoder/src/router.rs#L52-L84
+
+### Docker 与部署
+- Dockerfile：多阶段构建，包含调试工具与健康检查
+- docker-compose：挂载 Docker socket、项目工作目录、日志目录与启动脚本，设置环境变量与健康检查
+- 建议：生产环境使用 systemd 管理服务，或结合 Nginx 反向代理
+
+```mermaid
+flowchart TD
+A["构建镜像"] --> B["运行容器"]
+B --> C["挂载 Docker socket"]
+B --> D["挂载项目工作目录"]
+B --> E["挂载日志目录"]
+B --> F["设置环境变量"]
+F --> G["RCODER_PORT/RUST_LOG 等"]
+B --> H["健康检查 /health"]
+```
+
+**图表来源**
+- [docker/Dockerfile](file://docker/Dockerfile#L1-L120)
+- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+
+**章节来源**
+- file://docker/Dockerfile#L1-L120
+- file://docker/docker-compose.yml#L1-L37
+- file://README.md#L490-L584
+
+## 依赖关系分析
+- 工作区依赖：clap、tokio、axum、tower、sqlx、serde、tracing、opentelemetry、utoipa、pingora、bollard 等
+- 代理相关：agent-client-protocol、codex-acp（可选）、codex-core、codex-common、codex-arg0
+- 代理运行器：与 rcoder 共享配置与类型，独立运行
+
+```mermaid
+graph TB
+W["Workspace 依赖"] --> C1["clap"]
+W --> T1["tokio"]
+W --> A1["axum"]
+W --> O1["opentelemetry"]
+W --> U1["utoipa"]
+W --> P1["pingora"]
+W --> B1["bollard"]
+subgraph "代理依赖"
+AC["agent-client-protocol"]
+CA["codex-acp"]
+CC["codex-core"]
+CO["codex-common"]
+CG["codex-arg0"]
+end
+A1 --> AC
+CA --> CC
+CA --> CO
+CA --> CG
+```
+
+**图表来源**
+- [Cargo.toml](file://Cargo.toml#L35-L205)
+
+**章节来源**
+- file://Cargo.toml#L35-L205
+
+## 性能与可用性
+- 异步运行时：Tokio 全功能特性，支持高并发
+- 观测性：Tracing + OpenTelemetry，日志按天滚动，支持 trace_id 传播
+- 代理性能：Pingora 基于 Rust 异步 I/O 的高性能代理，支持健康检查与动态后端发现
+- 容器管理：自动清理遗留容器、资源限制与 TTL 控制，提升稳定性
+
+[本节为通用性能讨论，无需特定文件引用]
+
+## 故障排查指南
+- 端口冲突：使用 --port 指定不同端口
+- 代理连接失败：检查 API 密钥与网络连通性
+- 配置文件错误：检查 YAML 格式与字段名称
+- Docker socket 权限：确保挂载 /var/run/docker.sock 并具备访问权限
+- Pingora 代理请求：确认直接请求代理监听端口，避免误发到主服务端口
+
+**章节来源**
+- file://README.md#L611-L652
+- file://crates/rcoder/src/main.rs#L322-L351
+
+## 结论
+RCoder 提供了从本地开发到生产部署的一体化方案：清晰的命令行参数与配置系统、高性能的 Axum + Pingora 架构、完善的可观测性与容器化能力。按照本文的快速开始步骤，您可以迅速搭建并使用 RCoder 平台。
+
+[本节为总结性内容，无需特定文件引用]
+
+## 附录
+
+### 常用命令与示例
+- 构建与运行主服务：cargo build --workspace；cargo run --bin rcoder
+- 启用代理：cargo run --bin rcoder -- --enable-proxy --proxy-port 8080
+- 健康检查：curl -X GET http://localhost:3000/health
+- 聊天接口：POST /chat，SSE 进度流：GET /agent/progress/{session_id}
+
+**章节来源**
+- file://README.md#L44-L105
+- file://README.md#L229-L268
+
+### AI 代理配置要点
+- Claude Code：安装 CLI 并设置 API Key 与模型
+- OpenAI Codex：参考官方文档进行配置
+
+**章节来源**
+- file://README.md#L107-L131
+- file://install.md#L1-L9