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

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

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

openspec: command not found

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

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

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

"يتطلب 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. قد تكون في المكان الخطأ. توجد أوامر الشرطة المائلة في محادثة مساعد الذكاء الاصطناعي الخاص بك، وليس في الطرفية. إذا كتبت /opsx:propose في الصدفة (shell) الخاصة بك، فهذه هي المشكلة. راجع كيف تعمل الأوامر.

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

   openspec update

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

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

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

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

6. تأكد من أن أداتك تدعم ملفات الأوامر. لا تحصل Codex وبعض الأدوات الأخرى (CodeArts و Kimi CLI و ForgeCode و Mistral Vibe) على ملفات أوامر opsx-* منشأة؛ بل تستخدم بدلاً من ذلك استدعاءات قائمة على المهارات. بالنسبة لـ Codex، تحقق من .codex/skills/openspec-*. تختلف النماذج حسب الأداة: راجع الأدوات المدعومة و كيف تعمل الأوامر.

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

"التغيير غير موجود"

لم تتمكن الأوامر من تحديد التغيير الذي تقصده. حدده بوضوح، أو تحقق مما هو موجود:

openspec list                    # see active changes
/opsx:apply add-dark-mode        # name the change in chat

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

"لا توجد عناصر جاهزة"

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

openspec status --change <name>

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

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

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

openspec validate <name>           # validate one item
openspec validate --all            # validate everything
openspec validate --all --strict   # stricter checks, good for CI

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

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

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

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

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

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

التكوين

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

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

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

"معرف عنصر غير معروف في القواعد: X"

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

openspec schemas --json

"السياق كبير جدًا"

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

"المخطط غير موجود"

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

openspec schemas                    # list available schemas
openspec schema which <name>        # see where a schema resolves from
openspec schema init <name>         # create a custom one

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

الترحيل من سير العمل القديم

"تم اكتشاف ملفات قديمة في وضع غير تفاعلي"

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

openspec init --force

بالنسبة لـ Codex، قد يكتشف OpenSpec ملفات موجهة قديمة مُدارة في $CODEX_HOME/prompts أو ~/.codex/prompts. يقتصر هذا التنظيف على أسماء ملفات موجهة Codex القديمة المدرجة في القائمة المسموح بها لـ OpenSpec، ويزيل openspec init غير التفاعلي فقط الملفات التي توجد مهارات .codex/skills/openspec-* البديلة لها. يترك openspec update غير التفاعلي جميع عمليات التنظيف القديمة دون تغيير ما لم تمرر --force.

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

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

لم يتم ترحيل project.md القديم الخاص بي

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

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

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

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