← learn.wii.pub / ai-agent / acp

Agent Client Protocol(ACP)全解
编辑器与编码代理的通用协议

ACP 是一份基于 JSON-RPC 2.0 的开放协议,标准化代码编辑器 / IDE(Client)与编码代理(Agent)之间的通信,角色类似 LSP 之于语言服务器——由 Zed 发起、现与 JetBrains 联合治理。本文按官网全站(v1 稳定版 + v2 草案 + 生态 + 治理)完整梳理。

Client · 编辑器/IDE Agent · 编码代理 JSON-RPC 2.0 over stdio v2 draft(2026-07) Apache 2.0

CLIENT(编辑器) AGENT(代理子进程) stdio · newline-delimited JSON

initialize# ① 版本与能力协商C → A

{"jsonrpc":"2.0","id":0,"method":"initialize",
 "params":{"protocolVersion":1,
   "clientCapabilities":{"fs":{"readTextFile":true,
                             "writeTextFile":true},
                         "terminal":true},
   "clientInfo":{"name":"my-client","version":"1.0.0"}}}

──→

initialize · result# 协商结果 + authMethodsA → C

{"jsonrpc":"2.0","id":0,"result":{"protocolVersion":1,
 "agentCapabilities":{"loadSession":true,
   "promptCapabilities":{"image":true},
   "mcpCapabilities":{"http":true}},
 "agentInfo":{"name":"my-agent","version":"1.0.0"},
 "authMethods":[]}}

←──

session/new# ② 建会话:cwd + MCP 配置C → A

{"method":"session/new","params":{
 "cwd":"/home/user/project",
 "mcpServers":[{"name":"filesystem",
   "command":"/path/to/mcp-server","args":["--stdio"]}]}}

──→

session/new · resultA → C

{"id":1,"result":{"sessionId":"sess_abc123def456"}}

←──

session/prompt# ③ 用户消息(挂起整轮)C → A

{"method":"session/prompt","id":2,"params":{
 "sessionId":"sess_abc123def456",
 "prompt":[{"type":"text","text":"分析这段代码"}]}}

──→

session/update ×N# ④ 流式通知:计划/消息/工具调用A → C

{"method":"session/update","params":{"sessionId":…,
 "update":{"sessionUpdate":"agent_message_chunk",
   "messageId":"msg_agent_c42b9",
   "content":{"type":"text","text":"我来分析…"}}}}
// 另有 plan / tool_call / usage_update 等变体
// 需要时 A 会反向调用 session/request_permission

←──

session/prompt · result# ⑤ 回应即结束:停止原因A → C

{"id":2,"result":{"stopReason":"end_turn"}}

←──

// 这条"消息轨"就是 ACP 的全部骨架:请求-响应 + 单向通知,其余章节都在填充它

Part 00

30 秒版本

v1 + v2

v1 稳定运行;v2 于 2026-07-20 发布草案

40+

已适配 ACP 的编码代理(Claude Agent、Codex CLI、Gemini CLI、Cursor CLI…)

100+

客户端实现:编辑器 / CLI / 桌面 / 移动 / 即时通讯 / 框架

5 官方 SDK

TypeScript 与 Rust 已 1.0,另有 Python / Kotlin / Java

是什么:Client(编辑器)与 Agent(编码代理)之间的 JSON-RPC 2.0 协议。本地场景 Agent 以编辑器子进程运行,走 stdio(换行分隔 JSON);远程场景走 HTTP / WebSocket(完整支持仍在推进)。
解决什么:代理与编辑器深度耦合导致的集成开销、兼容性受限、开发者锁定——ACP 让"任一代理 × 任一编辑器"成为可能。
怎么运作:初始化协商版本与能力 →(按需)认证 → 建会话(cwd + MCP 服务器配置)→ session/prompt 驱动一轮对话,期间用 session/update 通知流式回传计划、消息、工具调用、diff,最终以 stopReason 收尾。
与 MCP 的关系:不是竞争而是分层——ACP 尽可能复用 MCP 的 JSON 类型;MCP 管"代理 ↔ 工具/数据",ACP 管"编辑器 ↔ 代理"的会话与 UX。
谁在管:Zed + JetBrains 联合治理,双 Lead Maintainer(BDFL),RFD 流程驱动演进,Apache 2.0。

Part 01

为什么需要 ACP

AI 编码代理与编辑器默认是紧耦合的:每个编辑器要为想支持的每个代理写定制集成,每个代理要实现各家编辑器专有 API 才能触达用户。官网归纳为三类问题:

问题	表现
集成开销	每一个「代理 × 编辑器」组合都需要定制开发
兼容性受限	代理只能配合一部分编辑器使用
开发者锁定	选定了代理,往往就得接受它自带的有限界面

