上周在 Orca 的设置里翻到一张卡片:GLM Coding Plan,Plan site 选到智谱 BigModel,API key 显示 Saved,下面三行额度——5 小时窗口用了 5%,周额度 92%,MCP 月度 26%。

我先愣了下:ZCode 什么时候成了 Orca 支持的 agent 了?

顺着这条线翻下去,发现这事比"加一个 agent"有味道得多。从有人提 issue 到版本发布,中间隔了 63 天,前后六次 PR 全部没合入。而真正让 PR 落地的,是 9 月 20 日 Z.ai 把 ZCode 开源这件事。

先把话说在前面:我上一篇写过 ZCode 的隐私问题(.enc 快照那件事),这篇只谈集成,两件事不冲突。工具能不能被别的工具接上,和它背后传不传文件,是两个问题。

时间线:卡了两个月,开源五天就合

按北京时间算:

时间发生了什么
7 月 25 日issue #10564 提出:把 ZCode 加成一等 agent
7 月 26 日第一个 PR #10654 提交
8 月中到 9 月中#13965、#14556、#16227、#16228 陆续提交,全部关闭未合入
9 月 20 日再试一次,#21756 提交
9 月 20 日晚Z.ai 开源 zai-org/ZCode(Apache-2.0)
9 月 25 日 17:17PR #22464 合入 main
9 月 27 日清晨v1.4.214 发布,ZCode 首次作为一等 harness 上线
9 月 27 日官网 changelog 把「ZCode agent harness」列为 v1.4.215 的头条

注意一个细节:GitHub 上 1.4.214 的发布时间是 9 月 26 日 22:36 UTC,换算成北京时间是 27 日凌晨。所以国内看这事,就是 9 月 27 日一次性上线的。

之后还有几波补丁,都是在把周边补齐:

  • v1.4.218:ZCode 会话历史进 AI Vault,Coding Plan 额度进 usage
  • v1.4.221:不装 ZCode 也能单独绑 GLM Coding Plan(就是你现在看到的那张卡)
  • v1.4.229:登录复用已有的 setup 终端,会话按记录顺序读
  • v1.4.232:GLM key 可以存在远端 host 上

真卡点:不是代码,是证据

看 PR 正文才知道,前面那六次尝试死在两个无法自证的问题上。

第一个是来路。#21756 的评审里有人明确反对:zcode 到底算不算 Z.ai 官方的东西?如果它只是个第三方客户端,Orca 把它标成 Z.ai 的 agent 就是不准确的。这个问题在官方开源之前,谁也答不上来——你只能指着某个用户装的二进制说"应该是吧"。

第二个更致命:hooks 到底会不会触发。

