核心用法
ia-orchestrating-swarms 是一个面向复杂工作流的多智能体编排框架，核心解决单一 Agent 无法高效处理的大规模任务分解与并行执行问题。它提供两种 Agent 生成模式：
- Subagent（短周期）：任务完成后立即返回结果，适用于搜索、分析等聚焦型工作
- Teammate（长周期）：通过收件箱持续通信，共享任务列表，支持并行协作与流水线作业
关键操作原语包括 Agents、Teams、Tasks、Inboxes、Messages 及 13 种 Teammate 操作（spawnTeam、write、broadcast、requestShutdown 等）。框架强制要求任务描述包含五大字段：Objective、Owned Files、Interface Contracts、Acceptance Criteria、Out of Scope，并严格执行「单文件单一所有者」规则防止冲突。
显著优点
1. 真正的并行执行：通过单条消息批量派发独立 Task，避免 Opus 4.7 默认串行化问题
2. 完善的隔离机制：支持 isolation: "worktree" 为每个实现 Agent 分配独立工作副本，消除并行写入冲突
3. 智能降级策略：提供基于 5 维度信号（文件数、模块跨度、依赖链、风险面、并行潜力）的团队派发决策树
4. 模型自适应选择：根据任务复杂度自动匹配 Haiku（1-2 文件机械任务）/ 默认模型 / Opus（架构决策与审查）
5. 故障恢复体系：内置 BLOCKED 状态分类决策树、最多 3 次 QA 重试、级联预防（超时/熔断/舱壁隔离）及中途补偿机制
潜在缺点与局限性
- 认知开销高：需要深入理解 7 种预设团队组合、状态化/无状态协调模型选择、13 种消息格式等复杂概念体系
- 调试困难：并行 Agent 的竞态条件、git 索引冲突、测试缓存抖动等问题需要预先在 dispatch prompt 中显式约束
- 团队膨胀风险：文档明确警告「协调角色多于工作角色」是典型的反模式，但实践中仍易过度设计
- 预设组合限制：7 种标准团队（Review/Debug/Feature/Fullstack/Migration/Security/Research）可能无法覆盖特殊领域需求
适合人群
- 需要处理跨模块、多文件集成的大型软件工程团队
- 构建自动化代码审查、安全审计、性能分析等并行分析流水线的开发者
- 追求极致效率、愿意承担多 Agent 系统复杂度的技术负责人
常规风险
| 风险类型 | 具体表现 | 缓解措施 |
|---------|---------|---------|
| 文件冲突 | 并行实现 Agent 覆盖彼此修改 | 强制 worktree 隔离或串行派发 |
| 上下文爆炸 | 状态化手传导致 prompt 线性增长 | 采用无状态模型或 `/compact` 策略 |
| 死锁/孤儿进程 | 队友未正常关闭，worktree 残留 | 终端状态验证 + `git worktree list` 检查 |
| 规范漂移 | 子 Agent 未按预期格式返回状态 | 标准化 DONE/DONE_WITH_CONCERNS/BLOCKED/NEEDS_CONTEXT 信号 |
该框架本质上是「用系统化复杂度换取执行并行度」，适合已形成成熟 Agent 协作规范的团队，不建议作为入门级方案。