名称: 开发依赖管理描述: 跨生态系统（npm、pip、cargo、maven）的包和依赖管理模式。覆盖锁文件、语义版本控制、依赖安全扫描、更新策略、单仓库工作空间、传递依赖和避免依赖地狱。

依赖管理 — 生产模式

现代最佳实践（2026年1月）：锁文件优先工作流、自动化安全扫描（Dependabot、Snyk、Socket.dev）、语义版本控制、最小依赖原则、单仓库工作空间（pnpm、Nx、Turborepo）、供应链安全（SBOM、AI BOM、Sigstore）、可重复构建和AI生成的代码验证。

何时使用此技能

代理应在用户请求以下内容时调用此技能：

向项目添加新依赖项
安全更新现有依赖项
解决依赖冲突或版本不匹配
审计依赖项以查找安全漏洞
理解锁文件管理和可重复构建
设置单仓库工作空间（pnpm、npm、yarn）
管理传递依赖项和覆盖
在相似包之间选择（包大小、维护、安全）
依赖版本约束和语义版本控制
依赖安全最佳实践和供应链安全
故障排除“依赖地狱”场景
包管理器配置和优化
创建跨环境可重复构建

快速参考

任务	工具/命令	关键操作	何时使用
从锁文件安装	`npm ci`、`poetry install`、`cargo build`	清洁安装，可重复	CI/CD，生产部署
添加依赖项	`npm install <pkg>`、`poetry add <pkg>`	自动更新锁文件	新功能需要库
更新依赖项	`npm update`、`poetry update`、`cargo update`	在版本约束内更新	每月/季度维护
检查漏洞	`npm audit`、`pip-audit`、`cargo audit`	扫描已知CVE	发布前，每周
查看依赖树	`npm ls`、`pnpm why`、`pipdeptree`	显示传递依赖项	调试冲突
覆盖传递依赖	`overrides`（npm）、`pnpm.overrides`	强制特定版本	安全补丁，冲突解决
单仓库设置	`pnpm workspaces`、`npm workspaces`	共享依赖项，交叉链接	多包项目
检查过时	`npm outdated`、`poetry show --outdated`	列出可用更新	计划更新冲刺

决策树：依赖管理

用户需求：[依赖任务]
    ├─ 添加新依赖项？
    │   ├─ 检查：我真的需要这个吗？（能否在<100 LOC中实现？）
    │   ├─ 检查：它维护良好吗？（最后提交<6个月，>10k下载/周）
    │   ├─ 检查：包大小影响？（对JS使用Bundlephobia）
    │   ├─ 检查：安全风险？（`npm audit`、Snyk）
    │   └─ 如果所有检查通过 → 使用`npm install <pkg>`添加 → 提交锁文件
    │
    ├─ 更新依赖项？
    │   ├─ 安全漏洞？ → `npm audit fix` → 测试 → 立即部署
    │   ├─ 例行更新？
    │       ├─ 补丁版本 → `npm update` → 安全，频繁进行
    │       ├─ 次要/主要 → 检查CHANGELOG → 在暂存环境测试 → 逐步更新
    │       └─ 全部同时 → [失败] 风险高 → 改为分批更新
    │
    ├─ 依赖冲突？
    │   ├─ 传递依赖问题？
    │       ├─ 查看树：`npm ls <package>`
    │       ├─ 谨慎使用覆盖：package.json中的`overrides`
    │       └─ 记录为什么需要覆盖
    │   └─ 对等依赖不匹配？
    │       └─ 检查版本兼容性 → 更新父或子依赖
    │
	├─ 单仓库项目？
	│   ├─ 使用pnpm工作空间（推荐默认）
	│   ├─ 共享依赖 → 根package.json
	│   ├─ 包特定 → 包目录
	│   └─ 使用Nx或Turborepo进行任务缓存
	│
	└─ 选择包管理器？
	    ├─ 新JS项目 → **pnpm**（推荐默认）或**Bun**（通常更快；验证生态系统成熟度）
	    ├─ 企业单仓库 → **pnpm**（成熟的工作空间支持）
	    ├─ 速度优先实验 → **Bun**（验证生态系统成熟度）
	    ├─ 现有npm项目 → 迁移到pnpm或保持（检查团队偏好）
	    ├─ Python → **uv**（快）、Poetry（成熟）、pip+venv（简单）
	    └─ 数据科学 → **conda**或**uv**（更快环境设置）

