Absolute Upgrade 是一个面向依赖升级的技能,目标是把项目依赖安全地更新到当前版本,按风险排序分波次推进,并保证每个波次后测试通过。它不是简单的 npm update,而是将过时和存在漏洞的依赖按影响范围分组:补丁和次版本进入安全波次批量处理,主版本或破坏性变更则单独门控、一次一个,并先阅读变更日志。升级增量应用,并针对项目自身的测试套件进行验证。
该技能运行共享引擎 references/health-engine.md,其中定义了 DETECT → SCAN → TRIAGE → FIX → VERIFY → REPORT 循环和安全契约。本技能文件只覆盖依赖升级特有的内容。
适用场景:
- 日常的“把依赖更新到最新”或“升级我们的依赖”。
- 特定的版本提升,例如“升级 React 到 19”或“迁移离开已弃用的 X 包”。
- 清理 npm outdated 或 Dependabot 积压,而不产生 40 个独立 PR。
不适用场景:添加新依赖(属于工作/功能决策),或专门审计漏洞(应使用 /absolute audit,它负责分类 CVE;upgrade 负责移动版本)。
扫描内容: 按生态列出过时依赖的 current → wanted → latest 以及跳变类型:
- npm:npm outdated --json,锁文件 package-lock.json
- pnpm:pnpm outdated --format json,锁文件 pnpm-lock.yaml
- yarn:yarn outdated --json,锁文件 yarn.lock
- Python (pip):pip list --outdated --format=json,清单 requirements*.txt
- Python (poetry/uv):poetry show --outdated / uv pip list --outdated,清单 pyproject.toml + lock
- Go:go list -u -m -json all,清单 go.mod / go.sum
同时标记:存在已知弃用的依赖、同一包的重复/多版本,以及直接依赖与传递依赖(只有直接依赖是升级目标;传递依赖跟随)。
风险排序(TRIAGE): 按 semver 跳变将升级计划分组为波次,最安全的优先:
- 波次 1:补丁(x.y.Z),默认批量处理,立即修复。
- 波次 2:次版本(x.Y.z),默认按包族批量处理,立即修复。
- 波次 3:主版本(X.y.z)/ 1.0 之前的次版本,默认一次一个,门控——先阅读变更日志/迁移指南,列出破坏性变更。
对于每个主版本升级:定位破坏性变更(CHANGELOG、发布说明、包提供的 codemod),清点触及变更 API 的调用点,并在应用前说明迁移方案。对等依赖冲突与其驱动包在同一波次解决。
修复与验证: 应用一个波次,重新生成锁文件,运行项目完整的测试和构建(安装通过不等于升级通过)。 主版本:在同一波次中应用版本提升和所需的代码迁移,否则构建会失败。如果包提供 codemod,则使用它。 如果某个波次无法在合理范围内通过,则回滚它,将其报告为阻塞并附上错误,保留已通过的波次。绝不使用 --force / --legacy-peer-deps 来掩盖真实冲突。
注意事项:
- 仅锁文件的“升级”:只提升清单而不重新生成并提交锁文件,会发布未经测试的传递依赖版本。始终重新生成。
- 将主版本与补丁一起批量处理:一个破坏性升级会导致整个波次失败,并掩盖是哪个变更导致的。主版本始终单独处理。
- 安装通过 ≠ 项目通过:npm install 成功不能证明任何事——运行测试。
- 围绕失败进行固定:如果某个升级破坏了功能,修复或推迟它;不要静默地固定依赖树来规避。
配套命令:
- /absolute audit:如果目标是修复漏洞,从那里开始;它会将版本移动路由回这里。
- /absolute deflake:不稳定的测试可能掩盖升级是否真正通过。
- /absolute work:如果升级需要真正的功能级迁移工作,则移交。