التثبيت والإعداد

يتكوّن ContextMint من عنصرين يتعامل معهما المستخدم: Engine (وحدة تحكم تشغيل على سطح المكتب + خادم Python) وإضافة VS Code (المحادثة، وContext Lens، وواجهة الحوكمة). المسار الافتراضي محلي أولاً على جهاز واحد. تواجه مشكلة أثناء الإعداد؟ انتقل إلى دعم التثبيت — خط المساعدة الأول قبل التواصل معنا.

المتطلبات الأساسية

  • Windows 10 فأحدث، أو macOS 12 فأحدث، أو Linux x64
  • VS Code الإصدار 1.85 أو أحدث
  • Ollama للاستدلال المحلي بالنماذج (يمكن لمعالج التشغيل الأول في Engine الربط للتثبيت)
  • مساحة تخزين كافية للتمثيلات المتجهية (دليل تقريبي: 1–3 جيجابايت لكل مستودع متوسط الحجم)
  • اتصال loopback على الشبكة إلى localhost:8000 (منفذ API الافتراضي)

التثبيت المحلي أولاً (موصى به)

  1. نزّل وثبّت ContextMint Engine من صفحة الإصدارات.
  2. افتح Engine من شريط النظام ← شغّل Start all (الخادم + Ollama).
  3. ثبّت إضافة ContextMint من ملف VSIX أو من المتجر.
  4. افتح مجلد مشروعك في VS Code — تسجّل الإضافة مساحة العمل تلقائياً.
  5. انتظر حتى تتجاوز الجاهزية حالتي Offline / Starting؛ قد تستمر الفهرسة في الخلفية.

شرح سريع: البدء (5 دقائق). يرتبط معالج التشغيل الأول في Engine أيضاً بهذه الصفحة عند حدوث فشل.

معالج التشغيل الأول (Engine)

عند التشغيل الأول، قد يطلب Engine:

  • مسار Python / الخلفية (يُكتشف تلقائياً عادةً في الحزم المُجمّعة)
  • رابط Ollama ونماذج التضمين والمحادثة الافتراضية
  • ما إذا كان يجب تشغيل الخادم وOllama عند تسجيل الدخول (تشغيل تلقائي اختياري)

أكمل المعالج قبل توقّع وصول المحادثة إلى حالة Ready أو Limited. تتضمن كل خطوة في المعالج رابط مساعدة التثبيت إلى هذه الصفحة.

تسجيل مساحة العمل

يحصل كل مجلد مفتوح على معرّف مساحة عمل ثابت (12 حرفاً سداسي عشري). تستدعي الإضافة POST /set-workspace مع مسار المجلد ومسارات المحررات المفتوحة حتى تعطي الفهرسة أولوية للملفات التي تحرّرها. لا تحتاج لضبط هذا يدوياً في الاستخدام العادي.

خادم داخل البنية المحلية (تجربة مؤسسية)

قد تنشر فرق المنصة حزمة API على مضيف داخلي مع استدلال متوافق مع OpenAI (عادةً vLLM) — وليس فقط «Ollama مشتركة». يوجّه المطوّرون الإضافة إلى ذلك الرابط:

  • ContextMint.serverUrl — عنوان API الأساسي للفريق (HTTPS)
  • ContextMint.enterpriseMode — فعّله عند اشتراط مصادقة الخادم
  • إعداد OIDC / JWT حسب مزوّد الهوية لديكم

لا تشغّل الإضافة Engine في هذا الوضع. يجب أن تتطابق مسارات المستودع (Remote SSH أو أحجام تركيب مطابقة). التفاصيل الكاملة: نشر الخادم السيادي, BYOK والمؤسسات, و الثقة والأمان.

التحقق من التثبيت

  • Engine ← نظرة عامة تُظهر الخادم Running
  • شريط حالة VS Code: ContextMint | Ready (أو Indexing / Limited)
  • المتصفح: http://localhost:8000/api/health يُرجع OK (محلي أولاً)

دعم التثبيت (الخط الأول)

استخدم هذا القسم عندما لا يطابق الإعداد المسار السلس أعلاه. اتّبع العرَض الذي يطابق ما تراه في Engine أو VS Code. فقط بعد هذه الخطوات صدّر حزمة دعم و راسلنا عبر البريد anis@contextmint.ai.

