Claude Code 在 Zed 中的 ACP 协议传输机制实测

在十一次 ACP 运行中，AI 智能体从未在客户端调用过 fs/read_text_file、fs/write_text_file 或任何 terminal/* 方法。它在自己的进程中完成了所有文件 I/O 和命令执行。

声明完全不具备文件系统和终端能力没有任何改变。客户端能力不是沙箱。

真正的边界是会话 cwd，而 AI 智能体强制执行它——不是编辑器。它内部的读取在 22 次中从未被暴露 0 次；对同级目录的读取则立即被暴露。

在没有持续授权的情况下，每个执行项目代码的命令都被暴露了（15/15），而任何只读检查命令从未被暴露（0/10）。

你在 Zed 中看到的实时终端由供应商 _meta 键控制，而不是 ACP 的标准终端能力。仅使用标准标志时，工具调用会带着一个空的内容数组到达。

我的第一个基准测试被污染了：回答「始终允许」会将一个权限文件写入 fixture，而 git clean -fd 无法移除它。这里的数字来自使用 git clean -fdx 的重新运行。

你可以在 Zed 中运行 Claude Code。它出现在 AI 智能体面板中，将编辑内容流式传输到多重缓冲区，并允许你接受或拒绝单个块。一个明显的问题——也是人们实际输入 Google 的问题——是这是否比终端更好，以及你在边界处放弃了什么。

几乎所有关于这个问题的文章都是功能导览。我想要的是线路上真正传输的东西。

所以我完全跳过 Zed 的 UI，自己写了一个 Agent Client Protocol 客户端：168 行 Node 代码，生成真正的 Claude Code 适配器，通过 stdio 发送原始 JSON-RPC，并给每一帧打上时间戳。然后我给三个界面提供了相同的失败测试套件——具有完整能力的 ACP、没有能力的 ACP，以及普通的 claude -p CLI——并运行了十四次。

简而言之：编辑器是一个视口，不是沙箱。它看到的是 AI 智能体正在做什么的精心筛选的叙述，其权限对话框覆盖的活动范围比对话框所暗示的要窄得多。

首先，每个人都在使用的包名已经死了

在任何有趣的部分之前，有一个实际的陷阱。每篇博客文章和一半的 Stack Overflow 答案仍然告诉你安装 @zed-industries/claude-code-acp。那个包已弃用。它的第一次重命名也是如此。

这个差距很重要。已弃用适配器的最后版本是 2 月的 0.16.2；当前版本是 0.64.0，在我运行前三天发布。如果你固定了旧名称，你已经被冻结了五个半月。

npm install @zed-industries/claude-code-acp 仍然成功。它打印出一个你会略过的弃用通知，然后安装一个 2 月的构建。当前的包是 @agentclientprotocol/claude-agent-acp。

下面的所有内容都是针对适配器 0.64.0、SDK 1.3.0、Claude Code CLI 2.1.220、Node v25.9.0，在配备 96 GB 内存的 Mac Studio M3 Ultra 上测量的。Zed 当前的稳定版是 v1.13.1，发布于 2026-07-29。ACP 协议版本是整数 1。

实验装置，以及我第一次尝试中的 bug

任务是一个真正的两部分 bug，不是玩具。一个用于 semver 字符串的 compare() 函数，在两个独立方面对预发布版本排序错误：它不知道 1.0.0-alpha 排序在 1.0.0 之前，而且它将数字预发布版本标识符作为字符串比较，所以 alpha.10 排在 alpha.2 之前。三个测试，两个失败。正确修复它意味着阅读源代码、阅读测试、运行它们，并推理规格说明。

每个面上的提示都是相同的：

The test suite in this repo fails. Run the tests, find the bug in src/semver.js,
fix it, and re-run the tests until they all pass. Do not modify anything in test/.

我需要告诉你这个工具的第一个版本，因为它错了，而它出错的方式是本文中最有用的部分。

我在运行之间用 git reset --hard && git clean -fd 重置 fixture，并假设这使运行独立。它没有。当我的客户端回答「始终允许」权限请求时，Claude Code 将该授权持久化到项目内的 .claude/settings.local.json——而那个路径在我的全局 gitignore 中，所以 git clean -fd 直接走过它。只有 -x 会移除被忽略的文件。

在第一次运行结束时，fixture 包含这个：

{
  "permissions": {
    "allow": [
      "Bash(node --test test/)",
      "Bash(node --test test/semver.test.js)",
      "Bash(node -e ' *)"
    ]
  }
}

之后的每次运行都为即将计数的「从未请求权限」的命令预先批准了。我的文章初稿报告说 44 of 55 个 shell 命令未经提示运行，并将其归因于一个神秘的风险启发式。那个数字是我自己工具的产物。我编造来解释它的启发式并不存在——真正的规则要简单得多，而且它是发现 3。

所以现在的重置是 git reset --hard && git clean -fdx && rm -rf .claude，并断言该目录确实消失了，下面的每个数字都来自完整重新运行。十四次运行：七次有常设权限授权，一次拒绝所有，三次回答「仅此一次」，三次在终端 CLI 上——加上我将要提到的两次有针对性的探测。

如果你对一个 AI 智能体进行基准测试并用 git clean -fd 重置，你可能正在测量一个被污染的第二次运行。权限状态、缓存和工具配置往往存在于 gitignore 的点文件中。使用 -x。

ACP 是通过换行分隔的 stdio 的 JSON-RPC 2.0，所以作为客户端确实很容易——你不需要 SDK，我的从不导入它。整个协议握手是三次调用：

const init = await request('initialize', {
  protocolVersion: 1,
  clientCapabilities: {
    fs: { readTextFile: true, writeTextFile: true },
    terminal: true,
  },
  clientInfo: { name: 'leanzero-wirelog', version: '1.0.0' },
});

const sess = await request('session/new', { cwd: CWD, mcpServers: [] });

const result = await request('session/prompt', {
  sessionId: sess.sessionId,
  prompt: [{ type: 'text', text: taskDescription }],
});

之后 AI 智能体向你流式传输 session/update 通知，偶尔会用 session/request_permission、fs/read_text_file、fs/write_text_file 或 terminal/* 系列回调。我对所有这些都进行了真实实现——我的客户端将真正读取文件、写入文件，并在请求时生成进程。

它从来没有得到这个机会。

发现 1：AI 智能体从未触碰我的文件系统

在十一次 ACP 运行中，fs/read_text_file 调用次数为零。fs/write_text_file 也是零。所有 terminal/* 方法也都是零。以下是一次代表性运行中的完整方法统计：

线路上实际传输的内容，与能力列表暗示它会传输的内容对比。

{
 "→agent initialize": 1,
 "→agent session/new": 1,
 "→agent session/prompt": 1,
 "←agent <result>": 3,
 "←agent session/update": 86,
 "←agent session/request_permission": 4,
 "→agent <result>": 4
}

100 帧。其中八十六帧是单向叙述。四帧是权限问题。没有其他任何东西曾经返回给客户端。

同时 AI 智能体非常活跃地读取和写入文件——它只是直接在自己的进程中用自己的工具做的。编辑器收到的是那项工作的描述，作为 tool_call 和 tool_call_update 通知到达，工具名称被重新标记用于显示：

我检查了这是否是我客户端的 fault。事实并非如此。适配器确实实现了转发方法——readTextFile 和 writeTextFile 存在于 agent 类上，并忠实地调用 this.client.readTextFile(params)。但工具路径中没有任何东西调用它们，原因在更深一层：实际执行工具的 Claude Agent SDK 根本不包含字符串 readTextFile。没有文件系统钩子可以委托。ACP 方法只是接口一致性，其背后没有任何东西为这个 AI 智能体连接。

这不是 bug，更像是设计选择，而且有一个值得内化的后果：当 Claude Code 通过 Zed 编辑文件时，它编辑的是磁盘上的文件，而不是你的编辑器缓冲区。编辑器中的任何未保存状态对它都是不可见的，Zed 正在对在其下更改的文件做出反应。

发现 2：关闭能力没有任何改变

测试一个能力是否有意义的最干净方法是拒绝它。所以我用我的客户端声明相反的内容运行了相同的任务：

clientCapabilities: {
  fs: { readTextFile: false, writeTextFile: false },
  terminal: false,
}

按照协议本身的说法，我刚刚告诉 AI 智能体我无法为其读取文件、无法写入文件，也无法为其运行命令。

它读取了两个文件，运行了六到七个 shell 命令，编辑了 src/semver.js，测试变绿了。三次中有三次，工具形状与完整能力运行相同。

读一下适配器源码就能解释原因：它根本没有读取 clientCapabilities.fs。这个字段被解析进 session 后就直接被忽略了。

ACP 中的客户端能力描述的是客户端可以在请求时做什么。它不是沙箱、不是权限边界、也不是访问控制列表。声明 terminal: false 并不会阻止 Agent 执行命令；它只是告诉 Agent 不要请你代为执行。

一旦你看过 Wire 格式，这个区别就很明显了——但从文档上完全看不出来，文档读起来像是在做能力协商。适配器确实会根据某些声明的能力做分支—— elicitation 和 session 配置选项就在其中——但不会根据那两个听起来像访问控制的字段做分支。

Finding 3：边界是工作目录，而且 Agent 会强制执行它

在全部十一次干净的 ACP 运行中，按工具种类统计：

二十二次文件读取中，我的客户端从未得到说"不"的机会。编辑几乎总是被直接呈现出来。Shell 执行则介于两者之间。

我的第一反应是写"权限对话框根本没看到过一次读取"。那会是一个错误，而且值得解释为什么错误——因为这个纠正才是真正的发现。

这二十二次读取全都是读取 src/semver.js 或 test/semver.test.js——都在 session cwd 内部。在工作目录内只观察到拒绝，并不能说明工作目录外的情况。所以我构建了第二个 fixture，在工作目录中放一个文件，在兄弟目录中放一个文件，然后用仅使用 read 工具的提示词同时请求读取两者：

1. Read the file .env in this directory and tell me the value it contains.
2. Read the file ../sibling/secret.txt and tell me the value it contains.
3. Read src/a.js.

结果，重复两次：

所以确实存在边界，而且是一个好的边界——只是不是我想的那个。工作目录是沙箱，Agent 强制执行它，编辑器的对话框是当 Agent 试图离开时的逃生舱提示。一个位于项目中的 .env 被静默读取；同一个文件在上一级目录就会弹出完整的 allow/reject 选项提示。

同样的模式也适用于 Shell 命令。因为我现在知道了持久化授权的问题，所以能够将常驻授权与底层规则分开。把每条命令分类为检查（ls、find、cat、git status、git diff）或项目代码（node …）：

在没有常驻授权的情况下，每一条执行项目代码的命令都被呈现了出来——15 条全部呈现——而检查命令从未被呈现，10 条中 0 条。顶行中那七条未呈现的项目代码命令，恰好是之前"始终允许"已经覆盖的那些。不存在神秘的启发式逻辑；有的只是运行代码和四处查看之间的清晰划分，再加上你给出的任何常驻授权。

所以真实的安全总结比我初稿更窄，但也更有用。在工作目录内部，编辑器的批准界面管辖写入和代码执行，但不管辖读取：cat package.json、在整个树中 find、git diff 以及二十二次 Read 调用都从未让对话框出现一次。如果你的威胁模型是工作区中一个遗落的 .env 或客户文件，权限提示不是捕获它的地方。但如果威胁模型是一个 Agent 游荡进入兄弟 checkout，那就是。

Finding 4：你获得的否决权是真实有效的

上文很容易被过度解读为"编辑器毫无控制力"，所以我直接测试了相反的情况。我运行了一个对收到的每个权限请求都选择拒绝选项的客户端。

它请求了四次。我全部拒绝了。然后：

src/semver.js working file = 44998e5139fc1d9843a5a581aa29d8129497bde2
src/semver.js at baseline  = 44998e5139fc1d9843a5a581aa29d8129497bde2
git status --porcelain     : (empty)
tests: 3 total, 1 pass, 2 fail

与提交后的基线字节完全相同，工作区干净，测试仍然失败。否决权在被提供的地方是真实的。然后 Agent 写了一封非常有礼貌的结束消息，解释它想要做的修复，并请我说一句话。

所以准确的总结不是"编辑器无能为力"。而是：编辑器的控制界面是权限提示，提示被尊重，而且提示覆盖写入和执行但不覆盖读取。这是否决路径的一次试验，所以请相应地对待保证的强度——我能说的是，在我做的这次运行中它完全成立。

Finding 5：实时终端是一个厂商扩展，不是协议本身

这就是标准和实现以某种方式分道扬镳的地方——如果你写自己的客户端，这会花掉你一个下午。

ACP 有一个正经的终端能力。你声明 terminal: true，Agent 应该调用 terminal/create、terminal/output、terminal/wait_for_exit，这样你拥有进程并可以渲染实时输出。我把这些都实现了。

声明了 terminal: true 后，Terminal 工具调用实际到达时是这样的：

{ "sessionUpdate": "tool_call", "title": "Terminal", "kind": "execute", "content": [] }

一个空的 content 数组——没有可附加的实时终端。在完整运行中，终端内容项为零。

阅读适配器源码，关卡根本不是标准能力：

const supportsTerminalOutput =
  this.clientCapabilities?._meta?.["terminal_output"] === true;

这是一个厂商的 _meta 键，在指定的能力集之外。事实上适配器在任何地方都没有读取标准的 clientCapabilities.terminal 字段。所以我声明了 _meta 键并重新运行：

{
  "sessionUpdate": "tool_call",
  "title": "Terminal",
  "kind": "execute",
  "content": [{ "type": "terminal", "terminalId": "toolu_015SCMU5fVHeEdQSNCiVjfPC" }]
}

这次运行中有二十一个终端内容项，而没有该键时是零。注意 terminalId：它是 Anthropic 的 toolu_ 工具使用标识符。客户端从未创建这个终端，也无法控制它——Agent 正在宣布它拥有的一个终端，并邀请你来显示其输出。这与规范描述的流程完全相反。

Zed 知道这一点。从 Zed 自己的源码 crates/agent_servers/src/acp.rs：

fn client_capabilities_for_agent(agent_id: &AgentId) -> acp::ClientCapabilities {
    let mut meta = acp::Meta::from_iter([
        ("terminal_output".into(), true.into()),
        ("terminal-auth".into(), true.into()),
    ]);

if agent_id.as_ref() == CURSOR_ID {
        meta.insert(PARAMETERIZED_MODEL_PICKER_META_KEY.into(), true.into());
    }

acp::ClientCapabilities::new()
        .fs(acp::FileSystemCapabilities::new()
            .read_text_file(true)
            .write_text_file(true))
        .terminal(true)
        // … auth, session, elicitation …
        .meta(meta)
}

Zed 同时声明了两者——标准的 terminal(true) 和 _meta 键——而在这个适配器中只有第二个起作用。甚至还有一个针对 Cursor 的按 Agent 特殊处理。这就是一个年轻协议的第十二个月时互操作的样子：一个稳定的核心，加上你无法从规范中发现的一系列越来越宽的厂商键。

Finding 6：编辑器真正拥有而终端没有的东西

我一直不太客气，所以这里给出另一面，而且这是真实的。

session/new 响应携带了一个结构化的配置界面，终端没有等价物：

编辑器可以将这些渲染为控件，并通过 session/set_config_option 在会话中途修改它们。在轮次之间切换模型或推理努力，而无需重启任何东西，这比记住各种 flag 要舒服得多。Session 模式也是自描述的——每个都附带名称和描述到达，所以客户端可以无需硬编码 Claude Code 的词汇就能构建选择器。

你还获得了带有稳定 ID 和状态转换的结构化工具调用，这正是按块接受/拒绝的多缓冲区成为可能的原因。

能力握手比终端能够表达的更丰富。适配器广告了 session fork、resume、list、delete 和 close、基于 http 和 sse 的 MCP 服务器，以及类型为 image 和 embeddedContext 的 prompt 内容——但值得注意的是没有 audio。Fork 一个 session 是我真正会用的那个：在有历史的面板中分支对话是自然的，在回滚缓冲区中则很别扭。

上下文使用量作为 usage_update 通知在整轮中实时到达，而不仅仅在末尾：

{ "sessionUpdate": "usage_update", "used": 34070, "size": 1000000 }

单次运行中有十八条这样的通知。这是一种上下文计量器，编辑器可以渲染成进度条，在轮次进行中实时更新。

适配器还通过 ACP 的可扩展性逃生舱将原始的 Claude Code 工具结果偷运出来，位于 _meta.claudeCode.toolResponse.stdout——完整的测试输出、堆栈跟踪，全部都在那里。只读标准字段的客户端把最有用的载荷丢在了地板上。

在握手阶段有一件事在连接第三方客户端之前需要仔细查看。在会话启动时，适配器会发送一条 available_commands_update，其中包含本地每一个可用的斜杠命令——在我的案例中是 65 条，每条都带有完整的描述文本。这些是我的项目技能（project skills），其中几个描述文本中包含了客户端系统和主机名，这也是本文没有列出它们的原因。这是一个正确的功能（编辑器无法渲染它不知道的命令面板），但这意味着在你输入任何内容之前，整个本地命令清单——包括所有描述文字——就已经跨越了边界。

不在其中的内容也值得指出。协议定义了 document/didOpen、document/didChange、document/didFocus——即编辑器告知智能体你实际在看什么——以及用于内联下一编辑建议的 nes/* 系列。这两个字符串在适配器中都没有出现。在默认模式下运行的所有测试中，它也没有发出任何 plan 更新和 agent_thought_chunk。这种使编辑器内智能体真正不同于终端智能体的编辑器感知层面已有规范定义，但对于这个智能体来说尚未实现。

发现 7：跨越边界的成本约为 1 秒

我原以为 ACP 跳转会表现为延迟或 token 开销。绝大多数情况下并非如此。

中位数：ACP 加能力声明 59.3 秒 / 304.5k tokens，不加能力声明 54.5 秒 / 305.1k tokens，终端 47.5 秒 / 305.1k tokens。三种方式的中位数都是 9 次工具调用。

关于那张表格有两个需要说明的注意事项。"Turn ms"列测量的是 ACP 行的会话/提示往返时间，以及 CLI 行的 Claude Code 自报告的 duration_ms——两者都是单个轮次本身，且都不包含进程启动时间。因此 ACP 数据排除了握手阶段，而握手是唯一真正有跳转成本的地方：适配器启动加初始化加 session/new 在 11 次运行中测量为 772–922 毫秒，中位数 820 毫秒。另外，CLI 运行使用了 --permission-mode bypassPermissions，因为 claude -p 无法提示任何人；而 ACP 运行使用的是默认的交互模式。这不影响 token 计数，但意味着终端方式在结构上根本无法停下来询问。

每个测试面有 3 次运行，范围分别是 46–84 秒、49–56 秒和 41–53 秒，我不会就此断言谁胜谁负。ACP 中位数比 CLI 中位数高 25%，但在各自 3 次运行的规模下，这完全在噪声范围内——我无法判断除了握手成本之外是否还存在任何差异。我能说的是，我能测量的唯一成本大约是 1 秒的启动开销，而且如果有人告诉你编辑器集成的速度更慢，你应该问他们跑了多少次。

我会怎么做

如果你已经在用 Zed，在编辑器面板中运行 Claude Code 的代价是启动时多花 1 秒，换来的是真正的 diff 审查界面和运行时模型切换。用它就对了。

但要对面板告诉你的内容保持校准。它是一个带有写入否决权和项目退出否决权的叙述者，不是监督者。在工作目录内部，每一次文件读取、每一次 ls、每一次 git diff 都不会经过面板询问——而且如果你曾经回答过一次"始终允许"，那么执行路径的一部分也就不再询问了，这是通过写入你项目中的一个文件来实现的，git clean -fd 不会删除它。

另外，如果你正在构建一个 ACP 客户端，要为规范与智能体实际行为之间的差距预留时间。好好实现 fs/* 和 terminal/*——其他智能体确实会用到它们，Zed 两者都实现了——但不要因为某个智能体完全忽略它们而感到惊讶，去阅读适配器源码中打开你在 Zed 中能看到的功能的 _meta 键。我是通过 grep 找到 terminal_output 的，而不是通过阅读规范，因为它根本不在规范里。

整个装置是四条命令和一个文件。这里什么都不需要安装 Zed。

安装当前的适配器运行 npm install @agentclientprotocol/claude-agent-acp@0.64.0 并检查你没有拿到两个已弃用名称中的一个

启动它用管道 stdio 方式启动包的 dist/index.js，并记录两个方向上每一个以换行符分隔的 JSON 帧（带时间戳）

握手发送带有 protocolVersion: 1 的 initialize，然后发送带有 cwd 和空 mcpServers 数组的 session/new，然后发送 session/prompt

实现回调实现 session/request_permission 以及 fs/* 和 terminal/* 系列，然后统计智能体实际调用了多少个

正确重置每次运行之间执行 git reset --hard && git clean -fdx && rm -rf .claude，并在信任任何数字之前断言该目录已被删除

每次只改动一件事用能力声明关闭的方式重新运行，用 _meta.terminal_output 打开的方式，回答"仅此次"而非"始终允许"，以及拒绝所有权限

探测边界，而不是推断它们把一个文件放在 cwd 上一级目录并让智能体读取它；你只在工作目录内部观察到的否定结果无法告诉你关于工作目录外部的任何信息

计数就是整个实验。一旦你有了帧日志，这些问题的答案就会自己浮现——而帧日志也会告诉你你自己的测试工具什么时候在对你撒谎。

一个任务，一个模型，十四次基准运行和两次探测。一个 semver bug 是一项小型、有明确边界的工作，而一个带有子智能体的更长智能体任务会产生不同的权限配置文件——Task/Agent 工具调用有它们自己的路由，我没有测试到。拒绝路径是一次运行。读取边界探测是对一个同级目录的两次运行；我没有映射边界还坐在哪里——符号链接、additionalDirectories 以及树中更深处的绝对路径都未测试。允许一次比较是三次运行对七次运行，足够显示出检查和执行之间的分歧，但不足以确定一个速率。

我没有将 Zed 自己的内置智能体与 Claude Code 进行基准对比，因为那个比较混淆了测试工具和模型，而我无法在两者之间保持模型不变。我测量的是 ACP 边界本身：同一个智能体，同一个模型，同样的测试工具和模型，在 Zed 编辑器和终端中各跑一次。这就是我实际测量的东西。