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

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

---

السجلات

يتم حفظ ملفات السجل في:

• macOS/Linux: ~/.local/share/slopcode/log/
• Windows: اضغط WIN+R والصق %USERPROFILE%\.local\share\slopcode\log

تتم تسمية ملفات السجل بطوابع زمنية (مثل 2025-01-09T123456.log) ويتم الاحتفاظ بأحدث 10 ملفات سجل.

يمكنك ضبط مستوى السجل باستخدام خيار CLI --log-level للحصول على معلومات تصحيح أكثر تفصيلا. على سبيل المثال: slopcode --log-level DEBUG.

---

التخزين

يخزن slopcode بيانات الجلسات وبيانات التطبيق الأخرى على القرص في:

• macOS/Linux: ~/.local/share/slopcode/
• Windows: اضغط WIN+R والصق %USERPROFILE%\.local\share\slopcode

يحتوي هذا الدليل على:

• auth.json - بيانات المصادقة مثل مفاتيح API ورموز OAuth
• log/ - سجلات التطبيق
• project/ - بيانات خاصة بالمشروع مثل بيانات الجلسة والرسائل
  • إذا كان المشروع داخل مستودع Git، فسيتم تخزينه في ./<project-slug>/storage/
  • إذا لم يكن داخل مستودع Git، فسيتم تخزينه في ./global/storage/

---

تطبيق سطح المكتب

يشغل SlopCode Desktop خادما محليا لـ SlopCode (العملية الجانبية slopcode-cli) في الخلفية. معظم المشكلات سببها إضافة لا تعمل بشكل صحيح، أو ذاكرة تخزين مؤقت تالفة، أو إعداد خادم غير صحيح.

فحوصات سريعة

• أغلق التطبيق تماما ثم أعد تشغيله.
• إذا عرض التطبيق شاشة خطأ، انقر Restart وانسخ تفاصيل الخطأ.
• على macOS فقط: قائمة SlopCode -> Reload Webview (يفيد إذا كانت الواجهة فارغة/متجمدة).

---

تعطيل الإضافات

إذا كان تطبيق سطح المكتب يتعطل عند التشغيل، أو يتوقف عن الاستجابة، أو يتصرف بشكل غريب، فابدأ بتعطيل الإضافات.

تحقق من الإعدادات العامة

افتح ملف الإعدادات العام وابحث عن المفتاح plugin.

• macOS/Linux: ~/.config/slopcode/slopcode.jsonc (أو ~/.config/slopcode/slopcode.json)
• macOS/Linux (عمليات تثبيت أقدم): ~/.local/share/slopcode/slopcode.jsonc
• Windows: اضغط WIN+R والصق %USERPROFILE%\.config\slopcode\slopcode.jsonc

إذا كانت لديك إضافات مضبوطة، فقم بتعطيلها مؤقتا بإزالة المفتاح أو ضبطه على مصفوفة فارغة:

{
  "$schema": "https://slopcode.dev/config.json",
  "plugin": [],
}

تحقق من أدلة الإضافات

يمكن لـ SlopCode أيضا تحميل إضافات محلية من القرص. انقلها مؤقتا إلى مكان آخر (أو أعد تسمية المجلد) ثم أعد تشغيل تطبيق سطح المكتب:

• إضافات عامة
  • macOS/Linux: ~/.config/slopcode/plugins/
  • Windows: اضغط WIN+R والصق %USERPROFILE%\.config\slopcode\plugins
• إضافات المشروع (فقط إذا كنت تستخدم إعدادات لكل مشروع)
  • <your-project>/.slopcode/plugins/

إذا عاد التطبيق للعمل، فأعد تفعيل الإضافات واحدة تلو الأخرى لمعرفة أيها يسبب المشكلة.

---

مسح ذاكرة التخزين المؤقت

إذا لم يساعد تعطيل الإضافات (أو كانت عملية تثبيت إضافة عالقة)، فامسح ذاكرة التخزين المؤقت حتى يتمكن SlopCode من إعادة بنائها.

1. أغلق SlopCode Desktop تماما.
2. احذف دليل ذاكرة التخزين المؤقت:

