14 KiB
14 KiB
ACP代理集成
**本文档引用的文件** - [acp_adapter/src/lib.rs](file://crates/acp_adapter/src/lib.rs) - [acp_adapter/src/types.rs](file://crates/acp_adapter/src/types.rs) - [agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs) - [agent_runner/src/proxy_agent/agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs) - [agent_runner/src/proxy_agent/channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs) - [agent_runner/src/proxy_agent/claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs) - [agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs) - [agent_runner/src/proxy_agent/mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs) - [agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs) - [agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs) - [agent_runner/src/handler/agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs) - [agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs) - [agent_runner/src/model.rs](file://crates/agent_runner/src/model.rs) - [shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)目录
简介
本文档详细阐述了ACP代理集成的技术实现，重点说明acp_agent模块如何通过acp_adapter crate实现与ACP协议适配器的通信。文档涵盖了请求转发、状态同步、错误传播机制，以及消息序列化/反序列化过程、连接管理策略和超时处理机制。同时，文档还解释了协议版本兼容性、异常处理和性能优化措施，并通过实际交互示例展示聊天请求的完整流程。
项目结构
项目采用模块化设计，主要分为以下几个核心模块：
acp_adapter: 提供与ACP协议适配器通信的核心功能agent_runner: 负责代理服务的运行和管理shared_types: 共享的数据类型和模型定义
graph TD
subgraph "核心模块"
A[acp_adapter] --> |提供| B[agent_runner]
C[shared_types] --> |共享类型| A
C --> |共享类型| B
end
subgraph "代理类型"
B --> D[Claude Code Agent]
B --> E[Codex Agent]
end
subgraph "通信协议"
A --> F[ACP协议]
F --> G[子进程通信]
end
图源
- acp_adapter/src/lib.rs
- agent_runner/src/proxy_agent/claude_code_agent.rs
- agent_runner/src/proxy_agent/codex_agent.rs
本节源
- acp_adapter/src/lib.rs
- agent_runner/src/proxy_agent/claude_code_agent.rs
- agent_runner/src/proxy_agent/codex_agent.rs
核心组件
系统的核心组件包括ACP适配器、代理服务管理器和会话状态管理器。ACP适配器负责处理与代理的底层通信，代理服务管理器负责启动和管理不同类型的代理服务，会话状态管理器则负责维护会话的生命周期和状态同步。
本节源
- acp_adapter/src/lib.rs
- agent_runner/src/proxy_agent/agent_service.rs
- agent_runner/src/service/session_cache.rs
架构概述
系统采用分层架构设计，通过抽象层实现不同AI代理的统一接入。核心架构包括协议抽象层、代理管理层和会话管理层。
graph TD
A[客户端] --> B[HTTP API]
B --> C[代理管理层]
C --> D[协议抽象层]
D --> E[ACP适配器]
E --> F[具体代理]
F --> G[Claude Code]
F --> H[Codex]
style D fill:#f9f,stroke:#333,stroke-width:2px
style C fill:#bbf,stroke:#333,stroke-width:2px
图源
- acp_adapter/src/lib.rs
- agent_runner/src/proxy_agent/agent_service.rs
- agent_runner/src/proxy_agent/acp_agent.rs
详细组件分析
ACP适配器分析
ACP适配器模块提供了与ACP兼容的AI代理通信的核心功能，包括连接管理、会话生命周期、消息处理和MCP集成。
类图
classDiagram
class AcpAdapter {
+initialize()
+new_session()
+load_session()
+prompt()
+cancel()
}
class SessionState {
+Initializing
+Connected
+Prompting
+Paused
+Closed
+Error
}
class StreamUpdate {
+UserMessageChunk
+AgentMessageChunk
+AgentThoughtChunk
+ToolCall
+SessionStateChanged
+PromptStarted
+PromptCompleted
+Error
}
AcpAdapter --> SessionState : "使用"
AcpAdapter --> StreamUpdate : "生成"
图源
请求处理流程
sequenceDiagram
participant Client as "客户端"
participant Handler as "Chat Handler"
participant Agent as "ACP Agent"
participant Adapter as "ACP Adapter"
Client->>Handler : 发送聊天请求
Handler->>Agent : 创建代理服务
Agent->>Adapter : 初始化连接
Adapter->>Agent : 返回连接信息
Agent->>Adapter : 发送Prompt请求
Adapter->>Client : 流式返回响应
Client->>Handler : 接收响应
图源
- agent_runner/src/handler/chat_handler.rs
- agent_runner/src/proxy_agent/acp_agent.rs
- acp_adapter/src/lib.rs
本节源
代理服务管理分析
代理服务管理器负责启动和管理不同类型的代理服务，通过统一的接口实现不同AI代理的接入。
代理服务类图
classDiagram
class AcpAgentService {
<<trait>>
+start_agent_service()
+agent_type_name()
}
class ClaudeCodeAgent {
+start_claude_code_acp_agent_service()
}
class CodexAgent {
+start_codex_acp_agent_service()
}
AcpAgentService <|-- ClaudeCodeAgent
AcpAgentService <|-- CodexAgent
图源
- agent_runner/src/proxy_agent/agent_service.rs
- agent_runner/src/proxy_agent/claude_code_agent.rs
- agent_runner/src/proxy_agent/codex_agent.rs
代理启动流程
flowchart TD
Start([启动代理服务]) --> CheckExistence["检查代理是否存在"]
CheckExistence --> |存在| Reuse["复用现有代理"]
CheckExistence --> |不存在| Create["创建新代理"]
Create --> StartProcess["启动子进程"]
StartProcess --> Initialize["初始化ACP连接"]
Initialize --> CreateSession["创建会话"]
CreateSession --> SetupChannels["设置通信通道"]
SetupChannels --> Monitor["监控代理状态"]
Monitor --> End([代理服务启动完成])
图源
本节源
- agent_runner/src/proxy_agent/agent_service.rs
- agent_runner/src/proxy_agent/claude_code_agent.rs
- agent_runner/src/proxy_agent/codex_agent.rs
会话状态管理分析
会话状态管理器负责维护会话的生命周期和状态同步，确保消息的正确传递和状态的一致性。
会话缓存流程
flowchart TD
A[客户端建立SSE连接] --> B[创建SessionData]
B --> C[插入SESSION_CACHE]
C --> D[创建消息通道]
D --> E[监听消息队列]
E --> F[推送消息到客户端]
F --> G{连接是否活跃?}
G --> |是| E
G --> |否| H[清理资源]
图源
消息处理流程
sequenceDiagram
participant Client as "客户端"
participant Handler as "Handler"
participant Cache as "SessionCache"
participant Agent as "Agent"
Client->>Handler : 建立SSE连接
Handler->>Cache : 创建SessionData
Cache->>Handler : 返回消息通道
loop 消息处理
Agent->>Cache : 发送消息
Cache->>Handler : 推送消息
Handler->>Client : 发送SSE事件
end
Client->>Handler : 断开连接
Handler->>Cache : 清理资源
图源
- agent_runner/src/service/session_cache.rs
- agent_runner/src/handler/agent_session_notification.rs
- agent_runner/src/proxy_agent/mod.rs
本节源
- agent_runner/src/service/session_cache.rs
- agent_runner/src/handler/agent_session_notification.rs
- agent_runner/src/proxy_agent/mod.rs
依赖分析
系统依赖关系清晰，各模块之间通过定义良好的接口进行通信，降低了耦合度。
graph TD
A[agent_runner] --> B[acp_adapter]
A --> C[shared_types]
B --> D[agent_client_protocol]
C --> E[protobuf]
style A fill:#f96,stroke:#333
style B fill:#6f9,stroke:#333
style C fill:#96f,stroke:#333
图源
本节源
性能考虑
系统在设计时充分考虑了性能优化，主要体现在以下几个方面：
- 连接复用: 通过PROJECT_AND_AGENT_INFO_MAP静态映射，实现项目与代理服务的一对一复用，避免频繁创建和销毁代理服务。
- 异步处理: 使用Tokio异步运行时，通过LocalSet管理非Send的ACP连接，确保高性能的异步I/O操作。
- 通道优化: 采用无界通道(unbounded_channel)进行消息传递，避免阻塞，同时通过环形缓冲区(HeapRb)管理消息队列，提高内存使用效率。
- 锁优化: 使用DashMap替代传统HashMap，提供高性能的并发访问，减少锁竞争。
- 资源管理: 通过CancellationToken实现优雅的资源清理，确保代理服务在取消时能够正确释放资源。
本节源
- agent_runner/src/proxy_agent/acp_agent.rs
- agent_runner/src/service/session_cache.rs
- agent_runner/src/proxy_agent/channel_utils.rs
故障排除指南
常见问题及解决方案
代理启动失败
症状: 启动代理服务时返回"启动ACP Agent服务失败"错误。
可能原因:
- 环境变量配置不正确
- 代理可执行文件未找到
- 项目目录权限问题
解决方案:
- 检查相关环境变量(如ANTHROPIC_API_KEY)是否正确设置
- 确认
claude-code-acp或codex-acp-agent命令是否在PATH中 - 检查项目目录的读写权限
消息推送中断
症状: SSE连接建立后，消息推送突然中断。
可能原因:
- 代理服务异常退出
- 网络连接问题
- 超时设置过短
解决方案:
- 检查代理服务的日志输出
- 增加连接超时时间
- 实现客户端重连机制
并发请求被拒绝
症状: 连续发送多个请求时，后续请求返回"Agent正在执行任务"错误。
原因: 系统设计为每个项目ID对应一个代理服务，禁止并发请求以避免状态混乱。
解决方案:
- 等待当前任务完成后发送新请求
- 为不同任务使用不同的项目ID
- 实现请求队列机制
本节源
- agent_runner/src/handler/chat_handler.rs
- agent_runner/src/handler/agent_cancel_handler.rs
- agent_runner/src/proxy_agent/claude_code_agent.rs
结论
ACP代理集成系统通过清晰的分层架构和模块化设计，实现了与不同AI代理的统一接入。系统通过acp_adapter crate提供了协议抽象层，使得上层应用可以无缝切换不同的代理实现。通过高效的连接管理、状态同步和错误处理机制，系统确保了稳定可靠的通信。未来可以考虑增加更多类型的代理支持，以及优化资源利用率和响应性能。