/multi-agent-orchestration

ZCode CLI Worker（zcode backend）

2026-09-30 当前合同：日常 Claude Code/Codex；CodeBuddy、独立 ZCode CLI/MiniMax Code、Qoder CN、千问办公仅用户指定时使用。QoderWork 已移除。按需启动与权限以 26-optional-cli-backends.md、27-qwenwork-cli-worker.md 为准；本文 QoderWork/旧 ZCode 无 TUI/旧模型等历史条目不作为当前派发配方。 补充参考：SKILL.md 的 zcode backend 深度说明。研究 2026-08-27（协议全链真机验证）， 同日完成 spawn-worker 端到端转正验证（Task-077）。

1. 概述

zcode 是智谱 ZCode 桌面端内置的官方 CLI（GLM 官方 Harness，源码路径 apps/zcode-cli/packages/cli/dist/zcode.cjs，12MB node bundle）。作为 worker backend 的价值：

• 额度经济：与 ZCode GUI 同端点（open.bigmodel.cn/api/anthropic）同凭证， 吃 GLM Coding Plan 套餐额度（官方活动期内 ZCode 渠道另有加成，2026-08-27 核实为 1.5x 至 2026-08-31；archive 草稿记录的 0.66x 折扣以官方页面为准复核）。
• 多一个模型池：GLM-5.3 / GLM-5.3-Flash 等与 Claude/Codex 系正交，额度 受限时可分流。
• 合规面干净：官方二进制 + 官方协议 + 本人 GUI 登录凭证，无逆向、无指纹 伪造（对比网关类项目的灰色边界）。

与其他四家 backend 的本质差异：桌面端捆绑的 zcode CLI 无独立 TUI（@zcode/tui 未随桌面端打包），因此 spawn 起的是本 skill 自带的 scripts/zcode-worker-driver.py 包装器（§6），不是裸 CLI。2026-09-07 研究修订 （§11）：npm 上存在社区非官方终端客户端 zcode-app-cli（作者 kingsword09，repo kingsword09/zcode-cli，MIT，v3.11.2-21，--version 输出带 zcode-app-cli 前缀，具备交互 TUI），自 ZCode Desktop 提取官方 glm 运行时内核运行、自带 TUI 层——"官方无独立 CLI 分发"仍成立（智谱 官方只有桌面捆绑 CLI）；但本 skill 当前 zcode backend 仍基于桌面捆绑发行版， driver/app-server 路径不变。

2. 二进制位置与首次配置（ prerequisite 清单）

装了 ZCode.app ≠ 可派发。CLI 不在 PATH、凭证不落 cli config—— 首次使用必须走完下面 5 步。check-dependencies.sh --backend zcode 检测的正是这几项，任何一项缺失都有对应修复指引。

首次配置 5 步

# 1) 安装并登录 ZCode 桌面端（App Store/官网 dmg），GUI 内连接 BigModel
#    Coding Plan（左下角"连接使用"）。GUI 登录态写入 ~/.zcode/v2/。

# 2) 建 PATH symlink（官方不发布独立 CLI，CLI 藏在 App bundle 里）
ln -s /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs ~/.local/bin/zcode

# 3) 兜底执行位：bundle 出厂通常带 +x 与 shebang，个别安装可能丢失
chmod +x /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs

# 4) 同步凭证到 CLI config（见下方 JSON 模板；GUI 的 v2 config 与 CLI
#    config 是分离存储，不复制 CLI 无法对话）
# 5) 验证
~/.local/bin/zcode --version          # 应输出版本号（如 0.16.5）
bash <skill>/scripts/check-dependencies.sh --backend zcode   # 三层全 OK

凭证同步模板（步骤 4）

GUI 登录后 ~/.zcode/v2/config.json 里有 provider 定义（含 baseURL + apiKey）； 把它抄进 ~/.zcode/cli/config.json：

{
  "model": "builtin:bigmodel-coding-plan/GLM-5.3",
  "provider": { "builtin:bigmodel-coding-plan": { "kind": "anthropic",
    "options": { "baseURL": "https://open.bigmodel.cn/api/anthropic",
                 "apiKey": "<从 v2 config 原样复制>" } } }
}

