Pemecahan Masalah Modernisasi GitHub Copilot

Artikel ini membahas masalah umum yang mungkin Anda temui saat menggunakan modernisasi GitHub Copilot untuk .NET, diatur menurut kategori. Setiap entri mengikuti format masalah, penyebab, dan solusi sehingga Anda dapat menemukan dan menyelesaikan masalah dengan cepat.

Masalah alur kerja

Masalah ini berkaitan dengan skenario penemuan, kelanjutan pekerjaan, dan status tugas.

Agen mengatakan "tidak ada skenario yang ditemukan"

Cause: Agen tidak mengenali ruang kerja sebagai proyek .NET.

Solution:

  1. Verifikasi bahwa akar ruang kerja berisi .slnfile , .csproj, atau .vbproj .
  2. Tanyakan kepada agen: "Solusi atau file proyek apa yang Anda gunakan?"
  3. Jika solusi atau file proyek Anda berada dalam subdirektori, buka direktori tersebut sebagai akar ruang kerja atau arahkan agen ke file secara eksplisit.

Agen tidak dapat melanjutkan pekerjaan sebelumnya

Menyebabkan: Folder .github/upgrades/ , tempat agen menyimpan semua statusnya, hilang atau rusak.

Solution:

  1. Periksa apakah .github/upgrades/ folder ada di akar repositori Anda.
  2. Jika Anda tidak sengaja menghapus folder, mulai skenario baru. Agen tidak dapat pulih tanpa file statusnya.
  3. Jika folder ada tetapi file tampak rusak, minta agen untuk "menilai ulang dan merencanakan ulang" untuk meregenerasinya.

Petunjuk / Saran

Terapkan .github/upgrades/ folder ke cabang Anda sehingga dipertahankan di seluruh sesi dan komputer.

Tugas terhenti dalam perjalanan

Menyebabkan: Sesi sebelumnya berakhir saat agen sedang bertugas.

Solution:

  1. Agen mendeteksi tugas kedaluarsa secara otomatis dalam banyak kasus. Beri tahu agen "lanjutkan" atau "mulai ulang tugas saat ini."
  2. Jika status macet berlanjut, beri tahu agen "tandai tugas saat ini sebagai tertunda dan mulai ulang" atau "nilai ulang dan lanjutkan dari langkah terakhir yang selesai."
  3. Periksa file yang progress-details.md sesuai untuk memahami di mana sesi sebelumnya berhenti.

Agen terus menyarankan skenario yang salah

Menyebabkan: Analisis agen mengambil karakteristik proyek yang tidak terduga dan menyimpulkan skenario yang berbeda dari yang Anda inginkan.

Solution:

Jadilah eksplisit tentang apa yang Anda inginkan. Alih-alih "tingkatkan proyek saya," katakan:

  • "Saya ingin meningkatkan ke .NET 10."
  • "Saya ingin meningkatkan dari Newtonsoft.Json ke System.Text.Json."
  • "Konversikan proyek saya ke format gaya SDK."

Tambahkan preferensi skenario untuk scenario-instructions.md mencegah ketidakcocokan di masa mendatang.

Masalah build dan kompilasi

Masalah ini berkaitan dengan kegagalan build, masalah pemulihan NuGet, dan kesalahan pembuatan kode.

Build gagal setelah perubahan agen

Menyebabkan: Peningkatan dapat memperkenalkan perubahan API yang melanggar, paket yang hilang, atau pola kode yang tidak kompatibel.

Solution:

  1. Beri tahu agen tentang kegagalan tersebut. Agen menganalisis kesalahan secara otomatis.
  2. Jika agen tidak dapat mengatasi masalah, kembalikan komit terakhir (git revert HEAD) dan minta agen mencoba pendekatan lain.
  3. Untuk kegagalan kompleks, periksa execution-log.md untuk memahami apa yang diubah agen dan dalam urutan apa.

Pemulihan NuGet gagal

Menyebabkan: Ketidaksesuaian paket dengan kerangka kerja target atau kegagalan autentikasi dengan umpan NuGet privat.

Solution:

  • Untuk umpan privat: Autentikasi ke umpan sebelum Anda memulai pemutakhiran.
  • Untuk paket yang tidak kompatibel: Beri tahu agen paket mana yang bermasalah. Agen dapat mencari versi yang kompatibel atau menyarankan paket alternatif.
  • Untuk masalah konektivitas umpan: Verifikasi bahwa Anda dapat menjalankan dotnet restore secara manual. Perbaiki masalah umpan terlebih dahulu, lalu biarkan agen mencoba kembali.

Agen menghasilkan kode yang tidak dikompilasi

Menyebabkan: Kode yang dihasilkan AI mungkin berisi kesalahan, terutama dalam kasus tepi atau dengan pola API yang jarang terjadi.

Solution:

  1. Agen mendeteksi kesalahan kompilasi secara otomatis. Jika agen sedang berjuang, berikan panduan atau perbaiki kode secara manual, dan beri tahu agen untuk melanjutkan.
  2. Jika agen berjuang dengan perbaikan tertentu setelah beberapa upaya, edit kode secara manual dan beri tahu agen: "Saya memperbaiki kesalahan kompilasi di MyClass.cs, tandai tugas ini selesai."
  3. Agen belajar dari perbaikan manual Anda dan menerapkan pola serupa ketika masalah yang sama muncul di tempat lain.

Masalah Git

Nota

