grok-delegate

Grok 委派

仅通过 Grok Build 原生 CLI 进行跨运行环境编排。父级运行环境负责宏观图；Grok 执行微观节点。

分派

$ARGUMENTS	操作
(empty)	显示预检、波次分类、关键规则和参考索引
preflight	运行 scripts/preflight.sh；遇到 fail 检查项时停止
auth	运行快速身份验证检查；显示 references/auth.md 中的补救方法
trivial	显示 Tier-T 适用条件和单节点 grok -p 模板
wave <0|1|2>	显示侦察／构建／验证波次的命令模板
tune	显示会话恢复／增量提示词循环
leader	显示 leader 池生命周期
ledger	显示会话账本架构
patterns	显示编排器 Pattern A–F → Grok 标志映射

分类关卡

1. 使用条件：父级运行环境负责多节点图，且至少有一个节点应通过原生 CLI 在 Grok Build 上运行。
2. 使用条件：某个关卡失败，父级需要对现有账本行使用 -r <sessionId> 进行调优轮次。
3. Tier-T 默认规则——当快速预检为 ok、grok-auth-expiry 为 ok，且叶节点范围明确（≤3 次读取，或 ≤1 个文件且 ≤80 LOC；不涉及破坏性操作／生产环境／git push／机密；没有未解决的、对用户或子任务至关重要的不确定性）时，默认使用 trivial。由父级负责综合结果。
4. Tier-T 失败回退——如果面向某项父级工作项的首次原生 grok -p Tier-T 分派失败，则停止该工作项的 Tier-T 流程，改为在本地继续。
5. 不要用于 Grok 配置／MCP 同步、技能安装或 Grok 内部嵌套 Grok 编排。
6. 不要将 Tier-T 用于多节点图、文件写入者之间存在重叠，或更适合在会话中完成且范围不受限的父级工作；对于有效的多节点 Grok 图，请使用 wave／patterns。
7. 格式错误的分派——不带 0|1|2 的 wave 无效；请显示有效层级或空参数示例集。绝不要自行设定默认波次。

操作约定

preflight

1. 从任意 cwd 运行 bash scripts/preflight.sh（内置 doctor.py；可选使用 --cwd 指定目标仓库）。
2. 如果 JSON 中的 ok 为 false，或任何 grok-auth-*／grok-binary 检查项为 fail，则停止集群分派。
3. 将 warn 视为提示；任何 grok-auth-expiry 检查项为 fail（过期、缺失或 expires_at 格式错误）时，都会阻止集群分派和 Tier-T 委派。

auth

1. 运行 preflight.sh；检查 JSON 输出中的 grok-auth-* 检查项。
2. 加载 references/auth.md，查看 OAuth 优先的补救方法（grok login）。
3. 可选的深度冒烟测试：bash scripts/auth_verify.sh --cwd <target>。

trivial

1. 确认符合 Tier-T 适用条件（分类关卡第 3 项）。
2. 运行快速预检；要求 ok: true 且 grok-auth-expiry: ok（OAuth 状态正常）。
3. 对于单文件编辑形式，父级必须在分派前运行常规分支和工作区脏状态安全检查。确认目标文件与无关的脏工作没有重叠，并由父级负责审查、综合结果和验证。
4. 分派一个范围明确的节点：

grok --no-auto-update \
  -p "<bounded self-contained task>" \
  --cwd "<absolute-repo-path>" \
  --output-format json \
  --max-turns 10

5. 如果原生分派失败，记录失败情况，停止当前父级工作项的 Tier-T 流程，并在本地继续。

wave <0|1|2>

1. 加载 references/command-templates.md，获取所需层级的模板。
2. 为 wave 1 分配不同的 -w w<wave>-<role>-<n> 名称，并确保文件所有权不重叠。
3. 说明进入下一波前必须通过的父级关卡。

tune

1. 加载 references/session-ledger.md，并使用 -r <sessionId> 恢复会话。
2. 为增量提示词添加前缀 Tune:；每个 node_id 的 parent_tune_count 最多为 3。
3. 切勿默认使用 --always-approve。

leader

1. 加载 references/leader-lifecycle.md。
2. 每个 cwd 池启动一个 leader；图执行完成后，使用 grok leader kill 终止孤立进程。

ledger

1. 加载 references/session-ledger.md。
2. 打开下一个父级关卡前，要求账本中有 N 条终态记录。

patterns

1. 加载 references/graph-patterns.md，并映射到 /orchestrator Pattern A–F。
2. 保持父级计数：分派 N 个节点 = 综合前解决 N 个节点。

(empty)

1. 展示预检、波次分类、关键规则和参考索引。
2. 在分派节点前，对当前父请求运行分类门。

规范术语

术语	含义
parent harness	拥有宏观 DAG 的 Codex、OpenCode、Claude 或 Cursor 会话
Tier-T	快速预检且 grok-auth-expiry: ok 后，通过单次 grok -p 进行的默认有界简单叶节点卸载
node	为图任务调用的一次 grok 子进程
wave	分阶段的节点批次（0 探查、1 构建、2 验证）
gate	进入下一波次前的父级检查点
tune	对现有节点执行的 -r <sessionId> -p "Tune: ..." 增量调整
ledger	跟踪每个节点 sessionId 的 grok-delegate-ledger.jsonl
worktree	使用 -w w<wave>-<role>-<n> 为每个并行构建者提供的 git 隔离环境
leader pool	用于密集图任务的共享 grok agent leader 后端