导航：核心模式

锁文件管理

references/lockfile-management.md

锁文件通过记录所有依赖项（直接+传递）的确切版本来确保可重复构建。防止“在我的机器上工作”问题至关重要。

黄金规则（始终提交，永不手动编辑，更改时重新生成）
按生态系统命令（npm ci、poetry install、cargo build）
故障排除锁文件冲突
CI/CD集成模式

语义版本控制（SemVer）

references/semver-guide.md

理解版本约束（^、~、精确）以及如何安全指定依赖范围。

SemVer格式（MAJOR.MINOR.PATCH）
版本约束语法（caret、tilde、精确）
按项目类型推荐策略
跨生态系统版本管理

依赖安全审计

references/security-scanning.md

自动化安全扫描、漏洞管理和供应链安全最佳实践。

自动化工具（Dependabot、Snyk、GitHub高级安全）
运行审计（npm audit、pip-audit、cargo audit）
CI集成和警报配置
事件响应工作流

依赖选择

references/dependency-selection-guide.md

决定是否添加新依赖项并在相似包之间选择。

最小依赖原则（最好的依赖是你不添加的那个）
评估清单（维护、包大小、安全、替代方案）
在相似包之间选择（比较矩阵）
何时拒绝依赖项

更新策略

references/update-strategies.md

安全地保持依赖项最新，同时最小化破坏性更改和安全风险。

更新策略（连续、计划、仅安全）
安全更新工作流（检查过时、分类风险、测试、部署）
自动化更新工具（Dependabot、Renovate、npm-check-updates）
处理破坏性更改和回滚计划

单仓库管理

references/monorepo-patterns.md

在单个仓库中管理多个相关包，共享依赖项。

工作空间工具（pnpm、npm、yarn工作空间）
单仓库结构和组织
构建优化（Nx、Turborepo）
版本控制和发布策略

传递依赖项

references/transitive-dependencies.md

处理依赖项的依赖项（间接依赖项）。

查看依赖树（npm ls、pnpm why、pipdeptree）
解决传递冲突（覆盖、解析、约束）
安全风险和版本冲突
最佳实践（谨慎使用、记录、测试）

生态系统特定指南

references/ecosystem-guides.md

语言和包管理器特定最佳实践。

Node.js（npm、yarn、pnpm比较和最佳实践）
Python（pip、poetry、conda）
Rust（cargo）、Go（go mod）、Java（maven、gradle）
PHP（composer）、.NET（nuget）

反模式

references/anti-patterns.md

管理依赖项时要避免的常见错误。

关键反模式（不提交锁文件、通配符、忽略审计）
危险反模式（从不更新、已弃用包）
中等反模式（过度使用覆盖、忽略对等依赖）

导航：模板

Node.js

assets/nodejs/

package-json-template.json - 生产就绪package.json，含最佳实践
npmrc-template.txt - npm团队配置
pnpm-workspace-template.yaml - 单仓库工作空间设置

Python

assets/python/

pyproject-toml-template.toml - Poetry配置，含最佳实践

自动化

assets/automation/

dependabot-config.yml - GitHub Dependabot配置
renovate-config.json - Renovate Bot配置
audit-checklist.md - 安全审计工作流
template-supply-chain-security.md - 新 SBOM、来源、漏洞管理
template-dependency-upgrade-playbook.md - 升级分批、推出、回滚
template-sbom-vuln-triage-checklist.md - SBOM映射+漏洞分类

供应链安全

assets/automation/template-supply-chain-security.md — 生产级依赖安全。

关键部分