ACP 用标准化协议解决,正如 LSP 之于语言服务器:实现 ACP 的代理可配合任何兼容编辑器,支持 ACP 的编辑器则接入全部 ACP 代理生态;双方独立创新,开发者自由选型。

前提假设用户主要待在编辑器里,按需唤起代理协助完成任务——ACP 的 UX 设计全部围绕这个场景展开。

Part 02

架构总览

设计哲学

原则	含义
MCP-friendly	构建在 JSON-RPC 之上,尽可能复用 MCP 类型,集成方不必为常见数据再造一套表示
UX-first	为「与 AI 代理交互的 UX 难题」而设计:足以清晰呈现代理意图(如 diff 展示),又不过度抽象
Trusted	面向"用编辑器对话可信模型"的场景:编辑器授予代理本地文件与 MCP 服务器访问,但工具调用控制权仍在用户手里

两种部署形态

本地代理:作为编辑器的子进程按需启动,所有通信走 stdin / stdout;一条连接可承载多个并发会话("多路思路并行")。
远程代理:部署在云端或独立基础设施,走 HTTP 或 WebSocket。官方注明:远程代理的完整支持仍是进行中的工作,正与代理平台协作补齐云部署场景。

本地架构:编辑器按需拉起代理子进程,stdio 双向 JSON-RPC;MCP 配置随 session/new 传递、由代理直连;编辑器想暴露自己的工具时,以 MCP 服务器配置的形式给出(必要时带一个小代理把请求隧道回编辑器)。图改绘自官网 Architecture 页。

协议要点一图流

PHASE 1

初始化

协商协议版本 + 双方能力,可选认证

PHASE 2

会话建立

session/new 创建,或 load / resume 恢复;传 cwd 与 mcpServers

PHASE 3

Prompt Turn

session/prompt 驱动;session/update 流式回传;可随时 cancel

收尾

stopReason

end_turn / max_tokens / max_turn_requests / refusal / cancelled

Part 03

通信模型

协议遵循 JSON-RPC 2.0,只有两类消息:

Methods(方法):请求-响应对,期待 result 或 error。
Notifications(通知):单向消息,不应答(成功或错误都不回)。代理靠它把更新实时流式推给编辑器;也利用 JSON-RPC 的双向请求让代理反过来请求编辑器(如请求工具调用权限)。

方法面清单(v1)

方向	方法 / 通知	说明	门槛
Agent 侧编辑器 → 代理	`initialize`	协商版本与能力	基线
	`authenticate`	认证(如需要)	基线
	`session/new`	创建会话	基线
	`session/prompt`	发送用户提示	基线
	`session/load`	加载历史会话(全量重放)	loadSession
	`logout`	退出认证态	auth.logout
	`session/set_mode`	切换运行模式(将被 config options 取代)	随 modes 提供
	`session/cancel` (通知)	取消进行中的操作	基线
Client 侧代理 → 编辑器	`session/request_permission`	请求用户授权工具调用	基线
	`fs/read_text_file`	读文件(含编辑器未保存状态)	fs.readTextFile
	`fs/write_text_file`	写文件	fs.writeTextFile
	`terminal/create`	创建终端执行命令	terminal
	`terminal/output`	获取输出与退出状态
	`terminal/release`	释放终端
	`terminal/wait_for_exit`	等待命令退出
	`terminal/kill`	杀掉命令但保留终端
	`elicitation/create`	向用户请求结构化输入	elicitation 模式能力
	`elicitation/complete` (通知)	回报 URL 模式带外交互完成	同上
Agent → Client	`session/update` (通知)	会话更新总通道:消息块 / 工具调用 / 计划 / 可用命令 / 模式变更等	基线

通用约定

协议内所有文件路径必须为绝对路径;行号 1-based。
JSON 属性键用 camelCase,判别字段(discriminator)的字符串值用 snake_case;信封字段(jsonrpc/id/method/params/result/error)按 JSON-RPC 2.0。
错误处理遵循 JSON-RPC 2.0:成功带 result;失败带 error{code,message};通知永不应答。
stdio 传输下消息以换行(\n)分隔且不得内嵌换行;UTF-8;代理的 stdout 除合法 ACP 消息外不得写任何内容,stderr 可用于日志。

Part 04

协议生命周期

4.1 初始化与能力协商已稳定

任何会话创建之前,Client 必须调用 initialize,带上所支持的最新协议版本与自身能力;Agent 必须以选定的协议版本与自身能力应答。双方 SHOULD 附带实现信息(clientInfo / agentInfo 的 name / title / version,未来版本将变为必填)。

版本协商规则:版本是单个整数,只标识 MAJOR(仅破坏性变更才递增)。请求带 Client 支持的最新版;Agent 支持则原样返回,否则返回自己的最新版;若 Client 不支持该版本,SHOULD 断开连接并告知用户。

