RCoder - AI驱动的开发平台

July 3, 2026 · View on GitHub

English

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 代理）

🛠️ 安装与运行

本地开发

# 克隆仓库
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 开发模式（推荐）

# 构建镜像并启动容器
make dev-build    # 构建 Docker 镜像
make dev-up       # 启动开发容器

# 代码修改后重启
make dev-restart  # 重新构建并重启

# 查看日志
make dev-logs

# 停止容器
make dev-down

启用反向代理

# 启用 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`

# 查看所有参数
cargo run --bin rcoder -- --help

📚 API 文档

🔁 Pingora 反向代理

Pingora 是项目内置的高性能反向代理。

# 启用代理
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 请求示例

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 应用"
  }'

🚑 健康检查

curl -X GET http://localhost:8087/health

响应：

{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00Z"
}

💬 聊天接口

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"
  }'

📊 实时进度流

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 协议定义

配置

配置优先级

命令行参数 - 最高优先级
环境变量 - 中等优先级
配置文件 - 较低优先级
默认配置 - 最低优先级

配置文件 (config.yml)

# 默认 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

使用示例

# 使用环境变量
RCODER_PORT=8080 RUST_LOG=debug cargo run --bin rcoder

# 命令行参数优先级最高
RCODER_PORT=8080 cargo run --bin rcoder -- --port 9000

🔧 开发指南

运行测试

# 运行所有测试
cargo test --workspace

# 运行单元测试
make test-unit

# 运行集成测试
make test-integration

代码质量

# 代码格式化
cargo fmt

# 代码检查
cargo clippy

# 全面检查
cargo clippy -- -D warnings

本地开发

# 启动开发服务器
RUST_LOG=debug cargo run --bin rcoder -- --port 8087

# 监视文件变化
cargo install cargo-watch
cargo watch -x "run --bin rcoder"

🚀 部署指南

Docker 部署

# 构建镜像
make docker-build

# 或分别构建
make docker-build-master       # 主服务镜像
make docker-build-agent-runner # Agent Runner 镜像

# 生产镜像（无调试工具）
make docker-build-agent-production

Docker Compose

# 启动服务
make dev-up

# 查看状态
docker-compose -f docker/docker-compose.yml ps

# 停止服务
make dev-down

Pyroscope 性能分析

# 启动 Pyroscope Server
make pyroscope-up

# 访问 Web UI
open http://localhost:4040

# 停止服务
make pyroscope-down

🐛 问题排查

常见问题

端口被占用：使用 --port 参数指定其他端口
容器启动失败：检查 Docker 服务状态和网络配置
gRPC 连接失败：确认容器网络和端口配置
API Key 错误：检查 api_key_auth 配置

调试模式

# 启用详细日志
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
问题追踪: Issues
SACP 协议: Symposium ACP
MCP 协议: rmcp

📝 许可证

本项目采用 Apache-2.0 许可证。详见 LICENSE 文件。

🤝 贡献

欢迎贡献！请阅读 CONTRIBUTING.md 了解如何参与开发。

贡献指南

Fork 项目
创建特性分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
开启 Pull Request

💫 由 RCoder 团队精心打造，致力于推进 AI 驱动的现代化开发体验。