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

السبب: بدأ التطبيق مصغّراً أو منع نظام التشغيل بدء التشغيل.

الإصلاح: تحقق من فائض شريط النظام (^) على Windows. أعد تشغيل Engine من قائمة Start. على Linux، تأكد من تشغيل تطبيق شريط النظام (tray applet).

السبب: الإضافة معطّلة، أو ملف تعريف VS Code خاطئ، أو خطأ تفعيل.

الإصلاح: الإضافات ← فعّل ContextMint. أعد تحميل النافذة. تحقق من Output ← “ContextMint” لأخطاء التفعيل.

السبب: عدم تطابق مسار تخطيط التطوير مع الحزمة المعبأة.

الإصلاح: Engine ← الإعدادات ← اضبط مسار الخلفية على الحزمة المشحونة. أعد تثبيت أحدث إصدار من Engine. لتطوير المصدر، وجّه pythonPath إلى venv المشروع.

السبب: لا يستمع API على العنوان المهيّأ.

الإصلاح: Engine ← تشغيل الكل. تحقق من http://localhost:8000/api/health. تحقق من جدار حماية يحظر loopback. عند استخدام خادم مشترك، تحقق من serverUrl وTLS.

السبب: المنفذ 8000 مستخدم، أو انهيار Python عند الإقلاع، أو عملية زومبي.

الإصلاح: Engine ← السجلات. أوقف الكل، وأنهِ عمليات python/contextmint الشاردة، وغيّر المنفذ في الإعدادات إذا لزم، ثم شغّل الكل مجدداً.

السبب: استطلاع جاهزية قديم، أو serverUrl خاطئ، أو انتهاء مهلة حالة الفهرس.

الإصلاح: أعد تحميل نافذة VS Code. تأكد من عدم وجود خطأ إملائي في نهاية مسار serverUrl. Engine ← الخادم ← أعد تشغيل الخادم.

السبب: Redis الاختياري غير مُشغّل (بعض تهيئات المؤسسات).

الإصلاح: بالنسبة لتجربة محلية أولاً، غالباً ما يكون تجاهله آمناً إذا كانت الدردشة تعمل. لخادم الفريق، شغّل Redis وفق دليل النشر أو عطّل الميزات المعتمدة على Redis في تهيئة الخادم.

السبب: Ollama غير مُشغّل أو عنوان خاطئ.

الإصلاح: Engine ← Ollama ← تشغيل / إعادة تشغيل. ثبّت Ollama إذا كان مفقوداً. العنوان الافتراضي http://localhost:11434.

السبب: لم يتم سحب نموذج الدردشة في Ollama.

الإصلاح: Engine ← النماذج ← اسحب نموذج الدردشة الافتراضي. طابق اسم النموذج مع افتراضيات الخادم.

السبب: نموذج تضمين مفقود، أو تحميل زائد على GPU/CPU، أو ضغط على القرص.

الإصلاح: اسحب نموذج التضمين في تبويب النماذج. قلّل الفهرسة المتزامنة إذا كانت قابلة للضبط. استبعد مجلدات ثنائية كبيرة عبر قواعد التجاهل.

السبب: تحميل بارد للنموذج في Ollama.

الإصلاح: متوقع مرة واحدة لكل إعادة تشغيل. يشغّل الخادم إحماءً في الخلفية؛ أرسل رسالة اختبار قصيرة لتحميل النموذج قبل الاستعلامات المهمة.

السبب: مساحة عمل متعددة الجذور، أو مجلد غير مسجّل، أو عدم تطابق مسارات على خادم مشترك.

الإصلاح: افتح مجلد جذر المستودع. Engine ← الفهرسة ← تأكد من إدراج مساحة العمل. للمؤسسات: يجب أن تطابق المسارات على الخادم مسارات مجلدات VS Code.

السبب: يشير serverUrl إلى localhost على المضيف البعيد بينما يستخدم اختبار المتصفح الجهاز المحلي.

الإصلاح: شغّل Engine على مضيف SSH أو استخدم serverUrl خاصاً بالفريق يمكن الوصول إليه من مضيف الإضافة البعيد. حوّل المنفذ 8000 إذا لزم.

السبب: رمز OIDC مفقود أو منتهي الصلاحية.

الإصلاح: أعد المصادقة وفق تدفق SSO الخاص بالمؤسسة. تأكد من تطابق oidcProviderId مع الخادم. تحقق من سجل تدقيق الخادم لأخطاء المصادقة.

السبب: أخطاء أذونات، أو مستودع ضخم، أو مهمة خلفية منهارة.

