codebase-migrate

Codebase Migrate 是一个面向大规模代码库迁移与多文件重构的技能。它协调框架升级、API 重命名、配置重写和结构性重构，可跨数百个文件执行。本地代码修改由智能体驱动，Composio CLI 负责周边流程：跟踪问题、按批次创建 PR 并进行 CI 验证。

适用场景

框架升级（React 17 → 19、Node 18 → 22、Django 4 → 5）。
单体仓库中的 API 重命名（例如 getUserById → users.byId）。
配置/格式迁移（webpack → vite、eslint → biome、jest → vitest）。
任何需要以可审查切片方式交付的“200 个文件同样修改”任务。

前置条件

curl -fsSL https://composio.dev/install | bash
composio login
composio link github（用于 PR 与 CI 状态）
composio link linear（或 jira，用于迁移跟踪）

智能体将直接使用的本地工具：git、rg、jscodeshift/ts-morph/comby/ast-grep（按语言选择）以及你的测试运行器。

规划阶段

精确定义转换。反例：“迁移到 vitest”。正例：“将 jest.mock 替换为 vi.mock，将 jest.fn() 换成 vi.fn()，使用模板 X 将 jest.config.js 重命名为 vitest.config.ts”。
评估影响范围： rg -l 'jest.(mock|fn|spyOn)' | wc -l rg -l 'from "jest"' | sort
提交跟踪问题： composio execute LINEAR_CREATE_ISSUE -d '{ "teamId":"TEAM_ID", "title":"Migrate test runner: jest → vitest", "description":"Batches of ~25 files. Checkpoint after each PR lands green." }'

按可审查批次执行循环：选取 N 个文件 → 转换 → 测试 → PR → 等待通过 → 合并 → 下一批。

批次辅助：匹配模式的前 25 个未处理文件

BATCH=$(rg -l 'jest.mock' | grep -v done.list | head -25) echo "$BATCH" > batch.list

智能体对 batch.list 运行 codemod，然后： git checkout -b migrate/vitest-batch-03 xargs < batch.list codemod-runner # 例如 jscodeshift / ts-morph / comby npm test -- --changed git add -A && git commit -m "migrate(test): jest → vitest (batch 3)" git push -u origin migrate/vitest-batch-03

composio execute GITHUB_CREATE_A_PULL_REQUEST -d '{ "owner":"acme","repo":"app", "head":"migrate/vitest-batch-03","base":"main", "title":"migrate(test): jest → vitest (batch 3)", "body":"Part of LIN-482. 25 files. Codemod: transforms/jest-to-vitest.ts." }'

随后轮询 CI 并在通过后合并： composio execute GITHUB_LIST_WORKFLOW_RUNS_FOR_A_REPOSITORY
-d '{"owner":"acme","repo":"app","branch":"migrate/vitest-batch-03"}'

工作流脚本 scripts/migrate-batch.ts，每批通过 composio run --file scripts/migrate-batch.ts -- --batch 3 运行： const batch = process.argv[process.argv.indexOf("--batch") + 1];

const pr = await execute("GITHUB_CREATE_A_PULL_REQUEST", { owner: "acme", repo: "app", head: migrate/vitest-batch-${batch}, base: "main", title: migrate(test): jest → vitest (batch ${batch}), body: Part of LIN-482. See transforms/jest-to-vitest.ts. });

await execute("LINEAR_CREATE_COMMENT", { issueId: "LIN-482", body: Opened PR #${pr.number}: ${pr.html_url} });

安全准则

每个 PR 只做一种转换。切勿把重命名与格式变更混在一起。
维护已迁移文件的 done.list，让下一批跳过它们。
最后一批运行完整测试套件，即使每批 PR 只运行了 --changed。
先 codemod，后手工编辑。如果 codemod 漏掉 3 个文件，手动修补并在 PR 正文中注明。
按批次回滚，而非全局回滚。每个 PR 都应能干净地还原。

验证循环每次合并后： rg 'jest.(mock|fn|spyOn)' | wc -l # 应趋近于 0 npm test # 完整套件 composio execute GITHUB_LIST_WORKFLOW_RUNS_FOR_A_REPOSITORY
-d '{"owner":"acme","repo":"app","branch":"main","event":"push"}'
| jq '.workflow_runs[0].conclusion'

故障排查

Codemod 正则匹配过多 → 改用基于 AST 的工具（ast-grep、ts-morph）进行结构化匹配。
本地测试通过但 CI 失败 → 确保 Node/Python 版本一致；检查 .nvmrc / pyproject.toml。
PR 太大难以审查 → 将批次大小减半；维护者不会审查 800 行的 diff。
批次间冲突 → 合并当前批次前先 rebase 未合并的批次；切勿对已合并批次强制推送。

完整 CLI 参考：docs.composio.dev/docs/cli

技能介绍

批次辅助：匹配模式的前 25 个未处理文件