zcode-delegate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ZCode Delegate

ZCode 委托功能

You are the orchestrator. This skill lets you hand a bounded coding task to a separate implementer — the Z.AI ZCode CLI — then review what it produced and land it yourself. You write the brief and own the judgment; ZCode does the typing; you verify and commit.

Nothing here is specific to one orchestrating agent. The loop needs only the ability to run a shell command and read a file. (It is designed for and run on Claude Code; treat other orchestrators as designed-for, not yet proven.)

你是协调者。此技能允许你将一个明确范围的编码任务交给独立的实现工具——Z.AI ZCode CLI——然后审核其产出并自行完成提交。由你撰写任务简报并负责判断；ZCode负责编写代码；你负责验证并提交。

本流程不局限于特定的协调Agent，只需具备执行Shell命令和读取文件的能力即可运行。（该流程专为Claude Code设计并在其上运行；其他协调Agent虽适配设计，但尚未经过验证。）

When NOT to use this

请勿使用的场景

The task is small enough to just do inline — delegation overhead is not worth it.
ZCode is not installed, or its CLI has no model provider configured.
You want to write the code yourself, or you only need a review.

任务足够小，可以直接完成——委托的成本得不偿失。
未安装ZCode，或其CLI未配置模型提供商。
你希望自行编写代码，或仅需要代码审核。

Prerequisites (check once)

前提条件（仅需检查一次）

ZCode is installed. The CLI ships inside the desktop app — it is not on PATH and not on npm. The relay resolves it in this order:
```
--zcode-path <file>
```
or
```
ZCODE_CLI
```
first, then PATH, then the installed app bundle. On Linux the app is an AppImage with no fixed install path, so the flag or the environment variable is required there — the relay guesses nothing.
A model provider is configured for the CLI, with a key it can actually reach. Being signed into the desktop app is not enough — see below.
You are in (or will point
```
--cd
```
at) the target git repository.

The relay records the CLI version and how it was resolved into

result.json

, so a surprising install is visible after the fact.

已安装ZCode。CLI随桌面应用一同发布——它不在PATH环境变量中，也无法通过npm安装。中继工具会按以下顺序查找它：首先是
```
--zcode-path <file>
```
参数或
```
ZCODE_CLI
```
环境变量，其次是PATH，最后是已安装的应用包。在Linux系统中，该应用是AppImage格式，没有固定安装路径，因此必须使用上述参数或环境变量——中继工具不会进行猜测。
已为CLI配置模型提供商，且拥有可正常访问的密钥。仅登录桌面应用是不够的——详见下文说明。
你处于（或将通过
```
--cd
```
参数指向）目标git仓库中。

中继工具会将CLI版本及其查找方式记录到

result.json

中，因此事后可以查看是否存在意外的安装情况。

Authenticating the headless CLI

无头CLI的身份验证

Signing into the ZCode desktop app does not authenticate the CLI this relay drives. The CLI keeps its own config at

~/.zcode/cli/config.json

, separate from the desktop app's, and nothing bridges the two.

zcode login

is the intended path, but where it fails with

OAuth response is not valid JSON

the way in is a Z.AI API key.

Two pieces are needed, and they are separate:

The provider block must exist in

~/.zcode/cli/config.json

. It defines the provider, its endpoint and its models — the environment cannot supply this:

jsonc

{
  "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" }
}

The key can live either in
```
provider.zai.options.apiKey
```
in that file, or in the environment as any one of
```
ZAI_API_KEY
```
,
```
ZCODE_API_KEY
```
, or
```
ANTHROPIC_API_KEY
```
. Prefer the environment — it keeps the secret off disk.

If a run fails with

Model provider is missing an API key: <provider>

, the provider block resolved but no key was found: set one of those variables and re-run.

登录ZCode桌面应用并不能验证此中继工具所驱动的CLI。CLI在

~/.zcode/cli/config.json

中保存自己的配置，与桌面应用的配置相互独立，二者之间没有关联。

zcode login

是标准的验证路径，但如果出现

OAuth response is not valid JSON

错误，则可以使用Z.AI API密钥进行验证。

需要两个独立的配置项：

提供商配置块必须存在于

~/.zcode/cli/config.json

中。它定义了提供商、其端点和模型——这些无法通过环境变量提供：

jsonc

{
  "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" }
}

密钥可以保存在上述文件的
```
provider.zai.options.apiKey
```
中，也可以存储在环境变量
```
ZAI_API_KEY
```
、
```
ZCODE_API_KEY
```
或
```
ANTHROPIC_API_KEY
```
中的任意一个。优先使用环境变量——这样可以避免将密钥存储在磁盘上。

如果运行时出现

Model provider is missing an API key: <provider>

错误，说明提供商配置块已找到但未发现密钥：设置上述环境变量之一后重新运行即可。

