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

حلول ملموسة لمشاكل محددة. يذكر كل إدخال عرضًا للأعراض، ويشرح السبب المحتمل في جملة واحدة، ويقدم لك الحل. إذا لم تجد مشكلتك هنا، فقد يساعدك الأسئلة الشائعة (FAQ)، وبالتأكيد سيساعدك Discord.

التثبيت والإعداد

openspec: command not found

لم يتم تثبيت واجهة سطر الأوامر (CLI)، أو أن الـ shell الخاص بك لا يمكنه العثور عليها. قم بتثبيتها عالميًا وتحقق:

npm install -g @fission-ai/openspec@latest
openspec --version

إذا تم تثبيتها ولكنها لا تزال غير موجودة، فمن المحتمل أن دليل npm العالمي (global) ليس ضمن متغير PATH. قم بتشغيل npm bin -g لمعرفة مكان وجود الملفات التنفيذية العالمية، وتأكد من أن هذا المسار موجود في ملف تعريف الـ shell الخاص بك.

"Requires Node.js 20.19.0 or higher" (يتطلب Node.js 20.19.0 أو أعلى)

يعمل OpenSpec على Node 20.19.0+. تحقق من إصدارك وقم بالترقية إذا لزم الأمر:

node --version

إذا كنت تستخدم bun لتثبيت OpenSpec، لاحظ أن OpenSpec لا يزال يعمل على Node، لذا فأنت بحاجة إلى توفر Node 20.19.0+ في PATH الخاص بك بغض النظر عن ذلك. راجع التثبيت.

openspec init لم يُعد إعداد أداة الذكاء الاصطناعي الخاصة بي

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

openspec init --tools claude,cursor

القائمة الكاملة لمعرّفات الأدوات موجودة في الأدوات المدعومة. استخدم --tools all للحصول على الكل، و--tools none لتخطي إعداد الأدوات.

الأوامر لا تظهر

إذا لم يظهر /opsx:propose (أو ما يعادله في أداتك) أو لم يفعل شيئًا، فاتبع هذه القائمة. وهي مرتبة من الأسرع للتحقق أولاً.

1. قد تكون في المكان الخاطئ. تُوضع الأوامر التي تبدأ بـ / في دردشة مساعد الذكاء الاصطناعي الخاص بك، وليس في الطرفية (terminal). إذا قمت بكتابة /opsx:propose في الـ shell الخاص بك، فهذه هي المشكلة. راجع كيف تعمل الأوامر.

2. أعد إنشاء الملفات. من جذر مشروعك:

   openspec update

   يقوم هذا الأمر بإعادة كتابة ملفات المهارات والأوامر لكل أداة قمت بتكوينها.

3. أعد تشغيل مساعدك. تقوم معظم الأدوات بالبحث عن المهارات والأوامر عند بدء التشغيل. غالبًا ما يؤدي فتح نافذة جديدة إلى ذلك.

4. تأكد من وجود الملفات. بالنسبة لـ Claude Code، تحقق من أن .claude/skills/ يحتوي على مجلدات openspec-*. تستخدم الأدوات الأخرى أدلتها الخاصة، وكلها مدرجة في الأدوات المدعومة.

5. تأكد من تهيئة هذا المشروع. تُكتب المهارات لكل مشروع. إذا قمت باستنساخ مستودع (repo) أو غيرت المجلدات، فقم بتشغيل openspec init (أو openspec update) هناك.

6. تأكد أن أداتك تدعم ملفات الأوامر. بعض الأدوات (Kimi CLI, Trae, ForgeCode, Mistral Vibe) لا يتم إنشاء ملفات أوامر opsx-* لها؛ بل تستخدم استدعاءات تعتمد على المهارات بدلاً من ذلك. تختلف النماذج حسب الأداة: راجع الأدوات المدعومة وكيف تعمل الأوامر.

العمل مع التغييرات

"Change not found" (لم يتم العثور على التغيير)

لم يستطع الأمر تحديد أي تغيير تقصده. قم بتسميته بشكل صريح، أو تحقق مما هو موجود:

openspec list                    # عرض التغييرات النشطة
/opsx:apply add-dark-mode        # تسمية التغيير في الدردشة

تأكد أيضًا من أنك في دليل المشروع الصحيح.

"No artifacts ready" (لا توجد نواتج جاهزة)

كل ناتج إما أنه تم إنشاؤه بالفعل أو أنه متوقف بانتظار تبعية ما. تحقق مما الذي يعيق العملية:

openspec status --change <name>

ثم قم بإنشاء التبعية المفقودة أولاً. تذكر الترتيب: الاقتراح (proposal) يمكّن المواصفات والتصميم؛ والمواصفات والتصميم معًا يُمكّنان المهام (tasks).

openspec validate يُبلغ عن تحذيرات أو أخطاء

يقوم التحقق بفحص مواصفاتك وتغييراتك بحثاً عن مشاكل هيكلية. اقرأ الرسالة: فهي تذكر الملف والمشكلة.

openspec validate <name>           # تحقق من عنصر واحد
openspec validate --all            # تحقق من كل شيء
openspec validate --all --strict   # فحوصات أكثر صرامة، جيدة لـ CI