الإصلاح: Engine ← الفهرسة ← اعرض الأخطاء. Engine ← السجلات. شغّل إعادة فهرسة يدوية. استبعد node_modules ومخرجات البناء عبر تهيئة التجاهل.

السبب: الملف لم يُفهرس بعد، أو مسار خاطئ (Repo بفهرس فارغ)، أو عدم تطابق الاستعلام.

الإصلاح: افتح الملف في المحرر (فهرسة ذات أولوية). انتظر اكتمال الفهرسة. أرفق الملف صراحةً. جرّب مسار Hybrid. استخدم استعلاماً غنياً بالرموز لعمليات بحث الكود.

السبب: تغيّر نموذج التضمين، أو مسح ذاكرة تخزين التجزئة المؤقتة، أو عاصفة مراقبة ملفات (watcher).

الإصلاح: ثبّت نموذج التضمين في تبويب النماذج. تحقق من السجلات لمحفزات إعادة فهرسة كاملة متكررة. أوقف عمليات الملفات الجماعية أثناء الفهرسة الأولية مؤقتاً.

السبب: استثناء في الفهرس، أو مخزن محلي تالف، أو امتلاء القرص.

الإصلاح: Engine ← تفاصيل خطأ الفهرسة. حرّر مساحة على القرص. كملاذ أخير: امسح بيانات فهرس مساحة العمل وأعد الفهرسة بالكامل (انسخ احتياطياً أولاً).

السبب: متوقع — يرفض مسار Repo التخمين دون أدلة.

الإصلاح: انتقل إلى مسار Work أو اقبل شريط استخدام مسار Work. أرفق ملاحظات أو فعّل حزمة جلسة.

السبب: لم يتم بناء أي حزم، ولا مرفقات.

الإصلاح: ابنِ حزم الجلسة/المستودع. أرفق ملفات ماركداون أو مواصفات. الصق السياق الأساسي كمرفق.

السبب: تجمّد Ollama، أو انتهاء مهلة سحابية، أو انقطاع SSE.

الإصلاح: انقر إلغاء (زر الإرسال). أعد تشغيل Ollama. تحقق من السجلات. قلّل حجم السياق / عدد المرفقات. أعد المحاولة بنموذج محلي فقط.

السبب: مفتاح API غير صالح، أو انقطاع لدى المزوّد، أو cloudEnabled بقيمة false.

الإصلاح: أعد تشغيل تهيئة مفتاح API السحابي. فعّل contextmint.cloudEnabled. تحقق من حالة المزوّد. افحص شارة التوجيه لمعرفة المستوى المستخدم.

السبب: مرفقات الصور معطّلة، أو صيغة خاطئة، أو الملف كبير جداً.

الإصلاح: فعّل contextmint.chat.imageAttachmentsEnabled. استخدم PNG أو JPEG أو WebP — وليس SVG. الحد الأقصى 5 ميغابايت لكل صورة. تحقق من Output ← ContextMint لأخطاء التحقق.

السبب: لا يوجد نموذج رؤية Ollama مثبّت.

الإصلاح: Engine ← النماذج ← اسحب moondream (صغير) أو llava. أعد تشغيل Ollama إذا نجح السحب لكن التوجيه لا يزال يفشل. لا تحل مفاتيح API السحابية محل نموذج رؤية محلي ما لم تختر رؤية سحابية صراحةً.

السبب: تم اختيار نموذج نصي فقط، أو تراجع مسار الرؤية بعد خطأ في نموذج الرؤية.

الإصلاح: تأكد من أن Lens يعرض مسار رؤية محلي أو سحابي قبل الإرسال. اسحب/حدّث نموذج الرؤية. تحقق من Engine ← السجلات لأخطاء متعددة الوسائط. أعد المحاولة بنموذج محلي مع نموذج رؤية مثبّت.

السبب: نموذج رؤية كبير على ذاكرة VRAM محدودة؛ نماذج الدردشة والرؤية تتنافس.

الإصلاح: استخدم moondream على الحواسيب المحمولة. اسمح بتفريغ نموذج الدردشة بين الأدوار إذا فعّل المشغّل خيار التفريغ قبل الرؤية. قلّل عدد الصور المرفقة. أغلق تطبيقات أخرى ثقيلة على GPU.

السبب: ARGUS معطّل على الخادم، أو التدقيق يعمل أثناء التدفق، أو أعاد نموذج الرؤية JSON فارغاً.

الإصلاح: انتظر انتهاء تدفق الدردشة. تأكد من تثبيت نموذج رؤية محلي. أعد المحاولة بلقطة شاشة واضحة للواجهة. تحقق من argus.enabled في افتراضيات الخادم. Engine ← السجلات لأخطاء /api/argus/audit.

