grok-delegate

Grok Delegate

对于因 Git 所有权检查而被拒绝的可信仓库，中继支持 --trust-git-root <exact-worktree-root>。此选择加入选项只影响中继的 Git 检查，不会更改持久化 Git 配置或 Grok 权限。请参阅分派与轮询。

你是编排者。此技能让你能将范围明确的编码任务交给单独的 实现者——Grok Build CLI（grok），然后审查其产出并由你亲自提交。你撰写任务说明并负责判断；Grok 会在明确的自主性配置下编写代码；你负责验证并提交。

这里的内容并不针对某一种编排 Agent。整个流程只需要能够运行 shell 命令并读取文件，因此无论你使用的是 Claude Code、Cursor、选择了模型的 OpenCode，还是任何类似的 Agent，都能以相同方式运行。（此流程专为 Claude Code 和 Cursor 设计；其他编排工具仅视为按设计可用，尚未验证。）

以下情况请勿使用

• 任务足够小，可以直接完成——委派带来的额外开销不值得。
• 未安装 grok CLI、未通过身份验证，或账户没有 Grok Build beta 访问权限。
• 你想自己编写代码，或只需要在没有实现者运行的情况下进行审查。

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

1. grok version 可以成功运行。如果不行，请在任意平台上通过 npm i -g @xai-official/grok 安装（或使用 xAI 官方 Grok CLI 文档中的安装程序），然后 进行身份验证（运行 grok login；无头主机上运行 grok login --device-auth；或设置 XAI_API_KEY）。
2. 确认 PATH 中使用的是哪个 grok。 command -v grok 会显示当前使用的二进制文件，grok version 会显示其版本——中继会将运行时的版本记录到 result.json，因此之后可以发现是否使用了过时的二进制文件。
3. 你当前位于目标 Git 仓库中（或将 --cd 指向该仓库）。

流程

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

1. 编写任务说明

Grok 只能看到你发送的文本——看不到编排器聊天历史，也没有共享上下文。任务所需的一切都应写入说明：目标、当前状态、需要更改的内容、需要保持不变的内容、项目的实际门禁命令（从仓库的 CLAUDE.md/AGENTS.md/Makefile 中查找——不要臆测），以及报告约定。告诉 Grok，它不会提交代码（由你提交）。每份说明只包含一项任务。完整指南和模板请参阅：references/writing-the-brief.md。

2. 调度

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

使用随附的辅助工具将简报发送给 Grok。它会封装 grok -p、捕获运行结果并写入结构化的 result.json —— 所以你只需“运行命令，读取文件”。（下文的 <skill-dir> 是此技能的安装目录 —— 即包含此 SKILL.md 的文件夹，也就是你加载此技能时所在的目录。Claude Code 加载技能时会将其打印为“此技能的基本目录”；在其他编排器中也使用同一目录 —— 如果不确定它位于何处，请运行 find ~ -name relay.mjs -path '*grok-delegate*'，并将其上一级目录填入此处。）

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# read-only (review/diagnosis; best-effort — verify touchedFiles): add --read-only
# continue the previous Grok session:       add --resume-last  (send only the delta brief)
# hard time limit (watchdog):               add --timeout 2h  (default: off; implementation runs routinely need 1-2h)
# see all options:                          node .../relay.mjs --help

辅助工具默认采用可写入（workspace-write）的自主配置 —— --always-approve 加上 --sandbox workspace —— 并将其产物写入临时目录，因此受审查的仓库会保持干净。 它 绝不会提交更改 —— 请参阅第 5 步。运行机制、标志和 result.json 的结构： references/dispatch-and-poll.md。

3. 等待完成

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

辅助工具会一直阻塞，直到 Grok 完成，因此请使用编排器提供的机制来等待，并在收到返回后继续：

• Claude Code： 使用 run_in_background: true 运行 Bash 调用；任务完成时你会收到通知。
• 普通 shell／其他 Agent： 对于短任务，在前台运行；对于较长任务，将其放到后台并轮询结果文件 —— 在 bash/zsh（包括 Git Bash/WSL）中使用 … &，或使用对应 shell 的命令（PowerShell 中使用 Start-Job，cmd 中使用 start /b）。当 result.json 存在且包含 status 时，表示运行已完成。（运行前的用法错误 —— 参数错误或简报为空 —— 会以代码 2 退出，并在 stderr 中输出消息，且不会写入结果文件，因此也要检查退出代码。若找不到 grok 二进制文件，则会以代码 127 退出，但 仍会 写入状态为 grok_unavailable 的 result.json。）

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

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

