SuperAPI AI 工具集

absolute-upgrade

部署与运维

查看项目

更新于 10-26 16:19

技能介绍

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:如果升级需要真正的功能级迁移工作,则移交。