290 lines
15 KiB
Markdown
290 lines
15 KiB
Markdown
# 聊天接口
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
|
||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||
- [crates/shared_types/src/model/chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs)
|
||
- [crates/shared_types/src/model/chat_response.rs](file://crates/shared_types/src/model/chat_response.rs)
|
||
- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs)
|
||
- [crates/shared_types/src/model/app_error.rs](file://crates/shared_types/src/model/app_error.rs)
|
||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
|
||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs)
|
||
- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
|
||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
|
||
- [http_test.rest](file://http_test.rest)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考量](#性能考量)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本文档面向RCoder项目的聊天API，聚焦于POST /chat端点的HTTP方法、请求头、请求体结构与响应格式；详解ChatPrompt数据模型中project_id、messages、model等字段的用途与约束；说明系统如何处理异步AI代理执行，并返回包含success、session_id和result的ChatResponse；涵盖请求验证错误（400）、服务器内部错误（500）等HTTP状态码的处理策略；提供完整的curl示例与错误码参考（如VALIDATION001、LOCAL001、INTERNAL001）；并阐述与SSE进度流的关联机制。
|
||
|
||
## 项目结构
|
||
RCoder采用双服务架构：
|
||
- rcoder服务：对外暴露统一入口，负责容器编排与请求转发，内部将请求转发至agent_runner容器服务。
|
||
- agent_runner服务：容器内AI代理执行与会话管理，负责实际的聊天处理、并发控制、SSE实时推送。
|
||
|
||
```mermaid
|
||
graph TB
|
||
Client["客户端"] --> R["rcoder服务<br/>/chat 转发"]
|
||
R --> AR["agent_runner服务<br/>/chat 执行"]
|
||
AR --> SSE["SSE 实时进度流<br/>/agent/progress/{session_id}"]
|
||
AR --> Cache["会话缓存与消息队列"]
|
||
```
|
||
|
||
图表来源
|
||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||
|
||
章节来源
|
||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||
|
||
## 核心组件
|
||
- POST /chat端点：接收聊天请求，校验参数，转发到容器内agent_runner服务，返回统一HttpResult包装的ChatResponse。
|
||
- ChatPrompt数据模型：承载project_id、project_path、session_id、prompt、attachments、data_source_attachments、agent_type、service_type、request_id、model_provider等字段。
|
||
- ChatResponse数据模型：返回project_id、session_id、error、request_id。
|
||
- SSE进度流：通过/agent/progress/{session_id}以Server-Sent Events推送实时更新。
|
||
- 错误处理：统一HttpResult结构，包含code、message、data、tid、success字段；AppError用于Axum错误映射。
|
||
|
||
章节来源
|
||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L109-L170)
|
||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L174-L220)
|
||
- [crates/shared_types/src/model/chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||
- [crates/shared_types/src/model/chat_response.rs](file://crates/shared_types/src/model/chat_response.rs#L1-L18)
|
||
- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L75)
|
||
- [crates/shared_types/src/model/app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||
|
||
## 架构总览
|
||
POST /chat的端到端流程如下：
|
||
- 客户端向rcoder服务发送POST /chat。
|
||
- rcoder服务根据project_id获取或创建容器，构建ProjectAndContainerInfo并缓存。
|
||
- rcoder服务将原始请求体直接转发到容器内的agent_runner服务的/chat端点。
|
||
- agent_runner服务执行聊天处理：校验参数、生成/清理会话、构建ChatPrompt并投递到本地任务通道。
|
||
- agent_runner服务返回HttpResult<ChatResponse>；rcoder服务解析并返回统一格式给客户端。
|
||
- 客户端通过/agent/progress/{session_id}建立SSE连接，接收实时进度。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端"
|
||
participant R as "rcoder服务"
|
||
participant AR as "agent_runner服务"
|
||
participant SSE as "SSE流"
|
||
C->>R : POST /chat
|
||
R->>R : 根据project_id获取/创建容器
|
||
R->>AR : 转发原始JSON到 /chat
|
||
AR->>AR : 参数校验/会话管理/构建ChatPrompt
|
||
AR-->>R : HttpResult<ChatResponse>
|
||
R-->>C : 统一HttpResult包装响应
|
||
C->>SSE : GET /agent/progress/{session_id}
|
||
AR-->>SSE : 推送实时更新
|
||
SSE-->>C : 事件流prompt_start/prompt_end/...
|
||
```
|
||
|
||
图表来源
|
||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L136-L221)
|
||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L174-L320)
|
||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||
|
||
## 详细组件分析
|
||
|
||
### HTTP端点：POST /chat
|
||
- 方法与路径：POST /chat
|
||
- 请求头：
|
||
- Content-Type: application/json
|
||
- 请求体结构（ChatRequest）：
|
||
- prompt: 字符串，必填（agent_runner侧进一步校验非空）
|
||
- project_id: 字符串，可选；若未提供，rcoder会生成并回填
|
||
- session_id: 字符串，可选；若未提供，agent_runner会创建新会话
|
||
- attachments: 数组，可选；支持多种附件类型
|
||
- data_source_attachments: 字符串数组，可选；用于传递外部数据源信息
|
||
- model_provider: 模型提供商配置对象，可选
|
||
- request_id: 字符串，可选；若未提供，agent_runner会生成
|
||
- 响应格式：统一HttpResult包装
|
||
- 成功：HttpResult.success(data=ChatResponse)
|
||
- 失败：HttpResult.error(code, message)
|
||
- 状态码：
|
||
- 200：成功
|
||
- 400：请求参数错误（如prompt为空）
|
||
- 409：Agent正在执行任务，禁止并发请求
|
||
- 500：服务器内部错误
|
||
|
||
章节来源
|
||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L109-L170)
|
||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L174-L220)
|
||
- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L75)
|
||
|
||
### ChatPrompt数据模型
|
||
- 字段说明与约束：
|
||
- project_id: 项目标识，决定工作目录./project_workspace/{project_id}
|
||
- project_path: 项目工作目录路径
|
||
- session_id: 可选；若未提供，agent_runner会创建新会话并返回
|
||
- prompt: 用户输入的提示词
|
||
- attachments: 可选附件列表
|
||
- data_source_attachments: 可选数据源附件（JSON字符串数组）
|
||
- agent_type: 代理类型
|
||
- service_type: 服务类型（强制要求，"rcoder"或"agent-runner"）
|
||
- request_id: 可选请求ID
|
||
- model_provider: 可选模型提供商配置
|
||
- 重要约束：
|
||
- service_type不可为空
|
||
- 若未提供project_id，系统会生成并创建工作目录
|
||
- 若未提供session_id，系统会创建新会话
|
||
|
||
章节来源
|
||
- [crates/shared_types/src/model/chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||
|
||
### ChatResponse数据模型
|
||
- 字段说明：
|
||
- project_id: 项目ID
|
||
- session_id: 会话ID
|
||
- error: 可选错误信息
|
||
- request_id: 可选请求ID
|
||
- 返回内容：
|
||
- rcoder服务会将agent_runner返回的ChatResponse封装为HttpResult.success(data=ChatResponse)再返回客户端
|
||
|
||
章节来源
|
||
- [crates/shared_types/src/model/chat_response.rs](file://crates/shared_types/src/model/chat_response.rs#L1-L18)
|
||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L290-L320)
|
||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L390-L430)
|
||
|
||
### 异步AI代理执行与SSE进度流
|
||
- 并发控制：agent_runner在收到请求时检查Agent状态，若Agent处于Active则拒绝并发请求，返回409错误。
|
||
- 会话管理：若显式提供了session_id，则移除该session；否则清理该项目下所有旧session，确保全新开始。
|
||
- 本地任务投递：构建ChatPrompt并投递到本地任务通道，等待执行结果。
|
||
- SSE推送：agent_runner通过/agent/progress/{session_id}以SSE推送实时事件，如prompt_start、prompt_end、agent消息分块、工具调用等。
|
||
- rcoder服务的SSE代理：rcoder服务也提供SSE代理，将容器内的SSE流透传给客户端。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["收到 /chat 请求"]) --> CheckPrompt["校验 prompt 非空"]
|
||
CheckPrompt --> PromptValid{"prompt有效？"}
|
||
PromptValid -- 否 --> Return400["返回 400 错误"]
|
||
PromptValid -- 是 --> CheckAgent["检查 Agent 状态"]
|
||
CheckAgent --> AgentActive{"Agent 正在执行？"}
|
||
AgentActive -- 是 --> Return409["返回 409 错误"]
|
||
AgentActive -- 否 --> CleanSession["清理旧会话如有"]
|
||
CleanSession --> BuildPrompt["构建 ChatPrompt"]
|
||
BuildPrompt --> SendTask["投递本地任务"]
|
||
SendTask --> WaitResult["等待执行结果"]
|
||
WaitResult --> ResultOk{"执行成功？"}
|
||
ResultOk -- 否 --> ReturnError["返回错误响应"]
|
||
ResultOk -- 是 --> ReturnSuccess["返回 ChatResponse"]
|
||
```
|
||
|
||
图表来源
|
||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L174-L320)
|
||
|
||
章节来源
|
||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L174-L320)
|
||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L207-L299)
|
||
- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L197-L257)
|
||
|
||
### 错误码与HTTP状态码
|
||
- 400 请求参数错误
|
||
- 示例：prompt为空
|
||
- 错误码示例：VALIDATION001
|
||
- 409 并发冲突
|
||
- Agent正在执行任务，禁止并发请求
|
||
- 错误码示例：1010
|
||
- 500 服务器内部错误
|
||
- rcoder服务转发失败或解析失败
|
||
- 错误码示例：INTERNAL001
|
||
- 本地执行失败
|
||
- 本地任务通道发送失败
|
||
- 错误码示例：LOCAL001
|
||
|
||
章节来源
|
||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L130-L168)
|
||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L311-L318)
|
||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L90-L107)
|
||
- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L75)
|
||
|
||
### curl示例
|
||
- 发送聊天请求并获取会话ID
|
||
- curl -X POST http://localhost:8087/chat -H "Content-Type: application/json" -d '{"prompt":"请帮我写一个 Rust 的 Hello World 程序","agent_type":"codex"}'
|
||
- 建立SSE进度流
|
||
- curl -N -H "Accept: text/event-stream" http://localhost:3000/agent/progress/{session_id}
|
||
- 取消会话（可选）
|
||
- curl -X POST http://localhost:3000/agent/session/cancel?project_id={project_id}&session_id={session_id}
|
||
|
||
章节来源
|
||
- [http_test.rest](file://http_test.rest#L1-L109)
|
||
|
||
## 依赖关系分析
|
||
- rcoder服务依赖agent_runner服务进行实际AI代理执行；通过容器URL直连转发。
|
||
- agent_runner服务依赖会话缓存与消息队列，保证SSE推送的可靠与有序。
|
||
- 共享类型（shared_types）定义了ChatPrompt、ChatResponse、HttpResult等跨服务通用模型。
|
||
|
||
```mermaid
|
||
graph LR
|
||
RC["rcoder服务"] --> AR["agent_runner服务"]
|
||
AR --> ST["shared_types<br/>ChatPrompt/ChatResponse/HttpResult"]
|
||
AR --> SC["会话缓存与消息队列"]
|
||
RC --> SSE["SSE代理"]
|
||
AR --> SSE
|
||
```
|
||
|
||
图表来源
|
||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L323-L431)
|
||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L260-L320)
|
||
- [crates/shared_types/src/model/chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||
- [crates/shared_types/src/model/chat_response.rs](file://crates/shared_types/src/model/chat_response.rs#L1-L18)
|
||
- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L197-L257)
|
||
|
||
## 性能考量
|
||
- 容器编排与状态缓存：rcoder服务使用DashMap缓存ProjectAndContainerInfo，降低重复创建成本。
|
||
- SSE推送：agent_runner使用SessionData与mpsc通道，避免阻塞主线程；SSE代理层透传事件，减少额外编码开销。
|
||
- 并发限制：通过Agent状态检查避免并发请求导致的资源竞争与性能抖动。
|
||
- 日志与追踪：HttpResult包含tid（trace_id），便于链路追踪与问题定位。
|
||
|
||
## 故障排查指南
|
||
- 400错误（参数无效）
|
||
- 检查请求体中prompt是否为空
|
||
- 检查service_type是否正确设置
|
||
- 409错误（Agent正在执行任务）
|
||
- 等待当前任务完成后重试
|
||
- 或者使用/agent/session/cancel取消当前任务
|
||
- 500错误（服务器内部错误）
|
||
- rcoder服务转发失败或解析失败
|
||
- 检查容器服务日志与网络连通性
|
||
- LOCAL001（本地执行失败）
|
||
- 本地任务通道发送失败
|
||
- 检查agent_runner服务状态与资源占用
|
||
|
||
章节来源
|
||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L130-L168)
|
||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L311-L318)
|
||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L323-L431)
|
||
|
||
## 结论
|
||
RCoder的聊天API通过rcoder服务与agent_runner服务的协同，实现了从请求接入、容器编排、AI代理执行到SSE实时进度推送的完整链路。统一的HttpResult与严格的参数校验、并发控制保障了系统的稳定性与可观测性。开发者可通过curl快速验证接口，并结合SSE流实现实时反馈。
|
||
|
||
## 附录
|
||
|
||
### API定义摘要
|
||
- POST /chat
|
||
- 请求体：ChatRequest
|
||
- 成功响应：HttpResult.success(ChatResponse)
|
||
- 失败响应：HttpResult.error(code, message)
|
||
- 状态码：200、400、409、500
|
||
- GET /agent/progress/{session_id}
|
||
- 响应：SSE事件流（prompt_start、prompt_end、agent消息分块、工具调用等）
|
||
|
||
章节来源
|
||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483) |