Rozwiązywanie problemów z modernizacją GitHub Copilot

W tym artykule opisano typowe problemy, które mogą wystąpić podczas używania modernizacji GitHub Copilot dla .NET, uporządkowane według kategorii. Każdy wpis jest zgodny z formatem problemu, przyczyny i rozwiązania, dzięki czemu można szybko znaleźć i rozwiązać problemy.

Problemy z przepływem pracy

Te problemy dotyczą odnajdywania scenariuszy, wznawiania pracy i stanu zadania.

Agent mówi "nie znaleziono scenariuszy"

Cause: Agent nie rozpoznaje obszaru roboczego jako projektu .NET.

Rozwiązanie:

  1. Sprawdź, czy katalog główny obszaru roboczego zawiera plik .sln, .csproj lub .vbproj.
  2. Zapytaj agenta: "Jakiego rozwiązania lub pliku projektu używasz?"
  3. Jeśli rozwiązanie lub plik projektu znajduje się w podkatalogu, otwórz ten katalog jako katalog główny obszaru roboczego lub wskaż agenta jawnie plikowi.

Agent nie może wznowić poprzedniej pracy

Przyczyna: Folder .github/upgrades/, w którym agent przechowuje swój stan, jest brakujący lub uszkodzony.

Rozwiązanie:

  1. Sprawdź, czy .github/upgrades/ folder istnieje w katalogu głównym repozytorium.
  2. Jeśli folder został przypadkowo usunięty, uruchom scenariusz świeży. Agent nie może się zregenerować bez plików statusu.
  3. Jeśli folder istnieje, ale pliki są uszkodzone, poproś agenta o ponowne oceny i ponowne zaplanowanie, aby je ponownie wygenerować.

Napiwek

Zatwierdź folder .github/upgrades/ do Twojej gałęzi, aby był zachowywany we wszystkich sesjach i na wszystkich maszynach.

Zadania zablokowane w toku

Przyczyna: Poprzednia sesja zakończyła się, gdy agent był w połowie zadania.

Rozwiązanie:

  1. Agent w większości przypadków automatycznie wykrywa nieaktualne zadania. Poinformuj agenta "wznów" lub "uruchom ponownie bieżące zadanie".
  2. Jeśli stan blokady będzie się powtarzać, poinformuj agenta "oznacz bieżące zadanie jako oczekujące i uruchom je ponownie" lub "ponownie oceń, a następnie kontynuuj od ostatniego ukończonego kroku".
  3. Sprawdź odpowiedni progress-details.md plik, aby dowiedzieć się, gdzie została zatrzymana poprzednia sesja.

Agent ciągle sugeruje niewłaściwy scenariusz

Przyczyna: Analiza agenta wykryła nieoczekiwane cechy projektu i wywnioskowała inny scenariusz niż zamierzałeś.

Rozwiązanie:

Bądź jawny o tym, co chcesz. Zamiast "uaktualnić mój projekt", powiedz:

  • "Chcę uaktualnić do wersji .NET 10."
  • "Chcę uaktualnić plik Newtonsoft.Json do pliku System.Text.Json"."
  • "Przekonwertuj projekt na format w stylu zestawu SDK".

Dodaj preferencje scenariusza do scenario-instructions.md, aby zapobiec przyszłym niezgodnościom.

Problemy z budowaniem i kompilacją

Te problemy dotyczą błędów kompilacji, problemów z przywracaniem nuGet i błędów generowania kodu.

Proces budowania kończy się niepowodzeniem po zmianach wprowadzonych przez agenta

Spowodować: Uaktualnienia mogą wprowadzać zmiany interfejsu API powodujące niezgodność, brakujące pakiety lub niezgodne wzorce kodu.

