ln-821-npm-upgrader

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

ln-821-npm-upgrader

类型： L3 Worker 类别： 8XX 优化

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

---

概述

方面	详情
输入	项目路径、包管理器类型、升级策略
输出	更新后的包清单，以及机器可读的依赖升级摘要
支持	npm、yarn（classic 和 berry）、pnpm

---

工作流

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

---

阶段 0：预检

检查项	必需	缺失时的操作
package.json	是	阻止升级
锁文件（package-lock.json、yarn.lock、pnpm-lock.yaml）	否	发出警告，并在最终验证前重新生成
包管理器可用	是	阻止升级
工作区基线安全	是	在托管运行中，协调器已做好准备；在独立运行中，在本地保护回滚

运行时协调

托管运行会从 ln-820 接收确定性的 runId 和准确的 summaryArtifactPath。 仍支持独立运行；如果省略运行时参数，则在返回前生成一个独立运行专用的产物。

---

阶段 1：分析依赖

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

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

---

阶段 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. 检查共享的破坏性变更模式。
3. 修改代码前，通过 Context7 或 Ref 查询迁移指南。

常见破坏性变更示例：

包	破坏性版本	主要变更
react	18 -> 19	JSX 转换、refs 作为 props
vite	5 -> 6	仅支持 ESM、更新的 Node 基线
eslint	8 -> 9	扁平配置
tailwindcss	3 -> 4	CSS 优先配置
typescript	5.4 -> 5.5+	更严格的类型推断

---

阶段 5：应用升级

升级顺序：

1. peer 依赖
2. 框架包
3. 构建工具
4. UI 库
5. 工具库
6. 开发依赖

管理器	命令
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	获取最新信息和社区修复方案

进行非简单的更改前，先使用 MCP 工具查找迁移指南。

---

阶段 6：应用迁移

1. 使用 MCP 工具查找当前迁移指南。
2. 仅在迁移指南支持时应用自动化代码转换。
3. 记录手动后续步骤，以便纳入最终报告。

未核对当前文档前，不要硬编码迁移。

---

阶段 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[]	已是最新版本或因策略跳过
verification	构建／测试／类型检查结果
warnings[]	非阻塞问题
artifact_path	持久化 Worker 报告路径（如已写入）

---

配置

Options:
  upgradeType: major          # major | minor | patch
  allowBreaking: true
  autoMigrate: true
  queryMigrationGuides: true
  auditLevel: high
  minimumReleaseAge: 14
  legacyPeerDeps: false
  force: false
  runBuild: true
  runTests: false
  runTypeCheck: true
  rollbackOnFailure: true

---

错误处理

错误	原因	解决方案
ERESOLVE	对等依赖冲突	使用 legacy peer dependency 模式重试
ENOENT	缺少锁文件	先重新生成依赖
构建失败	破坏性更改	应用迁移指南或回滚问题软件包
类型错误	版本不匹配	更新类型定义或框架对等软件包

回滚： 恢复 package.json 和锁文件，然后执行干净安装以恢复先前状态。

---

参考资料

• breaking_changes_patterns.md
• npm_peer_resolution.md

---

运行时摘要工件

必须阅读： 加载 references/coordinator_summary_contract.md

输出一个 dependency-worker 摘要封装。

托管模式：

• ln-820 传入确定性的 runId 和精确的 summaryArtifactPath
• 将摘要写入提供的 summaryArtifactPath

独立模式：

• 省略 runId 和 summaryArtifactPath
• 写入 .hex-skills/runtime-artifacts/runs/{run_id}/dependency-worker/ln-821--{identifier}.json

Monitor（2.1.98+）： 对于预计耗时超过 30 秒的安装／审计／构建／测试命令，请使用 Monitor。后备方案：Bash(run_in_background=true)。

完成定义

• 已分析软件包清单并确定依赖优先级
• 已针对所选包管理器完成安全审计
• 已识别过期软件包
• 已通过模式和当前文档检查破坏性更改
• 已应用升级，并在失败时回滚
• 升级后构建和相关验证命令均通过
• 已将 dependency-worker 摘要工件写入托管或独立路径

---

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