ACP 协议：AI Agent 开发的"即插即用"时代

[Pines-Cheng]

ACP 协议：AI Agent 开发的"即插即用"时代

当你还在为每个 AI 工具写一套插件时，有人已经用一个协议搞定了所有 Agent。

1. 什么是 ACP 协议

想象一下，你有一堆不同品牌的充电器——苹果一个接口，华为一个接口，小米又是另一个接口。每次换设备都得重新买充电器，是不是很烦？

Agent Client Protocol（ACP）就是 AI 编程助手领域的"USB-C 统一接口"。

简单来说，ACP 是一个基于 JSON-RPC 2.0 的开放协议，用来标准化 编辑器/IDE（Client） 和 AI 编程助手（Agent） 之间的通信方式。(现在已经扩展到各类 Web/桌面应用与 AI Agent)

• Client（客户端）：你的代码编辑器、IDE、桌面应用等，负责管理环境、处理用户交互，并控制对文件系统、终端等资源的访问
• Agent（代理）：具备代码理解、生成、重构能力的 AI 助手，比如 Claude Code、Gemini CLI、OpenCode 等

有了 ACP，任何支持该协议的编辑器都能无缝连接任何支持该协议的 AI Agent。就像当年 LSP（Language Server Protocol）统一了语言服务一样，ACP 正在统一 AI 编程助手的接入方式。

2. 为什么需要 ACP 协议

没有 ACP 之前的痛点

在 ACP 出现之前，AI 编程工具的生态是这样的：

• 每个编辑器都要为每个 AI 助手写一套插件：VS Code 一套、JetBrains 一套、Neovim 又一套
• 每个 AI 助手也要为不同编辑器分别适配：维护成本高，功能还不统一
• 用户被锁定：想用某个强大的 AI 工具？抱歉，它只支持特定的编辑器
• 开发者累，用户更累：一旦后端 API 升级，前端插件全部要跟着改

这就像 LSP 出现之前的"语言服务碎片化"时代——各 IDE 需要分别为每种语言写语法高亮、补全、跳转的实现。

ACP 解决了什么问题

ACP 的出现，彻底改变了这个局面：

✅ 解耦合：编辑器只管画界面和提供基础能力，AI 只管动脑子，中间通过标准协议连接

✅ 降低集成成本：编辑器实现一次 ACP Client，就能接入所有 ACP Agent；Agent 实现一次 ACP Server，就能在所有支持 ACP 的编辑器中使用

✅ 用户自由选择：不再被某个厂商的"编辑器+AI"组合绑定，可以自由搭配最适合自己的工具

✅ 生态繁荣：标准化降低了创新门槛，更多开发者可以快速构建新的 Agent 或 Client

用一个类比：ACP 就像是给 AI 编程工具装上了"即插即用"的接口，从此告别"专用充电器"时代。

3. ACP 协议的设计理念与实现原理

3.1 设计理念

ACP 的设计哲学非常务实，主要遵循三个核心原则：

🔌 MCP-friendly：复用而非重造

设计思路：ACP 基于 JSON-RPC 2.0 构建，并尽可能复用 MCP（Model Context Protocol） 的类型定义。

为什么重要？MCP 已经定义了一套成熟的类型系统（如 Content、Resource、Tool 等）。如果 ACP 重新发明一套自己的类型定义，开发者就需要在 ACP 和 MCP 之间做大量的类型转换。复用 MCP 类型意味着：

• Agent 处理 MCP 服务器返回的数据时，不需要做类型转换
• 开发者不需要学习两套类型定义，降低了学习成本
• 编辑器可以直接把 MCP 服务器配置传递给 Agent，Agent 无缝对接

实际影响：编辑器配置的 MCP 服务器（如文件系统、数据库、API 工具）可以直接传递给 Agent 使用，无需额外的适配层。

🎨 UX-first：为用户体验而生