Rozwiązanie:

  1. Poinformuj agenta o niepowodzeniu. Agent automatycznie analizuje błędy.
  2. Jeśli agent nie może rozwiązać problemu, przywróć ostatnie zatwierdzenie (git revert HEAD) i poproś agenta o wypróbowanie innego podejścia.
  3. W przypadku złożonych niepowodzeń sprawdź execution-log.md, co zmienił agent i w jakiej kolejności.

Przywracanie nuGet kończy się niepowodzeniem

Przyczyna: Niezgodność pakietu z platformą docelową lub niepowodzenia uwierzytelniania z prywatnymi repozytoriami NuGet.

Rozwiązanie:

  • W przypadku kanałów prywatnych: Uwierzytelnij się w kanale informacyjnym przed rozpoczęciem uaktualniania.
  • W przypadku niezgodnych pakietów: Poinformuj agenta, który pakiet jest problematyczny. Agent może wyszukiwać zgodne wersje lub sugerować alternatywne pakiety.
  • W przypadku problemów z łącznością kanału danych: Sprawdź, czy możesz go uruchomić dotnet restore ręcznie. Najpierw rozwiąż wszelkie problemy ze źródłem danych, a następnie pozwól agentowi ponowić próbę.

Agent generuje kod, który nie jest kompilowany

Spowodować: Kod generowany przez sztuczną inteligencję może zawierać błędy, szczególnie w przypadkach brzegowych lub z nietypowymi wzorcami interfejsu API.

Rozwiązanie:

  1. Agent wykrywa błędy kompilacji automatycznie. Jeśli agent ma problemy, podaj wskazówki lub napraw kod ręcznie i poinformuj agenta o kontynuowaniu.
  2. Jeśli agent zmaga się z określoną poprawką po wielu próbach, edytuj kod ręcznie i poinformuj agenta: "Usunęliśmy błąd kompilacji w MyClass.cs, oznacz to zadanie jako ukończone".
  3. Agent uczy się z ręcznej poprawki i stosuje podobne wzorce, gdy ten sam problem pojawia się w innym miejscu.

Problemy z usługą Git

Uwaga / Notatka

Agent działa również z folderami innych niż Git. Jeśli obszar roboczy nie jest repozytorium Git, agent pomija operacje git (rozgałęzianie, zatwierdzanie) i stosuje zmiany bezpośrednio do plików. Bez usługi Git utwórz kopię zapasową projektu ręcznie przed rozpoczęciem, aby można było przywrócić go w razie potrzeby.

Agent nie może utworzyć gałęzi

Przyczyna: Niezatwierdzone zmiany w drzewie roboczym, konflikt nazewnictwa gałęzi lub Git nie jest zainicjowany w obszarze roboczym.

Rozwiązanie:

  1. Przed rozpoczęciem scenariusza zatwierdź lub schowaj oczekujące zmiany.
  2. Sprawdź, czy usługa Git została zainicjowana, uruchamiając polecenie git status w katalogu głównym obszaru roboczego.
  3. Jeśli gałąź o zamierzonej nazwie agenta już istnieje, usuń istniejącą gałąź lub poproś agenta o użycie innej nazwy gałęzi.

Cofnij wszystkie zmiany agenta

Przyczyna: Uaktualnienie nie poszło zgodnie z planem i chcesz zacząć od nowa.

Rozwiązanie:

  1. Wróć do oryginalnej gałęzi, używając git checkout main (lub do gałęzi podstawowej).
  2. Gałąź robocza agenta zawiera wszystkie zmiany odizolowane od gałęzi głównej.
  3. Aby całkowicie usunąć gałąź agenta, uruchom polecenie git branch -D <agent-branch-name>.
  4. Aby zachować pewne zmiany, wybierz określone commity za pomocą polecenia git cherry-pick <commit-hash>.

Napiwek

Agent wykonuje szczegółowe zatwierdzenia dla każdego zadania, dzięki czemu można selektywnie zachować zmiany, które były skuteczne.

Problemy z wydajnością

Te problemy dotyczą szybkości uaktualniania i czasu trwania oceny.

