添加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/核心模块架构/HTTP
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/核心模块架构/HTTP
@@ -0,0 +1,312 @@
+# 路由配置
+
+<cite>
+**本文档引用的文件**
+- [router.rs](file://crates/agent_runner/src/router.rs)
+- [main.rs](file://crates/agent_runner/src/main.rs)
+- [handler/mod.rs](file://crates/agent_runner/src/handler/mod.rs)
+- [middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
+- [health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs)
+- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
+- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
+- [proxy_api.rs](file://crates/agent_runner/src/handler/proxy_api.rs)
+- [router.rs](file://crates/rcoder/src/router.rs)
+</cite>
+
+## 目录
+1. [项目结构](#项目结构)
+2. [核心路由注册机制](#核心路由注册机制)
+3. [模块化路由组织结构](#模块化路由组织结构)
+4. [全局中间件应用](#全局中间件应用)
+5. [路由层级划分逻辑](#路由层级划分逻辑)
+6. [动态路由参数处理](#动态路由参数处理)
+7. [错误传播模式](#错误传播模式)
+8. [API端点详细说明](#api端点详细说明)
+9. [OpenAPI文档集成](#openapi文档集成)
+
+## 项目结构
+
+本项目采用模块化设计，HTTP API路由配置主要分布在`crates/agent_runner`和`crates/rcoder`两个核心模块中。路由配置的核心文件位于`src/router.rs`，通过Axum框架实现路由注册。处理器函数分布在`src/handler`目录下，按功能模块组织。中间件定义在`src/middleware`目录中，用于处理全局请求拦截和日志追踪。
+
+```mermaid
+graph TD
+A[HTTP API路由系统] --> B[路由注册]
+A --> C[处理器模块]
+A --> D[中间件]
+A --> E[应用状态]
+B --> F[router.rs]
+C --> G[handler/mod.rs]
+D --> H[middleware/tracing_middleware.rs]
+E --> I[AppState结构]
+F --> J[create_router函数]
+G --> K[health_handler]
+G --> L[chat_handler]
+G --> M[agent_session_notification]
+G --> N[proxy_api]
+H --> O[tracing_middleware_handler]
+I --> P[sessions]
+I --> Q[config]
+I --> R[local_task_sender]
+I --> S[pingora_service]
+```
+
+**图源**
+- [router.rs](file://crates/agent_runner/src/router.rs)
+- [handler/mod.rs](file://crates/agent_runner/src/handler/mod.rs)
+- [middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
+
+**节源**
+- [router.rs](file://crates/agent_runner/src/router.rs)
+- [main.rs](file://crates/agent_runner/src/main.rs)
+
+## 核心路由注册机制
+
+基于Axum框架的路由注册机制通过`create_router`函数实现，该函数接收应用状态并返回配置好的Router实例。路由注册采用链式调用方式，将不同功能的路由分组后合并到主路由中。
+
+路由注册的核心流程如下：
+1. 创建API路由组，包含健康检查、聊天、代理会话通知等核心接口
+2. 创建代理API路由组，提供Pingora反向代理相关的状态查询接口
+3. 将各路由组合并到主路由中
+4. 集成Swagger UI路由，提供API文档界面
+
+```mermaid
+sequenceDiagram
+participant App as 应用启动
+participant Router as 路由创建
+participant API as API路由组
+participant Proxy as 代理API路由组
+participant Swagger as Swagger UI
+App->>Router : create_router(state)
+Router->>API : 创建API路由组
+API->>API : route("/health", get(health_check))
+API->>API : route("/chat", post(handle_chat))
+API->>API : route("/agent/progress/{session_id}", get(agent_session_notification))
+API->>Router : 返回API路由组
+Router->>Proxy : 创建代理API路由组
+Proxy->>Proxy : route("/proxy/status", get(proxy_status))
+Proxy->>Proxy : route("/proxy/stats", get(proxy_stats))
+Proxy->>Router : 返回代理API路由组
+Router->>Swagger : 创建Swagger UI路由
+Swagger->>Router : 返回Swagger路由
+Router->>App : 合并所有路由并返回
+```
+
+**图源**
+- [router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
+
+**节源**
+- [router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
+
+## 模块化路由组织结构
+
+路由处理器采用模块化组织结构，通过`handler/mod.rs`文件统一导出所有处理器模块。这种设计实现了关注点分离，使代码结构更加清晰和易于维护。
+
+```mermaid
+graph TD
+A[handler/mod.rs] --> B[agent_cancel_handler]
+A --> C[agent_session_notification]
+A --> D[chat_handler]
+A --> E[agent_status_handler]
+A --> F[health_handler]
+A --> G[proxy_api]
+A --> H[proxy_handler_api]
+B --> I[agent_session_cancel]
+C --> J[agent_session_notification]
+D --> K[handle_chat]
+E --> L[agent_status]
+F --> M[health_check]
+G --> N[proxy_status]
+G --> O[proxy_stats]
+G --> P[proxy_config]
+G --> Q[proxy_to_port]
+G --> R[proxy_to_port_with_path]
+G --> S[proxy_with_query_params]
+```
+
+**图源**
+- [handler/mod.rs](file://crates/agent_runner/src/handler/mod.rs)
+
+**节源**
+- [handler/mod.rs](file://crates/agent_runner/src/handler/mod.rs)
+
+## 全局中间件应用
+
+通过Layer堆叠机制应用全局中间件，实现请求的统一处理。主要中间件包括追踪中间件，用于记录请求日志和生成trace_id。
+
+```mermaid
+graph TD
+A[HTTP请求] --> B[Tracing中间件]
+B --> C[提取或生成trace_id]
+C --> D[创建日志span]
+D --> E[记录请求开始]
+E --> F[执行后续处理器]
+F --> G[记录响应完成]
+G --> H[返回响应]
+subgraph 中间件处理流程
+C
+D
+E
+F
+G
+end
+```
+
+**图源**
+- [middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
+
+**节源**
+- [middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
+
+## 路由层级划分逻辑
+
+路由系统采用清晰的层级划分逻辑，将公共接口与代理专用接口分离。这种设计提高了系统的可维护性和安全性。
+
+```mermaid
+graph TD
+A[主路由] --> B[API路由组]
+A --> C[代理API路由组]
+A --> D[Swagger UI路由]
+B --> E[公共接口]
+E --> F[/health]
+E --> G[/chat]
+E --> H[/agent/progress/{session_id}]
+E --> I[/agent/session/cancel]
+E --> J[/agent/status/{project_id}]
+C --> K[代理专用接口]
+K --> L[/proxy/status]
+K --> M[/proxy/stats]
+K --> N[/proxy/config]
+K --> O[/proxy/{port}]
+K --> P[/proxy/{port}/{*path}]
+```
+
+**图源**
+- [router.rs](file://crates/agent_runner/src/router.rs#L42-L69)
+
+**节源**
+- [router.rs](file://crates/agent_runner/src/router.rs#L42-L69)
+
+## 动态路由参数处理
+
+动态路由参数通过Axum的路径参数机制处理，支持路径参数和通配符参数。系统能够正确解析和验证动态路由参数。
+
+```mermaid
+flowchart TD
+A[接收到请求] --> B{路径匹配}
+B --> |/agent/progress/{session_id}| C[提取session_id]
+B --> |/proxy/{port}| D[提取port]
+B --> |/proxy/{port}/{*path}| E[提取port和path]
+B --> |其他路径| F[返回404]
+C --> G[验证session_id]
+G --> H[调用agent_session_notification]
+D --> I[验证port]
+I --> J[调用proxy_to_port]
+E --> K[验证port和path]
+K --> L[调用proxy_to_port_with_path]
+```
+
+**图源**
+- [router.rs](file://crates/agent_runner/src/router.rs#L46-L47)
+- [router.rs](file://crates/agent_runner/src/router.rs#L59-L63)
+
+**节源**
+- [router.rs](file://crates/agent_runner/src/router.rs#L46-L63)
+
+## 错误传播模式
+
+系统采用统一的错误传播模式，通过Result类型传递错误信息。错误处理遵循以下原则：
+
+1. 处理器函数返回Result类型，包含成功值或错误
+2. 使用AppError类型封装各种错误情况
+3. 错误信息包含错误代码和描述
+4. 通过HttpResult包装器提供一致的响应格式
+
+```mermaid
+stateDiagram-v2
+[*] --> 请求处理
+请求处理 --> 验证输入
+验证输入 --> |有效| 业务逻辑
+验证输入 --> |无效| 返回验证错误
+业务逻辑 --> |成功| 构建成功响应
+业务逻辑 --> |失败| 构建错误响应
+构建成功响应 --> 返回响应
+构建错误响应 --> 返回响应
+返回响应 --> [*]
+```
+
+**图源**
+- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L179)
+- [model.rs](file://crates/agent_runner/src/model.rs)
+
+**节源**
+- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L179)
+
+## API端点详细说明
+
+### 健康检查端点
+- 路径: `/health`
+- 方法: GET
+- 功能: 检查服务的健康状态
+- 响应: 返回服务状态、时间戳和服务名称
+
+### 聊天端点
+- 路径: `/chat`
+- 方法: POST
+- 功能: 发送聊天消息并获取AI响应
+- 请求体: 包含prompt、project_id、session_id等信息
+- 响应: 返回项目ID和会话ID
+
+### 代理会话通知端点
+- 路径: `/agent/progress/{session_id}`
+- 方法: GET
+- 功能: 通过SSE协议实时推送AI代理执行进度
+- 参数: session_id
+- 响应: SSE流，包含各种类型的消息事件
+
+### 代理API端点
+- 路径: `/proxy/status`, `/proxy/stats`, `/proxy/config`等
+- 方法: GET
+- 功能: 提供Pingora反向代理的状态、统计和配置信息
+- 参数: port, path等动态参数
+
+**节源**
+- [health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs)
+- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
+- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
+- [proxy_api.rs](file://crates/agent_runner/src/handler/proxy_api.rs)
+
+## OpenAPI文档集成
+
+系统集成了OpenAPI文档功能，通过utoipa和utoipa_swagger_ui crate提供API文档界面。文档包含所有API端点的详细描述、请求参数、响应格式和示例。
+
+```mermaid
+graph TD
+A[OpenAPI文档] --> B[API端点]
+A --> C[组件定义]
+A --> D[标签]
+A --> E[信息]
+B --> F[health_check]
+B --> G[handle_chat]
+B --> H[agent_session_notification]
+B --> I[proxy_status]
+B --> J[proxy_stats]
+B --> K[proxy_config]
+C --> L[请求体]
+C --> M[响应体]
+C --> N[参数]
+D --> O[system]
+D --> P[chat]
+D --> Q[agent]
+D --> R[proxy]
+E --> S[描述]
+E --> T[标题]
+E --> U[版本]
+E --> V[许可证]
+E --> W[联系人]
+```
+
+**图源**
+- [router.rs](file://crates/agent_runner/src/router.rs#L73-L208)
+
+**节源**
+- [router.rs](file://crates/agent_runner/src/router.rs#L73-L208)