إضافة VS Code وأداة سطر الأوامر moparmeg — التهيئة بمفتاح mop_ | مُبَرمِج

إضافة VS Code

تعلن صفحة التنزيلات «إضافة VS Code» بصيغة «.vsix» على أنها اختيارية: لا تُرسم بطاقتها إلا حين يسمّيها بيان الإصدار ببصمة SHA-256 ويوجد ملفها، وعندها تُنزَّل من /api/v1/downloads/moparmeg-vscode-extension. شروط التوفر نفسها في تطبيق سطح المكتب.

غير متاح بعد: مصدر الإضافة ليس في مستودع المنصة، ولا يحوي المستودع ملفها ولا بيانًا يسمّيه، فلا تظهر بطاقتها ما لم يُرفع الملف إلى مصدر التنزيلات على الخادم.

ما هي أداة سطر الأوامر

الأداة ملف واحد هو cli/moparmeg.mjs يستورد جدول الأوامر ومحلّل الوسائط من كود المنصة نفسه ويفحص شكل المفتاح بدالّة الخادم. تُشغَّل بـNode (المستودع يحدد الإصدار 24). يعرّف package.json اسم الأمر moparmeg لهذا الملف، لكن الحزمة معلَّمة خاصة (private) فلا تُنشر على npm.

الحصول على ملف الأداة خارج مستودع المنصة يتطلّب تواصلاً مع الدعم.

الحصول على مفتاح API

1. من لوحة التحكم افتح صفحة «مفاتيح API» (/api-keys).
2. في لوحة «إنشاء مفتاح جديد» اكتب اسمًا في الحقل «اسم المفتاح (مثال: تطبيق سطح المكتب)».
3. في «الصلاحيات» اختر ما يحتاجه المفتاح. المختار افتراضيًا كل الصلاحيات عدا «نشر المشاريع وإلغاء نشرها» (publish) و«طلب شراء النطاقات ونقلها» (domains:write). الأمر deploy يحتاج publish فاختره عمدًا؛ الصلاحيات لا تتغيّر بعد الإنشاء.
4. اضغط «إنشاء».
5. انسخ المفتاح فورًا: يُعرض مرّة واحدة ولا يُخزَّن منه إلا بصمة، فمن فقده ينشئ غيره.

شكل المفتاح: mop_ ثم 32 محرفًا من الحروف اللاتينية والأرقام و- و_. مفتاح قديم أُنشئ بلا صلاحيات لا يفتح من أوامر المفتاح إلا list وcreate وgenerate (ويبقى صالحًا لفحص الحساب في status). التفاصيل في مفاتيح API.

التهيئة والتشغيل

1. اضبط المفتاح في البيئة: في PowerShell $env:MOPARMEG_API_KEY="mop_..."، وفي bash export MOPARMEG_API_KEY=mop_....
2. اختياريًا اضبط MOPARMEG_BASE_URL؛ القيمة الافتراضية https://moparmeg-ksa.com.
3. من المجلد الذي يحوي الأداة شغّل node cli/moparmeg.mjs help لعرض «الأوامر المتاحة»، وnode cli/moparmeg.mjs <الأمر> --help لمساعدة أمر واحد.
4. جرّب node cli/moparmeg.mjs list.

الأداة لا تطبع المفتاح في أي رسالة، حتى رسائل الخطأ. وتقبل الأعلام بمسافة (--framework nextjs) أو بعلامة =، وترفض العلم المجهول.

الأوامر

