multi-agent-orchestration

多 Agent 编排

只有当专业分工或安全并行带来的收益超过协调成本时，才使用多个 Agent。

适用场景

• 将大型目标拆分为相互独立且可验证的工作流。
• 协调需要不同工具、权限或上下文的专家。
• 运行工作者—审核者、规划者—执行者、MapReduce 或有界辩论模式。
• 诊断重复工作、编辑冲突、交接不畅或依赖项停滞等问题。

不要仅为增加 Agent 数量而委派紧密耦合、规模较小或本质上必须按顺序执行的任务。

输入

收集目标、完成标准、任务图、可用 Agent 和工具、并发限制、共享文件或系统、权限边界、截止时间、预算以及最终决策负责人。说明假设和未解决的依赖项。

输出约定

输出：

1. 分解理由和明确的非目标。
2. 有向无环任务图，其中每项任务都注明负责人、依赖项、输入、输出约定、写入范围和验证方式。
3. 交接协议和共享状态策略。
4. 审批节点、超时与重试限制、升级途径和停止条件。
5. 综合计划，用于解决分歧并验证整合后的结果。
6. 完成报告，包含证据、尚存的不确定性以及未使用或失败的分支。

工作流

1. 分配工作前，先定义一个可衡量的目标和权限边界。
2. 按可分离的输出进行拆分，而不是按模糊的角色拆分。尽量减少共享的可变状态，并由同一负责人处理紧密耦合的步骤。选择拓扑结构时，请阅读 orchestration-patterns.md。
3. 绘制依赖关系并找出关键路径。只有输入独立且副作用不重叠的任务才并行执行。
4. 为每项任务指定一名负责到底的负责人。说明输入、交付格式、写入范围、验证方式、截止时间或超时时限，以及需要升级处理的情形。
5. 为每个 Agent 提供其所需的最少上下文和权限。需要独立判断时，应提供源材料，而非未公开的结论。
6. 要求结构化交接：状态、结果、证据、状态变更、假设、风险和下一个依赖项。下游操作开始前，先确认已收到交接。
7. 监控依赖状态和有效进展。限制重试和辩论次数；没有明确的容量与所有权模型时，不要递归委派。
8. 在中心位置或通过指定的整合者综合结果。依据一手证据解决相互冲突的说法，运行集成检查，并确认已满足原始完成标准。
9. 结束或取消未使用的工作，记录未解决的风险，并将控制权交还给最终决策负责人。

执行前使用 python3 scripts/validate_plan.py plan.json --strict。该命令会对依赖关系、循环、所有权、审批引用和数值执行限制进行结构检查。严格模式还会针对警告报错，包括精确的并行写入冲突、缺失超时或重试限制，以及不完整的重试约定。它只验证声明，无法验证运行时隔离、授权、审批真实性或实际任务行为。

安全与权限

• 委派不会扩大权限。不得让子 Agent 执行请求者未授权的操作。
• 外部消息、购买、部署、破坏性操作、凭据访问和生产环境变更，都必须经过明确的审批节点。
• 按角色隔离凭据和敏感上下文；不得通过共享状态或交接广播机密信息。
• 对可变资源使用单一写入者所有权、分支、事务或锁。
• 保留用户所有的变更，并确保可以恢复已取消的操作。

验证

• 验证计划无环，且所有依赖项和审批引用都能解析。将影响重大的工作标记为 consequential、deploy 或 external-mutation，并要求其任务级 approval_ref 指向该任务的审批点。
• 确认可并行运行的任务不会写入同一文件、记录、分支或环境。
• 在解除依赖任务的阻塞之前，检查每次交接是否符合其输出约定。
• 综合完成后，重新运行端到端测试或证据检查；单个任务成功并不足够。
• 确认最终报告将所有任务都列为已完成、失败、已取消或已取代。

失败处理

• 如果 Agent 停滞，检查其最新证据；只有在故障属于暂时性故障时才重试一次，然后重新分配或合并该任务。
• 如果 Agent 意见不一致，要求各方提供有来源支持的论据，并由指定的集成负责人裁定；不要对互不兼容的答案取平均值。
• 如果共享状态发生冲突，暂停写入者，保留两个版本，并由唯一负责人进行协调。
• 如果依赖项失败，应阻止下游工作或重新设计，而不是悄悄伪造其输入。
• 如果协调开销超过剩余工作量，停止委派，并由单一负责人完成关键路径。

示例

对于“准备并实现跨平台身份验证变更”，由一位负责人统筹架构和集成，委派相互独立的威胁建模和测试夹具设计；只有在接口冻结后，才分配互不重叠的实现文件；要求每次交接都附上变更路径和测试证据；将生产配置设为须经审批后才能处理；并由集成负责人运行完整测试套件，在宣布完成之前核对安全问题。