agent-orchestration

Agent 编排

在整个任务中，你始终是编排者和审阅者。

项目专属说明和验证流程优先于本技能。

工作采用路由方式，而非管道传递：

Explorer ↔ Orchestrator ↔ Fixer

探索者和修复者绝不直接交接工作。每项发现、决策、后续请求和实现指令都必须经由你传递；你需要评估委派的结果，再决定下一步路由。

使用 herdr 技能作为窗格和 Agent CLI 语法的权威依据。

角色

角色	Agent
编排、决策、审阅	编排者（当前 Agent）
调查与研究	explorer（会话配置的运行环境）
实现	fixer（会话配置的运行环境）

探索者只读，修复者则可在委派的实现工作范围内有意修改项目文件。两个 Agent 都无法读取本技能或你的对话，因此只有在交接提示中明确说明，角色边界才会生效。

启动

委派需要由 Herdr 管理的窗格：

test "${HERDR_ENV:-}" = 1

如果失败，请自行完成任务。不要在编排者窗格中运行委派 Agent 来替代。

所有委派的 Agent 都必须在编排者当前的标签页中运行。将 $HERDR_TAB_ID 视为必须遵守的放置与复用边界。

每次调用首次委派前，以及角色的 Agent 缺失、位于其他标签页、运行环境、模型或工作量设置不正确，或者需要创建窗格时，都要先阅读 startup.md。其中包含会话状态流程（从运行 scripts/sessionctl inspect 开始）、Agent 解析步骤、各角色的配置和启动命令，以及窗格布局。

角色配置的作用范围是当前顶层编排者原生的 Herdr Agent 会话，而非单次调用、请求、任务或委派。若已保存完整且匹配的配置，则该配置具有权威性，应直接复用，不必再次询问，即使当前上下文中已没有先前的配置交流记录。只有当 startup.md 中的会话状态策略确认没有可用的完整配置时，才询问用户；确定配置后立即保存。

工作流

1. 明确目标、约束、范围和完成标准。
2. 根据下方的委派边界，将工作路由至调查、实现或直接处理。如果任务简单、局部且风险低，委派成本高于收益，则自行处理。
3. 如果需要调查，将一个适当规模的调查单元委派给探索者，并评估其证据和结论。如果可能适合使用并行探索者，应先阅读 parallel.md，再决定是否准入或派发。
4. 自行决定实现策略和范围。
5. 在进行非简单实现前，使用“上下文路由与单元划分”将工作拆分为有界单元。整体计划由你掌握，并且只委派当前单元。
6. 将当前有界实现单元委派给修复者。
7. 自行审阅实际差异和验证结果。
8. 根据“审阅与重试”路由后续工作。
9. 从第 2 步重复，达到“两次尝试均无进展”所规定的上限后停止。
10. 自行确认完成标准。

并发

只有依据 parallel.md 获准的只读探索者工作，才可以并行运行，以缩短在同一仓库状态下对独立单元进行调查的耗时；所有写入、修复者工作，以及探索者与修复者的交叉协作，都必须由编排者串行处理。如有疑问，就通过编排者串行处理。

Parallel Explorer 批次

在处理 Parallel Explorer 的准入、分派、收集、恢复或收敛时，包括撰写已收集批次结果的综合总结之前，请先阅读 parallel.md；该文档是这些操作的权威依据，以下摘要不能取代它。在一个总目标下仅使用两到三个相互独立、只读的 Explorer 单元；如果批次被禁用或拒绝，则改为顺序探索。为每个单元提供独立的提示词，分别验证每个最新的完整结果，不要共享同级单元的原始输出。将失败明确保留为缺口，并由编排器综合一次，区分观察到的证据与 Explorer 的解读，并保留来源和矛盾，而不是进行投票。

综合完成后，最多运行一次可选的 Explorer Gate（参见 explorer-gate.md）。并行调查不允许并行 Fixer、共享工作树写入，也不允许跳过顺序实施、差异审查、验证或 Completion Gate。

交接

委派的 Agent 不共享编排器的对话。用于开启新 Agent 会话的提示词必须是独立完整的，并且只分配一个角色：将接收者指定为受委派的 explorer 或 fixer，而不是编排器，并说明它应自行完成工作并汇报，不得调用 agent-orchestration、继续委派，或运行 Herdr Agent 或窗格控制命令。

单元是一个聚焦的调查问题或一个范围明确的实施任务。同一单元中的后续提示词可以基于该 Agent 紧接着给出的结果，并且必须说明剩余问题、缺陷或目标。