Autonomy — read this before dispatching

自主性——调度前请阅读

ZCode's own term is mode. It has four values; only two are usable headlessly.

mode	Behaviour
`yolo`	Writes. ZCode's own default for `--prompt` , and this relay's write-capable default.
`plan`	Refuses edits. What `--read-only` selects.
`build`	Rejected by this relay. No permission client exists headlessly, so tools are blocked and the run exits 0 having done nothing.
`edit`	Rejected for the same reason.

Two limits stated plainly, because ZCode cannot enforce them:

plan
mode refused edits in testing, but the relay does not treat that as a guarantee. It takes a Git fingerprint before the run and reports a tri-state
```
readOnlyViolation
```
afterwards. Confirm
```
touchedFiles
```
came back empty rather than assuming no edits.
ZCode has no
--allowed-tools
. Only the
```
--disallowed-tools
```
denylist exists, and it is genuinely enforced. An explicit allowlisted tool surface is therefore impossible here — do not assume one.

ZCode自身将运行方式称为mode，共有四种取值，其中只有两种可用于无头模式：

mode	行为
`yolo`	写入代码。是ZCode使用 `--prompt` 参数时的默认模式，也是本中继工具支持写入的默认模式。
`plan`	拒绝编辑。由 `--read-only` 参数指定。
`build`	本中继工具拒绝使用。无头模式下不存在权限客户端，因此工具会被阻止，运行将退出并返回0，且不会执行任何操作。
`edit`	因相同原因被拒绝使用。

明确说明两个限制，因为ZCode无法强制它们：

测试中
plan
模式会拒绝编辑，但中继工具不将此视为绝对保证。它会在运行前记录Git指纹，并在运行后报告三态的
```
readOnlyViolation
```
状态。请确认
```
touchedFiles
```
为空，不要假设没有进行任何编辑。
ZCode没有
--allowed-tools
参数。仅存在
```
--disallowed-tools
```
黑名单，且该黑名单会被严格执行。因此无法实现明确的工具白名单——请勿假设存在白名单。

The loop

流程步骤

Run these five steps per task. Steps 1, 4, and 5 are your judgment; 2 and 3 are mechanical.

每个任务都需要执行以下五个步骤。步骤1、4、5需要你进行判断；步骤2、3为机械操作。

1. Write the brief

1. 撰写任务简报

ZCode sees only what you send — no repo memory, no chat history. Everything the task needs goes in the brief: the goal, the current state, what to change, what to leave untouched, the project's actual gate commands (discover them from the repo's CLAUDE.md/AGENTS.md/Makefile — do not assume), and a report contract. Tell ZCode it will not commit. One task per brief. The relay delivers the brief as an attached file, so the command line no longer bounds its length — the model's context window still does. Full guidance and a template: references/writing-the-brief.md.

ZCode仅能看到你发送的内容——没有仓库记忆，没有聊天历史。任务所需的所有信息都必须包含在简报中：目标、当前状态、需要修改的内容、需要保留的内容、项目的实际验证命令（从仓库的CLAUDE.md/AGENTS.md/Makefile中查找——不要假设），以及报告要求。告知ZCode它不会提交代码。每个简报对应一个任务。中继工具会将简报作为附件发送，因此命令行不再限制其长度——但模型的上下文窗口仍会限制。完整指南和模板：references/writing-the-brief.md。

2. Dispatch

2. 调度任务

bash

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo

bash

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo

read-only (review/diagnosis, no edits): add --read-only

只读模式（审核/诊断，不进行编辑）：添加 --read-only

continue a specific session: add --session <sess_...> (from result.json; send only the delta brief)

继续特定会话：添加 --session <sess_...> （来自result.json；仅发送增量简报）

continue the latest session for --cd: add --resume-last

继续--cd指向仓库的最新会话：添加 --resume-last

withhold tools (denylist): add --disallowed-tools "Write,Edit,Bash"

禁用工具（黑名单）：添加 --disallowed-tools "Write,Edit,Bash"

point at the CLI explicitly: add --zcode-path /path/to/zcode.cjs

明确指定CLI路径：添加 --zcode-path /path/to/zcode.cjs

hard time limit (watchdog): add --timeout 2h (default: off)

硬超时限制（监控）：添加 --timeout 2h （默认：无限制）

see all options: node .../relay.mjs --help

查看所有选项： node .../relay.mjs --help


