> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wolffi.sh/llms.txt
> Use this file to discover all available pages before exploring further.

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

> المشاكل الشائعة وكيفية إصلاحها

# ابحث عن مشكلتك

المشاكل الشائعة وحلولها. ابدأ بالمشكلة التي تتطابق مع أعراضك.

<AccordionGroup>
  <Accordion title="وولف فيش لا يستجيب على الإطلاق">
    **الأعراض**: تكتب رسالة ولا يحدث شيء. لا استجابة، لا خطأ.

    **تحقق من هذه بالترتيب:**

    1. **حالة المزود** — افتح الإعدادات وتأكد أن مزود LLM الخاص بك مُهيأ ويمكن الوصول إليه. إذا كنت تستخدم مزوداً سحابياً (OpenAI أو Anthropic)، تحقق من صفحة حالتهم.

    2. **هل Ollama يعمل** — إذا كنت تستخدم نموذجاً محلياً، تأكد أن Ollama يعمل:
       ```bash theme={null}
       curl http://localhost:11434/api/tags
       ```
       إذا انتهت المهلة، شغّل Ollama: `ollama serve`

    3. **سجلات التطبيق** — تحقق من سجلات Electron للأعطال:
       ```bash theme={null}
       ls -lt ~/.wolffish/logs/
       cat ~/.wolffish/logs/main.log
       ```
       ابحث عن استثناءات غير مُعالجة أو أخطاء اتصال.

    4. **سجل الأحداث** — إذا بدا التطبيق متجاوباً لكن LLM لا يرد، تحقق مما إذا كانت الأحداث تُطلق:
       ```bash theme={null}
       tail -20 ~/.wolffish/workspace/brain/corpus/$(date +%Y-%m-%d).log.md
       ```
       إذا رأيت `input.received` لكن لا `llm.response`، فاستدعاء المزود معلق أو فاشل.
  </Accordion>

  <Accordion title="الوكيل لا يستخدم قدرتي">
    **الأعراض**: أنشأت قدرة لكن وولف فيش لا يستخدمها أبداً.

    **تحقق من هذه:**

    1. **مُحفزات SKILL.md** — افتح SKILL.md الخاص بقدرتك وتحقق من حقل `triggers` في الواجهة. يجب أن تتطابق المُحفزات مع أنواع الرسائل التي ترسلها. مثال:
       ```yaml theme={null}
       triggers:
         - "deploy"
         - "push to production"
         - "release"
       ```

    2. **لقطة التصحيح** — أرسل رسالة يجب أن تُفعّل القدرة، ثم تحقق من أحدث لقطة تصحيح:
       ```bash theme={null}
       ls -t brain/prefrontal/.debug/ | head -1
       ```
       افتحها وانظر في قسم `<skills>`. هل قدرتك مُدرجة؟ إذا لا، فدرجة صلتها كانت تحت العتبة.

    3. **هل حمّلها cerebellum** — تحقق من سجل الأحداث لأحداث `capability.loaded` أو `capability.error`:
       ```bash theme={null}
       grep "capability" brain/corpus/$(date +%Y-%m-%d).log.md
       ```
       إذا رأيت `capability.error`، فإن SKILL.md به مشكلة في التحليل (واجهة تالفة، حقول مطلوبة مفقودة).

    4. **خفّض العتبة** — إذا سجلت المهارة درجة قريبة لكن ليست فوق العتبة الافتراضية، إما أضف مزيداً من المُحفزات أو خفّض `ras.threshold` في `config.json`.
  </Accordion>

  <Accordion title="استدعاءات الأدوات تُحظر دائماً">
    **الأعراض**: كل استدعاء أداة يُطلق تأكيد أمان أو يُرفض.

    **تحقق من هذه:**

    1. **danger\_patterns في SKILL.md** — يفحص `amygdala` معاملات الأداة مقابل تعبيرات `danger_patterns` النمطية المُعرّفة في SKILL.md الخاص بالقدرة. إذا كانت أنماطك واسعة جداً، ستتطابق مع كل شيء:
       ```yaml theme={null}
       danger_patterns:
         - "rm\\s+-rf"        # Good: specific
         - "rm"               # Bad: matches "format", "inform", etc.
       ```

    2. **confirm\_patterns** — هذه تتطلب تأكيد المستخدم لكن لا تحظر. إذا أردت تشغيل الأداة بدون سؤال، أزل النمط المطابق من `confirm_patterns`.

    3. **إعداد التجاوز** — للتطوير، يمكنك تعطيل تأكيدات الأمان في الإعدادات. هذا يتخطى بوابة amygdala بالكامل.

    <Warning>
      عطّل الأمان في التطوير فقط. في الاستخدام العادي، بوابة الأمان تمنع العمليات المدمرة.
    </Warning>
  </Accordion>

  <Accordion title="الذاكرة تبدو خاطئة أو قديمة">
    **الأعراض**: يشير وولف فيش إلى معلومات خاطئة أو قديمة أو من سياق غير صحيح.

    **أصلحها مباشرة:**

    1. **اقرأ ملف الحلقة** — الحلقات هي Markdown عادي. ابحث عن الذاكرة المعيبة:
       ```bash theme={null}
       grep -r "wrong information" brain/hippocampus/episodes/
       ```

    2. **عدّلها أو احذفها** — افتح ملف الحلقة وأصلح المحتوى، أو احذف الملف بالكامل. الحلقات مجرد Markdown — عدّلها مثل أي ملف آخر.

    3. **أعد بناء الفهرس** — بعد تعديل الحلقات، يصبح فهرس cortex قديماً. احذفه وسيعيد وولف فيش بناءه عند إعادة التشغيل التالية:
       ```bash theme={null}
       rm brain/cortex/cortex.db
       ```
       عند التشغيل التالي، يعيد cortex فهرسة جميع ملفات الحلقات من الصفر.
  </Accordion>

  <Accordion title="السياق كبير جداً / الاستجابات بطيئة">
    **الأعراض**: يستغرق وولف فيش وقتاً طويلاً للاستجابة، أو ترى تحذيرات ميزانية الرموز.

    **تحقق من هذه:**

    1. **تحذيرات hypothalamus** — ابحث عن أحداث الصحة:
       ```bash theme={null}
       grep "health" brain/corpus/$(date +%Y-%m-%d).log.md
       ```
       التحذيرات حول استخدام الرموز تعني أن نافذة السياق ممتلئة تقريباً.

    2. **قلل المهارات المُحمّلة** — إذا كانت قدرات كثيرة تتطابق مع كل رسالة، فمحتويات SKILL.md الخاصة بها تستهلك رموزاً. اجعل المُحفزات أكثر تحديداً حتى تُحمّل مهارات أقل في كل دور.

    3. **ارفع عتبة RAS** — في `config.json`، ارفع `ras.threshold` (الافتراضي 0.3) لتكون أكثر انتقائية فيما يُضمن في السياق:
       ```json theme={null}
       {
         "ras": {
           "threshold": 0.5
         }
       }
       ```

    4. **تحقق من حجم لقطة التصحيح** — تعليق ميزانية الرموز في أعلى كل لقطة تصحيح يُظهر الاستخدام. إذا هيمن `<memory>` أو `<skills>`، قلل تلك الأقسام.
  </Accordion>

  <Accordion title="Telegram / WhatsApp لا يتصل">
    **الأعراض**: القناة تظهر كمنفصلة، الرسائل لا تُستقبل.

    **لـ Telegram:**

    1. تأكد أن رمز البوت في الإعدادات صحيح
    2. تحقق من الاتصال بالإنترنت
    3. ابحث عن أخطاء الاتصال:
       ```bash theme={null}
       grep "telegram\|channel" ~/.wolffish/logs/main.log
       ```
    4. بوتات Telegram تتطلب الاستقصاء — إذا كان وولف فيش غير متصل، يعيد الاتصال تلقائياً عند إعادة التشغيل

    **لـ WhatsApp:**

    1. يجب مسح رمز QR في الإعدادات بهاتفك
    2. تنتهي الجلسة إذا كان هاتفك غير متصل لأكثر من 14 يوماً — أعد مسح رمز QR
    3. تحقق من أخطاء الجلسة في السجلات:
       ```bash theme={null}
       grep "whatsapp\|wa-web" ~/.wolffish/logs/main.log
       ```
  </Accordion>

  <Accordion title="الإضافة تُطلق أخطاء">
    **الأعراض**: إضافة قدرة تفشل في التحميل أو الأدوات تُخطئ أثناء التشغيل.

    **تحقق من هذه:**

    1. **بنية التصدير** — `plugin/index.mjs` يجب أن يُصدّر كائناً افتراضياً:
       ```javascript theme={null}
       export default {
         init(context) { ... },
         tools: { ... }
       }
       ```

    2. **أسماء الأدوات تتطابق** — أسماء الأدوات في الإضافة يجب أن تتطابق تماماً مع الأسماء المُعلنة في قسم `tools:` في واجهة SKILL.md.

    3. **المعاملات تتطابق مع المخطط** — مخطط JSON في SKILL.md يجب أن يتطابق مع ما تتوقعه دالة الإضافة. عدم تطابق الأنواع يسبب فشلاً صامتاً.

    4. **تحقق من سجل الأحداث** — ابحث عن أحداث `capability.error`:
       ```bash theme={null}
       grep "capability.error" brain/corpus/$(date +%Y-%m-%d).log.md
       ```
       رسالة الخطأ عادة تشير إلى المشكلة بالضبط (تصدير مفقود، خطأ صياغة، استيراد تالف).
  </Accordion>

  <Accordion title="cortex.db تالف">
    **الأعراض**: البحث لا يعمل، استرجاع الذاكرة يفشل، أخطاء تذكر SQLite أو FTS5.

    **الإصلاح**: احذف قاعدة البيانات. يعيد وولف فيش بناءها من ملفات Markdown المصدرية عند التشغيل التالي:

    ```bash theme={null}
    rm ~/.wolffish/workspace/brain/cortex/cortex.db
    ```

    ثم أعد تشغيل وولف فيش. يعيد cortex فهرسة جميع ملفات الحلقات من `brain/hippocampus/episodes/` — يستغرق هذا بضع ثوانٍ حسب عدد الحلقات لديك.

    <Info>
      `cortex.db` هو مخرج مُشتق — يمكن إعادة بنائه دائماً من ملفات Markdown. لن تفقد بيانات أبداً بحذفه.
    </Info>
  </Accordion>

  <Accordion title="وولف فيش يستخدم مساحة قرص كبيرة">
    **الأعراض**: استخدام القرص يزداد بمرور الوقت، خاصة في `~/.wolffish/`.

    **تحقق من هذه المواقع:**

    1. **ذاكرة التخزين المؤقت لـ Chromium** — المتصفح المُضمن يُخزّن بقوة:
       ```bash theme={null}
       du -sh ~/.wolffish/runtime/
       ```
       آمن للحذف: `rm -rf ~/.wolffish/runtime/Cache/`

    2. **سجلات الأحداث القديمة** — يجب أن تُنظف تلقائياً بعد 7 أيام، لكن تحقق:
       ```bash theme={null}
       ls -la ~/.wolffish/workspace/brain/corpus/*.log.md
       ```

    3. **تراكم الحلقات** — المثيلات طويلة التشغيل تراكم حلقات. راجع وقلّم القديمة:
       ```bash theme={null}
       du -sh ~/.wolffish/workspace/brain/hippocampus/episodes/
       ls ~/.wolffish/workspace/brain/hippocampus/episodes/ | wc -l
       ```

    4. **لقطات التصحيح** — يجب أن تُنظف تلقائياً، لكن تحقق:
       ```bash theme={null}
       du -sh ~/.wolffish/workspace/brain/prefrontal/.debug/
       ```
  </Accordion>

  <Accordion title="كيفية إعادة تعيين كل شيء (الخيار النووي)">
    إذا لم ينفع أي شيء آخر وتريد البدء من الصفر:

    ```bash theme={null}
    rm -rf ~/.wolffish/
    ```

    <Warning>
      هذا يحذف جميع الإعدادات والذكريات والحلقات والقدرات والسجلات. سيُشغل وولف فيش إعداد التشغيل الأول مرة أخرى. افعل هذا فقط إذا كنت مستعداً لخسارة كل شيء.
    </Warning>

    لإعادة تعيين أقل تدميراً، احذف مجلدات محددة فقط:

    * `rm -rf ~/.wolffish/workspace/brain/cortex/` — إعادة بناء فهرس البحث فقط
    * `rm -rf ~/.wolffish/workspace/brain/hippocampus/episodes/` — مسح جميع الذكريات
    * `rm -rf ~/.wolffish/workspace/brain/corpus/` — مسح سجلات الأحداث
    * `rm -rf ~/.wolffish/workspace/brain/prefrontal/.debug/` — مسح لقطات التصحيح
  </Accordion>
</AccordionGroup>

## الحصول على المساعدة

إذا جربت الخطوات أعلاه والمشكلة مستمرة:

<CardGroup cols={2}>
  <Card title="مشاكل GitHub" icon="github" href="https://github.com/thewolffish/issues">
    ابحث في المشاكل الموجودة أو أنشئ واحدة جديدة. أرفق سجل الأحداث ولقطة التصحيح
    المعنية.
  </Card>

  <Card title="مجتمع Discord" icon="discord" href="https://discord.gg/zWJpD3SgTt">
    اسأل في قناة الدعم. أعضاء المجتمع والمشرفون نشطون هنا.
  </Card>
</CardGroup>

<Tip>
  عند تقديم تقرير خلل، أرفق: 1. لقطة التصحيح من الدور الفاشل 2. القسم المعني من
  سجل الأحداث 3. ملف المهمة (إذا كانت أداة مُتضمنة) 4. ملف `config.json` الخاص
  بك (أخفِ مفاتيح API)
</Tip>