Node.js依赖自动升级工具 - npm/yarn/pnpm包管理器智能升级与破坏性变更检测

ln-821-npm-upgrader by levnikolaevich/claude-code-skills

77 周安装量

253 GitHub Stars

安装命令

npx skills add https://github.com/levnikolaevich/claude-code-skills --skill ln-821-npm-upgrader

🇨🇳中文介绍

路径说明： 文件路径（shared/、references/、../ln-*）是相对于技能仓库根目录的。如果在当前工作目录未找到，请定位此 SKILL.md 文件所在目录并向上返回一级以找到仓库根目录。如果缺少 shared/ 目录，请通过 WebFetch 从 https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path} 获取文件。

ln-821-npm-upgrader

类型： L3 Worker 类别： 8XX 优化 父级： ln-820-dependency-optimization-coordinator

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

概述

方面	详情

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

检查项	是否必需	缺失时的操作
锁文件（package-lock.json，yarn.lock，pnpm-lock.yaml）	是	警告并先运行 `npm install`
package.json	是	阻止升级
Git 干净状态	是	阻止（需要干净的基线用于回滚）

工作树与分支隔离

强制阅读： 加载 shared/references/git_worktree_fallback.md — 使用 ln-821 行。

阶段 1：分析依赖项

读取 package.json 并对依赖项进行分类，以确定升级优先级。