设计思路：协议不仅要"能用"，更要"好用"。ACP 内置了对 AI 编程场景特有 UX 需求的支持。

解决的痛点：

1. Diff 显示：AI 修改代码时，如何让用户清楚看到改了什么？

   • ACP 定义了标准的 FilePatch 类型，支持统一格式的代码变更展示
   • 避免了每个 Agent 用自己的方式表达代码修改（有的用纯文本，有的用 JSON，有的用自定义格式）

2. 流式输出：AI 思考过程可能很长，如何实时展示进度？

   • 通过 session/update 通知，Agent 可以流式推送思考过程、生成内容、工具调用状态
   • 用户不再需要盯着一个转圈的加载动画，而是能看到 AI 正在做什么

3. 工具调用权限：AI 要读写文件、执行命令，如何让用户掌控？

   • session/request_permission 机制让用户可以审核每个操作
   • 支持"一次性允许"、"本会话允许"、"永久允许"等灵活策略

4. 多轮对话管理：如何维护上下文、恢复会话？

   • session/new 和 session/load 标准化了会话生命周期
   • Agent 可以选择性地支持会话持久化

实际影响：这些 UX 特性不是"可选的扩展"，而是协议的核心部分。这意味着所有 ACP 客户端都能提供一致的、高质量的用户体验。

🔐 Trusted：信任但可控

ACP 的安全哲学很直白：既然你选择用某个编辑器和某个 AI，那就默认你信任它们。编辑器会主动给 Agent 开放文件系统和终端访问权限，但你依然握着最终控制权。

工作方式：

编辑器给 Agent 提供文件读写、命令执行等接口。Agent 在执行敏感操作前，可以（不是必须）弹窗问你一声：

{
  "method": "session/request_permission",
  "params": {
    "toolCall": { "toolCallId": "call_001" },
    "options": [
      { "kind": "allow_once", "name": "允许一次" },
      { "kind": "allow_always", "name": "总是允许" },
      { "kind": "reject_once", "name": "拒绝" }
    ]
  }
}

你可以选"允许一次"、"总是允许"，或者直接拒绝。编辑器也可以根据你的设置自动处理这些请求。

为什么不搞沙箱隔离？

因为 AI 编程助手需要真正"干活"——读代码、改文件、跑测试。如果像浏览器那样严格限制，体验会很糟糕。ACP 选择的是"协作伙伴"模式：

• 所有操作都走标准协议，透明可追溯
• 你可以随时审核和拒绝操作
• Agent 想请求权限就请求，不想请求就直接干（反正你信任它）

简单说：Claude Code 能直接读你的项目、跑命令、改代码。它可以选择在关键操作前问你，你也可以设置"别烦我，全自动"。信任基础上的灵活控制，这就是 ACP 的安全观。

3.2 实现原理

ACP 基于 JSON-RPC 2.0 规范，采用双向通信机制，让 Agent 和 Client 可以相互调用方法和发送通知。

通信模型

协议定义了两种消息类型（类似 Chrome DevTools Protocol）：

1. Methods（方法）- 请求-响应模式

当一方需要另一方执行某个操作并等待结果时使用。每个请求都有一个唯一的 id，响应会带上相同的 id 来配对。

• 请求包含：jsonrpc、id、method、params
• 响应包含：jsonrpc、id、result（成功）或 error（失败）
• 典型场景：Client 调用 Agent 的 initialize、session/new、session/prompt 等

2. Notifications（通知）- 单向消息

用于实时推送信息，不需要等待响应。通知消息没有 id 字段，接收方收到后不会回复。

• 通知包含：jsonrpc、method、params（无 id）
• 典型场景：Agent 通过 session/update 流式推送进度、思考过程、生成内容等

💡 如果你熟悉 Chrome DevTools Protocol：ACP 的通信模型与 CDP 非常相似，都基于 JSON-RPC 2.0。Methods 对应 CDP 的命令（如 Page.navigate），Notifications 对应 CDP 的事件（如 Page.loadEventFired）。