(`<skill-dir>` is this skill's installed directory — the folder containing this `SKILL.md`.)

The relay writes its artifacts to a temp dir, so the repo under review stays clean. It **never
commits** — see step 5. Mechanics, flags, and the `result.json` shape:
[references/dispatch-and-poll.md](references/dispatch-and-poll.md).


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

中继工具会将其生成的文件写入临时目录，因此待审核的仓库保持干净。它**永远不会提交代码**——详见步骤5。机制、参数和`result.json`格式：[references/dispatch-and-poll.md](references/dispatch-and-poll.md)。

3. Wait for completion

3. 等待完成

The relay blocks until ZCode finishes, so back it with whatever your orchestrator offers:

Claude Code: run the Bash call with
```
run_in_background: true
```
; you are notified on completion.
Plain shell / other agents: foreground for short tasks, or background it and poll the result file. The run is done when
```
result.json
```
exists with a
```
status
```
. A pre-run usage error exits 2 and writes no result file, so check the exit code too; a CLI that cannot be found exits 127 but does write a
```
result.json
```
with status
```
zcode_unavailable
```
.

Do not trust progress trackers over reality: read the working tree, not a status line.

中继工具会阻塞直到ZCode完成，因此可以利用协调者提供的后台运行能力：

Claude Code： 使用
```
run_in_background: true
```
执行Bash调用；完成后会收到通知。
普通Shell / 其他Agent： 短任务可在前台运行，长任务可在后台运行并轮询结果文件。当
```
result.json
```
存在且包含
```
status
```
字段时，运行完成。预运行的使用错误会返回退出码2且不会写入结果文件，因此也需要检查退出码；如果找不到CLI，会返回退出码127，但会写入包含
```
zcode_unavailable
```
状态的
```
result.json
```
。

不要依赖进度追踪器，要以实际情况为准：查看工作目录，而不是状态行。

4. Review — do not trust the self-report

4. 审核——不要相信自我报告

Re-run the project's gates yourself. Never take "gates passed" on faith.
Read the diff against the brief: did ZCode do what was asked, nothing more and nothing less?
```
touchedFiles
```
is your starting point.

On a
--read-only
run, check
readOnlyViolation
and confirm
touchedFiles
is empty.

Run the relevant guard skills on the diff if you have them installed.

Full checklist: references/review-and-land.md.

自行重新运行项目的验证命令。永远不要轻信“验证通过”的报告。
对照简报查看差异：ZCode是否完成了要求的任务，不多不少？
```
touchedFiles
```
是你的检查起点。
在
--read-only
运行模式下，检查
readOnlyViolation
状态并确认
touchedFiles
为空。
如果已安装相关的审核技能，对差异运行这些技能。

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

5. Land it

5. 完成提交

The orchestrator commits. Only after the gates pass and the diff holds:

Commit the verified work yourself, with a clear message.
If it needs changes, send a delta brief with
```
--session <sessionId>
```
from the prior
```
result.json
```
, and review again.

由协调者提交代码。只有在验证通过且差异符合要求后：

自行提交已验证的工作，并附上清晰的提交信息。
如果需要修改，使用之前
```
result.json
```
中的
```
--session <sessionId>
```
参数发送增量简报，然后再次审核。

Read-only second opinions

只读模式的第二意见

The relay doubles as a way to get an adversarial second opinion with no write risk: dispatch

--read-only

with a brief listing the agreed points, then each contested point with both positions, and ask ZCode to defend or concede each. Because plan mode's guarantee is measured rather than enforced here, verify

touchedFiles

came back empty instead of assuming no edits.

中继工具还可以用来获取具有对抗性的第二意见，且无写入风险：使用

--read-only

模式调度任务，简报中列出已达成一致的要点，然后列出每个有争议的要点及双方立场，要求ZCode为每个要点进行辩护或让步。由于plan模式的保证是通过检测而非强制实现的，请验证

touchedFiles

为空，不要假设没有进行任何编辑。

Authorization model

授权模型

Delegation is something the human opts into. Once they have, committing verified, gate-passing work is the agreed contract. Two limits: surface, don't absorb (report ZCode's design decisions and defensible-but-unasked turns rather than silently keeping them) and stop for scope changes (if correct completion needs going beyond the brief, ask). The full treatment is in references/review-and-land.md.

委托是用户主动选择的操作。一旦用户选择委托，提交已验证且通过验证的工作是约定的流程。有两个限制：透明化而非隐藏（报告ZCode的设计决策和合理但未要求的变更，不要默默保留）和范围变更时停止（如果正确完成任务需要超出简报范围，需询问用户）。完整说明见references/review-and-land.md。

References

参考文档

references/writing-the-brief.md — how to write a brief ZCode can execute blind: structure, the report contract, embedding the real gate commands.
references/dispatch-and-poll.md —
```
relay.mjs
```
flags, the
```
result.json
```
contract, how the CLI is resolved, backgrounding, and recovery.
references/review-and-land.md — the review checklist, the commit boundary, and the exact-session rework cycle.
references/multi-task-queues.md — running a sequential queue: carrying constraints forward, progress tracking, and the end-of-run coherence check.

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 —— 运行顺序队列：传递约束、进度追踪和运行结束的一致性检查。