• macOS: Finder -> Cmd+Shift+G -> الصق ~/.cache/slopcode
• Linux: احذف ~/.cache/slopcode (أو شغّل rm -rf ~/.cache/slopcode)
• Windows: اضغط WIN+R والصق %USERPROFILE%\.cache\slopcode

3. أعد تشغيل SlopCode Desktop.

---

إصلاح مشكلات اتصال الخادم

يمكن لـ SlopCode Desktop إما تشغيل خادمه المحلي (افتراضيا) أو الاتصال بعنوان URL لخادم قمت بتهيئته.

إذا ظهرت نافذة “Connection Failed” (أو لم يتجاوز التطبيق شاشة البداية)، فتحقق مما إذا كان هناك عنوان URL مخصص للخادم.

مسح عنوان URL الافتراضي لخادم سطح المكتب

من شاشة Home، انقر اسم الخادم (مع نقطة الحالة) لفتح محدد الخوادم. في قسم Default server، انقر Clear.

إزالة server.port / server.hostname من الإعدادات

إذا كان slopcode.json(c) يحتوي على قسم server، فأزله مؤقتا ثم أعد تشغيل تطبيق سطح المكتب.

تحقق من متغيرات البيئة

إذا كان SLOPCODE_PORT مضبوطا في بيئتك، فسيحاول تطبيق سطح المكتب استخدام ذلك المنفذ للخادم المحلي.

• أزل ضبط SLOPCODE_PORT (أو اختر منفذا متاحا) ثم أعد التشغيل.

---

Linux: مشكلات Wayland / X11

على Linux، قد تتسبب بعض إعدادات Wayland في نوافذ فارغة أو أخطاء في مدير التركيب (compositor).

• إذا كنت تستخدم Wayland وكانت نافذة التطبيق فارغة/يتعطل، فجرّب التشغيل مع OC_ALLOW_WAYLAND=1.
• إذا جعل ذلك الأمور أسوأ، فأزل هذا المتغير وجرّب التشغيل ضمن جلسة X11 بدلا من ذلك.

---

Windows: بيئة تشغيل WebView2

على Windows، يتطلب SlopCode Desktop وجود WebView2 Runtime الخاصة بـ Microsoft Edge. إذا فتح التطبيق نافذة فارغة أو لم يبدأ، فقم بتثبيت/تحديث WebView2 ثم جرّب مجددا.

---

Windows: مشكلات الأداء العامة

إذا كنت تواجه بطءا في الأداء، أو مشكلات في الوصول إلى الملفات، أو مشكلات في terminal على Windows، فجرّب استخدام WSL (نظام Windows الفرعي لـ Linux). يوفر WSL بيئة Linux تعمل بسلاسة أكبر مع ميزات SlopCode.

---

الإشعارات لا تظهر

لا يعرض SlopCode Desktop إشعارات النظام إلا عندما:

• تكون الإشعارات مفعلة لـ SlopCode في إعدادات نظام التشغيل، و
• تكون نافذة التطبيق غير نشطة.

---

إعادة تعيين تخزين تطبيق سطح المكتب (كحل أخير)

إذا لم يبدأ التطبيق ولم تتمكن من مسح الإعدادات من داخل الواجهة، فأعد تعيين الحالة المحفوظة لتطبيق سطح المكتب.

1. أغلق SlopCode Desktop.
2. اعثر على هذه الملفات واحذفها (توجد في دليل بيانات تطبيق SlopCode Desktop):

• slopcode.settings.dat (عنوان URL الافتراضي لخادم سطح المكتب)
• slopcode.global.dat و slopcode.workspace.*.dat (حالة الواجهة مثل الخوادم/المشاريع الأخيرة)

للعثور على الدليل بسرعة:

• macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support (ثم ابحث عن أسماء الملفات أعلاه)
• Linux: ابحث ضمن ~/.local/share عن أسماء الملفات أعلاه
• Windows: اضغط WIN+R -> %APPDATA% (ثم ابحث عن أسماء الملفات أعلاه)

---

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

إذا كنت تواجه مشكلات مع SlopCode:

