用途:把边界清晰的编码任务委派给独立的实现者 Z.AI ZCode CLI,由其改代码,编排者负责写任务说明、审查产物并亲自提交。循环只需能执行 shell 命令和读取文件,设计上运行于 Claude Code,其他编排器属「设计支持但未验证」。
不适用场景:任务小到可直接手写;未安装 ZCode 或 CLI 未配置模型提供商;只想自己写代码或只做审查。
前提:ZCode 随桌面应用分发,不在 PATH 也不在 npm;relay 依次用 --zcode-path 或环境变量 ZCODE_CLI、PATH、已安装应用包解析,Linux 的 AppImage 无固定路径,必须用参数或环境变量。CLI 使用独立配置 ~/.zcode/cli/config.json,登录桌面应用不等于认证 CLI;zcode login 在报 OAuth response is not valid JSON 时可用 Z.AI API key 代替。需在 config.json 中有 provider 块,key 可放 provider.zai.options.apiKey,或环境变量 ZAI_API_KEY、ZCODE_API_KEY、ANTHROPIC_API_KEY,推荐用环境变量。
自主性:mode 有 yolo(写入,默认)、plan(只读)、build 与 edit(被 relay 拒绝)。ZCode 无 --allowed-tools,只有真正生效的 --disallowed-tools 拒绝列表,因此无法给出白名单工具面。plan 模式在测试中拒绝编辑,但 relay 仅以 Git 指纹前后比对报告 touchedFiles 与三态 readOnlyViolation,需自行确认 touchedFiles 为空。
用法五步:1) 写 brief,包含目标、现状、要改与不改内容、从仓库真实发现的 gate 命令、报告契约,并告知不会提交,一个 brief 一个任务;2) 用 node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo 派发,可选 --read-only、--session、--resume-last、--disallowed-tools、--zcode-path、--timeout;3) 等待完成,relay 阻塞,可用后台运行或轮询 result.json,退出码 2 为用法错误、127 为 CLI 不可用(仍写 status: zcode_unavailable);4) 自己重跑 gate 并读 diff 审查,只读运行检查 touchedFiles 是否为空;5) 通过后由编排者提交,需修改则用 --session 发增量 brief。
只读第二意见:用 --read-only 与列出争点的 brief 获取无写入风险的反驳意见。委派须人工授权,提交通过 gate 的成果是约定契约;需公开 ZCode 的设计决策与越界行为,范围变更要先询问。参考资料:references/writing-the-brief.md、dispatch-and-poll.md、review-and-land.md、multi-task-queues.md。