添加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/API端点参考/API端点参考.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/API端点参考.md
@@ -0,0 +1,529 @@
+# API端点参考
+
+<cite>
+**本文档引用的文件**   
+- [router.rs](file://crates/rcoder/src/router.rs)
+- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
+- [health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs)
+- [agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs)
+- [agent_cancel_handler.rs](file://crates/rcoder/src/handler/agent_cancel_handler.rs)
+- [agent_stop_handler.rs](file://crates/rcoder/src/handler/agent_stop_handler.rs)
+- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs)
+- [proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs)
+- [http_result.rs](file://crates/shared_types/src/model/http_result.rs)
+- [app_error.rs](file://crates/shared_types/src/model/app_error.rs)
+- [http_test.rest](file://http_test.rest)
+- [README.md](file://README.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [API概览](#api概览)
+3. [核心API端点](#核心api端点)
+4. [Pingora反向代理API](#pingora反向代理api)
+5. [请求/响应格式](#请求响应格式)
+6. [认证方法](#认证方法)
+7. [错误处理策略](#错误处理策略)
+8. [安全考虑](#安全考虑)
+9. [速率限制](#速率限制)
+10. [版本信息](#版本信息)
+11. [客户端实现指南](#客户端实现指南)
+12. [性能优化技巧](#性能优化技巧)
+13. [调试工具与监控方法](#调试工具与监控方法)
+
+## 简介
+RCoder是一个基于Rust构建的现代化AI驱动开发平台，通过ACP（Agent Client Protocol）协议实现与多种AI代理的统一交互。本API文档详细描述了RCoder提供的RESTful API接口，包括HTTP方法、URL模式、请求/响应模式、认证方法等关键信息。平台提供简洁的HTTP API接口，让开发者能够轻松集成和管理AI辅助开发功能。
+
+**API端点**
+- `/health`：健康检查
+- `/chat`：发送聊天消息给AI代理
+- `/agent/progress/{session_id}`：获取统一实时进度流
+- `/agent/session/cancel`：取消正在执行的任务
+- `/agent/stop`：停止当前Agent
+- `/agent/status/{project_id}`：查询Agent状态
+- `/api/docs`：Swagger UI API文档
+- `/proxy/status`、`/proxy/config`、`/proxy/stats`：Pingora代理状态查询接口
+
+## API概览
+RCoder API基于Axum框架构建，提供现代化的REST API与统一的SSE（Server-Sent Events）进度流。API设计遵循RESTful原则，使用标准的HTTP方法和状态码。所有API响应都遵循统一的`HttpResult<T>`格式，包含`code`、`message`、`data`和`success`字段。
+
+```mermaid
+graph TB
+A[客户端] --> B[Axum HTTP服务器]
+A --> C[Pingora代理]
+B --> D[API路由]
+B --> E[代理工作器 (LocalSet)]
+C --> F[后端: 127.0.0.1:{端口}]
+```
+
+- Axum主服务负责业务API、会话管理与SSE进度流
+- Pingora独立监听代理端口，按路径前缀`/proxy/{port}/{path}`转发到指定后端
+- 两者并行运行，互不阻塞；Axum中的`/proxy/...`路由仅作为文档与重定向到Pingora
+
+## 核心API端点
+
+### 健康检查
+健康检查端点用于验证服务的运行状态。
+
+**端点信息**
+- **URL**: `/health`
+- **方法**: `GET`
+- **标签**: `system`
+- **描述**: 检查服务的健康状态
+
+**成功响应示例**
+```json
+{
+  "status": "healthy",
+  "timestamp": "2024-01-01T00:00:00Z",
+  "service": "rcoder-ai-service"
+}
+```
+
+**响应状态码**
+- `200`: 服务健康
+
+**Section sources**
+- [health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
+
+### 聊天接口
+聊天接口用于向AI代理发送消息并启动会话。
+
+**端点信息**
+- **URL**: `/chat`
+- **方法**: `POST`
+- **标签**: `chat`
+- **请求体类型**: `application/json`
+
+**请求参数**
+| 参数 | 类型 | 必需 | 描述 | 示例 |
+|------|------|------|------|------|
+| `prompt` | string | 是 | 用户输入的提示 | "帮我写一个Rust的Hello World程序" |
+| `project_id` | string | 否 | 可选的项目ID | "test_project" |
+| `session_id` | string | 否 | 可选的会话ID，不提供则创建新会话 | "session456" |
+| `attachments` | array | 否 | 可选的附件列表 | [] |
+| `data_source_attachments` | array | 否 | 数据源附件列表 | [] |
+| `model_provider` | object | 否 | 模型配置 | 见示例 |
+| `request_id` | string | 否 | 可选的请求ID，用于追踪 | "req_123456789" |
+
+**请求体示例**
+```json
+{
+  "prompt": "帮我写一个Rust的Web API项目",
+  "project_id": "my-project",
+  "session_id": "session123",
+  "attachments": [],
+  "data_source_attachments": [],
+  "model_provider": {
+    "id": "openai_gpt4",
+    "name": "openai",
+    "base_url": "https://api.openai.com/v1",
+    "api_key": "sk-...",
+    "requires_openai_auth": true,
+    "default_model": "gpt-4",
+    "api_protocol": "openai"
+  },
+  "request_id": "req_123456789"
+}
+```
+
+**成功响应示例**
+```json
+{
+  "success": true,
+  "data": {
+    "project_id": "test_project",
+    "session_id": "session456",
+    "error": null,
+    "request_id": "req_123456789"
+  },
+  "error": null
+}
+```
+
+**响应状态码**
+- `200`: 成功处理聊天请求
+- `500`: 服务器内部错误或容器服务异常
+
+**Section sources**
+- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L1-L431)
+
+### 实时进度流
+通过SSE（Server-Sent Events）协议获取AI代理执行进度的实时推送。
+
+**端点信息**
+- **URL**: `/agent/progress/{session_id}`
+- **方法**: `GET`
+- **标签**: `agent`
+- **内容类型**: `text/event-stream`
+
+**路径参数**
+| 参数 | 类型 | 必需 | 描述 | 示例 |
+|------|------|------|------|------|
+| `session_id` | string | 是 | 会话ID，用于标识特定的会话连接 | "session456" |
+
+**SSE事件格式**
+```
+data: {"type": "progress", "content": "正在处理您的请求..."}
+data: {"type": "result", "content": "项目创建完成"}
+```
+
+**响应头**
+- `Cache-Control`: no-cache
+- `Connection`: keep-alive
+
+**响应状态码**
+- `200`: 成功建立SSE连接，开始接收实时消息
+- `404`: 未找到对应的容器
+- `500`: 建立SSE连接失败
+
+**Section sources**
+- [agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L1-L378)
+
+### 任务取消
+取消正在执行的AI代理任务。
+
+**端点信息**
+- **URL**: `/agent/session/cancel`
+- **方法**: `POST`
+- **标签**: `agent`
+
+**查询参数**
+| 参数 | 类型 | 必需 | 描述 | 示例 |
+|------|------|------|------|------|
+| `project_id` | string | 是 | 项目ID，用于标识特定的项目 | "test_project" |
+| `session_id` | string | 否 | 会话ID，用于标识要取消的会话（可选） | "session456" |
+
+**成功响应示例**
+```json
+{
+  "success": true,
+  "data": {
+    "success": true,
+    "session_id": "session456"
+  },
+  "error": null
+}
+```
+
+**响应状态码**
+- `200`: 成功转发取消请求到容器
+- `400`: 请求参数错误
+- `404`: 未找到对应的项目或会话
+- `500`: 转发取消请求失败
+
+**Section sources**
+- [agent_cancel_handler.rs](file://crates/rcoder/src/handler/agent_cancel_handler.rs#L1-L262)
+
+### 停止Agent
+停止指定项目的Agent服务。
+
+**端点信息**
+- **URL**: `/agent/stop`
+- **方法**: `POST`
+- **标签**: `agent`
+
+**查询参数**
+| 参数 | 类型 | 必需 | 描述 | 示例 |
+|------|------|------|------|------|
+| `project_id` | string | 是 | 项目ID | "test_project" |
+
+**成功响应示例**
+```json
+{
+  "success": true,
+  "data": {
+    "success": true,
+    "project_id": "test_project",
+    "session_id": null,
+    "message": "容器已成功销毁"
+  },
+  "error": null
+}
+```
+
+**响应状态码**
+- `200`: 成功销毁容器
+- `400`: 请求参数错误
+- `500`: 销毁容器失败
+
+**Section sources**
+- [agent_stop_handler.rs](file://crates/rcoder/src/handler/agent_stop_handler.rs#L1-L241)
+
+## Pingora反向代理API
+Pingora是项目内置的高性能反向代理，所有真实的代理请求必须发送到Pingora的监听端口，并使用路径前缀形式`/proxy/{port}/{path}`来指定目标后端端口与路径。
+
+### 代理状态查询
+查询代理服务的状态。
+
+**端点信息**
+- **URL**: `/proxy/status`
+- **方法**: `GET`
+- **标签**: `proxy`
+
+**成功响应示例**
+```json
+{
+  "status": "running",
+  "listen_port": 8080,
+  "default_backend_port": 3000,
+  "default_backend_host": "127.0.0.1",
+  "backends": [
+    {
+      "port": 3000,
+      "host": "127.0.0.1",
+      "health_status": "healthy",
+      "last_check": "2025-01-12T10:30:00Z"
+    }
+  ],
+  "load_balancer": {
+    "algorithm": "round-robin",
+    "health_check_enabled": true,
+    "backend_count": 3
+  }
+}
+```
+
+### 代理统计信息
+查看代理的统计信息。
+
+**端点信息**
+- **URL**: `/proxy/stats`
+- **方法**: `GET`
+- **标签**: `proxy`
+
+**成功响应示例**
+```json
+{
+  "total_requests": 15420,
+  "successful_requests": 15200,
+  "failed_requests": 220,
+  "avg_response_time_ms": 35.5,
+  "active_connections": 12,
+  "port_stats": [
+    {
+      "port": 3000,
+      "requests": 8560,
+      "success_rate": 0.987,
+      "avg_response_time_ms": 28.3
+    }
+  ]
+}
+```
+
+### 代理配置查询
+查看代理的配置信息。
+
+**端点信息**
+- **URL**: `/proxy/config`
+- **方法**: `GET`
+- **标签**: `proxy`
+
+**成功响应示例**
+```json
+{
+  "listen_port": 8080,
+  "default_backend_port": 3000,
+  "default_backend_host": "127.0.0.1",
+  "load_balancing_algorithm": "round-robin",
+  "health_check": {
+    "enabled": true,
+    "interval_seconds": 5,
+    "timeout_seconds": 3,
+    "healthy_threshold": 2,
+    "unhealthy_threshold": 3
+  }
+}
+```
+
+**Section sources**
+- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L1-L195)
+- [proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs)
+
+## 请求/响应格式
+所有API响应都遵循统一的`HttpResult<T>`格式，确保客户端能够一致地处理响应。
+
+### 响应结构
+```json
+{
+  "code": "0000",
+  "message": "成功",
+  "data": {},
+  "tid": "trace-id",
+  "success": true
+}
+```
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| `code` | string | 响应代码，"0000"表示成功 |
+| `message` | string | 响应消息 |
+| `data` | object | 响应数据，成功时包含具体数据 |
+| `tid` | string | 跟踪ID，用于分布式追踪 |
+| `success` | boolean | 是否成功，根据code自动计算 |
+
+### 错误响应结构
+```json
+{
+  "code": "INTERNAL001",
+  "message": "Internal server error",
+  "data": null,
+  "tid": "trace-id",
+  "success": false
+}
+```
+
+**Section sources**
+- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L1-L103)
+
+## 认证方法
+RCoder API目前采用基于API密钥的认证方法。用户需要在请求头中包含`Authorization`字段。
+
+### 认证方式
+- **类型**: Bearer Token
+- **请求头**: `Authorization: Bearer <API_KEY>`
+- **环境变量**: `ANTHROPIC_API_KEY`用于Claude代理
+
+### 配置示例
+```bash
+export ANTHROPIC_API_KEY="your-api-key"
+export ANTHROPIC_MODEL="claude-3-sonnet-20240229"
+```
+
+## 错误处理策略
+RCoder API采用统一的错误处理策略，所有错误都通过`HttpResult<T>`格式返回。
+
+### 错误代码规范
+| 代码范围 | 描述 |
+|--------|------|
+| `0000` | 成功 |
+| `1xxx` | 客户端错误 |
+| `2xxx` | 服务器错误 |
+| `3xxx` | 认证错误 |
+| `4xxx` | 权限错误 |
+| `5xxx` | 内部错误 |
+
+### 错误处理示例
+```json
+{
+  "code": "INTERNAL001",
+  "message": "Internal server error",
+  "data": null,
+  "success": false
+}
+```
+
+**Section sources**
+- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
+
+## 安全考虑
+RCoder API在设计时充分考虑了安全性，采用了多种安全措施。
+
+### 安全特性
+- **项目隔离**: 每个对话在独立的项目工作空间中进行，确保安全性
+- **容器化**: AI代理在独立的Docker容器中运行，提供进程隔离
+- **输入验证**: 所有输入参数都经过严格验证
+- **日志记录**: 所有请求和响应都记录在结构化日志中
+- **追踪ID**: 每个请求都有唯一的追踪ID，便于审计和调试
+
+### 安全建议
+- 使用HTTPS保护API通信
+- 定期轮换API密钥
+- 限制API密钥的权限范围
+- 监控异常的API调用模式
+
+## 速率限制
+RCoder API实施了速率限制策略，以防止滥用和确保服务质量。
+
+### 速率限制规则
+- **默认限制**: 100次请求/分钟
+- **突发限制**: 200次请求/分钟（短时间）
+- **IP限制**: 每个IP地址的请求频率限制
+- **项目限制**: 每个项目ID的并发请求限制
+
+### 速率限制响应
+当超过速率限制时，API会返回`429 Too Many Requests`状态码。
+
+```json
+{
+  "code": "RATE_LIMIT_EXCEEDED",
+  "message": "请求频率超过限制",
+  "data": null,
+  "success": false
+}
+```
+
+## 版本信息
+RCoder API遵循语义化版本控制，确保向后兼容性。
+
+### 当前版本
+- **API版本**: 1.0.0
+- **协议版本**: ACP v0.4
+- **Rust版本**: 2024 Edition
+
+### 版本策略
+- 主版本号变更表示不兼容的API更改
+- 次版本号变更表示向后兼容的功能新增
+- 修订号变更表示向后兼容的问题修正
+
+## 客户端实现指南
+本节提供客户端实现的建议和最佳实践。
+
+### HTTP客户端配置
+- 使用连接池提高性能
+- 设置合理的超时时间
+- 启用压缩（gzip）减少传输数据量
+- 实现重试机制处理临时错误
+
+### SSE客户端实现
+```javascript
+const eventSource = new EventSource('/agent/progress/session123');
+eventSource.onmessage = function(event) {
+  console.log('收到消息:', event.data);
+};
+eventSource.onerror = function(event) {
+  console.error('SSE连接错误:', event);
+};
+```
+
+### 错误处理
+- 捕获并处理所有API错误
+- 实现指数退避重试策略
+- 记录错误日志用于调试
+- 向用户提供友好的错误消息
+
+## 性能优化技巧
+本节提供性能优化的建议，帮助提高API调用效率。
+
+### 批量请求
+- 尽可能使用批量操作减少网络往返
+- 合并多个小请求为一个大请求
+- 使用长连接保持会话状态
+
+### 缓存策略
+- 缓存频繁访问的静态数据
+- 使用ETag实现条件请求
+- 实现客户端缓存避免重复请求
+
+### 并发处理
+- 使用异步调用提高吞吐量
+- 实现请求管道化
+- 使用Web Worker处理后台任务
+
+## 调试工具与监控方法
+本节介绍调试和监控RCoder API的方法。
+
+### 调试工具
+- **REST Client**: 使用VS Code的REST Client插件测试API
+- **curl**: 命令行工具测试API端点
+- **Postman**: 图形化API测试工具
+
+### 监控方法
+- **日志监控**: 使用`RUST_LOG=debug`启用详细日志
+- **追踪系统**: 集成OpenTelemetry进行分布式追踪
+- **指标监控**: 收集API调用指标用于性能分析
+- **健康检查**: 定期调用`/health`端点验证服务状态
+
+**Section sources**
+- [http_test.rest](file://http_test.rest#L1-L109)
+- [README.md](file://README.md#L1-L652)