Agent działa wolno lub jest opóźniony

Przyczyna: Duże rozwiązania z wieloma projektami, złożonymi grafami zależności lub wieloma zmianami powodującymi niezgodność naturalnie trwają dłużej.

Rozwiązanie:

W przypadku dużych rozwiązań (50+ projektów) rozważ uaktualnianie etapami. Grupuj powiązane projekty i uaktualnij je razem.

Ocena trwa długo

Przyczyna: Ocena analizuje zależności każdego projektu, pakiety NuGet, platformy docelowe i odpowiednie zmiany powodujące niekompatybilność. W przypadku dużych rozwiązań ocena naturalnie trwa dłużej.

Rozwiązanie:

  1. Długie czasy oceny są normalne w przypadku dużych rozwiązań. Nie jest wymagana żadna akcja.
  2. Monitoruj postęp w panelu Output (wybierz pozycję AppModernizationExtension z listy rozwijanej w Visual Studio).
  3. Ocena jest uruchamiana tylko raz na scenariusz. Kolejne fazy używają buforowanych wyników.

Problemy z dostosowywaniem

Te problemy dotyczą niestandardowych umiejętności i plików instrukcji scenariusza.

Umiejętność niestandardowa nie jest rozpoznawana

Przyczyna: Plik umiejętności znajduje się w niewłaściwej lokalizacji, ma brakujące lub nieprawidłowe metadane lub ma nieprawidłowy format.

Rozwiązanie:

  1. Sprawdź, czy plik umiejętności znajduje się w jednej z obsługiwanych lokalizacji:
    • .github/skills/ (na poziomie repozytorium, na poziomie zespołu)
    • .github/upgrades/skills/ (poziom scenariusza)
    • %UserProfile%/.copilot/skills/ (poziom użytkownika, osobisty)
  2. Sprawdź, czy metadane umiejętności zawierają co najmniej pola name i description.
  3. Upewnij się, że discovery pole (jeśli ustawiono) jest jednym z następujących elementów: lazy, preloadlub scenario.
  4. Upewnij się, że description umiejętności pasuje do rodzaju zadania, do którego chcesz ją zastosować. Agent używa dopasowania opisu, aby wybrać umiejętności.

Zmiany w pliku scenario-instructions.md nie wchodzą w życie

Przyczyna: Agent może nie odczytać ponownie pliku w trakcie sesji lub Twoje edycje są w niewłaściwej sekcji.

Rozwiązanie:

  1. Poproś agenta o "ponowne załadowanie instrukcji" lub rozpoczęcie nowej sesji czatu, aby wymusić ponowne odczytanie.
  2. Sprawdź, czy zmiany znajdują się w odpowiednich sekcjach pliku:
    • Preferencje użytkownika: W przypadku ogólnych preferencji i ograniczeń.
    • Kluczowe decyzje: Do rejestrowania ważnych decyzji podjętych podczas uaktualniania.
    • Instrukcje niestandardowe: Do konkretnych zmian zachowań.
  3. Sprawdź, czy plik został zapisany i w oczekiwanej ścieżce: .github/upgrades/{scenarioId}/scenario-instructions.md.

Uzyskaj pomoc

Gdy coś nie działa zgodnie z oczekiwaniami:

  1. Zapytaj agenta: Zapytaj "Co poszło nie tak z ostatnim zadaniem?" Agent często może wyjaśnić, co się stało i zasugerować kolejne kroki.
  2. Przejrzyj dziennik wykonywania: Otwórz plik execution-log.md w pliku .github/upgrades/{scenarioId}/. Dziennik przedstawia chronologiczny zapis tego, co zrobił agent, w tym wszelkie napotkane błędy.
  3. Zgłoś problem: Jeśli znalazłeś usterkę lub agent stale nie działa prawidłowo, zgłoś problem w repozytorium GitHub @modernize-dotnet.

Treści powiązane

  • Last updated on