目录[隐藏]
一、为什么会出现 ACP？二、ACP 是什么？和 IBM 的 ACP 有何不同？2.1 定义：Agent Client Protocol（Zed 社区主推）2.2 注意不要和 IBM 的 ACP 混淆三、从 0 开始理解 ACP：架构与消息模型3.1 整体架构：谁是 Client，谁是 Server？3.2 消息模型：基于 JSON-RPC 2.03.3 一次完整交互的“生命周期”3.4 扩展机制：既要“统一”，也要“生长”四、开发者视角：如何把自己的工具“接上 ACP 总线”？4.1 生态中的官方 SDK4.2 用 Python 写一个最简 ACP Agent 的思路4.3 如果你是“编辑器 / UI”开发者，该做什么？五、从“能用”到“好用”：实际应用实践和案例5.1 桌面端“多 Agent 工作台”：AionUi5.2 基于 Electron + React 的 Open Claude Cowork5.3 IDE 编辑器：Zed & JetBrains & Neovim & Emacs5.4 Agent / CLI 侧的 ACP 实现六、如何在团队中落地 ACP？实战建议6.1 如果你负责“编辑器 / 内部开发工具”6.2 如果你负责“Agent / 智能体平台”七、小结：ACP 在整个智能体协议版图中的位置八、行动建议如果你是个人开发者 / 工程师如果你是工具 / 平台开发者如果你是架构师 / 技术负责人九、相关参考
一、为什么会出现 ACP？
——AI 编码时代的新“统一接口”问题
近两年，AI 编码助手爆发式增长：GitHub Copilot、Claude Code、Gemini CLI、OpenHands、Qwen Code、Kimi CLI、OpenCode……但开发体验却愈发割裂：
每个编辑器都要为每一个 AI 助手写一套插件：VS Code 一套、JetBrains 一套、Neovim/Emacs 再一套
每个 AI 助手也要为不同编辑器分别适配：维护成本高、功能还不统一
一旦后端 API 或交互模式升级，前端插件全部要跟着改
这和 LSP 出现之前的“语言服务碎片化” 极其相似：
在 LSP 之前，各 IDE 需要分别为每种语言写语法高亮、补全、跳转的实现。LSP 把“语言服务”抽象出来统一标准，极大降低了集成成本。
在 AI 编码时代，我们遇到的是类似但更复杂的问题：
如何让“任意编辑器”可以连接“任意 AI 编码代理”，而不是被某一家厂商的“编辑器+AI”捆绑？
Agent Client Protocol（ACP）正是为此而生。
二、ACP 是什么？和 IBM 的 ACP 有何不同？
2.1 定义：Agent Client Protocol（Zed 社区主推）
Agent Client Protocol（ACP） 是一个基于 JSON-RPC 2.0 的开放协议，用来标准化：
客户端（Client）：编辑器 / IDE / 终端 UI / 桌面应用
代理（Agent）：具备代码理解、生成、重构能力的 AI 编码代理（往往基于大模型 + 工具调用）
之间的通信方式与语义。
一句话概括它的目标：
让 任何编辑器 都可以无缝连接 任何 AI 编码代理，就像 LSP 统一语言服务那样，统一 AI 编码体验。[1][2]
2.2 注意不要和 IBM 的 ACP 混淆
当前“ACP”有两条主线，需要明确区分：
名称
全称
核心对象
典型场景
Agent Client Protocol
Agent Client Protocol（Zed）
编辑器 / IDE ↔ AI 编码代理
Zed、JetBrains、Neovim、桌面应用连接 Gemini CLI、Claude Code、OpenHands 等
Agent Communication Protocol
Agent Communication Protocol（IBM 等）
Agent ↔ Agent、应用 ↔ Agent
多智能体之间通信、跨系统编排
本文中如不特别说明，“ACP”均指 Zed 社区主导的 Agent Client Protocol。
三、从 0 开始理解 ACP：架构与消息模型
3.1 整体架构：谁是 Client，谁是 Server？
在 ACP 中：
Client = 编辑器 / UI 端
掌握本地文件系统、终端、权限确认 UI
Server = AI 代理
掌握大模型推理、代码生成、工具编排能力
典型架构如下：
+---------------------------+ JSON-RPC (stdio/pipe/TCP) +------------------------+
| Editor / IDE / GUI | <-------------------------------> | Coding Agent (ACP) |
| (Zed / JetBrains / | | (Gemini CLI / |
| AionUi / Open Cowork) | | Claude Code / etc.) |
+---------------------------+ +------------------------+
↑ ↑
| 提供：文件系统、终端、权限 UI | 执行：分析、规划、生成代码
| |
人机交互 & 环境层 智能决策 & 执行层
这种划分有两个关键好处：
安全：代理不直接“裸奔”访问本地文件与终端，一切都走 Client 提供的受控接口 + 权限确认
可组合：代理可以是本地 CLI 工具，也可以是远程服务，只要说“ACP 这门语言”就能挂载到各种编辑器 / 桌面 UI 上
3.2 消息模型：基于 JSON-RPC 2.0
ACP 严格遵守 JSON-RPC 2.0 标准，[3] 把所有交互规范化为两类消息：
Request / Response（请求-响应）
Notification（通知，无需响应）
请求示例：initialize
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"clientInfo": {
"name": "Zed",
"version": "0.202.0",
"capabilities": {
"fs": {
"readTextFile": true,
"writeTextFile": true
},
"terminal": true
}
}
}
}
响应示例：initializeResult
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"agentInfo": {
"name": "Gemini CLI",
"version": "1.3.0"
},
"capabilities": {
"loadSession": true,
"modes": ["chat", "edit"]
}
}
}
通知示例：session/update（流式输出）
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "abc-123",
"updates": [
{ "type": "messageChunk", "role": "assistant", "content": "正在分析你的项目结构…" }
]
}
}
3.3 一次完整交互的“生命周期”
从编辑器视角看，一次使用 AI 的完整流程可以拆解为 4 步：
初始化
initialize：能力协商（双方是谁、都能干什么）
会话建立
session/new：新建会话
session/load：加载旧会话（取决于代理是否声明支持）
对话 & 操作过程
session/prompt：发送用户请求（附上下文）
代理通过 session/update 持续推送计划、生成内容、进度
用户或编辑器可发送 session/cancel 终止
工具调用 & 权限
当代理需要读写文件或执行命令时：
通过 session/request_permission 请求授权
由 Client 通过 UI 询问用户是否允许
通过 fs/*、terminal/* 调用具体能力
这个生命周期在多个实际产品中被一再验证，例如 Gemini CLI、Claude Code、OpenHands 与 JetBrains / Zed / AionUi 的集成。
3.4 扩展机制：既要“统一”，也要“生长”
为了避免重蹈“一上新功能就得改协议核心”的覆辙，ACP 提供了类似 LSP 的扩展能力：
自定义方法：以 _ 前缀区分实验 / 私有扩展，例如 _symmacp/pipeline
扩展元数据：统一放在 _meta 中，避免污染主结构
能力声明：所有扩展在 initialize 里通过 capabilities 广而告之
这保证了：
主协议稳定，可长期演化
厂商 & 社区可以在不破坏兼容性的前提下进行创新
四、开发者视角：如何把自己的工具“接上 ACP 总线”？
4.1 生态中的官方 SDK
为了降低接入门槛，ACP 提供了多语言 SDK，封装了：
面向协议的 Pydantic / struct 类型模型（防止字段乱写）
基于 asyncio / async 的传输和消息收发
Agent / Client 抽象基类，简化实现过程
目前主流语言支持包括[2][4]：
语言
SDK 包名
Python
agent-client-protocol
Rust
agent-client-protocol
Kotlin
acp-kotlin
TypeScript
@agentclientprotocol/sdk
4.2 用 Python 写一个最简 ACP Agent 的思路
下面是一个抽象化的示例（简化版，帮助你快速建立直觉）：
from acp import Agent, schema
import asyncio
class SimpleAgent(Agent):
async def initialize(self, params: schema.InitializeParams) -> schema.InitializeResult:
"""处理初始化请求"""
return schema.InitializeResult(
agentInfo={"name": "simple-agent", "version": "0.1"},
capabilities={"loadSession": False}
)
async def session_new(self, params: schema.SessionNewParams) -> schema.SessionNewResult:
"""创建新会话"""
return schema.SessionNewResult(sessionId="session-1")
async def session_prompt(self, params: schema.SessionPromptParams) -> schema.SessionPromptResult:
"""处理用户请求"""
await self.send_session_update(
schema.SessionUpdateParams(
sessionId=params.sessionId,
updates=[schema.MessageChunk(type="messageChunk", content="思考中…")]
)
)
return schema.SessionPromptResult(
stopReason="completed",
response=f"Echo: {params.prompt}"
)
if __name__ == "__main__":
agent = SimpleAgent()
asyncio.run(agent.serve_stdio()) # 通过 stdio 与 ACP 客户端通讯
然后你只需在 Zed / JetBrains / AionUi 的配置里，写上类似：
{
"agent_servers": {
"My Simple Agent": {
"command": "python",
"args": ["-m", "my_simple_agent_module"]
}
}
}
即可把你的 Agent 挂到对应 IDE 里使用。
4.3 如果你是“编辑器 / UI”开发者，该做什么？
你需要实现一个 ACP Client 层，其职责包括：
启动 Agent 进程：按用户配置执行 command + args
维护 JSON-RPC 连接：通过 stdio / socket 读写 NDJSON 流
协议调度：
框架层统一处理 initialize、session/new、session/prompt 等
将 session/update 映射到 UI：流式输出、Patch 展示、权限弹窗
能力适配：
把 IDE 的文件 API 映射为 ACP 的 fs/* 方法
把内置终端映射为 terminal/* 方法
JetBrains 在 2025 年底发布的 ACP 支持，就是经典示例：整个 IDE 家族（IntelliJ、GoLand、PyCharm 等）只需实现一次 ACP Client，就可以同时接入 Gemini CLI、Claude Code、OpenHands 等多种 Agent。[5]
五、从“能用”到“好用”：实际应用实践和案例
这一部分我们按照“使用者角度”来拆解，从桌面应用、IDE 编辑器、CLI Agent 三个维度看 ACP 的实战落地。
5.1 桌面端“多 Agent 工作台”：AionUi
AionUi 是什么？
一个免费、开源的跨平台桌面 GUI，最初是 Gemini CLI 的本地 UI
后来加入了 Multi-Agent 模式，通过 ACP 把各种 CLI Agent 接在一起，变成一个本地“Cowork 工作台”[6]
和 ACP 的关系
AionUi 自身实现的是 ACP Client
它可以识别并连接本机上任何 ACP 兼容的 Agent CLI，例如：
Claude Code (claude)
Qwen Code (qwen --acp)
OpenCode (opencode acp)
Goose (goose acp)
Augment Code (auggie --acp)
Kimi CLI (kimi --acp)
以及后续持续增加的社区 Agent
用户体验上，你能获得什么？
在一个统一的 GUI 里：
用 Gemini 跑分析
用 Qwen Code 改代码
用 OpenCode 做大规模重构
当 Agent 需要读写文件、运行命令时，AionUi 会按 ACP 协议弹出权限确认窗口
所有对话、任务状态都持久化到本地，重启后可恢复
对于想要“本地版本 Claude Cowork / Copilot Workspace”体验，但又不想被单一厂商锁死的人来说，AionUi + ACP 是一个非常现实可行的路径。
5.2 基于 Electron + React 的 Open Claude Cowork
社区中有多个“Open Claude Cowork / Open Cowork”项目，其中有一支路线明确是 以 ACP 为底层协议，用 Electron + React 做桌面端多 Agent 协作工具。[7]
其核心设计可以概括为四个类：
AcpDetector：扫描本地可用 CLI（如 claude, qwen, opencode acp 等）
AcpAgentManager：管理多个 Agent 实例、连接复用
AcpAgent：封装会话级逻辑（initialize → newSession → prompt），支持 @file 语法引用文件
AcpConnection：与具体 Agent 的 JSON-RPC 底层连接，基于 NDJSON 流
关键能力：
多 Agent 并行，在一个 UI 中管理多个“项目任务”
使用 SQLite 做任务 / 会话的持久化存储，重启后可继续协作
对 ACP 中的权限请求进行 UI 弹窗拦截，增加超时和取消机制
可以把它理解为：
用 ACP 把一堆不同厂家的“Claude Code 类工具”挂载到一个本地桌面端，统一操作、统一审计、统一安全策略。
5.3 IDE 编辑器：Zed & JetBrains & Neovim & Emacs
Zed 作为 ACP 的发起方，[1][2] 是最早一批内置 ACP Client 的编辑器：
在 settings.json 中配置 agents 和命令，即可连接任意本地 ACP Agent
支持多个 Agent 并行挂载：如 “Gemini CLI + Claude Code + OpenHands” 同时在线
JetBrains 则在 2025 年底正式宣布与 Zed 联合推动 ACP，并在其全家桶 IDE 中上线支持[5]：
在 AI 设置中，除了官方 AI Assistant 外，还多了 “ACP Agent” 选项
用户可以选择本地命令作为后端，例如：
opencode acp
kimi --acp
qwen --acp
Neovim / Emacs / Obsidian / Marimo 等 通过各自的插件，也实现了 ACP Client 能力：
Neovim：如 codecompanion.nvim，通过
Emacs：agent-shell，以子进程方式挂载 ACP Agent
Obsidian：在笔记中选中代码块直接交给 ACP Agent 处理
Marimo：将 ACP Agent 的输出映射为 Notebook 单元
这些集成的共同点是：
一次实现 ACP Client → 后续可“插拔”任意 ACP Agent
对 Agent 的交互能力高度一致：
Chat 面板、内联编辑、带解释的重构操作
执行测试 / 命令、展示文件改动 diff
5.4 Agent / CLI 侧的 ACP 实现
目前已经宣布支持 ACP 的 Agent / CLI 工具有：
Gemini CLI：官方参考实现（Zed 首批集成对象）
Claude Code：通过 claude-code-acp（TS 实现）或社区的 Rust 版本[8]
OpenHands：openhands acp，可将复杂的多步骤开发任务抽象为一个 ACP Agent
clawdbot(Moltbot): 一款开源的、本地优先（Local-First）的个人 AI 助手。其核心理念是让 AI 真正“驻留”在你的设备或私有服务器上，并通过你日常使用的通讯软件（如 WhatsApp, Telegram, Discord, Slack 等）为你提供服务。
Goose、Augment Code（Auggie）、Qwen Code、Kimi CLI、OpenCode 等
典型用法往往类似：
# 启动一个 ACP server
qwen --acp
opencode acp
kimi --acp
goose acp
clawdbot acp
然后在任何 ACP 客户端（Zed / JetBrains / AionUi / Open Cowork / Toad）中把对应命令填进去即可。
六、如何在团队中落地 ACP？实战建议
假设你所在团队有两个诉求：
想在公司主力 IDE 中统一引入各种 AI 编码助手
想把自研的代码 Agent 提供给团队成员使用
我们可以按照“编辑器团队”和“Agent 团队”两侧来规划。
6.1 如果你负责“编辑器 / 内部开发工具”
短期目标（1–2 个月）：做一个最小可用的 ACP Client 集成
选一个编辑器或内部 Web IDE 作为试点
引入 TypeScript / Kotlin ACP SDK
实现最基本的：
initialize / session/new / session/prompt
接入 session/update → 将文本流显示到一个简单的 Chat 面板
配置 1–2 个现成 Agent（如 gemini acp、opencode acp）验证全链路
中期目标（3–6 个月）：扩展到“生产可用”
接入文件能力：实现 fs/read_text_file / fs/write_text_file 映射到项目文件树
接入终端能力：实现 terminal/* 映射到 IDE 内置终端
实现权限模型：
所有写文件 / 执行命令必须弹窗确认
提供“一次性允许 / 本会话允许 / 永久允许”选项
引入多 Agent 支持：有选择地接入 Claude Code、Qwen Code、OpenHands 等
长期目标：内部 AI 平台对接
在 IDE 侧只负责 ACP Client
把企业内部的 AI 编码平台封装成一个或多个 ACP Agent Server，对内统一暴露
通过组织级策略控制：
哪些项目可用哪些 Agent
哪些目录可被 Agent 读写
6.2 如果你负责“Agent / 智能体平台”
第一步：把现有 Agent 封装成 ACP Server
选用合适的 SDK（Python / Rust）
在现有业务逻辑外包一层：
实现 initialize，声明你的能力（是否支持 loadSession、支持哪些模式）
实现 session/new / session/prompt，将用户意图映射到你的内部工作流
如果 Agent 需要访问文件 / 终端：
改为通过 ACP 的 fs/*、terminal/* 间接访问，而不是直接用 os / subprocess
第二步：写好文档和示例配置
提供针对 Zed / JetBrains / AionUi / Neovim 的示例配置片段
明确说明：
启动命令
需要的环境变量（如 API Key、代理配置）
支持的模式（chat / edit / refactor / test 等）
第三步：企业内推广
把 ACP 集成纳入内部 IDE / Web IDE 的“官方支持列表”
从一个“高价值用例”切入（例如：安全审计 Agent 或重构 Agent），而不是泛泛聊天
七、小结：ACP 在整个智能体协议版图中的位置
如果我们把当前 Agent 相关协议做一个“分层”梳理，大致如下：
+---------------------------------+
| 应用层（IDE、桌面端、业务系统 UI） |
+---------------------------------+
| Agent Client Protocol (ACP) | ← 本文主角：UI ↔ 编码 Agent
+---------------------------------+
| MCP / 其它 Tool 协议 | ← Agent ↔ 工具 / 数据源
+---------------------------------+
| A2A / IBM ACP / 自定义协议 | ← Agent ↔ Agent
+---------------------------------+
| HTTP / TCP / stdio / NDJSON |
+---------------------------------+
MCP 解决“模型如何安全、统一地调用工具和数据源”
A2A / IBM ACP 解决“Agent 与 Agent 之间如何协作”
而 ACP（Agent Client Protocol） 聚焦在一个非常垂直但极其重要的领域：
编辑器 / 开发环境 与 AI 编码 Agent 的通信
在“AI 原生开发体验”这条路径上，ACP 与 LSP 一样，很可能会成为一种 长期存在的基础设施标准：
LSP：统一语言服务
MCP：统一模型与工具
ACP：统一 AI 编码 Agent 与编辑器
八、行动建议
如果你是个人开发者 / 工程师
尝试至少一个 ACP 客户端：
Zed / JetBrains 最新版本 / AionUi / Open Claude Cowork / Neovim + ACP 插件
尝试接入两个以上不同厂商的 Agent：
例如：Qwen Code（国产）+ OpenCode（开源）+ Gemini CLI（国际云厂商）
在实际项目中用 ACP Agent 做几件具体事情：
迁移一个模块的架构
改造测试体系
做一次安全审计或性能分析
如果你是工具 / 平台开发者
评估把自研 Agent 封装成 ACP Server 的工作量（通常以周为单位）
优先选择一个场景做 MVP：例如“重构 Agent”或“CI 修复失败用例 Agent”
发布后主动适配：
写出 Zed / JetBrains / AionUi 的配置示例
在文档中标明 “ACP-compatible Agent”
如果你是架构师 / 技术负责人
将 ACP 视作“企业内 AI 开发体验标准化”的一个选项：
它不会取代 MCP / A2A，但在 IDE/开发工具这一层是最佳人选之一
从安全视角审查 ACP 的使用：
明确哪些目录可被 ACP Agent 访问
明确命令执行白名单 / 黑名单策略
鼓励团队用一个小范围试点（单个业务组 + 单一 IDE）验证收益，再逐步推广。
九、相关参考
Agent Client Protocol. https://zed.dev/acp
Overview – Agent Client Protocol. https://agentclientprotocol.com/protocol/overview
JSON-RPC 2.0 Specification. https://www.jsonrpc.org/specification
Agent Client Protocol - Python SDK. https://agentclientprotocol.github.io/python-sdk/
Bring your own AI agent to JetBrains IDEs. https://blog.jetbrains.com/ai/2025/12/bring-your-own-ai-agent-to-jetbrains-ides/
ACP Setup · iOfficeAI/AionUi Wiki. https://github.com/iOfficeAI/AionUi/wiki/ACP-Setup
基于Electron + React + ACP 的本地多Agent 协作桌面应用. https://juejin.cn/post/7599581687357571122
Xuanwo/acp-claude-code. https://github.com/Xuanwo/acp-claude-code