ACP 实现要点与坑：投产前必须过的 6 道坎#

实现一个 ACP client 不难，难在把这 6 个坑全踩一遍再爬出来——不如提前知道它们。

0. 一句话先讲明白#

真正跑到生产的 ACP client，和"能跑 demo 的 ACP client"之间隔着 6 个工程细节：session id 来源、replay 事件过滤、chunk 拼接策略、cancel 不存在时的中止策略、凭据隔离、以及进程级故障的可观测性。每个单独看都不复杂，但任何一个漏掉，系统都会在某个异常路径上静默地给出错误结果。

这 6 个坑的共同特点是：在 happy path 下完全看不见。Session/new 第一次成功了，任务回复了，你会以为一切正常。坑只在异常路径上露出来：进程重启之后、任务需要取消时、CI 报告扫描时、或者某个凌晨容器 OOM 然后没有任何日志的时候。

本节内容基于 grok 0.1.220 (ae5f4af53) 的 correctness verify（2026-05-28），并复用 02-grok 章已沉淀的 trace 素材。协议层的结论按 Agent Client Protocol SDK schema、真实 wire fixture 与源码校准；Grok/xAI 扩展或偏差会单独标注，后续版本升级时需要重新验证。

你将学到#

• 为什么 session id 不能由 client 自造