典型示例 - 初始化请求与响应：

请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "clientInfo": {
      "name": "Zed",
      "version": "0.202.0",
      "capabilities": {
        "fs": { "readTextFile": true, "writeTextFile": true },
        "terminal": true
      }
    }
  }
}

响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "agentInfo": { "name": "Gemini CLI", "version": "1.3.0" },
    "capabilities": { "loadSession": true, "modes": ["chat", "edit"] }
  }
}

消息流程

一次完整的 AI 对话包含三个阶段：

1. 初始化：Client 发送 initialize 建立连接，协商能力（如果需要还会 authenticate）
2. 会话建立：通过 session/new 创建新会话，或 session/load 恢复已有会话
3. 对话轮次：
   • Client 发送 session/prompt（用户消息）
   • Agent 通过 session/update 流式推送进度、思考过程、工具调用
   • Agent 可以请求文件操作或权限
   • Client 可以随时 session/cancel 中断
   • 轮次结束时 Agent 返回响应和停止原因

传输方式

ACP 是传输无关的协议，适用于本地和远程场景：

本地 Agents：作为编辑器的子进程运行，通过 stdio 上的 JSON-RPC 通信。适合桌面编辑器（VS Code、Zed 等）。

远程 Agents：托管在云端或独立基础设施上，通过 HTTP 或 WebSocket 通信。适合 Web 应用、IM 机器人（飞书、Slack）、Chrome 扩展等场景。

💡 注意：远程 Agent 的全面支持仍在完善中，Streamable HTTP 传输方案正在草案阶段。

技术细节可以参考官方文档：

• 协议概览：https://agentclientprotocol.com/protocol/overview
• 架构设计：https://agentclientprotocol.com/protocol/architecture
• 消息流程：https://agentclientprotocol.com/protocol/overview#message-flow

4. ACP 协议的应用场景

ACP 不仅仅是一个技术协议，它已经在多个实际场景中落地应用。让我们看看几个典型案例：

🖥️ ACP UI：简洁的 Web 客户端

ACP UI 是一个开源的 Web 客户端实现，提供了简洁的界面来与 ACP Agent 交互。它展示了 ACP 协议的核心能力：会话管理、流式输出、工具调用权限控制等。

适用场景：快速体验 ACP 协议，或作为开发 ACP Client 的参考实现。

🎯 AionUi：多 Agent 工作台

AionUi 是一个免费开源的跨平台桌面应用，从 Gemini CLI 的本地 GUI 演变成了功能完整的"Cowork 平台"。

核心特色：

1. 内置 Agent 引擎：无需安装 CLI 工具，开箱即用

   • 零配置：用 Google 登录或填入任意 API Key 即可使用
   • 完整能力：文件读写、网页搜索、图片生成、MCP 工具支持
   • 12+ 内置助手：Cowork、PPTX 生成器、PDF 转 PPT、3D 游戏生成、UI/UX 设计等

2. 多 Agent 模式：自动检测并统一管理已安装的 CLI Agent（基于 ACP 协议）

   • 支持：Claude Code、Codex、Qwen Code、Goose、OpenClaw、Augment Code、Kimi CLI 等
   • 统一界面：一个平台管理所有 AI Agent
   • 并行会话：多个 Agent 同时运行，独立上下文
   • MCP 统一管理：配置一次，自动同步到所有 Agent

3. 随时随地 Cowork：

   • WebUI 模式：通过浏览器从手机、平板访问
   • IM 集成：支持 Telegram、飞书、钉钉、Slack
   • 定时任务：24/7 自动执行，真正的无人值守

4. 强大的文件处理：

   • 预览面板：支持 PDF、Word、Excel、PPT、代码、Markdown 等 10+ 格式
   • 智能文件管理：批量重命名、自动分类、文件合并
   • Excel 数据处理：AI 分析、自动美化、生成报告
   • 文档生成：自动生成 PPT、Word、Markdown