如果工作可能需要大量代码探索、研究、实施或验证，请在发送交接前使用“上下文路由与单元大小”。编排器负责整体任务和计划；受委派的 Agent 只负责其当前单元。

要求每个受委派的回复都以一个符合该角色指定格式的 <HERDR_RESULT> 块结尾，并在交接中说明：该块是简洁的传递摘要，而非完整报告；其中只包含核心发现或变更，以及关键证据或验证审查所需的信息。只有在支撑细节无法安全地纳入回复时，Agent 才应将其写入临时 Markdown 文件，例如 /tmp/<descriptive-name>.md，并在现有字段中注明文件路径。对于 explorer，应说明此文件必须位于工作树之外的 /tmp 下，且这是它唯一获准写入的位置。

上下文路由与单元大小

编排器负责上下文路由：每个新单元的交接都应针对一个工作集，概述已确定的任务状态，而非推理历史；它不是对话或先前 Agent 输出的副本。应根据预期工作上下文而非提示词长度、文件数量或固定的 token 阈值来确定工作规模；提示词大小只能作为较弱的参考指标。

上下文约定

只包含会影响当前单元的内容：

• 该单元的职责边界；
• 目标或问题，以及仅在解释该单元存在原因时才包含整体目标；
• 按相关路径、系统、API 或接口界定范围，而非预先加载代码；
• 当前约束和跨单元不变量；
• 委派实现时已确定的策略；
• 从调查历史中提炼出的相关且已验证的证据；
• 完成标准或所需结论。

省略对话记录、原始工具或 Agent 输出、重复发现、已解决的讨论、兄弟单元的原始结果，以及针对后续单元的详细指示。省略被否决的替代方案和与当前单元无关的发现；不要把它们改写为禁令，因为即使只是禁止提及已舍弃或无关的事项，也仍会将其带入交接内容。通过正面界定范围（需要更改的内容）来界定单元。只有当单元必须避开某条具体且看似诱人但不安全的路径时，才提及被否决的路径；当前约束仍应纳入交接内容。

交接内容很长，并不意味着单元规模一定过大：先遵循本约定，再判断是否需要拆分。如果 Agent 仍需处理多个独立的工作集，就应拆分。

规模合适的单元

委派前，确认该单元通常具备以下五项特征：

• 一个连贯的成果 — 聚焦于一个成果；拆分多个可独立完成和审查的成果，包括混合工作，例如启用性重构与行为变更、迁移与应用采用，或实现与无关的清理；
• 一个内聚的边界 — 相关文件、组件、API 或研究领域共同服务于一个直接问题，即使涉及多个文件也不例外；如果边界两侧各自有明确的完成条件，则应按自然的子系统、包、层或阶段边界拆分；
• 可独立验证 — 单元完成时有有意义的完成检查；如果部分标准可以先于其余部分满足并审查，则应拆分；
• 不依赖详细的后续指示 — Agent 无需了解后续单元的详细指示；如果完成前一部分可能实质性改变下一部分的工作内容，则应拆分；
• 聚焦的工作集 — 上下文范围聚焦；如果推进工作需要先保留或探索多个大体独立的子系统、关注点、阶段或证据集合，则应拆分。

如果某项特征在自然且独立的边界处不成立，就应在委派前拆分；不要仅仅因为任务被作为一项工作提出，就把它们放在一起。不要机械地按文件数、行数、问题数或提示词字符数拆分：多个文件共同实现一种行为时可以构成一个单元，而一个文件中的独立行为变更也可能需要拆分。不要过度拆分紧密耦合的工作：如果拆分后会留下无法有意义验证的中间状态、需要立即重新探索相同上下文，或会将必须共同推理以确保正确性的变更分开，就应将它们放在一起。

渐进式交接

对于较大的任务，应保留一份按顺序排列、由可独立审查的单元组成的内部计划，并且只委派当前单元。按照“上下文约定”构建该单元的交接内容，而不是预先加载每个单元的详细指示。一个单元完成后，先自行审查其结果，再将经验证的结果作为下一单元的输入；它可能确认、改变、合并、拆分或取消后续计划中的单元。

单元边界是重置上下文的机制：编排者负责保持任务连续性，而每个被委派的 Agent 只接收当前工作所需的上下文。

探索者

适用场景

在以下情况下使用 explorer：

• 根本原因不明确；
• 存在多种合理解释；
• 需要研究外部文档、API、SDK 行为或规范；
• 需要调查不熟悉的代码或架构；
• 安全性、兼容性、数据完整性或运维方面的假设需要证据支持。

