update-dependencies

更新依赖项

将依赖维护视为一次全面检查：盘点自有版本声明，让仓库的包管理器解析包关系图，然后验证并记录结果。

默认检查仓库中的每个包管理器根目录和工作区。请求可以将范围缩小到指定包，也可以扩展到最新主版本。

根据请求确定授权模式：

• 审计：盘点并评估更新，不更改文件。
• 改进：默认模式；应用符合策略的更新，进行验证，并保留未提交的结果。
• 发布：先改进，再执行所请求的发布。创建拉取请求的请求包括创建它所需的分支、提交和推送。

项目策略以仓库说明文件、清单和维护配置为准。本技能提供围绕这些内容的流程。如果适用的权威来源存在分歧，且当前仓库证据无法消除冲突，则暂缓有争议的更新，继续处理没有歧义的工作。

1. 明确维护约定

确定 Git 根目录、当前分支、工作树状态，以及仓库中的每个包管理器根目录。先阅读适用的 AGENTS.md 和同类说明文件（从最广范围到最窄范围），然后根据其中指引查阅依赖项、安全、发布、CI、生成代码和验证方面的指南。

对每个包管理器根目录，根据其声明和锁文件确定包管理器及其版本。记录工作区边界、必需脚本、更新自动化、版本范围和对等依赖策略、补丁或生成的产物、工具链声明、默认分支和发布规则。使用仓库指定的包管理器及版本进行解析和验证。

明确保留现有用户更改，不将其纳入本次处理范围。在审计模式下，本次运行中的所有命令都必须只读。

完成条件： 每个 JavaScript 或 TypeScript 包管理器根目录都有适用的策略和命令来源；每个已有的脏文件都经过有意纳入或排除；任何不受支持或存在冲突的根目录都已识别，且不会阻碍彼此独立的根目录。

2. 清点所有检测到的依赖面

完整阅读 references/dependency-surfaces.md，然后将其中的每个部分应用于各个包管理器根目录。将不存在的依赖面记录为不存在，不要悄然跳过。

在选择过时检查、审计、依赖图和 peer 诊断命令之前，先查看已安装包管理器的帮助信息。确认 peer 问题会导致失败、发出警告，还是需要单独检查。对于 pnpm 根目录，先阅读 references/pnpm-resolution.md，再选择命令或解读 peer 诊断。检查所有自有工作区清单，不要只依赖根目录摘要。将动态版本解析到提供该版本的声明，并且只计入一次。

使用包管理器支持的检查方式，采集基线 peer 诊断。如果获取诊断需要执行会写入文件的解析操作，请在 Improve 或 Publish 模式下，使用当前清单、锁文件和配置的隔离副本。在 Audit 模式下，将无法获取的诊断记录为验证缺口。同时，记录受影响验证关卡的基线失败。

维护一份工作台账：

依赖面	当前版本	符合条件的目标版本	风险	策略或证据	决策
包、操作、镜像或工具链	精确引用	精确引用或当前版本	补丁、小版本、主版本、非 semver、安全或关联	仓库或一手来源	当前、纳入、暂缓或拆分

除非用户要求提供产物，否则将台账保留为工作笔记。跨工作区使用者复用包和发布证据；如目标版本或策略不同，则分别记录。

完成条件： 每个检测到的依赖面都有一条台账记录或已注明其归属来源，并且已采集基线 peer 诊断和受影响检查，或明确记录了无法获取的具体原因。

3. 确定更新范围

在适用语义化版本（semver）的情况下，按 semver 距离对候选项分类；同时评估其对运行时、工具、CI、工具链或安全性的影响。将主版本更新、不可比较的引用、对运行时敏感的库、安全修复、包管理器或运行时升级，以及附带迁移说明的变更视为敏感项。