能力规则:能力全部可选;新增能力不算破坏性变更;未在 initialize 中出现的能力一律视为不支持——双方 SHOULD 兼容对端能力的所有组合。

侧	能力	开启什么
Client 能力	`auth.terminal`	允许代理广告 `type:"terminal"` 认证方式(终端登录)
	`fs.readTextFile` / `fs.writeTextFile`	开放对应 `fs/*` 方法
	`terminal`	开放全部 `terminal/*` 方法
	`elicitation`(`form` / `url` 各自显式出现)	开放 `elicitation/create` 的对应模式;ACP 不把空对象 `{}` 当作支持
	`session.configOptions.boolean`	允许代理在 configOptions 中携带布尔选项
Agent 能力	`loadSession`	`session/load` 可用
	`promptCapabilities.image / audio / embeddedContext`	prompt 可含图片 / 音频 / 内嵌资源(基线必须支持 text 与 resource_link)
	`mcpCapabilities.http`	可经 HTTP 连接 MCP 服务器
	`mcpCapabilities.sse`	SSE 传输(MCP 规范已弃用)
	`auth.logout`	`logout` 方法可用
	`sessionCapabilities.list / resume / close / delete / additionalDirectories`	分别开启 `session/list`、`session/resume`、`session/close`、`session/delete`、附加工作区根
	`session/delete` 等	见会话管理小节
	基线约束	所有 Agent 必须支持 `session/new`、`session/prompt`、`session/cancel`、`session/update`

4.2 认证已稳定

认证在初始化阶段协商:Agent 在 authMethods 里广告可用方式,支持登出的再广告 agentCapabilities.auth.logout。两类方式:

agent(默认类型):代理自管认证。Client 调 authenticate 并传广告的 methodId,成功返回空结果。
terminal(需 Client 能力 auth.terminal):Client 用与 ACP 连接相同的代理启动配置另起一个交互式进程,附加方式的 args 与 env(如 ACP_INTERACTIVE_LOGIN=1),把终端呈现给用户;退出码 0 视为成功,随后重连并重新 initialize。协议不定义带内成功信号;对 terminal 方式不得发送 authenticate。

logout 结束当前认证态,之后的新会话需重新走认证流程;协议不保证已运行会话在 logout 后的命运(可能被终止、继续运行或返回 auth_required),Client SHOULD 有所准备。

4.3 会话建立与管理已稳定

会话(Session)是 Client 与 Agent 之间的一段独立对话:各自维护上下文、历史与状态,同一代理可并行承载多个会话。

方法	能力门槛	语义
`session/new`	基线	传 `cwd` + `mcpServers`,返回唯一 `sessionId`;代理应连接全部指定 MCP 服务器
`session/load`	loadSession	恢复历史会话:代理必须以 `session/update` 全量重放对话(完成前不应答),之后可无缝继续提问;重放的消息可带 `messageId`
`session/resume`	sessionCapabilities.resume	重连已有会话但不重放历史;响应可带初始 mode / model / 配置状态
`session/close`	sessionCapabilities.close	取消该会话进行中的工作并释放资源(等同先 `session/cancel`)
`session/delete`	sessionCapabilities.delete	从 `session/list` 结果中移除;重复删除或删不存在的 SHOULD 静默成功;软删/硬删由实现自定
`session/list`	sessionCapabilities.list	发现会话:可按 `cwd` 过滤,`cursor` 游标分页(opaque,缺失 nextCursor 即末页);返回 `SessionInfo{sessionId,cwd,title?,updatedAt?,_meta?}`;仅发现不恢复,恢复仍走 load
`session_info_update` (通知)	—	代理实时推送会话元数据(标题/更新时间/_meta),典型如首轮对话后自动生成标题

工作目录与附加根

cwd 必须绝对路径,始终是会话主工作目录与相对路径基准,与子进程从哪里被拉起无关。
广告 sessionCapabilities.additionalDirectories 后,session/new / load / resume 可带 additionalDirectories(全部绝对路径)。会话有效根集 = [cwd, ...additionalDirectories],SHOULD 作为文件工具操作的边界;load/resume 时需全量重发期望列表,空/缺省即不启用附加根。

MCP 服务器配置

传输	门槛	配置要点
stdio	所有 Agent 必须支持	`{name, command(绝对路径), args, env[]}`
HTTP	mcpCapabilities.http	`{type:"http", name, url, headers[]}`;新代理 SHOULD 支持,以兼容现代 MCP 服务器
SSE	mcpCapabilities.sse	已被 MCP 规范弃用

Client 也可以借这道口子把自己的工具直接喂给底层模型——把自己实现为一个 MCP 服务器传进去。

4.4 Prompt Turn:一轮完整对话已稳定

Prompt Turn 是 Client 与 Agent 间一次完整交互循环:从用户消息开始,到代理完成响应为止,中间可能涉及多轮模型调用与工具执行。