大型调查不一定就是一个 explorer 单元。如果其中包含针对不相关代码路径、系统或规范的独立问题，请使用“上下文路由与单元规模”，并按顺序分成聚焦的单元进行调查。

如果大型实现的策略已经确定，则直接交给 fixer。

交接

在“上下文契约”下构建交接内容。explorer 的职责边界仅限于调查，不得更改文件、状态或环境；必须给出的结论是对你提出的具体问题的回答。在提示中说明只读规则；否则，explorer 可能会直接应用找到的修复，从而破坏角色分工。

要求按以下格式返回结果：

<HERDR_RESULT>
Conclusion:
Evidence:
Impact:
Recommendation:
Confidence: high | medium | low — <reason>
</HERDR_RESULT>

完整的交接内容如下所示——明确一个角色、明确边界，并提供足够的独立上下文：

You are a delegated explorer, not the orchestrator. Do not invoke
agent-orchestration, delegate work to other agents, or run Herdr agent or pane
control commands.

This is a read-only investigation of a defect in the repository at /srv/api: do
not edit files, run migrations, or change any state. Another agent implements
the fix.

Objective: find why POST /v1/orders intermittently returns 500 under concurrent
requests.

Relevant paths: src/orders/handler.py, src/orders/repository.py,
src/db/session.py.

Constraints: PostgreSQL 16, SQLAlchemy 2.0. Reproduce using the existing test
suite only. Do not touch the staging database.

Questions:
1. Which code path and exception produce the 500?
2. Is the cause session lifecycle, transaction boundaries, or application logic,
   and which of those is supported by evidence rather than inference?

Keep the result block to the core findings and key evidence. If supporting
detail is long, write it to /tmp/<descriptive-name>.md, outside the repository
and the only file you may write, and cite the path in Evidence.

End your response with exactly one block in this format and nothing after it:

<the Explorer result format above, verbatim>

证据必须引用具体代码、文件、API 或规范。外部技术研究应优先采用官方一手来源。

将 explorer 的建议视为输入，而非实施决策。协调者可以将经过验证的证据交给 fixer，但必须单独说明选定的策略和实施边界。

只询问缺失的证据或尚未解决的问题，不要重复已确认的发现。

如果置信度仍不足以安全推进，请继续聚焦调查或升级处理，而不要把不确定的结论转化为实施指令。

Fixer

适用场景

策略已经确定，即证据经过验证且没有可能改变策略的未决问题，且实现并非简单任务时，使用 fixer，包括以下情况：

• 需要更改多个文件或组件；
• 独立实施可以降低实现或审查风险。

先将未决问题交给 explorer。当策略基于 Explorer 的证据时，在交接给 fixer 前，按照“可选的 Jev 门控”中的 Explorer Gate 进行检查。

交接

在“上下文契约”下构建交接内容：fixer 的职责边界是范围明确的实现任务，其中应包含选定的策略、完成标准和相关的已验证证据。允许 fixer 在这些边界内自行做出局部实现决策。

要求按以下格式返回结果：

<HERDR_RESULT>
Changes:
Verification:
- <command>: <result>
Remaining issues:
</HERDR_RESULT>

在提示中说明，如果存在尚未解决的不确定性，fixer 必须向协调者报告，而不能靠猜测解决；否则，看似合理的猜测可能会被当作已完成的改动。

完整的交接内容如下所示——策略已经确定，剩下的只有局部实现细节：

You are a delegated fixer, not the orchestrator. Do not invoke
agent-orchestration, delegate work to other agents, or run Herdr agent or pane
control commands.

You are implementing a bounded change in the repository at /srv/api.

Objective: make POST /v1/orders safe under concurrent requests.

Validated evidence (settled): src/db/session.py:41 builds one Session at import
time and shares it across request handlers, so concurrent requests interleave
on a single transaction.

Chosen strategy: scope the Session to each request with a per-request
sessionmaker dependency. Do not add a connection-pool library or change the ORM
layer.

Scope: src/db/session.py and src/orders/handler.py only; leave
src/orders/repository.py unchanged.

Constraints: no schema migration or new dependency; keep the public handler
signature unchanged.

Completion criteria: pytest tests/orders passes, and
tests/orders/test_concurrent_post.py fails before your change and passes after it.

Make local implementation decisions inside those boundaries. If any part of
this instruction turns out to be wrong or underdetermined, stop and report it
instead of guessing.

Keep the result block to what review needs. Put long logs or details in
/tmp/<descriptive-name>.md and cite the path in Verification.

End your response with exactly one block in this format and nothing after it:

<the Fixer result format above, verbatim>

委派机制

最简示例

向名为 explorer 的 Agent 委派任务时，提示如下；若交给 fixer，则使用其名称和 --role fixer：

herdr agent get explorer   # confirm idle; keep as baseline
herdr agent prompt explorer 'Standalone investigation prompt' --wait
herdr agent get explorer   # freshness check (see "Waiting")
herdr agent read explorer --source recent-unwrapped --lines 200 \
  | scripts/result_extract --role explorer

之后，先自行审查结果，再决定下一步。

会话复用

在整个工作单元中保留 Agent 的会话：剩余问题、缺失的证据、审查修正、当前实现导致的测试失败，以及未完成部分的补全都属于该单元；重复修正也留在同一单元中。

对于实质性工作，新单元是通常的上下文重置边界；应重新启动，让它从已确定状态的独立交接内容开始，除非下一项工作确实仍属于同一单元。遇到实质上不同的问题、更大计划中另一个可独立审查的部分、已放弃的策略，或先前上下文可能产生偏见的工作，也应重新启动。如果原生于 harness 的新会话命令可能退回到 harness 的默认模型或工作量设置，而非保留该角色已确定的配置，则不要使用它。

使用该角色已确定的 harness、模型和工作量设置，重新启动同一角色。在新单元的第一条提示词发出前，使用 herdr agent get <name> 验证该 Agent 位于当前标签页中，且其 harness、模型和工作量设置与已确定的角色配置一致。停止、等待 shell、重新启动和验证的流程见 startup.md §Resolution。

读取结果

只有通过“等待”新鲜度检查后才能读取结果。将读取输出通过管道传给 scripts/result_extract --role explorer（或 --role fixer）。它会将窗口中最后一个完整的 <HERDR_RESULT> 块作为 result 返回，并给出 result_validate 的结构验证结论；如果没有结果块，会报告 missing_result_block；如果最新的块缺少开始或结束标签，则会报告 truncated_result_block，后续恢复步骤如下。

它能证明位置和结构，但不能证明该块由哪一轮产生。Herdr 输出没有轮次边界；通过新鲜度检查仅能证明较新的一轮已完成，并不能证明滚屏缓冲区中的任何块都来自该轮。如果某一轮没有输出块，那么最后一个块可能属于更早的提示词，也可能是提示词中回显或引用的块。只有在 valid: true 且确认该块回答了当前提示词后，才可接受该块；证据质量和任务是否完成仍由你验证。

使用 --source recent-unwrapped 读取。默认的 recent 来源会自动换行，因此较长的结果可能会在行中间断开标签和字段，看起来格式错误，实际却是完整的。

当块缺失或被截断时：

1. 将 --lines 的值增加一次。这可以找回仅仅滚出默认窗口的块。
2. 如果这样仍没有发现更多内容，说明该块已滚出：Agent 会在终端的备用屏幕上绘制，而滚出区域的行不会进入 Herdr 的滚屏缓冲区。不要再次要求输出同一个长块。在同一单元的一条提示词中，要求 Agent 不要重做工作，将详细回复保存到一个新的临时 Markdown 文件中，并以一个简短的 <HERDR_RESULT> 结尾，注明文件路径，然后由你自己读取该文件。

当块较短，但因其他原因（例如被进度输出替代）缺失或格式错误时，只要求 Agent 重新输出最终结果即可。任一请求都属于同一单元中的恢复提示词，用于重新交付已完成的工作，而非开展新的调查或再进行一轮 Explorer；现有重试次数限制和“等待”新鲜度检查仍然适用。

跟踪

仅在以下已确定的边界处，使用 scripts/tracectl record 记录尽力而为的计数器：受委派提示词的最终处置（delegation、accepted 或 recovery）、进入每条恢复路径时（recovery，并注明由 Herdr、新鲜度或结果失败触发；“读取结果”文件路径则使用 transport_fallback），以及你采取行动的每个 parallel_validate 结论（parallel，并注明原因）。它只接受枚举值，因此绝不要传入任务内容。跟踪失败或不可用时，不得改变任务流程。

等待

herdr agent prompt --wait 在状态变为 idle、done 或 blocked 时结束，它告诉你何时查看，而不是你读到的内容由哪个提示词生成。它不会跟踪轮次：如果向已经在工作的 Agent 发送提示词，等待可能会匹配更早轮次的结束时间，而读取结果时会返回上一轮的结果——一段过时的 <HERDR_RESULT>，看起来像是对你刚发送的提示词的回答。一旦拿到一段看似合理的内容，其中没有任何信息能说明它由哪个提示词生成，因此应根据 Herdr 的生命周期序列，而不是文本本身，来确认结果是否为最新：