SBOM生成 — CycloneDX、SPDX格式；CI/CD集成
AI BOM（新兴） — AI原生系统的扩展SBOM（模型、数据集、训练工件）
来源与认证 — SLSA级别、Sigstore签名、npm来源
漏洞管理 — 分类工作流、严重性SLA、扫描工具
升级剧本 — 分批策略、回滚程序
固定与可重复性 — 锁文件、哈希固定、版本约束
欧盟网络弹性法案 — 2027年12月生效的SBOM要求

做 / 避免

好：做

为每个发布生成SBOM
签署发布工件（Sigstore/cosign）
在CI/CD中运行漏洞扫描
在24小时内修复关键漏洞
使用锁文件进行可重复构建
验证npm包来源
按风险级别分批非安全更新

坏：避免

发布无SBOM
在生产中使用未签名包
忽略漏洞扫描器输出
一次更新所有依赖项
使用通配符版本范围（*、>=）
提交未更新锁文件
绕过安全门“仅此一次”

反模式

反模式	问题	修复
无SBOM	无法响应供应链攻击	在CI/CD中生成SBOM
未签名工件	篡改无法检测	使用Sigstore签名
浮动版本	构建不可重复	使用锁文件+精确版本
一次性全部更新	难以二分回归	按风险级别分批
CI中使用npm install	非确定性	使用`npm ci`
无审计门	漏洞发布到生产	基于审计门部署

AI生成的依赖风险

警告：AI编码代理可以大规模引入易受攻击或不存在的包（Endor Labs，2025年）。

问题

AI工具加速编码但引入供应链风险：

幻觉包 — AI建议不存在的包（typosquatting向量）
易受攻击依赖项 — AI推荐过时或CVE影响版本
不必要依赖项 — AI过度依赖包处理简单任务

最佳实践

做	不做
将AI生成代码视为不受信任的第三方输入	盲目接受AI依赖建议
对AI生成代码强制执行相同SAST/SCA扫描	跳过“AI编写”代码的安全审查
验证所有AI建议包确实存在	信任AI知道当前包版本
将安全工具集成到AI工作流中（MCP）	允许AI添加依赖项而无审查
将MCP服务器作为供应链一部分审查	使用未审查AI集成

验证清单

在接受AI建议依赖项之前：

[ ] 包存在于注册表（npm、PyPI、crates.io）
[ ] 包名拼写正确（无typosquatting）
[ ] 版本当前且维护
[ ] npm audit / pip-audit显示无漏洞
[ ] 每周下载>1000（已建立包）
[ ] 最后提交<6个月（积极维护）

可选：AI/自动化

注意：AI协助分类但安全决策需要人类判断。

自动化PR分类 — 按风险分类依赖更新
变更日志摘要 — 总结更新中的破坏性更改
漏洞关联 — 链接CVE到受影响包

有界声明

AI无法确定业务风险接受
自动化修复需要安全团队审查
漏洞严重性上下文需要人类验证

快速决策矩阵

场景	推荐
添加新依赖项	检查Bundlephobia、npm audit、每周下载、最后提交
更新依赖项	使用`npm outdated`，分批更新，在暂存环境测试
发现安全漏洞	使用`npm audit fix`，审查CHANGELOG，测试，立即部署
单仓库设置	使用pnpm工作空间或Nx/Turborepo进行构建缓存
传递冲突	谨慎使用`overrides`，记录原因，彻底测试
选择JS包管理器	pnpm（最快，磁盘效率高），Bun（7×更快），npm（最兼容）
Python环境	uv（10-100×更快），Poetry（成熟），pip+venv（简单），conda（数据科学）

核心原则

1. 始终提交锁文件

锁文件确保跨环境可重复构建。永远不要将它们添加到.gitignore。

例外：Rust库不要提交Cargo.lock（仅适用于应用程序）。

2. 使用语义版本控制

对大多数依赖使用caret（^），对关键任务使用精确版本，避免通配符（*）。

{
  "dependencies": {
    "express": "^4.18.0",  // 允许补丁和次要版本
    "critical-lib": "1.2.3"  // 对关键精确
  }
}

3. 定期审计依赖项

