AtomCode v5.0.9 新子系统深度分析 — ACP v2 协议栈
基于
strings对agent-client-protocolcrate 符号的还原分析 2026-09-09 前置报告：05-version-diff-v4.25.5-to-v5.0.9.md
1. ACP（Agent Client Protocol）引入背景
v5.0.9 全新引入 ACP —— 让 AtomCode 作为通用 Agent 被 IDE / 外部客户端驱动的标准协议实现，基于官方 Rust crate agent-client-protocol-2.0.0。
源码模块（全新）:
crates/atomcode-cli/src/acp/{commands,discovery,dispatch,elicitation,engine,mod,options,permission,sessions,turn,v2}.rs命令入口：atomcode acp serve（over stdio）。
2. 双协议栈：v1 与 v2 并行
二进制同时包含 agent_client_protocol_schema::v1 与 v2 两套 schema，运行时按客户端协商版本选择。
2.1 v2 新增/变更方法（vs v1）
| 方法 | v1 | v2 | 说明 |
|---|---|---|---|
InitializeRequest | ✅ | ✅ | 初始化握手 |
NewSessionRequest | ✅ | ✅ | 新建会话（含 additionalDirectories） |
LoadSessionRequest | ✅ | — | 加载会话（v2 移除） |
ResumeSessionRequest | ✅ | ✅ | 恢复会话 |
PromptRequest | ✅ | ✅ | 提示词请求 |
ListSessionsRequest | ✅ | ✅ | 会话列表 |
DeleteSessionRequest | ✅ | ✅ | 删除会话 |
CloseSessionRequest | ✅ | ✅ | 关闭会话 |
SetSessionModeRequest | ✅ | — | 设置会话模式（v2 移除） |
SetSessionConfigOptionRequest | ✅ | ✅ | 设置配置项 |
CancelNotification | ✅ | — | 取消通知（v1 agent 侧） |
CancelSessionNotification | — | ✅ | 取消会话（v2 新增） |
CancelRequestNotification | protocol_level | protocol_level | 协议级取消请求 |
2.2 v2 关键变更
CancelSessionNotification：v1 中取消是 agent 侧CancelNotification+ 协议级CancelRequestNotification双轨；v2 合并为会话级取消。LoadSessionRequest/SetSessionModeRequest移除：会话加载改为ResumeSessionRequest统一承载。CancelRequestNotification保留在 protocol_level：作为跨层通用取消信号。
2.3 协议版本协商
ACP protocol version
required ACP protocol version
unsupported ACP protocol version→ 握手阶段校验版本，不支持的版本拒绝。
3. 传输与能力
3.1 传输层
| 传输 | 说明 |
|---|---|
| stdio | 主通道（acp serve 默认） |
| MCP http 传输 | ACP 会话中可挂载 MCP server（v2 新增） |
| SSE | 事件流（atomcode_telemetry::event::SessionMode 等经 SSE 推送） |
3.2 会话能力
additionalDirectories entries must be absolute paths (got ...
struct NewSessionRequest with 4 elements
struct CancelNotificationadditionalDirectories：允许客户端声明额外工作目录（多目录会话），必须为绝对路径- 会话/提示词请求立即确认（async ack），运行中可热切换：
acp channel can switch execution mode / reasoning_effort / model at runtime3.3 权限往返
acp: request_permission round-trip failed
acp: request_user_input: bad payload
acp: request_permission ...→ ACP 将权限请求经协议通道转发给客户端（IDE）决策，非本地 TUI 弹窗。
3.4 取消链路
acp: v2 $/cancel_request for request
$ /cancel_request ← JSON-RPC 通知$ 前缀为 JSON-RPC 通知方法名（ACP 协议的 cancel_request 通知）。
4. 架构还原
┌──────────────────────────────────────────────────────────┐
│ 客户端 (IDE / 编辑器 / 测试驱动) │
│ ┌────────────────────────────────────────────────────┐ │
│ │ ACP over stdio/HTTP(SSE) │ │
│ └────────────────────────────────────────────────────┘ │
└──────────────────────┬───────────────────────────────────┘
│ JSON-RPC (agent-client-protocol)
┌──────────────────────▼───────────────────────────────────┐
│ atomcode acp serve │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────────────┐ │
│ │ discovery │ │ dispatch │ │ permission │ │
│ │ (协议版本) │ │ (请求路由) │ │ (round-trip 到 IDE)│ │
│ └─────────────┘ └─────────────┘ └────────────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────────────┐ │
│ │ sessions │ │ elicitation │ │ turn / engine │ │
│ │ (会话管理) │ │ (澄清请求) │ │ (回合执行) │ │
│ └─────────────┘ └─────────────┘ └────────────────────┘ │
│ MCP http transport (挂载 MCP server) │
└──────────────────────────────────────────────────────────┘模块职责（由文件名还原）：
- commands：
acp serve等 CLI 子命令 - discovery：协议版本发现/协商
- dispatch：JSON-RPC 方法分发
- elicitation：澄清请求（request_user_input）
- engine：与主引擎衔接
- options：会话选项（execution mode / reasoning_effort / model）
- permission：权限请求转发
- sessions：会话生命周期
- turn：回合执行
- v2：v2 特定逻辑
- mod：模块入口
5. 与 headless JSONL 的关系
ACP v2 与 --output-format jsonl 共用底层回合/会话抽象：
JSONL 事件流: run.started → message.delta → tool.started → usage → turn.completed
ACP 通知: state_update / cancel_request / 会话状态同步两者是同一执行内核的两面：JSONL 面向本地脚本消费，ACP 面向远程客户端双向控制。
6. 逆向方法论备注
- Rust 模块路径 + 泛型类型参数（
ChainedHandler、NotificationHandler）完整保留了 ACP handler 组装结构 agent_client_protocol_schema::v1/v2分离命名直接暴露双版本 schema 共存事实- 错误串
$ /cancel_request、round-trip failed揭示了协议级交互细节 - v1→v2 的方法增减（
LoadSessionRequest移除等）可通过同一 schema 命名空间对比推断
本报告由持续分析循环生成 — v5.0.9 ACP v2 协议栈深度分析