Agen juga bekerja dengan folder non-Git. Jika ruang kerja Anda bukan repositori Git, agen melewati operasi Git (percabangan, commit) dan langsung menerapkan perubahan ke file Anda. Tanpa Git, cadangkan proyek Anda secara manual sebelum memulai sehingga Anda dapat kembali jika diperlukan.

Agen tidak dapat membuat cabang

Menyebabkan: Perubahan yang tidak diterapkan di pohon kerja, konflik penamaan cabang, atau Git tidak diinisialisasi di ruang kerja.

Solution:

  1. Terapkan atau simpan perubahan yang tertunda sebelum Anda memulai skenario.
  2. Verifikasi bahwa Git diinisialisasi dengan menjalankan git status di akar ruang kerja.
  3. Jika cabang dengan nama agen yang dimaksudkan sudah ada, hapus cabang yang ada atau minta agen untuk menggunakan nama cabang yang berbeda.

Urungkan semua perubahan agen

Menyebabkan: Peningkatan tidak berjalan seperti yang direncanakan dan Anda ingin memulai kembali.

Solution:

  1. Beralih kembali ke cabang asli Anda dengan git checkout main (atau cabang dasar Anda).
  2. Cabang kerja agen berisi semua perubahan yang diisolasi dari cabang utama Anda.
  3. Untuk menghapus cabang agen sepenuhnya, jalankan git branch -D <agent-branch-name>.
  4. Untuk menyimpan beberapa perubahan, pilih secara selektif penerapan tertentu dengan git cherry-pick <commit-hash>.

Petunjuk / Saran

Agen membuat commit yang lebih terperinci per tugas, agar Anda dapat secara selektif mempertahankan perubahan yang berfungsi.

Masalah performa

Masalah ini berkaitan dengan kecepatan peningkatan dan durasi penilaian.

Agen lambat atau membutuhkan waktu lama

Penyebab: Solusi besar dengan banyak proyek, grafik ketergantungan yang kompleks, atau mengalami banyak perubahan besar secara alami memerlukan waktu lebih lama.

Solution:

Untuk solusi besar (50+ proyek), pertimbangkan untuk meningkatkan dalam batch. Kelompokkan proyek terkait dan tingkatkan bersama-sama.

Penilaian membutuhkan waktu lama

Penyebab: Penilaian menganalisis dependensi setiap proyek, paket NuGet, kerangka kerja target, dan perubahan signifikan yang berlaku. Untuk solusi besar, penilaian secara alami membutuhkan waktu lebih lama.

Solution:

  1. Waktu penilaian yang panjang normal untuk solusi besar. Tidak ada tindakan yang diperlukan.
  2. Pantau kemajuan di panel Output (pilih AppModernizationExtension dari menu dropdown di Visual Studio).
  3. Penilaian hanya berjalan sekali per skenario. Fase berikutnya menggunakan hasil cache.

Masalah kustomisasi

Masalah ini berkaitan dengan keterampilan kustom dan file instruksi skenario.

Keterampilan khusus tidak terdeteksi

Menyebabkan: File keterampilan berada di lokasi yang salah, memiliki metadata yang hilang atau tidak valid, atau memiliki format yang salah.

Solution:

  1. Verifikasi bahwa file keterampilan berada di salah satu lokasi yang didukung:
    • .github/skills/ (tingkat repositori, seluruh tim)
    • .github/upgrades/skills/ (tingkat skenario)
    • %UserProfile%/.copilot/skills/ (tingkat pengguna, pribadi)
  2. Periksa apakah metadata keterampilan mencakup setidaknya name dan description bidang.
  3. Konfirmasikan bahwa discovery bidang (jika diatur) adalah salah satu dari: lazy, , preloadatau scenario.
  4. Verifikasi bahwa keterampilan description cocok dengan jenis tugas yang Anda harapkan untuk diterapkan. Agen menggunakan pencocokan deskripsi untuk memilih keterampilan.

Perubahan pada scenario-instructions.md tidak berlaku

Penyebab: Agen mungkin tidak membaca ulang file selama sesi, atau pengeditan Anda berada di bagian yang salah.

Solution:

  1. Minta agen untuk "memuat ulang instruksi" atau memulai sesi percakapan baru agar dapat membaca ulang.
  2. Verifikasi bahwa pengeditan Anda berada di bagian file yang benar:
    • Preferensi Pengguna: Untuk preferensi dan batasan umum.
    • Keputusan Utama: Untuk merekam keputusan penting yang dibuat selama peningkatan.
    • Instruksi Kustom: Untuk penggantian perilaku tertentu.
  3. Verifikasi bahwa file disimpan dan di jalur yang diharapkan: .github/upgrades/{scenarioId}/scenario-instructions.md.

Dapatkan bantuan

Ketika sesuatu tidak berfungsi seperti yang diharapkan:

  1. Tanyakan kepada agen: Tanyakan "Apa yang salah dengan tugas terakhir?" Agen sering dapat menjelaskan apa yang terjadi dan menyarankan langkah-langkah berikutnya.
  2. Tinjau log eksekusi: Buka execution-log.md di .github/upgrades/{scenarioId}/. Log menunjukkan catatan kronologis tentang apa yang dilakukan agen, termasuk kesalahan apa pun yang ditemuinya.
  3. Pilih masalah: Jika Anda menemukan bug atau agen secara konsisten gagal pada sesuatu, ajukan masalah di repositori GitHub @modernize-dotnet.

Konten terkait

  • Last updated on