添加qiming-rcoder模块
This commit is contained in:
Codex
@@ -0,0 +1,279 @@
|
||||
# HTTP API架构
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.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)
|
||||
- [health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs)
|
||||
- [agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs)
|
||||
- [proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs)
|
||||
- [proxy_api.rs](file://crates/agent_runner/src/handler/proxy_api.rs)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs)
|
||||
- [lib.rs](file://crates/agent_runner/src/lib.rs)
|
||||
- [model.rs](file://crates/agent_runner/src/model.rs)
|
||||
- [mod.rs](file://crates/agent_runner/src/handler/mod.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概述](#架构概述)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
RCoder AI服务API是一个基于ACP（Agent Client Protocol）的AI驱动开发平台，提供完整的AI代理集成解决方案。该系统采用Rust语言构建，基于Axum框架实现高性能HTTP API服务，通过Server-Sent Events（SSE）协议提供实时通信能力。系统支持多种AI代理类型（Codex、Claude、Proxy），并集成了基于Cloudflare Pingora的高性能反向代理服务。API设计遵循RESTful原则，提供清晰的端点划分和完整的OpenAPI文档支持。
|
||||
|
||||
## 项目结构
|
||||
系统采用Rust工作区（workspace）结构，核心功能模块化组织。HTTP API服务主要由`agent_runner` crate实现，该模块负责处理所有HTTP请求、路由分发和状态管理。系统通过清晰的目录结构分离关注点，包括处理器（handler）、中间件（middleware）、代理代理（proxy_agent）、服务（service）和工具（utils）等模块。这种结构化设计提高了代码的可维护性和可扩展性，同时便于团队协作开发。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "crates"
|
||||
subgraph "agent_runner"
|
||||
H[handler]
|
||||
M[middleware]
|
||||
PA[proxy_agent]
|
||||
S[service]
|
||||
U[utils]
|
||||
R[router]
|
||||
C[config]
|
||||
end
|
||||
subgraph "shared_types"
|
||||
ST[共享类型定义]
|
||||
end
|
||||
subgraph "pingora-proxy"
|
||||
PP[Pingora代理服务]
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs)
|
||||
|
||||
**章节来源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs)
|
||||
|
||||
## 核心组件
|
||||
系统的核心组件包括基于Axum框架的HTTP服务器、基于DashMap的会话状态管理、基于MPMC通道的异步任务处理机制，以及集成的OpenTelemetry遥测系统。`AppState`结构体作为全局应用状态，封装了会话映射、配置信息、任务发送器和Pingora服务引用等关键数据。系统通过`LocalSet`在独立线程中运行非Send的代理工作器，确保了不同类型代理的兼容性。OpenAPI文档通过utoipa自动生成，提供完整的API描述和交互式Swagger UI界面。
|
||||
|
||||
**章节来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
|
||||
## 架构概述
|
||||
系统采用分层架构设计，从下到上分别为基础设施层、服务层、应用层和接口层。基础设施层提供日志、遥测和配置管理；服务层封装核心业务逻辑；应用层处理HTTP请求和响应；接口层暴露REST API和SSE流。系统通过清晰的组件分离和依赖注入，实现了高内聚低耦合的设计目标。Pingora反向代理作为独立的服务组件，与主HTTP服务器并行运行，提供高性能的端口路由和负载均衡能力。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "接口层"
|
||||
A[REST API]
|
||||
B[SSE流]
|
||||
C[Swagger UI]
|
||||
end
|
||||
subgraph "应用层"
|
||||
D[Axum服务器]
|
||||
E[路由分发]
|
||||
F[中间件链]
|
||||
end
|
||||
subgraph "服务层"
|
||||
G[代理管理]
|
||||
H[会话缓存]
|
||||
I[任务调度]
|
||||
end
|
||||
subgraph "基础设施层"
|
||||
J[配置管理]
|
||||
K[日志系统]
|
||||
L[遥测系统]
|
||||
end
|
||||
A --> D
|
||||
B --> D
|
||||
C --> D
|
||||
D --> E
|
||||
E --> F
|
||||
F --> G
|
||||
F --> H
|
||||
F --> I
|
||||
G --> J
|
||||
H --> K
|
||||
I --> L
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 路由设计分析
|
||||
系统基于Axum框架实现RESTful路由设计，通过模块化方式组织API端点。路由配置在`router.rs`文件中集中管理，使用`Router::new()`创建根路由器，并通过`merge()`方法合并多个子路由。API端点按功能分组，包括系统健康检查、聊天交互、代理状态管理和反向代理接口。每个端点通过`route()`方法绑定到相应的处理器函数，并使用`with_state()`方法注入共享的应用状态。OpenAPI文档通过`utoipa`属性宏自动生成，确保API文档与实现保持同步。
|
||||
|
||||
**章节来源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L40-L69)
|
||||
|
||||
#### 路由结构图
|
||||
```mermaid
|
||||
graph TD
|
||||
R[根路由器] --> API[API路由]
|
||||
R --> Proxy[代理API路由]
|
||||
R --> Swagger[Swagger UI]
|
||||
API --> Health[/health]
|
||||
API --> Chat[/chat]
|
||||
API --> Progress[/agent/progress/{session_id}]
|
||||
API --> Cancel[/agent/session/cancel]
|
||||
API --> Status[/agent/status/{project_id}]
|
||||
Proxy --> ProxyStatus[/proxy/status]
|
||||
Proxy --> ProxyStats[/proxy/stats]
|
||||
Proxy --> ProxyConfig[/proxy/config]
|
||||
Proxy --> ProxyPort[/proxy/{port}]
|
||||
Proxy --> ProxyPath[/proxy/{port}/{*path}]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L40-L69)
|
||||
|
||||
### 请求处理流程分析
|
||||
HTTP请求处理流程始于TCP监听器，通过Axum服务器接收请求并应用中间件链。`tracing_middleware`作为核心中间件，负责请求追踪、日志记录和trace_id管理。请求经过路由匹配后，分发到相应的处理器函数。处理器函数从共享状态中获取必要信息，执行业务逻辑，并通过MPMC通道与代理工作器通信。响应结果通过统一的`HttpResult`格式返回，确保API响应的一致性。错误处理通过`AppError`枚举和`IntoResponse` trait实现，提供结构化的错误信息。
|
||||
|
||||
**章节来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L130-L171)
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L72-L130)
|
||||
|
||||
#### 请求处理序列图
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Server as "Axum服务器"
|
||||
participant Middleware as "tracing_middleware"
|
||||
participant Handler as "处理器"
|
||||
participant Agent as "代理工作器"
|
||||
Client->>Server : HTTP请求
|
||||
Server->>Middleware : 应用中间件
|
||||
Middleware->>Middleware : 生成trace_id
|
||||
Middleware->>Middleware : 创建日志span
|
||||
Middleware->>Handler : 调用处理器
|
||||
Handler->>Handler : 验证请求参数
|
||||
Handler->>Handler : 构建ChatPrompt
|
||||
Handler->>Agent : 发送任务请求
|
||||
Agent->>Handler : 返回响应
|
||||
Handler->>Middleware : 返回结果
|
||||
Middleware->>Middleware : 记录响应信息
|
||||
Middleware->>Client : HTTP响应
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L130-L171)
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L72-L130)
|
||||
|
||||
### 中间件链分析
|
||||
`tracing_middleware`是系统的核心中间件，负责实现分布式追踪和结构化日志记录。该中间件通过`info_span!`宏创建请求级别的追踪span，包含方法、URI、trace_id等关键信息。trace_id的生成遵循优先级顺序：首先尝试从请求头（x-trace-id、x-request-id等）提取，若不存在则生成新的UUID。中间件使用`instrument`方法将整个请求处理过程包装在span中，确保所有日志都关联到正确的trace上下文。OpenTelemetry集成确保trace信息可以在分布式系统中传播，便于跨服务的性能分析和故障排查。
|
||||
|
||||
**章节来源**
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L138)
|
||||
|
||||
#### 中间件处理流程图
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([请求进入]) --> Extract["提取trace_id<br/>从请求头"]
|
||||
Extract --> HasTraceId{存在trace_id?}
|
||||
HasTraceId --> |是| UseExisting["使用现有trace_id"]
|
||||
HasTraceId --> |否| Generate["生成新trace_id"]
|
||||
Generate --> UseExisting
|
||||
UseExisting --> CreateSpan["创建tracing span"]
|
||||
CreateSpan --> Execute["执行请求处理"]
|
||||
Execute --> LogResponse["记录响应信息"]
|
||||
LogResponse --> End([响应返回])
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L138)
|
||||
|
||||
### 处理器模块分析
|
||||
处理器模块采用模块化设计，每个API端点对应独立的处理器文件。`mod.rs`文件作为公共接口，重新导出所有处理器函数。`chat_handler`处理聊天请求，验证输入参数，管理项目工作目录，并通过MPMC通道与代理工作器通信。`agent_session_notification`实现SSE流，为前端提供实时的代理执行进度更新。`health_handler`提供基本的健康检查功能，返回服务状态和时间戳。`agent_status_handler`查询代理状态，返回详细的会话信息和模型配置。所有处理器函数使用`utoipa::path`宏注解，自动生成OpenAPI文档。
|
||||
|
||||
**章节来源**
|
||||
- [mod.rs](file://crates/agent_runner/src/handler/mod.rs#L1-L17)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L320)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L483)
|
||||
- [health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L29-L35)
|
||||
- [agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L121)
|
||||
|
||||
#### 处理器模块类图
|
||||
```mermaid
|
||||
classDiagram
|
||||
class ChatHandler {
|
||||
+handle_chat(state : Arc~AppState~, request : Json~ChatRequest~) Result~HttpResult~ChatResponse~~, AppError~
|
||||
}
|
||||
class NotificationHandler {
|
||||
+agent_session_notification(params : Path~SessionNotificationParams~) Result~Sse~Stream~, AppError~
|
||||
}
|
||||
class HealthHandler {
|
||||
+health_check() Json~HealthResponse~
|
||||
}
|
||||
class StatusHandler {
|
||||
+agent_status(Path~project_id~) Result~HttpResult~AgentStatusResponse~~, AppError~
|
||||
}
|
||||
ChatHandler --> AppState : "使用"
|
||||
NotificationHandler --> AppState : "使用"
|
||||
StatusHandler --> AppState : "使用"
|
||||
AppState --> DashMap : "包含"
|
||||
AppState --> AppConfig : "包含"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L320)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L483)
|
||||
- [health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L29-L35)
|
||||
- [agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L121)
|
||||
|
||||
## 依赖分析
|
||||
系统依赖关系清晰，核心依赖包括Axum（HTTP框架）、Tokio（异步运行时）、Serde（序列化）、Tracing（日志和追踪）和Utoipa（OpenAPI文档）。`agent_runner` crate依赖`shared_types` crate获取共享的数据结构和枚举类型，依赖`pingora-proxy` crate实现反向代理功能。配置管理通过Clap实现命令行参数解析，通过Serde YAML实现配置文件加载。日志系统使用Tracing Subscriber，支持文件和控制台双输出，文件按天滚动并保留最近5天的日志。遥测系统集成OpenTelemetry，支持trace上下文传播和分布式追踪。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[agent_runner] --> B[axum]
|
||||
A --> C[tokio]
|
||||
A --> D[serde]
|
||||
A --> E[tracing]
|
||||
A --> F[utoipa]
|
||||
A --> G[shared_types]
|
||||
A --> H[pingora-proxy]
|
||||
A --> I[clap]
|
||||
A --> J[serde_yaml]
|
||||
B --> K[tower]
|
||||
C --> L[tokio-util]
|
||||
E --> M[tracing-subscriber]
|
||||
E --> N[tracing-opentelemetry]
|
||||
M --> O[tracing-appender]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml#L1-L79)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
|
||||
**章节来源**
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml#L1-L79)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
|
||||
## 性能考虑
|
||||
系统在性能方面进行了多项优化。会话状态使用`DashMap`实现，提供高性能的并发访问能力。异步任务通过MPMC通道传递，避免了阻塞操作。SSE流使用`async-stream`库实现，支持高效的异步流处理。日志系统采用非阻塞的`tracing-appender`，确保日志写入不会影响主请求处理流程。Pingora反向代理基于Rust异步I/O构建，提供高性能的代理能力。系统通过`LocalSet`在独立线程中运行代理工作器，避免了Send约束对性能的影响。配置加载采用优先级策略，确保配置解析的高效性。
|
||||
|
||||
## 故障排除指南
|
||||
常见问题包括代理并发请求限制、会话状态不一致和配置加载失败。代理并发请求限制通过在`handle_chat`处理器中检查`PROJECT_AND_AGENT_INFO_MAP`实现，当代理处于活动状态时拒绝新的聊天请求。会话状态不一致问题通过在每次请求时清理旧会话解决，确保状态的纯净性。配置加载失败时系统会自动创建默认配置文件，并提供详细的错误日志。SSE连接问题可以通过检查`SESSION_CACHE`和`create_new_connection`方法的实现来诊断。日志文件位于`logs`目录，按天滚动，便于问题追溯。
|
||||
|
||||
**章节来源**
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L211-L223)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L364-L369)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L117-L131)
|
||||
|
||||
## 结论
|
||||
RCoder AI服务API架构设计合理，采用现代化的Rust技术栈，实现了高性能、高可用的HTTP服务。系统通过清晰的模块划分和依赖管理，提供了良好的可维护性和可扩展性。Axum框架的使用简化了路由和中间件的实现，Tracing和OpenTelemetry的集成提供了强大的可观测性。SSE流的实现为前端提供了实时的代理执行进度更新，增强了用户体验。整体架构充分考虑了性能、可靠性和可维护性，为AI驱动的开发平台提供了坚实的基础。
|
||||
@@ -0,0 +1,296 @@
|
||||
# 中间件链
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
- [crates/agent_runner/src/handler/mod.rs](file://crates/agent_runner/src/handler/mod.rs)
|
||||
- [crates/rcoder/src/handler/mod.rs](file://crates/rcoder/src/handler/mod.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 引言
|
||||
本文件聚焦于HTTP API中间件链的设计与实现，重点阐述tracing_middleware的作用机制与在Tower Layer模式下的可复用性，说明如何利用该中间件实现请求级别的上下文追踪、日志记录与性能监控；解释OpenTelemetry集成方式，包括trace ID生成、span生命周期管理以及与外部观测系统的对接；梳理中间件执行顺序及其对请求/响应流的影响；并提供自定义中间件扩展的实践建议及在调试与性能分析中的价值。
|
||||
|
||||
## 项目结构
|
||||
本仓库采用多crate工作区组织，其中与HTTP中间件链最相关的两个服务分别为agent_runner与rcoder。两者均内置了相同的tracing_middleware实现，且在各自main中初始化了Tracing与OpenTelemetry传播器，随后在路由上叠加中间件层以形成中间件链。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "agent_runner"
|
||||
ARMain["main.rs<br/>初始化遥测与传播器"]
|
||||
ARRouter["router.rs<br/>创建Axum路由"]
|
||||
ARMW["middleware/tracing_middleware.rs<br/>Tracing中间件"]
|
||||
end
|
||||
subgraph "rcoder"
|
||||
RMain["main.rs<br/>初始化遥测与传播器"]
|
||||
RRouter["router.rs<br/>创建Axum路由"]
|
||||
RMW["middleware/tracing_middleware.rs<br/>Tracing中间件"]
|
||||
end
|
||||
ARMain --> ARRouter
|
||||
ARRouter --> ARMW
|
||||
RMain --> RRouter
|
||||
RRouter --> RMW
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L132-L139)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L132-L139)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
|
||||
## 核心组件
|
||||
- Tracing中间件：负责为每个HTTP请求生成或提取trace_id，创建请求span，记录请求/响应信息，并将trace_id注入到请求扩展中，供后续处理器使用。
|
||||
- 遥测初始化：在main中设置全局TextMapPropagator为TraceContext，初始化tracing订阅器，输出到文件与控制台。
|
||||
- 路由与中间件叠加：通过add_tracing_layer将中间件作为Tower Layer叠加到Axum Router上，形成中间件链。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L139)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L139)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
|
||||
## 架构总览
|
||||
下图展示了请求在中间件链中的流转过程，以及与OpenTelemetry的集成点。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Router as "Axum Router"
|
||||
participant MW as "Tracing中间件"
|
||||
participant Handler as "业务处理器"
|
||||
participant Otel as "OpenTelemetry传播器"
|
||||
Client->>Router : "HTTP请求"
|
||||
Router->>MW : "进入中间件链"
|
||||
MW->>MW : "提取/生成trace_id"
|
||||
MW->>Otel : "设置TraceContext传播器"
|
||||
MW->>MW : "创建请求span并记录开始"
|
||||
MW->>Handler : "next.run(req)"
|
||||
Handler-->>MW : "返回响应"
|
||||
MW->>MW : "记录响应状态"
|
||||
MW-->>Router : "返回响应"
|
||||
Router-->>Client : "HTTP响应"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L212-L225)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L302-L314)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### Tracing中间件类图
|
||||
Tracing中间件以函数式中间件形式实现，提供add_tracing_layer用于将中间件叠加到Axum Router上；内部通过extract_trace_id_from_headers与generate_trace_id实现trace_id策略；通过info_span与tracing::info记录请求/响应事件；通过req.extensions_mut插入trace_id供后续处理器使用。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class TracingMiddleware {
|
||||
+new() TracingMiddleware
|
||||
}
|
||||
class TracingFunctions {
|
||||
+generate_trace_id() String
|
||||
+extract_trace_id_from_headers(headers) Option~String~
|
||||
+tracing_middleware_handler(req, next) Response
|
||||
+add_tracing_layer(router) Router
|
||||
}
|
||||
TracingMiddleware --> TracingFunctions : "封装函数式中间件逻辑"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L12-L139)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L12-L139)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L139)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L139)
|
||||
|
||||
### 中间件处理流程（序列图）
|
||||
该序列图展示一次请求从进入中间件到返回响应的完整流程，包括trace_id策略、span创建与日志记录。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as "客户端"
|
||||
participant R as "Axum Router"
|
||||
participant T as "Tracing中间件"
|
||||
participant N as "Next(下游处理器)"
|
||||
C->>R : "发起请求"
|
||||
R->>T : "进入中间件"
|
||||
T->>T : "尝试从请求头提取trace_id"
|
||||
alt "未提取到"
|
||||
T->>T : "生成新的trace_id"
|
||||
end
|
||||
T->>T : "创建请求span并记录开始"
|
||||
T->>N : "next.run(req)"
|
||||
N-->>T : "返回响应"
|
||||
T->>T : "记录响应状态"
|
||||
T-->>R : "返回响应"
|
||||
R-->>C : "返回HTTP响应"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
|
||||
### 中间件执行顺序与对请求/响应流的影响
|
||||
- 叠加位置：add_tracing_layer将中间件作为顶层Layer叠加到Router上，因此它会最先拦截请求，最后才返回响应。
|
||||
- 对请求的影响：中间件在进入下游处理器前记录请求开始、注入trace_id到请求扩展；对上游调用方透明，仅增加少量开销。
|
||||
- 对响应的影响：中间件在下游返回后记录响应状态，便于统一观测与排障。
|
||||
- 与OpenTelemetry的关系：main中设置了TraceContextPropagator，使trace_id在分布式链路中可被传播；中间件通过tracing_span与tracing日志记录，形成可观测闭环。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L132-L139)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L132-L139)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L212-L225)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L302-L314)
|
||||
|
||||
### OpenTelemetry集成与span生命周期
|
||||
- TraceContext传播器：在main中设置全局TextMapPropagator为TraceContext，确保trace_id在跨进程/服务间传播。
|
||||
- span创建与记录：中间件创建“http_request”与“http_request_processing”两类span，分别用于请求级追踪与处理阶段记录。
|
||||
- 日志与span关联：通过tracing::info与info_span，将trace_id写入日志字段，便于与span关联检索。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L212-L225)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L302-L314)
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L85-L124)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L85-L124)
|
||||
|
||||
### 外部观测系统对接
|
||||
- 日志输出：main中配置tracing_subscriber输出到文件与控制台，日志为JSON格式，便于后续导入ELK/Promtail等系统。
|
||||
- trace ID与span：通过中间件与传播器，trace_id贯穿请求全链路，可与Jaeger/Tempo等分布式追踪系统对接。
|
||||
- 指标采集：rcoder还集成了Pingora代理，可通过其stats接口获取真实后端指标，结合日志与trace可形成端到端观测。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L190-L210)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L283-L301)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L68-L84)
|
||||
|
||||
### 自定义中间件扩展建议
|
||||
- 设计原则
|
||||
- 保持无状态与纯函数式：中间件应尽量避免持有可变共享状态，减少竞态与副作用。
|
||||
- 明确职责边界：每个中间件专注单一职责（鉴权、限流、日志、追踪等），通过Tower Layer组合。
|
||||
- 顺序敏感性：将更通用的中间件置于外层，将更具体的中间件置于内层；例如鉴权/限流在外层，业务处理器在内层。
|
||||
- 实现要点
|
||||
- 使用axum::middleware::from_fn或实现tower::Layer，将中间件以Layer形式叠加到Router。
|
||||
- 在进入下游前记录关键信息（如trace_id、用户标识、请求参数摘要），在返回后记录响应状态与耗时。
|
||||
- 通过req.extensions_mut传递上下文数据，避免全局状态污染。
|
||||
- 调试与性能分析价值
|
||||
- trace_id串联：便于跨服务定位问题，快速回溯请求路径。
|
||||
- 统一日志字段：统一的trace_id与span字段，便于日志聚合与检索。
|
||||
- 性能瓶颈定位：结合响应状态与日志时间戳，识别慢请求与异常路径。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L132-L139)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L132-L139)
|
||||
|
||||
## 依赖关系分析
|
||||
- 依赖组件
|
||||
- axum：HTTP框架，提供Router、Request、Response、Next等。
|
||||
- tower/tower-http：中间件与服务抽象，支持Layer叠加。
|
||||
- tracing/tracing-opentelemetry：日志与OpenTelemetry集成。
|
||||
- opentelemetry/opentelemetry_sdk：SDK与传播器。
|
||||
- uuid：生成trace_id。
|
||||
- 关键依赖关系
|
||||
- main中设置TraceContextPropagator，为后续中间件与OpenTelemetry提供传播基础。
|
||||
- 中间件通过tracing与tracing_opentelemetry记录span与日志。
|
||||
- Router通过add_tracing_layer叠加中间件，形成Tower Layer链。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Cargo["Cargo.toml 依赖声明"] --> Axum["axum"]
|
||||
Cargo --> Tower["tower / tower-http"]
|
||||
Cargo --> Tracing["tracing / tracing-opentelemetry"]
|
||||
Cargo --> Otel["opentelemetry / opentelemetry_sdk"]
|
||||
Cargo --> Uuid["uuid"]
|
||||
ARMain["agent_runner/main.rs"] --> Otel
|
||||
RMain["rcoder/main.rs"] --> Otel
|
||||
ARMW["agent_runner/tracing_middleware.rs"] --> Tracing
|
||||
RMW["rcoder/tracing_middleware.rs"] --> Tracing
|
||||
ARRouter["agent_runner/router.rs"] --> Axum
|
||||
RRouter["rcoder/router.rs"] --> Axum
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [Cargo.toml](file://Cargo.toml#L59-L105)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L212-L225)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L302-L314)
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L139)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L139)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
|
||||
章节来源
|
||||
- [Cargo.toml](file://Cargo.toml#L59-L105)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L212-L225)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L302-L314)
|
||||
|
||||
## 性能考量
|
||||
- 中间件开销：中间件在请求进入与返回时各做一次日志记录与span创建，开销极低，适合在生产环境长期开启。
|
||||
- trace_id生成：使用UUID v4简单格式，长度固定，生成成本低。
|
||||
- 日志落盘：按天滚动与保留策略，避免日志膨胀；JSON格式利于外部系统解析。
|
||||
- 观测成本：trace_id与span字段统一，便于日志聚合与检索，但需关注日志量与存储成本。
|
||||
|
||||
## 故障排查指南
|
||||
- trace_id缺失
|
||||
- 检查请求头是否携带trace_id或x-request-id等常见头；若无则中间件会自动生成。
|
||||
- 确认main中已设置TraceContextPropagator，确保trace_id在跨服务传播。
|
||||
- 日志未输出或格式异常
|
||||
- 检查tracing_subscriber初始化与EnvFilter配置；确认文件appender路径与权限。
|
||||
- 响应异常
|
||||
- 通过中间件记录的trace_id在日志中定位具体请求，结合span层级排查下游处理器异常。
|
||||
- 与外部观测系统对接
|
||||
- 确保OpenTelemetry SDK与Exporter配置正确；trace_id字段与span字段一致，便于检索。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L49-L69)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L49-L69)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L190-L210)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L283-L301)
|
||||
|
||||
## 结论
|
||||
本项目通过Tower Layer模式将Tracing中间件以可复用的方式叠加到Axum Router上，实现了请求级上下文追踪、统一日志记录与性能监控。OpenTelemetry传播器在main中初始化，配合中间件的span与日志，形成了从请求入口到响应返回的完整可观测闭环。该设计易于扩展，可按需叠加更多中间件以满足安全、限流、审计等需求，并在调试与性能分析中具有显著价值。
|
||||
|
||||
## 附录
|
||||
- 中间件叠加位置
|
||||
- agent_runner：在路由创建后通过add_tracing_layer叠加。
|
||||
- rcoder：同样在路由创建后通过add_tracing_layer叠加。
|
||||
- 路由与处理器
|
||||
- 两个服务的router.rs均定义了API路由与代理路由，并通过with_state注入应用状态。
|
||||
- Handler模块
|
||||
- 两个服务的handler/mod.rs导出了各自的处理器模块，供路由绑定。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L132-L139)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L132-L139)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [crates/agent_runner/src/handler/mod.rs](file://crates/agent_runner/src/handler/mod.rs#L1-L17)
|
||||
- [crates/rcoder/src/handler/mod.rs](file://crates/rcoder/src/handler/mod.rs#L1-L19)
|
||||
@@ -0,0 +1,334 @@
|
||||
# 请求处理流程
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.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)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
本文件深入解析 RCoder Agent Runner 服务的 HTTP API 请求处理生命周期，重点覆盖以下方面：
|
||||
- 从请求进入路由到最终响应返回的完整链路
|
||||
- chat_handler、agent_status_handler、agent_session_notification、agent_cancel_handler 等核心处理器的实现逻辑
|
||||
- 请求体解析、服务调用（container_manager 或 agent_runner）、响应构造的细节
|
||||
- SSE 流式响应在进度通知中的应用机制
|
||||
- 典型请求处理链路的时序图，展示数据在 handler、service 与 proxy_agent 之间的流转
|
||||
- 错误处理模式与状态码映射策略
|
||||
|
||||
## 项目结构
|
||||
Agent Runner 采用模块化组织，核心模块包括：
|
||||
- handler：HTTP 路由与处理器
|
||||
- proxy_agent：ACPI 协议代理与会话管理
|
||||
- service：会话缓存与消息推送
|
||||
- model：共享模型与错误类型
|
||||
- router：Axum 路由注册与 OpenAPI 文档
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "HTTP 层"
|
||||
R["Router<br/>注册路由"]
|
||||
CH["chat_handler<br/>POST /chat"]
|
||||
ASH["agent_status_handler<br/>GET /agent/status/{project_id}"]
|
||||
ASN["agent_session_notification<br/>GET /agent/progress/{session_id}<br/>SSE"]
|
||||
AC["agent_cancel_handler<br/>POST /agent/session/cancel"]
|
||||
end
|
||||
subgraph "业务层"
|
||||
PA["proxy_agent<br/>ACPI 代理与会话管理"]
|
||||
SVC["service<br/>会话缓存与消息推送"]
|
||||
MOD["model<br/>共享模型与错误类型"]
|
||||
end
|
||||
R --> CH
|
||||
R --> ASH
|
||||
R --> ASN
|
||||
R --> AC
|
||||
CH --> PA
|
||||
CH --> SVC
|
||||
ASH --> PA
|
||||
ASH --> SVC
|
||||
AC --> PA
|
||||
AC --> SVC
|
||||
PA --> SVC
|
||||
SVC --> ASN
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L321)
|
||||
- [agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L484)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs#L110-L258)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L200)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
|
||||
章节来源
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
|
||||
## 核心组件
|
||||
- 路由与状态
|
||||
- AppState：持有会话映射、本地任务发送器、Pingora 代理服务引用
|
||||
- 路由注册：/health、/chat、/agent/progress/{session_id}、/agent/session/cancel、/agent/status/{project_id}、/proxy/*
|
||||
- 处理器
|
||||
- chat_handler：解析 ChatRequest，校验参数，生成或复用 project_id 与 session_id，构建 ChatPrompt，发送到本地任务通道，等待 oneshot 响应并返回 HttpResult
|
||||
- agent_status_handler：查询 PROJECT_AND_AGENT_INFO_MAP，返回 AgentStatusResponse
|
||||
- agent_session_notification：建立 SSE 连接，推送 UnifiedSessionMessage，支持心跳与取消
|
||||
- agent_cancel_handler：通过 cancel_tx 发送取消通知，清理 SSE 连接与缓存
|
||||
- 代理与会话
|
||||
- proxy_agent：维护 PROJECT_AND_AGENT_INFO_MAP，封装 ACP 连接信息，启动代理服务，转发 session_notification
|
||||
- channel_utils：通用的 Prompt/Cancellation 处理任务，负责状态更新、消息推送与超时保护
|
||||
- session_cache：全局 SESSION_CACHE，RingBuffer 缓冲与实时推送，支持连接级取消令牌与显式关闭
|
||||
|
||||
章节来源
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L25-L70)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L321)
|
||||
- [agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L484)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs#L110-L258)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L200)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
|
||||
## 架构总览
|
||||
整体架构围绕“请求-代理-通知”三段式展开：
|
||||
- 请求阶段：Axum 路由将 HTTP 请求交由对应 handler 解析与校验
|
||||
- 代理阶段：handler 将 ChatPrompt 通过本地任务通道发送给 agent_worker，后者启动 ACPI 代理并发送 Prompt
|
||||
- 通知阶段：代理通过 session_notification 回调，经由 push_session_update 推送到 SESSION_CACHE，SSE 连接从 SESSION_CACHE 拉取并推送至客户端
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as "客户端"
|
||||
participant H as "chat_handler"
|
||||
participant W as "agent_worker"
|
||||
participant P as "ACPI 代理"
|
||||
participant S as "SESSION_CACHE"
|
||||
participant N as "agent_session_notification"
|
||||
C->>H : POST /chat
|
||||
H->>H : 校验参数/生成 project_id/session_id/request_id
|
||||
H->>W : 发送 LocalSetAgentRequest(含 ChatPrompt)
|
||||
W->>P : 启动代理并发送 Prompt
|
||||
P-->>W : 返回 ChatPromptResponse
|
||||
W-->>H : oneshot 响应
|
||||
H-->>C : HttpResult 成功/错误
|
||||
C->>N : GET /agent/progress/{session_id}
|
||||
N->>S : 创建/获取 SessionData 并建立连接
|
||||
P-->>S : session_notification -> 推送 UnifiedSessionMessage
|
||||
S-->>N : 拉取消息并转为SSE事件
|
||||
N-->>C : 事件流推送(progress_start/end/updates/heartbeat)
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L321)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L164-L200)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L92-L230)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L484)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### chat_handler：聊天请求处理
|
||||
- 输入解析：Json<ChatRequest>，包含 prompt、project_id、session_id、attachments、data_source_attachments、model_provider、request_id
|
||||
- 参数校验：prompt 非空校验
|
||||
- 项目与会话管理：
|
||||
- 若未提供 project_id，自动生成 UUID（去除横杠）并创建 ./project_workspace/{project_id}
|
||||
- 若 Agent 正处于 Active 状态，拒绝并发请求
|
||||
- 若提供了 session_id，移除该 session；否则清空该项目下的所有 session
|
||||
- 任务构建：根据 model_provider 自动选择 AgentType，构建 ChatPrompt，并通过 LocalSetAgentRequest.new 生成 oneshot 通道
|
||||
- 任务提交：通过 AppState.local_task_sender 发送 LocalSetAgentRequest
|
||||
- 响应构造：等待 chat_prompt_rx.await，若 error 非空返回 PROMPT001，否则返回 HttpResult.success，包含 project_id、session_id、request_id
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["进入 handle_chat"]) --> Validate["校验 prompt 非空"]
|
||||
Validate --> GenPID{"是否提供 project_id?"}
|
||||
GenPID --> |否| CreateWS["生成 project_id 并创建工作目录"]
|
||||
GenPID --> |是| UsePID["使用请求中的 project_id"]
|
||||
CreateWS --> CheckAgent["检查 Agent 是否 Active"]
|
||||
UsePID --> CheckAgent
|
||||
CheckAgent --> |Active| Reject["返回并发请求错误"]
|
||||
CheckAgent --> |Idle| CleanSess["清理旧 session按 session_id 或按 project_id"]
|
||||
CleanSess --> BuildPrompt["构建 ChatPrompt含 attachments、data_source_attachments、model_provider"]
|
||||
BuildPrompt --> SendTask["发送 LocalSetAgentRequest 到本地任务通道"]
|
||||
SendTask --> AwaitResp{"等待 oneshot 响应"}
|
||||
AwaitResp --> |error 非空| RespErr["返回 PROMPT001 错误"]
|
||||
AwaitResp --> |成功| RespOK["返回 HttpResult.success包含 project_id/session_id/request_id"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L321)
|
||||
|
||||
章节来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L321)
|
||||
|
||||
### agent_status_handler：Agent 状态查询
|
||||
- 路径参数：project_id
|
||||
- 参数校验：project_id 非空
|
||||
- 查询逻辑：从 PROJECT_AND_AGENT_INFO_MAP 获取 Agent 信息
|
||||
- 若存在：返回包含 is_alive=true、session_id、status、last_activity、created_at、model_provider 的 AgentStatusResponse
|
||||
- 若不存在：返回 is_alive=false 的简化响应
|
||||
|
||||
章节来源
|
||||
- [agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L22-L39)
|
||||
|
||||
### agent_session_notification：SSE 实时进度
|
||||
- 路径参数：session_id
|
||||
- 连接建立：为 session_id 创建新的 SessionData，插入 SESSION_CACHE
|
||||
- 连接管理：
|
||||
- 立即发送 heartbeat 事件，随后每 30 秒发送一次心跳
|
||||
- 使用 CancellationToken 监听取消信号：当新连接建立或用户取消任务时，旧连接自然断开
|
||||
- 当 channel 发送端被 drop 时，recv() 返回 None，连接自然断开
|
||||
- 事件类型映射：根据 UnifiedSessionMessage.message_type 动态设置事件名（prompt_start、prompt_end、各类 agent_session_update、heartbeat）
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as "客户端"
|
||||
participant H as "agent_session_notification"
|
||||
participant S as "SESSION_CACHE"
|
||||
participant W as "SessionWorker"
|
||||
participant P as "ACPI 代理"
|
||||
C->>H : GET /agent/progress/{session_id}
|
||||
H->>S : SessionData : : new + 插入 SESSION_CACHE
|
||||
H->>S : create_new_connection(1000)
|
||||
H-->>C : 发送 initial heartbeat 事件
|
||||
loop 心跳/消息循环
|
||||
alt 收到 CancellationToken
|
||||
H-->>C : 断开旧连接
|
||||
else 收到 UnifiedSessionMessage
|
||||
H-->>C : 事件流推送按 message_type 映射
|
||||
else 心跳定时器
|
||||
H-->>C : 发送 heartbeat 事件
|
||||
end
|
||||
end
|
||||
note over P,S : 代理通过 session_notification 推送消息到 SESSION_CACHE
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L484)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L142-L207)
|
||||
|
||||
章节来源
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L484)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
|
||||
### agent_cancel_handler：任务取消
|
||||
- 查询参数：project_id（可选 session_id）
|
||||
- 逻辑：
|
||||
- 若未提供 session_id，从 PROJECT_AND_AGENT_INFO_MAP 中解析
|
||||
- 通过 cancel_tx 发送 CancelNotificationRequest，并等待响应
|
||||
- 成功后：主动关闭 SSE 连接（close_current_connection），移除 SESSION_CACHE 条目
|
||||
- 未找到活跃连接：同样主动关闭并清理 SESSION_CACHE
|
||||
- 返回：HttpResult.success(CancelResponse{success, session_id})
|
||||
|
||||
章节来源
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs#L110-L258)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L200)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L91)
|
||||
|
||||
### 代理与会话管理（proxy_agent 与 channel_utils）
|
||||
- AcpAgentService：根据 AgentType 启动 Claude 或 Codex 代理服务，返回 AcpConnectionInfo（包含 session_id、prompt_tx、cancel_tx、stop_handle）
|
||||
- AcpAgentClient：实现 agent_client_protocol::Client，处理权限请求、文件读写、session_notification 回调
|
||||
- session_notification：将 AgentSessionUpdate 包装为 SessionNotify，调用 push_session_update 推送
|
||||
- request_id 优先从 SessionNotification.meta 获取，否则通过 PROJECT_AND_AGENT_INFO_MAP + SESSION_REQUEST_CONTEXT 解析
|
||||
- channel_utils：
|
||||
- spawn_prompt_handler_for_agent：监听 prompt_rx，更新 Agent 状态为 Active，推送 SessionPromptStart，调用 Agent.prompt，推送 SessionPromptEnd 或 SessionPromptError
|
||||
- spawn_cancel_handler_for_agent：监听 cancel_rx，调用 Agent.cancel，超时保护，完成后将 Agent 状态恢复为 Idle
|
||||
|
||||
章节来源
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L200)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
|
||||
## 依赖关系分析
|
||||
- handler 依赖
|
||||
- chat_handler 依赖 AppState（sessions、local_task_sender）、ChatPromptBuilder、AgentType、HttpResult/AppError
|
||||
- agent_status_handler 依赖 PROJECT_AND_AGENT_INFO_MAP
|
||||
- agent_session_notification 依赖 SESSION_CACHE、UnifiedSessionMessage
|
||||
- agent_cancel_handler 依赖 PROJECT_AND_AGENT_INFO_MAP、CancelNotificationRequest
|
||||
- proxy_agent 依赖
|
||||
- AcpAgentService/AcpAgentClient、PROJECT_AND_AGENT_INFO_MAP、AcpConnectionInfo
|
||||
- service 依赖
|
||||
- SESSION_CACHE、PROJECT_SESSION_MAP、SessionData、SessionWorker、UnifiedSessionMessage
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
CH["chat_handler"] --> PA["proxy_agent"]
|
||||
CH --> SVC["service"]
|
||||
ASH["agent_status_handler"] --> PA
|
||||
ASN["agent_session_notification"] --> SVC
|
||||
AC["agent_cancel_handler"] --> PA
|
||||
AC --> SVC
|
||||
PA --> SVC
|
||||
SVC --> ASN
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L321)
|
||||
- [agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L484)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs#L110-L258)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L200)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
|
||||
章节来源
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
|
||||
## 性能考量
|
||||
- 会话缓存与推送
|
||||
- SessionData 使用 mpsc::channel 与 CancellationToken 管理连接，避免命令传递的额外开销
|
||||
- SessionWorker 使用 RingBuffer 缓冲消息，实时推送至当前连接，丢弃心跳消息以节省带宽
|
||||
- 通过 PROJECT_SESSION_MAP 确保 project_id 仅对应一个活跃 session，避免旧数据污染
|
||||
- 取消与断开
|
||||
- CancellationToken 与显式 drop Sender 实现快速断开，减少资源占用
|
||||
- 取消超时保护（默认 10 秒），避免阻塞
|
||||
- 并发控制
|
||||
- chat_handler 在 Agent Active 时拒绝并发请求，避免资源争用
|
||||
- 通过 oneshot 通道保证 ChatPromptResponse 的顺序性与一致性
|
||||
|
||||
[本节为通用性能讨论，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 常见错误与状态码映射
|
||||
- 参数错误：chat_handler 对 prompt 校验失败返回 400（AppError::Generic -> INTERNAL_SERVER_ERROR），但 OpenAPI 注释中明确 400 场景
|
||||
- 并发请求：Agent Active 时返回 409（自定义错误码），提示“Agent正在执行任务，请等待当前任务完成后再发送新请求”
|
||||
- 内部错误：AppError::AnyhowError/IOError -> 500（IntoResponse 默认 INTERNAL_SERVER_ERROR）
|
||||
- SSE 连接异常：心跳丢失、连接断开、取消后清理不彻底
|
||||
- 排查步骤
|
||||
- chat_handler：确认 project_id 生成与工作目录创建、session 清理逻辑、LocalSetAgentRequest 发送与 oneshot 响应
|
||||
- agent_session_notification：检查 SessionData::new、create_new_connection、CancellationToken 与心跳定时器
|
||||
- agent_cancel_handler：确认 cancel_tx 发送、响应等待、SSE 连接关闭与 SESSION_CACHE 清理
|
||||
- proxy_agent：核对 PROJECT_AND_AGENT_INFO_MAP 更新、AcpAgentService 启动、session_notification 推送
|
||||
|
||||
章节来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L321)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L484)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs#L110-L258)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L1-L103)
|
||||
|
||||
## 结论
|
||||
本文件梳理了 RCoder Agent Runner 的 HTTP API 请求处理全生命周期，明确了 chat_handler、agent_status_handler、agent_session_notification、agent_cancel_handler 的职责边界与协作关系。通过 SSE 实时推送与会话缓存机制，系统实现了低延迟、高可靠的状态反馈；通过代理层与通道工具的解耦设计，保障了并发安全与可扩展性。建议在生产环境中关注：
|
||||
- 参数校验与错误映射的一致性
|
||||
- SSE 连接的健壮性与自动重连策略
|
||||
- 取消超时与资源回收的可观测性
|
||||
- 代理启动失败的兜底处理与告警
|
||||
@@ -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)
|
||||
Reference in New Issue
Block a user