关键规则

1. 仅使用原生 CLI — 不使用 bin/gk、MCP 控制服务或自定义无头包装脚本。
2. 必须预检 — 在分派任务组或执行 Tier-T 卸载前运行 scripts/preflight.sh。
3. 优先使用 OAuth — 默认运行 grok login；仅在用户明确要求时使用 API 密钥。
4. 父级拥有图 — Grok 深度为 1；通过父级 bash 并行处理同级节点，不要嵌套 Grok 编排。
5. 跨 harness 委派时，切勿默认使用 --always-approve。
6. 自动化路径始终使用 --no-auto-update 和显式的 --cwd。
7. 计数 — 进入下一检查点前，分派的 N 个节点 = ledger 中终止状态的 N 行。
8. 每个 worktree 仅一个写入者 — 并行波次 1 节点之间的文件所有权不得重叠。

适用场景

• 父级通过 bash 分派互相独立的 Grok 节点（Pattern A/E）。
• 快速预检通过且 grok-auth-expiry 检查通过时，默认进行有界的 Tier-T 叶节点卸载。
• 检查点失败后原位调整：-r <sessionId>。
• 使用 -w worktree 进行并行构建，或使用假设 --best-of-n。

不适用场景

• 多节点图或写入者重叠（使用波次，而不是 Tier-T）。
• 破坏性操作、生产环境操作、git 推送、读取密钥或大范围实现工作。
• Grok 配置/MCP 同步 — /harness-master。
• 安装技能 — 仅使用 Skills CLI dry-run 预览（除非维护者要求，否则不要实际执行 --apply）。
• 超出平台深度 1 的 Grok 嵌套 Grok 图。

预检

权威流程：操作员契约 → 上文的 preflight / auth。

bash skills/grok-delegate/scripts/preflight.sh

检查目标仓库：cd <target-repo> && grok inspect --json（grok inspect 没有 --cwd 标志）。

三层模型

1. 父级 — /orchestrator 或 OpenCode Ensemble 管理波次和检查点。
2. 本技能 — 模板、ledger、安全和恢复。
3. Grok CLI — -p、-r、worktree、leader，以及可选的 grok agent stdio。

波次分类

波次	用途	典型的 --agent	--max-turns
0 探查	只读探索	researcher	8
1 构建	实现	仓库 Agent	25
2 验证	测试、评审	code-reviewer	10
调整	会话增量调整	继承	10
假设	竞争性理论	researcher	12

模板：references/command-templates.md。

单个节点

grok --no-auto-update \
  -p "<self-contained task>" \
  --cwd "<absolute-repo-path>" \
  --output-format json \
  --max-turns 25 \
  --agent "<agent-name>"

根据 references/output-json.md 解析 JSON。根据 references/session-ledger.md 追加 ledger 行。

调整循环

grok --no-auto-update \
  -r "<sessionId>" \
  -p "Tune: <delta only>" \
  --cwd "<same cwd>" \
  --output-format json \
  --max-turns 10

每个 node_id 的 parent_tune_count 上限为 3。

并行波次分派

在一条父消息中分派 N 个相互独立的 bash 子进程。每个节点使用唯一的 -w w<wave>-<role>-<n>，且所有权互不重叠。请参阅 references/concurrency.md。

Leader 池

grok agent leader --no-exit-on-disconnect --no-auto-update

客户端通过 grok agent --leader 接入。详情请参阅：references/leader-lifecycle.md。

恢复阶梯

1. 节点失败 → 重试一次；否则将账本状态设为 failed。
2. JSON 解析失败 → 使用 --output-format plain 进行排查。
3. Leader 已停止 → 运行 grok leader list；重启池。
4. 身份验证失败 → 运行 grok login；重新运行预检；暂停整个集群，直至 grok-auth-* 检查通过。

完成标准

• 预检 doctor JSON 返回 ok: true
• 每个已派发的节点都有终态账本状态
• 父级门禁已通过，或已记录用户明确中止
• 已终止孤立的 Leader：grok leader kill

验证

check.py 会运行技能验证、评估验证、审计、doctor 冒烟测试和 parse_grok_json 冒烟测试。

uv run python skills/grok-delegate/scripts/check.py
uv run pytest tests/test_grok_delegate_*.py -q
uv run python skills/skill-creator/scripts/audit.py skills/grok-delegate
uv run python skills/skill-creator/scripts/package.py skills/grok-delegate --dry-run

参考索引

文件	内容
wave-dag.md	Bash 派发时的波次门禁
graph-patterns.md	编排器 A–F + Tier-T 映射
command-templates.md	可复制粘贴的调用命令
output-json.md	无头模式 JSON 字段
session-ledger.md	账本架构
agent-map.md	仓库 Agent → --agent
concurrency.md	配额、命名
leader-lifecycle.md	Leader 启动/停止
acp-driver.md	官方 ACP stdio 摘录
safety-permissions.md	权限矩阵
auth.md	以 OAuth 为主的身份验证与补救措施
doctor-output.md	捆绑的 doctor JSON

官方文档：https://docs.x.ai/build/cli/headless-scripting

范围边界

适用范围： 原生 Grok CLI 委派、波次模板、Tier-T 简单任务分派、会话调优循环、并行 worktree 派发、Leader 池策略。

不适用范围： Grok 配置同步、自定义封装、MCP 服务，或维护者未要求时执行的实时 skills sync --apply。