agent-orchestration

在复杂 coding 任务中指导主 agent 做角色分层、顺序阶段、单任务委派、并行独立性判定、反重复规则、结果回收与验证;适合需要 subagent 或 multi-agent 协作的实现、重构、排障和研究任务。

SKILL.md

GitHub

Agent Orchestration

这个 skill 解决的不是“怎么多开几个 agent”,而是主 agent 如何真正承担主控职责。重点是:分层、分阶段、把任务切成可委派单元、判断能否并行、避免重复劳动、回收结果并做验证门禁。

何时使用

  • 复杂功能、复杂重构或跨多个模块的 bugfix
  • 需要主 agent 协调 planner / worker / reviewer / explore 等不同角色
  • 任务里同时包含研究、计划、实现、评审或验证,不适合一个上下文硬做到底
  • 有 2 个以上候选子任务,且其中一部分可能可以并行
  • 你已经感觉“直接写代码”会让主 agent 失去全局视角

不适用:

  • 极小的单文件修改、机械改名、纯文本修正
  • 目标已经非常明确,不需要委派、阶段切换或额外验证
  • 任务重点是实现某个平台的 multi-agent runtime,而不是提升主 agent 的 prompt 纪律

产物

每次使用本 skill,默认产出以下最小集合:

  1. 编排记录
    • 记录本轮角色分层、阶段顺序、是否并行、为什么并行或不并行
    • 若当前任务已有记录文件,优先回写到该文件
    • 若没有既定记录位置,默认写入 .research/orchestration-note.md
  2. 委派任务清单
    • 每个子任务的目标、输入、非目标、预期输出、验证方式、当前状态
  3. 回收与验证结论
    • 每个子任务的结果是否可采纳
    • 哪些需要追问、返工、重派或升级

默认要求:

  • 主 agent 自己维护全局上下文,不把“理解任务”这件事外包给子代理
  • 每次委派都必须是单任务、低歧义、可验证的说明
  • 并行前必须先做独立性判定
  • 子代理结果不能直接信任,必须经过主 agent 的回收与验证

工作流

  1. 先判断是否真的需要编排
    • 看复杂度、跨度、不确定性和角色差异
    • 若是单一明确小任务,直接执行,不为了形式而委派
  2. 做角色分层
    • planner:澄清范围、拆任务、补依赖
    • orchestrator:维护全局状态、决定顺序与并行、回收结果
    • worker:执行明确实现任务
    • explore:做只读研究、检索、现状盘点
    • reviewer:做规格、质量或风险把关
    • 角色是职责,不是必须一一对应为独立运行时对象
  3. 固定阶段顺序
    • 默认按 research -> plan -> execute -> review -> verify 推进
    • 复杂任务不要跳过计划和验证
    • 若阶段口径发生变化,先更新共享记录,再继续推进
  4. 把工作切成单任务单元
    • 一个子任务只解决一个明确问题
    • 一个子任务只应有一个主要交付物
    • 一个子任务必须有清晰边界、输入、非目标和验证方式
    • 不要把“自己看代码决定怎么做”这种大包任务直接丢给子代理
  5. 判断能否并行
    • 只有当子任务彼此独立、写集基本不重叠、没有强顺序依赖时才并行
    • 若多个任务共享同一文件、同一状态或同一关键决策,优先串行
    • 若只是检索、只读盘点或互不干扰的实现,才考虑并行
  6. 写委派 prompt
    • 由主 agent 提炼上下文,不要求子代理自己重新理解全局任务
    • 一次只交给一个明确任务,不把多个目标打包成一个模糊请求
    • 明确写出:
      • 你要解决的单个任务是什么
      • 已知上下文和边界是什么
      • 哪些事不要做
      • 预期输出长什么样
      • 如何证明结果可用
      • 遇到阻塞时如何上报
    • 模板见 references/delegation-template.md
  7. 执行反重复规则
    • 已经委派出去的检索、盘点或审查,主 agent 不重复手工做同样的事情
    • 主 agent 在等待期间,只能做不依赖该结果的非重叠工作
    • 若需要故意比较两个方案,必须显式说明这是“对照实验”,不能伪装成重复委派
  8. 回收结果并做验证门禁
    • 先看子代理返回的摘要,但不要把摘要当证据
    • 主 agent 必须自己读取关键代码、diff、文件或测试结果
    • 至少判断三件事:
      • 结果是否真的覆盖了任务要求
      • 是否引入了额外复杂度或越界修改
      • 是否有 fresh verification evidence
    • 结果不够时,继续追问、返工、重派或升级,不要直接宣称完成

决策约束

  • 主 agent 的职责是保持全局视角,而不是把模糊需求直接扔给子代理
  • 子代理应拿到“可执行任务”,而不是“去帮我想想”
  • 同一问题只交给一个主要责任方,避免重复研究和责任漂移
  • 并行数量服从任务独立性,不服从表面吞吐量
  • 只要结果需要被主线采纳,就必须经过主 agent 的验证门禁
  • 平台术语、工具名和运行时 API 只在明确做适配时再单独补,不要硬编码进核心 skill

失败信号

  • 主 agent 无法说明为什么这个任务适合并行
  • 子代理收到的是一个大而模糊的目标,没有清晰交付物
  • 主 agent 在等待子代理时又自己重做了同样的检索或审查
  • 子代理返回“看起来完成了”,主 agent 没做独立验证就继续推进
  • 多个子代理同时改动同一片核心代码,主 agent 却没有合并策略

模板

需要角色选择、并行独立性检查、单任务委派 prompt 和结果回收模板时,读取 references/delegation-template.md。