核心用法
ia-orchestrating-swarms 是一套面向多智能体协作的编排框架，核心能力包括：
1. 两种智能体生成模式
- Subagent（子智能体）：短生命周期，任务完成后返回结果，适用于搜索、分析等聚焦型工作
- Teammate（队友）：持久化运行，通过收件箱通信，支持共享任务列表，适用于并行工作、流水线与持续协作
2. 并行扇出（Fan-Out）
关键约束：必须在单个 assistant 消息中发起多个 Task 调用，否则 Opus 4.7 会序列化执行。适用于独立的只读或工作树隔离型任务。
3. 任务描述模板
每个分派任务必须包含：
- 目标：一句话说明要完成什么
- 所属文件：该智能体创建或修改的文件（互斥原则）
- 接口契约：从其他智能体导入什么、向下游导出什么
- 验收标准：如何判断任务正确完成
- 范围外：明确不触碰的内容
4. 调度纪律与风险控制
- 文件交集检查：预检查确保文件所有权唯一，冲突时降级为串行或分配 worktree 隔离
- 模型选择矩阵：Haiku（1-2 文件机械任务）、默认模型（多文件集成）、Opus（架构决策与审查）
- 状态信号标准化：DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT
- BLOCKED 分类处置：缺失上下文→补充重派；推理天花板→升级模型；任务过大→拆分；需求错误→上报用户
5. 两阶段审查门
先验证规范符合性，再评估质量——避免"完美解决错误问题"。
6. 协调模型选择
| 特性 | 无状态（复制输出） | 有状态（文件所有权+依赖） |
|------|------------------|------------------------|
| 状态共享方式 | Leader 在提示间复制完整输出 | 智能体读写共享任务文件 |
| 最佳场景 | 短流水线，2-3 个智能体顺序交接 | 并行工作，4+ 智能体，复杂依赖图 |
| 故障模式 | 上下文随智能体数量线性膨胀 | 并发修改冲突 |
显著优点
1. 工程化完备：从文件所有权、worktree 隔离到 QA 重试循环，覆盖生产级多智能体系统的完整生命周期
2. 故障韧性设计：内置熔断、超时、级联预防、失败分类、部分结果合成等模式
3. 反谄媚机制：评审面板采用冷启动隔离、每轮新实例、标签随机化，降低模型迎合偏差
4. 明确的规模边界：提供量化信号（文件数、模块跨度、依赖链、风险面、并行潜力）判断何时需要团队化
潜在缺点与局限性
1. 认知门槛高：需理解 subagent/teammate 差异、worktree 隔离、接口契约等概念，学习曲线陡峭
2. Overhead 明显：小任务团队化会导致 token 浪费，文档明确建议"低于 3 个复杂信号时自己动手"
3. 工具链依赖：依赖 Git worktree、特定模型版本（Opus 4.7）的行为特性，移植性受限
4. 调试复杂度：并行智能体的竞态条件、 orphaned teammates 等需人工验证 git worktree list
适合人群
- 构建大型代码库自动化流水线（代码审查、重构、安全审计）的工程团队
- 需要并行处理多个独立分析任务（多文件安全扫描、性能基准测试）的场景
- 具备 Git 高级特性（worktree、索引管理）操作经验的开发者
常规风险
1. 竞态条件：并行实现智能体若无 worktree 隔离会导致 Git 覆盖，必须执行预分派文件交集检查
2. 上下文爆炸：无状态协调中复制完整输出会导致提示长度失控，需主动摘要
3. 僵尸会话：背景运行的 teammate 可能遗留 stale worktree，需终端状态验证
4. 模型行为漂移：Opus 4.7 的并行化需显式声明，版本升级可能破坏原有调度假设
安全等级说明
本报告由系统自动生成占位，未执行完整安全扫描。基于技能设计特征评估：
- 涉及文件系统操作（worktree、Git 索引）
- 支持后台持久化进程
- 无网络外连或敏感数据处理的显式描述
- 依赖结构化模板约束可降低任意执行风险
建议生产环境使用前，针对具体 backend（in-process/tmux/iTerm2）进行沙箱测试。