upgrade-dependencies 是一个面向 JavaScript/TypeScript 工作区的依赖升级技能,来源为 draekien/create-d9-app。其用途是安全地把过时的补丁与次版本依赖固定版本升级到精确版本,并在升级后运行构建与质量检查,避免引入主版本破坏性变更。
主要能力:
- 识别包管理器:读取根 package.json 的 packageManager 字段,据此确定使用 pnpm、npm、yarn 或 bun。
- 读取清单:根 package.json 以及 apps//package.json、packages//package.json,处理 dependencies、devDependencies、optionalDependencies 中的固定版本,跳过 workspace:*、link:、file:、git、npm: 别名与 URL 规格。
- 筛选候选版本:通过 npm view <pkg> versions time --json 获取版本与发布时间,排除带 - 的预发布版本,要求发布时间满足最小年龄(minimumReleaseAge,取自 pnpm-workspace.yaml 或 .npmrc,未设置时为 1440 分钟)。
- 版本分类:与当前固定版本同主版本且更新的候选取最高者,次版本不同记为 minor,否则记为 patch;存在更高主版本时记录 held: major,但不应用。若全部为最新,则不修改文件并报告。
- 读取发布说明:对每个待升级包,读取从旧版本之后到新版本(含)的每个版本发布说明,优先用 gh release view,缺失时读取仓库 CHANGELOG.md,记录破坏性变更、弃用与迁移步骤。
- 确认机制:先打印包、旧版本、新版本、类型、破坏性变更与迁移列表;未传 --accept 时停下等待开发者接受或排除,不修改文件;传入 --accept 则继续。
- 应用升级:把固定版本设置为精确新版本(不使用 ^、~、latest),执行 <pm> install,再按 build、check、typecheck、test 顺序运行脚本,根 package.json 未定义的脚本跳过。
- 失败处理:若某检查失败,发布说明中已记录该变更与迁移则应用迁移并重新安装与运行全部脚本;否则把导致失败的包回退到旧版本并重跑,报告为 held: check failed 并附错误文本。持续直到四项检查全部退出 0,不以失败检查结束。
- 报告:输出变更包表格(Package、Old、New、Type),并列出 held: major(包、当前版本、最新符合条件的最高主版本)、held: check failed(包、旧版本、尝试版本、错误文本)以及已应用的迁移与变更文件。
使用方式:作为技能调用时传入参数,$ARGUMENTS 中可用 --accept 表示提前接受破坏性变更列表并在第 4 步继续而不停止。流程依次为读取工作区、查找升级、读取发布说明、展示并停止、应用、处理失败检查、报告。
适用场景:需要定期小幅升级依赖、保持精确版本锁定、并在升级后自动验证构建、检查、类型检查与测试的 pnpm/npm/yarn/bun 工作区项目。
限制:仅应用补丁与次版本升级,从不应用主版本;不处理 workspace:*、link:、file:、git、npm: 别名与 URL 规格;依赖 npm view、GitHub 发布说明或 CHANGELOG 的可用性;检查失败且发布说明未覆盖时只能回退;最小发布年龄与包管理器由项目配置决定。具体脚本是否定义取决于根 package.json。