类别	示例	优先级
框架	react，vue，angular	2（在对等依赖之后）
构建工具	vite，webpack，esbuild	3
UI 库	@radix-ui/*，tailwindcss	4
状态管理	@tanstack/react-query，zustand	5
工具库	lodash，date-fns	6
开发依赖	eslint，prettier，typescript	7
对等依赖	@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 查看完整模式。

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

常见的破坏性变更

包	破坏性版本	关键变更
react	18 → 19	JSX 转换，ref 作为 prop
vite	5 → 6	仅支持 ESM，Node 18+
eslint	8 → 9	需要扁平配置
tailwindcss	3 → 4	基于 CSS 的配置
typescript	5.4 → 5.5+	更严格的类型推断

阶段 5：应用升级

对等依赖（TypeScript，@types/*）
框架包（React，Vue 核心）
构建工具（Vite，webpack）
UI 库（在框架之后）
工具库（lodash，date-fns）
开发依赖（测试，代码检查）

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

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

用于迁移搜索的 MCP 工具

优先级顺序（回退策略）

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

步骤	工具	参数
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__ref_search_documentation	"react 19 migration guide breaking changes"
阅读	mcp__Ref__ref_read_url	来自搜索结果的 URL

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

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

阶段 6：应用迁移

使用 MCP 工具（见上文）查找迁移指南
通过 Edit 工具应用自动化代码转换
为用户记录手动迁移步骤

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

阶段 7：验证构建

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

从错误中识别失败的包
搜索 Context7/Ref 寻找修复方案
如果未解决：回滚该包，继续处理其他包

阶段 8：报告结果

字段	描述
project	项目路径
packageManager	npm，yarn 或 pnpm
duration	总耗时
upgrades.major[]	应用的破坏性变更
upgrades.minor[]	功能更新
upgrades.patch[]	错误修复
migrations[]	应用的迁移
skipped[]	已是最新版本
buildVerification	通过或失败
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	对等依赖冲突	--legacy-peer-deps
ENOENT	缺少锁文件	先运行 npm install
构建失败	破坏性变更	通过 Context7 应用迁移
类型错误	版本不匹配	更新 @types/*

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

锁文件和 package.json 已验证存在
依赖项已分类并确定优先级（对等依赖优先）
安全审计已完成（严重问题会阻止升级）
通过 npm/yarn/pnpm outdated 识别出过时的包
通过 breaking_changes_patterns.md 和 MCP 工具检测到破坏性变更
按优先级顺序应用升级，失败时回滚
升级后构建和类型检查通过
返回报告，包含主/次/补丁版本计数、迁移和构建状态

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

🇺🇸English

Paths: File paths (shared/, references/, ../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root. If shared/ is missing, fetch files via WebFetch from https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}.

ln-821-npm-upgrader

Type: L3 Worker Category: 8XX Optimization Parent: ln-820-dependency-optimization-coordinator

Upgrades Node.js dependencies using npm, yarn, or pnpm with automatic breaking change detection and migration.

Overview

Aspect	Details
Input	Project path, package manager type
Output	Updated package.json, lock file, migration report
Supports	npm, yarn (classic & berry), pnpm

Workflow

Phases: Pre-flight → Analyze → Security Audit → Check Outdated → Identify Breaking → Apply Upgrades → Apply Migrations → Verify Build → Report

Phase 0: Pre-flight Checks

Check	Required	Action if Missing
Lock file (package-lock.json, yarn.lock, pnpm-lock.yaml)	Yes	Warn and run `npm install` first
package.json	Yes	Block upgrade
Git clean state	Yes	Block (need clean baseline for revert)

Workers assume coordinator (ln-820) already verified git state and created backup.

Worktree & Branch Isolation

MANDATORY READ: Load shared/references/git_worktree_fallback.md — use ln-821 row.

Phase 1: Analyze Dependencies

Read package.json and categorize dependencies for upgrade priority.

Dependency Categories

Category	Examples	Priority
framework	react, vue, angular	2 (after peer deps)
build	vite, webpack, esbuild	3
ui	@radix-ui/*, tailwindcss	4
state	@tanstack/react-query, zustand	5
utils	lodash, date-fns	6
dev	eslint, prettier, typescript	7
peer	@types/*, typescript	1 (first)

Phase 2: Security Audit

Commands

Manager	Command
npm	`npm audit --audit-level=high`
yarn	`yarn audit --level high`
pnpm	`pnpm audit --audit-level high`

Actions

Severity	Action
Critical	Block upgrade, report
High	Warn, continue
Moderate/Low	Log only

Phase 3: Check Outdated

Commands

Manager	Command
npm	`npm outdated --json`
yarn	`yarn outdated --json`
pnpm	`pnpm outdated --json`

Phase 4: Identify Breaking Changes

Detection

MANDATORY READ: Load breaking_changes_patterns.md for full patterns.

Compare current vs latest major versions
Check breaking_changes_patterns.md for known patterns
Query Context7/Ref for migration guides

Common Breaking Changes

Package	Breaking Version	Key Changes
react	18 → 19	JSX Transform, ref as prop
vite	5 → 6	ESM only, Node 18+
eslint	8 → 9	Flat config required
tailwindcss	3 → 4	CSS-based config
typescript	5.4 → 5.5+	Stricter inference

Phase 5: Apply Upgrades

Upgrade Order

Peer dependencies (TypeScript, @types/*)
Framework packages (React, Vue core)
Build tools (Vite, webpack)
UI libraries (after framework)
Utilities (lodash, date-fns)
Dev dependencies (testing, linting)

Commands

Manager	Command
npm	`npm install <package>@latest --save`
yarn	`yarn add <package>@latest`
pnpm	`pnpm add <package>@latest`

Peer Dependency Conflicts

Situation	Solution
ERESOLVE error	`npm install --legacy-peer-deps`
Still fails	`npm install --force` (last resort)

MCP Tools for Migration Search

Priority Order (Fallback Strategy)

Priority	Tool	When to Use
1	mcp__context7__query-docs	First choice for library docs
2	mcp__Ref__ref_search_documentation	Official docs and GitHub
3	WebSearch	Latest info, community solutions

Context7 Usage

Step	Tool	Parameters
1. Find library	mcp__context7__resolve-library-id	libraryName: "react", query: "migration guide"
2. Query docs	mcp__context7__query-docs	libraryId: "/facebook/react", query: "react 18 to 19 migration"

MCP Ref Usage

Action	Tool	Query Example
Search	mcp__Ref__ref_search_documentation	"react 19 migration guide breaking changes"
Read	mcp__Ref__ref_read_url	URL from search results

WebSearch Fallback

Use when Context7/Ref return no results:

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

Phase 6: Apply Migrations

Process

Use MCP tools (see section above) to find migration guide
Apply automated code transforms via Edit tool
Log manual migration steps for user

Do NOT apply hardcoded migrations. Always fetch current guides via MCP tools.

Phase 7: Verify Build

Commands

Check	Command
TypeScript	`npm run check` or `npx tsc --noEmit`
Build	`npm run build`
Tests	`npm test` (if available)

On Failure

Identify failing package from error
Search Context7/Ref for fix
If unresolved: rollback package, continue with others

Phase 8: Report Results

Report Schema

Field	Description
project	Project path
packageManager	npm, yarn, or pnpm
duration	Total time
upgrades.major[]	Breaking changes applied
upgrades.minor[]	Feature updates
upgrades.patch[]	Bug fixes
migrations[]	Applied migrations
skipped[]	Already latest
buildVerification	PASSED or FAILED
warnings[]	Non-blocking issues

Configuration

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

Error Handling

Error	Cause	Solution
ERESOLVE	Peer dep conflict	--legacy-peer-deps
ENOENT	Missing lock file	npm install first
Build fail	Breaking change	Apply migration via Context7
Type errors	Version mismatch	Update @types/*

Rollback

Restore package.json and lock file from git, then run clean install to restore previous state.

References

Definition of Done

Lock file and package.json verified present
Dependencies categorized and prioritized (peer deps first)
Security audit completed (critical blocks upgrade)
Outdated packages identified via npm/yarn/pnpm outdated
Breaking changes detected via breaking_changes_patterns.md and MCP tools
Upgrades applied in priority order with rollback on failure
Build and type checks pass after upgrades
Report returned with major/minor/patch counts, migrations, and build status

Version: 1.1.0 Last Updated: 2026-01-10

Weekly Installs

Repository

levnikolaevich/…e-skills

GitHub Stars

253

First Seen

Mar 8, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

cursor74

gemini-cli72

github-copilot72

codex72

amp72

cline72

Node.js依赖自动升级工具 - npm/yarn/pnpm包管理器智能升级与破坏性变更检测

🇨🇳中文介绍

ln-821-npm-upgrader

概述

相关 Skills

工作流程

阶段 0：预检

工作树与分支隔离

阶段 1：分析依赖项

依赖项类别

阶段 2：安全审计

命令

操作

阶段 3：检查过时依赖

命令

阶段 4：识别破坏性变更

检测

常见的破坏性变更

阶段 5：应用升级

升级顺序

命令

对等依赖冲突

用于迁移搜索的 MCP 工具

优先级顺序（回退策略）

Context7 使用

MCP Ref 使用

WebSearch 回退

阶段 6：应用迁移

流程

阶段 7：验证构建

命令

失败时

阶段 8：报告结果

报告模式

配置

错误处理

回滚

参考

完成定义

🇺🇸English

ln-821-npm-upgrader

Overview

Workflow

Phase 0: Pre-flight Checks

Worktree & Branch Isolation

Phase 1: Analyze Dependencies

Dependency Categories

Phase 2: Security Audit

Commands

Actions

Phase 3: Check Outdated

Commands

Phase 4: Identify Breaking Changes

Detection

Common Breaking Changes

Phase 5: Apply Upgrades

Upgrade Order

Commands

Peer Dependency Conflicts

MCP Tools for Migration Search

Priority Order (Fallback Strategy)

Context7 Usage

MCP Ref Usage

WebSearch Fallback

Phase 6: Apply Migrations

Process

Phase 7: Verify Build

Commands

On Failure

Phase 8: Report Results

Report Schema

Configuration

Error Handling

Rollback

References

Definition of Done

最新 Skills