• 顶层 model 是字符串引用 "provider键/模型ID"；provider 表在顶层 provider 键（单数），driver/CLI 从这里合并 baseURL/kind/apiKey。
• key 是快照：GUI 刷新凭证后 CLI 会 401，重抄 provider 段即可 （症状：worker turn 秒级 prompt_failed / 401，重做步骤 4）。
• 任何真实 apiKey 不得进入 git / worktree / 日志（SKILL §1 凭证边界）。
• ZCODE_CLI_CONFIG 环境变量可覆盖 config 路径（多装机器/测试用）。
• ZCode.app 升级后 bundle 路径不变（版本号不进路径），symlink 无需重建； 但升级可能重置 +x，回到步骤 3。

3. CLI 关键参数（0.16.5 实测）

zcode -p "<prompt>"            # headless 单发（positional；--prompt 同义）
  --cwd <dir>                  # 工作目录（默认当前目录）
  --mode yolo                  # 无人值守必需：build/plan 模式在 headless 下
                               # 无权限客户端，Write/Bash 全被拒
  --resume <sessionId>         # 续会话（session 存 ~/.zcode/cli/db/db.sqlite）
  --json                       # 收尾输出结构化汇总（sessionId/usage）
zcode app-server               # stdio JSON 协议长驻服务（driver 的底层）
zcode login --no-browser       # Z.ai OAuth（BigModel 登录走 GUI，不需要这条）
zcode doctor / version / plugins list / skills list

注意：--allowed-tools 在 0.16.5 未实现（Unknown option）；无 --model 参数 （模型由 config 决定）。

4. 可用模型

由 ~/.zcode/cli/config.json 的 provider 决定；BigModel Coding Plan 常见： GLM-5.3（1M 上下文）、GLM-5.3-Flash。

全局 vs per-worker 语义

• 全局（默认）：不给 --model 时，所有 worker 共用 config model 字段 指定的模型（如 builtin:bigmodel-coding-plan/GLM-5.3）。

• per-worker：driver 加 --model，在 session/create 拿到 sessionId 后、 flush 队列消息前发一次 session/setModel，仅作用于该 worker 自己的会话， 不影响 config 全局值与其他 worker。用法：

  python3 scripts/zcode-worker-driver.py --model GLM-5.3-Flash        # 裸 modelId
  python3 scripts/zcode-worker-driver.py --model providerId/modelId    # 显式 provider

  裸 modelId 的 providerId 取 config model 字段的 provider 前缀（即当前 登录的 BigModel Coding Plan）。setModel 失败（如 modelId 拼错）driver 打印 错误行并 WARNING，继续用全局模型，不 crash。

• batch 模式不支持模型指定：zcode --prompt 无模型参数， render-runtime-profile.sh 对 --backend zcode --mode batch --model ... 直接报错退出（fail-closed，不静默降级到全局模型）。

session/setModel 真实 schema（2026-08-27 bundle + 真机实测）

{"id": N, "method": "session/setModel", "params": {
  "sessionId": "sess_...",
  "model": {"providerId": "builtin:bigmodel-coding-plan", "modelId": "GLM-5.3-Flash"}
}}

strict 对象；model 必填 {providerId, modelId, variant?}，另有可选 runtimeModel / expectedRevision / persistAsWorkspaceLastUsed（默认 true——会改写全局 config 的 model 字段，一个 worker 的 --model 会 污染所有其他 worker 的默认模型；driver 显式传 false 关闭，PM 双 worker 实测踩坑 2026-08-27）。成功响应空 result，随后 收到 state.updated (model_changed) 事件。真机验证：/status 的 session/read 结果在 result.session.model 回显 {providerId, modelId}（注意不在顶层，projection 里也没有 model）。

5. 关键限制

1. 桌面捆绑发行版无 TUI：zcode/zcode tui 直接跑必报 Cannot find package '@zcode/tui'（bundle 内逻辑：非 SEA 单文件版直接 import 外部包，桌面端打包 未携带）。worker 只能走 driver（长驻协议）或 headless（一次性）。社区非官方 客户端 zcode-app-cli 不受此限（§11，未本机验证）。
2. headless 必须 yolo：无人值守执行需用户授权（与 claude-code bypassPermissions 同级风险面）；install-guard 因此走 prompt-only 降级 （同 codex，需显式 --allow-prompt-only-install-guard）。
3. 15 秒偏好应答窗口：app-server 每个 turn 前发 session/requestRuntimePreferences 服务端请求，客户端超时未答则该 turn prompt_failed。driver 已内置自动应答——绕过 driver 自己写协议客户端 必须处理这个。
4. 并发 = 套餐路数：同凭证多 worker 并发等同 GUI 多窗口；超出 Coding Plan 并发上限会 429。orchestration-personal.json 的 concurrency.per_backend.zcode 应设为 ≤ 套餐路数。
5. 额度活动期限：加成活动有截止（当前核实 2026-08-31），worker 池用量 预算勿按加成期常量化。

