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

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

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

openspec: command not found

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

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

إذا تم تثبيتها ولكن ما زال لا يتم العثور عليها، فمن المحتمل أن دليل npm العام الخاص بك غير موجود في متغيّر PATH. شغّل npm prefix -g لمعرفة مكان الحزم العامة: على macOS وLinux، تكون الملفات التنفيذية في مجلد bin/ داخل ذلك الدليل، وعلى Windows تكون مباشرة فيه. تأكد من إضافة هذا المسار إلى PATH. (تمت إزالة npm bin -g في npm 9.)

إذا استخدمت التثبيت بمساعدة الذكاء الاصطناعي، فهذه هي نقطة التسليم المتوقعة: هذا الأمر يطلب من مساعدك أن يُريك تغيير PATH بدلاً من تعديل ملفات بدء التشغيل بنفسه.

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

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

   openspec update

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

   تأتي ملفات التعليمات من واجهة الأوامر المثبّتة، لذا فإن واجهة الأوامر القديمة تُبلغ أن كل شيء محدّث دون كتابة سير العمل الأحدث. يتحقق openspec update الآن من ذلك ويعرض عليك الترقية — اقبل العرض إذا رأيته.

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

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

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

6. تأكد من أن أداتك تدعم ملفات الأوامر. Codex وCodeArts وForgeCode وHermes وKimi Code وMistral Vibe وZed Agent والهدف المشترك .agents لا تحصل على ملفات أوامر opsx-* مُنشأة؛ فهي تستخدم استدعاءات قائمة على المهارات بدلاً من ذلك، لذا لن يكتمل /opsx تلقائيًا لها أبدًا. اكتب $openspec-propose في Codex، و/skill:openspec-propose في Kimi Code، و/openspec-propose في البقية. الهدف المشترك .agents محايد تجاه البائعين، لذا فإن /openspec-propose هو الشكل الشائع وليس شكلًا مضمونًا — إذا لم يستجب مساعدك له، فراجع وثائقه الخاصة لمعرفة كيفية استدعاء مهارة. يحصل Amazon Q على ملفات أوامر، لكنه يحمّلها في مكتبة الأوامر الخاصة به بدلاً من قائمة الشرطة المائلة — اكتب @opsx-propose هناك، وليس /opsx. صيغة كل أداة مدرجة في كيفية الاستدعاء.

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

"التغيير غير موجود (Change not found)"

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

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

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

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

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

openspec status --change <name>

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

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

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

openspec validate <name>           # التحقق من عنصر واحد
openspec validate --all            # التحقق من كل شيء
openspec validate --all --strict   # فحوصات أكثر صرامة، مناسبة للـ CI
openspec validate --archived       # فشل إذا كانت التغييرات المؤرشفة تحتوي على مهام غير مفحوصة

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

رسالة واحدة تستحق ملاحظة خاصة:

MODIFIED "<requirement>" omits scenario(s) the current spec still has: "<scenario>"

متطلب MODIFIED يستبدل كتلة المتطلب بالكامل، لذا يجب أن يحمل كل سيناريو يبقى بعد التغيير، وليس فقط السيناريوهات التي عدّلتها. انسخ السيناريوهات المُسمّاة من openspec/specs/<capability-path>/spec.md إلى الدلتا، مع الحفاظ على أي أدلة نطاق (domain directories) في المسار. يظهر هذا غالبًا في تغيير أقدم بعد أن أضاف تغيير شخص آخر سيناريو إلى نفس المتطلب — الأرشفة ترفض ذلك التغيير على أي حال، والتحقق من الصحة يقول ذلك الآن قبل تنفيذه.

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

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

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

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

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

"قام المستخدم بإغلاق المطالبة قسرًا مع 0 null (User force closed the prompt with 0 null)"

حدث شيء ما شغّل openspec archive ولا يوجد شيء يمكنه الإجابة على سؤال — وكيل ذكاء اصطناعي يستدعيه من أداة، أو وظيفة CI، أو أي قشرة أوامر بإدخال قياسي (stdin) مغلق. تطلب الأرشفة حتى ثلاثة تأكيدات، وكان التأكيد الذي لا يمكن الإجابة عليه يفشل سابقًا بتلك الرسالة الخام.

مرّر --yes للإجابة عنها مسبقًا:

openspec archive <change-name> --yes

احتفظ بأي علامات كنت تمررها — --skip-specs و--no-validate تغيّران ما تفعله الأرشفة، لذا فإن إعادة التشغيل بـ --yes المجردة ليست نفس الأمر. تقوم الإصدارات الحالية بتسمية العلامة لك وتطبع سطر Fix: يمكنك لصقه. إذا كنت تقصد الاختيار من قائمة، فمرّر اسم التغيير صراحةً: منتقى التغييرات يحتاج أيضًا إلى إجابة.

إذا شغّلت الأرشفة بدلاً من ذلك مع إعادة توجيه مخرجاتها إلى ملف أو التقاطها بواسطة أداة وقمت بالفعل بتمرير إجابة (printf 'y\n' | openspec archive …)، كانت الإصدارات الأقدم تكتب رموز هروب الطرفية (terminal escape codes) في ذلك الملف الملتقَط أثناء رسم المطالبة — في بعض البيئات بما يكفي لتضخيم الملف بشكل كبير. تقرأ الإصدارات الحالية مطالبات التأكيد كنص عادي كلما لم يكن stdout طرفية، كما يطلب openspec archive بدون وسائط (والذي كان سيرسم منتقى تغييرات تفاعليًا) تمرير اسم تغيير مسبقًا بدلاً من عرض قائمة في الملف الملتقَط. في كلتا الحالتين، تبقى التشغيلات المعاد توجيهها وتشغيلات الوكلاء نظيفة؛ وتمرير --yes (مع اسم تغيير) يتخطى المطالبات تمامًا.

الإعداد (Configuration)

ملف config.yaml الخاص بي لا يُطبَّق

ثلاثة أسباب معتادة:

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

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

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

openspec schemas --json

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

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

"المخطط غير موجود (Schema not found)"

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

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

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

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

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

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

openspec init --force

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

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

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

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

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

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

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

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