添加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/README.md
+++ b/qiming-rcoder/README.md
@@ -0,0 +1,495 @@
+# RCoder - AI驱动的开发平台
+
+> [English](README_EN.md)
+
+RCoder 是一个基于 Rust 构建的现代化 AI 驱动开发平台，通过 **SACP (Symposium ACP)** 协议实现与多种 AI 代理的统一交互。项目采用**微服务架构**，支持 **Docker 容器化部署**和 **gRPC 高性能通信**。
+
+## ✨ 核心特性
+
+- 🔁 **反向代理**：集成 Cloudflare Pingora，高性能端口路由 `/proxy/{port}/{path}`
+- 🌐 **HTTP API**：基于 Axum 的现代化 REST API 与统一 SSE 进度流
+- 🤖 **多代理支持**：统一接入 Claude Code、Codex 等 AI 代理
+- 🐳 **容器化架构**：每个项目对应独立的 Docker 容器，实现隔离和资源管理
+- ⚡ **gRPC 通信**：基于 Tonic 的高性能内部通信，支持 Server Streaming
+- 🔧 **配置系统**：命令行 > 环境变量 > 配置文件，多层配置优先级
+- 📜 **API 文档**：自动化 API 文档（utoipa + Swagger UI）
+- 📊 **可观测性**：Tracing + OpenTelemetry 完整链路追踪 + Pyroscope 性能分析
+- 🖥️ **Computer Agent**：容器化 AI 代理环境，集成 VNC 远程桌面、音频流和 IME 输入
+
+## 🏠 架构概览
+
+### 整体架构
+
+```
+外部客户端 (HTTP/SSE)
+    ↓
+RCoder (HTTP API Server + Docker 管理 + gRPC 客户端)
+    ↓ gRPC (Chat, CancelSession, SubscribeProgress)
+Agent Runner (gRPC Server in Docker)
+    ↓ Server Streaming (实时进度事件)
+RCoder (转换为 SSE)
+    ↓
+外部客户端 (SSE)
+```
+
+### 核心组件
+
+- **RCoder 主服务**：Axum HTTP 服务 + 容器管理 + gRPC 客户端
+- **Agent Runner**：独立的 AI 代理运行环境（Docker 容器内），提供 gRPC 服务
+- **Pingora 代理**：高性能反向代理服务，支持端口路由
+- **Docker Manager**：全局容器生命周期管理
+
+### 🛠️ 技术栈
+
+| 组件类型 | 技术选型 | 说明 |
+|----------|---------|------|
+| **编程语言** | Rust 2024 Edition | 现代化系统编程语言 |
+| **HTTP 框架** | Axum + Tower | 高性能异步 Web 框架 |
+| **RPC 框架** | Tonic (gRPC) | 高性能 RPC 通信 |
+| **AI 协议** | SACP + MCP | 支持多种 AI 代理协议 |
+| **容器化** | Docker + Bollard | 容器管理和编排 |
+| **数据库** | DuckDB + SQLx | 嵌入式分析数据库 |
+| **日志系统** | Tracing + OpenTelemetry | 结构化日志和分布式追踪 |
+| **性能分析** | Pyroscope | 持续性能剖析 |
+| **命令行** | clap | 现代化命令行参数解析 |
+
+## 🚀 快速开始
+
+### 📝 环境要求
+
+- Rust: 1.75+（2024 Edition）
+- Docker（用于容器化部署）
+- 可选：Claude Code CLI（用于 Claude 代理）
+
+### 🛠️ 安装与运行
+
+#### 本地开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/your-org/rcoder.git
+cd rcoder
+
+# 本地编译
+cargo build --workspace
+
+# 运行主服务
+cargo run --bin rcoder
+
+# 指定端口和项目目录
+cargo run --bin rcoder -- --port 8087 --projects-dir ./my-projects
+```
+
+#### Docker 开发模式（推荐）
+
+```bash
+# 构建镜像并启动容器
+make dev-build    # 构建 Docker 镜像
+make dev-up       # 启动开发容器
+
+# 代码修改后重启
+make dev-restart  # 重新构建并重启
+
+# 查看日志
+make dev-logs
+
+# 停止容器
+make dev-down
+```
+
+#### 启用反向代理
+
+```bash
+# 启用 Pingora 反向代理
+cargo run --bin rcoder -- --enable-proxy --proxy-port 8080
+
+# 指定默认后端端口
+cargo run --bin rcoder -- --enable-proxy --proxy-port 8080 --backend-port 3000
+```
+
+### 💻 命令行参数
+
+| 参数 | 短参数 | 说明 | 示例 |
+|------|--------|------|------|
+| `--port` | `-p` | 设置主服务端口 | `--port 8087` |
+| `--projects-dir` | `-d` | 设置项目工作目录 | `--projects-dir ./projects` |
+| `--enable-proxy` | 无 | 启用 Pingora 反向代理 | `--enable-proxy` |
+| `--proxy-port` | 无 | 设置 Pingora 监听端口 | `--proxy-port 8080` |
+| `--backend-port` | 无 | 默认后端端口 | `--backend-port 3000` |
+
+```bash
+# 查看所有参数
+cargo run --bin rcoder -- --help
+```
+
+## 📚 API 文档
+
+### 🔁 Pingora 反向代理
+
+Pingora 是项目内置的高性能反向代理。
+
+```bash
+# 启用代理
+cargo run --bin rcoder -- --enable-proxy --proxy-port 8080
+
+# 代理请求示例（转发到 5173 端口）
+curl "http://127.0.0.1:8080/proxy/5173/page/123/"
+```
+
+### 🏥 核心端点
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/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 文档 |
+
+### gRPC 服务 (Agent Runner)
+
+| 方法 | 类型 | 说明 |
+|------|------|------|
+| `Chat` | Unary | 发送聊天请求 |
+| `SubscribeProgress` | Server Streaming | 订阅进度事件流 |
+| `CancelSession` | Unary | 取消会话任务 |
+| `GetStatus` | Unary | 查询 Agent 状态 |
+| `StopAgent` | Unary | 停止 Agent |
+| `GetContainerStatus` | Unary | 查询容器状态 |
+| `GetVncStatus` | Unary | 查询 VNC 服务状态 |
+
+### 🖥️ Computer Agent 端点
+
+Computer Agent 提供容器化的 AI 代理环境，支持 VNC 远程桌面、音频流和 IME 输入。每个用户对应独立的 Docker 容器，多个项目可共享同一容器。
+
+#### 核心接口
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/computer/chat` | POST | 发送聊天消息到 Computer Agent |
+| `/computer/progress/{session_id}` | GET (SSE) | 获取实时进度流 |
+| `/computer/agent/stop` | POST | 停止指定项目的 Agent（不销毁容器） |
+| `/computer/agent/status` | POST | 查询 Agent 状态（alive/idle/busy） |
+| `/computer/agent/session/cancel` | POST | 取消正在执行的会话 |
+
+#### 桌面与媒体代理（通过 Pingora）
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/computer/desktop/{user_id}/{project_id}` | GET | 获取 VNC 桌面访问地址 |
+| `/computer/vnc/{user_id}/{project_id}/{*path}` | GET | VNC/noVNC 代理（端口 6080） |
+| `/computer/audio/{user_id}/{project_id}/{*path}` | GET | 音频流代理（端口 6089/6090） |
+| `/computer/ime/{user_id}/{project_id}/{*path}` | GET | IME 输入法代理（端口 6091） |
+
+#### Pod/容器管理
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/computer/pod/count` | GET | 容器数量统计（按服务类型分组） |
+| `/computer/pod/list` | GET | 列出所有容器详情（支持分页 `?limit=100`） |
+| `/computer/pod/ensure` | POST | 确保容器存在（幂等，不启动 Agent） |
+| `/computer/pod/keepalive` | POST | 刷新容器活跃时间（防止自动清理） |
+| `/computer/pod/restart` | POST | 重启容器（销毁并重建） |
+| `/computer/pod/status` | GET | 查询容器状态（`?user_id=xxx`） |
+| `/computer/pod/vnc-status` | GET | 查询 VNC 服务就绪状态 |
+
+#### Computer Chat 请求示例
+
+```bash
+curl -X POST http://localhost:8087/computer/chat \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": "user-123",
+    "project_id": "my-project",
+    "prompt": "帮我创建一个 Python Web 应用"
+  }'
+```
+
+### 🚑 健康检查
+
+```bash
+curl -X GET http://localhost:8087/health
+```
+
+响应：
+```json
+{
+  "status": "ok",
+  "timestamp": "2024-01-01T00:00:00Z"
+}
+```
+
+### 💬 聊天接口
+
+```bash
+curl -X POST http://localhost:8087/chat \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "你好，请帮我创建一个 Rust Web API 项目",
+    "project_id": "my-project",
+    "session_id": "optional-session-id"
+  }'
+```
+
+### 📊 实时进度流
+
+```bash
+curl -X GET http://localhost:8087/agent/progress/your-session-id \
+  -H "Accept: text/event-stream"
+```
+
+## 📁 项目结构
+
+```
+crates/
+├── agent_abstraction/     # Agent 抽象层
+├── agent_config/          # Agent 配置管理
+├── agent_runner/          # Agent 运行时（gRPC 服务端）
+│   ├── src/
+│   │   ├── grpc/          # gRPC 服务实现
+│   │   ├── proxy_agent/   # ACP 代理实现
+│   │   └── service/       # 核心服务
+│   └── Cargo.toml
+├── docker_manager/        # Docker 容器管理
+├── duckdb_manager/        # DuckDB 数据库管理
+├── rcoder/               # 主应用
+│   ├── src/
+│   │   ├── grpc/         # gRPC 客户端
+│   │   ├── handler/      # HTTP 处理器
+│   │   ├── service/      # 业务服务
+│   │   └── cleanup_task/ # 清理任务
+│   └── Cargo.toml
+├── rcoder-proxy/         # Pingora 代理封装
+├── rcoder-telemetry/     # 遥测和追踪
+└── shared_types/         # 共享类型和 Proto 定义
+    └── proto/
+        └── agent.proto   # gRPC 协议定义
+```
+
+## 配置
+
+### 配置优先级
+
+1. **命令行参数** - 最高优先级
+2. **环境变量** - 中等优先级
+3. **配置文件** - 较低优先级
+4. **默认配置** - 最低优先级
+
+### 配置文件 (config.yml)
+
+```yaml
+# 默认 Agent ID
+default_agent_id: "claude-code-acp-ts"
+
+# 项目工作目录
+projects_dir: "./project_workspace"
+
+# 主服务端口
+port: 8087
+
+# Docker 配置
+docker_config:
+  network_mode: "bridge"
+  network_base_name: "agent-network"
+  work_dir: "/app"
+  auto_cleanup: true
+  container_ttl_seconds: 3600
+  api_timeout_seconds: 10
+  cache_status_ttl_seconds: 10
+
+# 容器清理配置
+cleanup_config:
+  enabled: true
+  idle_timeout_seconds: 600
+  cleanup_interval_seconds: 300
+  container_protection_seconds: 300
+
+# API Key 鉴权配置
+api_key_auth:
+  enabled: false
+  api_key: "sk-xxx"
+
+# 反向代理配置
+proxy_config:
+  listen_port: 8088
+  default_backend_port: 8086
+  backend_host: "127.0.0.1"
+```
+
+### 环境变量
+
+| 变量名 | 说明 | 默认值 |
+|--------|------|--------|
+| `RCODER_PORT` | 服务端口 | 8087 |
+| `RCODER_PROJECTS_DIR` | 项目目录 | ./project_workspace |
+| `RCODER_NETWORK_MODE` | Docker 网络模式 | bridge |
+| `RCODER_NETWORK_BASE_NAME` | 网络基础名称 | agent-network |
+| `RCODER_API_TIMEOUT_SECONDS` | Docker API 超时 | 10 |
+| `RCODER_API_KEY_ENABLED` | 启用 API Key 鉴权 | false |
+| `RCODER_API_KEY` | API Key 密钥 | - |
+| `RUST_LOG` | 日志级别 | info |
+
+### 使用示例
+
+```bash
+# 使用环境变量
+RCODER_PORT=8080 RUST_LOG=debug cargo run --bin rcoder
+
+# 命令行参数优先级最高
+RCODER_PORT=8080 cargo run --bin rcoder -- --port 9000
+```
+
+## 🔧 开发指南
+
+### 运行测试
+
+```bash
+# 运行所有测试
+cargo test --workspace
+
+# 运行单元测试
+make test-unit
+
+# 运行集成测试
+make test-integration
+```
+
+### 代码质量
+
+```bash
+# 代码格式化
+cargo fmt
+
+# 代码检查
+cargo clippy
+
+# 全面检查
+cargo clippy -- -D warnings
+```
+
+### 本地开发
+
+```bash
+# 启动开发服务器
+RUST_LOG=debug cargo run --bin rcoder -- --port 8087
+
+# 监视文件变化
+cargo install cargo-watch
+cargo watch -x "run --bin rcoder"
+```
+
+## 🚀 部署指南
+
+### Docker 部署
+
+```bash
+# 构建镜像
+make docker-build
+
+# 或分别构建
+make docker-build-master       # 主服务镜像
+make docker-build-agent-runner # Agent Runner 镜像
+
+# 生产镜像（无调试工具）
+make docker-build-agent-production
+```
+
+### Docker Compose
+
+```bash
+# 启动服务
+make dev-up
+
+# 查看状态
+docker-compose -f docker/docker-compose.yml ps
+
+# 停止服务
+make dev-down
+```
+
+### Pyroscope 性能分析
+
+```bash
+# 启动 Pyroscope Server
+make pyroscope-up
+
+# 访问 Web UI
+open http://localhost:4040
+
+# 停止服务
+make pyroscope-down
+```
+
+## 🐛 问题排查
+
+### 常见问题
+
+- **端口被占用**：使用 `--port` 参数指定其他端口
+- **容器启动失败**：检查 Docker 服务状态和网络配置
+- **gRPC 连接失败**：确认容器网络和端口配置
+- **API Key 错误**：检查 `api_key_auth` 配置
+
+### 调试模式
+
+```bash
+# 启用详细日志
+RUST_LOG=debug cargo run --bin rcoder
+
+# 查看容器日志
+make dev-logs
+
+# 进入容器调试
+docker exec -it <container_id> /bin/bash
+```
+
+## 📈 更新日志
+
+### v0.1.0 (当前版本)
+
+#### 新增功能
+- ✅ 基于 SACP 协议的 AI 代理统一管理
+- ✅ gRPC 高性能通信架构
+- ✅ Docker 容器化部署（项目级隔离）
+- ✅ VNC/noVNC 远程桌面支持
+- ✅ API Key 鉴权中间件
+- ✅ 容器自动清理机制
+- ✅ 多镜像配置支持
+- ✅ Pyroscope 性能分析集成
+
+#### 技术特性
+- ✅ Rust 2024 Edition
+- ✅ Tonic gRPC (v0.14.2)
+- ✅ SACP 协议 (v10.1.0)
+- ✅ MCP 协议支持 (rmcp v0.12.0)
+- ✅ DuckDB 数据库
+- ✅ OpenTelemetry 追踪
+- ✅ eBPF 调试工具支持
+
+## 🔗 相关链接
+
+- **项目仓库**: [GitHub](https://github.com/your-org/rcoder)
+- **问题追踪**: [Issues](https://github.com/your-org/rcoder/issues)
+- **SACP 协议**: [Symposium ACP](https://crates.io/crates/sacp)
+- **MCP 协议**: [rmcp](https://crates.io/crates/rmcp)
+
+## 📝 许可证
+
+本项目采用 MIT 或 Apache-2.0 双许可证。详见 [LICENSE](LICENSE) 文件。
+
+## 🤝 贡献
+
+欢迎贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何参与开发。
+
+### 贡献指南
+
+1. Fork 项目
+2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
+3. 提交更改 (`git commit -m 'Add amazing feature'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 开启 Pull Request
+
+---
+
+💫 **由 RCoder 团队精心打造，致力于推进 AI 驱动的现代化开发体验。**