Устранение неполадок при модернизации GitHub Copilot

В этой статье рассматриваются распространенные проблемы, которые могут возникнуть при модернизации с помощью GitHub Copilot для .NET, упорядоченные по категориям. Каждая запись представлена в формате: проблема, причина и решение, чтобы вы могли быстро найти и устранить проблемы.

Проблемы с рабочим процессом

Эти проблемы связаны с обнаружением сценариев, возобновлением работы и состоянием задачи.

Агент говорит, что "сценарии не найдены"

Cause: Агент не распознает рабочую область как проект .NET.

Solution:

  1. Убедитесь, что корневой каталог рабочей области содержит файл .sln, .csproj или .vbproj.
  2. Спросите агента: "Какое решение или файл проекта вы используете?"
  3. Если ваше решение или проект находятся в подкаталоге, откройте этот каталог как корневой каталог рабочей области или явно укажите агенту путь к файлу.

Агент не может возобновить предыдущую работу

Причина: Папка .github/upgrades/, в которой агент хранит все своё состояние, отсутствует или повреждена.

Solution:

  1. Проверьте, существует ли .github/upgrades/ папка в корневом каталоге репозитория.
  2. Если вы случайно удалили папку, запустите сценарий свежим. Агент не может восстановиться без файлов состояния.
  3. Если папка существует, но файлы кажутся поврежденными, попросите агента пересмотреть и перепланировать их генерацию.

Подсказка

Зафиксируйте папку в .github/upgrades/ ветке, чтобы она была доступна во всех сеансах и на всех устройствах.

Задачи застряли в процессе выполнения

Причина: Предыдущий сеанс закончился, пока агент был в процессе выполнения задачи.

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 вручную. Сначала исправьте все проблемы с каналом данных, а затем дайте агенту повторить попытку.

Агент создает код, который не компилируется

Причина: Код, созданный ИИ, может содержать ошибки, особенно в крайних случаях или при работе с нестандартными шаблонами API.

Solution:

  1. Агент автоматически обнаруживает ошибки компиляции. Если агент борется, предоставьте рекомендации или исправьте код вручную и сообщите агенту продолжить работу.
  2. Если агент борется с определенным исправлением после нескольких попыток, измените код вручную и сообщите агенту: "Исправлена ошибка компиляции в MyClass.cs, пометьте эту задачу завершенной".
  3. Агент узнает об исправлении вручную и применяет аналогичные шаблоны, когда эта проблема появится в другом месте.

Проблемы с Git

Замечание

Агент также работает с папками без Git. Если ваша рабочая область не является репозиторием Git, агент пропускает Git-операции (ветвление, фиксация) и применяет изменения непосредственно к вашим файлам. Без Git создайте резервную копию проекта вручную перед началом работы, чтобы при необходимости можно было вернуться.

Агент не может создать ветвь

Причина: Незафиксированные изменения в рабочем дереве, конфликт именования ветви или Git не инициализирован в рабочей области.

Solution:

  1. Зафиксируйте или сохраните несохраненные изменения перед началом работы над сценарием.
  2. Убедитесь, что Git инициализирована, выполнив команду git status в корневом каталоге рабочей области.
  3. Если ветвь с предполагаемым именем агента уже существует, удалите существующую ветвь или попросите агента использовать другое имя ветви.

Отмена всех изменений агента

Причина: Обновление не прошло так, как планировалось, и вы хотите начать заново.

Solution:

  1. Вернитесь в исходную ветвь с помощью git checkout main (или базовую ветвь).
  2. Рабочая ветвь агента содержит все изменения, изолированные от основной ветви.
  3. Чтобы полностью удалить ветвь агента, выполните команду git branch -D <agent-branch-name>.
  4. Чтобы сохранить некоторые изменения, выполните cherry-pick конкретных коммитов с git cherry-pick <commit-hash>.

Подсказка

Агент выполняет подробные фиксации для каждой задачи, чтобы вы могли выборочно сохранять изменения, которые успешно прошли.

Проблемы с производительностью

Эти проблемы связаны с длительностью обновления и длительностью оценки.

Агент работает медленно или требует много времени

Причина: Большие решения с множеством проектов, сложными графами зависимостей или многочисленными критическими изменениями естественно требуют больше времени.

Solution:

Для крупных решений (50+ проектов) рассмотрите возможность обновления в пакетах. Группировать связанные проекты и обновлять их вместе.

Оценка занимает много времени

Причина: Оценка анализирует зависимости каждого проекта, пакеты NuGet, целевые фреймворки и применимые критические изменения. Для крупных решений оценка, естественно, занимает больше времени.

Solution:

  1. Длительное время оценки является нормой для крупных решений. Никаких действий не требуется.
  2. Отслеживайте ход выполнения на панели Output (выберите AppModernizationExtension в раскрывающемся списке Visual Studio).
  3. Оценка выполняется только один раз в каждом сценарии. Последующие этапы используют кэшированные результаты.

Проблемы с настройкой

Эти проблемы связаны с пользовательскими навыками и файлами инструкций сценария.

Пользовательский навык не распознан

Причина: Файл навыка находится в неправильном расположении, отсутствуют или недопустимые метаданные, или имеет неправильный формат.

Solution:

  1. Убедитесь, что файл навыка находится в одном из поддерживаемых расположений:
    • .github/skills/ (уровень репозитория, на уровне всей команды)
    • .github/upgrades/skills/ (уровень сценария)
    • %UserProfile%/.copilot/skills/ (уровень пользователя, персональный)
  2. Убедитесь, что метаданные навыка включают по крайней мере name и description поля.
  3. Убедитесь, что discovery поле (если задано) является одним из следующих значений: 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. Создать проблему: Если вы нашли ошибку или агент часто завершается сбоем, создайте проблему в репозитории @modernize-dotnet GitHub.

Связанный контент

  • Last updated on