依赖升级与兼容性
让 Agent 按 SemVer、变更日志、peer 约束与 lockfile 一致性推进升级：分批合并、特性开关与可执行回滚。本页按「流程 → 版本语义 → 锁文件 → 迁移与观测 → SKILL → depup-page 清单」组织。
先区分补丁、次版本与主版本；对传递依赖冲突，SKILL 要求输出解析树差异与 pin 理由。安全补丁尽量独立 PR，与功能升级解耦。
升级主流程（skill-flow-block）
[ 清点：直接依赖 + 传递链 + peer / optional ]
│
▼
┌──────────────────────┐
│ SemVer：目标版本档位 │──── 读 CHANGELOG / Releases；
│ 与破坏性矩阵 │ 主版本默认扩测试或合约
└──────────────────────┘
│
▼
┌──────────────────────┐
│ Lockfile：同一解析器 │──── npm / pnpm / pip / Go modules …
│ 与镜像源在 CI 与本地一致 │ 禁止「只改 package 不改 lock」分叉
└──────────────────────┘
│
▼
┌──────────────────────┐
│ 迁移：codemod / 适配 │──── 特性开关渐进；废弃 API 给替代与时间表
│ 与预发或金丝雀观测 │
└──────────────────────┘
│
▼
[ 合流 │ 保留回滚：上一 lock 快照 / tag / revert 命令 ]
顺序要点：版本语义与 lock 一致性先于大改代码；合流后靠指标验收，并把「回到上一解析结果」写成一条可执行命令，而不是口头约定。
SemVer 与破坏性变更检测
补丁与次版本仍可能因类型收紧、Node/Java 运行时差异或隐式行为变化而破坏构建；主版本升级必须假设 API 面变化，并核对官方迁移指南。
- 阅读 CHANGELOG：关注
Breaking、弃用周期与最低运行时要求。 - Peer 依赖：框架插件、
engines、原生模块 ABI 与操作系统矩阵一并列出。 - 废弃 API：给出替代路径与计划移除版本，避免静默堆积技术债。
npm-check-updates 使用与分批升级策略：
# npm-check-updates 检测可升级依赖
# 安装
npm install -g npm-check-updates
# 查看所有可升级依赖（不修改 package.json）
npx ncu
# 只升级 patch 版本
npx ncu --target patch -u
npm install
# 只升级 minor 版本
npx ncu --target minor -u
npm install
# 升级指定包的 major 版本（需单独处理）
npx ncu -u react react-dom
npm install
# 查看依赖树差异（升级前后对比）
npm ls --depth=2 > deps-before.txt
npx ncu -u && npm install
npm ls --depth=2 > deps-after.txt
diff deps-before.txt deps-after.txt
# 分批升级策略（推荐顺序）
# 批次1: patch（自动合并，风险最低）
# 批次2: minor（冒烟测试后合并）
# 批次3: major（单独 PR + 迁移指南 + 扩展测试）
# 安全 CVE：独立 PR，走紧急通道Lockfile 与解析一致性
国内镜像与 registry 切换时，须保证 CI、容器构建与开发者本地使用同一套锁文件与安装命令；否则会出现「本地绿、流水线红」的解析分叉。
- Node：
package-lock.json/pnpm-lock.yaml/yarn.lock择一并全员一致；npm ci类命令与缓存策略写进文档。 - Python：
requirements.txt带哈希或poetry.lock/uv.lock；禁止混用未锁定的范围升级。 - Go：
go.sum与 module proxy；私有仓库凭据与GOPRIVATE说明清楚。
迁移、Renovate 配置与回滚
破坏性 API 迁移应附带 codemod 或渐进适配步骤；合并后在预发或金丝雀观察错误率与延迟，并明确回滚到上一 lock 快照或制品版本的操作。
- 主版本升级默认附带扩展测试或合约测试更新。
- 特性开关可隔离新依赖路径，便于快速关闭。
- 记录与操作系统、语言运行时的兼容性矩阵，便于 on-call 对照。
Renovate 配置文件示例（patch 自动合并 + major 需人工审阅）：
// renovate.json — 项目根目录
{
"$schema": "https://docs.renovatebot.com/renovate-schema.json",
"extends": ["config:recommended"],
// 合并时间窗：工作日上午（减少噪音）
"schedule": ["before 9am on Monday through Friday"],
// patch 版本：自动合并（CI 全绿才合并）
"packageRules": [
{
"matchUpdateTypes": ["patch"],
"automerge": true,
"automergeType": "pr",
"requiredStatusChecks": ["CI / test", "CI / lint"]
},
// minor 版本：自动创建 PR，需人工 review
{
"matchUpdateTypes": ["minor"],
"automerge": false,
"labels": ["dependencies", "minor"]
},
// major 版本：分组到同一 PR，带 breaking change 标签
{
"matchUpdateTypes": ["major"],
"automerge": false,
"groupName": "major dependencies",
"labels": ["dependencies", "major", "breaking-change"]
},
// 安全漏洞：立即创建 PR，不等时间窗
{
"matchCategories": ["security"],
"schedule": "at any time",
"automerge": false,
"labels": ["security", "urgent"]
}
],
// lockfile 维护：每周更新 lockfile（无版本变更时）
"lockFileMaintenance": {
"enabled": true,
"schedule": ["before 6am on Monday"]
}
}SKILL 片段
---
name: dependency-upgrade-cn
description: 评估依赖升级、SemVer、兼容性与 lockfile 一致性
---
# 检测工具
- npm-check-updates：npx ncu（查看）/ npx ncu -u（更新）
- Renovate：自动创建 PR，可配置 automerge
- npm audit：npx npm audit（安全漏洞检测）
# 分批升级策略
- 批次1: patch → automerge（CI 全绿）
- 批次2: minor → 创建 PR，冒烟测试后合并
- 批次3: major → 单独 PR + 迁移指南 + 扩展测试
- 安全 CVE → 独立 PR，走紧急通道不等时间窗
# 核对清单
1. CHANGELOG：Breaking / 弃用 / 最低运行时要求
2. peer 依赖：engines / 框架插件 / 原生模块 ABI
3. 传递依赖：npm ls --depth=2 前后 diff
4. lockfile：package-lock.json / pnpm-lock.yaml 择一并全员一致
5. CI 与本地使用同一 npm/pnpm 大版本
# Renovate automerge 配置要点
- patch: automerge: true, requiredStatusChecks: [CI/test]
- minor: automerge: false, 人工 review
- major: groupName 分组 + breaking-change 标签
- lockFileMaintenance: 每周维护 lockfile
# 回滚
- 记录升级前的 lock 提交 SHA / tag
- 回滚命令：git checkout <sha> -- package-lock.json && npm ci升级自检清单（depup-page JS）
选择生态与升级档位后生成本页专用备忘（仅本地、无网络）；贴进 issue 或 PR 描述前请按实际栈裁剪。
升级备忘