The Legacy Code Refactorer
行业：软件开发 ｜ 规模：企业级遗留系统
背景
Node.js 等运行时与生态会定期结束对旧版本的维护（如 Node 14 于 2023 年 4 月结束 LTS），企业为获得安全与性能支持不得不升级。但大型遗留项目往往依赖大量第三方包，升级主版本后常出现依赖冲突（peer dependency、ABI 变化等），有时需数十轮「改版本—安装—看报错—再改」才能打通。人工执行极易中途放弃或误判「已解决」（如忽略部分错误）。
本案例将智能体置于拉尔夫·威古姆循环（Ralph Wiggum Loop）中：没有「我完成了」类工具，循环条件仅为「npm install 成功」；每次迭代在隔离环境中执行，由智能体读错误、改配置、重试，直至真正通过，从而处理需多轮迭代的依赖链。
问题
表象问题（团队能直接感知）
想把项目从 Node 14 升级到 Node 20（或类似大版本升级），执行 npm install 后报大量依赖冲突；人工试了几轮改 package.json 或锁文件，要么仍失败，要么误以为「能装了」却漏掉部分错误；依赖链长时，需要几十轮试错，人工难以坚持。
根本原因（技术与流程层面）
依赖解析与兼容性判断是 NP 难问题；工具（npm/yarn/pnpm）只给出当前状态的错误，不自动给出「下一步改哪几个包」。常规 AI 若在几轮后仍失败，可能倾向于输出「已完成」或忽略部分错误以「完成任务」；没有强制循环条件时，不会持续迭代到真正成功。
核心痛点
- 迭代次数多：复杂依赖链可能需要数十轮「改—装—看错—再改」
- 幻觉式完成：AI 可能声称升级完成却未真正解决所有错误
- 环境一致性：每次尝试需在干净环境中重装，避免残留状态干扰
解决方案：无「完成」出口的循环 + 隔离重试 + 异常处理
阶段一：循环条件唯一（The Ralph Wiggum Loop）
智能体没有「标记完成」或「我完成了」类工具；循环的唯一定义是：当前环境的 npm install（或等价安装命令）是否成功。若失败，智能体必须根据错误日志继续修改（如 package.json、resolutions、锁文件），然后由系统自动重新执行安装；若成功，循环结束，此时才允许进入下一阶段（如跑测试、提交）。
阶段二：隔离环境与重试（Session Isolation）
每一轮修改与安装都在独立环境（如新容器或干净目录）中执行，避免上一轮的 node_modules 或缓存影响下一轮。安装命令的输出（stdout/stderr）完整回传给智能体，作为下一轮推理的输入。
阶段三：异常与恢复（Exception Handling & Recovery）
若单轮执行超时、磁盘满或网络异常，系统捕获异常并重试或回退到上一轮状态，避免循环因环境故障而非依赖问题中断。智能体只关注「依赖与版本」层面的错误信息，不承担基础设施故障的修复。
实施难点
难点 1：依赖冲突的传递性
A 依赖 B、B 依赖 C，有时只能通过升级 B 或加 resolution 解决，智能体需要正确理解错误信息中的包名与版本约束。对过于晦涩的报错，可结合文档或人工给出一次「提示」再继续。
难点 2：最大迭代与人工兜底
极端情况下可能存在无解或需人工决策的冲突（如放弃某依赖）。设定最大迭代轮次并在达到后转人工，可避免无限循环。
难点 3：与业务代码的兼容
依赖装通仅代表安装成功，不保证运行时兼容（如 Node 20 的 breaking changes）。通常在本循环之后增加「跑测试」等闸门，与本案例的「仅负责装通」形成组合。
效果（估算，非精确数字）
| 指标 | 变化 |
|---|---|
| 依赖安装成功率 | 在循环内持续尝试直至安装成功，避免人工中途放弃或误判完成 |
| 迭代轮次 | 某类复杂依赖链在案例中曾需数十轮；实际因项目与依赖图而异 |
| 人工介入 | 最大轮次或无解时转人工；日常可交给智能体跑通大部分升级场景 |
「数十轮」来源于单次案例描述，不同项目与依赖图差异很大。Node.js 版本与 LTS 政策以官方发布为准。
用到的模式及其在本案例的具体作用
| 模式 | 在本案例解决的具体问题 |
|---|---|
| The Ralph Wiggum Loop | 以「安装成功」为唯一出口，无「完成」工具，迫使智能体持续迭代直至真正通过，解决「幻觉式完成」问题 |
| Session Isolation | 每轮在干净环境中执行安装，避免残留状态干扰，保证结果可复现 |
| Exception Handling & Recovery | 处理超时、网络等环境异常，避免循环因非依赖问题中断 |
参考依据
| 来源 | 具体内容 | 年份 |
|---|---|---|
| Node.js Release Schedule | LTS 周期与版本支持策略（如 Node 14 EOL） | nodejs.org |
| npm / pnpm 文档 | 依赖解析、resolutions、peer dependencies 等 | — |