代码迁移 Agent:仓库级语言与运行时升级

代码迁移 Agent:仓库级语言与运行时升级

本节摘要:Amazon 的 MigrationBench(Java 8 到 17)与 Google 的 App Engine Py2 到 Py3 迁移器设了 2026 的标杆。Moderne 的 OpenRewrite 在规模上做确定性 AST 重写,Grit 用 codemod 风格 DSL 解决同一问题。生产模式把两者合一:确定性基底做安全重写,加一层 Agent 处理歧义情形,每分支一个沙箱构建,测试翻绿才开 PR。本节要求你迁移 50 个真实仓库,发布带失败分类的通过率。你会学到确定性基底与 Agent 的分工,以及失败分类法这套真正的交付物。

对应原课程:Phase 19 · Lesson 09 · code-migration-agent(原英文 phases/19-capstone-projects/09-code-migration-agent/docs/en.md)。

学习目标

阅读完本节,你应当能够:

1. 解释大规模代码迁移为何是编程 Agent 最干净的生产应用(真值明确、收益实在、基准公开)。
2. 把迁移拆成两层:确定性基底(OpenRewrite/libcst)与 Agent 层(处理歧义)。
3. 用 Daytona 沙箱每分支预装目标运行时,跑 Agent「构建-分类-修-重跑」循环。
4. 设硬上限:每仓库 30 分钟、8 美元、20 轮 Agent 回合。
5. 建失败分类法(dep/syntax/test/build-tool/budget_exhausted/coverage_regression),配计数与样例 diff。
6. 在 50 个仓库上对比「确定性 + Agent」全管线 vs 「仅确定性」基线的通过率。

一、问题与直觉

大规模代码迁移是 2026 年编程 Agent 最干净的生产应用之一。真值显而易见(迁移后测试套件过没过?),收益实在(一个 Java-8 舰队迁移是人头规模的项目),基准公开(MigrationBench 50 仓库子集)。Moderne 的 OpenRewrite 处理确定性那一半。Agent 层处理 OpenRewrite 配方做不到的一切:歧义重写、构建系统漂移、长尾语法、传递依赖破坏。

你要构建一个 Agent,吃进一个 Java 8 仓库(或 Python 2 仓库),产出一条 CI 翻绿的迁移分支。你要度量通过率、测试覆盖率保持、单仓库成本,并建一个失败分类法。对照「仅确定性」基线的并排对比告诉你 Agent 的价值到底在哪。

二、从零实现

管线两层。确定性基底(Java 用 OpenRewrite、Python 用 libcst)安全地跑大部分机械重写:导入、方法签名、空安全编辑、try-with-resources、废弃 API 替换。它快,产出可审计的 diff。Agent 层(OpenAI Agents SDK 或 LangGraph 上跑 Claude Opus 4.7 与 GPT-5.4-Codex)处理配方做不到的情形:构建文件升级(Maven/Gradle/pyproject)、传递依赖冲突、测试抖动、自定义注解。

每个仓库一个预装目标运行时的 Daytona 沙箱。Agent 迭代:跑构建、分类失败、应用修复、重跑。硬限:每仓库 30 分钟、8 美元、20 轮。若全部测试过且覆盖率增量非负,分支开 PR;否则归入失败类附证据。

Agent 循环的核心(分类驱动的定向修复):

def agent_loop(sandbox, budget):
    while budget.remaining():
        result = sandbox.run_build()
        if result.green:
            return passed
        failure_class = classify(result.failures)   # dep/syntax/test/build-tool
        fix = author_fix(failure_class, result)      # 定向修,不盲改
        sandbox.apply(fix)
    return file_under("budget_exhausted", sandbox.diff)
​

失败分类法是交付物。50 个仓库里,什么坏了?传递依赖?自定义注解?构建工具版本?与迁移无关的测试抖动?每类一个计数加一个样例 diff。未来的配方作者可以瞄准前三类。