适用场景：想要"本地版 Claude Cowork"体验，但又不想被单一厂商锁定的开发者。你可以在同一个界面中用不同的 Agent 完成不同任务，还能设置定时任务让 AI 自动工作。

💻 Zed：原生支持 ACP 的编辑器

Zed 是 ACP 协议的发起方之一，也是最早内置 ACP Client 的编辑器。在 Zed 中，你只需要在配置文件中添加几行配置，就能接入任意 ACP Agent。

{
  "agent_servers": {
    "Gemini CLI": {
      "command": "gemini",
      "args": ["acp"]
    },
    "Claude Code": {
      "command": "claude-code",
      "args": ["--acp"]
    }
  }
}

适用场景：追求现代化编辑器体验，同时希望灵活选择 AI 助手的开发者。

🔧 JetBrains：全家桶支持

2025 年 10 月，JetBrains 正式宣布与 Zed 联合推动 ACP，并在其全家桶 IDE（IntelliJ、PyCharm、GoLand 等）中上线支持。

核心优势：整个 IDE 家族只需实现一次 ACP Client，就可以同时接入 Gemini CLI、Claude Code、OpenHands 等多种 Agent。

适用场景：JetBrains 用户现在可以在熟悉的 IDE 中，自由选择最适合的 AI 助手，不再局限于官方的 AI Assistant。

📝 其他场景

• Neovim：通过 codecompanion.nvim 插件支持 ACP
• Emacs：通过 agent-shell 以子进程方式挂载 ACP Agent
• Obsidian：通过 obsidian-agent-client 插件，在笔记中直接调用 AI 处理代码
• Marimo：将 ACP Agent 的输出映射为 Notebook 单元

完整的客户端列表可以查看：https://agentclientprotocol.com/get-started/clients

5. ACP 协议会给我们带来什么改变？

a. 从"手动对接"到"即插即用"

以前，每次想用一个新的 AI 编程工具，你都要：

1. 查看它支持哪些编辑器
2. 安装对应的插件
3. 配置一堆参数
4. 祈祷它能正常工作

现在，只要你的编辑器支持 ACP，任何 ACP Agent 都能直接用。就像插 USB 设备一样简单。

b. 不仅是连接，更是体验标准化

ACP 的野心不止于解决连接问题。它还要解决 AI Agent 交互中的 UX 难题：

• Diff 显示：如何清晰展示代码变更？
• 流式更新：如何实时展示 AI 的思考过程？
• 工具调用权限控制：如何让用户掌控 AI 的操作？
• 多轮对话管理：如何维护上下文和会话状态？

这些是每个 Agent × Editor 组合都要重新发明的轮子，ACP 把它们标准化了。

开发者不再需要关注这些基础设施，可以把精力集中在：

• 如何通过 Skills 构建用户场景
• 如何打造更好的产品体验
• 如何解决实际的编程问题

c. 繁荣的生态系统正在形成

标准化带来的最大好处是降低创新门槛。未来会出现：

• 更多基于 ACP 的客户端：不仅是编辑器，还有专门的桌面应用、Web 应用、移动端应用
• 更多基于 ACP 的 Agent：开源社区和商业公司都能快速构建新的 AI 助手
• 更多基于 ACP 的工具和插件：比如专门的权限管理工具、会话分析工具、协作工具等

就像 LSP 催生了 VS Code 插件生态一样，ACP 正在催生一个全新的 AI 编程工具生态。

6. 当前生态概览

a. 已有的 Agent 客户端

部分展示如下：