6. tmux Worker 启动（driver 模式，标准路径）

bash scripts/spawn-worker.sh \
  --project "$PROJECT" --branch feat/w-zcode --session w-zcode \
  --worker-backend zcode \
  --allow-prompt-only-install-guard "<理由>" \
  --no-trust-auto --no-permission-auto --no-orca-mode

默认命令 = python3 <skill>/scripts/zcode-worker-driver.py（validator 的 trusted-driver 通道唯一放行的 python 形态）。driver 职责：

• 子进程方式长驻 zcode app-server（会话状态在内存，多轮零重启）；
• 自动应答 runtimePreferences（§5.3）；
• PM send 的纯文本 → session/send（进程内注入，纠偏不丢上下文）；
• 事件流渲染为可读行（[session] running (prompt_started) / [driver] send ✓ accepted=True）——tmux capture-pane / Orca terminal read 直接可读；
• PM 侧本地命令：/status（session/read）、/stop（session/stop 软停当前 轮，进程不死）、/compact、/quit。

headless 备选（render --mode batch）： zcode --mode yolo --prompt "$(cat PROMPT_FILE)" ——一次性、无纠偏，仅适合 自包含短任务。

协议参考（自写客户端时）：stdio JSON 裸帧（无 jsonrpc 信封）， {id, method, params} / {id, result|error}；错误码沿用 JSON-RPC（-32601/ -32602/-32004 Session is not active）；服务端会反向发请求（偏好应答）。 session/create 响应的 sessionId 在 result.session.sessionId（嵌套， 非顶层——2026-08-27 真机踩坑记录）。

7. 适用场景

8. 与 Skill 框架的集成

• backend 标识 zcode（canonical 归一仅此拼写；不做 PM host，policy 无 hosts.zcode）。
• 白名单：claude-code / codex PM 可派发；codebuddy/qoderwork-cn PM 派 zcode 被拒（deny_by_default，测试矩阵覆盖）。
• 身份门禁三重门：policy JSON + canonical_harness_backend case + validate-worker-command.py（basename zcode 或 trusted-driver realpath）。
• install-guard：prompt_only_degraded（历史依据"无 PreToolUse hook 机制"）。 2026-09-07 上游研究发现 ZCode 实际支持 Claude 兼容生命周期 hook（含 PreToolUse，配置面 ~/.zcode/cli/config.json 的 hooks.events，见 §11）， 本机未验证、行为暂不变；本地验证通过后再评估 install-guard 是否升级。
• trust/permission/external-imports dialog 自动化默认全关（无 TUI 无 dialog， 避免空等）。
• Session Context（METADATA/STATUS/RESULT）照常：STATUS 由 worker prompt 约定自写（driver 不代写）。
• G24 边界辨析：CHANGELOG G24 "ZCode 类非 CLI harness 不适用本 skill 做 PM" 指 GUI 产品做 PM；zcode CLI 做 worker 是另一回事，两者并存不矛盾。

9. 权限与 scope 控制

• zcode 无项目级 settings/hook 机制（无 .zcode/settings.local.json 等价物） ——scope-guard 的 settings 写入分支对其自然跳过。
• 越界防护依赖：① worktree 物理隔离；② worker prompt 的 allowed/forbidden files 声明；③ yolo 模式下的 PM 巡检（driver 渲染 + /status + 产物 diff）。
• install 授权：--allow-prompt-only-install-guard + INSTALL_AUTHORIZATION 照常生效（prompt 约束层）。

10. zcode spawn 实战坑（2026-08-27 真机记录）

1. sessionId 嵌套：result.session.sessionId，顶层取不到 → driver 早期 版本 session 永不 ready、消息卡 queued（已修，stub 测试同步真实结构）。
2. create 响应在偏好应答之后：先发 create 也要等服务端偏好请求并应答 才返回响应；PM 在 session ready 前 send 的文本由 driver 排队（queue + drain），不丢弃。
3. clean-worktree 的 Orca 路径解析：从 symlink 目录调用时 Orca 可能把 PM 所在目录误判为删除目标而拒绝——在真身仓根目录执行清理可避开 （记忆：spawn/clean 必须站项目根）。

11. 发行版全景与上游 TUI 建模研究（2026-09-07）

