atomcode 接入 ACP SDK 的 Handler 与传输实战笔记:闭包人体工学、单任务分发循环与内存通道
atomcode 接入 ACP SDK 的 Handler 与传输实战笔记:闭包人体工学、单任务分发循环与内存通道
本文以 atomcode 仓库内 docs/acp-sdk-handler-notes.md 这份历史 spike 笔记为骨架,结合 crates/atomcode-cli/src/acp/ 的完整实现与测试,系统讲解 agent-client-protocol(ACP,Agent Client Protocol)接入时的三个关键工程点:Handler 闭包的注册与响应写法、分发事件循环的单任务并发模型、以及不依赖子进程的内存传输通道。读完本文,你将掌握如何用 on_receive_request! 宏注册请求处理器、为何 session/prompt 这类长任务必须用 cx.spawn() 移出分发循环、以及如何用 Channel::duplex() 编写无子进程无网络的端到端测试。
1. 背景:一份"代码为准"的接入笔记
docs/acp-sdk-handler-notes.md 是 2026-06-29 在把 atomcode acp agent 接入 agent-client-protocol 时记录的历史 spike 笔记,开篇即声明"Kept as reference only — the code is authoritative"(仅作参考,代码才是权威)。也就是说,这份笔记是给后续维护者指路的线索图,真正的实现细节全部落在 crates/atomcode-cli/src/acp/ 的 14 个模块中:
| 模块 | 职责 |
|---|---|
| mod.rs | ACP agent 装配:v1/v2 双 handler 链、serve_stdio/serve_over、protocol_router 分流、fallback dispatch |
| dispatch.rs | session/new/session/resume/session/load 处理、v1 prompt turn 驱动 |
| turn.rs | v1/v2 共享的协议中立 turn 驱动骨架(TurnWire trait) |
| engine.rs | EngineConfig 与 spawn_session(prepare → assemble → spawn 出 CodingRuntime) |
| sessions.rs | 活会话表、wire id 编解码、cancel/close/delete 拆除逻辑 |
| v2.rs | v2 draft 协议链(feature 门控 unstable_protocol_v2) |
| translate.rs | v1 事件映射与 stop reason 映射 |
| permission.rs | 审批回环:kernel 审批请求 ↔ session/request_permission |
| elicitation.rs | request_user_input ↔ elicitation/create(form)回环 |
| commands.rs | slash 命令广告与本地执行、v1/v2 plan update 派生 |
| replay.rs | resume/load 历史回放:原生聚合 → neutral replay entries |
依赖声明在 crates/atomcode-cli/Cargo.toml:agent-client-protocol = { workspace = true, features = <a href="https://link.gitcode.com/i/f07a330a0a21d3e6e5688d7008458ee4" target="_blank">"unstable_protocol_v2", "unstable_elicitation"] }。更宏观的协议推进路线(SDK 1.0.1 → 2.0.0 迁移、差距分析、v1+v2 双支持机制)可参考 [docs/plans/2026-08-17-acp-sdk-2.0-protocol-roadmap.md。
2. Handler 闭包人体工学:注册、响应与错误构造
笔记第一部分记录的是在 SDK 上写 handler 时最"磨人"的三个 API 细节,理解它们能避免大量编译期试错。
2.1 responder.respond(response):请求处理的"终点"
请求 handler 收到一个请求后,通过 Responder 把响应发回客户端。其签名是:
fn respond(self, response: T) -> Result<(), agent_client_protocol::Error>
其中 T = Req::Response,即该请求类型的协议响应。因为 respond 消费 self,所以一个请求只能被应答恰好一次——这在 dispatch.rs 的 v1 turn 驱动中体现为"on every exit path answers exactly once"(每个退出路径都恰好应答一次)的纪律。
一个典型的 handler 写法(来自 mod.rs 的 initialize 处理器):
async move |init: InitializeRequest, responder, _cx: ConnectionTo<Client>| {
// 记录客户端是否声明支持 form 形式的 elicitation
client_elicitation_form.store(/* … */);
responder.respond(
InitializeResponse::new(init.protocol_version)
.agent_info(Implementation::new("atomcode", env!("CARGO_PKG_VERSION")).title("AtomCode"))
.agent_capabilities(v1_agent_capabilities()),
)
}
对于"应答前还有异步工作"的处理器(如 session/new 需要先 spawn kernel 会话),可以先 responder.respond(resp)? 完成应答,再继续 best-effort 的通知发送——例如 session/new 处理器 在应答之后广播 available_commands_update,并刻意用 let _ = cx.send_notification(..) 吞掉发送失败,避免"已答应的请求因通知投递失败被标记为失败"。
2.2 on_receive_request!() / on_receive_dispatch!():返回类型标注稳定前的过渡宏
笔记指出,SDK 的这两个宏展开为:
// on_receive_request!() 展开为:
|f: &mut _, req, responder, cx| Box::pin(f(req, responder, cx))
// 必须作为最后一个参数传入
// on_receive_dispatch!() 展开为:
|f: &mut _, dispatch, cx| Box::pin(f(dispatch, cx))
这是"直到返回类型标注(return-type notation)稳定之前"的过渡方案。从 mod.rs 的实际用法可以看到,每个 on_receive_request 调用都遵循同一形态:
.on_receive_request(
{ /* async move 闭包 */ },
agent_client_protocol::on_receive_request!(), // 必须作为 final arg
)
on_receive_dispatch 则用于注册 fallback 分发处理器(见 mod.rs):它收到 Dispatch<UntypedMessage>,其中 matches_method() 恒为 true,因此能看到每一条消息。该处理器只对未知的 client→agent 请求(Dispatch::Request)回复 JSON-RPC error;对 response 和 notification 必须放行(Handled::No),否则会截获 session/request_permission 的应答并导致整个连接被错误拆掉——注释里记录了这个曾真实发生的坑(旧代码对所有响应调用 respond_with_error,导致每次审批(包括 Allow)都被当作"未处理消息",最终拆掉整个 ACP 连接)。
2.3 util::internal_error(message):统一构造内部错误
fn internal_error(message: impl ToString) -> agent_client_protocol::Error
它内部调用 Error::internal_error().data(message.to_string()),把 ToString 参数挂到错误的 data 字段上。仓库中它被用于所有"本应成功却失败"的路径,例如:
- engine.rs:spawn 失败 →
internal_error(format!("{e}")); - mod.rs:
require_engine在未配置 engine 时返回internal_error("acp: no engine configured; run via \atomcode acp`")`; - dispatch.rs:
unknown_session与kernel_dead两个终态分别用respond_with_internal_error应答 v1 的 deferred responder。
与 internal_error 相对的是 invalid_params(),用于协议层面的参数错误——两者的分野贯穿整个 ACP 实现(见下文第 6 节的失败语义)。
3. 分发循环的并发模型:单任务、非并发、cx.spawn() 逃生门
笔记第二部分引用 crate 源码注释,明确了 agent-client-protocol 连接的分发模型:
"The connection processes messages on a single async task. While a handler is running, no other messages can be processed."(连接在单个 async 任务上处理消息。当某个 handler 正在运行时,其他消息都无法被处理。)
即:单个异步任务、默认非并发。handler 会阻塞分发循环直到返回;若要并发处理,必须使用 cx.spawn()。
这一约束对 prompt turn 的影响在 mod.rs 的 session/prompt 处理器中体现得淋漓尽致:如果 handler 内联 await 整个 turn(可能持续数分钟),那么同一条连接上的 session/cancel 通知和客户端的权限应答(session/request_permission 的 response)将永远得不到处理。因此实现把 turn 用 cx.spawn(...) 移出循环,并把 deferred Responder 一并交给 spawn 出的任务:
async move |req: PromptRequest, responder, cx: ConnectionTo<Client>| {
let (text, images, has_attachments) = dispatch::prompt_text(&req);
// …
cx.spawn({
let cx = cx.clone();
async move {
dispatch::run_prompt_turn(
cx, sessions, sid, text, images, has_attachments,
responder, auto_approve, msg_ids, elicitation_form_arc.as_ref(),
).await
}
})?;
Ok(())
}
3.1 错误纪律:传输死亡 ≠ 审批故障
与并发模型配套的是一条贯穿整个 src/acp/ 的错误纪律:
cx.send_notification失败会向上传播——这是"传输死亡"(transport death),允许拆掉连接;- 审批回环(approval round-trip)失败绝不传播——审批故障是单次事件,fail-closed(默认 deny)后 turn 继续,不能让一个 ESC 或异常应答摧毁客户端整个会话线程。
这条纪律在 dispatch.rs 有明确的注释与实现:handle_approval 内部已 fail-closed 并返回 Ok,但调用侧仍做防御性兜底——万一出错,向 kernel 发送 {"decision":"deny"} 让被阻塞的调用解除,同时 eprintln! 记录原因,turn 照常进行。
3.2 共享 turn 驱动:TurnWire trait
v1 与 v2 两条链曾经各自复制一份 turn 循环,后来被收敛为 turn.rs 的协议中立驱动:TurnWire trait 定义每条链需要的协议面(notify、running_update、try_slash、translate、handle_approval_request、handle_user_input_request、on_tool_started、plan_update、session_info_update、unknown_session、kernel_dead、finish),驱动 run_turn 则把会话解析、提交、取消 watcher、事件循环、auto-title、终态映射等骨架统一写一遍。
run_turn 内部还处理了几个极易出错的细节:
$/cancel_requestwatcher:SDK 会翻转请求的取消标记,watcher 任务监听到后向 kernel 发送AgentCommand::Cancel,通过 oneshot channel 在 turn 结束时退出,避免泄漏到下一个 turn;Error事件后的TurnComplete必须排空:kernel 在Error之后总会补发一个TurnComplete,若在Error处直接 return,残留的TurnComplete会污染下一个 turn——所以循环里遇到Error只记录last_error,继续循环直到吞掉TurnComplete;- messageId 按"每个 LLM 输出轮"推进:每次
AgentEvent::Usage触发next_message_id(msg_ids),同一轮的文本/思考 chunk 共享一个 id,id变化即新消息(v1 规范语义),客户端不会再把多轮输出合并成一条消息。
4. 非 stdio 内存传输:Channel::duplex() 与端到端测试
笔记第三部分记录了 agent-client-protocol::Channel 的用途:Channel::duplex() 返回一对互相连接的 (Channel, Channel),每个 Channel 对任意 Role 实现 ConnectTo<R>,因此可以在进程内完成整条 agent 的接线,无需子进程。
4.1 传输无关的核心:serve_over
mod.rs 把 ACP 服务的核心做成传输无关的 serve_over(opts, transport),serve_stdio 只是它套上 Stdio 的薄封装:
pub async fn serve_stdio(opts: AcpServeOptions) -> anyhow::Result<()> {
serve_over(opts, Stdio::new()).await
}
serve_over 内部构建共享状态 SharedState(会话表、engine、provider factory、config option catalog、跨代共享的 message-id 计数器、客户端 elicitation form 能力标记),然后装配 v1 链与 v2 链,最后通过 SDK 2.0 提供的 Agent.protocol_router().with_v1(..).with_v2(..) 按客户端 initialize 协商的协议版本分流。T: ConnectTo<Agent> 的泛型约束让 serve_over 既能接 Stdio,也能接 Channel 端点。
4.2 测试如何复用同一套接线
crates/atomcode-cli/tests/acp_end_to_end.rs 正是笔记所描述的用法:
let (agent_channel, client_channel) = Channel::duplex();
let opts = AcpServeOptions {
engine: Some(dummy_engine()),
provider_factory: Some(Arc::new(StubProviderFactory(Arc::new(stub)))),
auto_approve: false,
..Default::default()
};
let agent_task = tokio::spawn(async move { serve_over(opts, agent_channel).await });
测试在一条端点上跑真实的生产 handler 链(serve_over),另一条端点上用 Client.builder() 驱动;LLM 侧注入 atomcode_kernel::testkit::MockProvider(kernel 自带的可脚本化 LlmProvider,通过 AcpServeOptions.provider_factory 注入,每个会话得到工厂构建的 stub),于是整条链路"无子进程、无网络"。initialize_new_prompt_streams_and_stops 覆盖了 initialize → session/new → session/prompt 全流程;另有 resume_reconnects_to_persisted_session 覆盖 create→prompt→close→list→resume→prompt→delete 的持久化链路及三类错误路径。这正是"传输无关核心"带来的直接收益:stdio 与内存通道共用一套 handler,测试即生产。
5. 从笔记到实现:v1/v2 双协议路由与能力广告
5.1 双链共享状态
SharedState(mod.rs)把九份共享绑定收敛为一个可 Clone 的 bundle,v1 与 v2 两条链都从它解构出自己的闭包捕获,消除了每个 handler 处的 Arc::clone 样板。
5.2 能力广告的"只广告已实现"原则
v1 的 initialize 响应(v1_agent_capabilities)只广告实际实现的协议面:loadSession=true、promptCapabilities.image=true、sessionCapabilities{list,delete,close,resume,additionalDirectories}、mcpCapabilities.http=true;刻意不广告 auth/fs/terminal(未实现),也不广告 MCP sse(能力层无 SSE 传输)。对应测试 v1_capabilities_only_advertise_implemented_surfaces 逐项断言 logout 为 null、fs/terminal 不存在、mcp.sse=false。v2 链同样有 v2_capabilities_only_advertise_implemented_surfaces 断言(见 v2.rs)。
5.3 v2 的差异面
v2 draft 链(v2.rs)在 session/prompt 上立即回 {} ack,进度与终态全部走 state_update(running → 流式 chunks → idle + stop reason);工具调用更新是 upsert 语义(首个 tool_call_update 即创建记录);session/resume 支持 replayFrom: "start" 全量回放;session/set_config_option 复用共享 apply_session_config_option,v1 catalog 在 wire 边界转换为 v2 形状(v1_to_v2_config_option)。两条链共享同一个会话表与 message-id 计数器,因此 wire id 与 messageId 在协议代际之间绝不冲突。
6. 会话生命周期与失败语义:fail-closed 的坚持
6.1 wire id 与原生 id 的双向还原
ACP 会话并非第二套持久化模型。wire SessionId 采用 acp-<native session id> 前缀编码(sessions.rs),wire_session_id/native_id_from_wire 双向还原,session/resume/session/delete/session/list 都通过它落到唯一的原生 SessionManager catalog。测试 wire_session_id_round_trips_native_ids 断言非本 agent 铸造的 id(如 raw-uuid)永远不是合法的 resume/delete 目标。
6.2 cwd 的严格校验
协议 MUST:cwd 必须是绝对路径。共享入口 spawn_and_register_session 在 spawn 任何东西之前校验,相对路径直接返回 invalid_params(测试 relative_cwd_is_rejected_before_spawning 同时断言会话表保持为空)。additionalDirectories 的每个条目同样必须是绝对路径(validate_additional_directories)。
resume 时还要求请求 cwd 与存储的 working_dir 匹配,但直接 PathBuf 相等太严格——编辑器可能传入尾部斜杠、冗余 . 段、.. 或符号链接路径。cwd_matches 采用三级匹配:先字节相等,再逐组件相等(词法归一化、不触碰文件系统、不 case-fold),最后对两者 pathnorm::canonicalize 解析符号链接与大小写;cwd_matches_accepts_equivalent_spellings_and_rejects_others 用六个断言覆盖了这些边界(含"不做词法 case-fold,防止把 case-sensitive 存储桶键当作同一项目")。
6.3 resume 的 fail-closed 矩阵
handle_resume_session 的失败语义是"fail-closed,绝不静默 fresh":
- 非本 agent 铸造的 wire id → invalid params;
- catalog 中无该会话 → invalid params;
- 请求
cwd与存储 cwd 不一致 → invalid params(协议将 cwd 钉死在会话上); - 会话在本进程或其他进程处于活动状态(租约冲突)→ invalid params,且明确说明"close it before resuming",绝不接管;
- catalog 查找成功后 snapshot 缺失/损坏/版本不匹配 → internal error(是竞态,不是静默 fresh 的理由)。
租约冲突专门由 map_resume_start_error 映射:RuntimeStartError::SessionInUse → invalid params,其余一律 internal error。对应的 resume_rejects_unknown_session_non_acp_id_and_cwd_mismatch 测试把三类错误路径全部钉死。
6.4 cancel / close / delete
session/cancel(notification)只取消目标会话,未知会话是故意的 no-op(客户端可能把 cancel 与已完成的 turn 竞态,静默忽略是正确协议行为),发送AgentCommand::Cancel——与全屏 UI 相同的命令(测试cancel_sends_the_contracts_cancel);session/close先取消再Shutdown,并用 5 秒超时等待事件流收尾(租约释放),未知会话同样是 no-op 成功;session/delete先拆活会话(释放租约),再经SessionManager::acquire_lease+delete删除磁盘记录;他进程持有租约时明确报错,未知会话静默成功(协议 SHOULD)。
7. prompt 内容块的消费与 turn 的终态
7.1 内容块解析:prompt_text
session/prompt 的 content blocks 被解析为 (text, images, has_attachments):
Text块按顺序拼接;Image块经 atomcode_capabilities::image_normalize 下采样/重编码(每次 turn 都会重发附件)后转为 kernel 的ImageContent;ResourceLink(协议 baseline 块,每个 agent 必须支持)被渲染为内联[resource: 名称 (uri)]标记,让引用活着进入 kernel prompt,模型可用自己的工具读取,而不是被静默丢弃;has_attachments标志专门用于把关:带附件的 prompt 绝不走本地 slash 命令拦截,必须整块交给 kernel,防止本地处理器悄悄丢掉附件。
7.2 终态映射:stop_reason
kernel 的 StopReason 精确映射到 ACP v1 stop reason:Stopped → end_turn、MaxRounds/MaxContinuations/RepeatLoop/ToolLoopDetected → max_turn_requests、Cancelled → cancelled、PromptRejected/PolicyDenied → refusal;ProviderError 等异常终态返回 Err,由调用侧转成 internal error。而"turn 正常结束但记录没能落盘"(SnapshotUnavailable)不再被报成协议失败——fold_persistence_failure 把它折进 turn 回复的文本里(测试 a_turn_that_was_not_written_down_still_finished 断言:磁盘满了时,客户端仍然收到 end_turn 终态,只是附带一句未落盘说明)。
7.3 工具调用与审批的协议流
v1 的审批流是:tool_call(pending) → session/request_permission → tool_call_update(in_progress) → completed/failed。V1Wire 用 announced: HashSet<String> 记录已被审批回环宣告为 pending 的调用,on_tool_started 对它们发 in_progress 更新而非重复创建记录(dispatch.rs);--dangerously-skip-permissions(auto_approve=true)时直接向 kernel 发 allow,不做客户端往返。v2 的工具更新是 upsert,pending 宣告本身就是记录创建,无需 announced 集合(v2.rs)。
8. 最小可运行验证:acp_stdio_agent 示例
仓库提供了 examples/acp_stdio_agent.rs,一个手动冒烟入口,可直接在 stdio 上跑默认配置的 ACP 服务:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-01-01"}}' \
| cargo run -p atomcode --example acp_stdio_agent
生产入口是 atomcode acp 子命令(由 CLI 装配 AcpServeOptions 注入 engine 与 provider factory)。此外 tests/acp_initialize.rs 提供了编译期证明:serve_stdio 符号存在、AcpServeOptions 可构造。
9. 小结
docs/acp-sdk-handler-notes.md 虽然只是一份 35 行的 spike 笔记,但它精准地划出了接入 ACP SDK 的三个关键战场:
- 闭包人体工学——
responder.respond的消费语义、on_receive_request!/on_receive_dispatch!必须作末参的过渡宏、util::internal_error的统一错误构造; - 单任务分发循环——handler 阻塞即全连接阻塞,长任务必须
cx.spawn()移出循环,同时坚持"传输死亡可拆连接、审批故障 fail-closed"的错误纪律; - 传输抽象——
serve_over把 handler 接线与传输解耦,Channel::duplex()让端到端测试跑在进程内,与生产 stdio 共用同一套代码。
顺着 docs/plans/2026-08-17-acp-sdk-2.0-protocol-roadmap.md 可以继续看到这条线后续的演进:SDK 升级到 2.0.0、v1/v2 双链经 protocol_router 分流、resume/load/list/delete 持久化落地、slash 命令与 plan 显示、elicitation 回环——而这些实现全部建立在笔记所记录的三个基础上。读代码时,"代码为准"——笔记是地图,crates/atomcode-cli/src/acp/ 才是目的地。