commandcode-delegate

Command Code 委派

你是编排者。此技能可让你将范围明确的编码任务交给独立的实现者——Command Code CLI（cmd），然后审查其产出并由你亲自提交。你撰写任务说明并负责判断；Command Code 在你的工作树中编写代码；你负责验证并提交。

这里的内容并不专属于某一种编排 Agent。这个流程只需要能够运行 shell 命令并读取文件，因此无论你使用的是 Claude Code、搭配所选模型的 OpenCode，还是其他同类 Agent，流程都一样。（本流程是为 Claude Code 设计并在其上运行的；其他编排者仅视为适用对象，尚未经过验证。）

不要在以下情形使用

• 任务很小，直接完成即可——委派的开销不值得。
• 未安装或未通过身份验证的 cmd CLI（运行 cmd login）。
• 你想自己编写代码，或者只需要代码审查（Command Code 自带 /review）。
• 你使用原生 Windows，且 cmdc --version 无法运行。上游建议在 Windows 上使用 WSL，以获得稳定体验。

首次派发前请阅读：自主运行模式

Command Code 的无头模式恰好有两种状态，中间没有其他状态：

• **默认状态（使用 -p，不带 --yolo）：**读取、grep 和 glob 均可正常使用。CLI 权限层会拒绝所有写入、编辑和 shell 调用，而无头模式无法在运行中提示你授予权限。这就是中继的 --read-only 模式。
• **--yolo（别名为 --dangerously-skip-permissions）：**允许使用所有工具，范围包括进程能够访问的任何位置。没有文件系统沙箱，也没有路径限制。实现任务需要此模式，因此中继默认会传入该选项。

--permission-mode auto-accept 和 --tools-all 都无法解除无头模式的写入限制。直接通过 CLI 测试时，写入、编辑和 shell 操作在两种设置下都会遭到拒绝。因此，通过 Command Code 执行实现任务属于完全信任运行：应通过严谨的任务说明和干净的工作树控制范围，而非依靠沙箱。任务说明仅提供指导，git worktree 可以隔离检出内容，但无法限制进程。如果不能接受在目标树之外写入文件，请使用 codex-delegate 等由操作系统强制执行的沙箱，或在容器内运行此流程。

前提条件（检查一次即可）

1. cmd --version 能正常运行，且 cmd status 显示已通过身份验证。如果不满足，请安装 Command Code 并运行 cmd login。
2. **确认 PATH 中的 CLI。**在 macOS/Linux 上，command -v cmd 会显示当前使用的 cmd。在原生 Windows 上，使用 cmdc --version；cmd 是系统 shell。中继在 Windows 上使用 cmdc，并通过 cmd.exe 启动其 npm .cmd shim。COMMANDCODE_BIN 仍可作为绝对路径覆盖项使用，但绝不能指向系统命令解释器。中继会在 result.json 中记录运行的版本，因此事后可以发现二进制文件是否错误。
3. 你当前位于目标 git 仓库中（或会将 --cd 指向该仓库），且派发前工作树干净——以干净的基线审查完全信任运行的结果要容易得多。

流程

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

1. 撰写任务说明

Command Code 只能看到你发送的文本——没有仓库记忆、聊天记录或共享上下文（但它会自动读取仓库自己的 AGENTS.md）。任务所需的一切都应写入任务说明：目标、当前状态、需要更改的内容、需要保持不变的内容、项目实际使用的门禁命令（从仓库的 AGENTS.md/CLAUDE.md/Makefile 中查找——不要自行假设），以及报告要求。告知它不要提交代码（由你提交）。每份任务说明只包含一项任务。完整指南和模板见：references/writing-the-brief.md。

2. 分派

对于 Codex 编排后台工作，请先安装并配置独立的 codex-background 支持工具。如果缺少其 MCP 工具或注册表，请停止并 报告设置要求；不要悄悄退回到由模型驱动的轮询。然后调用其已注册的 delegate_run MCP 工具一次，代替下方的 shell 示例。 遵循该技能，使用结构化的通用参数、保持提供方标志不变，并通过 runId 重新连接。 在任务完成前保持请求待处理状态，然后继续执行此技能的审查和落地步骤。其他编排器继续使用下方的 shell 工作流。

使用捆绑的辅助工具将任务简述发送给 Command Code。它会封装 cmd -p、捕获运行结果，并 写入结构化的 result.json——因此你只需要“运行命令，读取文件”。（下方的 <skill-dir> 是此技能的安装目录——也就是包含此 SKILL.md 的文件夹，即你加载此技能的目录。Claude Code 会在技能 加载时将其显示为“此技能的基础目录”；其他编排器使用同一目录——如果不确定它的位置，请运行 find ~ -name relay.mjs -path '*commandcode-delegate*'，并替换为该目录的上级目录。）

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# read-only (review/diagnosis, no edits):   add --read-only
# continue the exact session:               add --session <sessionId>  (from result.json; send only the delta brief)
# fallback when no session id is available: add --continue-last
# hard time limit (watchdog):               add --timeout 2h  (default: off; implementation runs routinely need 1-2h)
# see all options:                          node .../relay.mjs --help