三、架构与技术栈

• 确定性基底:OpenRewrite(Java)或 libcst(Python)。
• Agent:OpenAI Agents SDK 或 LangGraph 上 Claude Opus 4.7 + GPT-5.4-Codex。
• 沙箱:Daytona devcontainers,每分支一个,预装目标运行时(Java 17/Python 3.12)。
• 构建系统:Maven、Gradle、uv(Python)。
• 基准:Amazon MigrationBench 50 仓库子集(Java 8 到 17)、Google App Engine Py2 到 Py3 仓库。
• 测试套件:并行 runner,覆盖率用 Jacoco(Java)或 coverage.py(Python)。
• 可观测性:Langfuse + 每仓库一个 trace bundle,含每个 diff 块。
• 仪表盘:失败分类仪表盘,每类计数与样例 diff。

四、可复用产物

outputs/skill-migration-agent.md 是交付物。给定仓库,它跑确定性配方再跑 Agent 循环,产出翻绿的迁移分支,或把仓库归入某分类。评分量表:

一次典型迁移:

$ migrate legacy-java-service --target java17
[recipe]   27 rewrites applied (JUnit 4->5, HashMap initializer, try-with-resources)
[build]    FAIL: cannot find symbol sun.misc.BASE64Encoder
[agent]    turn 1 classify: removed_jdk_api
[agent]    turn 2 apply: sun.misc.BASE64Encoder -> java.util.Base64
[build]    OK
[tests]    412/412 passing; coverage 84.1% -> 84.3%
[pr]       opened #1841  cost=$3.20  turns=4
​

五、框架对比

OpenRewrite(Moderne)是 Java 确定性基底标杆,配方生态最完整;libcst 是 Python 的等价物(Instagram 出品);Grit 用 codemod DSL 走另一条路。Agent 层,OpenAI Agents SDK 与 LangGraph 都可,关键是给 Agent run_build/read_file/edit_file/run_test/git_diff 五个工具并强制分类驱动修复。本节的设计哲学是「确定性优先、Agent 兜底」——70~80% 的机械重写交给配方(安全、快、可审计),Agent 只碰配方做不到的,这样既控成本又控风险。

六、练习

1. 仅确定性:只用 OpenRewrite 跑迁移管线(无 Agent),对比全管线通过率,找出 Agent 单独决定胜负的案例。
2. lint 检查:加一个「lint 干净」检查——迁移后跑风格 linter(Java 用 spotless,Python 用 ruff),若出现新 lint 错则 PR 失败,度量「覆盖率保住但风格退化」的比例。
3. 最小 diff:加一个「最小 diff」优化器——Agent 分支过测后,用第二轮裁掉不必要改动,报告 diff 体积缩减。
4. 第三迁移:扩展到第三种迁移(Node 18 到 Node 22),复用沙箱包装,把配方层换成自定义 codemod。
5. 首绿构建时间:把「首次翻绿构建时间(TTFGB)」作为 UX 指标,目标 p50 < 10 分钟。

本节要点回顾

1. 干净应用:代码迁移真值明确(测试过没过)、收益实在、基准公开,是 Agent 最佳生产落点之一。
2. 两层合一:确定性基底(OpenRewrite/libcst)做 70~80% 机械重写,Agent 兜底歧义情形。
3. 沙箱每分支:Daytona 预装目标运行时,Agent 跑构建-分类-修-重跑循环。
4. 硬上限:每仓库 30 分钟、8 美元、20 轮,任一击穿即归入 budget_exhausted。
5. 覆盖率门:测试翻绿且覆盖率增量非负才开 PR,否则归入 coverage_regression。
6. 失败分类法是交付:dep/syntax/test/build-tool/budget/coverage 各一计数加样例 diff。

下一节,我们升级到「多智能体软件团队」——架构师、并行编码者、审查者、测试者协同的开 PR 流水线。