使用包管理器支持工作区的命令构建候选项。让其解析器根据现有配置选择符合条件的版本，并评估声明的 peer 范围。若命令会强制执行已配置的资格检查，则以这些检查为准，包括 pnpm 的 minimumReleaseAge。仅当包管理器无法强制执行相应策略，或仓库说明明确要求时，才添加手动检查。

对每个拟更新的直接依赖、目录条目、覆盖项和明确指定的传递依赖更新，研究其当前版本到目标版本之间的官方变更日志和发行说明。对多个使用者和关联的软件包系列复用这项研究。通过所属更新涵盖附带的传递依赖变更；若诊断信息、安全公告或发行说明指出风险，则单独调查。使用仓库规定的文档查询机制。记录缺失的说明以及所用的主要来源替代方案。

对于敏感更新，还要确定所需迁移以及运行时或工具链限制。根据 peer 诊断开展兼容性研究；仅凭主版本差异并不能证明存在 peer 冲突。第 5 步验证应用行为之前，包管理器的解析结果仍属暂定。

为每个候选项指定一个结果：

• 纳入：符合仓库策略，已准备好进行解析和验证。
• 暂缓：因已证实的兼容性问题、策略限制或具体的证据缺口而保持不变。
• 拆分：需要单独制定迁移范围，本轮更新中保持不变。
• 当前：已是最新版本、由本地推导得出，或不会产生更新。

将关联声明作为一个整体决策：本地工具和 CI 中的运行时版本、清单和引导文件中的包管理器固定版本，以及动态派生镜像的来源与使用者。

如果纳入的更新涉及 Ultracite、lint 或格式化后端、React Doctor、已加载的 JavaScript lint 插件或共享 lint 配置包，则在更改 lint 配置之前运行 /linting-alignment 技能。如果该技能不可用，保留现有配置，并暂缓任何安全性取决于配置迁移的更新。

**完成条件：**每个候选项都有策略和发行研究结果；敏感的纳入项都有迁移与验证计划；每个暂缓或拆分项都有明确理由；并且所有已检测到的 lint 技术栈变更都已完成对齐交接，或已安全暂缓。

4. 应用已纳入的更新

在 Audit 模式下，保持工作树不变，并继续进行验证和报告。

在 Improve 或 Publish 模式下，使用仓库的包管理器更新协调一致的分组，并检查各组之间的差异。对于耦合的包，应同时更新其工作区和目录归属方，以免中间版本混用成为阻碍。

• 只有当包管理器根目录下所有可能被选中的候选项都标记为 Include 时，才允许使用广泛更新命令。
• 如果任何候选项标记为 Hold 或 Split，请使用依赖项选择器、排除项和工作区筛选器批量更新已纳入项，同时保留暂缓声明。如果支持的选择器无法分离该组，请缩小范围，或暂缓更新无法拆分的组。
• 保留版本范围策略、工作区和目录协议、别名、覆盖项或解析项、锁文件归属、包管理器配置、补丁、自动化固定版本的样式，以及容器标签或摘要策略。只有请求或策略明确纳入的情况下，才选择超出声明范围的更新。
• 只有在请求或仓库策略明确纳入运行时和包管理器升级时，才应用这些升级。
• 不要将已拒绝的探测结果及无关的生成文件或源代码管理变更纳入最终差异。

每个包组更新后，将解析器警告与 peer 检查结果核对，并将诊断结果与基线比较。调查相互矛盾的输出，确认依赖图无异常后再继续。将管理器对声明范围的评估和仓库既有例外视为兼容性证据。对报告的问题进行分类：

• 保留 peer 要求符合仓库策略的更新，然后验证应用行为。
• 记录基线中未变化的警告和现有的限定范围例外，不将其视为新回归。是否阻止发布，遵循仓库策略。
• 对于新出现或加重的问题，追踪受影响的使用方、所需范围、解析出的提供方及工作区范围。先尝试协调范围内的更新或受支持的兼容目标，再暂缓受影响的组。
• 只有在有针对性的上游兼容性证据、符合现有 peer 策略的许可，且受影响的检查均通过时，才保留新出现的范围外警告。否则，暂缓或拆分该组，并继续其他独立更新。