每周运行安全审计，立即修复关键漏洞。

npm audit
npm audit fix

4. 最小化依赖项

最好的依赖是你不添加的那个。问：我能否在<100 LOC中实现？

5. 定期更新

每月或每季度更新。不要让技术债务累积。

npm outdated
npm update

6. 谨慎使用覆盖

仅为安全补丁或冲突覆盖传递依赖项。记录原因。

{
  "overrides": {
    "axios": "1.6.0"  // CVE-2023-xxxxx修复
  }
}

外部资源

参见data/sources.json获取精选资源：

包管理器：npm、pnpm、Yarn、pip、Poetry、Cargo、Go模块、Maven、Composer
语义版本控制：SemVer规范，版本计算器，约束参考
安全工具：Snyk、Dependabot、GitHub高级安全、OWASP Dependency-Check、pip-audit、cargo-audit、Socket.dev、Renovate
锁文件管理：package-lock.json、poetry.lock、Cargo.lock、pnpm-lock.yaml官方文档
单仓库工具：pnpm工作空间、npm工作空间、Yarn工作空间、Nx、Turborepo、Lerna、Bazel
分析工具：Bundlephobia、npm-check-updates、depcheck、pipdeptree、cargo tree
供应链安全：SLSA框架、SBOM（CISA）、Sigstore、npm来源、OpenSSF Scorecard
最佳实践：npm/Poetry/Cargo指南、ACM Queue文章、依赖地狱参考
版本管理：nvm、pyenv、rustup、asdf
学习资源：npm指南、Python打包用户指南、Rust书、Monorepo.tools

使用说明

对于Codex / Claude Code：

当用户需要依赖管理指导时使用此技能
基于任务引用特定资源（锁文件、安全、更新）
提供生态系统特定指导（Node.js、Python、Rust）
始终推荐安全审计和可重复构建
鼓励最小依赖和定期更新
链接到常见配置模板

最佳实践：

始终提交锁文件（除库的Cargo.lock外）
使用语义版本控制（对大多数依赖caret，对关键精确）
每周审计依赖项（npm audit、pip-audit、cargo audit）
每月或每季度更新依赖项（不要一次全部）
基于项目需求选择包管理器（pnpm用于速度，Poetry用于Python应用）
在ADRs（架构决策记录）中记录依赖选择

成功标准：依赖项最小化、维护良好、安全、跨环境可重复，并定期审计漏洞。

趋势感知协议

重要：当用户询问有关包管理器、依赖工具或供应链安全的推荐问题时，你必须在回答前使用WebSearch检查当前趋势。

触发条件

“对于[生态系统]，什么是最好的包管理器？”
“我应该使用什么进行[依赖管理/安全]？”
“依赖管理的最新趋势是什么？”
“[npm/pnpm/Poetry]的当前最佳实践？”
“[工具/方法]在2026年仍然相关吗？”
“[pnpm] vs [npm] vs [yarn]？”
“最佳依赖安全扫描器？”

必需搜索

搜索：“dependency management best practices 2026”
搜索：“[specific tool] vs alternatives 2026”
搜索：“supply chain security trends January 2026”
搜索：“[package manager] features 2026”

报告内容

搜索后，提供：

当前格局：现在哪些依赖工具流行
新兴趋势：获得关注的新包管理器、安全工具或模式
已弃用/下降：失去相关性或支持的工具/方法
推荐：基于新鲜数据，不仅是静态知识

示例主题（用新鲜搜索验证）

包管理器（pnpm、npm、yarn、Poetry、uv for Python）
安全扫描（Snyk、Dependabot、Socket.dev）
供应链安全（SBOM、Sigstore、SLSA）
单仓库工具（Nx、Turborepo、Bazel）
锁文件和可重复性模式
自动化依赖更新（Renovate、Dependabot）

名称: 开发依赖管理 描述: 跨生态系统（npm、pip、cargo、maven）的包和依赖管理模式。覆盖锁文件、语义版本控制、依赖安全扫描、更新策略、单仓库工作空间、传递依赖和避免依赖地狱。