name: 迁移 description: 迁移工作流 - 研究 → 分析 → 计划 → 实施 → 审查

/migrate - 迁移工作流

安全地进行框架、语言和基础设施的迁移。

何时使用

“迁移到 X”
“升级框架”
“从 X 移动到 Y”
“升级 Python/Node/等”
“迁移数据库”
框架版本升级
语言迁移
基础设施变更

工作流概述

┌──────────┐    ┌──────────┐    ┌────────────┐    ┌──────────┐    ┌───────────┐
│  研究    │───▶│  分析    │───▶│   计划     │───▶│  实施    │───▶│   审查    │
│  oracle  │    │ phoenix  │    │ plan-agent │    │  kraken  │    │ surveyor  │
└──────────┘    └──────────┘    └────────────┘    └──────────┘    └───────────┘
  Research       Analyze          Plan             Implement       Review
  研究目标       分析当前状态     制定迁移计划     实施更改        审查迁移结果

代理序列

#	代理	角色	输出
1	oracle	研究目标框架/版本	研究报告
2	phoenix	分析当前代码库以评估迁移影响	影响分析
3	plan-agent	创建分阶段迁移计划	迁移计划
4	kraken	实施迁移更改	代码更改
5	surveyor	审查迁移的完整性	迁移审查报告

为什么需要额外阶段？

迁移是高风险操作：

版本间的破坏性变更
依赖冲突
数据格式变化
API 弃用

额外的研究和审查阶段可以及早发现问题。

执行步骤

阶段 1: 研究目标

Task(
  subagent_type="oracle",
  prompt="""
  研究迁移目标: [TARGET]

  调查内容:
  - 从当前版本的破坏性变更
  - 新 API 和模式
  - 我们使用的已弃用功能
  - 官方文档中的迁移指南
  - 常见陷阱和解决方案

  输出: 迁移研究报告
  """
)

阶段 2: 分析当前状态

Task(
  subagent_type="phoenix",
  prompt="""
  分析代码库以进行迁移: [FROM] → [TO]

  识别:
  - 使用已弃用 API 的文件
  - 依赖冲突
  - 需要更新的模式
  - 受影响区域的测试覆盖率
  - 风险区域（关键路径）

  输出: 带受影响文件的影响分析
  """
)

阶段 3: 计划迁移

Task(
  subagent_type="plan-agent",
  prompt="""
  创建迁移计划: [FROM] → [TO]

  研究: [来自 oracle]
  影响: [来自 phoenix]

  计划应:
  - 分阶段（如果可能）
  - 每个阶段独立可测试
  - 包括回滚策略
  - 优先确保关键路径的稳定性

  输出: 分阶段迁移计划
  """
)

阶段 4: 实施

Task(
  subagent_type="kraken",
  prompt="""
  实施迁移阶段: [PHASE_N]

  计划: [来自 plan-agent]

  要求:
  - 严格按照计划执行
  - 每次更改后运行测试
  - 记录任何偏差
  - 如果测试失败则停止

  输出: 完成的阶段及测试结果
  """
)

阶段 5: 审查迁移

Task(
  subagent_type="surveyor",
  prompt="""
  审查迁移: [FROM] → [TO]

  检查:
  - 所有已弃用 API 是否已替换
  - 无剩余的兼容性垫片
  - 测试通过
  - 性能可接受
  - 无安全回归

  输出: 迁移审查报告
  """
)

迁移类型

框架升级

用户: /migrate React 17 → 18
→ 完整工作流，处理钩子和并发模式变更

语言版本

用户: /migrate Python 3.9 → 3.12
→ 关注新语法和移除的功能

数据库迁移

用户: /migrate MongoDB → PostgreSQL
→ 模式设计、数据转换、查询重写

基础设施

用户: /migrate AWS → GCP
→ 服务映射、配置翻译

示例

用户: /migrate 从 Express 迁移到 Fastify

Claude: 开始 /migrate 工作流: Express → Fastify

阶段 1: 研究 Fastify...
[启动 oracle]
关键差异:
- 基于模式的验证（相对于中间件）
- 插件架构
- 原生异步/等待
- 不同的中间件模式

阶段 2: 分析当前 Express 使用情况...
[启动 phoenix]
影响分析:
- 23 个路由文件需要更新
- 8 个中间件需要转换
- 3 个插件需要 Fastify 等效物
- 测试覆盖率: 78%

阶段 3: 创建迁移计划...
[启动 plan-agent]

迁移计划: Express → Fastify
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

阶段 1: 设置与核心
- 在 Express 旁边添加 Fastify
- 迁移核心服务器设置
- 并行运行两者

阶段 2: 路由（按领域）
- 迁移认证路由
- 迁移用户路由
- 迁移产品路由
- ...

阶段 3: 中间件
- 转换错误处理程序
- 转换认证中间件
- 转换日志记录

阶段 4: 清理
- 移除 Express
- 移除兼容层
- 最终测试

回滚: 在阶段 4 完成前保留 Express

阶段 4: 实施阶段 1...
[启动 kraken]
✅ Fastify 服务器与 Express 并行运行
✅ 核心路由已迁移
✅ 测试通过

[继续其他阶段...]

阶段 5: 审查迁移...
[启动 surveyor]
✅ 所有 Express 代码已移除
✅ 23/23 路由已迁移
✅ 性能提升（快 2.1 倍）
✅ 无安全回归

迁移完成! Express → Fastify

增量迁移

对于大型代码库，一次运行一个阶段:

用户: /migrate React 17 → 18 --phase 1
[仅运行阶段 1]

用户: /migrate React 17 → 18 --phase 2
[运行阶段 2，读取先前交接]

标志

--phase N: 仅运行特定阶段
--dry-run: 计划而不实施
--rollback: 执行回滚计划
--parallel: 新旧并行运行（绞杀者模式）