ln-710-dependency-upgrader

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ln-710-dependency-upgrader

Type: L2 Domain Coordinator Category: 7XX Project Bootstrap Parent: ln-700-project-bootstrap

Coordinates dependency upgrades by detecting package managers and delegating to appropriate L3 workers.

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

通过检测包管理器并将任务委派给相应的L3工作器，统筹依赖项升级工作。

Overview

概述

Aspect	Details
Input	Detected stack from ln-700
Output	All dependencies upgraded to latest compatible versions
Workers	ln-711 (npm), ln-712 (nuget), ln-713 (pip)

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

Workflow

工作流

See diagram.html for visual workflow.

Phases: Pre-flight → Detect → Security Audit → Delegate → Collect → Verify → Report

查看diagram.html获取可视化工作流。

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

Phase 0: Pre-flight Checks

阶段0：预检查

Verify project state before starting upgrade.

Check	Method	Block if
Uncommitted changes	`git status --porcelain`	Non-empty output
Create backup branch	`git checkout -b upgrade-backup-{timestamp}`	Failure
Lock file exists	Check for lock file	Missing (warn only)

Skip upgrade if uncommitted changes exist. User must commit or stash first.

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

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

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

Phase 1: Detect Package Managers

阶段1：检测包管理器

Detection Rules

检测规则

Package Manager	Indicator Files	Worker
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 files	ln-712
pip	requirements.txt	ln-713
poetry	pyproject.toml + poetry.lock	ln-713
pipenv	Pipfile + Pipfile.lock	ln-713

包管理器	标识文件	工作器
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 files	ln-712
pip	requirements.txt	ln-713
poetry	pyproject.toml + poetry.lock	ln-713
pipenv	Pipfile + Pipfile.lock	ln-713

Phase 2: Security Audit (Pre-flight)

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

Security Checks

安全检查

Package Manager	Command	Block Upgrade
npm	`npm audit --audit-level=high`	Critical only
pip	`pip-audit --json`	Critical only
nuget	`dotnet list package --vulnerable`	Critical only

包管理器	命令	阻塞升级条件
npm	`npm audit --audit-level=high`	仅当存在严重漏洞时
pip	`pip-audit --json`	仅当存在严重漏洞时
nuget	`dotnet list package --vulnerable`	仅当存在严重漏洞时

Release Age Check

版本发布时长检查

Option	Default	Description
minimumReleaseAge	14 days	Skip packages released < 14 days ago
ignoreReleaseAge	false	Override for urgent security patches

Per Renovate best practices: waiting 14 days gives registries time to pull malicious packages.

选项	默认值	描述
minimumReleaseAge	14 days	跳过发布时长不足14天的包
ignoreReleaseAge	false	覆盖默认设置以适配紧急安全补丁

遵循Renovate最佳实践：等待14天可让注册表有时间移除恶意包。

Phase 3: Delegate to Workers

阶段3：委派至工作器

CRITICAL: All delegations use Task tool with
subagent_type: "general-purpose"
for context isolation.

Prompt template:

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")

Anti-Patterns:

❌ Direct Skill tool invocation without Task wrapper
❌ Any execution bypassing subagent context isolation

重要提示： 所有委派任务均使用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工具
❌ 任何绕过子代理上下文隔离的执行操作

Delegation Context

委派上下文

Each worker receives standardized context:

Field	Type	Description
projectPath	string	Absolute path to project
packageManager	enum	npm, yarn, pnpm, nuget, pip, poetry, pipenv
options.upgradeType	enum	major, minor, patch
options.allowBreaking	bool	Allow breaking changes
options.testAfterUpgrade	bool	Run tests after upgrade

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

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

Worker Selection

工作器选择

Package Manager	Worker	Notes
npm, yarn, pnpm	ln-711-npm-upgrader	Handles all Node.js
nuget	ln-712-nuget-upgrader	Handles .NET projects
pip, poetry, pipenv	ln-713-pip-upgrader	Handles all Python

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

Phase 4: Collect Results

阶段4：收集结果

Result Schema

结果Schema

Field	Type	Description
status	enum	success, partial, failed
upgrades[]	array	List of upgraded packages
upgrades[].package	string	Package name
upgrades[].from	string	Previous version
upgrades[].to	string	New version
upgrades[].breaking	bool	Is breaking change
warnings[]	array	Non-blocking warnings
errors[]	array	Blocking errors

字段	类型	描述
status	enum	success, partial, failed
upgrades[]	array	已升级包的列表
upgrades[].package	string	包名称
upgrades[].from	string	旧版本
upgrades[].to	string	新版本
upgrades[].breaking	bool	是否为破坏性变更
warnings[]	array	非阻塞警告
errors[]	array	阻塞错误

Phase 5: Verify Build

阶段5：验证构建

Build Commands by Stack

按技术栈划分的构建命令

Stack	Command
Node.js	`npm run build` or `yarn build`
.NET	`dotnet build --configuration Release`
Python	`pytest` or `python -m pytest`

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

On Build Failure

构建失败时的处理

Identify failing package from error
Search Context7/Ref for migration guide
Apply known fixes
If still fails: rollback package, log warning

从错误信息中定位失败的包
在Context7/Ref中搜索迁移指南
应用已知修复方案
若仍失败：回滚该包，记录警告

Phase 6: Report Summary

阶段6：生成报告摘要

Report Schema

报告Schema

Field	Type	Description
totalPackages	int	Total packages analyzed
upgraded	int	Successfully upgraded
skipped	int	Already latest
failed	int	Rolled back
breakingChanges	int	Major version upgrades
buildVerified	bool	Build passed after upgrade
duration	string	Total time

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

Configuration

配置

yaml

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

yaml

Options:
  # 升级范围
  upgradeType: major          # major | minor | patch

  # 破坏性变更
  allowBreaking: true
  autoMigrate: true           # 应用已知迁移方案

  # 安全设置
  auditLevel: high            # none | low | moderate | high | critical
  minimumReleaseAge: 14       # 天数，设为0则禁用
  blockOnVulnerability: true

  # 范围设置
  skipDev: false              # 包含devDependencies
  skipOptional: true          # 跳过可选依赖

  # 验证设置
  testAfterUpgrade: true
  buildAfterUpgrade: true

  # 回滚设置
  rollbackOnFailure: true

Error Handling

错误处理

Recoverable Errors

可恢复错误

Error	Recovery
Peer dependency conflict	Try --legacy-peer-deps
Build failure	Rollback package, continue
Network timeout	Retry 3 times

错误类型	恢复方案
对等依赖冲突	尝试使用--legacy-peer-deps
构建失败	回滚该包，继续执行
网络超时	重试3次

Fatal Errors

致命错误

Error	Action
No package managers found	Skip this step
All builds fail	Report to parent, suggest manual review

错误类型	处理动作
未检测到任何包管理器	跳过此步骤
所有构建均失败	上报至父级，建议手动检查

References

参考文档

breaking_changes_patterns.md
security_audit_guide.md

Version: 1.1.0 Last Updated: 2026-01-10

breaking_changes_patterns.md
security_audit_guide.md

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