• list («عرض المشاريع»): حتى 50 من مشاريعك بعناوينها ومعرّفاتها في الرابط ومعرّف كل مشروع (ID)، مع علامة للمنشور. يحتاج صلاحية projects:read.
• create («إنشاء مشروع جديد»): create "اسم المشروع" [--framework nextjs|react|html] [--template <id>] [--description <نص>]، ويطبع معرّف المشروع الجديد. يمر الإنشاء بالبوابات نفسها التي تمر بها لوحة التحكم: عنوان حتى 100 حرف، وفحص الإساءة، وعقد الباقة (إطار لا تشمله باقتك يُرفض 403 برمز STACK_NOT_IN_PLAN)، وحد عدد المشاريع؛ ثم تُبنى ملفات البداية: هيكل Next.js أو React، أو قالب HTML الفارغ دون إطار. --template يقبل معرّفًا من قائمة templates (قوالب المجالات) ويرسله إلى الخادم معرّفَ مجال: مع Next.js أو React يُبنى الهيكل لذلك المجال، وبلا إطار تُبنى صفحة HTML للمجال (index.html وstyle.css وscript.js). معرّف مجال لا يعرفه الخادم يُرفض بـ«قالب المجال المحدد غير موجود»، وإن عاد المشروع بلا ملفات تنبّه الأداة «الخادم لم يُعد ملفّات القالب». يحتاج projects:write.
• generate («توليد كود بالـ AI»): يرسل الوصف إلى /api/v1/ai ويطبع عدد الملفات والنموذج والرموز فقط؛ لا يحفظ الملفات في مشروع ولا على جهازك. يحتاج ai:chat.
• deploy («نشر المشروع»): deploy <معرّف-المشروع>. يقرأ ملفات المشروع من /api/v1/projects/<id> ثم يطلب نشرها بالملفات نفسها ويطبع «تم النشر» مع الرابط. يحتاج projects:read وpublish، ويمر بمسار النشر الذي يستعمله المتصفح: مشروع لا تملكه يرد «المشروع غير موجود»، وتعديل جرى بين القراءة والنشر يُرفض بـ«تغيّرت نسخة المشروع قبل النشر…»، وحتى 10 نشرات في الدقيقة. المعرّف يطبعه create وlist.
• status («حالة النظام (والحساب إن وُجد مفتاح)»): يقرأ صفحة الصحة العامة بلا مفتاح. وإن ضبطت مفتاحًا صالح الشكل يضيف اسم الحساب والباقة وحصة الذكاء الاصطناعي؛ ومفتاح مشوّه لا يُفشله بل يتخطى فحص الحساب بتنبيه.
• templates («عرض القوالب المتاحة»): لا يحتاج مفتاحًا.

رموز الخروج والأخطاء

• 0: نجاح.
• 1: فشل الأمر، ومنه «تعذّر الاتصال بـ…» حين يتعذّر الوصول إلى الخادم.
• 2: «أمرٌ غير معروف» مع قائمة المتاح، أو خطأ في الوسائط مثل «علمٌ غير معروف».
• 3: «لا مفتاح: اضبط MOPARMEG_API_KEY — تسكّه من لوحة مُبَرمِج في /api-keys».
• 4: «شكلُ المفتاح غير صالح — يبدأ بـmop_ ويليه ٣٢ محرفاً. أعد نسخه من /api-keys».

مفتاح محذوف أو غير معروف يرد عليه الخادم بـ«Invalid API key» فتطبع الأداة «المفتاح مرفوض — اسكك مفتاحاً من /api-keys». وإن كان الخادم أقدم من الأمر تطبع «هذه الأداة تتطلّب إصدار واجهة مبرمج الأحدث». انظر واجهة API.

الباقات

أوامر المفتاح (list وcreate وgenerate وdeploy) تمر بسقف الواجهة البرمجية. في «المجانية» تُرفض list وcreate وdeploy بالعبارة «واجهة API البرمجية متاحة في الباقات المدفوعة فقط — خطة المجانية تشمل القوالب الجاهزة والمحرّر المرئي.»، ويُرفض generate قبل ذلك برمز AI_PAID_ONLY والعبارة «الذكاء الاصطناعي متاح في الباقات المدفوعة فقط — خطة المجانية تشمل القوالب الجاهزة والمحرّر المرئي.»؛ ويبقى templates وstatus يعملان. وتوليد يفشل على الخادم لا يُحتسب من حصة اليوم. وفي «الأساسية»، «المميزة»، «الاحترافية» يعمل generate بحصص الذكاء الاصطناعي التالية، وعدد نداءات الواجهة بالمفتاح في الساعة لا يتجاوز الرقم نفسه:

• «المجانية»: لا طلبات ذكاء اصطناعي.
• «الأساسية»: 50 طلب ذكاء اصطناعي في اليوم.
• «المميزة»: 200 طلب ذكاء اصطناعي في اليوم.
• «الاحترافية»: 1000 طلب ذكاء اصطناعي في اليوم.

أسئلة شائعة

هل أستطيع تثبيت الأداة بـnpm؟

لا. package.json يعرّف الأمر moparmeg لكن الحزمة خاصة لا تُنشر؛ الأداة ملف في مستودع المنصة.

من أين آتي بمعرّف --template؟

من moparmeg templates: كل سطر ينتهي بمعرّف القالب بين قوسين. ويمكن جمعه مع --framework ليُبنى هيكل ذلك الإطار للمجال نفسه.