添加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/核心模块架构/代理运行器架构/代理运行器架构.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/核心模块架构/代理运行器架构/代理运行器架构.md
@@ -0,0 +1,536 @@
+# 代理运行器架构
+
+<cite>
+**本文档引用的文件**
+- [main.rs](file://crates/agent_runner/src/main.rs)
+- [lib.rs](file://crates/agent_runner/src/lib.rs)
+- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs)
+- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
+- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
+- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
+- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
+- [router.rs](file://crates/agent_runner/src/router.rs)
+- [model.rs](file://crates/agent_runner/src/model.rs)
+- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
+- [lib.rs](file://crates/acp_adapter/src/lib.rs)
+- [lib.rs](file://crates/docker_manager/src/lib.rs)
+- [lib.rs](file://crates/pingora-proxy/src/lib.rs)
+- [lib.rs](file://crates/shared_types/src/lib.rs)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概述](#架构概述)
+5. [详细组件分析](#详细组件分析)
+6. [依赖分析](#依赖分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+
+## 简介
+代理运行器是一个基于Rust的高性能AI代理管理平台，旨在为AI驱动的开发提供完整的代理集成解决方案。该系统通过ACP（Agent Client Protocol）协议与不同的AI代理（如Codex、Claude Code）进行通信，实现了代理生命周期管理、会话状态维护和异步任务调度等核心功能。系统采用模块化设计，通过Pingora反向代理实现高性能的请求路由，并通过Docker管理器实现资源隔离和容器化部署。代理运行器支持多代理架构，通过抽象层设计实现了不同AI代理的无缝集成。
+
+## 项目结构
+代理运行器采用Rust工作区（workspace）结构，包含多个独立的crates，每个crate负责特定的功能模块。这种模块化设计提高了代码的可维护性和可扩展性。
+
+```mermaid
+graph TD
+A[代理运行器] --> B[agent_runner]
+A --> C[acp_adapter]
+A --> D[claude-code-agent]
+A --> E[codex-acp-agent]
+A --> F[docker_manager]
+A --> G[pingora-proxy]
+A --> H[rcoder]
+A --> I[shared_types]
+B --> J[HTTP服务器]
+B --> K[代理服务]
+B --> L[会话管理]
+C --> M[ACP协议适配]
+F --> N[Docker容器管理]
+G --> O[反向代理]
+I --> P[共享数据类型]
+```
+
+**图表来源**
+- [main.rs](file://crates/agent_runner/src/main.rs)
+- [lib.rs](file://crates/agent_runner/src/lib.rs)
+- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
+
+**章节来源**
+- [main.rs](file://crates/agent_runner/src/main.rs)
+- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
+
+## 核心组件
+代理运行器的核心组件包括代理服务管理、会话状态维护、ACP协议适配和Docker资源管理。这些组件协同工作，实现了AI代理的全生命周期管理。
+
+**章节来源**
+- [main.rs](file://crates/agent_runner/src/main.rs)
+- [lib.rs](file://crates/agent_runner/src/lib.rs)
+- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs)
+
+## 架构概述
+代理运行器采用分层架构设计，从上到下分为HTTP接口层、业务逻辑层、代理服务层和基础设施层。这种分层设计确保了系统的高内聚、低耦合特性。
+
+```mermaid
+graph TD
+A[HTTP接口层] --> B[业务逻辑层]
+B --> C[代理服务层]
+C --> D[基础设施层]
+A --> E[API路由]
+A --> F[请求处理]
+B --> G[会话管理]
+B --> H[状态维护]
+C --> I[ACP适配]
+C --> J[代理通信]
+D --> K[Docker管理]
+D --> L[资源隔离]
+E --> M[chat_handler]
+F --> N[agent_service]
+G --> O[session_cache]
+H --> P[AgentStatus]
+I --> Q[acp_adapter]
+J --> R[claude_code_agent]
+K --> S[docker_manager]
+L --> T[container隔离]
+```
+
+**图表来源**
+- [main.rs](file://crates/agent_runner/src/main.rs)
+- [router.rs](file://crates/agent_runner/src/router.rs)
+- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
+- [docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
+
+**章节来源**
+- [main.rs](file://crates/agent_runner/src/main.rs)
+- [router.rs](file://crates/agent_runner/src/router.rs)
+
+## 详细组件分析
+
+### 代理生命周期管理
+代理运行器通过`agent_worker`任务管理所有AI代理的生命周期。每个代理服务与一个项目ID关联，实现了代理的复用和资源优化。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Handler as "chat_handler"
+participant AgentWorker as "agent_worker"
+participant AgentService as "代理服务"
+Client->>Handler : POST /chat
+Handler->>AgentWorker : 发送LocalSetAgentRequest
+AgentWorker->>AgentWorker : 检查现有代理
+alt 代理存在
+AgentWorker->>AgentService : 复用现有代理
+AgentService-->>AgentWorker : 返回会话ID
+else 代理不存在
+AgentWorker->>AgentService : 创建新代理
+AgentService-->>AgentWorker : 返回会话ID
+end
+AgentWorker->>Handler : 发送ChatPromptResponse
+Handler-->>Client : 返回响应
+```
+
+**图表来源**
+- [main.rs](file://crates/agent_runner/src/main.rs#L58-L76)
+- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L196-L341)
+- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
+
+**章节来源**
+- [main.rs](file://crates/agent_runner/src/main.rs)
+- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
+
+### 会话状态维护
+会话状态维护是代理运行器的核心功能之一，通过`SESSION_CACHE`和`PROJECT_SESSION_MAP`两个全局数据结构实现。
+
+```mermaid
+classDiagram
+class SessionData {
+command_tx : UnboundedSender~SessionCommand~
+current_sender : Arc~Mutex~Option~Sender~UnifiedSessionMessage~~~~
+current_cancel : Arc~Mutex~Option~CancellationToken~~~
+new(max_size : usize) Arc~Self~
+message_count() usize
+create_new_connection(buffer_size : usize) Result~(Receiver~UnifiedSessionMessage~, CancellationToken)~
+push_message(message : UnifiedSessionMessage)
+close_current_connection()
+}
+class SessionWorker {
+-max_size : usize
+-command_rx : UnboundedReceiver~SessionCommand~
+-current_sender : Arc~Mutex~Option~Sender~UnifiedSessionMessage~~~~
+-current_cancel : Arc~Mutex~Option~CancellationToken~~~
+spawn(max_size : usize, command_rx : UnboundedReceiver~SessionCommand~, current_sender : Arc~Mutex~Option~Sender~UnifiedSessionMessage~~~~, current_cancel : Arc~Mutex~Option~CancellationToken~~~)
+run()
+}
+class SessionCommand {
+Push{message : UnifiedSessionMessage}
+Clear{ack : oneshot : : Sender~usize~}
+MessageCount{ack : oneshot : : Sender~usize~}
+}
+SessionData --> SessionWorker : "spawn"
+SessionWorker --> SessionCommand : "处理"
+SessionData --> SessionCommand : "发送命令"
+```
+
+**图表来源**
+- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L25-L222)
+- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L142-L171)
+
+**章节来源**
+- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
+
+### ACP协议适配器
+ACP协议适配器是代理运行器与AI代理通信的核心组件，实现了ACP协议的客户端功能。
+
+```mermaid
+classDiagram
+class AcpAgentClient {
+request_permission(args : RequestPermissionRequest) Result~RequestPermissionResponse, Error~
+write_text_file(args : WriteTextFileRequest) Result~WriteTextFileResponse, Error~
+read_text_file(args : ReadTextFileRequest) Result~ReadTextFileResponse, Error~
+session_notification(args : SessionNotification) Result~(), Error~
+ext_method(request : ExtRequest) Result~ExtResponse, Error~
+ext_notification(notification : ExtNotification) Result~(), Error~
+}
+class Client {
+<<trait>>
+request_permission(args : RequestPermissionRequest) Result~RequestPermissionResponse, Error~
+write_text_file(args : WriteTextFileRequest) Result~WriteTextFileResponse, Error~
+read_text_file(args : ReadTextFileRequest) Result~ReadTextFileResponse, Error~
+session_notification(args : SessionNotification) Result~(), Error~
+ext_method(request : ExtRequest) Result~ExtResponse, Error~
+ext_notification(notification : ExtNotification) Result~(), Error~
+}
+AcpAgentClient --|> Client : "实现"
+class AcpConnectionInfo {
+session_id : SessionId
+prompt_tx : UnboundedSender~PromptRequest~
+cancel_tx : UnboundedSender~CancelNotificationRequest~
+stop_handle : Option~AgentStopHandleArc~
+}
+class AcpAgentService {
+<<trait>>
+start_agent_service(chat_prompt : ChatPrompt, model_provider : Option~ModelProviderConfig~) Result~AcpConnectionInfo~
+agent_type_name() &'static str
+}
+AcpAgentService <-- AcpConnectionInfo : "返回"
+AcpAgentClient <-- AcpConnectionInfo : "使用"
+```
+
+**图表来源**
+- [acp_adapter/src/lib.rs](file://crates/acp_adapter/src/lib.rs)
+- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L43-L255)
+- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
+
+**章节来源**
+- [acp_adapter/src/lib.rs](file://crates/acp_adapter/src/lib.rs)
+- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs)
+- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
+
+### 多代理支持实现
+代理运行器通过`AgentType`枚举和特征对象实现了对多种AI代理的支持，包括Claude和Codex。
+
+```mermaid
+classDiagram
+class AgentType {
+<<enum>>
+Claude
+Codex
+}
+class AcpAgentService {
+<<trait>>
+start_agent_service(chat_prompt : ChatPrompt, model_provider : Option~ModelProviderConfig~) Result~AcpConnectionInfo~
+agent_type_name() &'static str
+}
+AgentType --|> AcpAgentService : "实现"
+class ClaudeCodeAgent {
+start_claude_code_acp_agent_service(chat_prompt : ChatPrompt, model_provider : Option~ModelProviderConfig~) Result~AcpConnectionInfo~
+}
+class CodexAgent {
+start_codex_acp_agent_service(chat_prompt : ChatPrompt, model_provider : Option~ModelProviderConfig~) Result~AcpConnectionInfo~
+}
+AcpAgentService <|-- ClaudeCodeAgent : "具体实现"
+AcpAgentService <|-- CodexAgent : "具体实现"
+AgentType --> ClaudeCodeAgent : "调用"
+AgentType --> CodexAgent : "调用"
+```
+
+**图表来源**
+- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
+- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
+- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs)
+
+**章节来源**
+- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
+- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
+
+### 异步任务调度
+代理运行器采用Rust的异步运行时模型，通过Tokio运行时和LocalSet实现了高效的异步任务调度。
+
+```mermaid
+flowchart TD
+A[主异步运行时] --> B[HTTP服务器]
+A --> C[清理任务]
+A --> D[代理服务]
+D --> E[独立OS线程]
+E --> F[单线程Tokio运行时]
+F --> G[LocalSet]
+G --> H[agent_worker]
+H --> I[ACP连接]
+H --> J[通道处理器]
+B --> K[请求处理]
+K --> L[发送LocalSetAgentRequest]
+L --> H
+C --> M[定期清理]
+M --> N[清理空闲会话]
+```
+
+**图表来源**
+- [main.rs](file://crates/agent_runner/src/main.rs#L58-L76)
+- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L196-L341)
+
+**章节来源**
+- [main.rs](file://crates/agent_runner/src/main.rs)
+- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
+
+### 资源隔离策略
+代理运行器通过Docker管理器实现了严格的资源隔离，确保每个AI代理在独立的容器环境中运行。
+
+```mermaid
+classDiagram
+class DockerManager {
+new(config : DockerManagerConfig) DockerResult~Self~
+create_container(config : ContainerConfig) DockerResult~Container~
+start_container(container_id : &str) DockerResult~()
+stop_container(container_id : &str) DockerResult~()
+remove_container(container_id : &str) DockerResult~()
+list_containers() DockerResult~Vec~ContainerInfo~~
+}
+class ContainerConfig {
+image : String
+name : String
+ports : Vec~PortMapping~
+volumes : Vec~VolumeMapping~
+env_vars : Vec~EnvVar~
+network_mode : String
+}
+class PortMapping {
+host_port : u16
+container_port : u16
+}
+class VolumeMapping {
+host_path : String
+container_path : String
+}
+class EnvVar {
+name : String
+value : String
+}
+DockerManager --> ContainerConfig : "使用"
+ContainerConfig --> PortMapping : "包含"
+ContainerConfig --> VolumeMapping : "包含"
+ContainerConfig --> EnvVar : "包含"
+```
+
+**图表来源**
+- [docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
+- [docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs)
+
+**章节来源**
+- [docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
+
+### 错误恢复机制
+代理运行器实现了多层次的错误恢复机制，确保系统的稳定性和可靠性。
+
+```mermaid
+flowchart TD
+A[错误发生] --> B{错误类型}
+B --> C[可恢复错误]
+B --> D[不可恢复错误]
+C --> E[重试机制]
+E --> F[指数退避]
+F --> G[最大重试次数]
+G --> H{重试成功?}
+H --> |是| I[继续执行]
+H --> |否| J[降级处理]
+D --> K[优雅降级]
+K --> L[返回默认值]
+L --> M[记录错误日志]
+M --> N[发送告警]
+I --> O[正常流程]
+J --> O
+N --> O
+P[监控系统] --> Q[错误指标]
+Q --> R[告警系统]
+R --> S[运维人员]
+```
+
+**图表来源**
+- [main.rs](file://crates/agent_runner/src/main.rs#L31-L232)
+- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L142-L161)
+- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L235-L247)
+
+**章节来源**
+- [main.rs](file://crates/agent_runner/src/main.rs)
+- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
+
+### 可扩展性考虑
+代理运行器的设计充分考虑了可扩展性，通过模块化架构和配置驱动的方式支持未来的功能扩展。
+
+```mermaid
+graph TD
+A[核心框架] --> B[插件系统]
+A --> C[配置管理]
+A --> D[服务发现]
+B --> E[新代理类型]
+B --> F[新协议适配]
+B --> G[新存储后端]
+C --> H[动态配置]
+C --> I[热更新]
+C --> J[配置验证]
+D --> K[服务注册]
+D --> L[健康检查]
+D --> M[负载均衡]
+A --> N[监控系统]
+N --> O[指标收集]
+N --> P[日志聚合]
+N --> Q[分布式追踪]
+O --> R[Prometheus]
+P --> S[ELK]
+Q --> T[OpenTelemetry]
+```
+
+**图表来源**
+- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
+- [config.rs](file://crates/agent_runner/src/config.rs)
+- [main.rs](file://crates/agent_runner/src/main.rs)
+
+**章节来源**
+- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
+- [config.rs](file://crates/agent_runner/src/config.rs)
+
+### 性能监控
+代理运行器集成了全面的性能监控系统，通过OpenTelemetry实现分布式追踪和指标收集。
+
+```mermaid
+graph TD
+A[应用代码] --> B[Tracing]
+B --> C[OpenTelemetry]
+C --> D[Exporter]
+D --> E[Jaeger]
+D --> F[Prometheus]
+D --> G[Zipkin]
+A --> H[Metrics]
+H --> I[Counter]
+H --> J[Histogram]
+H --> K[Gauge]
+I --> L[请求计数]
+J --> M[响应时间]
+K --> N[并发数]
+A --> O[Logging]
+O --> P[JSON日志]
+P --> Q[ELK]
+C --> R[Trace Context]
+R --> S[跨服务追踪]
+T[监控面板] --> U[指标可视化]
+U --> V[告警规则]
+V --> W[通知系统]
+```
+
+**图表来源**
+- [main.rs](file://crates/agent_runner/src/main.rs#L181-L231)
+- [Cargo.toml](file://crates/agent_runner/Cargo.toml#L65-L69)
+
+**章节来源**
+- [main.rs](file://crates/agent_runner/src/main.rs)
+- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
+
+### 与docker_manager的集成
+代理运行器与Docker管理器深度集成，实现了容器化部署和资源管理。
+
+```mermaid
+sequenceDiagram
+participant AgentRunner as "代理运行器"
+participant DockerManager as "Docker管理器"
+participant DockerDaemon as "Docker守护进程"
+AgentRunner->>DockerManager : 创建容器请求
+DockerManager->>DockerDaemon : 创建容器
+DockerDaemon-->>DockerManager : 容器ID
+DockerManager->>DockerDaemon : 启动容器
+DockerDaemon-->>DockerManager : 启动成功
+DockerManager-->>AgentRunner : 容器准备就绪
+AgentRunner->>DockerManager : 发送命令
+DockerManager->>DockerDaemon : 执行命令
+DockerDaemon-->>DockerManager : 命令输出
+DockerManager-->>AgentRunner : 返回结果
+AgentRunner->>DockerManager : 停止容器
+DockerManager->>DockerDaemon : 停止容器
+DockerDaemon-->>DockerManager : 停止成功
+DockerManager-->>AgentRunner : 清理完成
+```
+
+**图表来源**
+- [docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
+- [docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs)
+
+**章节来源**
+- [docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
+
+## 依赖分析
+代理运行器的依赖关系清晰，各模块之间的耦合度低，便于维护和扩展。
+
+```mermaid
+graph TD
+A[agent_runner] --> B[acp_adapter]
+A --> C[shared_types]
+A --> D[pingora-proxy]
+A --> E[claude-code-agent]
+A --> F[codex-acp-agent]
+A --> G[docker_manager]
+B --> H[agent-client-protocol]
+C --> I[grpc]
+D --> J[axum]
+D --> K[reqwest]
+E --> L[agent-client-protocol]
+F --> M[agent-client-protocol]
+G --> N[bollard]
+A --> O[tokio]
+A --> P[axum]
+A --> Q[tracing]
+A --> R[serde]
+A --> S[dashmap]
+O --> T[异步运行时]
+P --> U[Web框架]
+Q --> V[日志追踪]
+R --> W[序列化]
+S --> X[并发映射]
+```
+
+**图表来源**
+- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
+- [Cargo.toml](file://crates/acp_adapter/Cargo.toml)
+- [Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
+
+**章节来源**
+- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
+
+## 性能考虑
+代理运行器在设计时充分考虑了性能因素，采用了多种优化策略。
+
+**章节来源**
+- [main.rs](file://crates/agent_runner/src/main.rs)
+- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
+- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
+
+## 故障排除指南
+当代理运行器出现问题时，可以按照以下步骤进行排查。
+
+**章节来源**
+- [main.rs](file://crates/agent_runner/src/main.rs)
+- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
+- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
+
+## 结论
+代理运行器通过精心设计的架构和实现，提供了一个高性能、可扩展的AI代理管理平台。系统采用模块化设计，各组件职责清晰，耦合度低。通过ACP协议适配器，实现了与不同AI代理的无缝集成。异步任务调度和资源隔离策略确保了系统的高效性和稳定性。全面的监控和错误恢复机制为系统的可靠运行提供了保障。整体架构具有良好的可扩展性，能够适应未来的需求变化。