客户端	类型	特点
ACP UI	Web 应用	开源 Web 客户端，展示核心协议能力，适合快速体验
AionUi	桌面应用	内置 Agent 引擎 + 多 Agent 管理，支持定时任务、WebUI、IM 集成
Zed	代码编辑器	ACP 发起方，原生支持，配置简单，现代化体验
JetBrains IDEs	IDE 家族	IntelliJ/PyCharm/GoLand 等全家桶支持，企业级功能
Neovim	文本编辑器	通过 CodeCompanion/agentic.nvim 等插件支持
Emacs	文本编辑器	通过 agent-shell.el 以子进程方式挂载 Agent
Obsidian	笔记软件	通过插件在笔记中直接调用 AI 处理代码和内容
Marimo	Notebook	将 Agent 输出映射为 Notebook 单元，适合科学计算

完整列表：https://agentclientprotocol.com/get-started/clients

b. 已有的 Agent 服务端

部分展示如下：

Agent	提供方	特点
Gemini CLI	Google	Google 官方实现，多模态能力强
Claude Code	Anthropic	代码理解和生成能力出色
OpenCode	开源社区	完全开源，支持自定义模型和工具，灵活可扩展
Qwen Code	阿里云	基于通义千问，中文支持好，适合国内开发者
Kimi CLI	Moonshot AI	支持 200K+ 超长上下文，适合大型项目分析
Goose	开源社区	轻量级设计，快速启动，适合简单任务
OpenHands	开源社区	专注多步骤复杂任务，支持完整开发流程
Augment Code	Augment	商业化产品，企业级支持，集成度高

目前已有 27+ 个 Agent 支持 ACP 协议，完整列表：https://agentclientprotocol.com/get-started/agents

c. 协议规范与草案

核心协议

协议模块	功能	状态	文档
Initialization	建立连接、协商协议版本、交换 Client 和 Agent 的能力声明	✅ 稳定	详细文档
Session Setup	创建新会话、加载已有会话、管理会话生命周期和状态	✅ 稳定	详细文档
Prompt Turn	处理用户输入、Agent 流式响应、工具调用、取消操作	✅ 稳定	详细文档
Content	文本、图片、资源、Diff、Plan 等多种内容类型	✅ 稳定	详细文档
Tool Calls	工具调用报告、权限请求、状态跟踪、Diff 展示	✅ 稳定	详细文档
File System	文件读取、写入、列表、搜索等文件系统操作	✅ 稳定	详细文档
Terminals	创建终端、执行命令、实时输出、终端管理	✅ 稳定	详细文档
Agent Plan	Agent 计划展示，让用户了解 Agent 的执行步骤和进度	✅ 稳定	详细文档
Session Modes	会话模式管理（如 chat、edit 等不同交互模式）	✅ 稳定	详细文档
Session Config Options	会话配置选项，支持更灵活的会话管理	✅ 稳定	详细文档
Slash Commands	斜杠命令支持，快速触发特定功能	✅ 稳定	详细文档
Transports	传输层协议，支持 stdio、HTTP、WebSocket 等多种传输方式	✅ 稳定	详细文档

扩展机制

Agent Client Protocol 提供了内置的扩展机制，允许实现添加自定义功能，同时保持与核心协议的兼容性。这些机制确保 Agent 和 Client 可以进行创新，而不会破坏互操作性。

扩展类型	功能	状态	文档
Custom Methods	通过 _ 前缀定义私有方法，实现特定功能扩展	✅ 支持	详细文档
Meta Fields	在任何对象中添加 _meta 字段，携带自定义元数据	✅ 支持	详细文档
Custom Capabilities	在能力声明中添加自定义字段，声明特定功能支持	✅ 支持	详细文档

RFC 草案（RFDs）

ACP 社区正在通过 RFD（Request for Dialog）流程推进协议演进。以下是部分有代表性的草案：

会话管理相关：

RFD	主题	功能描述	状态
Session Fork	会话分叉	允许从现有会话创建分支，探索不同的解决方案路径	📝 草案
Session Resume	会话恢复	支持恢复已有会话，保持上下文连续性	📝 草案
Session Delete	会话删除	允许 Client 删除指定会话，管理会话生命周期	📝 草案
Session Stop	停止会话	停止活动会话的执行	📝 草案

