Pemecahan masalah

Gejala dikelompokkan menurut tempat kemunculannya pada jalur dari instalasi hingga ekspor, dengan kegagalan pendatang baru yang paling umum lebih dulu. Setiap entri menamai penyebab dan perintah perbaikannya.

🚧 Instalasi dan lingkungan

uv sync gagal

Penyebab: Python 3.12 atau yang lebih baru tidak ada di PATH, atau uv tidak ada. Perbaikan: Konfirmasi versi Python, lalu jalankan ulang:

uv sync --all-extras --group dev

Jika uv tidak ada, instal dari instruksi paket resmi Astral, buka shell baru, dan jalankan ulang perintahnya.

Penginstal melaporkan prasyarat yang hilang

Penyebab: Skrip instalasi memerlukan git dan uv di PATH. Perbaikan: Instal prasyarat yang disebutkan, lalu jalankan ulang perintah instalasi yang sama. Atur DISPATCHATLAS_HOME sebelum menjalankan ulang ketika checkout harus berada di luar direktori data pengguna default.

Pembaruan melaporkan perubahan tetapi tidak menerapkannya

Penyebab: Pemeriksaan pembaruan bersifat hanya-baca secara default. Perbaikan: Atur DISPATCHATLAS_REF ke tag rilis atau SHA commit lengkap 40 karakter, lalu terapkan pembaruan checkout terlepas secara eksplisit:

$env:DISPATCHATLAS_REF = "<release-tag>"
.\scripts\installer\update.ps1 -Apply

export DISPATCHATLAS_REF="<release-tag>"
scripts/installer/update.sh --apply

Penghapusan menolak sebuah target

Penyebab: Skrip penghapusan menolak path kosong, root sistem berkas, direktori home, dan direktori tanpa sentinel ruang kerja DispatchAtlas. Perbaikan: Atur DISPATCHATLAS_HOME ke path checkout terinstal dan jalankan ulang perintah penghapusan.

📦 Impor

ModuleNotFoundError: No module named 'dispatchatlas'

Penyebab: Ruang kerja tidak tersinkron, atau skrip berjalan di bawah interpreter Python di luar lingkungan proyek. Perbaikan: Dari root repositori, sinkronkan dan jalankan skrip melalui uv agar lingkungan proyek aktif:

uv sync --all-extras --group dev
uv run python your-script.py

MissingOptionalDependencyError saat membuat solver

Penyebab: Backend berat opsional (solver eksak, estimator pembelajaran) tetap di balik extras dan disonda saat runtime, tidak pernah diimpor selama impor paket. Galat menamai extra yang hilang, tujuannya, dan catatan lisensi apa pun. Perbaikan: Instal extra yang disebutkan (misalnya exact, exact-commercial, atau learning) atau pilih solver yang backend-nya tersedia. Deklarasi dependensi solver tercantum di sistem solver.

🧪 Konfigurasi dan eksekusi kampanye

CampaignConfigError saat memvalidasi kampanye

Penyebab: Sebuah bidang konfigurasi gagal validasi — id kosong, benih atau anggaran non-positif, nama protokol penghentian duplikat, atau daftar benchmark, solver, atau tujuan yang kosong. Galat membawa path bidang yang gagal. Perbaikan: Perbaiki bidang yang disebutkan. Halaman mesin kampanye mendokumentasikan setiap blok konfigurasi, dan experiments/configs/smoke-pilot.json adalah contoh kerja lengkap:

uv run dispatchatlas-lab validate --config experiments/configs/smoke-pilot.json

KeyError saat mengambil masalah benchmark

Penyebab: id masalah tidak ada dalam katalog penyedia, atau string biasa diteruskan di tempat ProblemId diharapkan. Perbaikan: Bungkus id (provider.get_problem(ProblemId("smoke-job-shop-0"))) dan daftar dulu id yang tersedia dengan provider.list_problem_ids() — lihat tutorial.