STEP 1

用户消息

session/prompt(prompt: ContentBlock[],按能力约束类型)

STEP 2

代理处理

交给 LLM,可能产出文本、工具调用或两者

STEP 3

流式回报

session/update:plan → agent_message_chunk → tool_call…

STEP 4-5

工具执行

可先 request_permission;状态 pending→in_progress→completed

STEP 6

循环/收尾

工具结果回喂 LLM,循环至无工具调用,响应 stopReason

Stop Reasons(轮停止原因)

值	含义
`end_turn`	模型完成响应,未再请求工具
`max_tokens`	达到 token 上限
`max_turn_requests`	单轮内模型请求次数超限
`refusal`	代理拒绝继续
`cancelled`	Client 取消了本轮

消息 ID 与用量上报

消息块可以携带不透明唯一的 messageId:同 ID 归属同一条消息,变更即新消息——Client 由此把流式 chunk 组装成完整消息。
Agent 可发 usage_update 通知上报上下文用量:used / size(必填 token 数)与可选 cost{amount,currency(ISO 4217)}。

取消语义

Client 发 session/cancel 通知后,SHOULD 立即把本轮未完成工具调用预标记为 cancelled,必须以 cancelled 结果应答所有挂起的权限请求。
Agent 收到后 SHOULD 尽快停止所有模型请求与工具调用;在最终应答 session/prompt(带 cancelled)之前仍可补发 session/update;Client SHOULD 继续接收取消后的工具调用更新。
陷阱(官方专门警告):底层 API 库被中断时常抛异常并可能以错误响应冒泡——代理必须捕获并翻译成语义化的 cancelled 停止原因,否则客户端会把取消当错误展示。

通用取消机制 `$/cancel_request` 已稳定(2026-06-29)

JSON-RPC 本身不定义取消,ACP 补充了 $/cancel_request 通知:接收方可取消对应请求及嵌套活动,但必须对原请求给出正常响应或 -32800 Request Cancelled 错误。内部取消(如上下文超限、超时、用户关 IDE)SHOULD 采用一致行为。级联取消示例:Client 取消 prompt 轮 → Agent 对自己发起的 terminal/create、request_permission 等子请求逐个发 $/cancel_request → 最后以 stopReason:"cancelled" 收束。

Part 05

UX 元素与数据

5.1 内容块 Content Blocks

内容块是协议中流动的可展示信息,结构沿用 MCP 的 ContentBlock,代理因此可以零转换转发 MCP 工具输出。出现在 session/prompt、session/update 与工具调用结果中。

类型	prompt 中门槛	要点
`text`	必须支持	用户可读文本默认 Markdown——足够富格式,又不要求编辑器能渲染 HTML
`image`	image	Base64 `data` + `mimeType`,可选 `uri`
`audio`	audio	Base64 音频,供转写/分析
`resource`(内嵌资源)	embeddedContext	把完整资源(文本 text 或 blob)嵌入消息;@-mention 引用文件的首选方式——即使代理无权访问来源也能拿到上下文
`resource_link`	必须支持	指向代理可访问资源的引用:{uri,name,mimeType?,title?,description?,size?}

5.2 工具调用 Tool Calls

LLM 请求执行外部动作(读文件、跑代码、取数据)时,Agent 通过 session/update 报告工具调用,Client 据此实时展示进度与结果。首个 tool_call 通知创建,后续 tool_call_update 增量更新(除 toolCallId 外字段全部可选,只传变更字段)。

字段	取值	用途
`kind`	`read / edit / delete / move / search / execute / think / fetch / other`	帮助 Client 选图标、优化进度展示
`status`	`pending / in_progress / completed / failed`	执行生命周期;pending = 输入流式传输中或等待批准
`content`	常规内容块 / `diff` / `terminal`	工具产出;diff 为 `{path,oldText?,newText}`(newText 必填,oldText 空即新建文件);terminal 引用实时输出
`locations`	`{path,line?}`	正在读写的文件位置,支撑"跟随代理"类 UI
`rawInput / rawOutput`	object	工具原始入参/出参

权限请求

执行前 Agent 可调用 session/request_permission(带 toolCall 摘要与 options)。选项 kind:allow_once / allow_always / reject_once / reject_always;Client 按用户设置也可全自动处理。应答为 {outcome:"selected",optionId} 或 {outcome:"cancelled"}(轮被取消时必须回 cancelled)。

5.3 代理计划 Agent Plan

复杂任务的执行策略:session/update 携带 plan 通知,entries[] 每项为 {content, priority(high/medium/low), status(pending/in_progress/completed)}。每次必须发完整列表,Client 整体替换;计划可在执行中动态增删改。

5.4 终端 Terminals

让代理在 Client 环境里执行 shell 命令,带实时输出与进程控制(需 Client 能力 terminal)。五个方法:

