استكشاف الأخطاء وإصلاحها

تُجمَّع الأعراض حسب موضع ظهورها على المسار من التثبيت إلى التصدير، مع أكثر أعطال القادمين الجدد شيوعًا أولًا. يذكر كل مدخل السبب وأمر الإصلاح.

🚧 التثبيت والبيئة

uv sync يفشل

السبب: Python 3.12 أو أحدث غير موجود في PATH، أو uv مفقود. الإصلاح: تأكّد من إصدار Python، ثم أعد التشغيل:

uv sync --all-extras --group dev

إذا كان uv مفقودًا، فثبّته من تعليمات حزمة Astral الرسمية، وافتح صدفة جديدة، وأعد تشغيل الأمر.

المُثبِّت يبلّغ عن متطلّب مسبق مفقود

السبب: تتطلّب سكربتات التثبيت وجود git وuv في PATH. الإصلاح: ثبّت المتطلّب المسبق المذكور، ثم أعد تشغيل أمر التثبيت نفسه. عيّن DISPATCHATLAS_HOME قبل إعادة التشغيل عندما ينبغي أن يقع الـ checkout خارج دليل بيانات المستخدم الافتراضي.

التحديث يبلّغ عن تغييرات لكنه لا يطبّقها

السبب: فحوص التحديث للقراءة فقط افتراضيًّا. الإصلاح: عيّن DISPATCHATLAS_REF إلى وسم إصدار أو SHA التزام كامل من 40 حرفًا، ثم طبّق تحديث الـ checkout المنفصل صراحةً:

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

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

إلغاء التثبيت يرفض هدفًا

السبب: ترفض سكربتات إلغاء التثبيت المسارات الفارغة، وجذور نظام الملفات، وأدلّة المنزل، والأدلّة التي تفتقر إلى حارس مساحة عمل DispatchAtlas. الإصلاح: عيّن DISPATCHATLAS_HOME إلى مسار الـ checkout المُثبَّت وأعد تشغيل أمر إلغاء التثبيت.

📦 عمليات الاستيراد

ModuleNotFoundError: No module named 'dispatchatlas'

السبب: مساحة العمل غير مُزامَنة، أو يعمل السكربت تحت مفسّر Python خارج بيئة المشروع. الإصلاح: من جذر المستودع، زامِن وشغّل السكربتات عبر uv حتى تكون بيئة المشروع نشطة:

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

MissingOptionalDependencyError عند إنشاء حلّال

السبب: تبقى الخلفيّات الثقيلة الاختيارية (الحلّالات الدقيقة، مُقدِّرات التعلّم) خلف الإضافات (extras) وتُستكشَف وقت التشغيل، ولا تُستورَد أبدًا أثناء استيراد الحزمة. يذكر الخطأ الإضافة المفقودة وغرضها وأي ملاحظة ترخيص. الإصلاح: ثبّت الإضافة المذكورة (مثل exact أو exact-commercial أو learning) أو اختر حلّالًا خلفيّته موجودة. تُدرَج إعلانات تبعيّات الحلّالات في نظام الحلّالات.

🧪 تهيئة الحملات وتنفيذها

CampaignConfigError عند التحقّق من حملة

السبب: يفشل حقل تهيئة في التحقّق — معرّف فارغ، أو بذرة أو ميزانية غير موجبة، أو أسماء بروتوكول توقّف مكرّرة، أو قائمة نسخ مرجعية أو حلّالات أو أهداف فارغة. يحمل الخطأ مسار الحقل المُخفِق. الإصلاح: صحّح الحقل المذكور. توثّق صفحة محرّك الحملات كل كتلة تهيئة، وexperiments/configs/smoke-pilot.json مثال عملي كامل:

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

KeyError عند جلب مسألة نسخة مرجعية

السبب: معرّف المسألة غير موجود في كتالوج المزوّد، أو مُرِّرت سلسلة نصّية عادية حيث يُتوقَّع ProblemId. الإصلاح: غلّف المعرّف (provider.get_problem(ProblemId("smoke-job-shop-0"))) واسرد أولًا المعرّفات المتاحة بـ provider.list_problem_ids() — راجع الدروس التعليمية.

