Back to Details

ln-821-npm-upgrader

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
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.
路径： 文件路径（
shared/
、
references/
、
../ln-*
）是相对于技能仓库根目录的。如果在当前工作目录（CWD）中未找到，请定位到本SKILL.md所在目录，然后向上一级找到仓库根目录。

ln-821-npm-upgrader

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.
类型： L3 Worker 分类： 8XX 优化 父级： ln-820-dependency-optimization-coordinator
使用npm、yarn或pnpm升级Node.js依赖，具备自动破坏性变更检测与迁移功能。

Overview

概述

AspectDetails
InputProject path, package manager type
OutputUpdated package.json, lock file, migration report
Supportsnpm, yarn (classic & berry), pnpm
方面详情
输入项目路径、包管理器类型
输出更新后的package.json、锁文件、迁移报告
支持npm、yarn（经典版&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

阶段0：预检查

CheckRequiredAction if Missing
Lock file (package-lock.json, yarn.lock, pnpm-lock.yaml)YesWarn and run 
npm install
first
package.jsonYesBlock upgrade
Git clean stateYesBlock (need clean baseline for revert)
Workers assume coordinator (ln-820) already verified git state and created backup.
检查项是否必需缺失时的操作
锁文件（package-lock.json、yarn.lock、pnpm-lock.yaml）是发出警告并先运行
npm install
package.json是阻止升级
Git干净状态是阻止升级（需要干净的基线以便回滚）
Worker假设协调器（ln-820）已验证Git状态并创建备份。

Worktree & Branch Isolation

工作树与分支隔离

MANDATORY READ: Load 
shared/references/git_worktree_fallback.md
— use ln-821 row.
必读： 加载
shared/references/git_worktree_fallback.md
— 使用ln-821对应的行。

Phase 1: Analyze Dependencies

阶段1：分析依赖

Read package.json and categorize dependencies for upgrade priority.
读取package.json并对依赖进行分类以确定升级优先级。

Dependency Categories

依赖分类

