ACP (Agent Client Protocol)

什么是 ACP

ACP（Agent Client Protocol）是 Zed Industries 提出的开放协议（Apache 2.0），用来标准化代码编辑器与 AI 编码 agent 之间的通信。它用 JSON-RPC 2.0 跑在 stdin/stdout 双向流上：编辑器把 agent 当子进程拉起，双方交换换行分隔的 JSON 消息。

核心价值是「一次实现，处处可用」——任何支持 ACP 的 agent 都能在任何支持 ACP 的编辑器里跑，不需要为每个编辑器单独做集成。

最贴切的类比是 LSP（Language Server Protocol）。LSP 让一个语言服务器能在所有编辑器里提供补全/跳转；ACP 让一个 AI agent 能在所有编辑器里提供对话/工具调用/文件编辑。ACP 就是「AI agent 版的 LSP」。

解决什么问题

在 ACP 之前，agent 和编辑器是 N×M 的适配地狱：

• Claude Code 要单独适配 Zed、Neovim、JetBrains……
• 每个编辑器要单独对接 Claude Code、Codex、Gemini CLI……

Block 的 goose 团队把这形容为「三个应用问题」：开发者得同时开编辑器、agent 窗口、浏览器。ACP 把 agent 收进编辑器，砍掉一个窗口。每加一个 agent 或一个编辑器，只要实现一次 ACP，就和生态里所有另一侧打通。

工作原理

ACP 用 JSON-RPC 2.0 over stdio，生命周期大致是：

1. initialize        协商协议版本与能力（文件系统/终端/MCP）
2. session/new       新建会话（传入 CWD、MCP server 配置）
3. session/prompt    客户端发用户消息（ContentBlock[]：文本/图片/音频）
4. session/update    agent 流式回传（消息块、工具调用、计划）
5. 回调客户端         fs/read_text_file、fs/write_text_file、
                     terminal/create、session/request_permission

几个关键点：

• 传输层：stdin/stdout，UTF-8，JSON-RPC 2.0，协议版本是 uint16，只有破坏性变更才递增
• 双向：agent 不只是被动应答，还能回调客户端读写文件、开终端、申请权限（human-in-the-loop）
• 流式：session/update 把消息块、工具调用、执行计划实时推给编辑器

谁在用

由 Zed 和 JetBrains 背书，Google 的 Gemini CLI 是参考实现。VS Code 截至 2026 年 3 月无原生支持（微软把 agent mode 押在 MCP 上），仅有社区扩展 vscode-acp。

ACP vs MCP

新人最容易混淆这两个协议，但它们解决完全不同的问题：

二者协同：ACP 会话启动时，编辑器把 MCP server 端点传给 agent，于是 agent 一边通过 ACP 跟编辑器交互，一边通过 MCP 调用工具。ACP 不是要取代 MCP。

怎么用（Zed 接入自定义 agent）

在 ~/.config/zed/settings.json 里加 agent server：

{
  "agent_servers": {
    "My ACP Agent": {
      "type": "custom",
      "command": "my-agent",
      "args": ["acp"],
      "env": {}
    }
  }
}

然后在 Zed 的 Agent 面板选择它即可。Python 侧可以 pip install agent-client-protocol（需 3.10+），提供异步基类和 stdio JSON-RPC transport。

常见踩坑

• 以为 ACP 取代 MCP：不是。一个管「编辑器↔agent」，一个管「agent↔工具」，生产里通常两个一起用。
• 指望 VS Code 原生支持：截至 2026 年 3 月还没有，VS Code 走的是 MCP 路线。需要在 VS Code 里用得靠社区扩展。
• Claude Code 是桥接不是原生：Anthropic 没原生采用 ACP，是 Zed 做了桥接适配器包了一层。功能基本可用但要知道这层关系。
• 协议还在迭代：2026 年 3 月到 v0.11.0，版本仍在演进，跟进 breaking change。

延伸阅读

• 工具协议：MCP——agent ↔ 工具的标准
• agent 协作：A2A——agent ↔ agent 的标准
• 项目约定：AGENTS.md——给 agent 的项目说明
• 编辑器：Zed / 工具：Gemini CLI