الأسباب الشائعة هي نقص قسم مطلوب (مثل مواصفات بدون سيناريوهات) أو رأس دلتا (delta header) مشوه. أصلح الملف وأعد التشغيل. يوثق مرجع CLI صيغة الإخراج.

الذكاء الاصطناعي أنشأ نواتج غير مكتملة أو خاطئة

لم يكن لدى الذكاء الاصطناعي سياق كافٍ. بعض الحلول تساعد:

• أضف سياق المشروع في openspec/config.yaml حتى يتم حقن مكدس العمل (stack) والاصطلاحات الخاصة بك في كل طلب. راجع التخصيص.
• أضف قواعد (rules:) لكل ناتج للحصول على توجيه ينطبق فقط على، على سبيل المثال، المواصفات.
• قدم وصفًا أكثر تفصيلاً عند الاقتراح.
• استخدم /opsx:continue الموسع لإنشاء ناتج واحد في كل مرة ومراجعة كل منهما، بدلاً من أن يقوم /opsx:ff بإنشائها جميعاً دفعة واحدة.

الأرشيف لن يكتمل، أو يحذر من المهام غير المكتملة

لن يتسبب الأرشيف (Archive) في تعليق بسبب مهام غير مكتملة، ولكنه سيحذرك، لأن الأرشفة تعني عادةً أن العمل قد تم. إذا بقيت المهام عن قصد (أنت تقوم بتقديم تغيير جزئي)، فتابع. وإلا قم بإكمال المهام أولاً. سيقدم الأرشيف أيضًا خيار مزامنة مواصفات الدلتا الخاصة بك مع المواصفات الرئيسية إذا لم تقم بالمزامنة بعد؛ قل نعم ما لم يكن لديك سبب لعدم ذلك.

التكوين (Configuration)

ملف config.yaml الخاص بي لا يتم تطبيقه

ثلاثة مشتبه بهم عادةً:

1. اسم الملف الخاطئ. يجب أن يكون openspec/config.yaml، وليس .yml.
2. YAML غير صالح. قم بتشغيله عبر أي مدقق YAML؛ فالـ CLI يبلغ أيضًا عن أخطاء بناء الجملة مع أرقام الأسطر.
3. كنت تتوقع إعادة تشغيل. أنت لست بحاجة إلى ذلك. التغييرات في الإعدادات تسري فورًا.

"Unknown artifact ID in rules: X" (معرف ناتج غير معروف في القواعد: X)

مفتاح تحت rules: لا يتطابق مع أي ناتج موجود في مخططك (schema). بالنسبة للمخطط الافتراضي المعتمد على المواصفات (spec-driven)، فإن المعرّفات الصالحة هي proposal وspecs وdesign وtasks. لرؤية المعرّفات لأي مخطط:

openspec schemas --json

"Context too large" (السياق كبير جداً)

تم تحديد حقل context: بحد أقصى 50KB، وذلك عن قصد، لأنه يتم حقنه في كل طلب. قم بتلخيصه، أو اربط إلى وثائق أطول بدلاً من لصقها. السياق المقتضب ينتج نتائج أفضل وأسرع أيضًا.

"Schema not found" (لم يتم العثور على المخطط)

اسم المخطط الذي أشارت إليه غير موجود. اعرض ما هو متاح وتحقق من التهجئة:

openspec schemas                    # عرض المخططات المتاحة
openspec schema which <name>        # معرفة من أين يتم حل المخطط
openspec schema init <name>         # إنشاء مخطط مخصص

راجع التخصيص.

الترحيل من سير العمل القديم (Legacy workflow)

"Legacy files detected in non-interactive mode" (تم اكتشاف ملفات قديمة في وضع غير تفاعلي)

أنت في CI أو shell غير تفاعلي، و OpenSpec وجد ملفات قديمة لتنظيفها ولكنه لا يستطيع أن يسألك. وافق تلقائيًا:

openspec init --force

الأوامر لم تظهر بعد الترحيل

أعد تشغيل IDE الخاص بك. يتم اكتشاف المهارات عند بدء التشغيل. إذا استمرت في عدم الظهور، فقم بتشغيل openspec update وتحقق من مواقع الملفات في الأدوات المدعومة.

ملفي القديم project.md لم يرحل

هذا مقصود. OpenSpec لا يحذف project.md تلقائيًا لأنه قد يحتوي على سياق قمت بكتابته. انقل الأجزاء المفيدة إلى قسم context: في config.yaml، ثم احذفه بنفسك. يقوم دليل الترحيل بشرح هذه العملية، بما في ذلك مطالبة يمكنك إعطاؤها للذكاء الاصطناعي ليقوم بالتقطير (distilling).

ما زلت عالقاً؟

• Discord: discord.gg/YctCnvvshC
• مشاكل GitHub: github.com/Fission-AI/OpenSpec/issues
• من الطرفية (terminal): openspec feedback "what went wrong" يفتح مشكلة لك.

عند الإبلاغ عن مشكلة، قم بتضمين إصدار OpenSpec الخاص بك (openspec --version) وإصدار Node الخاص بك (node --version) وأداة الذكاء الاصطناعي الخاصة بك والأمر المحدد والإخراج. هذا يجعل المساعدة أسرع بكثير.