migrate

用途

Migrate 用于编排 monorepo 中的批量迁移工作，包括导入路径变更、包重命名和模块移动。它强调使用脚本化批量操作，而不是逐文件编辑，并在每一步进行类型校验，最后以原子方式提交。

主要能力

• 去重检查：通过 git log 和 grep 确认迁移是否已完成或部分完成。
• 构建迁移清单：用 grep 列出所有受影响的文件，并按工作区汇总。
• 脚本化批量替换：使用 grep | xargs sed 进行批量替换，而非逐文件编辑。
• 验证门：在 apps/api、apps/frontend、packages/server 等目录运行 tsc --noEmit 或 svelte-check 检查类型。
• 残留检查：查找仍指向旧路径的文件。
• 运行测试：使用 vitest 运行相关测试。
• 原子提交：只暂存已迁移的文件，提交信息包含迁移描述和影响范围。

使用方式

技能提供两个脚本：

bash scripts/build-manifest.sh @old/pkg/name
bash scripts/replace-imports.sh @old/pkg/name @new/pkg/name /tmp/migration-manifest.txt

执行流程分为七步：

1. 去重检查：

git log --oneline -20
grep -r "<new-import-path>" apps/ packages/ --include="*.ts" --include="*.svelte" -l | head -10

1. 构建迁移清单：

grep -rl "<old-import-path>" apps/ packages/ --include="*.ts" --include="*.tsx" --include="*.svelte" > /tmp/migration-manifest.txt
echo "Files to migrate: $(wc -l < /tmp/migration-manifest.txt)"
cat /tmp/migration-manifest.txt

1. 脚本化批量替换：

grep -rl "@old/pkg" apps/api/ --include="*.ts" | \
  xargs sed -i '' "s|@old/pkg|@new/pkg|g"

grep -rl "@old/pkg" apps/frontend/ --include="*.ts" --include="*.svelte" | \
  xargs sed -i '' "s|@old/pkg|@new/pkg|g"

注意：macOS 使用 sed -i ''，Linux 使用 sed -i。

1. 验证门：

cd apps/api && npx tsc --noEmit 2>&1 | head -30
cd apps/frontend && npx svelte-check --threshold error 2>&1 | tail -20
cd packages/server && npx tsc --noEmit 2>&1 | head -20

1. 残留检查：

grep -r "<old-import-path>" apps/ packages/ --include="*.ts" --include="*.svelte" -l

1. 运行测试：

npx vitest run apps/api --reporter=dot
npx vitest run apps/frontend --reporter=dot

1. 原子提交：

git commit -m "refactor(imports): migrate @old/pkg → @new/pkg

Affects N files across apps/api, apps/frontend, packages/server.
All typechecks pass. Full test suite green.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"

只暂存已迁移的文件，不要使用 git add -A。

适用场景

• 影响 3 到 20 个文件的迁移：使用清单加脚本化 sed。
• 影响超过 20 个文件或涉及 packages/ 目录：先展示清单并获得用户确认再执行 sed。
• 常见迁移模式包括：包重命名（@company/old-pkg → @company/new-pkg）、路径重构（@app/shared/utils → @app/core/utils）、索引合并（./auth/helpers → ./auth/index）、框架别名（$lib/server/* → src/lib/server/*）。

限制

• 不要用于只涉及一两个文件的变更，应直接使用 Edit 工具。
• 不要用于探索性重构或包边界决策尚未确定的情况。
• 禁止逐文件使用 Edit 工具进行批量迁移。
• 禁止在没有去重检查的情况下开始迁移。
• 禁止在没有类型检查的情况下提交。
• 禁止跳过残留检查。
• 禁止在没有迁移清单的情况下进行迁移。
• 如果影响超过 20 个文件或涉及 packages/，必须先与用户确认清单数量。
• 动态构造的导入字符串、测试夹具数据、注释或文档中的残留需要人工检查。
• 测试失败时需检查 mock 路径是否仍指向旧模块路径。