Swarm Migration Pattern

大规模代码迁移若按顺序执行会十分耗时：

• 框架升级（例如，从测试库A迁移至测试库B）
• Lint规则推广（覆盖数百个文件）
• API迁移（依赖发生变更时）
• 代码现代化（例如，从类组件转向Hooks）
• 全代码库重构模式应用

人工手动完成这些工作繁琐乏味；单个Agent按顺序执行则速度缓慢。

采用智能体集群架构（swarm architecture），由主Agent编排10个以上并行子Agent，同步处理迁移任务的独立分块工作。

模式流程：

1. 主Agent制定迁移计划：枚举所有需要迁移的文件/目标对象
2. 创建任务清单：将工作拆分为可并行处理的任务块
3. 启动子Agent集群：同时启动10个以上Agent，每个Agent承接N项任务
4. 映射-归约执行：每个子Agent独立完成其负责分块的迁移工作
5. 验证环节：主Agent验证结果，可按需启动额外Agent进行问题修复
6. 合并整合：合并迁移结果（生成单个PR或协调完成合并）

graph TD
    A[主Agent] --> B[扫描代码库]
    B --> C[创建任务清单<br/>100个文件需迁移]
    C --> D[启动10个子Agent]
    D --> E1[子Agent 1<br/>文件1-10]
    D --> E2[子Agent 2<br/>文件11-20]
    D --> E3[...]
    D --> E10[子Agent 10<br/>文件91-100]
    E1 --> F[主Agent验证结果]
    E2 --> F
    E3 --> F
    E10 --> F
    F --> G[合并后的PR]

实现方案：

# 主Agent编排逻辑
main_agent.prompt = """
1. 查找所有匹配指定模式的文件（例如，基于旧框架开发的*.test.js文件）
2. 创建包含文件路径的待办事项清单
3. 将文件划分为每批10个的处理批次
4. 针对每个批次，启动子Agent（subagent）并下达以下指令：
   
- 迁移这批指定文件
   - 遵循docs/migration.md中的迁移指南
   - 每次修改后运行测试
   - 测试通过则提交代码
5. 监控所有子Agent的执行状态
6. 验证所有待办事项已完成
"""

# 启动Agent集群（swarm）
for batch in batches:
    spawn_subagent(
        task=f"将{batch.files}从框架A迁移至框架B",
        context=migration_guide,
        auto_commit=True
    )

Anthropic的实际落地案例：

“Anthropic内部有越来越多的团队每月消耗大量调用额度，单月花费超1000美元，且这类用户的占比增长速度相当快。最普遍的使用场景是代码迁移……主Agent会生成一个覆盖全部任务的大型待办清单，随后通过大量子Agent实现类MapReduce的分布式处理逻辑。你可以这样指示Claude：‘启动10个Agent，每次并行处理10个批次，逐步完成所有代码迁移工作。’”——鲍里斯·切尔尼（Boris Cherny）

常见迁移类型：

• Lint规则强制执行：在全量文件中应用新的ESLint/Biome规则
• 框架迁移：Jest → Vitest、Mocha → Jest等跨测试框架迁移
• API更新：升级至新版依赖库的API规范
• 代码现代化：var → const/let、回调函数 → async/await等语法升级
• 导入路径调整：相对路径 → 绝对路径的统一改造

优点：

• 大规模并行化：相较于串行迁移，速度提升10倍以上
• 验证简便：每个子Agent处理易于管控的任务块
• 故障隔离：单个子Agent故障不会影响其他Agent运行
• 规模化场景性价比高：手动需耗时数周的迁移任务，成本仅约1000美元
• 可复现性强：所有文件可应用完全一致的迁移规则

缺点：

• Token成本高昂：同时运行10个以上Agent会产生高额Token消耗
• 协调复杂度高：主Agent需全程跟踪所有子Agent的状态与任务进度
• 合并冲突风险：并行修改操作可能引发冲突
• 依赖独立性要求：仅适用于迁移目标可拆分的场景
• 验证负担较重：需对10个以上Agent的输出结果逐一验证

前置条件：

• 原子化迁移：每个文件可独立完成迁移操作
• 明确的规范定义：迁移规则必须清晰无歧义
• 完善的测试覆盖：通过自动化机制验证迁移正确性
• 沙箱环境支持：可安全地同时运行多个Agent

优化建议：

• 批量大小调优：初始设置为每个Agent处理10个文件，根据任务复杂度灵活调整
• 分阶段部署：先迁移10%的目标，验证通过后再完成剩余部分
• 故障处理机制：让主Agent对失败批次采用优化后的指令进行重试
• 资源限制管控：限制并行Agent的数量，避免过度占用基础设施资源