扩展与集成：

RFD	主题	功能描述	状态
MCP-over-ACP	MCP 传输	通过 ACP 通道传输 MCP 消息，实现无缝工具注入	📝 草案
Agent Proxies	Agent 代理	通过 ACP 代理扩展 Agent 功能	📝 草案
Agent Telemetry	遥测导出	Agent 遥测数据导出，支持性能监控和分析	📝 草案

安全与认证：

RFD	主题	功能描述	状态
Authentication Methods	认证方法	支持多种身份验证方式	📝 草案
Logout Method	注销方法	用户注销和会话清理	📝 草案

交互增强：

RFD	主题	功能描述	状态
Elicitation	结构化输入	会话期间的结构化用户输入，提升交互体验	📝 草案
Request Cancellation	请求取消	请求取消机制，让用户可以中断正在执行的操作	📝 草案

💡 注意：ACP 协议仍在持续演进中，RFD 状态可能随时变化。部分草案可能已被合并到核心协议，部分可能已被废弃。请以官方最新信息为准。

查看所有 RFD：https://agentclientprotocol.com/rfds/about

协议更新动态：https://agentclientprotocol.com/updates

协议概览：https://agentclientprotocol.com/protocol/overview

7. 总结与展望

AI 时代，只有产品先发优势，没有技术先发优势

这是一个残酷但真实的现实。前面花一两个月吭哧吭哧撸的功能，现在基于社区和标准协议，两三天就能搞定。

ACP 协议的意义，就在于让开发者站在巨人的肩膀上。

专注于真正重要的事情

有了 ACP，那些重复造轮子的活儿终于可以省了。Chat 交互界面、内容展示格式、流式输出、会话管理、Slash 命令解析、工具调用权限控制、Agent 服务端对接……这些基础设施都已经标准化了。

开发者可以把时间花在真正有价值的地方：通过 Skills 构建用户场景，打造更好的产品体验，解决实际的编程问题。

未来已来

ACP 协议的出现，标志着 AI 编程工具进入了"即插即用"时代。就像当年 USB 接口统一了外设连接，LSP 统一了语言服务一样，ACP 正在统一 AI 编程助手的接入方式。

这不仅仅是一个技术协议，更是一场生态革命：

• 用户获得了自由选择的权利
• 开发者降低了集成成本
• 创新者获得了更低的门槛

当标准化的基础设施就位，真正的创新才刚刚开始。

---

相关链接：

• ACP 官方网站：https://agentclientprotocol.com/
• ACP 协议概览：https://agentclientprotocol.com/protocol/overview
• 客户端列表：https://agentclientprotocol.com/get-started/clients
• Agent 列表：https://agentclientprotocol.com/get-started/agents
• RFC 草案：https://agentclientprotocol.com/rfds/about

开始行动：

1. 如果你是编辑器用户，试试 Zed 或 JetBrains 的 ACP 支持
2. 如果你想要桌面体验，试试 AionUi
3. 如果你是开发者，看看如何把你的工具接入 ACP 生态

AI 编程的未来，是开放的、标准化的、可组合的。ACP 协议，正在让这个未来成为现实。

[Pines-Cheng]

包括大名鼎鼎的 OpenClaw 也接入了 Agent Client Protocol (ACP)，会话允许 OpenClaw 通过 ACP 后端插件运行外部编码框架 （例如 Pi、Claude Code、Codex、OpenCode 和 Gemini CLI）。
如果你用简单的语言请求 OpenClaw “在 Codex 中运行此” 或 “在线程中启动 Claude Code”，OpenClaw 应该将该请求路由到 ACP 运行时（而不是原生的子 Agent 运行时）。
详细可见：https://docs.openclaw.ai/tools/acp-agents

[ke1vin4real]

写得很好，来个rss吧