السبب: تعذّر على شجرة عمل المعاينة تثبيت التبعيات ضمن المهلة.

الإصلاح: افتح شجرة عمل sandbox يدوياً وأصلح أخطاء npm ci / التثبيت. زد argus.deps_install_timeout_sec على الخادم إذا كان المستودع كبيراً. استخدم مسار تدقيق اللصق عندما لا يكون تمهيد sandbox مطلوباً.

السبب: اخترت صراحةً نموذج رؤية سحابياً في شريط التأليف.

الإصلاح: اختر محلي أو تلقائي مع نموذج رؤية محلي مثبّت. إرفاق الصور وحده لا يجب أن يفرض السحابي — إذا حدث ذلك، أبلغ عن خطأ مع حزمة الدعم ومسار الرؤية من Lens.

السبب: lensPreviewEnabled معطّل ونفدت أول N عمليات إرسال.

الإصلاح: فعّل contextmint.trust.lensPreviewEnabled. بدّل المعاينة من شريط التأليف أو إعدادات الثقة.

السبب: الحزمة غير مبنية أو اسم خاطئ في manifest.

الإصلاح: لوحة الحزم ← فحص وتعلّم. تحقق من تطابق اسم manifest.yaml مع مرجع @pack.

السبب: تغيّرت المصادر أسرع من التزامن التلقائي.

الإصلاح: أعد بناء الحزمة. فعّل autoSync مع فترة تأخير مناسبة. التزم بمصادر الحزمة إذا كان ذلك مقصوداً.

السبب: لست في وضع Agent، أو الجاهزية محظورة، أو سياسة sandbox.

الإصلاح: انتقل إلى وضع Agent. تأكد من مرحلة Ready/Limited/Indexing. تحقق من إعدادات sandbox.enabled.

السبب: أذونات ملفات، أو تعارض git، أو مسار خارج مساحة العمل.

الإصلاح: راجع الاختلاف (diff) في معاينة التصحيح. تأكد من إمكانية الكتابة على الملفات. استخدم git للتراجع. تحقق من Output لأخطاء التطبيق.

السبب: لم يتم تشغيل فحص جودة لمساحة العمل.

الإصلاح: Engine ← الجودة ← شغّل الفحص. انتظر الاكتمال. أعد محاولة الدردشة مع تفعيل معاينة الحوكمة.

السبب: يفهرس الخادم /data/repos/foo بينما يفتح VS Code C:\foo.

الإصلاح: طابق المسارات عبر Remote SSH بنفس المسار المطلق أو تخطيط مسارات على جانب الخادم. أعد تسجيل مساحة العمل على الخادم.

السبب: MITM مؤسسي أو شهادة موقّعة ذاتياً غير موثوقة.

الإصلاح: ثبّت شهادة الجذر الخاصة بالمؤسسة على جهاز التطوير. استخدم شهادة داخلية صالحة على مدخل API. حل مؤقت للتطوير فقط: ثق بإعدادات الوكيل (proxy) وفق سياسة تقنية المعلومات.

السبب: دفعة التضمين واستدلال الدردشة يتنافسان على نفس الجهاز.

الإصلاح: دع الفهرسة الأولية تكتمل. استخدم نموذج دردشة أصغر. على مضيفات Ollama المشتركة المتنازع عليها، اضبط inline.pause_mode على الخادم إلى shared_runtime (تُشدّد إضافة contextmint.inline.pauseWhileIndexing ذلك فقط أكثر). جدول إعادة الفهرسة الكبيرة خارج ساعات العمل.

السبب: استرجاع مقاطع كثيرة قبل الحد الأقصى.

الإصلاح: ضيّق السؤال. أرفق ملفات محددة. استبعد المقاطع غير ذات الصلة في lens. اضبط إعدادات الحد الأقصى للسياق على الخادم إن كنت مشغّلاً.

1. Engine ← حول ← تصدير حزمة الدعم
2. أرقام إصدار Engine والإضافة
3. إصدار نظام التشغيل وإصدار VS Code
4. خطوات إعادة الإنتاج، ومرحلة الجاهزية، ومسار السياق المستخدم
5. أسطر سجلات ذات صلة منقّحة من Engine ← السجلات

راسلنا عبر anis@contextmint.ai أو افتح مشكلة على GitHub لإصدارات الإطلاق.

تحصل دفعات التجارب على قناة هندسية مباشرة. راجع شركاء التصميم أو جهة الاتصال المسؤولة عن إعدادك.