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

"الخدمة تشهد ضغطًا مرتفعًا. يرجى المحاولة لاحقًا!"

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

متى يحدث:

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

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

مشكلات التثبيت والإعداد

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

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

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

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

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

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

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

تعذّر تسجيل الدخول إلى Verdent for VS Code

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

الحل:

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

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

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

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

فشل التسجيل

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

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

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

نماذج مفقودة (Claude، GPT، Gemini)

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

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

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

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

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

مشكلات الأداء

الأعراض:

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

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

رسائل الأخطاء المتعلقة بالصور

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

أخطاء file_edit

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

الأسباب:

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

الحلول:

# 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)

أخطاء أوامر bash

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

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

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

# 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
• تحقق من أذونات الملفات/الدلائل

البحث لا يُعيد أي نتائج

المشكلة: لا تجد grep_file أو glob الملفات المتوقعة

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

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

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

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

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

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

# Use case-insensitive search if needed
grep_content("pattern", case_insensitive=true)

عدم استدعاء الوكيل الفرعي

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

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

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

اختبار يدوي:

@subagent-name perform task

سلوك الوكلاء الفرعيين المدمجين

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

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

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

الحل:

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

عدم تطبيق AGENTS.md

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

التشخيص:

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

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

# 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)

أخطاء اتصال MCP

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

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

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

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

• أعد تشغيل خادم MCP
• تحقق من صيغة سلسلة الاتصال
• تحقق من قواعد جدار الحماية التي تسمح بمرور حركة MCP
• تحقق من صحة مفاتيح أو رموز API

قيود الملفات الثنائية

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

الحل البديل:

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

معالجة الملفات الكبيرة

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

الحل البديل:

# 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")

اختلافات الأوامر عبر المنصات

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

الحل البديل:

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

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

أفضل ممارسة: استخدم نصوص npm لضمان التوافق عبر المنصات.