方法	语义
`terminal/create`	启动命令,立即返回 `terminalId` 不等完成;可带 `cwd / env / outputByteLimit`(超限从头截断,必须落在字符边界)
`terminal/output`	取当前输出 + 退出状态(若已退出),含 `truncated` 标志
`terminal/wait_for_exit`	阻塞至命令退出,返回 `exitCode / signal`
`terminal/kill`	杀命令但保留终端,可继续 output / wait_for_exit
`terminal/release`	杀掉仍在跑的命令并释放全部资源;ID 随即失效(嵌入工具调用的输出 Client SHOULD 继续展示)

终端可嵌入工具调用(content:[{type:"terminal",terminalId}]),Client 边生成边展示,release 后保留。
官方给出「超时」组合模式:create → 起计时器 → 与 wait_for_exit 竞速 → 超时则 kill + output 取回终值 → release。

5.5 文件系统 File System

fs/read_text_file(可带 line / limit 做行级读取)与 fs/write_text_file(不存在则创建)。价值在于读写编辑器未保存状态,并让 Client 追踪代理执行期间的文件修改。

5.6 主动询问 Elicitation 已稳定(2026-07-22)

Agent 借 Client 向用户要结构化信息,基于 MCP 2026-07-28 RC 的 elicitation 规范改造,支持两模式:

Form 模式:受限 JSON Schema(扁平对象,属性为基本类型/枚举)收集非敏感数据;Client SHOULD 先本地校验并允许用户改后再提交;禁止用于索要密码、API key、token、支付凭据等。
URL 模式:打开带外交互(如 OAuth)。带 elicitationId + url;accept 只代表用户同意打开 URL,不代表完成;外部完成后 Agent 向同一连接发 elicitation/complete 通知。拿到的凭据不得回流 ACP 或进入模型上下文。

能力按模式显式广告(elicitation:{form:{},url:{}})——与 MCP 不同,ACP 不把 {} 当作 form 支持。响应三态:accept / decline / cancel。安全要求(URL 不得预取、须先展示完整 URL 征得同意、在语言模型不可窥视的安全上下文打开、高亮域名、校验发起与完成是同一已认证用户等)在官网有整节硬性规定。

5.7 会话模式 → 会话配置项

Session Modes(旧):代理提供若干运行模式(如 Ask / Architect / Code),影响系统提示、工具可用性与是否请求权限;Client 用 session/set_mode 切换,Agent 用 current_mode_update 反向通知。典型场景:architect 模式下模型调「退出计划模式」工具时,借权限请求让用户选择切换到的模式。

Session Config Options(新,2026-02-04 稳定)全面取代 modes:任意数量的会话级配置选择器(模型、模式、推理力度等)。

概念	说明
`ConfigOption`	`{id,name,description?,category?,type,currentValue,options[]}`;`type` 默认 `select`,`boolean` 需 Client 能力显式开启(2026-07-06 稳定)
`category`	纯 UX 语义:`mode / model / model_config / thought_level`(2026-06-24 稳定),`_` 前缀可自定义;Client 必须容忍未知类别;正确性不得依赖它
顺序	数组顺序即代理期望的优先级;Client SHOULD 按序展示、同类别按序决胜
默认值	每个配置项必须有默认值,保证 Client 不展示/不认识该选项时代理照常工作(未知 type 直接忽略)
改值	Client:`session/set_config_option`;Agent:`config_option_update` 通知。两边的载荷都是全量配置状态——改一项可能引发联动(如换模型改变可选推理档位)
过渡规则	代理提供 configOptions 时 SHOULD 同时提供 modes;支持前者的 Client 忽略 modes,只支持后者的回退 modes;代理保持两者同步

5.8 斜杠命令 Slash Commands

建会话后,Agent 可发 available_commands_update 广告命令列表({name,description,input?{hint}}),并可随时动态更新。命令本身不新增协议方法——以普通用户消息运行:prompt:[{type:"text",text:"/web agent client protocol"}],由代理识别前缀处理;同一条 prompt 里可混排图片等其他内容类型。

Part 06

扩展机制

ACP 内建三条扩展通道,保证"在不破坏互操作的前提下创新":

_meta 字段:协议中所有类型(请求、响应、通知,乃至内容块、工具调用、计划条目、能力对象)都带 _meta:{[key:string]:unknown},可挂任意自定义信息。根级 traceparent / tracestate / baggage 三个键 SHOULD 保留给 W3C Trace Context,以兼容 MCP 与 OpenTelemetry 生态。规范类型的根级字段名全部保留给未来版本,实现不得自加。
_ 前缀自定义方法:方法名以 _ 开头即自定义扩展,遵循标准 JSON-RPC 语义——自定义请求必须应答(不认识则回 -32601 Method not found);自定义通知不认识则 SHOULD 忽略。
能力对象里广告扩展:在 initialize 的能力对象 _meta 里声明扩展特性(如 "zed.dev":{workspace:true}),让对端先探测再使用,避免撞 -32601。

