الأسئلة الشائعة لاستكشاف الأخطاء

حلول لمشكلات Synapse الشائعة.

لا أستطيع تسجيل الدخول

الأعراض

• يُرجع POST /login 401
• "Invalid email or password"

الحلول

1. تحقق أن البريد الإلكتروني صحيح — حساس لحالة الأحرف
2. تحقق من كلمة المرور — 6 أحرف كحد أدنى
3. سجّل أولًا إذا لم يكن لديك حساب: POST /register
4. أعد تعيين كلمة المرور (إذا كان SMTP مُعدًا) عبر واجهة الويب

فقدت Mind Key

الأعراض

• لا أستطيع الوصول إلى الذكريات
• حُذف Mind Key أو فُقد

الحلول

لا يمكن استرداد Mind Keys. يجب أن:

1. تسجّل الدخول للحصول على JWT: POST /login
2. تسرد العقول: GET /minds (مع JWT)
3. تنشئ عقلًا جديدًا: POST /minds
4. تحفظ Mind Key الجديد
5. (اختياري) تحذف العقل القديم: DELETE /minds/:id

البيانات في العقل القديم فقدت إلا إذا وجدت Mind Key.

استدعاءات الـ API تُرجع 401

الأعراض

• جميع استدعاءات الـ API تُرجع 401 Unauthorized
• "Mind Key fehlt oder ungültig"

الحلول

1. تحقق من تنسيق الترويسة: Authorization: Bearer mk_...
2. تحقق أن Mind Key يبدأ بـ mk_ (وليس eyJ وهو JWT)
3. اختبر مباشرة:

   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall

4. قد يكون Mind Key مُبطَلًا — أنشئ عقلًا جديدًا

راجع المصادقة.

استدعاءات الـ API تُرجع 404

الأعراض

• 404 Not Found
• "Route not found"

الحلول

1. تحقق من نقاط النهاية الصالحة: curl https://synapse.schaefer.zone/endpoints
2. قارن عنوان URL بدقة — حساس لحالة الأحرف، بلا شرطات مائلة لاحقة
3. تحقق من طريقة HTTP — GET /memory مقابل POST /memory مختلفة

استدعاءات الـ API تُرجع 429

الأعراض

• 429 Too Many Requests
• "Rate limit exceeded"

الحلول

1. بدّل إلى مصادقة الترويسة (بلا حد معدل):

   # لا تفعل
   curl ".../memory/recall?key=mk_..."
   
   # افعل
   curl -H "Authorization: Bearer mk_..." .../memory/recall

2. انتظر Retry-After ثانية إذا وجب استخدام ?key=

راجع حدود المعدل.

بحث الذاكرة يُرجع نتائج فارغة

الأعراض

• يُرجع GET /memory/search?q=... فارغًا
• أعرف أن الذكريات موجودة

الحلول

1. تحقق من وجود الذكريات: GET /memory/recall
2. تحقق من صياغة البحث — لـ FTS5 صياغة محددة
3. جرّب استعلامًا أبسط — ?q=docker بدلًا من ?q=docker+swarm+deployment
4. استخدم البحث الدلالي للاستعلامات المفاهيمية: GET /memory/semantic-search?q=...

راجع بحث FTS5.

الذكريات لا تستمر

الأعراض

• يُرجع POST /memory نجاحًا
• لا يُظهرها GET /memory/recall

الحلول

1. تحقق من نفس Mind Key — مفاتيح مختلفة = عقول مختلفة
2. تحقق من الاستجابة — يُرجع POST { "id": "mem_...", "status": "stored" }
3. جرّب GET /memory (قائمة JSON) بدلًا من /memory/recall (نص)
4. تحقق من المرشّح — ?category= أو ?tag= قد يخفيها

الأدوات لا تظهر في Claude Desktop

الأعراض

• يُظهر Claude Desktop 0 أدوات
• لا توجد أيقونة 🔌

الحلول

1. أعد تشغيل Claude Desktop بالكامل (Cmd+Q)
2. تحقق أن ملف الإعداد JSON صالح
3. تحقق من Node.js 18+ مثبت
4. شغّل MCP يدويًا: npx -y synapse-mcp-api@latest
5. تحقق من السجلات: ~/Library/Logs/Claude/mcp.log

راجع استكشاف أخطاء MCP.

Synapse غير متصل

الأعراض

• لا يمكن الوصول إلى synapse.schaefer.zone
• curl ينتهي بانتهاء المهلة

الحلول

1. تحقق من إنترنتك — جرّب موقعًا آخر
2. تحقق من صحة Synapse: curl https://synapse.schaefer.zone/health
3. انتظر — قد يكون انقطاعًا مؤقتًا أو نشرًا
4. تحقق من صفحة الحالة (إن وُجدت)

للاستضافة الذاتية: تحقق من حالة حاوية Docker، اتصال قاعدة البيانات.

أخطاء قاعدة البيانات

الأعراض

• 500 Internal Server Error
• "Database connection failed"

الحلول

للاستضافة الذاتية:

1. تحقق من تشغيل PostgreSQL: docker ps | grep postgres
2. تحقق من DATABASE_URL في البيئة
3. تحقق من الترحيلات: npm run migrate:check
4. تحقق من مساحة القرص: df -h

للمُستضاف: أبلغ الدعم.

الـ Webhook لا يعمل

الأعراض

• سجّلت webhook لكن لا أتلقى استدعاءات
• لا POST إلى عنوان URL الخاص بك

الحلول

1. تحقق أن عنوان URL قابل للوصول: curl -X POST your-url -d '{}'
2. تحقق من مرشّح الأحداث — memory.* يطابق جميع أحداث الذاكرة
3. اختبر الـ webhook: POST /webhooks/:id/test
4. تحقق أن الـ webhook مُمكَّن: GET /webhooks/:id
5. تحقق من SSL — يتطلب Synapse HTTPS صالحًا لعناوين URL للـ webhooks

راجع Webhooks API.

مهمة Cron لا تعمل

الأعراض

• أنشأت مهمة cron لكنها لا تعمل
• next_run لا يُحدّث

الحلول

1. تحقق من صياغة الجدول — يجب أن تكون cron 5 حقول صالح OR عدد ثوانٍ صحيح
2. تحقق أن نقطة النهاية مسموحة — يجب أن تكون http(s)، بلا عناوين IP خاصة
3. تحقق أن المهمة مُمكَّنة: GET /cron
4. انتظر الوقت المجدول التالي — cron ليس فوريًا

راجع Cron والمجدول.

تحتاج مزيدًا من المساعدة؟

1. تحقق من الوثائق الموجودة: https://synapse.schaefer.zone/docs
2. ابحث في الوثائق: GET /docs/search?q=your+question
3. افتح issue: https://gitlab.com/schaefer-services/synapse/-/issues
4. تواصل: راجع صفحة /support

الخطوات التالية

• الأخطاء ومعالجتها
• أسئلة الـ API الشائعة
• استكشاف أخطاء MCP