添加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)
--- a/qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/代理状态查询接口.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/代理状态查询接口.md
@@ -0,0 +1,329 @@
+# 代理状态查询接口
+
+<cite>
+**本文引用的文件列表**
+- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs)
+- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs)
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
+- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
+- [crates/shared_types/src/model/model_provider.rs](file://crates/shared_types/src/model/model_provider.rs)
+- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs)
+- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
+- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文档面向 RCoder 项目的“代理状态查询”API，聚焦 GET /agent/status/{project_id} 端点，系统性说明其 HTTP 方法、路径参数、响应格式与数据模型，并深入解释条件序列化机制（仅当代理存活时才包含详细字段）。同时提供成功响应示例（含代理运行中与未运行两种状态），并阐述该接口在客户端 UI 展示与自动化监控系统中的典型使用场景与集成方式。
+
+## 项目结构
+该接口位于两个模块中均有实现，分别服务于不同的运行形态：
+- agent_runner 模块：基于 ACP 代理的实现，使用全局 DashMap 存储项目与代理信息。
+- rcoder 模块：基于容器化 Agent 的实现，使用 AppState 中的项目到代理映射。
+
+二者共享同一 AgentStatusResponse 数据模型与统一的 HTTP 包装格式。
+
+```mermaid
+graph TB
+subgraph "API层"
+Router["路由注册<br/>/agent/status/{project_id}"]
+HandlerAR["agent_runner 状态处理器"]
+HandlerRC["rcoder 状态处理器"]
+end
+subgraph "数据模型"
+ModelResp["AgentStatusResponse"]
+ModelProv["ModelProviderSafeInfo"]
+HttpWrap["HttpResult<T>"]
+end
+subgraph "状态存储"
+MapAR["PROJECT_AND_AGENT_INFO_MAP<br/>DashMap<String, ProjectAndAgentInfo>"]
+AppStateRC["AppState.project_and_agent_map"]
+end
+Router --> HandlerAR
+Router --> HandlerRC
+HandlerAR --> MapAR
+HandlerRC --> AppStateRC
+HandlerAR --> ModelResp
+HandlerRC --> ModelResp
+ModelResp --> ModelProv
+HandlerAR --> HttpWrap
+HandlerRC --> HttpWrap
+```
+
+图表来源
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
+- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
+- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
+- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L22-L25)
+- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L97)
+- [crates/shared_types/src/model/model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L116-L132)
+- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
+
+章节来源
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
+
+## 核心组件
+- HTTP 端点：GET /agent/status/{project_id}
+- 路由注册：在 agent_runner 模块中通过路由工厂注册
+- 处理器：
+  - agent_runner：从全局 DashMap 读取项目代理信息
+  - rcoder：从 AppState 中的项目到代理映射读取
+- 数据模型：AgentStatusResponse（包含项目ID、存活标志、会话ID、状态、最后活动时间、创建时间、模型提供商安全信息）
+- 条件序列化：仅当 is_alive 为 true 时，序列化 session_id、status、last_activity、created_at、model_provider
+- HTTP 包装：统一返回 HttpResult<T> 结构，包含 code、message、data、tid、success 字段
+
+章节来源
+- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
+- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
+- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L97)
+- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
+
+## 架构总览
+下图展示从客户端到处理器、再到状态存储与响应封装的整体调用链路。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Router as "Axum 路由"
+participant Handler as "AgentStatus 处理器"
+participant Store as "状态存储"
+participant Model as "AgentStatusResponse"
+participant Wrap as "HttpResult 包装"
+Client->>Router : "GET /agent/status/{project_id}"
+Router->>Handler : "Path(project_id)"
+Handler->>Handler : "校验 project_id"
+alt "存在代理"
+Handler->>Store : "查询项目代理信息"
+Store-->>Handler : "ProjectAndAgentInfo"
+Handler->>Model : "构造 AgentStatusResponseis_alive=true"
+Handler->>Wrap : "封装为 HttpResult.success"
+Wrap-->>Client : "200 OK JSON"
+else "不存在代理"
+Handler->>Model : "构造 AgentStatusResponseis_alive=false"
+Handler->>Wrap : "封装为 HttpResult.success"
+Wrap-->>Client : "200 OK JSON"
+end
+```
+
+图表来源
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
+- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
+- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
+- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L97)
+- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
+
+## 详细组件分析
+
+### 端点定义与路由
+- 方法：GET
+- 路径：/agent/status/{project_id}
+- 路由注册位置：在 agent_runner 模块的路由工厂中注册
+- OpenAPI 注解：包含参数说明、响应示例与标签
+
+章节来源
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
+- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L11-L69)
+
+### 处理器逻辑（agent_runner）
+- 输入校验：去除空白字符，若为空则返回参数错误
+- 查询逻辑：从全局 DashMap 中按 project_id 获取代理信息
+- 成功分支：构造完整 AgentStatusResponse（包含 session_id、status、last_activity、created_at、model_provider）
+- 失败分支：构造简化 AgentStatusResponse（仅 project_id、is_alive=false）
+
+章节来源
+- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
+- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L22-L25)
+
+### 处理器逻辑（rcoder）
+- 输入校验：同上
+- 查询逻辑：从 AppState.project_and_agent_map 获取代理信息
+- 成功分支：构造完整 AgentStatusResponse
+- 失败分支：构造简化 AgentStatusResponse
+
+章节来源
+- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
+- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L661-L680)
+
+### 数据模型：AgentStatusResponse
+- 字段说明：
+  - project_id：项目ID
+  - is_alive：代理是否存活
+  - session_id：会话ID（仅当 is_alive 为 true 时存在）
+  - status：代理服务状态（仅当 is_alive 为 true 时存在）
+  - last_activity：最后活动时间（仅当 is_alive 为 true 时存在）
+  - created_at：创建时间（仅当 is_alive 为 true 时存在）
+  - model_provider：模型提供商安全信息（仅当 is_alive 为 true 时存在）
+- 条件序列化：使用 serde 的 skip_serializing_if 仅在 Option 非空时序列化对应字段
+
+```mermaid
+classDiagram
+class AgentStatusResponse {
+string project_id
+bool is_alive
+string? session_id
+AgentStatus? status
+DateTime? last_activity
+DateTime? created_at
+ModelProviderSafeInfo? model_provider
+}
+class ModelProviderSafeInfo {
+string id
+string name
+ModelApiProtocol api_protocol
+string default_model
+}
+class ModelApiProtocol {
+<<enum>>
+Anthropic
+OpenAI
+}
+AgentStatusResponse --> ModelProviderSafeInfo : "可选关联"
+```
+
+图表来源
+- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L97)
+- [crates/shared_types/src/model/model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L116-L132)
+
+章节来源
+- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L97)
+- [crates/shared_types/src/model/model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L116-L132)
+
+### 条件序列化机制
+- 仅当 is_alive 为 true 时，才会序列化 session_id、status、last_activity、created_at、model_provider
+- 该机制通过 serde 的 skip_serializing_if 实现，避免在代理未运行时返回冗余字段
+
+章节来源
+- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L97)
+
+### HTTP 包装与响应格式
+- 统一包装：HttpResult<T>，包含 code、message、data、tid、success
+- 成功响应：success=true，data 为 AgentStatusResponse
+- 失败响应：success=false，data=null，error 包含错误码与消息
+
+章节来源
+- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
+
+### 状态存储与生命周期
+- agent_runner：使用全局 DashMap 存储 ProjectAndAgentInfo，键为 project_id
+- rcoder：使用 AppState.project_and_agent_map 存储代理信息
+- 清理任务：在 Agent 生命周期结束时，原子性移除映射项，触发生命周期守卫 Drop，完成资源清理
+
+章节来源
+- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L22-L25)
+- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L661-L680)
+
+## 依赖关系分析
+- 路由到处理器：路由注册将 GET /agent/status/{project_id} 绑定到处理器函数
+- 处理器到存储：处理器从全局 DashMap 或 AppState 中查询项目代理信息
+- 处理器到模型：构造 AgentStatusResponse 并通过 HttpResult 包装
+- 模型到外部：AgentStatusResponse 依赖 ModelProviderSafeInfo，后者来自 ModelProviderConfig 的安全信息转换
+
+```mermaid
+graph LR
+Router["router.rs"] --> HandlerAR["agent_status_handler.rs (agent_runner)"]
+Router --> HandlerRC["agent_status_handler.rs (rcoder)"]
+HandlerAR --> Map["PROJECT_AND_AGENT_INFO_MAP"]
+HandlerRC --> AppState["AppState.project_and_agent_map"]
+HandlerAR --> Model["AgentStatusResponse"]
+HandlerRC --> Model
+Model --> SafeInfo["ModelProviderSafeInfo"]
+```
+
+图表来源
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
+- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
+- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
+- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L22-L25)
+- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L97)
+- [crates/shared_types/src/model/model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L116-L132)
+
+## 性能考量
+- 查询复杂度：DashMap 的读取为 O(1) 平均复杂度，适合高频状态查询
+- 序列化开销：条件序列化避免在代理未运行时序列化冗余字段，降低响应体积
+- 并发安全：DashMap 提供无锁读取能力，减少锁竞争
+- 日志与追踪：处理器记录请求与结果，便于定位问题与性能分析
+
+## 故障排查指南
+- 参数错误：当 project_id 为空时，返回 INVALID_PARAMS 错误
+- 代理不存在：返回 is_alive=false 的简化响应
+- 代理清理：确认清理任务是否正确移除映射项，避免脏读
+- 模型提供商安全信息：确认 to_safe_info 转换是否成功，避免敏感信息泄露
+
+章节来源
+- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L75-L84)
+- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L79-L84)
+- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L661-L680)
+- [crates/shared_types/src/model/model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L79-L88)
+
+## 结论
+GET /agent/status/{project_id} 接口以简洁稳定的响应模型提供了代理状态查询能力。通过条件序列化与统一的 HTTP 包装，既能满足客户端 UI 的直观展示需求，也能为自动化监控系统提供一致的数据格式。在 agent_runner 与 rcoder 两套实现中，接口语义保持一致，便于跨形态部署与迁移。
+
+## 附录
+
+### 接口规范摘要
+- 方法：GET
+- 路径：/agent/status/{project_id}
+- 路径参数：
+  - project_id：string，必填，项目ID
+- 成功响应（200 OK）：
+  - data：AgentStatusResponse
+  - success：true
+- 失败响应（400）：
+  - error：包含错误码与消息
+  - success：false
+
+章节来源
+- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L11-L69)
+- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L13-L67)
+- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
+
+### 响应示例（JSON）
+- 代理运行中（is_alive=true）
+  - data 字段包含：project_id、is_alive、session_id、status、last_activity、created_at、model_provider
+- 代理未运行（is_alive=false）
+  - data 字段包含：project_id、is_alive（false），其余字段省略
+
+章节来源
+- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L21-L49)
+- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L21-L51)
+
+### 数据模型字段详解
+- project_id：string，项目标识
+- is_alive：bool，代理是否存活
+- session_id：string，会话ID（仅存活时存在）
+- status：枚举，代理状态（Active/Idle/Terminating，仅存活时存在）
+- last_activity：时间戳，最后活动时间（仅存活时存在）
+- created_at：时间戳，创建时间（仅存活时存在）
+- model_provider：对象，模型提供商安全信息（仅存活时存在）
+
+章节来源
+- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L32-L41)
+- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L97)
+- [crates/shared_types/src/model/model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L116-L132)
+
+### 使用场景与集成建议
+- 客户端 UI：
+  - 轮询查询 /agent/status/{project_id}，根据 is_alive 控制按钮可用性与状态提示
+  - 若 is_alive=true，显示 session_id、status、last_activity 等细节，帮助用户了解代理运行状况
+- 自动化监控：
+  - 以 is_alive 作为健康指标，结合 last_activity 判断代理是否处于僵尸状态
+  - 将 model_provider 信息纳入监控面板，便于追踪模型提供商与默认模型
+- 错误处理：
+  - 对 400 参数错误进行明确提示，引导用户修正 project_id
+  - 对 5xx 内部错误通过 HttpResult.error 的 code 与 message 进行统一处理
+
+章节来源
+- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
+- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L75-L84)
+- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L79-L84)
--- a/qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/代理进度流接口.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/代理进度流接口.md
@@ -0,0 +1,305 @@
+# 代理进度流接口
+
+<cite>
+**本文引用的文件**
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.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/shared_types/src/model/agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs)
+- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
+- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
+- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
+- [crates/shared_types/src/grpc/agent.rs](file://crates/shared_types/src/grpc/agent.rs)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖分析](#依赖分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向 RCoder 项目的“代理进度流”接口，聚焦于 GET /agent/progress/{session_id} 的 Server-Sent Events（SSE）实现。该接口提供实时的 AI 任务执行进度更新，涵盖代码生成、文件操作等事件类型；同时说明 SSE 文本流格式、事件类型分类、客户端重连机制，以及 session_id 的生成与有效期管理策略，并给出 JavaScript 客户端示例的对接思路与最佳实践。
+
+## 项目结构
+- 该接口在两个服务中均有实现：
+  - agent_runner：直接消费内部会话缓存，推送统一的 UnifiedSessionMessage。
+  - rcoder：作为代理层，将外部容器的 SSE 流透传给客户端。
+- 路由注册位于 agent_runner 的路由文件中，暴露 /agent/progress/{session_id}。
+
+```mermaid
+graph TB
+subgraph "Agent Runner 服务"
+R["路由注册<br/>/agent/progress/{session_id}"]
+H1["SSE处理器<br/>agent_session_notification"]
+C["会话缓存<br/>SessionCache/SessionData"]
+end
+subgraph "Shared Types"
+M["UnifiedSessionMessage<br/>统一消息模型"]
+end
+R --> H1
+H1 --> C
+C --> M
+```
+
+图表来源
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
+- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
+- [crates/shared_types/src/model/agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L16-L30)
+
+章节来源
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
+
+## 核心组件
+- SSE 处理器：负责建立 SSE 连接、发送心跳、将消息事件化并推送。
+- 会话缓存：维护每个 session_id 的消息通道与取消令牌，支持新连接覆盖旧连接。
+- 统一消息模型：将不同类型的会话更新统一为 UnifiedSessionMessage，便于前端解析。
+- 代理层（rcoder）：当需要透传外部容器的 SSE 时，将容器端 SSE 流透传至客户端。
+
+章节来源
+- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
+- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L24-L103)
+- [crates/shared_types/src/model/agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L16-L30)
+
+## 架构总览
+SSE 进度流的总体交互如下：
+- 客户端发起 GET /agent/progress/{session_id} 建立 SSE 连接。
+- 服务端根据 session_id 获取或创建会话数据，建立消息通道与取消令牌。
+- 服务端立即发送一次心跳事件，随后周期性发送心跳，并将收到的统一消息转换为 SSE 事件推送。
+- 若连接被取消（如新连接建立或用户取消），旧连接会自然断开。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Handler as "SSE处理器"
+participant Cache as "会话缓存"
+participant Worker as "会话工作线程"
+participant Model as "统一消息模型"
+Client->>Handler : "GET /agent/progress/{session_id}"
+Handler->>Cache : "创建/获取 SessionData 并建立新连接"
+Handler->>Client : "发送初始心跳事件"
+Worker-->>Handler : "推送 UnifiedSessionMessage"
+Handler->>Client : "按事件类型发送事件如 prompt_start/prompt_end/tool_call 等"
+Handler->>Client : "周期性发送心跳事件"
+Handler-->>Client : "连接被取消/断开时终止推送"
+```
+
+图表来源
+- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
+- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L67-L103)
+- [crates/shared_types/src/model/agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L16-L30)
+
+## 详细组件分析
+
+### SSE 文本流格式与事件类型
+- 文本流遵循标准 SSE 格式，每条消息包含事件类型与数据两部分。
+- 事件类型与 UnifiedSessionMessage 的映射关系：
+  - prompt_start：会话开始
+  - prompt_end：会话结束（含结束原因）
+  - agent_message_chunk：Agent 文本响应片段
+  - agent_thought_chunk：Agent 思考过程片段
+  - tool_call：工具调用通知
+  - tool_call_update：工具调用状态更新
+  - available_commands_update：可用命令更新
+  - current_mode_update：当前模式更新
+  - heartbeat：心跳消息
+- 数据体为 JSON，结构遵循 UnifiedSessionMessage，包含 session_id、message_type、sub_type、data、timestamp。
+
+章节来源
+- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
+- [crates/shared_types/src/model/agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L165-L246)
+
+### SSE 处理器（agent_runner）
+- 建立新连接：为每个 session_id 创建新的 SessionData 并插入缓存，确保每次连接全新开始。
+- 发送心跳：首次立即发送一次心跳事件，随后以固定间隔（如 30 秒）发送心跳。
+- 事件分发：将收到的 UnifiedSessionMessage 按 message_type 与 sub_type 转换为对应的事件名并推送。
+- 取消与断开：监听取消令牌与通道关闭，及时退出循环并记录日志。
+
+```mermaid
+flowchart TD
+Start(["建立连接"]) --> NewSession["创建/获取 SessionData 并建立新连接"]
+NewSession --> SendHB["发送初始心跳事件"]
+SendHB --> Loop{"循环接收消息"}
+Loop --> |收到消息| MapEvent["按消息类型映射事件名"]
+MapEvent --> Yield["yield SSE 事件"]
+Yield --> Loop
+Loop --> |取消令牌触发| Close["断开连接"]
+Loop --> |通道关闭| Close
+Close --> End(["结束"])
+```
+
+图表来源
+- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
+
+章节来源
+- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
+
+### 会话缓存与连接管理
+- SessionData：持有命令通道、当前发送器与取消令牌，支持创建新连接并设置当前发送器与取消令牌。
+- SessionWorker：维护环形缓冲区，按需缓冲非心跳消息，并将消息实时推送到当前发送器。
+- 项目-会话映射：ensure_project_session 确保同一项目仅对应一个活跃会话，必要时清理旧会话数据。
+- 主动关闭：close_current_connection 主动触发取消令牌并丢弃发送器，促使接收端感知断开。
+
+```mermaid
+classDiagram
+class SessionData {
+new(max_size)
+create_new_connection(buffer_size)
+push_message(message)
+close_current_connection()
+}
+class SessionWorker {
+spawn(max_size, command_rx, current_sender, current_cancel)
+run()
+}
+class UnifiedSessionMessage {
+session_id
+message_type
+sub_type
+data
+timestamp
+}
+SessionData --> SessionWorker : "spawn"
+SessionWorker --> UnifiedSessionMessage : "推送"
+```
+
+图表来源
+- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L24-L103)
+- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L140-L222)
+- [crates/shared_types/src/model/agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L16-L30)
+
+章节来源
+- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L24-L103)
+- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L140-L222)
+
+### 代理层 SSE 透传（rcoder）
+- 当需要代理外部容器的 SSE 时，rcoder 会根据 session_id 查找对应容器，建立到容器 SSE 端点的连接，并将容器的 SSE 流透传给客户端。
+- 透传逻辑按双换行符切分事件，解析 event/data 字段，避免重复 data: 前缀，然后直接透传事件。
+- 错误处理：容器连接失败或读取失败时，发送 error 事件并记录日志。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Proxy as "rcoder SSE代理"
+participant Container as "容器SSE端点"
+Client->>Proxy : "GET /agent/progress/{session_id}"
+Proxy->>Container : "建立到容器SSE的连接"
+Container-->>Proxy : "SSE事件流按双换行符分隔"
+Proxy->>Proxy : "解析event/data并去重"
+Proxy-->>Client : "透传SSE事件"
+Proxy-->>Client : "错误时发送error事件"
+```
+
+图表来源
+- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L106-L299)
+- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L207-L299)
+
+章节来源
+- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L106-L299)
+
+### session_id 的生成与有效期管理
+- 生成机制：在聊天处理流程中，当创建项目会话状态时，会为项目设置 session_id，并更新最后活动时间。项目-会话映射通过 ensure_project_session 保证唯一性。
+- 有效期管理：服务端未对 session_id 设置硬性过期时间；连接断开或取消会触发清理。若需要过期控制，可在业务侧增加会话超时策略（例如定期清理长时间无活动的会话）。
+- 会话切换：当同一项目的新会话建立时，旧会话数据会被清理，确保不会跨会话污染。
+
+章节来源
+- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L272-L302)
+- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L80-L95)
+- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L282-L354)
+
+### 客户端重连机制与最佳实践
+- 心跳检测：服务端会周期性发送 heartbeat 事件，前端应基于心跳判断连接是否仍活跃。
+- 自动重连：建议实现指数退避的自动重连策略，避免频繁重试造成压力。
+- 事件处理：根据事件类型（prompt_start/prompt_end/tool_call 等）更新 UI 状态，避免阻塞主线程。
+- 错误处理：监听连接错误与 SessionPromptEnd 中的错误信息，向用户反馈并引导重试或取消。
+
+章节来源
+- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
+
+### 与 gRPC 订阅接口的关系
+- 项目中提供了基于 gRPC 的订阅进度流接口（subscribe_progress），可替代传统的 /agent/progress/{session_id} SSE 接口。
+- 若采用 gRPC 方案，前端需使用 gRPC 客户端订阅进度流，事件类型与数据结构保持一致。
+
+章节来源
+- [crates/shared_types/src/grpc/agent.rs](file://crates/shared_types/src/grpc/agent.rs#L232-L236)
+
+## 依赖分析
+- 路由依赖：/agent/progress/{session_id} 在 agent_runner 的路由中注册。
+- 处理器依赖：SSE 处理器依赖会话缓存与统一消息模型。
+- 代理层依赖：rcoder 的代理处理器依赖容器映射与 SSE 透传逻辑。
+- 项目-会话映射：通过 ensure_project_session 保证同一项目仅有一个活跃会话。
+
+```mermaid
+graph LR
+Router["路由"] --> SSEHandler["SSE处理器"]
+SSEHandler --> SessionCache["会话缓存"]
+SessionCache --> UnifiedMsg["统一消息模型"]
+ProxyHandler["rcoder代理处理器"] --> ContainerSSE["容器SSE端点"]
+```
+
+图表来源
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
+- [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#L106-L299)
+- [crates/shared_types/src/model/agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L16-L30)
+
+章节来源
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
+- [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#L106-L299)
+
+## 性能考虑
+- 心跳频率：默认 30 秒一次，可根据网络状况调整，避免过多心跳占用带宽。
+- 缓冲策略：SessionWorker 使用环形缓冲区，非心跳消息优先缓冲，心跳消息直通，减少延迟。
+- 取消与断开：通过 CancellationToken 与通道关闭快速退出，避免资源泄漏。
+- 透传效率：rcoder 代理层按双换行符切分事件，避免重复解析，提高透传效率。
+
+章节来源
+- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L395-L475)
+- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L173-L222)
+- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L156-L262)
+
+## 故障排查指南
+- 404 未找到容器：当 session_id 对应的活跃容器不存在时，返回 404 并携带错误码。
+- 建立 SSE 连接失败：容器 SSE 连接失败或读取失败时，发送 error 事件并记录错误。
+- 连接被取消：当新连接建立或用户取消任务时，旧连接会主动断开。
+- 心跳缺失：若长时间未收到 heartbeat，应触发重连流程。
+
+章节来源
+- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L106-L153)
+- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L207-L259)
+- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L400-L477)
+
+## 结论
+RCoder 的代理进度流接口通过 SSE 提供了稳定、低延迟的实时进度推送能力。其核心在于：
+- 统一消息模型与事件类型映射，便于前端解析；
+- 会话缓存与取消令牌机制，确保连接可控与资源回收；
+- 代理层透传能力，满足多容器场景；
+- 心跳与断开策略，保障连接健康与稳定性。
+
+建议在前端实现自动重连与指数退避、基于事件类型的状态机更新，并结合业务侧的会话超时策略，构建健壮的实时进度体验。
+
+## 附录
+
+### API 定义与示例
+- 端点：GET /agent/progress/{session_id}
+- 内容类型：text/event-stream
+- 响应：SSE 事件流，事件类型与数据体见“SSE 文本流格式与事件类型”。
+
+章节来源
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
+- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
+
+### JavaScript 客户端对接要点（概念性说明）
+- 使用浏览器内置 EventSource API 建立连接，监听不同事件类型并更新 UI。
+- 实现自动重连：监听 error 与 close 事件，采用指数退避策略重连。
+- 心跳检测：收到 heartbeat 事件后刷新心跳计时器，超时则触发重连。
+- 错误处理：监听 error 事件与 SessionPromptEnd 中的错误信息，向用户反馈并引导操作。
+
+[本节为概念性说明，不直接分析具体源码文件]
--- a/qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/健康检查接口.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/健康检查接口.md
@@ -0,0 +1,305 @@
+# 健康检查接口
+
+<cite>
+**本文引用的文件列表**
+- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs)
+- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.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)
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
+- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
+- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
+- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs)
+- [README.md](file://README.md)
+- [docker/Dockerfile](file://docker/Dockerfile)
+- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向RCoder项目的健康检查API，聚焦GET /health端点的HTTP方法、URL模式、响应格式与行为语义。文档解释该接口如何用于系统状态监控与负载均衡器健康探测，给出成功与失败场景的JSON结构说明，阐述服务启动时的验证作用，并提供在Kubernetes等容器编排系统中的集成方式、curl示例与客户端实现要点，以及性能监控与超时处理的最佳实践。
+
+## 项目结构
+- 健康检查端点在两个主要服务中均可用：
+  - rcoder主服务：提供HTTP API与健康检查
+  - agent_runner服务：同样提供健康检查端点
+- 路由注册与OpenAPI文档由各服务的router模块负责
+- 服务启动时绑定端口并启动HTTP服务器，健康检查端点即随服务启动而可用
+
+```mermaid
+graph TB
+subgraph "rcoder主服务"
+RMain["main.rs<br/>启动HTTP服务器"]
+RRouter["router.rs<br/>路由注册 /health"]
+RHandler["health_handler.rs<br/>健康检查处理器"]
+end
+subgraph "agent_runner服务"
+AMain["main.rs<br/>启动HTTP服务器"]
+ARouter["router.rs<br/>路由注册 /health"]
+AHandler["health_handler.rs<br/>健康检查处理器"]
+end
+RMain --> RRouter --> RHandler
+AMain --> ARouter --> AHandler
+```
+
+图表来源
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
+- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
+- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
+- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
+
+章节来源
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
+- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
+
+## 核心组件
+- 健康检查处理器
+  - 路径：/health
+  - 方法：GET
+  - 响应：JSON对象，包含status、timestamp、service字段
+- 路由注册
+  - rcoder：在router.rs中将GET /health绑定到处理器
+  - agent_runner：同理
+- 服务启动
+  - main.rs中创建Axum Router并绑定TCP监听，健康检查端点随服务启动而可用
+
+章节来源
+- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
+- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
+- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
+
+## 架构总览
+健康检查端点作为系统健康状态的快速探测入口，既可用于内部监控，也可供外部负载均衡器/编排系统进行存活探针。在rcoder中，健康检查端点位于HTTP API层，不依赖业务逻辑，因此其可用性直接反映服务进程的启动与HTTP服务器的就绪状态。
+
+```mermaid
+sequenceDiagram
+participant LB as "负载均衡器/探针"
+participant HTTP as "HTTP服务器(Axum)"
+participant Router as "路由(/health)"
+participant Handler as "健康检查处理器"
+LB->>HTTP : GET /health
+HTTP->>Router : 分发请求
+Router->>Handler : 调用处理器
+Handler-->>HTTP : 返回JSON响应
+HTTP-->>LB : 200 OK 或错误码
+```
+
+图表来源
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
+- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
+- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
+
+## 详细组件分析
+
+### 健康检查端点定义与响应
+- HTTP方法与URL模式
+  - 方法：GET
+  - 路径：/health
+- 响应结构
+  - status：字符串，表示服务健康状态
+  - timestamp：UTC时间戳
+  - service：服务标识
+- 成功响应
+  - HTTP状态码：200 OK
+  - 响应体：包含上述字段的JSON对象
+- 失败响应
+  - 当HTTP服务器未启动或路由未注册时，可能出现非200的状态码（例如5xx）
+  - 由于健康检查处理器不进行数据库或其他外部依赖的深度校验，一般不会出现500错误；若出现，通常表示服务启动异常或中间件/路由配置问题
+
+```mermaid
+flowchart TD
+Start(["请求进入 /health"]) --> Route["匹配路由 /health"]
+Route --> HandlerCall["调用健康检查处理器"]
+HandlerCall --> BuildResp["构造响应对象(status, timestamp, service)"]
+BuildResp --> ReturnOK["返回 200 OK + JSON"]
+ReturnOK --> End(["结束"])
+```
+
+图表来源
+- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
+- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
+
+章节来源
+- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
+- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
+
+### 服务启动与健康检查可用性
+- rcoder主服务
+  - main.rs中创建Axum Router并绑定监听端口，随后启动HTTP服务器
+  - 启动日志明确打印了API端点信息，包括GET /health
+- agent_runner服务
+  - 同样在main.rs中绑定监听端口并启动HTTP服务器
+  - 路由注册中包含GET /health
+
+```mermaid
+sequenceDiagram
+participant Main as "main.rs"
+participant Router as "router.rs"
+participant Server as "HTTP服务器(Axum)"
+Main->>Router : create_router(state)
+Router-->>Main : 返回Router
+Main->>Server : 绑定监听端口并启动
+Server-->>Main : 服务就绪
+Note over Main,Server : /health 端点随服务启动而可用
+```
+
+图表来源
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
+- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
+
+章节来源
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
+- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
+
+### 在Kubernetes等容器编排系统中的集成
+- 健康检查配置
+  - Dockerfile中定义了HEALTHCHECK指令，使用curl对http://localhost:PORT/health进行探测
+  - 默认端口为8087（来自rcoder_default.yml中的port字段）
+- 推荐配置
+  - 在Kubernetes中，使用livenessProbe/readinessProbe指向同一端点
+  - 建议将探针超时时间设置为小于探测周期，避免长时间阻塞导致误判
+  - 若使用代理（Pingora），建议直接对代理监听端口进行探测，或在代理层暴露健康检查端点
+
+章节来源
+- [docker/Dockerfile](file://docker/Dockerfile#L296-L304)
+- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L10-L12)
+
+### curl命令示例与客户端实现指南
+- curl示例
+  - GET http://localhost:8087/health
+- 客户端实现要点
+  - 使用HTTP客户端库发起GET请求
+  - 解析JSON响应，读取status、timestamp、service字段
+  - 对于200以外的状态码，视为不健康
+  - 设置合理的超时时间，避免阻塞
+
+章节来源
+- [README.md](file://README.md#L229-L242)
+
+### 健康检查与负载均衡器健康探测
+- 健康检查处理器不进行外部依赖（如数据库、代理后端）的深度校验，仅反映服务进程与HTTP服务器的就绪状态
+- 负载均衡器可将其作为存活探针，结合探针超时、重试次数与周期进行综合判断
+- 若需要对代理后端进行健康探测，可参考代理健康检查配置（见下一节）
+
+章节来源
+- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L52-L98)
+- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
+
+## 依赖关系分析
+- 路由到处理器的依赖
+  - rcoder与agent_runner分别在各自的router.rs中注册GET /health
+  - 处理器在各自handler/health_handler.rs中实现
+- 服务启动依赖
+  - main.rs负责创建Router并启动HTTP服务器
+- 代理健康检查（额外能力）
+  - rcoder的ProxyConfig包含HealthCheckConfig
+  - Pingora服务实现健康检查循环，定期对后端端口进行连通性探测
+
+```mermaid
+graph LR
+RMain["rcoder/main.rs"] --> RRouter["rcoder/router.rs"]
+RRouter --> RHandler["rcoder/handler/health_handler.rs"]
+AMain["agent_runner/main.rs"] --> ARouter["agent_runner/router.rs"]
+ARouter --> AHandler["agent_runner/handler/health_handler.rs"]
+Config["rcoder/config.rs<br/>ProxyConfig/HealthCheckConfig"] --> PingoraSvc["pingora-proxy/service.rs<br/>健康检查循环"]
+```
+
+图表来源
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
+- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
+- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
+- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
+- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L52-L98)
+- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
+
+章节来源
+- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L52-L98)
+- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
+
+## 性能考量
+- 健康检查处理器为纯内存计算，开销极低，适合高频探测
+- 探测周期与超时设置建议
+  - 周期：根据业务SLA设定，常见为10-30秒
+  - 超时：建议小于周期，避免探针阻塞影响其他请求
+- 在Kubernetes中，合理设置initialDelaySeconds、periodSeconds、timeoutSeconds与failureThreshold，避免误判
+- 若使用代理（Pingora），可利用其健康检查能力对后端进行更细粒度的探测
+
+章节来源
+- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L124-L134)
+- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L581-L591)
+
+## 故障排查指南
+- 无法访问/health
+  - 检查服务是否已启动并绑定到预期端口
+  - 确认防火墙与网络策略允许访问
+- 响应非200
+  - 查看服务日志，定位路由或中间件异常
+  - 确认路由注册是否正确
+- 健康检查频繁失败
+  - 检查探针超时与周期设置
+  - 在Kubernetes中适当增大failureThreshold，避免抖动
+- 代理健康检查相关
+  - 确认ProxyConfig中的health_check.enabled、interval_seconds、timeout_seconds配置
+  - 检查后端端口连通性
+
+章节来源
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
+- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
+- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L52-L98)
+- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
+
+## 结论
+GET /health端点为RCoder提供了轻量、可靠的健康状态探测入口，适用于服务启动验证与负载均衡器健康探测。其简单实现确保了低开销与高可用性。在生产环境中，建议结合探针超时、周期与重试策略，以及必要时启用代理健康检查，以获得更全面的健康状态视图。
+
+## 附录
+
+### API定义与示例
+- 端点：GET /health
+- 响应示例（成功）
+  - 状态码：200 OK
+  - 响应体：包含status、timestamp、service字段的JSON对象
+- 响应示例（失败）
+  - 状态码：非200（例如5xx）
+  - 响应体：错误信息（由HTTP服务器或中间件决定）
+
+章节来源
+- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
+- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
+- [README.md](file://README.md#L229-L242)
+
+### 集成与最佳实践
+- curl示例
+  - curl -X GET http://localhost:8087/health
+- Kubernetes集成
+  - 使用livenessProbe/readinessProbe指向同一端点
+  - HEALTHCHECK已在Dockerfile中定义，可直接复用
+- 超时与周期
+  - 建议周期10-30秒，超时小于周期
+  - failureThreshold根据稳定性需求调整
+
+章节来源
+- [README.md](file://README.md#L229-L242)
+- [docker/Dockerfile](file://docker/Dockerfile#L296-L304)
--- a/qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/反向代理接口.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/反向代理接口.md
@@ -0,0 +1,269 @@
+# 反向代理接口
+
+<cite>
+**本文引用的文件**
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
+- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs)
+- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs)
+- [crates/rcoder/src/handler/proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs)
+- [crates/agent_runner/src/handler/proxy_api.rs](file://crates/agent_runner/src/handler/proxy_api.rs)
+- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs)
+- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs)
+- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs)
+- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs)
+- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs)
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
+- [crates/rcoder/src/proxy_agent/port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向RCoder项目的反向代理API，聚焦/proxy/{port}/{path}端点的路由机制与请求转发逻辑，说明其如何将请求代理到AI代理在特定端口上运行的服务；解释端口管理机制与请求/响应的透明转发过程；提供curl示例，展示如何通过该接口访问代理的Web界面或API；说明与Pingora反向代理组件的集成方式，以及在处理WebSocket连接时的特殊考虑。
+
+## 项目结构
+RCoder项目包含两个主要服务：
+- rcoder服务：提供聊天、会话管理、代理状态查询等API，并在启动时可选择启用Pingora反向代理服务。
+- agent_runner服务：同样可启用Pingora代理服务，用于代理AI代理容器对外暴露的端口。
+
+反向代理API在两个服务中均通过Axum路由注册，核心处理逻辑位于各自的handler模块中；而真正的代理转发由Pingora库实现。
+
+```mermaid
+graph TB
+subgraph "rcoder服务"
+RRouter["Axum路由<br/>/proxy/*"]
+RHandler["代理处理器<br/>proxy_handler_api.rs"]
+RState["AppState<br/>包含Pingora服务引用"]
+end
+subgraph "agent_runner服务"
+ARouter["Axum路由<br/>/proxy/*"]
+AHandler["代理处理器<br/>proxy_handler_api.rs"]
+AState["AppState<br/>包含Pingora服务引用"]
+end
+subgraph "Pingora代理"
+PServer["PingoraServerManager<br/>启动与管理"]
+PService["PingoraProxyService<br/>端口代理实现"]
+PPort["PortProxy<br/>请求过滤/选择上游/响应过滤"]
+end
+RRouter --> RHandler --> RState
+ARouter --> AHandler --> AState
+RState --> PService
+AState --> PService
+PServer --> PService
+PService --> PPort
+```
+
+图表来源
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L83)
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L67-L79)
+- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L230-L332)
+- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L230-L332)
+- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L66)
+- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L224-L354)
+
+章节来源
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L83)
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L67-L79)
+
+## 核心组件
+- 路由注册：在rcoder与agent_runner的router中分别注册/proxy/status、/proxy/stats、/proxy/config、/proxy/{port}、/proxy/{port}/{*path}等端点。
+- 代理处理器：提供状态、统计、配置查询；以及将请求重定向到Pingora监听端口的处理器。
+- Pingora服务：负责实际的请求转发、负载均衡、健康检查、指标统计与上游选择。
+- 配置与启动：在rcoder主程序中根据配置启动Pingora服务器管理器，并将服务引用注入到AppState，供代理处理器读取。
+
+章节来源
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L83)
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L67-L79)
+- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L230-L332)
+- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L230-L332)
+- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L66)
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
+
+## 架构总览
+/proxy/{port}/{path}端点的请求流如下：
+- 客户端请求到达rcoder/agent_runner的Axum路由。
+- 若代理未启用，返回“服务不可用”错误。
+- 若启用，处理器将请求临时重定向至Pingora监听端口的对应路径（/proxy/{port}或/ proxy/{port}/{path}），由Pingora完成实际转发。
+- Pingora根据请求路径提取目标端口，动态发现后端主机，选择上游Peer，重写请求头与URI，转发到后端服务，并记录指标。
+
+```mermaid
+sequenceDiagram
+participant C as "客户端"
+participant AX as "Axum路由"
+participant H as "代理处理器"
+participant PS as "Pingora服务"
+participant PR as "PortProxy"
+participant BE as "后端服务"
+C->>AX : "GET /proxy/{port}/{path}"
+AX->>H : "匹配路由并进入处理器"
+H->>PS : "读取配置/状态如需"
+H-->>C : "307 临时重定向到 Pingora 监听端口"
+C->>PS : "再次请求 /proxy/{port} 或 /proxy/{port}/{path}"
+PS->>PR : "upstream_peer/过滤请求/响应"
+PR->>PR : "提取端口/重写URI/选择上游"
+PR->>BE : "转发到后端服务"
+BE-->>PR : "返回响应"
+PR-->>PS : "记录指标/计时"
+PS-->>C : "返回最终响应"
+```
+
+图表来源
+- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L230-L332)
+- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L246-L354)
+- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L66)
+
+## 详细组件分析
+
+### 路由与控制器
+- rcoder与agent_runner各自在router中注册/proxy/*端点，包括状态、统计、配置查询与端口代理。
+- 代理处理器对/proxy/{port}与/proxy/{port}/{*path}进行处理：若代理未启用则返回错误；否则构造临时重定向到Pingora监听端口的Location头。
+
+章节来源
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L83)
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L67-L79)
+- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L230-L332)
+- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L230-L332)
+
+### Pingora代理实现
+- PingoraProxyService：维护后端映射、负载均衡算法、健康检查、指标统计与上下文跟踪。
+- PortProxy：实现ProxyHttp，负责：
+  - 上游请求过滤：重写Host、添加X-Forwarded-Proto与X-Load-Balancer头；重写URI，移除/proxy/{port}前缀并保留查询参数。
+  - 上游Peer选择：从请求路径提取目标端口；若端口不在后端映射中则动态添加到默认主机；选择HttpPeer。
+  - 响应过滤：记录响应状态与耗时、更新指标、减少活跃连接数。
+
+章节来源
+- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L224-L354)
+- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L356-L409)
+- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L411-L596)
+
+### 端口管理机制
+- rcoder服务中的PortManager负责容器端口分配与回收，避免端口冲突，确保代理后端端口可用。
+- Pingora侧通过动态后端映射实现“按需发现”，首次遇到某端口时自动将其加入后端列表。
+
+章节来源
+- [crates/rcoder/src/proxy_agent/port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs#L1-L96)
+- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L300-L333)
+
+### WebSocket连接的特殊考虑
+- Pingora库基于Cloudflare Pingora，支持HTTP/1.1与HTTP/2，理论上可处理升级为WebSocket的请求。
+- 由于rcoder与agent_runner的代理处理器采用临时重定向的方式，客户端需要遵循重定向并保持连接；具体WebSocket行为取决于上游后端服务是否支持升级。
+- 若上游服务不支持升级，或客户端未正确处理重定向，可能出现握手失败或连接中断。
+
+章节来源
+- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L58)
+- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L66)
+
+### 请求/响应透明转发流程
+```mermaid
+flowchart TD
+Start(["进入处理器"]) --> CheckEnabled{"代理已启用？"}
+CheckEnabled --> |否| ReturnErr["返回服务不可用错误"]
+CheckEnabled --> |是| BuildLoc["构造重定向到 Pingora 监听端口的 Location"]
+BuildLoc --> Redirect["返回307临时重定向"]
+Redirect --> Pingora["Pingora 接收请求"]
+Pingora --> FilterReq["上游请求过滤<br/>重写Host/URI/添加头部"]
+FilterReq --> SelectPeer["选择上游Peer<br/>提取端口/动态后端"]
+SelectPeer --> Forward["转发到后端服务"]
+Forward --> RespFilter["响应过滤<br/>记录指标/计时"]
+RespFilter --> Done(["返回响应"])
+ReturnErr --> End(["结束"])
+Done --> End
+```
+
+图表来源
+- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L230-L332)
+- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L246-L354)
+
+## 依赖关系分析
+- rcoder/agent_runner的路由依赖于代理处理器模块；代理处理器依赖于AppState中的Pingora服务引用。
+- Pingora服务依赖于Pingora库的ProxyHttp trait实现，通过包装器将内部PortProxy暴露为Pingora服务。
+- rcoder主程序在启动时根据配置创建PingoraServerManager并启动服务器，同时将服务引用注入AppState。
+
+```mermaid
+graph LR
+Router["Axum路由"] --> Handler["代理处理器"]
+Handler --> AppState["AppState"]
+AppState --> PingoraSvc["PingoraProxyService"]
+PingoraSvc --> PortProxy["PortProxy"]
+PingoraMgr["PingoraServerManager"] --> PingoraSvc
+Main["rcoder主程序"] --> PingoraMgr
+```
+
+图表来源
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L83)
+- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L230-L332)
+- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L66)
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
+
+章节来源
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L83)
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L67-L79)
+- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L230-L332)
+- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L230-L332)
+- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L66)
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
+
+## 性能考量
+- 负载均衡：Pingora支持轮询与一致性哈希两种算法，默认启用轮询；可根据配置切换。
+- 健康检查：Pingora内置TCP健康检查，周期性探测后端连通性，支持超时与阈值配置。
+- 指标统计：提供总请求数、成功率、平均响应时间、每端口统计与活跃连接数等指标，便于监控与优化。
+- 动态后端：首次遇到新端口时自动加入后端映射，避免预配置开销，提升弹性。
+
+章节来源
+- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L509-L596)
+- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L143-L155)
+- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
+
+## 故障排查指南
+- 代理未启用：当AppState中未注入Pingora服务或配置为空时，/proxy/*接口返回“服务不可用”错误。确认rcoder主程序已按配置启动Pingora服务。
+- 端口提取失败：若请求路径不符合/proxy/{port}格式，将回退到默认后端端口。检查客户端是否使用正确的路径格式。
+- 后端未发现：Pingora在首次遇到端口时会动态添加默认主机；若后端主机不可达，健康检查会标记为不健康。检查后端服务状态与网络连通性。
+- 重定向链路：代理处理器返回307临时重定向，客户端需跟随重定向并保持连接（尤其WebSocket场景）。
+
+章节来源
+- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L31-L114)
+- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L31-L114)
+- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L300-L333)
+
+## 结论
+RCoder的反向代理API通过Axum路由与Pingora代理实现解耦：路由层负责接入与状态查询，Pingora负责高性能转发与负载均衡。/proxy/{port}/{path}端点采用临时重定向到Pingora监听端口的方式，使客户端透明地访问任意端口的后端服务。结合动态后端与健康检查，系统具备良好的弹性与可观测性。
+
+## 附录
+
+### curl示例
+以下示例展示如何通过/proxy接口访问不同后端服务（请将localhost替换为实际部署地址与端口）：
+- 访问默认后端健康检查
+  - curl "http://localhost:3000/proxy/8080/health"
+- 访问特定端口的API
+  - curl "http://localhost:3000/proxy/3000/api/users"
+- 访问代理状态
+  - curl "http://localhost:3000/proxy/status"
+- 访问代理统计
+  - curl "http://localhost:3000/proxy/stats"
+- 访问代理配置
+  - curl "http://localhost:3000/proxy/config"
+
+章节来源
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L173-L193)
+- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L173-L193)
+
+### 与Pingora集成要点
+- 启动方式：rcoder主程序创建PingoraServerManager并启动服务器，监听配置中的listen_port。
+- 服务注入：将Pingora服务引用注入AppState，代理处理器可读取配置与指标。
+- 路由规则：Pingora内部处理/proxy/{port}与/proxy/{port}/{path}，移除前缀并重写URI，转发到后端。
+
+章节来源
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
+- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L66)
+- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L246-L354)
--- a/qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/聊天接口.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/聊天接口.md
@@ -0,0 +1,290 @@
+# 聊天接口
+
+<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)