# استكشاف الأخطاء وإصلاحها (/ar/docs/verdent-for-vscode/help-support/common-issues)

> المشكلات الشائعة والتشخيصات والحلول



### ما ستتعلمه [#ما-ستتعلمه]

إجراءات استكشاف الأخطاء الشائعة وخطوات التشخيص وحلول بديلة للمشكلات المعروفة الخاصة بـ Verdent for VS Code.

<Info>
  يجري حاليًا تجميع دليل تفصيلي لاستكشاف أخطاء أكثر المشكلات المُبلَّغ عنها من بيانات الدعم. توفر هذه الصفحة إجراءات تشخيص عامة. تواصل مع [support@verdent.ai](mailto:support@verdent.ai) للمشكلات المحددة غير المذكورة هنا.
</Info>

***

## تشخيص سريع [#تشخيص-سريع]

<Tabs>
  <Tab title="أخطاء الخدمة (الأكثر شيوعًا)">
    ### "الخدمة تشهد ضغطًا مرتفعًا. يرجى المحاولة لاحقًا!" [#الخدمة-تشهد-ضغطًا-مرتفعًا-يرجى-المحاولة-لاحقًا]

    **هذا هو الخطأ الأكثر شيوعًا رقم 1** الذي يواجهه المستخدمون. يشير إلى أن خدمة Verdent محمّلة بشكل زائد مؤقتًا.

    **متى يحدث:**

    * خلال أوقات الاستخدام المرتفع
    * عندما تكون الخدمات الخلفية تحت ضغط كبير
    * تدهور مؤقت في الخدمة

    **خطوات الاستعادة (بالترتيب):**

    <Steps>
      <Step title="التراجع عن الرسالة" stepNumber="1">
        إذا استمر الخطأ، تراجع عن أحدث رسالة:

        * انقر على زر التراجع/الإلغاء في واجهة الدردشة
        * أعد إرسال طلبك بعد انتظار قصير
      </Step>

      <Step title="بدء جلسة جديدة" stepNumber="2">
        إذا استمرت الأخطاء، ابدأ جلسة جديدة:

        * حدد زر "+" (جلسة جديدة) في الشريط العلوي
        * يؤدي ذلك إلى مسح السياق وموافقات الأدوات
        * أعد إرسال طلبك في الجلسة النظيفة
      </Step>

      <Step title="الانتظار وإعادة المحاولة" stepNumber="3">
        انتظر 30-60 ثانية وحاول إرسال طلبك مرة أخرى. تُحل معظم مشكلات الخدمة بسرعة.
      </Step>
    </Steps>

    <Warning>
      إذا استمرت المشكلة لأكثر من 5-10 دقائق عبر جلسات متعددة، تحقق من \[صفحة حالة [Verdent](https://verdent.ai/status) أو تواصل مع [support@verdent.ai](mailto:support@verdent.ai).
    </Warning>
  </Tab>

  <Tab title="التثبيت والإعداد">
    ### مشكلات التثبيت والإعداد [#مشكلات-التثبيت-والإعداد]

    **متطلبات النظام:**

    * **إصدار VS Code:** 1.90.0 أو أحدث (مطلوب)
    * **اتصال الإنترنت:** مطلوب اتصال نشط
    * **الاشتراك:** اشتراك Verdent نشط

    **قائمة تشخيص أساسية:**

    1. **التحقق من إصدار VS Code:** المساعدة ← حول (يجب أن يكون 1.90.0 أو أحدث)
    2. **التحقق من اتصال الإنترنت:** يتطلب Verdent اتصالًا نشطًا
    3. **التحقق من الاشتراك:** تأكد من أن اشتراك Verdent نشط
    4. **إعادة تشغيل VS Code:** بعد التثبيت أو تغييرات الإعداد
    5. **التحقق من حالة الإضافة:** عرض ← الإضافات ← Verdent (يجب أن تظهر "مفعّلة")

    **إجراء إعادة التثبيت النظيف:**

    <Steps>
      <Step title="إلغاء تثبيت Verdent">
        عرض ← الإضافات ← Verdent ← إلغاء التثبيت
      </Step>

      <Step title="إعادة تشغيل VS Code">
        أغلق VS Code تمامًا وأعد فتحه
      </Step>

      <Step title="إعادة تثبيت Verdent">
        عرض ← الإضافات ← ابحث عن "Verdent" ← تثبيت
      </Step>
    </Steps>

    **التحقق من السجلات:**

    * افتح لوحة المخرجات: عرض ← المخرجات
    * حدد "Verdent" من القائمة المنسدلة
    * ابحث عن رسائل الأخطاء أو تتبعات المكدس

    <Info>
      تُحل معظم مشكلات التثبيت بإعادة تحميل بسيطة لـ VS Code أو إعادة تثبيت نظيفة. إذا استمرت المشكلات، تحقق من السجلات وتواصل مع الدعم مع تفاصيل السجل.
    </Info>
  </Tab>

  <Tab title="المصادقة والحساب">
    ### تعذّر تسجيل الدخول إلى Verdent for VS Code [#تعذّر-تسجيل-الدخول-إلى-verdent-for-vs-code]

    **السبب الأكثر شيوعًا:** مشكلة في إعداد الوكيل الوسيط (proxy)

    **الحل:**

    <Steps>
      <Step title="افتح إعدادات VS Code">
        اضغط `Cmd+,` (macOS) أو `Ctrl+,` (Windows/Linux)
      </Step>

      <Step title="ابحث عن إعداد الوكيل الوسيط">
        ابحث عن "useProxy" أو "verdent.enableProxy" في شريط بحث الإعدادات
      </Step>

      <Step title="بدّل حالة الوكيل الوسيط">
        بدّل إعداد الوكيل الوسيط تشغيلًا/إيقافًا (عكس الحالة الحالية)
      </Step>

      <Step title="أعد محاولة تسجيل الدخول">
        حاول تسجيل الدخول إلى Verdent مرة أخرى
      </Step>
    </Steps>

    <Info>
      إذا كنت خلف جدار حماية للشركة، فقد تحتاج إلى تفعيل إعداد الوكيل الوسيط. إذا كنت على شبكة منزلية، جرّب تعطيله.
    </Info>

    ***

    ### عدم استلام أرصدة النسخة التجريبية المجانية [#عدم-استلام-أرصدة-النسخة-التجريبية-المجانية]

    **الخطأ:** لم يتم استلام أرصدة النسخة التجريبية المجانية أو تم رفض الوصول إلى النسخة التجريبية المجانية

    **السبب:** تم اكتشاف انتهاك لشروط الخدمة أثناء التسجيل

    **الحل:** تواصل مع [support@verdent.ai](mailto:support@verdent.ai) للحصول على مساعدة بخصوص وصولك إلى النسخة التجريبية المجانية. سيراجع فريق الدعم حسابك ويساعد في حل المشكلة.

    ***

    ### فشل التسجيل [#فشل-التسجيل]

    **الخطأ:** تم رفض تسجيل الحساب أو تقييده

    **السبب:** انتهك التسجيل شروط خدمة Verdent، مما أدى إلى تقييد الوصول

    **الحل:** تواصل مع [support@verdent.ai](mailto:support@verdent.ai) للحصول على المساعدة. يمكن لفريق الدعم مراجعة تسجيلك وتقديم إرشادات لحل المشكلة.

    ***

    ### نماذج مفقودة (Claude، GPT، Gemini) [#نماذج-مفقودة-claude-gpt-gemini]

    **المشكلة:** تعذّر العثور على نماذج Claude أو GPT أو Gemini في اختيار النموذج

    **السبب:** قيود جغرافية من مزوّدي النماذج

    **الشرح:** يفرض بعض مزوّدي نماذج الذكاء الاصطناعي قيودًا إقليمية تمنع توفر نماذج معينة في مواقع جغرافية محددة. عند حدوث ذلك:

    * لن تظهر النماذج المقيَّدة في قائمة اختيار النموذج
    * يمكنك الاستمرار في استخدام جميع النماذج المتاحة الأخرى دون انقطاع
    * لا تأثير على اشتراكك أو أرصدتك

    **التحقق من النماذج المتاحة:** زر [https://www.verdent.ai/regions](https://www.verdent.ai/regions) لمعرفة النماذج المتاحة في منطقتك

    <Note>
      يتم تحديد القيود الإقليمية من قِبل مزوّدي نماذج الذكاء الاصطناعي (Anthropic، OpenAI، Google)، وليس من قِبل Verdent. لا يمكن لـ Verdent تجاوز هذه القيود.
    </Note>
  </Tab>

  <Tab title="الأداء">
    ### مشكلات الأداء [#مشكلات-الأداء]

    **الأعراض:**

    * أوقات استجابة بطيئة
    * أخطاء امتلاء نافذة السياق
    * انتهاء مهلة تنفيذ الأدوات

    **الأسباب والحلول الشائعة:**

    | المشكلة             | السبب                               | الحل                                                                       |
    | ------------------- | ----------------------------------- | -------------------------------------------------------------------------- |
    | استجابات بطيئة      | قراءة ملفات كبيرة                   | استخدم نطاقات الأسطر: `file_read("file.js", start_line=100, max_lines=50)` |
    | امتلاء السياق       | سجل محادثة طويل                     | التفويض إلى وكلاء فرعيين أو بدء محادثة جديدة                               |
    | انتهاء مهلة الأدوات | أوامر bash طويلة التنفيذ            | ضبط مهلة صريحة أو تقسيمها إلى أوامر أصغر                                   |
    | استخدام ذاكرة مرتفع | عدد كبير جدًا من العمليات المتوازية | الحد من عمليات تنفيذ الأدوات المتزامنة                                     |

    <Tip>
      فوّض المهام الاستكشافية إلى الوكيل الفرعي @Explorer للحفاظ على السياق الرئيسي.
    </Tip>
  </Tab>

  <Tab title="أخطاء الصور">
    ### رسائل الأخطاء المتعلقة بالصور [#رسائل-الأخطاء-المتعلقة-بالصور]

    **مرجع سريع لأخطاء معالجة الصور الشائعة:**

    | رسالة الخطأ                 | السبب                                                          | الحل                                          |
    | --------------------------- | -------------------------------------------------------------- | --------------------------------------------- |
    | **نوع صورة غير مدعوم**      | فقط صور JPEG وPNG وGIF أو WebP مدعومة                          | تراجع وغيّر نوع الصورة إلى صيغة مدعومة        |
    | **أبعاد الصورة كبيرة جدًا** | لا يمكن أن يتجاوز عرض الصورة أو ارتفاعها 8000 بكسل             | تراجع واضبط أبعاد الصورة إلى 8000×8000 أو أقل |
    | **المُدخل طويل جدًا**       | يتجاوز المُدخل الحد الأقصى المسموح به لطول النموذج             | بسّط مُدخلك أو قلّل حجم الصورة                |
    | **الملف كبير جدًا للغاية**  | لا يمكن أن يتجاوز حجم الصورة 5 ميغابايت                        | تراجع وأرسل صورة مضغوطة (بحد أقصى 5 ميغابايت) |
    | **صورة غير قابلة للقراءة**  | تعذّرت معالجة الصورة، قد يكون الملف تالفًا أو بصيغة غير مدعومة | تراجع واستبدل الصورة بملف صالح                |
  </Tab>
</Tabs>

***

## مشكلات خاصة بالأدوات [#مشكلات-خاصة-بالأدوات]

<Tabs>
  <Tab title="أخطاء file_edit">
    ### أخطاء file\_edit [#أخطاء-file_edit]

    **الخطأ:** "تعذّر العثور على تطابق دقيق"

    **الأسباب:**

    * تغيّر النص منذ آخر عملية file\_read
    * اختلافات في المسافات البيضاء (مسافات جدولة مقابل مسافات عادية)
    * النص غير فريد في الملف

    **الحلول:**

    ```bash
    # 1. Read file again to get current state
    file_read("file.js")

    # 2. Use larger context string for uniqueness
    file_edit("file.js",
      old_string="function foo() {\n  return 42;\n}",
      new_string="...")

    # 3. For multiple identical strings, use replace_all
    file_edit("file.js", old_string="TODO", new_string="DONE", replace_all=true)
    ```

    <Warning>
      اقرأ الملف دائمًا مباشرة قبل التعديل لضمان الحصول على الحالة الحالية.
    </Warning>
  </Tab>

  <Tab title="أخطاء bash">
    ### أخطاء أوامر bash [#أخطاء-أوامر-bash]

    **الخطأ:** انتهاء مهلة الأمر أو فشل التنفيذ

    **الحد الأقصى للمهلة:** 120 ثانية (دقيقتان، حد صارم)

    **الحل:** قسّم الأوامر الطويلة إلى عمليات أصغر:

    ```bash
    # Instead of one long command, break into steps
    bash("step1")  # Completes in < 2min
    bash("step2")  # Completes in < 2min
    ```

    **الأمر غير موجود:**

    * تحقق من وجود الأمر: `bash("which command-name")`
    * تأكد من صحة المسار أو فعّل البيئة أولًا
    * استخدم المسارات الكاملة للملفات التنفيذية

    **أخطاء الأذونات:**

    * تُنفَّذ الأوامر بأذونات المستخدم
    * استخدم `sudo` فقط عند الضرورة وفي Manual Accept Mode
    * تحقق من أذونات الملفات/الدلائل
  </Tab>

  <Tab title="مشكلات البحث">
    ### البحث لا يُعيد أي نتائج [#البحث-لا-يُعيد-أي-نتائج]

    **المشكلة:** لا تجد grep\_file أو glob الملفات المتوقعة

    **تحقق من صيغة النمط:**

    ```bash
    # Wrong
    grep_file("*.ts")  # Missing ** for recursive

    # Correct
    grep_file("**/*.ts")  # Recursive search
    ```

    **تحقق من الاستثناءات:**

    ```bash
    # Ensure not accidentally excluding target files
    glob("**/*.js", exclude=["**/dist/**", "**/node_modules/**"])
    ```

    **حساسية حالة الأحرف:**

    ```bash
    # Use case-insensitive search if needed
    grep_content("pattern", case_insensitive=true)
    ```
  </Tab>
</Tabs>

***

## مشكلات الوكلاء الفرعيين والإعدادات [#مشكلات-الوكلاء-الفرعيين-والإعدادات]

<Tabs>
  <Tab title="عدم استدعاء الوكيل الفرعي">
    ### عدم استدعاء الوكيل الفرعي [#عدم-استدعاء-الوكيل-الفرعي]

    **المشكلة:** لا يُفعّل الوكيل الفرعي المخصص تلقائيًا

    **قائمة التحقق:**

    * موقع الملف: `~/.verdent/subagents/[name].md`
    * ترويسة YAML صالحة تتضمن `name` و`description`
    * سياسة الاستدعاء تطابق الاستخدام (الوضع الصارم يتطلب إشارة @-mention)
    * إرشادات "متى تُستخدم" تطابق نمط الطلب
    * لا توجد أخطاء صياغية في ملف markdown

    **اختبار يدوي:**

    ```
    @subagent-name perform task
    ```

    <Tip>
      استخدم إشارة @-mention صريحة للتحقق من عمل الوكيل الفرعي قبل استكشاف مشكلة الاستدعاء التلقائي.
    </Tip>
  </Tab>

  <Tab title="الوكلاء الفرعيون المدمجون">
    ### سلوك الوكلاء الفرعيين المدمجين [#سلوك-الوكلاء-الفرعيين-المدمجين]

    **المشكلة:** @Explorer أو @Verifier أو @Code-reviewer لا يعملون كما هو متوقع

    **الأسباب الشائعة:**

    * الطلب لا يطابق تخصص الوكيل الفرعي
    * سياق الوكيل الفرعي ممتلئ (نادر)
    * سياق المحادثة الرئيسية يؤثر في التوجيه

    **الحل:**

    * استخدم إشارة @-mention صريحة لفرض وكيل فرعي محدد
    * أعد صياغة الطلب ليطابق خبرة الوكيل الفرعي
    * ابدأ محادثة جديدة إذا كان السياق يمثل مشكلة
  </Tab>

  <Tab title="قواعد AGENTS.md">
    ### عدم تطبيق AGENTS.md [#عدم-تطبيق-agentsmd]

    **المشكلة:** قواعد المشروع لا تؤثر في سلوك Verdent

    **التشخيص:**

    1. **الموقع:** يجب أن يكون الملف في الدليل الجذر للمشروع
    2. **الصياغة:** Markdown صالح (تحقق من الأخطاء الصياغية)
    3. **الدقة:** يجب أن تكون القواعد توجيهية: "استخدم دائمًا X" وليس "حاول استخدام X"
    4. **الاختبار:** ابدأ محادثة جديدة لاختبار التطبيق الجديد

    **التحقق من الأسبقية:**

    ```markdown
    # In AGENTS.md (highest priority)
    - Use 4-space indentation

    # In VERDENT.md (lower priority)
    - Use 2-space indentation

    # Result: 4-space indentation (AGENTS.md wins)
    ```
  </Tab>

  <Tab title="اتصال MCP">
    ### أخطاء اتصال MCP [#أخطاء-اتصال-mcp]

    **الخطأ:** تعذّر الاتصال بخادم MCP

    **خطوات التشخيص:**

    1. **تحقق من mcp.json:** صياغة JSON صالحة في `~/.verdent/mcp.json`
    2. **تشغيل الخادم:** تأكد من أن عملية خادم MCP نشطة
    3. **الشبكة:** تحقق من الاتصال بنقطة النهاية الخاصة بالخادم
    4. **المصادقة:** تأكد من صحة بيانات الاعتماد
    5. **السجلات:** تحقق من سجلات خادم MCP لمعرفة تفاصيل الخطأ

    **الحلول الشائعة:**

    * أعد تشغيل خادم MCP
    * تحقق من صيغة سلسلة الاتصال
    * تحقق من قواعد جدار الحماية التي تسمح بمرور حركة MCP
    * تحقق من صحة مفاتيح أو رموز API
  </Tab>
</Tabs>

***

## المشكلات المعروفة والحلول البديلة [#المشكلات-المعروفة-والحلول-البديلة]

<Tabs>
  <Tab title="الملفات الثنائية">
    ### قيود الملفات الثنائية [#قيود-الملفات-الثنائية]

    **المشكلة:** تعذّر تعديل الصور أو ملفات PDF أو الملفات الثنائية المُصرَّفة

    **الحل البديل:**

    ```bash
    # Use bash to call external tools
    bash("convert input.png -resize 50% output.png")
    bash("pdftotext document.pdf output.txt")
    ```

    <Info>
      تتطلب تعديلات الملفات الثنائية أدوات خارجية تُستدعى عبر أوامر bash.
    </Info>
  </Tab>

  <Tab title="الملفات الكبيرة">
    ### معالجة الملفات الكبيرة [#معالجة-الملفات-الكبيرة]

    **المشكلة:** الملفات التي تتجاوز 10,000 سطر تسبب مشكلات في السياق

    **الحل البديل:**

    ```bash
    # Always use line ranges for large files
    file_read("large.log", start_line=1000, max_lines=100)

    # Search first to find relevant sections
    grep_content("ERROR", glob="large.log")
    ```

    <Tip>
      ابحث أولًا باستخدام grep\_content لتحديد أرقام الأسطر ذات الصلة، ثم اقرأ فقط تلك النطاقات المحددة.
    </Tip>
  </Tab>

  <Tab title="اختلافات المنصات">
    ### اختلافات الأوامر عبر المنصات [#اختلافات-الأوامر-عبر-المنصات]

    **المشكلة:** تختلف أوامر bash بين Windows وUnix

    **الحل البديل:**

    ```bash
    # Use cross-platform tools when possible
    bash("npm run build")  # Works everywhere

    # Or conditional execution
    bash("if [[ \"$OSTYPE\" == \"linux-gnu\"* ]]; then ...; fi")
    ```

    **أفضل ممارسة:** استخدم نصوص npm لضمان التوافق عبر المنصات.
  </Tab>
</Tabs>

***

## الحصول على مساعدة إضافية [#الحصول-على-مساعدة-إضافية]

### قنوات الدعم [#قنوات-الدعم]

**للمشكلات المحددة غير المذكورة هنا:**

* **البريد الإلكتروني:** [support@verdent.ai](mailto:support@verdent.ai)
* **Discord:** [انضم إلى مجتمع Verdent](https://discord.com/invite/NGjXEZcbJq) للحصول على دعم فوري
* **مشكلات GitHub:** أبلغ عن الأخطاء أو اطلب ميزات جديدة

**عند الإبلاغ عن المشكلات، أدرج:**

1. إصدار Verdent (من لوحة الإضافات)
2. إصدار VS Code
3. نظام التشغيل
4. رسائل الخطأ (النص الدقيق)
5. خطوات إعادة إنتاج المشكلة
6. السلوك المتوقع مقابل السلوك الفعلي

***

### جمع معلومات التشخيص [#جمع-معلومات-التشخيص]

**لمساعدة الدعم في التشخيص:**

```bash
# VS Code version
bash("code --version")

# System info
bash("uname -a")  # Unix
bash("systeminfo")  # Windows

# Verdent logs location
# Check VS Code Output panel → Verdent
```

***

## اطلع أيضًا على [#اطلع-أيضًا-على]

<CardGroup cols="2">
  <Card title="الأسئلة الشائعة" icon="circle-question" href="/docs/verdent-for-vscode/help-support/faqs">
    الأسئلة الشائعة
  </Card>

  <Card title="القيود" icon="triangle-exclamation" href="/docs/verdent-for-vscode/help-support/limitations">
    القيود والمحدّدات المعروفة
  </Card>
</CardGroup>