验收策略和例外应由仓库策略规定。禁用检查、强行越过解析器错误或添加 peer 抑制规则，都需要明确限定范围的策略变更。仅凭安装命令退出代码为 0 并不足够，尤其是在管理器仅对无效 peer 发出警告时。

将实际选定的版本与台账和发布调研结果核对。确认每项变更后的声明都对应 Include，且每项 Hold 或 Split 声明都保留原值。

完成条件： Audit 模式下依赖图保持不变，并记录拟议的分组和诊断缺口；Improve 或 Publish 模式下，每个已纳入的包组都有 peer 证据，每个报告的问题都有处理结论，暂缓和拆分的声明均未改变，且差异仅包含已纳入的更新及其必要产物。

5. 验证结果

在 Audit 模式下，仅运行仓库批准的只读检查。跳过安装、修复或格式化命令、生成器、有自有输出的构建，以及任何可能更改工作树的验证入口；记录每项跳过的检查关卡，并确认最终文件系统状态与初始状态一致。

在 Improve 或 Publish 模式下，安装已解析的依赖图，并运行适用于已更改范围的仓库锁文件一致性检查，以及文档中规定的格式化、lint、类型检查、测试、构建、生成和验证关卡。在 monorepo 中，纳入受影响的依赖方，以及所有使用已更改共享目录或工具链包的使用方。即使针对性检查通过，也要遵循仓库范围的必需关卡。所有模式下还需：

• 在 Git 工作树中运行 git diff --check。
• 重新运行依赖清单和 peer 检查，并将所有仍未解决的过时项目和 peer 问题与台账核对。
• 完成安全修复后，重新运行适用的安全审计。
• 使用仓库自有工具或既定检查，验证已更改的自动化、容器、补丁和生成产物范围。
• 如果 lint 技术栈发生变化，运行 /linting-alignment 要求的验证。
• 验证后再次检查状态，因为安装和生成器可能会产生额外更改。

检查失败时，应查明是否由此次纳入的更新导致。修复该更新、暂缓该更新或将其拆分；不要将无关的基线失败纳入本次处理，并记录其确切证据。受阻的更新不可发布。

**完成条件：**Audit 模式为每项拟纳入的内容记录所需验证，并保留初始文件系统状态；Improve 或 Publish 模式中的每项已应用内容均通过适用关卡，或因确切的阻塞原因被移除；最终台账与文件系统一致；工作树中仅包含获准的更改。

6. 仅在用户要求时报告和发布

开篇说明仓库原本已是最新状态、已成功更新，还是仍受阻。总结纳入、暂缓和拆分的候选项；敏感更新的证据；已更改范围；安全发现；以及每项验证结果。区分待处理的托管检查与失败项。

Audit 模式结束时，工作树必须保持不变。Improve 模式结束时，已验证的更改保持未提交且未发布。

在 Publish 模式下，遵循仓库指南和执行环境约束。保留任何符合这些要求的当前分支。如果发布需要新分支，且两者都未提供分支名称，则使用 agent/YYYY-MM-DD-update-dependencies 作为备用名称。执行用户要求的发布边界及其前置步骤：

• 用户要求提交或创建拉取请求时，仅暂存本次更新所涉及的文件。
• 用户要求推送或创建拉取请求时，执行推送。
• 用户要求创建或更新拉取请求时，以发现的基础分支为目标。通过 /pr 编写说明，并包含发布源链接、纳入和延期的更新、peer 诊断的处理结果以及验证结果。报告拉取请求的 URL 和待处理的托管检查。

没有剩余更改或验证受阻时，应停止发布。

**完成条件：**用户可以查看已完整核算的范围、每项纳入／暂缓／拆分决定、确切的验证状态，以及用户要求的发布结果或停止发布的确切原因。