byy/qiming

Files

2026-06-01 13:54:52 +08:00

14 KiB

Raw Permalink Blame History

API端点参考

**本文档引用的文件** - [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)

简介

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字段。

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
描述: 检查服务的健康状态

成功响应示例

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00Z",
  "service": "rcoder-ai-service"
}

响应状态码

200: 服务健康

Section sources

health_handler.rs

聊天接口

聊天接口用于向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"

请求体示例

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

成功响应示例

{
  "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

实时进度流

通过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

任务取消

取消正在执行的AI代理任务。

端点信息

URL: /agent/session/cancel
方法: POST
标签: agent

查询参数

参数	类型	必需	描述	示例
`project_id`	string	是	项目ID，用于标识特定的项目	"test_project"
`session_id`	string	否	会话ID，用于标识要取消的会话（可选）	"session456"

成功响应示例

{
  "success": true,
  "data": {
    "success": true,
    "session_id": "session456"
  },
  "error": null
}

响应状态码

200: 成功转发取消请求到容器
400: 请求参数错误
404: 未找到对应的项目或会话
500: 转发取消请求失败

Section sources

agent_cancel_handler.rs

停止Agent

停止指定项目的Agent服务。

端点信息

URL: /agent/stop
方法: POST
标签: agent

查询参数

参数	类型	必需	描述	示例
`project_id`	string	是	项目ID	"test_project"

成功响应示例

{
  "success": true,
  "data": {
    "success": true,
    "project_id": "test_project",
    "session_id": null,
    "message": "容器已成功销毁"
  },
  "error": null
}

响应状态码

200: 成功销毁容器
400: 请求参数错误
500: 销毁容器失败

Section sources

agent_stop_handler.rs

Pingora反向代理API

Pingora是项目内置的高性能反向代理，所有真实的代理请求必须发送到Pingora的监听端口，并使用路径前缀形式/proxy/{port}/{path}来指定目标后端端口与路径。

代理状态查询

查询代理服务的状态。

端点信息

URL: /proxy/status
方法: GET
标签: proxy

成功响应示例

{
  "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

成功响应示例

{
  "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

成功响应示例

{
  "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

请求/响应格式

所有API响应都遵循统一的HttpResult<T>格式，确保客户端能够一致地处理响应。

响应结构

{
  "code": "0000",
  "message": "成功",
  "data": {},
  "tid": "trace-id",
  "success": true
}

字段	类型	描述
`code`	string	响应代码，"0000"表示成功
`message`	string	响应消息
`data`	object	响应数据，成功时包含具体数据
`tid`	string	跟踪ID，用于分布式追踪
`success`	boolean	是否成功，根据code自动计算

错误响应结构

{
  "code": "INTERNAL001",
  "message": "Internal server error",
  "data": null,
  "tid": "trace-id",
  "success": false
}

Section sources

http_result.rs

认证方法

RCoder API目前采用基于API密钥的认证方法。用户需要在请求头中包含Authorization字段。

认证方式

类型: Bearer Token
请求头: Authorization: Bearer <API_KEY>
环境变量: ANTHROPIC_API_KEY用于Claude代理

配置示例

export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="claude-3-sonnet-20240229"

错误处理策略

RCoder API采用统一的错误处理策略，所有错误都通过HttpResult<T>格式返回。

错误代码规范

代码范围	描述
`0000`	成功
`1xxx`	客户端错误
`2xxx`	服务器错误
`3xxx`	认证错误
`4xxx`	权限错误
`5xxx`	内部错误

错误处理示例

{
  "code": "INTERNAL001",
  "message": "Internal server error",
  "data": null,
  "success": false
}

Section sources

app_error.rs

安全考虑

RCoder API在设计时充分考虑了安全性，采用了多种安全措施。

安全特性

项目隔离: 每个对话在独立的项目工作空间中进行，确保安全性
容器化: AI代理在独立的Docker容器中运行，提供进程隔离
输入验证: 所有输入参数都经过严格验证
日志记录: 所有请求和响应都记录在结构化日志中
追踪ID: 每个请求都有唯一的追踪ID，便于审计和调试

安全建议

使用HTTPS保护API通信
定期轮换API密钥
限制API密钥的权限范围
监控异常的API调用模式

速率限制

RCoder API实施了速率限制策略，以防止滥用和确保服务质量。

速率限制规则

默认限制: 100次请求/分钟
突发限制: 200次请求/分钟（短时间）
IP限制: 每个IP地址的请求频率限制
项目限制: 每个项目ID的并发请求限制

速率限制响应

当超过速率限制时，API会返回429 Too Many Requests状态码。

{
  "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客户端实现

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

14 KiB Raw Permalink Blame History Unescape Escape

API端点参考

目录

简介

API概览

核心API端点

健康检查

聊天接口

实时进度流

任务取消

停止Agent

Pingora反向代理API

代理状态查询

代理统计信息

代理配置查询

请求/响应格式

响应结构

错误响应结构

认证方法

认证方式

配置示例

错误处理策略

错误代码规范

错误处理示例

安全考虑

安全特性

安全建议

速率限制

速率限制规则

速率限制响应

版本信息

当前版本

版本策略

客户端实现指南

HTTP客户端配置

SSE客户端实现

错误处理

性能优化技巧

批量请求

缓存策略

并发处理

调试工具与监控方法

调试工具

监控方法

14 KiB

Raw Permalink Blame History