zcode-delegate

ZCode 委派

你是编排者。这项技能让你可以把范围明确的编码任务交给单独的实现者——Z.AI ZCode CLI，然后审查它的产出并亲自提交。你编写任务说明并负责判断；ZCode 负责敲代码；你负责验证和提交。

这里的内容并不专属于某一种编排 Agent。这个流程只需要能够运行 shell 命令并读取文件。（它是为 Claude Code 设计并在其上运行的；其他编排者目前仅视为适用对象，尚未经过验证。）

何时不应使用

• 任务足够小，可以直接完成——委派的额外开销不值得。
• 未安装 ZCode，或者其 CLI 未配置模型提供方。
• 你想自己编写代码，或者只需要代码审查。

先决条件（检查一次即可）

1. 已安装 ZCode。 CLI 随桌面应用一起提供——它不在 PATH 中，也不在 npm 上。中继按以下顺序查找：先查 --zcode-path <file> 或 ZCODE_CLI，再查 PATH，最后查已安装的应用包。在 Linux 上，应用是没有固定安装路径的 AppImage，因此必须使用该标志或环境变量——中继不会猜测路径。
2. 已为 CLI 配置模型提供方，且配置了它实际可以访问的密钥。仅登录桌面应用还不够——请见下文。
3. 你位于目标 git 仓库中（或将 --cd 指向该仓库）。

中继会将 CLI 版本及其解析方式记录到 result.json 中，因此事后可以发现意外的安装情况。

为无头 CLI 进行身份验证

登录 ZCode 桌面应用不会为此中继驱动的 CLI 进行身份验证。 CLI 在 ~/.zcode/cli/config.json 中使用自己的配置，与桌面应用的配置分开，两者之间没有任何关联。zcode login 是预期的方式，但如果遇到 OAuth response is not valid JSON 错误，则需要使用 Z.AI API 密钥。

需要分别配置以下两项：

1. 提供方配置块必须存在于 ~/.zcode/cli/config.json 中。它定义提供方、端点和模型——无法通过环境提供这些配置：

   {
     "provider": {
       "zai": {
         "kind": "anthropic",
         "options": { "apiKeyRequired": true, "baseURL": "https://api.z.ai/api/anthropic" },
         "models": { "glm-5.1": { "name": "GLM-5.1" } }
       }
     },
     "model": { "main": "zai/glm-5.1" }
   }
   

2. 密钥可以存放在该文件的 provider.zai.options.apiKey 中，也可以通过 ZAI_API_KEY、ZCODE_API_KEY 或 ANTHROPIC_API_KEY 中的任意一个环境变量提供。建议使用环境变量——这样密钥不会写入磁盘。

如果运行失败并提示 Model provider is missing an API key: <provider>，说明已解析到提供方配置块，但未找到密钥：设置上述任一环境变量后重新运行。

自主性——派发任务前请阅读

ZCode 使用的术语是模式。它有四种取值，其中只有两种可在无头环境中使用。

模式	行为
yolo	写入。 ZCode 对 --prompt 的默认模式，也是此中继支持写入的默认模式。
plan	拒绝编辑。 --read-only 选择的模式。
build	被此中继拒绝。 无头环境中不存在权限客户端，因此工具会被阻止，运行以状态码 0 退出，但不会执行任何操作。
edit	出于同样的原因而被拒绝。

有两项限制需要明确说明，因为 ZCode 无法对此进行强制约束：

• 测试中，plan 模式拒绝了编辑，但中继不会将此视为保证。 它会在运行前获取 Git 指纹，并在运行后报告三态的 readOnlyViolation。请确认返回的 touchedFiles 为空，而不要假定没有编辑。
• ZCode 没有 --allowed-tools。 它只有 --disallowed-tools 拒绝列表，而且该列表确实会被强制执行。因此，此处无法显式指定允许使用的工具范围——请勿对此作此假设。

工作流程

每项任务都按以下五个步骤执行。步骤 1、4 和 5 需要你作出判断；步骤 2 和 3 则是机械操作。

1. 编写任务说明

ZCode 只能看到你提供的内容——没有仓库记忆，也没有聊天记录。任务所需的一切都要写进任务说明：目标、当前状态、需要修改的内容、保持不变的内容、项目的实际检查命令（从仓库的 CLAUDE.md/AGENTS.md/Makefile 中查找，不能想当然），以及报告规范。告诉 ZCode 它不会提交更改。每份任务说明只处理一项任务。中继会将任务说明作为附件文件发送，因此命令行不再限制其长度——但模型的上下文窗口仍有限制。完整指南和模板： references/writing-the-brief.md。