1. الإبلاغ عن المشكلات على GitHub

   أفضل طريقة للإبلاغ عن الأخطاء أو طلب الميزات هي عبر مستودعنا على GitHub:

   github.com/grappeggia/slopcode/issues

   قبل إنشاء مشكلة جديدة، ابحث في المشكلات الموجودة لمعرفة ما إذا كانت مشكلتك قد تم الإبلاغ عنها بالفعل.

2. انضم إلى Discord

   للحصول على مساعدة فورية ونقاشات المجتمع، انضم إلى خادم Discord الخاص بنا:

   slopcode.dev/discord

---

مشكلات شائعة

فيما يلي بعض المشكلات الشائعة وكيفية حلها.

---

SlopCode لا يبدأ

1. تحقق من السجلات بحثا عن رسائل الخطأ
2. جرّب التشغيل مع --print-logs لرؤية المخرجات في terminal
3. تأكد من أنك تستخدم أحدث إصدار عبر slopcode upgrade

---

مشكلات المصادقة

1. جرّب إعادة المصادقة باستخدام الأمر /connect في واجهة TUI
2. تحقق من أن مفاتيح API الخاصة بك صالحة
3. تأكد من أن شبكتك تسمح بالاتصال بواجهة API الخاصة بالمزوّد

---

النموذج غير متاح

1. تحقق من أنك قمت بالمصادقة مع المزوّد
2. تأكد من أن اسم النموذج في الإعدادات صحيح
3. قد تتطلب بعض النماذج صلاحيات وصول محددة أو اشتراكات

إذا واجهت ProviderModelNotFoundError فمن المرجح أنك تشير إلى نموذج بشكل غير صحيح في مكان ما. يجب الإشارة إلى النماذج بهذه الصيغة: <providerId>/<modelId>

أمثلة:

• openai/gpt-4.1
• openrouter/google/gemini-2.5-flash
• slopcode/kimi-k2

لمعرفة النماذج التي لديك صلاحية الوصول إليها، شغّل slopcode models

---

ProviderInitError

إذا واجهت ProviderInitError، فمن المحتمل أن إعداداتك غير صالحة أو تالفة.

لحل ذلك:

1. أولا، تحقق من أن المزوّد مضبوط بشكل صحيح باتباع دليل المزوّدين

2. إذا استمرت المشكلة، فجرّب مسح الإعدادات المخزنة لديك:

   rm -rf ~/.local/share/slopcode

   على Windows، اضغط WIN+R واحذف: %USERPROFILE%\.local\share\slopcode

3. أعد المصادقة مع المزوّد باستخدام الأمر /connect في واجهة TUI.

---

AI_APICallError ومشكلات حزم المزوّد

إذا واجهت أخطاء في استدعاءات API، فقد يكون السبب حزم مزوّد قديمة. يقوم slopcode بتثبيت حزم المزوّد (OpenAI و Anthropic و Google وغير ذلك) ديناميكيا عند الحاجة ويقوم بتخزينها مؤقتا محليا.

لحل مشكلات حزم المزوّد:

1. امسح ذاكرة التخزين المؤقت لحزم المزوّد:

   rm -rf ~/.cache/slopcode

   على Windows، اضغط WIN+R واحذف: %USERPROFILE%\.cache\slopcode

2. أعد تشغيل slopcode لإعادة تثبيت أحدث حزم المزوّد

سيجبر ذلك slopcode على تنزيل أحدث إصدارات حزم المزوّد، وهو ما يحل غالبا مشكلات التوافق مع معاملات النماذج وتغييرات API.

---

النسخ/اللصق لا يعمل على Linux

يحتاج مستخدمو Linux إلى تثبيت إحدى أدوات الحافظة التالية حتى تعمل ميزة النسخ/اللصق:

لأنظمة X11:

apt install -y xclip
# or
apt install -y xsel

لأنظمة Wayland:

apt install -y wl-clipboard

للبيئات بدون واجهة رسومية (Headless):

apt install -y xvfb
# and run:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

سيكتشف slopcode ما إذا كنت تستخدم Wayland ويفضل wl-clipboard، وإلا فسيحاول العثور على أدوات الحافظة بالترتيب التالي: xclip ثم xsel.