ln-711-npm-upgrader

路径： 文件路径（shared/、references/、../ln-*）均相对于 skills 仓库根目录。如果当前工作目录下找不到，请定位此 SKILL.md 目录，并向上一级找到仓库根目录。

ln-711-npm-upgrader

类型： L3 Worker 类别： 7XX 项目引导 父级： ln-710-dependency-upgrader

使用 npm、yarn 或 pnpm 升级 Node.js 依赖项，并自动检测和迁移破坏性变更。

---

概述

方面	详情
输入	项目路径、包管理器类型
输出	更新后的 package.json、锁文件、迁移报告
支持	npm、yarn（classic 和 berry）、pnpm

---

工作流

请参阅 diagram.html 查看可视化工作流。

阶段： 预检 → 分析 → 安全审计 → 检查过期依赖 → 识别破坏性变更 → 应用升级 → 应用迁移 → 验证构建 → 生成报告

---

阶段 0：预检

检查项	必需	缺失时的操作
锁文件（package-lock.json、yarn.lock、pnpm-lock.yaml）	是	发出警告并先运行 npm install
package.json	是	阻止升级

Worker 假定协调器（ln-710）已验证 git 状态并创建备份。

---

阶段 1：分析依赖项

读取 package.json，并按升级优先级对依赖项分类。

依赖项类别

类别	示例	优先级
框架	react、vue、angular	2（在 peer deps 之后）
构建	vite、webpack、esbuild	3
UI	@radix-ui/*、tailwindcss	4
状态	@tanstack/react-query、zustand	5
工具	lodash、date-fns	6
开发	eslint、prettier、typescript	7
peer	@types/*、typescript	1（最先）

---

阶段 2：安全审计

命令

管理器	命令
npm	npm audit --audit-level=high
yarn	yarn audit --level high
pnpm	pnpm audit --audit-level high

操作

严重性	操作
严重	阻止升级并报告
高	发出警告，继续
中/低	仅记录

---

阶段 3：检查过期依赖

命令

管理器	命令
npm	npm outdated --json
yarn	yarn outdated --json
pnpm	pnpm outdated --json

---

阶段 4：识别破坏性变更

检测

必须阅读： 加载 breaking_changes_patterns.md 查看完整模式。

1. 比较当前版本与最新主版本
2. 查看 breaking_changes_patterns.md 中的已知模式
3. 查询 Context7/Ref 获取迁移指南

常见破坏性变更

包	破坏性变更版本	主要变更
react	18 → 19	JSX 转换、ref 作为 prop
vite	5 → 6	仅 ESM、Node 18+
eslint	8 → 9	必须使用 Flat config
tailwindcss	3 → 4	基于 CSS 的配置
typescript	5.4 → 5.5+	更严格的类型推断

---

阶段 5：应用升级

升级顺序

1. Peer 依赖项（TypeScript、@types/*）
2. 框架包（React、Vue core）
3. 构建工具（Vite、webpack）
4. UI 库（在框架之后）
5. 工具库（lodash、date-fns）
6. 开发依赖项（测试、lint）

命令

管理器	命令
npm	npm install <package>@latest --save
yarn	yarn add <package>@latest
pnpm	pnpm add <package>@latest

Peer 依赖冲突

情况	解决方案
ERESOLVE 错误	npm install --legacy-peer-deps
仍然失败	npm install --force（最后手段）

---

用于搜索迁移资料的 MCP 工具

优先级顺序（回退策略）

优先级	工具	使用时机
1	mcp__context7__query-docs	首选，用于查询库文档
2	mcp__Ref__ref_search_documentation	官方文档和 GitHub
3	WebSearch	最新信息、社区解决方案

Context7 用法

步骤	工具	参数
1. 查找库	mcp__context7__resolve-library-id	libraryName: "react", query: "migration guide"
2. 查询文档	mcp__context7__query-docs	libraryId: "/facebook/react", query: "react 18 to 19 migration"

MCP Ref 用法

操作	工具	查询示例
搜索	mcp__Ref__ref_search_documentation	"react 19 migration guide breaking changes"
阅读	mcp__Ref__ref_read_url	搜索结果中的 URL

WebSearch 备用方案

在 Context7/Ref 没有返回结果时使用：

• "<package> <version> breaking changes migration {current_year}"
• "<package> <error message> fix stackoverflow"

---

阶段 6：应用迁移

流程

1. 使用 MCP 工具（见上文）查找迁移指南
2. 通过 Edit 工具应用自动代码转换
3. 记录手动迁移步骤并告知用户

不要应用硬编码的迁移。始终通过 MCP 工具获取最新指南。

---

阶段 7：验证构建

命令

检查项	命令
TypeScript	npm run check 或 npx tsc --noEmit
构建	npm run build
测试	npm test（如有）

失败时

1. 根据错误确定失败的包
2. 在 Context7/Ref 中搜索解决方案
3. 如果无法解决：回滚该包，并继续处理其他包

---

阶段 8：报告结果

报告架构

字段	描述
project	项目路径
packageManager	npm、yarn 或 pnpm
duration	总耗时
upgrades.major[]	已应用的破坏性变更
upgrades.minor[]	功能更新
upgrades.patch[]	错误修复
migrations[]	已应用的迁移
skipped[]	已是最新版本
buildVerification	PASSED 或 FAILED
warnings[]	不影响继续执行的问题

---

配置

Options:
  # Upgrade scope
  upgradeType: major          # major | minor | patch

  # Breaking changes
  allowBreaking: true
  autoMigrate: true
  queryMigrationGuides: true  # Use Context7/Ref

  # Security
  auditLevel: high            # none | low | moderate | high | critical
  minimumReleaseAge: 14       # days

  # Peer dependencies
  legacyPeerDeps: false
  force: false

  # Verification
  runBuild: true
  runTests: false
  runTypeCheck: true

  # Rollback
  createBackup: true
  rollbackOnFailure: true

---

错误处理

错误	原因	解决方案
ERESOLVE	Peer dep 冲突	--legacy-peer-deps
ENOENT	缺少锁文件	先运行 npm install
构建失败	破坏性变更	通过 Context7 应用迁移
类型错误	版本不匹配	更新 @types/*

回滚

从 git 恢复 package.json 和锁文件，然后运行干净安装以恢复先前状态。

---

参考资料

• breaking_changes_patterns.md
• npm_peer_resolution.md

---

完成定义

• 已确认锁文件和 package.json 存在
• 已对依赖分类并确定优先级（先处理 peer deps）
• 已完成安全审计（严重问题会阻止升级）
• 已通过 npm/yarn/pnpm outdated 识别过时的包
• 已通过 breaking_changes_patterns.md 和 MCP 工具检测破坏性变更
• 已按优先级应用升级，失败时回滚
• 升级后构建和类型检查均通过
• 已返回报告，包含 major/minor/patch 数量、迁移内容和构建状态

---

版本： 1.1.0 最后更新： 2026-01-10