辅助工具默认执行可写入（--yolo）的运行，这会有意修改目标仓库。 其临时目录只会将中继文件保留在该仓库之外。中继绝不会提交—— 请参阅第 5 步。运行机制、标志和 result.json 的结构：references/dispatch-and-poll.md。

3. 等待完成

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

辅助工具会一直阻塞，直到 Command Code 完成，因此请使用编排器提供的相应方式运行，并在其返回后 继续：

• Claude Code： 使用 run_in_background: true 运行 Bash 调用；完成后会收到通知。
• 普通 shell / 其他 Agent： 对于短任务，在前台运行；也可以在后台运行并轮询 结果文件——bash/zsh 中使用 … &，或使用你所用 shell 的等效方式。当 result.json 存在且包含 status 时，运行即已完成。（运行前的用法错误——参数错误或任务简述为空——会以代码 2 退出，并输出 stderr 消息且不写入结果文件，因此也要检查退出代码。缺少 cmd 二进制文件 时会以 127 退出，但仍会写入 status 为 commandcode_unavailable 的 result.json。）

不要相信进度跟踪器，而要以实际情况为准：只有写入 result.json 且进程已退出，运行才算完成。 读取工作树，而不是状态行。实现者的完整报告位于 result.json 的 finalMessage 字段中（也会在 stdout 上的报告标记之间完整打印）。

4. 审查——不要相信自述

result.json 包含 Command Code 自己的摘要和门禁声明。请重新验证，不要照单全收：

• 自行重新运行项目的门禁（第 1 步中的测试、lint 和构建命令）。不要轻信“门禁已通过”的说法。
• 对照任务简述阅读差异：是否完成了要求，既没有做多余的事（范围蔓延），也没有遗漏？结果中的 touchedFiles 是你的检查起点——并且由于此次运行获得了完全信任权限，请检查任务简述指定路径 之外是否也有修改，而不只是检查指定路径之内的修改。
• 如果安装了相关守护技能，请在差异上运行它们（guard-skills 中的 clean-code-guard、 test-guard 等）——此技能负责产出工作；这些技能负责评判工作。
• 对于架构/迁移更改，进行往返验证；对于移除操作，使用 grep 查找悬空引用。

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

5. 提交

中继程序不会提交，但无法阻止 Command Code 在 --yolo 模式下写入 .git。简报禁止实现者提交，而审查者会在提交前将 HEAD 与记录的派发前基线进行比较。由编排器提交。 只有在各项检查通过且差异符合要求后，才能：

• 自行提交已验证的工作，并使用清晰的提交说明。
• 如果需要修改，请使用先前 result.json 中的 --session <sessionId> 发送差异简报（仅在没有会话 ID 时使用 --continue-last），然后再次审查。

只读的第二意见

中继程序还可以用来获取一份中立的对抗式第二意见：使用一份列出已达成共识的要点、再逐一列出有争议的要点及双方立场的简报，派发时加上 --read-only，并要求 Command Code 对每一点进行辩护或让步——最终消息中须给出结果，且不得触碰任何文件。此处的只读保证来自 CLI 自身的权限层，而非操作系统沙箱，因此中继程序还会事后检查：readOnlyViolation: false 表示 Git 可见检测器未发现变更（不包括被忽略的路径或仓库外路径）；true 表示检测到了变更；null 表示 git 无法判断。

授权模式

是否委派由人类自行决定。一旦人类同意（“运行这个队列”“继续”），提交已验证且通过检查的工作就是双方约定的职责——这正是整个流程的目的。此授权有两项限制：指出问题，不要擅自吸收（报告 Command Code 的设计决策、虽可辩护但未受委托的处理，以及不阻塞流程的小问题，而不是默默保留它们）；范围变更时停止（如果正确完成工作需要超出简报范围，请先询问，不要自行扩大授权范围）。完整说明请参阅 references/review-and-land.md。

参考资料

• references/writing-the-brief.md — 如何撰写一份 Command Code 无需额外指导即可执行的简报：结构、XML 块、报告约定，以及如何嵌入实际的检查命令。
• references/dispatch-and-poll.md — relay.mjs 标志、result.json 约定、各编排器的后台运行方式，以及运行异常时的恢复方法。
• references/review-and-land.md — 审查清单、提交边界，以及精确指定会话的返工周期。
• references/multi-task-queues.md — 如何运行顺序队列：延续约束、跟踪进度，以及运行结束时的一致性检查。