Kampanye penuh menolak untuk dieksekusi

Penyebab: Kampanye pada tahap full gagal-menutup dengan full-campaign execution requires statistical design approval hingga persetujuan itu dicatat pada konfigurasi. Perbaikan: Jalankan pada tahap smoke atau pilot untuk pemeriksaan lokal, atau catat persetujuan desain statistik sesuai kesiapan rilis sebelum mengaktifkan eksekusi penuh.

Pelanjutan merencanakan ulang alih-alih melewati eksekusi yang selesai

Penyebab: Titik pemeriksaan di .checkpoints/{campaign_id}.json dijaga oleh hash konfigurasi; perubahan konfigurasi apa pun membatalkannya alih-alih menggunakannya kembali secara diam-diam. Perbaikan: Jaga konfigurasi tidak berubah untuk melanjutkan, atau terima rencana baru di bawah konfigurasi yang berubah. Kontrak ruang kerja dijelaskan dalam kampanye yang dapat direproduksi.

📤 Ekspor, laporan, dan situs

Ekspor analisis melaporkan titik pemeriksaan yang hilang

Penyebab: Perintah dispatchatlas export mengharapkan direktori kampanye yang selesai dengan checkpoint.json, plan.json, environment.json, dan catatan hasil. Perbaikan: Arahkan --campaign-dir ke direktori hasil kampanye alih-alih induknya, atau jalankan ulang kampanye:

uv run dispatchatlas export `
  --campaign-dir .\experiments\results\smoke-pilot `
  --target-dir .\exports\smoke-pilot `
  --authorized-output-root .\exports `
  --tier core

Jika --target-dir di luar direktori kerja saat ini, teruskan --authorized-output-root eksplisit yang memuat tujuan.

Validasi data portal gagal

Penyebab: Aset situs statis tidak selaras dengan ekspor hasil portal. Perbaikan: Regenerasi aset statis. Perintah membaca ekspor hasil yang difilter pengungkapan dan telah di-commit di exports/portal-results.json secara default, jadi ia berjalan tanpa argumen:

uv run python tools/build_site_assets.py

Teruskan --result-source untuk menerbitkan ekspor portal-results.json yang difilter pengungkapan berbeda:

uv run python tools/build_site_assets.py --result-source .\path\to\portal-results.json

Jika perintah melaporkan dispatchatlas site-assets: error, periksa bahwa --result-source (atau exports/portal-results.json default) menunjuk ke berkas portal-results.json yang ada, yang dihasilkan oleh jalur ekspor analisis.

Gerbang redaksi portal gagal

Penyebab: Sebuah token yang bukan miliknya pada permukaan publik mencapai data portal, sehingga build gagal-menutup agar wajah yang diterbitkan terbaca sebagai kit optimasi penjadwalan generik. Perbaikan: Galat mencantumkan setiap artefak pelanggar, path bidang, dan token. Redaksi bidang pelanggar di pembangun yang memancarkan artefak itu (di bawah tools/portal_contract.py atau bukti sumbernya) agar hanya bukti turunan yang aman untuk publik mencapai data portal, lalu regenerasi:

uv run python tools/build_site_assets.py

Kegagalan ini berbeda dari ekspor portal yang hilang: meneruskan --result-source yang berbeda tidak menghapusnya — token pelanggar harus dihapus di sumbernya.

Build situs tidak dapat menemukan sebuah halaman

Perbaikan: Jalankan uji kontrak situs dan build dokumentasi:

uv run pytest tests/site
npm --prefix site run build
npm --prefix site run check

Sebuah solver hilang dari rekomendasi

Penyebab: Pemilihan memfilter berdasarkan metadata. Perbaikan: Periksa metadata solver untuk dukungan tujuan, tag kapabilitas yang diperlukan, status dependensi opsional, dan visibilitas tingkat-bukti di sistem solver.

Masih buntu? Lihat FAQ atau buka isu di repositori GitHub.