Grok 的 result.json 包含其自身的摘要和门禁声明。请重新验证，不要直接接受：

• 亲自重新运行项目的门禁（第 1 步中的测试／lint／构建命令）。不要轻信“门禁已通过”。
• 根据简报检查差异： Grok 是否按要求完成了工作，没有多做（范围蔓延），也没有少做？touchedFiles 是你的检查起点。
• 如果已安装相关守护技能，请针对差异运行它们（例如 guard-skills 中的 clean-code-guard、test-guard 等）——此技能负责产出工作；这些技能负责评判工作。
• 对于架构／迁移更改，请进行往返验证；对于删除操作，请 grep 查找悬空引用。

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

5. 合并

由编排器提交。 只有在门禁通过且差异符合要求后，才执行以下操作：

• 自行提交已验证的工作，并使用清晰的提交消息。
• 如果需要修改，请使用 --resume-last 发送增量简报（不要重述整个任务），然后再次审查。

自主性模型

Grok 的默认权限模式是 ask，在无头管道中会阻塞，等待审批提示。因此，中继程序始终会显式设置自主性：

中继标志	Grok 获得的权限	适用场景
(默认)	--always-approve --sandbox workspace	常规实现 — 写入范围限于工作树
--read-only	--sandbox read-only --always-approve	审查 / 诊断 — 由内核强制执行的沙箱，并非完全只读（见下方说明）
--full-access	--always-approve --sandbox off	任务需要使用不受限制的工具时，明确选择启用

仅使用 --always-approve 会批准所有工具（写入、shell、网络）——这比工作区范围内的写入更接近不受限制。与 --sandbox workspace 配合使用，才能确保默认设置安全。只有在人类提出要求时，才使用 --full-access。

--read-only 由内核强制执行，并非完全只读。 在 grok 1.0.25 中，只读沙箱（macOS 上的 Seatbelt，Linux 上的 Landlock）会拒绝 grok 自身的写入 / search_replace 工具和 shell 重定向，并返回 EPERM，因此 --always-approve 只会自动批准沙箱内的工具。不过，该配置文件并非完全只读：它仍允许写入 /tmp、/var/tmp 和 ~/.grok/，因此位于这些路径下的仓库并未受到保护；在 macOS 上，它也不会限制子进程的网络访问。之后务必确认 touchedFiles；保证应以差异为准，而不是标志。中继程序会自动执行报告检查：它会解析 git porcelain 的输出，并为已存在未提交更改的 Git 可见路径记录工作树身份和索引条目的指纹。若任一信号证明确有更改，readOnlyViolation 为 true；若检查覆盖完整且未发现更改，则为 false；若覆盖不完整，则为 null。忽略的路径、子模块内部内容、完美还原的更改以及并发更改的归属仍不在检查范围内，因此差异审查仍是最终保障。

授权模型

委派需要人类主动选择。一旦他们表示同意（“运行此队列”、“继续”），提交通过验证和关卡的工作就是双方约定的契约——这正是整个流程的意义所在。该授权有两条限制：展示，不要擅自接纳（报告 Grok 的设计决策、有理有据但未经要求的改动，以及不阻塞流程的小问题，不要默默保留它们）和范围变更时停止（如果要正确完成任务就必须超出任务说明，请先询问——不要自行扩大授权范围）。完整说明请见 references/review-and-land.md。

参考资料

• references/writing-the-brief.md — 如何编写 Grok 可以在无人监督下执行的任务说明：结构、XML 块、报告约定，以及如何嵌入实际的关卡命令。
• references/dispatch-and-poll.md — relay.mjs 标志、result.json 约定、按编排器在后台运行，以及运行异常时的恢复方法。
• references/review-and-land.md — 审查清单、提交边界，以及通过 --resume-last 进行返工的流程。
• references/multi-task-queues.md — 运行顺序队列：延续约束、跟踪进度，以及运行结束时的一致性检查。