Part 07

v1 vs v2 v2 全程草案

ACP v2(2026-07-20 发布草案)是一次整合式重构:重设计 prompt 生命周期、统一流式/非流式更新、默认前向兼容、并移除生态已抛弃的协议面。官方建议 v1/v2 并轨支持——按连接协商版本,v2 先藏在未来旗标后面。

如果只记住五件事

session/prompt 的响应不再代表轮结束,只是"已受理"的确认;前台进度与完成全部走 state_update 通知,stopReason 也搬到了那里。
更新即 upsert:消息、工具调用、计划按 ID 打补丁,语义统一——省略字段=不变,null=清除,具体值=替换,chunk=追加。
Client 文件系统、终端执行、会话模式 API 全部移除;代理自有的终端输出改为纯展示面;代理需要 Client 侧工具时走 Client 提供的 MCP 服务器。
能力重组:双方统一为 capabilities + 必填 info;会话级能力嵌套在 session 下;支持标记从布尔改为对象;广告 session 即承诺一整套基线方法。
处处可扩展:枚举与标签联合接受未知值;_ 前缀归实现,其余未知值保留给未来 ACP。

方法对照

v1	v2
`authenticate`	更名 `auth/login`;广告了 authMethods 就必须同时实现 `auth/logout`
`session/load`	移除——用 `session/resume` + `replayFrom:{type:"start"}`
`session/set_mode`、`modes`、`current_mode_update`	移除——统一走 config options(`configId` 取代 `id`)
`fs/`、`terminal/`(Client 执行面)	整体移除;Client 工具改经 `mcpServers` 提供
`session/list / resume / close`(各自能力门控)	升为基线必做(广告 session 即须实现);`session/delete` 仍可选
`session/prompt` 挂起整轮、响应携带 stopReason	受理即回 `{}`;新 `state_update`(running / idle / requires_action)承载状态,停止原因在 idle 时给出
MCP stdio 配置无 `type`;SSE 可选	每个服务器配置必须带 `type`(stdio/http);SSE 移除;stdio 也成为显式能力 `session.mcp.stdio`
stdio 单条消息	显式支持 JSON-RPC 批量(数组);生命周期敏感消息(initialize、auth/login、session/new、resume、prompt)不得批量

`session/update` 变体对照

v1	v2
`user/agent/thought_message_chunk`(messageId 可选)	保留,messageId 必填;新增整消息 upsert `user_message / agent_message / agent_thought`(content 为数组,可整体替换/清空)
`tool_call`(创建)+ `tool_call_update`(修改)	只留 `tool_call_update`:首见 toolCallId 即创建;新增 `tool_call_content_chunk` 流式追加内容;status 增加 `cancelled`
`plan`(无身份扁平列表)	`plan_update`:带 `planId` 与 `type:"items"` 判别,支持一会话多计划,条目 status 增加 `cancelled`
—	新增 `terminal_update`(快照式替换,base64)+ `terminal_output_chunk`(独立 base64 分块追加):代理自有、纯展示的终端输出,无输入/控制语义
diff = `{path,oldText,newText}`	结构化 `changes[]`(add/delete/modify/move/copy + fileType/mimeType)+ 可选 `patch`(git_patch 格式,路径须绝对);删除文件与二进制/符号链接可表达了
权限请求塞 `toolCall`,提示文案挤在 title 里	`title`(必填)+ 可选 `description` + 可选 `subject` 标签联合(`tool_call` 或 `command`);收到不认识的 outcome 不得当作批准
—	slash 命令 `input` 变标签联合(`{type:"text",hint}`);resource_link 增 `icons`;base64 字段标注 `contentEncoding`

为什么要动 prompt 生命周期v1 里"响应即轮次"把「受理」与「完成」耦合在一起,导致历史重放、多客户端观察同一会话、后台工作、排队消息都很难表达。v2 把前台进度全部表达为通知后,同一套消息流天然适用于 resume 重放与多端观战。停止原因五个值本身未变,只是从 prompt 响应搬进 idle state_update。

官方 migration 页还给出 Agent 16 条 / Client 14 条 / SDK 5 条的完整迁移清单,以及 v1+v2 并轨的结构建议(共享应用逻辑 + 两个薄协议面,initialize 后按协商版本选择)。此处仅提炼,完整版见 Migrating from v1。

Part 08

生态

8.1 实现了 ACP 的代理(40 个)