CategoryExamplesPriority
frameworkreact, vue, angular2 (after peer deps)
buildvite, webpack, esbuild3
ui@radix-ui/*, tailwindcss4
state@tanstack/react-query, zustand5
utilslodash, date-fns6
deveslint, prettier, typescript7
peer@types/*, typescript1 (first)
类别示例优先级
框架react、vue、angular2（在Peer依赖之后）
构建工具vite、webpack、esbuild3
UI组件库@radix-ui/*、tailwindcss4
状态管理@tanstack/react-query、zustand5
工具库lodash、date-fns6
开发依赖eslint、prettier、typescript7
Peer依赖@types/*、typescript1（最先）

Phase 2: Security Audit

阶段2：安全审计

Commands

命令

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

Actions

操作

SeverityAction
CriticalBlock upgrade, report
HighWarn, continue
Moderate/LowLog only
严重程度操作
严重（Critical）阻止升级并生成报告
高（High）发出警告并继续
中/低（Moderate/Low）仅记录

Phase 3: Check Outdated

阶段3：检查过时依赖

Commands

命令

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

Phase 4: Identify Breaking Changes

阶段4：识别破坏性变更

Detection

检测方式

MANDATORY READ: Load breaking_changes_patterns.md for full patterns.
  1. Compare current vs latest major versions
  2. Check breaking_changes_patterns.md for known patterns
  3. Query Context7/Ref for migration guides
必读： 加载breaking_changes_patterns.md查看完整模式。
  1. 比较当前版本与最新主版本
  2. 检查breaking_changes_patterns.md中的已知模式
  3. 查询Context7/Ref获取迁移指南

Common Breaking Changes

常见破坏性变更

PackageBreaking VersionKey Changes
react18 → 19JSX Transform, ref as prop
vite5 → 6ESM only, Node 18+
eslint8 → 9Flat config required
tailwindcss3 → 4CSS-based config
typescript5.4 → 5.5+Stricter inference
包破坏性版本主要变更
react18 → 19JSX Transform、ref作为属性
vite5 → 6仅支持ESM、Node 18+
eslint8 → 9需要Flat配置
tailwindcss3 → 4基于CSS的配置
typescript5.4 → 5.5+更严格的类型推断

Phase 5: Apply Upgrades

阶段5：应用升级

Upgrade Order

升级顺序

  1. Peer dependencies (TypeScript, @types/*)
  2. Framework packages (React, Vue core)
  3. Build tools (Vite, webpack)
  4. UI libraries (after framework)
  5. Utilities (lodash, date-fns)
  6. Dev dependencies (testing, linting)
  1. Peer依赖（TypeScript、@types/*）
  2. 框架包（React、Vue核心）
  3. 构建工具（Vite、webpack）
  4. UI组件库（在框架升级之后）
  5. 工具库（lodash、date-fns）
  6. 开发依赖（测试、代码检查工具）

Commands

命令

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

Peer Dependency Conflicts

Peer依赖冲突解决

SituationSolution
ERESOLVE error
npm install --legacy-peer-deps
Still fails
npm install --force
(last resort)
情况解决方案
ERESOLVE错误
npm install --legacy-peer-deps
仍失败
npm install --force
（最后手段）

MCP Tools for Migration Search

用于迁移搜索的MCP工具

Priority Order (Fallback Strategy)

优先级顺序（降级策略）

PriorityToolWhen to Use
1mcp__context7__query-docsFirst choice for library docs
2mcp__Ref__ref_search_documentationOfficial docs and GitHub
3WebSearchLatest info, community solutions
优先级工具使用场景
1mcp__context7__query-docs库文档的首选工具
2mcp__Ref__ref_search_documentation官方文档与GitHub搜索
3WebSearch获取最新信息、社区解决方案

Context7 Usage

Context7 使用方法

StepToolParameters
1. Find librarymcp__context7__resolve-library-idlibraryName: "react", query: "migration guide"
2. Query docsmcp__context7__query-docslibraryId: "/facebook/react", query: "react 18 to 19 migration"
步骤工具参数
1. 查找库mcp__context7__resolve-library-idlibraryName: "react", query: "migration guide"
2. 查询文档mcp__context7__query-docslibraryId: "/facebook/react", query: "react 18 to 19 migration"

MCP Ref Usage

MCP Ref 使用方法

ActionToolQuery Example
Searchmcp__Ref__ref_search_documentation"react 19 migration guide breaking changes"
Readmcp__Ref__ref_read_urlURL from search results
操作工具查询示例
搜索mcp__Ref__ref_search_documentation"react 19 migration guide breaking changes"
读取mcp__Ref__ref_read_url搜索结果中的URL

WebSearch Fallback

WebSearch 降级方案

Use when Context7/Ref return no results:
  • "<package> <version> breaking changes migration {current_year}"
  • "<package> <error message> fix stackoverflow"
当Context7/Ref无结果时使用：
  • "<package> <version> breaking changes migration {current_year}"
  • "<package> <error message> fix stackoverflow"

Phase 6: Apply Migrations

阶段6：应用迁移

Process

流程

  1. Use MCP tools (see section above) to find migration guide
  2. Apply automated code transforms via Edit tool
  3. Log manual migration steps for user
Do NOT apply hardcoded migrations. Always fetch current guides via MCP tools.
  1. 使用MCP工具（见上文）查找迁移指南
  2. 通过Edit工具应用自动化代码转换
  3. 记录需要用户手动执行的迁移步骤
请勿应用硬编码的迁移逻辑。始终通过MCP工具获取最新指南。

Phase 7: Verify Build

阶段7：验证构建

Commands

命令

CheckCommand
TypeScript
npm run check
or 
npx tsc --noEmit
Build
npm run build
Tests
npm test
(if available)
检查项命令
TypeScript 检查
npm run check
或 
npx tsc --noEmit
构建
npm run build
测试
npm test
（若可用）

On Failure

失败处理

  1. Identify failing package from error
  2. Search Context7/Ref for fix
  3. If unresolved: rollback package, continue with others
  1. 从错误信息中识别失败的包
  2. 搜索Context7/Ref获取修复方案
  3. 若无法解决：回滚该包，继续处理其他包

Phase 8: Report Results

阶段8：生成结果报告

Report Schema

报告结构

FieldDescription
projectProject path
packageManagernpm, yarn, or pnpm
durationTotal time
upgrades.major[]Breaking changes applied
upgrades.minor[]Feature updates
upgrades.patch[]Bug fixes
migrations[]Applied migrations
skipped[]Already latest
buildVerificationPASSED or FAILED
warnings[]Non-blocking issues
字段描述
project项目路径
packageManagernpm、yarn或pnpm
duration总耗时
upgrades.major[]已应用的破坏性变更
upgrades.minor[]功能更新
upgrades.patch[]Bug修复
migrations[]已应用的迁移
skipped[]已是最新版本的依赖
buildVerification通过（PASSED）或失败（FAILED）
warnings[]非阻塞问题

Configuration

配置

yaml
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
yaml
Options:
  # 升级范围
  upgradeType: major          # major | minor | patch

  # 破坏性变更
  allowBreaking: true
  autoMigrate: true
  queryMigrationGuides: true  # 使用Context7/Ref

  # 安全设置
  auditLevel: high            # none | low | moderate | high | critical
  minimumReleaseAge: 14       # 天数

  # Peer依赖
  legacyPeerDeps: false
  force: false

  # 验证设置
  runBuild: true
  runTests: false
  runTypeCheck: true

  # 回滚设置
  createBackup: true
  rollbackOnFailure: true

Error Handling

错误处理

ErrorCauseSolution
ERESOLVEPeer dep conflict--legacy-peer-deps
ENOENTMissing lock filenpm install first
Build failBreaking changeApply migration via Context7
Type errorsVersion mismatchUpdate @types/*
错误原因解决方案
ERESOLVEPeer依赖冲突使用
--legacy-peer-deps
ENOENT缺失锁文件先运行
npm install
构建失败破坏性变更通过Context7应用迁移
类型错误版本不匹配更新@types/*

Rollback

回滚

Restore package.json and lock file from git, then run clean install to restore previous state.
从Git恢复package.json和锁文件，然后执行干净安装以恢复之前的状态。

References

参考资料

  • breaking_changes_patterns.md
  • npm_peer_resolution.md
  • breaking_changes_patterns.md
  • npm_peer_resolution.md

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
  • 已验证锁文件和package.json存在
  • 依赖已分类并确定优先级（Peer依赖优先）
  • 已完成安全审计（严重问题会阻止升级）
  • 通过
    npm/yarn/pnpm outdated
    识别出过时依赖
  • 通过breaking_changes_patterns.md和MCP工具检测到破坏性变更
  • 已按优先级顺序应用升级，失败时可回滚
  • 升级后构建和类型检查通过
  • 已返回包含主/次/补丁版本升级数量、迁移情况和构建状态的报告
版本： 1.1.0 最后更新时间： 2026-01-10