2. 派发

对于 Codex 编排的后台工作，请先安装并配置独立的 codex-background 支持工具。如果缺少它的 MCP 工具或注册表，请停止并报告所需的设置；不要悄悄改用模型驱动的轮询。然后调用已注册的 delegate_run MCP 工具一次，替代下面的 shell 示例。 按照该技能传入结构化的通用参数、保持提供方标志不变，并通过 runId 重新附加。请求完成前保持待处理状态，然后继续执行本技能的审查和交付步骤。其他编排器继续使用下面的 shell 工作流。

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# read-only (review/diagnosis, no edits):   add --read-only
# continue a specific session:              add --session <sess_...>  (from result.json; send only the delta brief)
# continue the latest session for --cd:     add --resume-last
# withhold tools (denylist):                add --disallowed-tools "Write,Edit,Bash"
# point at the CLI explicitly:              add --zcode-path /path/to/zcode.cjs
# hard time limit (watchdog):               add --timeout 2h  (default: off)
# see all options:                          node .../relay.mjs --help

（<skill-dir> 是此技能的安装目录，即包含此 SKILL.md 的文件夹。）

中继会将生成的文件写入临时目录，因此待审查的仓库保持干净。它不会提交更改——见第 5 步。有关执行机制、标志和 result.json 的结构： references/dispatch-and-poll.md。

3. 等待完成

使用 codex-background 的 Codex 会保持原 MCP 请求待处理：不要由模型驱动休眠、状态轮询或日志轮询。仅在请求中断后使用 delegate_wait 重新附加。

中继会一直阻塞，直到 ZCode 完成，因此请使用编排器提供的相应方式：

• Claude Code： 使用 run_in_background: true 运行 Bash 调用；完成后你会收到通知。
• 普通 shell / 其他 Agent： 短任务可在前台运行；也可在后台运行，并轮询结果文件。result.json 中出现 status 即表示运行完成。运行前的用法错误会以 2 退出，且不会写入结果文件，因此也要检查退出代码；找不到 CLI 时会以 127 退出，但会写入 status 为 zcode_unavailable 的 result.json。

不要相信进度跟踪器，要以实际情况为准：读取工作树，而不是状态行。

4. 审查——不要轻信自我报告

• 亲自重新运行项目的检查。 切勿轻信“检查已通过”的说法。
• 根据任务说明检查差异： ZCode 是否恰好完成了要求，没有多做或少做？从 touchedFiles 开始检查。
• 对于 --read-only 运行，检查 readOnlyViolation，并确认 touchedFiles 为空。
• 如果已安装相关防护技能，请针对差异运行它们。

完整检查清单：references/review-and-land.md。

5. 交付

由编排器提交。 只有在检查通过且差异符合要求后，才能：

• 亲自提交已验证的更改，并使用清晰的提交说明。
• 如果需要修改，请使用前一个 result.json 中的 <sessionId> 发送增量任务说明，并附上 --session <sessionId>，然后再次审查。

只读的第二意见

中继也可用于获取无写入风险的对抗性第二意见：使用 --read-only 派发任务，并在任务说明中列出双方达成一致的要点，然后逐一列出有争议的要点及双方观点，再请 ZCode 为每一点进行辩护或让步。由于这里的计划模式保证仅通过测量而非强制执行，因此请核实返回的 touchedFiles 为空，不要想当然地认为没有编辑。

授权模型

委派需要由人主动选择。一旦选择，提交已验证且通过门禁的工作就是双方约定的契约。有两条限制：呈现，而非代为吸收（报告 ZCode 的设计决策，以及有理有据但未被要求的调整，而不是悄悄将其保留）和遇到范围变更时停止（如果正确完成工作需要超出任务说明，请先询问）。完整说明见 references/review-and-land.md。

参考资料

• references/writing-the-brief.md — 如何编写一份 ZCode 可在无人指导下执行的任务说明：结构、报告约定，以及嵌入实际门禁命令。
• references/dispatch-and-poll.md — relay.mjs 标志、result.json 约定、CLI 的解析方式、后台运行及恢复。
• references/review-and-land.md — 审查清单、提交边界，以及精确会话返工周期。
• references/multi-task-queues.md — 如何运行顺序队列：延续约束、跟踪进度，以及运行结束时的一致性检查。