Claude Agent 经 Zed 的 SDK 适配器 Codex CLI 经官方适配器 codex-acp Gemini CLI GitHub Copilot 公测(2026-01-28) Cursor Cursor CLI Cline OpenCode Qwen Code Kimi CLI Augment Code Goose Block OpenHands Junie JetBrains Factory Droid Kiro CLI AWS Mistral Vibe Poolside Docker cagent fast-agent AgentPool AutoDev Blackbox AI Bub bub-acp-server Claw Orchestrator Code Assistant Construct crow-cli Hermes Agent Nous Research Kaagum localharness Minion Code OpenClaw Pi pi-acp 适配器 Qoder CLI Raxol siGit Code Stakpak stdio Bus VT Code fount

高亮 = 头部通用代理;完整名单与链接见官网 Agents 页。

8.2 客户端 / 框架 / 连接器(100+ 项目)

类别	代表(→ 官网 Clients 页有完整名单)
编辑器 / IDE	Zed(发源地)、JetBrains AI Assistant、neovim(CodeCompanion / agentic / avante / hermes 四插件)、VS Code 系(ACP Client、ACP Pro、Multicoder、Exo…)、Emacs(agent-shell)、Obsidian(4 个插件)、Sublime、Pulsar、Qt Creator、Unity×2、Visual Studio(Poolside)…
CLI / TUI	acpx、Hash、Hydra、Martty、Nori CLI、pool、Toad
桌面 / Web	AionUi、DeepChat、Devin Desktop、GitKraken Kepler、Codeg、Capsule、Braide、Superlite、ACP UI(全平台)、ACP Inspector(调试器)…约 45 个
移动端	Happy、Runmote(扫码配对,免 SSH/VPN)、Shellular、Agmente、Ferngeist、Mobvibe、VACP(语音)
即时通讯	Discord、Telegram×4、Slack×4、微信(WeChat ACP)、QQ(qq-ai-bot)、飞书(Lark ACP)、Matrix(Zooid)
框架集成	LangChain / LangGraph(Deep Agents)、Mastra、Koog(JetBrains)、LlamaIndex、AgentPool、fast-agent、ACP Kit(Pydantic AI / LangChain 桥)、LLMling-Agent
连接器 / 桥	stdio↔HTTP 桥、ACP→AG-UI(SSE)、WebSocket 远程传输、LLDB 崩溃→代理调试(acpdbg)、数据库 IDE(Kangaroo)、Jupyter/marimo/DuckDB 集成…

8.3 ACP Registry 2026-03-09 发布

官方策划的代理分发渠道:Client 侧一个标准入口即可发现、安装、配置兼容代理,免去各家自定义集成元数据。收录的是支持认证的代理。仓库:agentclientprotocol/registry(官网 Registry 页即其渲染视图,含各代理版本号与来源)。

8.4 官方 SDK 与社区库

语言	包 / 仓库	说明
TypeScript	`npm i @agentclientprotocol/sdk`	1.0 流式 `agent()` / `client()` API 注册类型化 handler(旧的 AgentSideConnection / ClientSideConnection 类已弃用)
Rust	`cargo add agent-client-protocol`	1.0 实现 `Agent` / `Client` trait;Zed 编辑器的外部代理集成即由它驱动
Python	`pip install agent-client-protocol`	Pydantic 模型 + 异步基类 + JSON-RPC 管线,镜像官方 schema,含 Gemini CLI 桥等示例
Kotlin	`com.agentclientprotocol:acp`	当前支持 JVM,多平台目标推进中
Java	agentclientprotocol/java-sdk	模型 + JSON-RPC 管线 + 两侧连接助手,附 Spring AI 集成示例

社区维护库覆盖 Cangjie、C++、Crystal、Dart、.NET×3、Elixir、Emacs(el)、Go×6、React(use-acp)、TypeScript、Swift×3、Vala 等语言,见官网 Community 库页。协议的 JSON Schema(v1/v2 各有 stable 与 unstable 两套)在 Schema 页公开。

Part 09

治理与流程

谁说了算

ACP 由 Zed 与 JetBrains 联合治理(阶段性模式,目标是过渡到独立基金会)。
层级:contributors → maintainers(管 SDK/文档等组件)→ core maintainers(定方向)→ 两位 Lead Maintainer(BDFL):Zed 的 Ben Brandt 与 JetBrains 的 Sergey Ignatov(2026-02-18 加入)。以上三层构成 steering group,双周例会。
许可:Apache 2.0,不签 CLA;安全问题报 security@zed.dev;讨论主阵地为 Zulip。

RFD:Requests for Dialog

ACP 版的 RFC 流程,是提案新特性、收集社区意见、沉淀设计决策的主机制(重构措辞、修客观错误等不需要)。生命周期:

RFD 1

PR 提案

fork 仓库,复制 TEMPLATE.md 改 kebab-case 文件名;PR 即讨论场

RFD 2

Draft

核心成员愿意 champion 才并入;可开特性门控的实验实现

RFD 3

Active

