核心用法
ia-orchestrating-swarms 是一套面向多智能体协同的编排框架，核心解决「何时分发、如何分发、怎样整合」的分布式 AI 工作流问题。
两种智能体模式
| 模式 | 生命周期 | 通信方式 | 适用场景 |
|------|---------|---------|---------|
| **Subagent（子智能体）** | 任务完成即终止 | 返回值传递 | 搜索、分析、聚焦型任务 |
| **Teammate（队友）** | 持久运行至主动关闭 | 收件箱消息 | 并行工作、流水线、持续协作 |
并行分发策略
- 正确做法：单条消息内并行发起多个
Task调用，实现真正的并发执行 - 错误做法：消息间串行等待，导致人为序列化
- 安全隔离：实现类智能体必须使用
isolation: "worktree"避免 Git 状态冲突
任务描述强制模板
每个分发的任务必须包含：目标（Objective）、专属文件（Owned Files）、接口契约（Interface Contracts）、验收标准（Acceptance Criteria）、明确排除项（Out of Scope）。核心铁律：单一文件唯一所有者。
状态机与故障处理
智能体必须返回四种状态之一：DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT。BLOCKED 时需按决策树分类处理（缺失上下文→补全重试、推理瓶颈→模型升级、任务过大→拆分、规格错误→上报用户）。
协调模型选择
| 模型 | 状态共享方式 | 适用规模 | 风险 |
|------|-----------|---------|------|
| **无状态** | 负责人复制粘贴输出 | 2-3 智能体，串行传递 | 上下文线性膨胀 |
| **有状态** | 共享任务文件+专属所有权 | 4+ 智能体，复杂依赖图 | 并发修改冲突 |
---
显著优点
1. 工程化成熟度极高：从任务模板、交接协议、QA 重试循环（最多 3 次）到最终集成验证，形成完整闭环
2. 并行效率优化：显式指导打破默认序列化，最大化利用 Opus 4.7 的并发能力
3. 冲突预防机制：预分发文件交集检查 + 工作树隔离，从源头消除 Git 竞争和代码覆盖
4. 弹性设计：内置抗阿谀（anti-sycophancy）策略、韧性模式（超时、熔断、舱壁隔离）
潜在缺点与局限性
1. 认知门槛陡峭：需深入理解「何时自己干 vs 何时派团队」的 5 信号评估法，误用会导致令牌浪费
2. 模型依赖性强：部分模式（如并行分发）明确标注「Opus 4.7 不默认并行」，版本差异影响行为
3. 预设团队覆盖有限：仅 7 种预设组合（Review/Debug/Feature/Fullstack/Migration/Security/Research），高度定制化场景需自行设计
4. 状态管理复杂：有状态模式下需手动处理文件所有权、依赖图、工作树生命周期，调试困难
适合人群
- 大型代码库维护者：需要并行安全审查、性能分析、架构评估
- 复杂功能开发团队：涉及多模块协调、接口契约明确的长期项目
- AI 工作流架构师：设计企业级多智能体系统，追求可控性与可观测性
常规风险
- 团队开销陷阱：3 信号以下复杂度仍派团队，管理成本超过收益
- 文件所有权遗漏：未执行预分发交集检查导致静默覆盖
- BLOCKED 滥用：未按决策树分类即重试，陷入无限循环
- 评审标准混淆：未区分「规格符合性」与「质量评估」两阶段，错误接受漂亮但偏离需求的方案