Herdr + grok-pi 子代理编排 Skill

Herdr + grok-pi 子代理编排

本技能把 grok-pi 放进一个由 Herdr 管理的新 tab/pane，并用 shell 脚本提交提示词、读取终端状态、等待完成和清理。它是“可见 PTY 编排”，不是把 TUI 当作普通 stdout 管道。

关键约束

禁止失联等待。 创建子代理或提交 prompt 后，必须立即进入 wait/run 轮询。轮询间隔默认 5 秒，最大允许 60 秒，绝不使用超过 75 秒的单次 sleep。
优先使用 run。 run 在同一个命令内完成创建、提交、轮询和输出，避免主代理创建后忘记跟踪。
默认只读。 脚本默认只开放 read,grep,find,ls。只有用户明确要求修改代码时，才通过 --tools 显式开放写入相关工具，并仍需定期检查。
每个任务独立 tab。 不要复用用户已有的 pane；脚本会创建自己的 tab，并把 tab_id、pane_id 和运行状态保存到 ~/.local/state/grok-pi-herdr/（可用 GROK_PI_HERDR_STATE_DIR 覆盖）。
完成判断要有证据。 idle 只能表示当前 pane 没有工作指示器；最终报告还应读取最近输出，确认有回答或明确错误。blocked、exited 和超时都不能报告为成功。
不要把 grok-pi 当作普通 headless CLI。 grok-pi --print-capabilities 表明它内部使用 Pi JSONL RPC，但 grok-pi 自己负责 TUI/PTY；在 Herdr 中通过 pane send-text + pane send-keys 驱动最稳定。不要直接把用户 prompt 管道到 grok-pi 的 stdin。

先做环境检查

herdr --version
grok-pi --version
herdr status --json
herdr api snapshot

必须确认 Herdr server 正在运行。需要了解协议边界时运行：

grok-pi --print-capabilities  # 注意：正确命令是 grok-pi，不是 grok

输出应包含 Pi JSONL RPC over stdio、bridge: pi-grok-adapter -> ACP 和 prompt/get_state 等 RPC 命令。这个结果只用于研究，不改变编排方式：当前技能通过 Herdr PTY 读取可见进度。

脚本位置

~/.pi/agent/skills/grok-pi-herdr-orchestration/scripts/herdr-grok-pi.sh

为了便于复制，下面记为 $RUNNER：

RUNNER="$HOME/.pi/agent/skills/grok-pi-herdr-orchestration/scripts/herdr-grok-pi.sh"

推荐：一次性研究任务

把完整任务放在 -- 后，脚本会在新 tab 启动只读 grok-pi，并持续轮询到结束：

"$RUNNER" run \
  --cwd "$PWD" \
  --label "仓库结构研究" \
  --model grok-4.3 \
  --thinking high \
  --timeout 1800 \
  --output /tmp/grok-pi-research.txt \
  -- \
  '只读研究当前仓库：梳理模块、入口、调用关系和风险。不要修改文件。完成后给出有文件路径依据的结构化报告。'

run 的输出路径是实际从 Herdr pane 读取的终端文本，不是模型 API 的假定响应。成功条件是命令退出码为 0 且输出中有最终回答；超时退出码为 124，blocked/exited 为非零。

分阶段控制

1. 创建

run_id=$("$RUNNER" start \
  --cwd "$PWD" \
  --label "探索代理" \
  --model grok-4.3 \
  --thinking high)
printf 'run_id=%s\n' "$run_id"

start 只负责启动并等待 TUI ready；它返回后不代表任务完成。返回后必须马上提交 prompt 并开始 wait，不可在两个命令之间长时间休眠或结束本轮工作。

2. 提交任务并等待

"$RUNNER" prompt "$run_id" \
  '只读阅读 README、入口文件和相关配置，输出研究结论及证据路径。不要写文件。'
"$RUNNER" wait "$run_id" --timeout 1800

wait 每次检查：

Herdr pane 的前台进程（grok-pi/pi-rpc）是否仍存在；
最近 pane 输出是否显示 Thinking、Waiting for response、Responding 等工作指示器；
是否出现用户选择/批准等阻塞提示；
没有工作指示器时是否已经回到输入提示。

3. 随时查看进度

"$RUNNER" status "$run_id"
"$RUNNER" read "$run_id" 120

status 输出 JSON，其中 state 为 working、idle、blocked 或 exited。主代理在长任务期间应不晚于 60 秒执行一次 status 或 wait 轮询；如果需要向用户汇报，读取 recent_output，不要仅凭进程存在判断进展。

4. 停止和清理

"$RUNNER" stop "$run_id"

脚本先发送 ctrl+q，再关闭它自己创建的 tab，并将状态文件标记为 stopped。不要关闭或接管其他 tab。

编排选择

| 任务 | 方式 | 默认权限 | |---|---|---| | 仓库侦察、架构研究、只读审查 | run | read,grep,find,ls | | 多轮研究，需要追加问题 | start + prompt + wait | read,grep,find,ls | | 用户明确要求子代理修改代码 | start --tools ...，再分阶段 prompt/wait | 仅显式指定 | | 需要取消的长任务 | 保存 run_id，status 后 stop | 不扩大权限 |

若明确要让子代理写代码，使用最小工具集，例如：

run_id=$("$RUNNER" start \
  --cwd "$PWD" \
  --label "实现代理" \
  --tools read,grep,find,ls,bash,edit,write)
"$RUNNER" prompt "$run_id" '先检查现状并提出计划；得到用户确认后再修改。'
"$RUNNER" wait "$run_id" --timeout 1800

不要默认开放 bash/edit/write，也不要把 --always-approve 当作研究任务的必要条件。

故障处理

herdr status 显示 server 未运行：先启动 Herdr，确认 herdr status --json 的 server.running 为 true，再重试。
grok-pi 启动后立即退出：运行 grok-pi --version、检查认证和 herdr pane read <pane>；不要重复创建大量 tab。
状态是 blocked：读取 pane 输出，向用户说明需要什么批准/输入；不要无限轮询掩盖阻塞。
状态是 exited：保留 state 文件和 pane 最后输出，报告退出原因；不能把“进程结束”当成“研究成功”。
只看到 TUI 没有 agent 记录：这是可能的。若启动时禁用了扩展，Herdr 不会收到 Pi lifecycle hook；本技能仍可通过 pane process/output 监控。不要因此改用用户已有 agent pane。
输出不完整：使用 read RUN_ID 500 或指定 run --output PATH，并在最终报告中保留输出文件路径。

最终报告格式

完成后向用户报告：

run_id、cwd 和使用的模型/思考级别；
最后一次观测到的状态及轮询是否遵守 <=60 秒约束；
研究结论和关键证据路径；
输出文件路径（如有）；
如果是 blocked、exited、超时或输出不完整，明确标注，不要包装成成功。

Agent Skills: Herdr + grok-pi 子代理编排

Install this agent skill to your local

Skill Files