الحملة الكاملة ترفض التنفيذ

السبب: تفشل حملة في مرحلة full إلى الإغلاق بـ full-campaign execution requires statistical design approval حتى تُسجَّل تلك الموافقة على التهيئة. الإصلاح: نفّذ في مرحلة smoke أو pilot للفحوص المحلية، أو سجّل موافقة التصميم الإحصائي وفق جاهزية الإصدار قبل تمكين التنفيذ الكامل.

الاستئناف يعيد التخطيط بدلًا من تخطّي عمليات التشغيل المكتملة

السبب: نقطة التفتيش في .checkpoints/{campaign_id}.json محميّة بتجزئة تهيئة؛ وأي تغيير في التهيئة يُبطلها بدلًا من إعادة استخدامها بصمت. الإصلاح: أبقِ التهيئة دون تغيير للاستئناف، أو اقبل خطّة جديدة تحت التهيئة المُغيَّرة. عقد مساحة العمل موصوف في الحملات القابلة لإعادة الإنتاج.

📤 الصادرات والتقارير والموقع

تصدير التحليل يبلّغ عن نقطة تفتيش مفقودة

السبب: يتوقّع أمر dispatchatlas export دليل حملة مكتملًا يحوي checkpoint.json وplan.json وenvironment.json وسجلّات النتائج. الإصلاح: وجّه --campaign-dir إلى دليل نتائج الحملة بدلًا من أصله، أو أعد تشغيل الحملة:

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

إذا كان --target-dir خارج دليل العمل الحالي، فمرّر --authorized-output-root صريحًا يحتوي على الوجهة.

يفشل التحقّق من بيانات البوابة

السبب: أصول الموقع الساكن غير متوافقة مع تصدير نتائج البوابة. الإصلاح: أعِد توليد الأصول الساكنة. يقرأ الأمر افتراضيًّا تصدير النتائج المُلتزَم والمُرشَّح وفق الإفصاح في exports/portal-results.json، لذا يعمل دون وسائط:

uv run python tools/build_site_assets.py

مرّر --result-source لنشر تصدير portal-results.json آخر مُرشَّح وفق الإفصاح:

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

إذا أبلغ الأمر عن dispatchatlas site-assets: error، فتحقّق من أن --result-source (أو exports/portal-results.json الافتراضي) يشير إلى ملف portal-results.json موجود مُولَّد عبر مسار تصدير التحليل.

تفشل بوّابة التنقيح في البوابة

السبب: وصل إلى بيانات البوابة رمز لا ينتمي إلى السطح العام، لذا تفشل البِنية إلى الإغلاق كي يبقى الوجه المنشور مقروءًا كعُدّة عامة لتحسين الجدولة. الإصلاح: يَسرد الخطأ كل مُنتَج مُخالف ومسار حقل ورمز. نقّح الحقل المُخالف في الباني الذي يُصدِر ذلك المُنتَج (تحت tools/portal_contract.py أو دليل مصدره) كي لا يصل إلى بيانات البوابة سوى أدلّة مشتقّة آمنة للعموم، ثم أعِد التوليد:

uv run python tools/build_site_assets.py

يختلف هذا العطل عن تصدير بوابة مفقود: تمرير --result-source مختلف لا يزيله — يجب إزالة الرمز المُخالف عند مصدره.

بِنية الموقع لا تعثر على صفحة

الإصلاح: شغّل اختبارات عقد الموقع وبِنية التوثيق:

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

حلّال مفقود من التوصيات

السبب: يُرشِّح الاختيار وفق البيانات الوصفية. الإصلاح: افحص في البيانات الوصفية للحلّال دعمَ الأهداف، ووسوم القدرات المطلوبة، وحالة التبعيّات الاختيارية، ورؤية طبقة الأدلّة في نظام الحلّالات.

ما زلت عالقًا؟ راجع الأسئلة الشائعة أو افتح مشكلة في مستودع GitHub.