ln-822-nuget-upgrader

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

ln-822-nuget-upgrader

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

升级 .NET NuGet 包，自动检测破坏性变更并执行迁移。

---

概述

方面	详情
输入	解决方案或项目路径，以及升级策略
输出	更新后的 .csproj 文件和机器可读的依赖项升级摘要
支持	.NET 6、7、8、9、10

---

工作流

阶段： 预检 -> 查找项目 -> 安全审计 -> 检查过时包 -> 识别破坏性变更 -> 应用升级 -> 还原并构建 -> 报告

---

阶段 0：预检

检查	必需	缺失时的操作
.csproj 文件	是	阻止升级
.sln 文件	否	回退到递归查找项目
dotnet CLI	是	阻止升级
工作区基线安全	是	在托管运行中，协调器已做好准备；在独立运行中，在本地保护回滚能力

运行时协调

托管运行会从 ln-820 获取确定性的 runId 和准确的 summaryArtifactPath。 独立运行仍受支持；如果省略运行时参数，则在返回前生成一个作用域为该次独立运行的制品。

---

阶段 1：查找项目

方法	命令
查找 .csproj 文件	Get-ChildItem -Recurse -Filter *.csproj
读取解决方案成员	dotnet sln list

---

阶段 2：安全审计

检查	命令
易受攻击的包	dotnet list package --vulnerable
过时的包	dotnet list package --outdated

操作：

严重程度	操作
严重	阻止并报告
高	警告并继续
中/低	仅记录

---

阶段 3：检查过时包

步骤	命令
安装辅助工具	dotnet tool install --global dotnet-outdated-tool
检测过时的包	dotnet outdated --output json

---

阶段 4：识别破坏性变更

检测流程：

1. 比较当前版本与最新主版本。
2. 检查 breaking_changes_patterns.md。
3. 更改代码前，使用 MCP 工具查找迁移指南。

常见示例：

包	含破坏性变更的版本	主要变更
Microsoft.EntityFrameworkCore	8 -> 9	查询和迁移变更
Serilog.AspNetCore	7 -> 8	配置更新
Swashbuckle.AspNetCore	6 -> 7	Minimal API 集成变更

---

用于搜索迁移信息的 MCP 工具

优先级	工具	使用时机
1	mcp__context7__query-docs	首选，用于查询库文档
2	mcp__Ref__ref_search_documentation	官方 Microsoft 文档
3	WebSearch	最新信息和社区修复方案

应用迁移前，使用工具链确认迁移方案。

---

阶段 5：应用升级

优先级顺序：

1. SDK 或运行时包
2. 框架包
3. EF Core
4. 日志记录包
5. 其他所有包

操作	命令
更新单个包	dotnet add package <name> --version <ver>
更新多个包	dotnet outdated --upgrade

---

阶段 6：还原并构建

步骤	命令
还原	dotnet restore
构建	dotnet build --configuration Release
测试	dotnet test

失败时：

1. 找出失败的包。
2. 在 Context7 或 Ref 中搜索迁移指南。
3. 如果仍未解决，则回滚该包并继续。

---

阶段 7：报告结果

字段	描述
solution	解决方案路径
projects[]	已更新的项目
duration	总用时
upgrades[]	已应用的升级
verification	还原/构建/测试结论
warnings[]	不阻止流程的问题
artifact_path	持久化工作器报告路径（如已写入）

---

配置

Options:
  upgradeType: major          # major | minor | patch
  auditLevel: high
  minimumReleaseAge: 14
  includePrerelease: false
  targetFramework: net10.0
  runTests: true
  runBuild: true

---

错误处理

错误	原因	解决方案
CS0246	缺少类型	搜索替代 API
NU1605	检测到降级	检查包约束
构建失败	重大变更	应用迁移指南，或回滚导致问题的包

---

参考资料

• breaking_changes_patterns.md
• dotnet_version_matrix.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-822--{identifier}.json

监控（2.1.98+）： 对于预计超过 30 秒的还原/构建/测试命令，使用 Monitor。备用方案：Bash(run_in_background=true)。

完成标准

• 已发现所有目标 .csproj 文件
• 已完成 NuGet 依赖项的安全审计
• 已识别过期包
• 已结合模式和当前文档检查重大变更
• 已按安全顺序应用升级，并在失败时回滚
• dotnet restore、dotnet build 和所需测试均成功
• 已将 dependency-worker 摘要产物写入托管或独立路径

---

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