dependency-upgrader

依赖升级

明确约定

1. 阅读仓库说明，并识别清单文件、包装器、版本目录、锁定文件、所选包管理器和现有安全工具。
2. 确认用户请求的包、允许的版本范围、升级动机，以及是否包含主版本迁移。将“更新依赖”视为升级到最小兼容稳定版本，而非允许升级所有主版本。
3. 编辑前记录当前声明和解析出的版本、依赖路径，以及最小且可靠的基线检查。
4. 如果工作树中存在相互重叠的更改，或所需工具不可用，请停止并报告；不要切换包管理器，也不要重新生成其他包管理器的锁定文件。

选择版本

1. 使用当前的注册表元数据，以及官方发行说明、迁移指南、兼容性表和安全公告。
2. 优先选择能解决所述问题的最小稳定版本。除非用户提出要求，否则不要选择预发布版或候选发布版。
3. 将紧密耦合的包分组；否则一次更新一个依赖或低风险依赖组。
4. 对于主版本，在编辑前确定运行时要求、已移除的 API、配置更改和回滚限制。

审计已知漏洞

每次升级依赖或审计漏洞时，都要阅读 references/vulnerability-audit-playbook.md。

1. 选择版本前，审计每个目标依赖及其解析后的传递依赖闭包。条件允许时，还要运行一次仓库级扫描，以区分基线问题与升级引入或保留的漏洞。
2. 优先使用仓库原生检查和 GitHub 连接器的 Dependabot 或依赖审查数据，然后使用生态系统审计命令和 OSV 进行交叉核对。不要认为任何单一数据库都涵盖所有问题。
3. 将每条发现与确切的解析包、版本、范围和依赖路径对应起来。记录 GHSA 或 OSV 标识符，以及存在时的 CVE 别名；没有 CVE 标识符并不意味着没有漏洞。
4. 在权威公告或供应商通知中确认受影响和已修补的版本范围。区分已知暴露、实际可达性、误报、已撤回的公告和覆盖缺口。
5. 提议最接近且兼容的已修补版本。对于存在漏洞的传递依赖，优先升级最近的直接父依赖、平台或 BOM；仅在父依赖没有修复版本或不兼容时，才使用临时约束或覆盖。

检查供应链风险

遵守仓库现有策略。如果没有策略，建议为常规升级设置至少 72 小时的发布时长门槛，并记录紧急安全修复的任何例外。对于 Node，使用 references/node-upgrade-playbook.md 中所选包管理器的设置。对于 Gradle 或 Maven，遵循仓库策略或手动核实发布时间；不要编造与包管理器无关的设置。

接受锁定文件差异前：

• 检查所有新增的直接和传递依赖、版本、注册表、URL、完整性值和生命周期脚本；
• 调查意外的包替换、新维护者、来源证明变更、git/tarball 来源或大幅扩大的传递依赖范围；
• 如果所选包管理器和注册表支持，则使用注册表签名或来源证明验证，但不要将来源证明视为代码安全的证明；
• 如果仓库已启用冻结锁定文件、漏洞和依赖审查检查，请继续保持启用；
• 切勿仅为完成升级而绕过完整性、签名、策略或漏洞检查失败。

紧急公告可能足以成为提议狭窄年龄门槛例外的理由。仅在获得用户或仓库所有者的明确批准、验证所选修复方案和安全公告，并且针对性验证通过后，才可应用该例外。

应用并验证

1. 使用仓库的包管理器或构建包装器，并保留其锁文件格式。
2. 仅对清单文件和锁文件做出体现升级所需的最小更改。
3. 运行包脚本前检查差异。发现问题时，尽可能使用仅操作锁文件或忽略脚本的模式；只有在必要且可信时才启用脚本。
4. 每完成一组风险项后运行有针对性的测试，然后运行仓库中相应的 CI 等效检查。
5. 针对最终解析出的依赖关系图重新运行相同的漏洞扫描。确认目标安全公告已不存在、未引入新漏洞，并且选中了预期的安全版本和依赖路径。
6. 将失败与基线进行比较，并还原无关的变更，而不是将其规范化。

仅针对检测到的生态系统使用 references/node-upgrade-playbook.md 或 references/gradle-upgrade-playbook.md。

报告

列出旧版和新版的声明版本与解析版本、依赖路径、安全公告 ID 和来源、受影响版本范围和修复版本范围、扫描时间戳和覆盖范围缺口、原因和紧迫性、迁移工作、供应链检查、命令及其结果、基线发现，以及未解决的风险。应表述为“这些来源未发现已知漏洞”，而不要声称依赖是安全的。