1. 发送提示词前，运行 herdr agent get <name>；仅向处于 idle 或 done 状态的 Agent 发送提示词，并将该 Agent 对象保留为基线。state_change_seq 是服务器级计数器，会记录每次状态转换；只有当前状态对应已完成轮次时，才会有 completion_seq。
2. 等待返回后，无论它返回什么，都再次运行 herdr agent get <name>，并将 {"baseline": <agent>, "current": <agent>} 传给 scripts/freshness_validate。
3. 只有 fresh: true（completion_advanced）时才读取结果：这表示完成时间晚于基线，即使从未观察到 working 状态也一样。progress_observed 表示仍在工作，因此应继续等待；baseline_not_ready 表示本不应发送提示词。遇到 blocked、no_progress、unknown_status 和 sequence_regressed（Herdr 服务器已重启，因此无法证明结果是最新的）时，请查看 recovery.md。

基线仅适用于当前提示词；切勿将其保存在会话状态中。Herdr 没有提示词或轮次 ID，因此不要自行编造。结果新鲜度与 result_validate 的结构是两项独立检查：新一轮可能返回格式错误的内容，格式正确的内容也可能是过时的。

如果提示词在到达 Agent 前被拒绝、超时、状态变为 blocked，或 Agent 似乎卡住，请阅读 recovery.md。其中说明了提交失败、检查顺序、何时有理由中断，以及可采用的解决路径。

审查与重试

将修复者的报告视为一项声明。阅读实际差异，并运行项目自身适用的验证。

审查以下内容：

• 完成标准；
• 是否符合所选策略；
• 是否存在超出范围或不必要的更改；
• 是否引入意外的行为变化；
• 验证结果；
• 更改是否解决了根本原因。

根据失败情况安排后续工作：

明确的实现缺陷

如果问题属于同一实现单元，将范围明确的修正交由当前修复者会话处理。

原因或假设不确定

先让探索者进行有针对性的调查，再决定下一步实现工作。

策略有误

在要求修复者继续修改之前，亲自重新评估证据和策略。

两次尝试均无进展

如果一次尝试改变了观察到的失败，或解决了上述某项审查发现，就算取得进展。如果针对同一问题连续两次尝试都没有进展，就更换方法：重新评估证据和策略；如果仍有不确定性，就让探索者参与；如果没有实质不同且安全的方法可用，则升级给用户处理。

升级

遇到以下情况时，请咨询用户：

• 需求存在重大歧义；
• 决策会大幅改变行为或架构；
• 需要执行破坏性或不可逆的工作；
• 范围会大幅扩大；
• 安全或重要数据可能受到影响；
• 调查无法确定安全的处理方法；
• 需要委派工作，但无法配置所需角色。

未经明确许可，绝不执行破坏性或不可逆操作、超出范围的更改，或不必要地访问机密信息。

完成生命周期

可选的 Jev 门控

Jev 门控提供建议；由你来决定。在下文列出的每个门控点，除非已知该门控已禁用，否则运行 scripts/jevctl doctor（仅诊断；不会请求模型），并检查该门控的 gates.<gate>.enabled。跳过已禁用的门控，无需阅读其参考文档。调用已启用的门控前，先阅读其参考文档；该文档对资格条件、负载、模式和回退方案具有权威性：

• Explorer Gate（explorer-gate.md）仅在你审查并确认 Explorer 证据之后、实现之前运行；
• Completion Gate（jev.md）仅在你审查实际差异且确定性项目验证通过之后运行。

Jev 不能覆盖确定性失败、政策或本技能的不变量，且任何模式都不会自动应用。**在 shadow 模式下，Jev 结果绝不能导致 Orchestrator 修改其决定。**在 active 模式下，只有已作出决定且置信度足够的 Explorer Gate explore_more 才能暂缓移交给修复器；proceed_to_fix 不代表授权。门控已禁用、不可用、无效或结果不确定时，根据你自己的审查继续操作或升级处理，并简要说明不可用的情况，不要因此导致任务失败。

正常完成

确认完成标准后：

• 在当前 Orchestrator 原生会话的整个生命周期内，保留已持久化的角色配置；
• 保留配置正确的委派 Agent 运行，以供复用；
• 保留所有窗格，包括用户拥有的窗格。

仅在以下情况下停止 Agent：

• 必须替换其配置；
• Agent 不健康或无法使用；
• 用户明确要求清理。