دليل القرار

  1. صينية Engine غير ظاهرة؟ ← تحقق من قائمة الصينية الفائضة؛ أعد تشغيل Engine من قائمة ابدأ.
  2. فشل Start all؟ ← تبويب السجلات + تعارض المنفذ 8000 ← أعد تشغيل الجهاز ← أعد تثبيت حزمة Engine.
  3. الإضافة تُظهر Offline؟ ← Engine غير قيد التشغيل أو serverUrl غير صحيح.
  4. عالق على Starting في VS Code؟ ← أعد تحميل النافذة؛ Engine ← الخادم ← أعد تشغيل الخادم.
  5. Limited / Ollama غير متصل؟ ← ثبّت Ollama؛ Engine ← Ollama ← Start؛ اسحب النماذج من تبويب Models.
  6. أخطاء فهرسة؟ ← Engine ← تفاصيل الفهرسة؛ أصلح الأذونات؛ أعد فهرسة مساحة العمل.

المحرك والخادم

«Start all» لا يفعل شيئاً أو يفشل فوراً

جرّب:

  1. Engine ← السجلات (Logs) — ابحث عن تتبّع أخطاء Python أو «address already in use».
  2. أوقف الكل ← أغلق Engine ← تأكد من عدم وجود عملية contextmint / python عالقة على المنفذ 8000.
  3. Engine ← الإعدادات — تأكد أن مسار الخلفية يشير إلى الخادم المرفق (التثبيت المُجمّع).
  4. أعد تثبيت أحدث إصدار من Engine إذا كان ملف الخادم مفقوداً.

لا تزال عالقاً؟ استكشاف أخطاء Engine · صدّر حزمة الدعم من About.

رابط الصحة لا يُحمَّل في المتصفح

جرّب: Engine ← نظرة عامة ← تأكد أن الخادم Running. استخدم الرابط الدقيق من الإعدادات (الافتراضي http://127.0.0.1:8000). عطّل أي VPN/وكيل يمنع loopback. في وضع الخادم المشترك، استخدم رابط HTTPS الخاص بفريقكم بدلاً منه.

Ollama والنماذج

Ollama غير مكتشف / وضع Limited في VS Code

جرّب:

  1. ثبّت من ollama.com/download.
  2. Engine ← Ollama ← Start أو Restart.
  3. Engine ← Models ← اسحب نماذج التضمين والمحادثة الموصى بها.
  4. شغّل Start all مرة أخرى؛ انتظر حتى تختفي تحذيرات Ollama من الجاهزية في النظرة العامة.
تم سحب النماذج لكن المحادثة لا تزال تُخطئ

جرّب: تأكد أن أسماء النماذج في Engine Models تطابق إعدادات الخادم الافتراضية. أعد تشغيل الخادم بعد تغيير نموذج التضمين (قد يتطلب إعادة فهرسة). اختبر برسالة قصيرة «hi» في وضع Ask.

إضافة VS Code

الإضافة مثبّتة لكن لا توجد أيقونة ContextMint

جرّب: فعّل الإضافة من لوحة Extensions. أعد تحميل النافذة. تحقق من Output ← ContextMint بحثاً عن أخطاء التفعيل. تأكد أن إصدار VS Code ≥ 1.85.

المحادثة محظورة — «server offline» أو «starting»

جرّب:

  1. Engine ← Start all (محلي أولاً).
  2. الإعدادات ← يجب أن يطابق ContextMint.serverUrl إعداد Engine (عادةً http://localhost:8000).
  3. أعد تحميل نافذة VS Code بعد أن يصبح الخادم سليماً.

ملاحظة: لا تمنع الفهرسة المحادثة — فقط حالات offline/starting/error تمنعها.

الخادم المؤسسي المشترك — أخطاء 401 أو مسارات

جرّب: فعّل enterpriseMode، وأعد مصادقة SSO، وحاذِ مسارات المستودع مع الخادم (Remote SSH). راجع BYOK والمؤسسات.

الفهرسة أثناء التثبيت

الفهرسة عالقة عند 0% أو تُظهر أخطاء

جرّب: Engine ← الفهرسة ← افتح تفاصيل مساحة العمل. تحقق من مساحة القرص وأذونات القراءة. استثنِ المجلدات الكبيرة عبر .gitignore / .contextmintignore. أعد الفهرسة يدوياً من بطاقة مساحة العمل في النظرة العامة.

متى تُصعّد المشكلة

  1. Engine ← About ← Download support bundle (أو تبويب Logs).
  2. دوّن إصدار Engine ونظام التشغيل والخطوات التي جربتها بالفعل من هذه الصفحة.
  3. راسلنا عبر anis@contextmint.ai أو افتح مشكلة على GitHub لإصدارات الإطلاق.
  4. شركاء التصميم: استخدموا قناة الهندسة المخصصة لكم.

فهرس الأعراض الأوسع: استكشاف الأخطاء الكامل · كل توثيق المستخدم · مركز الدعم