排查GitHub Copilot更新问题

本文按类别介绍在使用 GitHub Copilot 为 .NET 进行现代化时可能遇到的常见问题。 每个条目都遵循问题、原因和解决方案格式，以便快速查找和解决问题。

工作流问题

这些问题与方案发现、恢复工作和任务状态有关。

代理说“找不到方案”

Cause：代理无法将工作区识别为.NET项目。

Solution:

1. 确保工作区根目录包含.sln、.csproj或.vbproj文件。
2. 询问代理： “你使用的是哪种解决方案或项目文件？
3. 如果解决方案或项目文件位于子目录中，请以工作区根目录的形式打开该目录，或将代理显式指向该文件。

代理无法恢复以前的工作

原因： 代理 .github/upgrades/ 存储其所有状态的文件夹丢失或损坏。

Solution:

1. .github/upgrades/检查存储库根目录中是否存在该文件夹。
2. 如果意外删除了文件夹，请重新开始情境。 代理如果没有其状态文件，则无法恢复。
3. 如果文件夹存在，但文件似乎已损坏，请让代理 “重新评估和重新计划” 以重新生成它们。

停滞在进行中状态的任务

原因：上一个会话在代理进行任务中途时结束的。

Solution:

1. 在大多数情况下，代理会自动检测过时的任务。 告知代理 “继续” 或 “重启当前任务”。
2. 如果停滞状态仍然存在，请告知代理 “将当前任务标记为挂起并重启” 或 “重新评估并继续执行上一个已完成的步骤”。
3. 检查相应的 progress-details.md 文件，了解上一个会话停止的位置。

代理不断建议错误的方案

原因： 代理的分析识别出了未预料到的项目特点，并推测出了不同于您预期的情形。

Solution:

明确所需内容。 而不是 “升级我的项目”， 例如：

• “我想升级到 .NET 10.”
• “我想从 Newtonsoft.Json 升级到 System.Text.Json。
• “将项目转换为 SDK 样式格式。”

将情景首选项添加到 scenario-instructions.md 以防止将来的不匹配。

生成和编译问题

这些问题与生成失败、NuGet 还原问题和代码生成错误有关。

代理更改后构建失败

原因： 升级可以引入 中断性 API 更改、缺少的包或不兼容的代码模式。

Solution:

1. 告知代理失败情况。 代理会自动分析错误。
2. 如果代理无法解决问题，请还原最后一次提交（git revert HEAD），并要求代理尝试其他方法。
3. 对于复杂的故障，请检查 execution-log.md 以了解代理程序进行了哪些更改以及更改的顺序。

NuGet 还原失败

原因： 与目标框架不兼容或专用 NuGet 源身份验证失败。

Solution:

• 对于私有源： 在开始升级之前为源进行身份验证。
• 对于不兼容的包： 告知代理哪个包有问题。 代理可以搜索兼容版本或建议备用包。
• 对于源连接问题： 验证是否可以手动运行 dotnet restore 。 首先修复任何馈送问题，然后让代理重试。

代理生成不编译的代码

原因： AI 生成的代码可能包含错误，尤其是在边缘情况或不常见的 API 模式中。

Solution:

1. 代理会自动检测编译错误。 如果代理处于困境，请手动提供指导或修复代码，并告知代理继续。
2. 如果代理在多次尝试后难以处理特定修复，请手动编辑代码并告诉代理： “我修复了MyClass.cs中的编译错误，请标记此任务完成。
3. 当同一问题出现在其他位置时，代理会从手动修复中学习并应用类似的模式。

Git 问题

代理无法创建分支

原因： 工作树中有未提交的更改、分支命名冲突，或 Git 没有在工作区中初始化。

Solution:

1. 在开始方案之前提交或保存挂起的更改。
2. 通过在工作区根目录中运行 git status 来验证 Git 是否已初始化。
3. 如果已存在具有代理预期名称的分支，请删除现有分支或要求代理使用不同的分支名称。

撤消所有代理更改

原因： 升级未按计划进行，你希望从头开始。

Solution:

1. 使用 git checkout main（或者基分支）切换回原始分支。
2. 代理的工作分支包含与主分支隔离的所有更改。
3. 若要完全删除代理的分支，请运行 git branch -D <agent-branch-name>。
4. 若要保留一些更改，请使用git cherry-pick <commit-hash>挑选特定的提交。

性能问题

这些问题与升级速度和评估持续时间有关。

代理速度缓慢或需要很长时间

原因： 具有许多项目、复杂依赖项关系图或许多中断性变更的大型解决方案自然需要更长的时间。

Solution:

对于大型解决方案（50 多个项目），请考虑批量升级。 将相关项目分组并将它们一起升级。

评估需要很长时间

原因： 评估将分析每个项目的依赖项、NuGet 包、目标框架和适用的中断性变更。 对于大型解决方案，评估自然需要更长的时间。

Solution:

1. 大型解决方案的评估时间较长。 无需执行任何操作。
2. 在 Output 面板中监视进度（从 Visual Studio 的下拉列表中选择 AppModernizationExtension）。
3. 每个情境仅运行一次评估。 后续阶段使用缓存的结果。

自定义问题

这些问题与自定义技能和方案说明文件相关。

未识别出自定义技能

原因： 技能文件位于错误的位置、缺少或无效的元数据，或者格式不正确。

Solution:

1. 验证技能文件是否位于支持的位置之一：
   • .github/skills/ （库级，整个团队）
   • .github/upgrades/skills/ （方案级别）
   • %UserProfile%/.copilot/skills/ （用户级、个人版）
2. 检查技能元数据是否至少包括 name 和 description 字段。
3. 确认 discovery 字段（如果 set）为以下 lazy字段之一， preload或 scenario。
4. 验证技能 description 是否与预期应用的任务类型匹配。 代理使用描述匹配来选择技能。

对 scenario-instructions.md 的更改不会生效

原因： 代理可能无法在会话期间重新读取文件，或者您的编辑在文件中的位置不正确。

Solution:

1. 要求代理 “重新加载说明” 或启动新的聊天会话以强制重新读取。
2. 验证编辑是否位于文件的正确部分中：
   • 用户首选项： 对于常规首选项和约束。
   • 关键决策： 记录升级期间做出的重要决策。
   • 自定义说明：用于特定行为覆盖。
3. 验证文件是否已保存，并在预期路径中保存： .github/upgrades/{scenarioId}/scenario-instructions.md。

获取帮助

当某些东西未按预期工作时：

1. 询问代理： 问 “上一个任务有什么问题？” 代理通常可以解释所发生的事情并建议后续步骤。
2. 查看执行日志：在 execution-log.md 中打开 .github/upgrades/{scenarioId}/。 日志显示代理所执行的操作的时间顺序记录，包括它遇到的任何错误。
3. 提交问题：如果发现了 bug 或者代理在某个方面一直出现问题，请在 @modernize-dotnet GitHub 存储库提交相关问题。

相关内容

• 什么是GitHub Copilot的现代化更新？
• 最佳实践
• 核心概念
• GitHub Copilot现代化常见问题解答