70行Python驱动Gemini：ACP协议拆开看

2025年8月，Zed团队想把第三方智能体塞进自家编辑器，写下一句判断：需要"一种比 ANSI 转义码更有结构的通信方式"。靠解析终端界面去猜智能体在干什么，只要对方重绘一次屏幕，解析就崩。

他们的答案是 Agent Client Protocol，简称 ACP：一套 Apache 许可的 JSON-RPC 方法集，2025年8月27日公布，Google 的 Gemini CLI 是"最初的参考实现"。五个月后，2026年1月28日，Zed 与 JetBrains 合作开放 ACP Registry——智能体注册一次，所有会说这套协议的编辑器里都能出现。

而你要做的，只是用大约 70 行 Python，向 Gemini CLI 发出编辑器会发的四个请求，并逐行读回它的每一条应答。

管道里跑的是什么

ACP 就是 JSON-RPC 2.0。编辑器（客户端）把智能体作为子进程拉起，往它的 stdin 写消息，从 stdout 读消息。每条消息占一行：传输规范要求消息"以换行符分隔"，且"禁止"内嵌换行。日志如果有，走 stderr，stdout 上不许有别的东西。

消息分两类。方法（method）是请求与响应的配对，靠 id 对上号；通知（notification）是单向的，不收回执。流量是双向的：编辑器调用智能体（initialize、session/new、session/prompt），智能体也会回调编辑器（session/request_permission，以及可选的 fs/read_text_file、fs/write_text_file 和 terminal/* 系列方法——前提是编辑器声明支持）。

一轮提示有固定形状：编辑器发 session/prompt，智能体边干活边流式发 session/update 通知，中途可能停下来要权限，最后用原始 session/prompt 请求的应答收尾，附一个停止原因。在那个应答到达之前，这一轮都算还在跑。

把 Gemini CLI 拉进 ACP 模式

用 npm install -g @google/gemini-cli 装好，开关是 --acp。旧教程写的是 --experimental-acp，当前源码仍然接受，帮助文本标注"已弃用，请改用 --acp"。ACP 模式文档也用 gemini --acp，但 CLI 参考页还只列着旧开关，跑一下 gemini --help 确认你手上的版本。

动手前有个坑。Gemini CLI 的 README 写着："未付费层与 Google One 用户：Gemini CLI 已于 2026年6月18日被 Antigravity CLI 取代。"下面的脚本用 Gemini API key 登录，这是 Gemini CLI 仍提供的方式之一。如果你的 key 在未付费层，先确认它还能用。

整个客户端做的事很朴素：打印发出的每一行（>>）和收到的每一行（<<），用 json.dumps 保证一行内没有换行，正好符合传输要求。判断消息类型时看有没有 method 字段——智能体给自己发的请求挑 id，一个权限请求可能和你的某个请求撞 id，请求带 method、响应不带，这就是区分依据。

编辑器会发的四个请求

把下面这段接在同一个文件后面，在 ~/code/acp-scratch 这类临时目录里跑，因为提示词会让智能体在那里建文件。

• initialize：商定协议版本（规范示例用 1），交换能力。这里客户端声明自己不能替智能体读文件、写文件、跑终端，Gemini CLI 的文件服务于是回退到本地磁盘。作为回应，Gemini CLI 公布 loadSession、图像/音频/内嵌上下文提示、HTTP 与 SSE 上的 MCP，以及四种登录方式：Google 登录、Gemini API key、Vertex AI、AI API Gateway。
• authenticate：挑一种。API key 方式的 id 是 gemini-api-key，处理逻辑从 _meta["api-key"] 读 key，同时把你选的方式写进 Gemini CLI 的用户设置。
• session/new：开一段对话。cwd "必须是绝对路径"，mcpServers 是编辑器把自己的工具交给智能体的地方，结果里带回 sessionId。
• session/prompt：把你的消息作为内容块列表发出去。斜杠命令也走这条路，就是一段纯文本，比如 /web agent client protocol。

读回来的东西怎么解

一轮进行中，智能体发 session/update 通知，每条带 params.sessionId 和 params.update，update.sessionUpdate 指明变体。规范自带的工具调用示例长这样：

{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"sess_abc123def456","update":{"sessionUpdate":"tool_call","toolCallId":"call_001","title":"Analyzing Python code","kind":"other","status":"pending"}}}

Gemini CLI 的会话代码会发这些变体：agent_message_chunk（流式回复）、agent_thought_chunk（推理过程）、user_message_chunk、tool_call、tool_call_update、usage_update，以及列出它接受哪些斜杠命令的 available_commands_update。

工具调用带一个 kind，编辑器据此选图标：read、edit、delete、move、search、execute、think、fetch、switch_mode、other。status 在 pending、in_progress、completed、failed 之间流转，tool_call_update 只带发生变化的字段。

当智能体想写 hello.txt，它会停下来调用 session/request_permission。文件编辑场景下，Gemini CLI 用自己的确认结果构造选项；如果配置里关了 always-allow，"本次会话允许"那一行就不出现，只有开了永久批准才会多出第四个"所有未来会话"选项。脚本用请求自己的 id 回 {"outcome": {"outcome": "selected", "optionId": "proceed_once"}}。若你用 session/cancel 通知取消一轮，规范要求客户端对任何未决的权限请求回 {"outcome": {"outcome": "cancelled"}}。

这一轮在请求 3 的应答到达时结束，正常情况是 {"result": {"stopReason": "end_turn"}}。其余停止原因有 max_tokens、max_turn_requests、refusal、cancelled。这就是完整的一轮。声明了文件与终端支持的编辑器还会收到 fs/* 和 terminal/* 调用；除此之外，Zed 的智能体面板或 JetBrains IDE 读到的消息类型，和你的脚本读到的一样。

另一条路：智能体自己的终端

Hermes 走的是反方向。每个智能体，包括 Gemini CLI，都在真实终端里跑自己的界面，"和它在别处跑完全一样，所以厂商的新命令和新模式在发布当天就能在 Hermes 里用"。什么都不翻译，也就不存在等翻译追上来的问题。

Hermes 加在终端外围：每个任务一个分支和 worktree，每个会话一个状态（是猜的会标出来），一个等你处理的智能体收件箱，以及每一轮都存下来、可以单独 diff 或还原。它从不替你回答权限提示，也从不自己往终端里打字。Gemini CLI 在 Hermes 里请求写 hello.txt 时，你在 Gemini CLI 自己的提示里回答，不是在 Hermes 的按钮上。

Hermes 的设计记录 ADR 003 把 ACP 列为它愿意构建的那类协议。结构化视图只在厂商提供有文档、稳定的机器协议（"Claude Agent SDK 流、ACP、Codex app server"）、该视图能提供终端给不了的东西、且你主动开启时才建。目前这个视图只对 Claude 存在，作为可选的 Agent view。

两种设计各自放弃了什么

ACP 给编辑器的是带类型的事件：权限请求带着工具 kind 和固定选项列表，编辑器能画自己的批准按钮；文件访问可以走编辑器，智能体看到的就是编辑器允许的；一次集成就能触达注册表里的每个客户端——Claude Code、Codex CLI、GitHub Copilot CLI、OpenCode、Gemini CLI 都在列。

ACP 放弃的是智能体自己的界面。编辑器显示的是协议承载的东西，以及智能体或其适配器映射进去的东西。Claude Code 和 Codex 并不原生说 ACP，Zed 靠自建适配器接上两者；Zed 的 Claude Code 集成是"包住 Claude Code SDK 的适配器"，2025年9月上线时 Zed 就指出"许多内置斜杠命令尚未被 SDK 支持"。这个缺口后来可能补上了，但任何适配器都可能落后于它包着的 CLI。

终端路线放弃的是带类型的流。Hermes 画不出 Gemini CLI 的工具调用卡片，它对终端智能体的状态有时是推断的（并标注为推断），每次工具调用你都在智能体自己的界面里批准。换来的是厂商原封不动的界面，以及厂商发布变更的当天就能用上。

要一个跨多个智能体的原生统一界面，ACP 是更好的设计；要每个智能体都保持厂商出厂的样子并排跑，终端赢。你那边是怎么跑的？