dev-dependency-management

依赖管理

快速参考

任务	使用
生态系统默认设置和包管理器选择	references/ecosystem-guides.md
锁文件和 CI 安装策略	references/lockfile-management.md
安全扫描、SBOM 和来源证明	references/security-scanning.md、assets/automation/template-supply-chain-security.md、assets/automation/template-sbom-vuln-triage-checklist.md
单体仓库和工作区策略	references/monorepo-patterns.md、assets/nodejs/pnpm-workspace-template.yaml
更新策略和回滚	references/update-strategies.md、assets/automation/template-dependency-upgrade-playbook.md
添加或避免依赖的决策	references/dependency-selection-guide.md、references/transitive-dependencies.md
漏洞检测	生态系统的原生审计工具（npm audit、pnpm audit、pip-audit、cargo audit、govulncheck、composer audit）或 osv-scanner；参见 references/security-scanning.md
漏洞分类、VEX、EU CRA 查询	references/security-scanning.md
策略清单评分器（不是漏洞扫描器：没有公告数据库，会拒绝真实清单，对未经检查的输入以状态码 2 退出）	python3 scripts/dep_auditor.py --help；限制条件见 scripts/README.md

转至其他指南

• 框架特定的前端或后端实现：使用相应的软件技能。
• 依赖层之外的应用安全架构：使用 software-security-appsec。
• CI/CD 平台设计：使用 ops-devops-platform。

工作流

1. 识别现有的生态系统、包管理器、锁文件和包装器约定。
2. 决定最小且安全的更改：添加、移除、固定版本、更新、审计或迁移。
3. 仅加载锁文件、安全、单体仓库策略或更新策略所需的指南。
4. 迁移 Node 工具链之前，使用下方的查询检查目标主版本的发行说明和脚本审批设置；并将其与 CI 的运行时及所需的原生构建进行比较。
5. 完成可复现性检查、回滚说明，以及任何后续审计或 SBOM 工作。

升级验证与回滚方案

将清单和锁文件视为一个整体变更单元。升级前，记录已解析的版本、完整性／来源元数据、传递依赖变更、安装脚本变更，以及用于保护受影响路径的精确构建／测试／运行时探测。即使请求升级的直接依赖看似无害，也要审查新引入的包和生命周期脚本。

回滚说明必须将清单和锁文件一并恢复到已知的配对状态，并说明缓存、生成的客户端、数据库状态或持久化的线格式是否会导致仅回滚代码并不足够。对于有状态或会改变协议的升级，发布前必须要求向前兼容的迁移方案或经过测试的降级路径。如果新版本已经写入数据或更改外部契约，“回退依赖版本”并不是完整的回滚计划。

核心决策

包管理器默认选择

生态系统	新仓库的默认选择	版本查询	主要约束
Node	除非兼容性需求更倾向于 npm，否则使用 pnpm	npm view pnpm dist-tags（新主版本可能会通过非默认标签发布）	pnpm 11 移除了 onlyBuiltDependencies，改用 allowBuilds；设置 CI 策略前，请查阅目标主版本的发布说明，了解其运行时和安装方式，并查看构建设置中的脚本审批要求
Python	uv	uv 发布说明	承诺 API 稳定性前，检查 uv 是否仍采用 0.x 版本号
Rust	Cargo	固定的 rust-toolchain.toml	应用需提交 Cargo.lock
Go	Go 模块	go.mod 中的 go / toolchain 行	go.mod + go.sum 为规范形式
Java	Maven wrapper 或 Gradle wrapper	wrapper 属性	使用 wrappers，并配合 BOM 或版本目录
.NET	PackageReference	global.json SDK 固定版本	优先使用 PackageReference，而非 packages.config
PHP	Composer	composer.json 中的 config.platform	应用需提交 composer.lock

保持仓库内部的一致性，比追求理论上的生态系统纯粹性更重要。

锁文件和工具链策略

最低要求：

• 提交应用的锁文件
• 在 CI 中使用精确的锁文件安装
• 避免手动编辑锁文件
• 同一个软件包依赖图不要保留多个锁文件
• 优先使用仓库本地的包装器或工具链文件，而非未固定版本的全局安装

规则：当 Claude 编辑匹配的文件时，rules/deps/lockfiles.md 会加载此不变量。

更新策略

默认节奏：

• 补丁版本：小步、频繁更新
• 次版本：集中更新并测试
• 主版本：单独更新，审查发布说明并制定回滚计划
• 安全更新：根据可达性和利用证据确定优先级（优先查看 KEV 收录情况，EPSS 作为可能性信号，CVSS 仅表示严重程度），并将 not_affected 结论及其理由记录为 VEX 声明；参见漏洞分流

供应链控制

使用：