ZCode 支持在 ~/.zcode/cli/config.json 里配 hooks,官方也有个 issue(zai-org/feedback#32)在抱怨"配好了 hook 但从来不触发"。Orca 的整个状态系统就建立在 hook 上——侧栏的状态点、action required 徽章、完成通知,全靠 agent 主动 POST 心跳。如果 hook 不触发,Orca 接上去就是一个永远显示"空闲"的假面板。

前面六次 PR 的状态机,全都建立在"hook 应该会触发"这个假设上。而假设是没法 code review 的。

9 月 20 日 Z.ai 开源之后,这两条同时有了答案。五天后的 PR 里,作者写了一句很实在的话:

用真实源码(agent CLI 0.16.9)来写,而不是靠猜。

读源码读出来的六个事实

#22464 的 PR 正文里列了六条"读了源码之后改变了实现"的发现。这部分是我觉得整件事里最有信息量的地方,几乎每一条都对应一个别人猜错过的坑。

一、ZCode 的 hook 输出本来就带 Claude 兼容别名。

它的 hook runner 在自己那套 camelCase 字段旁边,额外写了一份 Claude 形状的别名:hook_event_name、session_id、tool_name、tool_input、transcript_path、last_assistant_message。源码注释里说这是有意为之。

结果就是 Orca 不用写新的解析器,ZCode 直接走已有的 Claude 兼容通道,只需要补一个身份标识。这也解释了为什么之前六次 PR 都在同一块地方反复改——大家都以为需要一个独立适配层,其实不需要。

二、hooks.enabled 默认是 false。

这是那条"hook 从来不触发"的真正原因。写 hooks.events 不够,运行时压根没打开开关。Orca 的安装器会把它置成 true,而且如果用户后来手动关回去,状态检查会报 partial,而不是假装一切正常。

一句话总结:不是坏了,是没通电。

三、PermissionRequest 只在审批卡已经显示在屏幕上时才触发。

这条价值很高。它意味着这个事件天然抢在用户回答之前,也不可能为自动批准的调用误触发——所以可以当作"面板被阻塞了"的可信信号。换句话说是免检的。

对比某些其它 agent,同类事件会在各种路径上乱响,你只能靠超时去猜。

四、ZCode 的澄清工具就叫 AskUserQuestion,形状和 Claude 的一模一样。

questions 数组、options 数组。所以 Orca 现有那张问题卡直接复用,没写一行新 UI。

五、它会把进程名改成 zcode-cli。

所以进程识别不能拿启动命令去匹配。这个坑如果不读源码,就得靠用户报"面板检测不到 agent"来发现。

六、它不输出 OSC 标题,而且 banner 永远在动。

终端程序通常用 OSC 序列把标题写出来,agent 就靠这个判断"现在在跑什么"。ZCode 一个都不发,banner 还一直重绘。

于是就绪判断不能等"屏幕安静下来",得等 composer 那个输入框出现。PR 里还专门留了一个测试,把这个负面结论钉住,防止后来的人再试一次屏幕抓取。

本机实测:桌面版自带的 CLI 跑不了 TUI

既然聊到这儿,我把本机的环境对了一遍。

  • Orca:1.4.245
  • ZCode 桌面版:3.17.1
  • 本机 PATH 里的 zcode:没有

第三条是关键。ZCode 桌面版其实自带一份引擎,就在应用包里:

node /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs --version
# 0.17.1

版本号能打出来,看着一切正常。但真去开一个会话:

node /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs tui
# Error: Cannot find package '@zcode/tui' imported from
# /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs

原因不复杂:桌面版打包引擎的时候,把文本界面那块裁掉了,因为它自己画窗口,不需要 TUI。版本号、doctor、一次性 prompt 全都能跑,唯独开不了会话——而 Orca 要的正好就是会话。

Orca 后来专门为这个情况加了一个提示(PR #22730)。它不去匹配"TUI 需要交互式终端"这句报错,因为那句话会被本地化,中文环境里就匹配不上了;它匹配的是 Node 的模块解析错误——Cannot find package '@zcode/tui',这句不会被翻译。

也就是说,Orca 官方对 ZCode 的要求写得很直白:install a zcode build with a terminal UI。要装的是带 TUI 的 zcode,不是桌面版。

还有一个坑:hooks 到底写进哪个文件

Orca 文档说它会把 hooks 写进 ~/.zcode/cli/config.json。但我翻本机这个文件,只有 565 字节,里面没有 hooks 段,旁边也没有 setting.json。

原因是我根本没装 CLI,所以安装器没跑过——这算正常。

但 issue 里有个 Windows 用户的实测报告更值得记:现在的 zcode-app-cli(3.15.x 之后)已经不从 config.json 读 hooks 了,那个文件降级成了"legacy / migration source",真正生效的是 ~/.zcode/cli/setting.json。他手工把同样形状的 hooks 段写进 setting.json,日志里 hookCount 立刻从 0 变成正常值,事件开始触发。

同一份报告里还有三个细节:

  • zcode login zai 的 OAuth 走完了不等于能用。CLI 对 account:* 这类 provider 额外要求一份 Coding Plan 的 API-key 凭证,只有浏览器授权的话,每一轮都会报 Model creation failed。得在 TUI 里 /login,选「Z.AI Coding Plan API Key」,把 key 贴进去。
  • 桌面版开着的时候,会周期性重写 ~/.zcode/v2/provider_config.json,把你手改的模型选择冲掉。调 CLI 之前先把桌面版退掉。
  • ZCode 的用量记在本地 ~/.zcode/cli/db/db.sqlite 里,所以 Orca 做额度统计不需要碰什么未公开的计费接口。

你现在要怎么用

分两种情况,别看混了。

只想看额度和历史:装桌面版就够了。绑 GLM Coding Plan 的那条路(v1.4.221 加的)是独立的,不需要 CLI,key 存进去就能读到 5 小时、周、MCP 三档用量。你现在截图上那个 92% 就是这条路读出来的。

想在 Orca 面板里真的把 ZCode 当 agent 跑:得另装带 TUI 的 zcode。官方给的路径是自己从 zai-org/ZCode 构建命令行发行包(pnpm build:zcode,装到 ~/.zcode/runtime 并软链到 ~/.local/bin);社区有个 zcode-app-cli,把运行时从固定版本的桌面版里提出来再套一层 TUI,也能跑,issue 里 mac 和 Windows 都有人实测通过。

装完确认两件事:command -v zcode 指到你新装的那份,然后 ~/.zcode/cli/setting.json 里能看到 7 个事件——SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、Stop。

最后

这件事让我觉得有意思的不是"又一个 agent 被接上了",而是那个卡了两个月的东西。

六次 PR 里没有一次是因为代码写得太差被拒的。被拒的是论证方式:你说它应该能工作,但拿不出证据。等源码公开,同样的工作五天就落地了。

做开源项目的人可能都熟悉这个循环——有人提 issue,有人说"我这边能跑",但没人能证明它在你机器上也会跑。最后能推动事情的往往不是更多热情,而是一份可复核的源码。

顺一句,写这篇的时候看了一眼额度:周额度已经 92% 了。真要拿它跑重活,等下周。


参考: