Preskoči na vsebino

توليد البرامج بالذكاء الاصطناعي

برامج Orb هي JSON مُهيكل، وهذه البنية تجعلها أهدافاً مثالية لتوليد LLM. تصف تطبيقك بلغة طبيعية، وLLM يُخرج برنامج .orb صالح.

يغطي هذا التعليمي:

  • تثبيت واستخدام مهارة Orb
  • توجيه LLM لتوليد برنامج كامل
  • التحقق من المخرجات
  • إصلاح الأخطاء الأكثر شيوعاً التي يرتكبها LLM
OrderLifecycleFulfillment/orders/track
Orbital Unit = Entity + Traits + Pages

مهارة Orb​

حزمة @almadar/skills تتضمن مهارة Claude Code تعلّم LLM مواصفات لغة Orb الكاملة: الوحدات المدارية، الكيانات، السمات، آلات الحالة، الأنماط، تعبيرات S-expression، وغيرها.

التثبيت​

npm install -g @almadar/skills

ثم ثبّت مهارة Claude Code:

almadar-skills install almadar-orbitals

سير عمل التوليد​

1. صف تطبيقك بلغة طبيعية
       ↓
2. LLM يفككه إلى وحدات مدارية (واحدة لكل نطاق كيان)
       ↓
3. LLM يولّد: entity + traits + state machines + pages
       ↓
4. التحقق: orb validate schema.orb
       ↓
5. إصلاح أي أخطاء، التكرار
       ↓
6. التشغيل: orb dev

كيفية التوجيه لتوليد البرنامج​

توجيه التفكيك​

ابدأ بطلب تفكيك التطبيق إلى وحدات مدارية قبل كتابة JSON:

أريد بناء تطبيق إدارة مشاريع مع:
- مشاريع (اسم، وصف، حالة: active/archived)
- مهام (عنوان، أولوية، مُسند إليه، تاريخ الاستحقاق، مرتبطة بمشروع)
- مستخدمون (اسم، بريد إلكتروني، دور: admin/member)

المهام يمكن إنشاؤها، تعديلها، حذفها، ونقلها عبر الحالات:
todo → in progress → review → done.

عند إكمال مهمة، يجب تحديث عدد المهام المكتملة للمشروع.

من فضلك فكك هذا إلى وحدات Orb مدارية وولّد برنامجاً كاملاً.

ما يجب تضمينه في التوجيه​

التوجيه الجيد للتوليد يغطي:

العنصرمثال
الكيانات"المهام لها عنوان، أولوية (low/medium/high)، تاريخ استحقاق، مُسند إليه"
الاستمرارية"المهام دائمة (مخزنة في قاعدة البيانات)، العربة في وقت التشغيل (الجلسة فقط)"
سير العمل"المهام تنتقل من todo إلى in progress إلى review إلى done"
سلوكيات الواجهة"المستخدمون يمكنهم عرض، إنشاء، تعديل، وحذف المهام على صفحة /tasks"
قواعد العمل"المُسند إليه فقط يمكنه تحديد المهمة كمنتهية"
الاتصالات"عند إكمال مهمة، حدّث عداد المشروع"
الصفحات المطلوبة"أحتاج مسارات /tasks و/projects و/users"

الأخطاء الأكثر شيوعاً لـ LLM​

1. صفحات مفقودة (pages) (الأكثر شيوعاً)​

LLM يولّد entity + traits لكن ينسى مصفوفة pages بالكامل.

إصلاح التوجيه: "البرنامج يفتقد مصفوفة pages لكل وحدة مدارية. أضف pages مع path وtraits[].ref لكل وحدة مدارية."

2. الحالات كنصوص بدلاً من كائنات​

// ❌ خطأ
"states": ["Pending", "InProgress", "Done"]

// ✅ صحيح
"states": [
  { "name": "Pending", "isInitial": true },
  { "name": "InProgress" },
  { "name": "Done", "isTerminal": true }
]

3. انتقال INIT مفقود​

الصفحة تُحمّل لكن لا تعرض شيئاً لأنه لا توجد حلقة ذاتية INIT مع render-ui.

