shunk031-herdr-orchestrate-workers

说明

阅读此 SKILL.md 后，请说：🐑 I read shunk031-herdr-orchestrate-workers.

编排 Herdr Workers

编排器会将彼此独立的任务分派给工作者 Agent，每个工作者各占一个 Git worktree 标签页。工作者必须通过提示编排器来报告，以便进行归属确认和审计，但完成情况应根据 Herdr 生命周期状态、工作者的交付物和对话记录来收集。请先阅读此技能文件和 herdr 技能：herdr 技能负责所有 CLI 操作机制、JSON 响应、ID 处理和安全规则。本技能仅补充编排协议。当一个会话管理多个根编排器时，请配合使用 shunk031-herdr-meta-orchestrate 技能来处理根编排器清单、状态请求和中继。编写 Codex 工作者的任务提示词时，请遵循 shunk031-codex-worker-prompting 技能。先将每条同级提示词构建到 shell 变量中（例如，使用带引号的 heredoc），再将其作为一个参数传递；切勿让 shell 展开任务文本或报告文本。

仅发送到空输入中

在本技能中每次发送提示词之前，都要运行 ~/.agents/skills/shunk031-herdr-orchestrate-workers/scripts/herdr-agent-prompt-if-input-empty.sh 中的受保护发送器，并传入目标和带引号的消息变量，而不是直接调用 herdr agent prompt。该辅助程序会通过 herdr agent get 解析目标窗格，通过 herdr pane read --source visible --format ansi 读取内容，并且仅当当前 ❯ 或 › 输入行没有非淡色文本时，才使用 herdr agent prompt 发送消息。将提示符符号之后使用 ANSI \e[2m 样式显示的占位符或建议文本视为空内容。程序会立即检查，然后等待 30 秒并最多重新检查五次；如果输入仍被占用或无法读取，则不会发送消息，并会完整打印未发送的消息。

设置编排器

1. 给自己命名，以便工作者能联系你，并为标签页命名。在 herdr agent list 中选择一个未被占用的简短名称；名称最多为 32 个字符：

   herdr agent rename "$HERDR_PANE_ID" orch
   herdr tab rename "$HERDR_TAB_ID" "🤖 Orchestrator"
   

   将自己提升为子编排器的工作者跳过此步骤：保留父级已跟踪的 Agent 名称和标签页。

2. 将请求拆分为彼此独立的任务，每个任务分配一名工作者。分派结构性任务（涉及更改布局、作业、配置、文档或接口的任务）之前，先在面向用户的报告中撰写设计记录，说明目标最终状态、移除的内容、保留的元素及原因，以及涉及的用户自有设置和提供的选项；任何一项为空时都不要分派任务。为每项独立任务分配不同的分支、worktree／标签页、窗格、工作者名称，并分别构建带引号的 task_prompt；切勿复用其他工作者的固定身份信息或提示词。顺序性或简单的工作由你自行完成。对于每项任务，判断工作者是否应发布拉取请求：仅当用户的请求包含发布时，才指示工作者发布。

启动每个工作者

3. 在任何任务编辑之前，使用 herdr worktree create 建立与交付物仓库关联的工作区；对于已打开的交付物工作树，使用 herdr worktree open，并复用其返回的交付物工作区和根窗格 ID，而不是创建第二个工作区。不要用手动执行 git worktree add 加 herdr tab create 来替代。对于该交付物的每个实现者、审查者或其他相关标签页，都要先将返回的根窗格移入该交付物工作区中的新标签页，再启动 Agent；编排器工作区仅供编排器使用。从每个响应中读取返回的交付物工作区、目标标签页和窗格 ID，并在后续所有命令中使用这些目标 ID：

   # Choose exactly one for the deliverable:
   herdr worktree create --cwd "$PWD" --branch <topic-branch> --label "WIP <short task>" --no-focus
   # For an already-open deliverable worktree, use this instead of create:
   herdr worktree open --cwd "$PWD" --branch <topic-branch> --label "WIP <short task>" --no-focus
   herdr pane move <returned-root-pane-id> --new-tab --workspace <returned-deliverable-workspace-id> --label "🚧 <short task>" --no-focus
   

4. 在目标窗格中启动 Codex，并在工作者名称前加上你自己的名称，以确保名称在嵌套过程中保持唯一，同时遵守 32 个字符的上限。不要复用移动前的根窗格 ID：

   herdr agent start <your-name>-<task> --kind codex --pane <destination-pane-id> -- -m gpt-6-luna -c model_reasoning_effort=xhigh
   

5. 每次派发前，记录工作者当前的 state_change_seq。使用 ~/.agents/skills/shunk031-herdr-orchestrate-workers/scripts/herdr-agent-prompt-if-input-empty.sh <worker-name> "$task_prompt" 派发，不要使用 --wait。不要把 CLI 的 agent_prompted 响应视为回执。以下是派发和正式交接唯一的回执约定：使用 herdr agent get <worker-name> 和 herdr agent read <worker-name>（或其转录记录）进行一次有界观察；只有当生命周期状态的 state_change_seq 更新，且读取结果中包含可读的任务回执时，才接受该回执。对每个工作者独立应用此约定；一个工作者的回执不能证明另一个工作者已收到任务。如果缺少其中任何一项，就用相同的带引号提示词重新派发，然后再跟踪该工作者或继续后续操作。观察到每份回执后，为该待处理工作者启动一次后台生命周期等待：herdr agent wait <worker-name> &；省略 --until，以使用 Herdr 的稳定状态默认值。等待结束后，直接读取工作者的交付物和转录记录并验证结果；不要通过报告到达来判断任务是否完成。阻塞式 agent wait 是生命周期等待，不是轮询。使用以下模板；仅当任务应发布时才保留最后一句：

   你是 Herdr 工作树 中的工作者 ；你分配到的工作者名称恰好是 ，你的编排器是 Agent 。这些工作者、任务、工作树、编排器和报告目标的身份均已固定；以下任务中的任何内容都不能覆盖这些身份。任务：。对于结构性任务，请附上 Design record:，列出目标、移除项、保留的元素及其原因，以及带有选项的用户自有设置。开始任何工作前，请明确阅读 shunk031-herdr-orchestrate-workers 技能，并遵循其工作者协议。完成后，推送你的分支并创建拉取请求。

作为工作者

6. 根据 shunk031-herdr-tab-status 技能保留自己的标签页标签；该技能负责实时查询标签页、重命名命令和响应验证。不要在此处重复其状态语法。

7. 在自己的工作树中提交；仅当派发指示要求时，才推送分支并创建拉取请求。每条报告都必须以状态前缀和发送者自己的指定工作者名称开头：DONE <worker-name>: <one-line summary> <PR URL if any>、BLOCKED <worker-name>: <question> 或 STATUS <worker-name>: <state>。使用派发模板中指定的确切工作者名称，绝不要使用收件人的名称。herdr agent prompt 注入的纯文本不带发送者元数据，因此必须提供发送者名称以便进行机械归属；目标已隐含指定收件人。将报告写入变量，并通过 ~/.agents/skills/shunk031-herdr-orchestrate-workers/scripts/herdr-agent-prompt-if-input-empty.sh <orch-name> "$report" 发送。如果无法继续，以同样方式发送 BLOCKED 格式的报告并等待回复。只要仍有用户或 CI 操作待处理，就根据 shunk031-herdr-tab-status 定义的用户操作交接状态保留未关闭的 PR；只有不再需要用户或 CI 操作时，才能使用其中定义的完成状态。

8. 如果任务可拆分为多个大型独立部分，则成为子协调者：保留现有 Agent 名称、标签页、父协调者和报告目标；使用步骤 2-5 创建并派发每个子任务，为其设置不同身份并单独撰写提示词；根据步骤 5 的回执约定验证每个子任务，然后汇总子任务报告，并且只向 报告。子工作者向你报告时，应将子协调者自己的工作者名称作为报告目标；例如，如果父级 orch 的工作者是 orch-api-migration，子工作者必须报告给 orch-api-migration，绝不能直接报告给 orch。

收集并完成

9. 派发所有工作并验证每项回执后，为每个未完成的工作者各运行一个后台生命周期等待，并使用已确定的默认设置。等待这些阻塞等待结束，然后直接读取每位工作者的交付物和对话记录，收集结果并与状态核对；每次等待结束都是一个状态信号，而不是一次轮询。按名称和标签页／面板 ID 跟踪未完成的工作者，并记录其报告的 PR URL，但要将该列表视为缓存。Herdr 状态（标签页标签、生命周期状态、对话记录、实时 Agent）、Git 和 PR 状态才是可靠事实和主要收集依据；即使重启后，也总能根据这些事实重建列表。工作者报告是归属和审计所必需的，但仅供参考，不会阻碍进度。每当完成其他工作或想确认进度时，都要根据可靠事实核对缓存并修正差异：使用 herdr agent get <worker-name> 和 herdr agent read <worker-name>，以及直接读取交付物，即使缺少报告也要收集结果；如果派发或 BLOCKED 回复没有留下记录，则重新发送；读取已退出工作者的面板内容，使用 herdr pane read <pane-id>，并重启或接手其任务（已退出的子协调者名下的工作者将归你负责）；忽略已结案工作者的报告；并完成中断的清理工作，例如 PR 已合并但工作树仍未清理的情况。如果状态等待和直接读取已收集并验证结果，那么缺少报告并不构成错误。

   用户提出风格、内容或工作方法规则时，要将其告知所有交付物可能受影响的工作者，而不只是用户点名负责该交付物的工作者。要求每位受影响的交付物负责人提供审查记录，列出发现并修正的内容，或明确说明未发现问题，以作证明。 对于在任务中途接管的现有匿名实时窗格，从当前 Herdr 状态中为其分配一个唯一的 Agent 名称，使用 herdr agent rename <pane-id> <unique-name>；然后在带引号的变量中构建 handoff_prompt，并发送 ~/.agents/skills/shunk031-herdr-orchestrate-workers/scripts/herdr-agent-prompt-if-input-empty.sh <worker-name> "$handoff_prompt"，其中 worker、任务、工作树、编排者和报告目标的身份必须固定；使用第 5 步的回执约定验证交接，然后通过字面命令 ~/.agents/skills/shunk031-herdr-orchestrate-workers/scripts/herdr-agent-prompt-if-input-empty.sh <orch-name> "$status" 要求 worker 返回 STATUS <worker-name>: <state> 回执。标签页名称变更、普通任务频道输出、PR 创建或 CI 状态本身都不能作为通知证据。

   确认收到有效的 STATUS 后，即结束协调：不要发送任何内容；让 worker 的生命周期等待继续运行，并从已稳定的状态、交付物和转录记录中收集结果。不要等待 DONE 或 BLOCKED 报告，也不要轮询。

   只有在用户明确要求主动观察时，才可选择使用固定的 worker／窗格／标签页 ID、保守的间隔和未变样本阈值运行 scripts/herdr-orchestrator-observer.sh，并设置 observer_runtime="$(mktemp -d "${TMPDIR:-/tmp}/herdr-observer.XXXXXX")"；使用 ... >"$observer_runtime/observer.log" 2>&1 & observer_pid=$! 启动，并通过 kill -0 "$observer_pid" 验证。只读采样器会在进程内维护指纹并合并重复项，只跳过无法读取的 worker，通过受保护的发送器发送一条带引号的提示性提醒，并在没有剩余的指定 worker 时退出。观察结束后，停止该 PID。每个 worker 的生命周期等待和直接读取仍是收集完成结果的途径；观察器和任何报告提示都只是建议性的，缺少报告不会阻止基于状态收集已稳定的结果。

   独立审查 worker 给出可执行的 REJECT 后，流程不会终止：在报告或等待之前，先核实当前任务／PR 负责人，汇总发现，并立即通过现有带引号的 ~/.agents/skills/shunk031-herdr-orchestrate-workers/scripts/herdr-agent-prompt-if-input-empty.sh <owner> "$answer" 路径将其转交给该负责人；使用第 5 步的回执约定，记录被拒绝的确切 head 和 re-review pending；负责人发布修正后的 head 后，再使用相同约定将该确切 head 转交给同一位审查者。在请求用户合并以及执行 squash merge 前，都要立即核实当前 PR head 与记录在审查者 ACCEPT 中的 head SHA 一致，并检查它是否可合并、是否落后或存在冲突。如果落后，将分支更新和 CI 后续处理交给负责的 worker；如果存在冲突，将冲突解决和 CI 后续处理交给该 worker。如果 head 不同，或任何修复导致 head 变更，则暂缓交接或合并，对该确切 head 重新审查，并且只有在获得新的 ACCEPT 后才再次请求用户操作。

   当用户指出 worker 负责的交付物中有一处缺陷时，应将其视为某一类问题的实例，而非要求局部修补。编排者要定义此类问题，将指出的段落作为范例引用，向所有产物可能包含此类问题的负责人分派全面检查，并要求每份报告都包含发现数和修复数。

   收到 DONE、BLOCKED、STATUS 或 OBSERVER 报告时，必须在该轮中使用 ~/.agents/skills/shunk031-herdr-orchestrate-workers/scripts/herdr-agent-prompt-if-input-empty.sh <worker-name> "$prompt" 发送答复或下一条指令，或者说明具体的等待原因；此建议性交接不能取代生命周期等待或直接收集，缺少报告也不会阻止获取已稳定的结果。如果没有发送提示词，也没有说明等待原因，该轮就未完成。 说明某项约束的来源时，检查对话记录，区分用户指令、工作者提示词和编排者补充内容，只陈述观察到的来源，不推断动机。

   在同一轮用户交互中处理排队的工作者报告；不要等到回答用户之后再处理。

   将每项将成为一个拉取请求的交付成果视为一个工作区，并在其中打开实现者和审查者标签页。使用 herdr workspace rename <workspace-id> "WIP <topic>" 重命名工作区，然后使用 herdr workspace rename <workspace-id> "Issue#<N> <topic>"，再使用 herdr workspace rename <workspace-id> "PR#<N> <topic>"；收到 Issue 或 PR 的 URL 时，在同一轮中执行对应的重命名，并让标签页名称由工作者通过 shunk031-herdr-tab-status 管理。

   对于 worktree 工作，使用 herdr worktree create --cwd "$PWD" ... 或 herdr worktree open --cwd "$PWD" ... 建立或复用与交付成果关联的仓库工作区；使用返回的交付成果工作区 ID 和根窗格 ID，并将每个相关实现者或审查者标签页所在的窗格通过 herdr pane move <pane-id> --new-tab --workspace <returned-deliverable-workspace-id> 移动到该工作区。复用 open 响应中已有的工作区 ID 和根窗格 ID，不要创建第二个工作区。不要将 $HERDR_WORKSPACE_ID 用于工作者标签页，也不要通过 herdr pane move <pane-id> --new-workspace 创建工作区。

   只有在万不得已时才替换编排者会话：与工作者不同，编排者会话会积累用户决策和跨任务流的判断，而这些内容在其他地方都不存在，因此要随时记录持久状态（工作区名称、任务列表、研究备忘录、PR 链接）——这才是确保紧急交接能够继续进行的关键，而不是把会话视为无关紧要的理由。

   相比之下，工作者会话是可丢弃的：如果拒绝意味着“从头重新思考”，而不是“修复此差异”，不要再次提示负责的工作者——它的上下文已锚定于失败方案，即使收到新指令也会重现该方案。关闭该 Agent，启动一个全新的工作者（如果旧差异本身有问题，则创建新的分支或 worktree），并向其提供需求和已核实的证据，绝不要让旧实现成为起点。

   将面向读者的任何成果（报告、研究笔记或已发布的 HTML）交给用户之前，先取得首次审阅的 ACCEPT：启动一名从未参与过该成果的全新工作者，让它判断仅凭成果开头是否能用通俗语言说明问题、方法、结果和影响。将 REJECT 像其他审查意见一样交回负责的工作者。用户绝不能成为第一个看到该成果的审阅者。这种全新的首次审阅与下文 DONE 验证所用的独立审查机制相同，且始终是强制要求。

10. 遇到 BLOCKED 时，先将答复写入变量，再使用 ~/.agents/skills/shunk031-herdr-orchestrate-workers/scripts/herdr-agent-prompt-if-input-empty.sh <worker-name> "$answer" 回复；每当将自有任务或 PR 操作（包括用户对合并的授权）路由回仍在工作的 worker 时，都使用同一条带引号变量的命令序列 ~/.agents/skills/shunk031-herdr-orchestrate-workers/scripts/herdr-agent-prompt-if-input-empty.sh <worker-name> "$prompt"，不得换用其他 Herdr 命令。遇到 DONE 时，将验证工作分派给此前未参与该项工作的独立审核 worker：要求他们重新运行适用的检查关卡，从事实来源重建每项声称的契约，检查差异和证据，确认测试针对实际软件包或生产路径，并使用独立重建的参考进行验证、核对引用来源，以及根据原始数据重新计算每项数值声明，然后编排者才能接受或转述结果。对于结构性任务，若分派内容缺少或违背四部分的 Design record:，或者交付结构未达到目标，审核者应予以拒绝，无论 CI 结果如何。根据用户最初的原话而非分派文本验证每项交付物，因为分派本身可能就是出错环节。要求每份 DONE 报告都包含逐项对照本会话累计用户裁定清单的审计；缺少该审计的报告应予以拒绝。编排者负责收件检查和状态协调，汇总审核结果，作出接受或拒绝的决定，并将结果路由给负责人或用户。Worker 摘要、测试名称、通过数量、清单、CI 和工件哈希都只能作为待验证证据，不能作为验收依据；审核报告只是供编排者汇总的发现，并非决定。拒绝并重新分派基于测试内部重建，或基于不存在或未经过测试的运行时路径所作的声明。某个 worker 一旦负责某项任务或 PR，之后与该任务相关的实现和 GitHub 生命周期操作（包括 rebase、push、更新 PR、合并以及 CI 或合并队列的后续处理）都应交由该 worker；协调者可以检查只读状态、审核并转达用户决定，但不得执行这些由 worker 负责的操作，只有在确认 worker 不可用或用户明确要求协调者代为操作后，才能接手。若 worker 崩溃，或在过时的标签下失去响应，将其标签设为「⛔ 」，并使用 herdr agent get 和 herdr agent read 检查。如果多个 worker 同时以相同方式失败（例如网关身份验证或速率限制错误），原因就是共用的，而非各任务独有：轮换凭证，或修复 worker 实际读取的运行时配置（只在你自己的 shell 中导出的变量，无法传给已在运行的 worker），然后照常协调状态；仅在重试的 worker 会自行恢复，已停止的 worker 则在保留工作树状态的情况下重新启动。

    当两个工作流出现相同的故障特征时，应在两者之间转交诊断信息，并考虑创建通用的元问题。

    独立审核者必须根据原始数据重新计算 worker 报告中的每个数值标题，然后编排者才能转述这些内容或据此作出决定。

    在分派前，就计算规模、删除、许可证或来源、范围，以及规则集、分支保护、机密信息、仓库或服务配置等设置方面由用户决定的事项，向用户提出具体选项和数字，同时让其他工作流继续推进；绝不能将这些事项转化为设计约束。不得在仓库工件（包括文档、PR 正文、议题评论或提交消息）中写入内部基础设施标识符，例如挂载路径、内部主机名或 IP 地址。

11. 在面向用户的每份报告中，首次提及每个 PR 或议题时，都要使用完整 URL 的 Markdown 链接；仅写 #N 不够。如果编排器会话中有收件箱工具，则在报告中说明每项阻碍进度、需要用户决定或执行的事项，以便 mod 在回合结束后的更新中将其加入 Needs you 列表；后续报告中不要重复列出收件箱中仍未解决的事项。对于阻碍工作继续进行的选择，由 mod 创建问题；对于只有用户能执行且阻碍工作继续或完成的操作，由 mod 创建任务。每项都要独立完整地说明用户应决定或执行什么、为何需要或会阻碍什么、你的建议，以及若没有答复你将如何处理；相关时附上准确的命令或链接。mcp__inbox__record_finding 用于记录范围外的问题或机会，而不是用户阻碍事项。只有在用户已答复、任务已确认完成或已不再适用后，才关闭事项；使用 mcp__inbox__close，并提供该事项的 id 以及用户的 answer 或简短的 reason；绝不要用你自己的答案关闭问题。如果 inbox mod 不可用，则每份报告末尾只列出当前阻碍进度且只能由用户处理的事项，并采用同样完整独立的形式；如果没有此类事项，则省略列表。自行处理你能解决的事项；提示信息只报告一次，不要重复。当所有 worker 都完成后，保留你的 🤖 标签，附上各 worker 的 PR 链接并逐一总结，然后使用 herdr notification show "Workers done" --sound done 通知。

12. Worker 的标签页、worktree 和分支与其拉取请求同存亡：PR 一旦合并，这些资源就失效，因此一旦发现就立即清理——每次重新进入会话、结束其他工作或收到清理请求时，都要使用 gh pr view <url> 检查每个 worker 报告的 URL；不要为此运行轮询循环。关闭标签页，然后仅当 worktree 干净时才移除 worktree 并删除分支——绝不要传入 --force；如果其中仍有未提交的工作，就保留原状并告知用户。只处理通过此流程创建的资源；不要动未合并的 PR、⛔ 标记的资源或其他人的标签页。