• 尽可能使用官方注册表
• 在支持的情况下验证来源证明或签名
• 为发布产物生成 SBOM，并包含客户或监管机构要求的最少字段（查阅步骤见 references/security-scanning.md）
• 明确审查安装或构建脚本
• 对每个待发布产物设置构建时静态门禁，而不仅检查源代码。门禁覆盖软件包或二进制文件及其中包含的所有内容：供应商化和静态链接的依赖项、插件、扩展或配方清单，以及模板。发布前，检查许可证是否在允许列表中、是否存在已知安全公告，以及来源是否获准（不得使用绕过锁文件的 git 或路径依赖），并对捆绑的清单进行架构验证。未通过检查的产物不得进入发布渠道。可以使用诸如 cargo-deny's deny.toml 之类的策略文件来表达这些规则
• 为例外、解析结果和临时固定版本设置到期时间
• 设置发布延迟（pnpm minimumReleaseAge、Renovate minimumReleaseAge、Dependabot cooldown），避免使用刚发布的软件包；这只是一个防护层，并非根本解决方案，因为过去有几起 npm 被入侵事件在移除前仅持续了数小时（参见 references/security-scanning.md 中的事件模式）
• 缓解依赖混淆：为所有内部软件包添加作用域，在使用前审查所有组织作用域的软件包
• 欧盟市场：如果你在欧盟销售带数字元素的产品，在设计分诊工作流前，查明《网络韧性法案》（Regulation (EU) 2024/2847）中哪些漏洞报告义务适用于你；参见 EU Cyber Resilience Act Lookup
• 在采用 npm 主版本更新前，阅读其对应版本的配置文档和更新日志，了解依赖项生命周期脚本的审批要求，以及 git/远程依赖项的默认设置。在 CI 中检查所需的原生构建和来源，并逐项审查审批内容，不要启用所有脚本。

AI 生成的依赖项风险

接受 AI 推荐的软件包前：

• 确认该软件包确实存在
• 检查是否存在仿冒拼写风险
• 检查维护情况和发布频率
• 在可行时，优先使用标准库或现有依赖项
• 对其执行与其他任何新软件包相同的审计和审查流程

规则：rules/common/dependencies.md 会在每次编码会话中加载此不变量。

输出模式

默认采用以下模式之一：

• 依赖项策略简报： 包管理器选择、锁文件规则、更新频率和安全控制。
• 升级计划： 范围、分批安排、测试、回滚和审计跟进。
• 依赖项审计： 健康风险、无人维护的软件包、依赖图复杂度和修复顺序。
• Monorepo 依赖策略： 工作区模型、共享策略和更新自动化规则。

已知陷阱

• 升级传递依赖项或安全敏感的软件包，却不检查修复是否实际进入生产产物路径。

• 一次性混合升级包装器、锁文件和包管理器，导致回滚和责任归属难度大增。

• 当涉及 postinstall 脚本、peer 依赖项或原生构建时，假定 monorepo 提升依赖项或工作区去重不会造成问题。

• 接受临时固定版本或例外设置，却没有指定移除负责人、到期时间和重新测试触发条件。

• 当来源证明、安装脚本和发布流程仍未经过审查时，却把生成 SBOM 视为已完成供应链控制。

• 把 dep_auditor.py 运行结果干净视为审计通过：它只读取自行声明的标志。其输入必须包含明确的依赖项列表（无依赖项的生态系统使用 []）、布尔策略标志、非负整数形式的依赖项年龄（如有提供），以及非未来日期的扫描日期；声明格式错误时将以状态码 2 退出。

参考资料

文件	内容
references/ecosystem-guides.md	Node、Python、Rust、Go、Java、.NET、PHP 各生态的包管理器默认配置、CI 安装命令和注意事项
references/lockfile-management.md	锁文件对照表、基本规则、各生态的精确安装命令、CI 规则和偏差恢复
references/security-scanning.md	原生审计命令、SBOM 生成、来源证明控制、Dependabot/Renovate 的使用和分诊工作流
references/monorepo-patterns.md	JS/TS 工作区默认配置、pnpm 供应链设置、多语言结构和版本治理
references/dependency-selection-guide.md	添加或避免依赖的决策标准、依赖图检查命令、AI 推荐包检查清单
references/update-strategies.md	更新频率表、按风险分批的工作流、机器人策略和回滚规则
references/transitive-dependencies.md	依赖树检查、覆盖模式、去重和解析决策树
references/license-compliance.md	许可证风险表、GPL 决策树、自动化工具、CI 集成和 SBOM 生成命令
references/version-conflict-resolution.md	冲突类型、各包管理器的诊断命令、强制解析语法和 pnpm catalogs
references/container-dependency-patterns.md	多阶段构建模式、层缓存、漏洞扫描（Trivy/Grype）和可复现的基础镜像固定
references/semver-guide.md	npm、Python 和 Cargo 的 SemVer 约束语法及常见陷阱
references/anti-patterns.md	重大和中度反模式及纠正示例

精选源链接位于 data/sources.json。

导航

• 资源文件：assets/nodejs/package-json-template.json、assets/nodejs/npmrc-template.txt、assets/nodejs/pnpm-workspace-template.yaml、assets/python/pyproject-toml-template.toml、assets/automation/dependabot-config.yml、assets/automation/renovate-config.json、assets/automation/audit-checklist.md、assets/automation/template-dependency-upgrade-playbook.md、assets/automation/template-supply-chain-security.md、assets/automation/template-sbom-vuln-triage-checklist.md
• 脚本和示例：scripts/dep_auditor.py、scripts/README.md、data/sample-dependency-manifest.example.json

学习循环

如果先前的决策或陷阱与当前任务相关，请在 learnings.consolidated.md 存在时查阅；仅在需要了解历史或它是现有备用资料时使用 learnings.md。否则跳过这两个文件。

应用这些经验后，如果你遇到了值得记住的模式、值得避免的错误，或让你感到意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的项目。不要修改 SKILL.md 本身。