إصلاح التوجيه: "كل سمة تفاعل تحتاج انتقال INIT (حلقة ذاتية) يُطلق render-ui لعرض الواجهة الأولية. بدونه الصفحة ستكون فارغة."

4. استخدام خصائص إجراءات مُهملة​

// ❌ مُهمل
{ "type": "form-section", "onSubmit": "SAVE", "onCancel": "CANCEL" }

// ✅ صحيح
{ "type": "form-section", "submitEvent": "SAVE", "cancelEvent": "CANCEL" }

5. مصفوفة traits على مستوى البرنامج (بنية خاطئة)​

// ❌ خطأ - traits على المستوى الجذري (صيغة قديمة)
{
  "name": "App",
  "traits": [...],
  "pages": [...]
}

// ✅ صحيح - traits تعيش داخل orbitals
{
  "name": "App",
  "orbitals": [{
    "name": "FeatureName",
    "entity": { ... },
    "traits": [...],
    "pages": [...]
  }]
}

6. linkedEntity مفقود على السمة​

// ❌ linkedEntity مفقود
{ "name": "TaskCRUD", "category": "interaction", "stateMachine": { ... } }

// ✅ صحيح
{ "name": "TaskCRUD", "linkedEntity": "Task", "category": "interaction", "stateMachine": { ... } }

التوليد التكراري للتطبيقات الكبيرة​

للتطبيقات بأكثر من 3-4 وحدات مدارية، ولّد وحدة مدارية واحدة في كل مرة:

الخطوة 1: "ولّد فقط وحدة TaskManager المدارية (entity + traits + pages)"
الخطوة 2: "الآن أضف وحدة ProjectManager التي تستمع لـ TASK_COMPLETED من TaskManager"
الخطوة 3: "الآن أضف وحدة UserManager لتصفح المستخدمين"
الخطوة 4: "اجمع الثلاث وحدات مدارية في برنامج واحد"

هذا يقلل الأخطاء ويجعل كل جزء قابلاً للمراجعة قبل التجميع.

التحقق من المخرجات​

تحقق دائماً قبل التشغيل:

orb validate schema.orb

أخطاء التحقق الشائعة وما تعنيه:

الخطأالسبب
Missing initial stateلا توجد حالة بها "isInitial": true
Unknown event in transitionالانتقال يشير إلى مفتاح حدث غير موجود في مصفوفة events
Missing pagesوحدة مدارية لها سمات لكن بدون مصفوفة pages
Invalid pattern typeنوع type في تأثير render-ui ليس اسم نمط صالح
Deprecated propاستخدام onSubmit بدلاً من submitEvent، إلخ.
Circular dependencyوحدتان مداريتان تستمعان لبعضهما (استخدم وحدة مدارية وسيطة ثالثة)

توجيه مرجعي (انسخ واستخدم)​

هذا التوجيه يعمل جيداً مع مهارة Orb مثبتة:

باستخدام لغة Orb، ولّد برنامج .orb كامل لـ: [وصف تطبيقك]

المتطلبات:
- كل نطاق ميزة يصبح وحدة مدارية واحدة مع: entity، traits، pages
- كل سمة يجب أن تحتوي انتقال INIT حلقة ذاتية يعرض الواجهة الأولية باستخدام render-ui
- الحالات يجب أن تكون كائنات: { "name": "StateName", "isInitial": true }
- الصفحات يجب أن تكون موجودة مع path وtraits[].ref
- استخدم "submitEvent"/"cancelEvent" على form-section (وليس onSubmit/onCancel)
- استخدم "actions" على page-header (وليس headerActions)
- جميع السمات تنتمي داخل orbitals - لا توجد مصفوفة traits على مستوى البرنامج

الكيانات المطلوبة: [اذكر الكيانات]
سير العمل: [صف انتقالات الحالة]
الصفحات المطلوبة: [اذكر المسارات]
قواعد العمل / الصلاحيات: [صف الحراس]
الاتصالات عبر الوحدات المدارية: [صف emits/listens إن وجدت]

الخطوات التالية​