核心团队/工作组正在投入——是可见性信号,非稳定性承诺

RFD 4

Preview

完整实现,开放社区评审数日

RFD 5

Completed

最终决定权在 core team lead;可能是唯一的"单行门"(此后再改即破坏性)

另有「To be removed」支线:未落地的可被关闭;已落地草案的在移除完成前先进该状态。最新动态:Terminal Authentication 已 Completed(2026-08-20),Tool Call Name 进入 Preview(2026-09-14),Session Compaction / Session Notices 在 Draft。官方还维护 RFD Updates 时间线页。

工作组与兴趣组

兴趣组(Interest Group):识别并 articulating ACP 该解决的问题,组织开放讨论。
工作组(Working Group):产出具体交付物(RFD / 社区实现)。写 RFD 前强烈建议先在兴趣组内协作对齐。
例:Transports 工作组(2026-04-22 成立,JetBrains Anna Zhdan 与 Block Goose 的 Alex Hancock 牵头)正标准化 WebSocket / HTTP 远程传输。

布道

Publications 页收录 9 场公开演讲(2025-11 柏林 → 2026-06 伦敦,含上海两场 Copilot 主题)与 2 支视频(Zed × JetBrains 对谈、B 站「ACP in GitHub Copilot」);另有 Brand 页提供品牌资产。

Part 10

时间线与学习路径

协议演进时间线(节选自官网 Updates / RFD Updates)

2025-10-24initialize 增加可选 clientInfo / agentInfo 实现信息
2026-02-04Session Config Options 稳定(模式/模型/推理力度统一为配置选择器)
2026-02-18Sergey Ignatov(JetBrains)出任第二位 Lead Maintainer
2026-03-09session/list、session_info_update 稳定;ACP Registry 首版发布
2026-04-22session/resume 稳定;Transports 工作组成立
2026-04-23session/close 稳定
2026-05-21logout 方法稳定
2026-06-01附加工作区根 additionalDirectories 稳定
2026-06-05messageId、usage_update、session/delete 三项同日稳定
2026-06-24model_config 配置类别稳定
2026-06-25Rust 与 TypeScript SDK 双双 1.0
2026-06-29通用请求取消 $/cancel_request 稳定
2026-07-06布尔配置项类型稳定
2026-07-20ACP v2 以草案形式发布(协议文档 + schema)
2026-07-22Elicitation(form / URL 两模式)稳定
2026-08-20Terminal Authentication RFD 完成,进 v1/v2 稳定 schema
2026-09-14Tool Call Name RFD 进入 Preview(征求意见)

建议学习路径

建立直觉:读本文 00-03 节 + 官网 Introduction 与 v1 Overview,记住"请求-响应 + 通知"与三阶段消息流。
跑通一次:装 Zed(或 JetBrains / VS Code 插件)接一个 Gemini CLI / Codex CLI,开 ACP Inspector 之类调试器看真实消息轨;或用 TS/Rust SDK 的示例 agent + client 对跑。
吃透生命周期:按 Initialization → Authentication → Session Setup → Prompt Turn 顺序精读 v1 文档(本文 04 节是索引),对照 wire 轨逐帧理解。
补 UX 面:Content / Tool Calls / Plan / Terminals / Elicitation / Config Options / Slash Commands(本文 05 节),想清楚每个元素"解决什么 UX 问题"。
看向前沿:读 Migrating from v1 理解 v2 的生命周期重构与前向兼容设计;关注 RFD Updates 与 Transports 工作组(远程传输标准化的最大变量)。
动手时:SDK 优先(TS/Rust 已 1.0);扩展一律走 _meta 与 _ 前缀;机器可读索引用 llms.txt。

官方文档完整地图

分区	页面
Get Started(5)	Introduction · Architecture · Agents · Clients · ACP Registry
Protocol v1(20)	Overview · Initialization · Authentication · Session Setup / List / Delete · Prompt Turn · Content · Tool Calls · Elicitation · File System · Cancellation · Terminals · Agent Plan · Session Modes · Session Config Options · Slash Commands · Extensibility · Transports · Schema
Protocol v2(18,草案)	Overview · Migrating from v1 · Initialization · Authentication · Session Setup / List / Delete · Prompt Lifecycle · Content · Tool Calls · Elicitation · Cancellation · Agent Plan · Session Config Options · Slash Commands · Extensibility · Transports · Schema
Libraries(6)	Kotlin · Java · Python · Rust · TypeScript · Community
RFDs(40+)	About / Updates 流程页 + 各特性 RFD(session-fork、mcp-over-acp、elicitation、session-compaction、streamable-http-websocket-transport、v2 系列提案等)
Community / 其他	Communication · Code of Conduct · Governance · Working & Interest Groups · Contributing · Publications · Updates · Announcements(20+ 篇)· Brand · llms.txt