agent-swarm-deployer

Agent Swarm Deployer

部署一组并行子 Agent，处理大量相互独立的数据任务（文档、记录、行、项目），并汇总结果。用于数据操作；代码更改请使用 agent-army。

目录

• references/overview.md -- 群组与军团的比较、使用场景、架构图
• references/swarm-design.md -- 输入/输出架构、批次大小和群组规模公式、扩展指南
• references/agent-brief.md -- Agent 简报模板、数据分发方法、进度跟踪
• references/aggregation-recovery.md -- 合并逻辑、完整性验证、重试策略、错误处理表
• references/output-formats.md -- CSV/JSON/Markdown/单文件输出、最终摘要报告
• references/task-configs.md -- 情感分析、潜在客户评分、内容生成、摘要的即用型配置

工作流

1. 理解任务。部署前先明确五项内容：数据来源、对每个项目执行的操作、输出格式、输出目的地，以及质量/验证要求。如有任何不明确之处，先询问用户——错误的规范会浪费所有 Agent 的计算资源。

2. 接收数据并盘点。使用 Glob/Bash 定位并统计项目数量。读取 3-5 个样本以了解其结构。估算每个项目和全部数据的 token 数量。报告接收摘要（来源、总数量、项目格式、样本结构、token 估算）。

3. 检测输入架构并定义输出架构。根据样本推导输入架构；定义任务所需的确切输出架构。参见 references/swarm-design.md。

4. 设计群组。根据 token 预算计算批次大小（每个 Agent 可用上下文约为 200K 的 70%），并根据项目总数计算群组规模。每波最多 20 个 Agent；超过则拆分为多波。提交群组计划和 Agent 分配方案，然后征求批准。参见 references/swarm-design.md。

5. 准备 Agent 简报。为每个 Agent 编写一份独立完整的简报，包含角色、任务、输入数据、含示例的输出架构、质量规则、错误处理流程，以及严格的 JSON 输出格式。参见 references/agent-brief.md。

6. 分发数据并部署。根据来源类型选择分发方式（使用 Bash 预先拆分 CSV/JSON；小型数据集内联嵌入；目录则传递文件路径）。通过 Agent 工具并行启动最多 20 个 Agent，设置 run_in_background: true，并在一条消息中发送所有调用。上一波完成后再运行后续波次。参见 references/agent-brief.md。

7. 跟踪进度。Agent 返回结果时，记录状态、已处理数量和累计覆盖率。参见 references/agent-brief.md。

8. 收集并汇总。解析每个 Agent 的 JSON；验证架构、完整性和重复项。合并为一个有序输出，并提取失败项。提交汇总摘要，包含覆盖率检查和失败分析。参见 references/aggregation-recovery.md。

9. 恢复失败项。将所有失败和跳过的项目加入队列，部署一个带有增强说明的重试 Agent，最多重试 2 次，并将仍未解决的项目标记为“无法恢复”。如果无法恢复的项目超过 10%，则提醒用户。参见 references/aggregation-recovery.md。

10. 写入输出并总结。生成所需格式（CSV、JSON、Markdown 或单文件），并附上最终摘要，涵盖执行情况、结果、质量指标、观察到的模式和成本。参见 references/output-formats.md。

应避免的反模式

1. 不要对顺序任务使用群组。如果项目 N 依赖项目 N-1，请改用链式处理。
2. 不要为每个项目单独部署一个 Agent。应按批次处理项目；每个 Agent 处理一个项目会浪费开销。
3. 不要跳过架构定义。没有架构，从多个 Agent 合并结果就会变得不可靠。
4. 不要忽略失败项。即使成功率达到 99%，处理 10,000 个项目时仍会有 100 个失败项。务必重试。
5. 不要跳过样本运行就部署。扩展处理规模前，先手动处理 5 个项目，验证任务和输出质量。