证据来源：stablyai/orca 未合并 PR #13965/#16227/#16228（guanbear 系列，实现 "ZCode as a first-class supported agent"，issue #10564）的完整 diff 阅读 + 本机实测（桌面端 0.16.5、npm registry 查询、~/.zcode/cli/config.json 结构、ps 进程观测）。上游设计未合并、非既成事实；标注"未本机验证"的 结论不得写成已验证能力。

11.1 官方捆绑版与社区非官方 TUI 客户端

上游用 zcode --version 输出是否匹配 ^zcode-app-cli\s+\S+ 区分二者； 桌面捆绑版输出裸版本号不命中 → 一律走一次性 argv 注入。该探测依赖版本 输出形状这一未承诺契约——两发行版版本号独立演化，任何一侧改版式都会 静默改变分流结果（本 skill 若未来采用同类探测，须带失效兜底）。

11.2 上游的三层 TUI 建模（对独立发行版才生效）

1. 注入分流：agent-input（等 TUI composer 就绪后粘贴 prompt）vs startup-command（argv 一次性）。远程会话、用户命令覆盖、交互失败后的 10 分钟冷却期一律 fail-closed 落到 startup-command。
2. 就绪三重门：进程 ready（entrypoint 识别为 zcode-cli）→ composer input-ready（draft-paste-ready 扫描器盯 bracketed-paste ?2004h 等信号， 区分 shell 光标与真正的 agent composer）→ hook 上报 provider session （session_id；10 秒等不到则警告"输出回退终端显示"）。
3. 状态不走 TUI 刮取：生命周期事件走 Claude 兼容 hook（POST 到编排方 本地端口）；会话记录直接读 ZCode 自己的 SQLite 会话库（同 §3 ~/.zcode/cli/db）。TUI 终端只是启动面与兜底显示面。

对本 skill 的含义：driver（app-server 长驻协议）+ headless 的双路径对桌面 捆绑发行版仍是正确设计，与上游对"签名桌面运行时"的降级处理一致；若未来 需要交互 TUI worker，前置条件是安装社区客户端 zcode-app-cli（非官方， 信任决策归用户；bin 名同为 zcode，安装后必须 which -a zcode 核对未遮蔽 官方软链——本 skill 的 zcode backend 与 credential-sync 均假设软链指向官方 bundle）并重验 §11.1 特征位。

11.3 ZCode hook 能力（上游证据，未本机验证）

上游 PR 向 ~/.zcode/cli/config.json 的 hooks.events 写托管块，事件集为 SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / PostToolUseFailure / PermissionRequest / Stop，payload 为 Claude 兼容格式（session_id 等字段， 上游直接复用 kimi 的归一化器）。配置结构：顶层 hooks: { enabled, events: {<事件名>: [{matcher, hooks: [{type, command, enabled, timeoutMs}]}]} }（JSON 对象树，非 TOML）。若本机验证成立，install-guard（§8）与 worker 状态观测 （PM 巡检可用 hook 事件替代/补充 driver 渲染行）都有升级空间。

并发写风险（本机实证）：~/.zcode/cli/config.json 是多写者文件——本机 存在 .bak-pm / .bak-pm2 / .bak-zcode-worker 备份（本 skill 自己的 credential-sync 与 worker 流程产物），桌面端、CLI、编排方都可能改写它。 任何 hook 安装/凭证同步必须：改前备份、原子写（临时文件 + rename）、改后 校验；不得假设自己是唯一写者。

版本记录

• 2026-08-27：协议全链真机验证（偏好应答/create/send/stop/注入）；backend 转正（Task-077）：identity gate、driver、render、deps、测试矩阵、端到端 两轮产物验收。
• 2026-09-07：发行版全景修订（§1/§5.1/§8/§11）——发现社区非官方终端 客户端 zcode-app-cli（kingsword09/zcode-cli，MIT，v3.11.2-21，--version 带 zcode-app-cli 前缀、自带交互 TUI；实现=提取桌面端官方 glm 内核直跑， 凭证逻辑留在官方内核），"无 TUI"改为按客户端区分、"官方无独立 CLI 分发" 维持成立；上游 orca PR #13965/#16227/#16228 的 TUI 建模研究（注入分流/ 就绪三重门/hook+SQLite 状态通道——其交互路径特征位锚定的正是这个社区 客户端）与 config.json 多写者并发风险入册。社区客户端与 hook 能力均未本机 验证，验证项见 TASKS TASK-2026-09-07-ZCODE-DISTRIBUTION-RESEARCH。