ln-710-dependency-upgrader

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

ln-710-dependency-upgrader

类型： L2 领域协调器
类别： 7XX 项目引导
父级： ln-700-project-bootstrap

通过检测包管理器并委派给相应的 L3 工作器来协调依赖升级。

---

概述

方面	详情
输入	来自 ln-700 的已检测技术栈
输出	所有依赖均升级至最新兼容版本
工作器	ln-711（npm）、ln-712（nuget）、ln-713（pip）

---

工作流

查看 diagram.html 了解可视化工作流。

阶段： 预检 → 检测 → 安全审计 → 委派 → 收集 → 验证 → 报告

---

阶段 0：预检

开始升级前验证项目状态。

检查项	方法	阻止升级的条件
未提交的更改	git status --porcelain	输出非空
创建备份分支	git checkout -b upgrade-backup-{timestamp}	失败
锁文件存在	检查锁文件	缺失（仅警告）

如果存在未提交的更改，则跳过升级。用户必须先提交或暂存更改。

---

阶段 1：检测包管理器

检测规则

包管理器	指示文件	工作器
npm	package.json + package-lock.json	ln-711
yarn	package.json + yarn.lock	ln-711
pnpm	package.json + pnpm-lock.yaml	ln-711
nuget	*.csproj 文件	ln-712
pip	requirements.txt	ln-713
poetry	pyproject.toml + poetry.lock	ln-713
pipenv	Pipfile + Pipfile.lock	ln-713

---

阶段 2：安全审计（预检）

安全检查

包管理器	命令	阻止升级
npm	npm audit --audit-level=high	仅限严重问题
pip	pip-audit --json	仅限严重问题
nuget	dotnet list package --vulnerable	仅限严重问题

发布时长检查

选项	默认值	说明
minimumReleaseAge	14 days	跳过发布不足 14 days 的包
ignoreReleaseAge	false	紧急安全补丁时覆盖此设置

按照 Renovate 最佳实践：等待 14 days 可让软件包注册中心有时间撤下恶意包。

---

阶段 3：委派给工作器

重要： 所有委派都使用 Task 工具，并将 subagent_type: "general-purpose" 用于上下文隔离。

提示词模板：

Task(description: "Upgrade deps via ln-71X",
     prompt: "Execute ln-71X-{worker}. Read skill from ln-71X-{worker}/SKILL.md. Context: {delegationContext}",
     subagent_type: "general-purpose")

反模式：

• ❌ 不使用 Task 封装而直接调用 Skill 工具
• ❌ 绕过子 Agent 上下文隔离执行任何操作

委派上下文

每个工作器都会收到标准化的上下文：

字段	类型	说明
projectPath	string	项目的绝对路径
packageManager	enum	npm、yarn、pnpm、nuget、pip、poetry、pipenv
options.upgradeType	enum	major、minor、patch
options.allowBreaking	bool	是否允许破坏性更改
options.testAfterUpgrade	bool	升级后是否运行测试

工作器选择

包管理器	工作器	说明
npm、yarn、pnpm	ln-711-npm-upgrader	处理所有 Node.js 项目
nuget	ln-712-nuget-upgrader	处理 .NET 项目
pip、poetry、pipenv	ln-713-pip-upgrader	处理所有 Python 项目

---

阶段 4：收集结果

结果架构

字段	类型	说明
status	enum	成功、部分成功、失败
upgrades[]	array	已升级包的列表
upgrades[].package	string	包名称
upgrades[].from	string	先前版本
upgrades[].to	string	新版本
upgrades[].breaking	bool	是否为破坏性更改
warnings[]	array	非阻塞警告
errors[]	array	阻塞性错误

---

阶段 5：验证构建

各技术栈的构建命令

技术栈	命令
Node.js	npm run build or yarn build
.NET	dotnet build --configuration Release
Python	pytest or python -m pytest

构建失败时

1. 根据错误识别失败的软件包
2. 在 Context7/Ref 中搜索迁移指南
3. 应用已知修复方法
4. 如果仍然失败：回滚软件包，记录警告

---

第 6 阶段：报告摘要

报告架构

字段	类型	描述
totalPackages	int	分析的软件包总数
upgraded	int	成功升级的数量
skipped	int	已是最新版本的数量
failed	int	已回滚的数量
breakingChanges	int	主版本升级的数量
buildVerified	bool	升级后构建是否通过
duration	string	总耗时

---

配置

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

  # Breaking changes
  allowBreaking: true
  autoMigrate: true           # Apply known migrations

  # Security
  auditLevel: high            # none | low | moderate | high | critical
  minimumReleaseAge: 14       # days, 0 to disable
  blockOnVulnerability: true

  # Scope
  skipDev: false              # Include devDependencies
  skipOptional: true          # Skip optional deps

  # Verification
  testAfterUpgrade: true
  buildAfterUpgrade: true

  # Rollback
  rollbackOnFailure: true

---

错误处理

可恢复的错误

错误	恢复措施
对等依赖冲突	尝试 --legacy-peer-deps
构建失败	回滚软件包，继续执行
网络超时	重试 3 次

致命错误

错误	操作
未找到软件包管理器	跳过此步骤
所有构建均失败	向父级报告，建议手动检查

---

参考资料

• breaking_changes_patterns.md
• security_audit_guide.md

---

完成标准

• 通过预检（Git 状态干净，已创建备份分支）
• 根据指示文件检测到所有软件包管理器
• 按软件包管理器完成安全审计（严重漏洞会阻止升级）
• 通过 Task 工具分派工作进程，并隔离上下文
• 收集工作进程结果及升级、跳过和失败的数量
• 应用所有升级后验证构建
• 生成包含 totalPackages、upgraded、skipped、failed、buildVerified 的摘要报告

---

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