核心用法
ia-orchestrating-swarms 是一套声明式多智能体协调框架，核心解决「何时派队、如何并行、怎样避免踩坑」三类问题。
两大原语
- Task（子代理）：短生命周期，任务完成即销毁，通过返回值同步结果。适合搜索、分析、一次性计算。
- Teammate（队友）：长生命周期，通过 Inbox 异步通信，共享任务列表，需显式
requestShutdown。适合并行审查、流水线协作、持续反馈。
并行扇出（Fan-Out）
关键约束：必须在单条助手消息中同时发起多个 Task 调用。Opus 4.7 不会自动并行化，跨消息顺序派发会被串行化。若 harness 对活跃子代理数设限，需将溢出任务队列化，待槽位释放后重新派发，而非直接失败。
文件互斥与隔离
派队前必须执行「文件交集检查」：收集各单元声明的 Owned Files，若任一文件出现在多单元中，则判定为不安全。解决方案：降级为串行、启用 isolation: "worktree"（每代理独立工作副本），或重写边界使文件归属唯一。实施代理默认共享 git 状态，若无工作树隔离，禁止并行派发。
任务描述模板
每个派发任务必须包含：Objective（目标）、Owned Files（独占文件）、Interface Contracts（输入输出约定）、Acceptance Criteria（验收标准）、Out of Scope（明确排除项）。
阻塞分类与响应（BLOCKED triage）
| 根因 | 信号 | 响应 |
|------|------|------|
| 缺上下文 | 索要文件/规格/决策 | 补上下文，重派同代理 |
| 推理瓶颈 | 卡在无法自行解决的细节 | 升级模型（haiku→sonnet→opus） |
| 任务过大 | 部分进展后触顶 token/复杂度 | 拆分任务，显式接口契约 |
| 规格错误 | 发现计划矛盾或遗漏需求 | 升级至用户，禁止自行重派 |
两阶段审查门：先验证规格符合性，再评估质量。规格不符直接拒收，避免「解决错误问题的漂亮方案」。
协调模型选择
- 无状态（Stateless）：Leader 在提示词间复制输出，适合 2-3 代理短流水线。
- 有状态（Stateful）：代理通过共享任务文件读写状态，适合 4+ 代理复杂依赖图，需配合 worktree 或独占文件所有权防冲突。
显著优点
1. 系统化防踩坑：文件交集检查、预派队安全门、git 索引竞速约束，将「并行覆盖写入」等经典坑点显式化。
2. 弹性与韧性：内置超时、熔断、舱壁隔离、故障分类（重试/重分配/升级）、部分失败合成，生产级可靠性设计。
3. 模型分级调度：按任务复杂度匹配 haiku/默认/opus，成本与性能 trade-off 可量化。
4. 丰富的预设团队：Review/Debug/Feature/Fullstack/Migration/Security/Research 七类模板，开箱即用，避免过度设计。
5. 反谄媚机制：审查面板支持冷启动隔离、每轮新实例、标签随机化、收敛检测，降低群体思维风险。
潜在局限
1. 学习曲线陡峭：需理解 Task vs Teammate、无状态 vs 有状态、worktree 隔离等概念，新手易混淆生命周期与通信模式。
2. harness 依赖：并行能力受底层实现（Opus 4.7）限制，需人工处理容量回压（backpressure）与队列逻辑。
3. 调试复杂度高：多代理竞态、死锁、部分失败场景下的追踪需要 git worktree list、任务状态机、交叉文件审查等额外运维。
4. 无状态上下文线性膨胀：长流水线若不使用 /compact 或子代理转储，Leader 提示词会迅速超载。
适合人群
- 架构师/技术 Lead：需并行审查、分治重构、大规模代码迁移的团队。
- DevOps/平台工程师：构建内部 CI/CD 智能代理流水线，需故障隔离与弹性。
- 安全审计团队：多维度并行安全扫描（Security Sentinel + Performance Oracle + Architecture Strategist）。
- 研究型开发者：探索 multi-agent 协作上限，需结构化协调而非简单链式调用。
常规风险
1. 文件竞态：未启用 worktree 且未执行交集检查即并行派发实施代理，导致代码覆盖。
2. 序列化误用：将可并行任务拆分到多消息顺序执行，浪费 wall-clock 时间。
3. 阻塞误判：未区分「缺上下文」与「推理瓶颈」，盲目重试同一模型，Token 空耗。
4. 规格漂移：子代理自行读取计划文件而非接收完整任务文本，导致版本不一致、理解偏差。
5. 孤儿进程：异常退出未清理 Teammate，残留 worktree 或后台任务占用资源。