إضافة القدرات (دليل المساهم)

استخدم هذا عندما يحتاج OpenClaw إلى نطاق مشترك جديد مثل التضمينات، أو توليد الصور، أو توليد الفيديو، أو أي مجال ميزة مستقبلي مدعوم من مورّد.

القاعدة:

• Plugin = حد الملكية
• القدرة = عقد مشترك في النواة

لا تبدأ بتوصيل مورّد مباشرة بقناة أو أداة. ابدأ بتعريف القدرة.

متى تنشئ قدرة

أنشئ قدرة جديدة عندما تكون كل الشروط التالية صحيحة:

1. يمكن لأكثر من مورّد واحد تنفيذها بشكل معقول.
2. ينبغي للقنوات أو الأدوات أو Plugins الميزات استهلاكها من دون الاهتمام بالمورّد.
3. تحتاج النواة إلى امتلاك سلوك التراجع أو السياسة أو الإعدادات أو التسليم.

إذا كان العمل خاصًا بمورّد فقط ولا يوجد عقد مشترك بعد، فتوقف وعرّف العقد أولًا.

التسلسل القياسي

1. عرّف عقد النواة المطبوع.
2. أضف تسجيل Plugin لهذا العقد.
3. أضف مساعد وقت تشغيل مشتركًا.
4. وصّل Plugin مورّدًا حقيقيًا واحدًا كدليل.
5. انقل مستهلكي الميزات/القنوات إلى مساعد وقت التشغيل.
6. أضف اختبارات العقد.
7. وثّق إعدادات المشغّل ونموذج الملكية.

ما الذي يوضع أين

النواة:

• أنواع الطلب/الاستجابة.
• سجل المزوّدين + الحل.
• سلوك التراجع.
• مخطط الإعدادات مع بيانات تعريف وثائق title / description المنشورة على عقد الكائنات المتداخلة، وأحرف البدل، وعناصر المصفوفات، والتركيب.
• سطح مساعد وقت التشغيل.

Plugin المورّد:

• استدعاءات واجهة API الخاصة بالمورّد.
• معالجة مصادقة المورّد.
• تطبيع الطلبات الخاصة بالمورّد.
• تسجيل تنفيذ القدرة.

Plugin الميزة/القناة:

• يستدعي api.runtime.* أو مساعد plugin-sdk/*-runtime المطابق.
• لا يستدعي تنفيذ مورّد مباشرة أبدًا.

نقاط فصل المزوّد والحزام

استخدم خطافات المزوّد عندما ينتمي السلوك إلى عقد مزوّد النموذج بدلًا من حلقة الوكيل العامة. تشمل الأمثلة معاملات الطلب الخاصة بالمزوّد بعد اختيار النقل، وتفضيل ملف المصادقة، وطبقات المطالبات، وتوجيه التراجع اللاحق بعد التحويل عند فشل النموذج/الملف.

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

أبقِ كلا نقطتي الفصل ضيقتين:

• النواة تملك سياسة إعادة المحاولة/التراجع.
• Plugins المزوّدين تملك تلميحات الطلب/المصادقة/التوجيه الخاصة بالمزوّد.
• Plugins الأحزمة تملك تصنيف المحاولة الخاص بوقت التشغيل.
• Plugins الطرف الثالث تُرجع تلميحات، لا تعديلات مباشرة على حالة النواة.

قائمة تحقق الملفات

لقدرة جديدة، توقّع لمس هذه المناطق:

• src/<capability>/types.ts
• src/<capability>/...registry/runtime.ts
• src/plugins/types.ts
• src/plugins/registry.ts
• src/plugins/captured-registration.ts
• src/plugins/contracts/registry.ts
• src/plugins/runtime/types-core.ts
• src/plugins/runtime/index.ts
• src/plugin-sdk/<capability>.ts
• src/plugin-sdk/<capability>-runtime.ts
• حزمة Plugin مضمّنة واحدة أو أكثر.
• الإعدادات، الوثائق، الاختبارات.

مثال عملي: توليد الصور

يتبع توليد الصور الشكل القياسي:

1. تعرّف النواة ImageGenerationProvider.
2. تكشف النواة registerImageGenerationProvider(...).
3. تكشف النواة runtime.imageGeneration.generate(...).
4. تسجّل Plugins openai وgoogle وfal وminimax تنفيذات مدعومة من مورّدين.
5. يسجّل المورّدون المستقبليون العقد نفسه من دون تغيير القنوات/الأدوات.

مفتاح الإعدادات منفصل عمدًا عن توجيه تحليل الرؤية:

• agents.defaults.imageModel يحلّل الصور.
• agents.defaults.imageGenerationModel يولّد الصور.

أبقِ هذين منفصلين حتى يبقى التراجع والسياسة صريحين.

مزوّدو التضمينات

استخدم embeddingProviders لمزوّدي تضمينات المتجهات القابلة لإعادة الاستخدام. هذا العقد أوسع عمدًا من الذاكرة: يمكن للأدوات أو البحث أو الاسترجاع أو المستوردات أو Plugins الميزات المستقبلية استهلاك التضمينات من دون الاعتماد على محرّك الذاكرة.

يمكن لبحث الذاكرة استهلاك embeddingProviders العامة. عقد memoryEmbeddingProviders الأقدم هو توافق مهمل بينما ينتقل مزوّدو التضمينات الخاصة بالذاكرة الحاليون؛ ينبغي لمزوّدي التضمينات القابلة لإعادة الاستخدام الجدد استخدام embeddingProviders.

قائمة تحقق المراجعة

قبل شحن قدرة جديدة، تحقّق من:

• لا توجد قناة/أداة تستورد كود المورّد مباشرة.
• مساعد وقت التشغيل هو المسار المشترك.
• يوجد اختبار عقد واحد على الأقل يؤكد ملكية الحزمة المضمّنة.
• وثائق الإعدادات تسمّي مفتاح النموذج/الإعدادات الجديد.
• تشرح وثائق Plugin حد الملكية.

إذا تجاوز PR طبقة القدرة وثبّت سلوك المورّد داخل قناة/أداة، فأعده وعرّف العقد أولًا.

ذو صلة

• داخليات Plugin — نموذج القدرات، الملكية، مسار التحميل، مساعدات وقت التشغيل.
• بناء Plugins — درس أول Plugin.
• نظرة عامة على SDK — مرجع خريطة الاستيراد وواجهة API للتسجيل.
• إنشاء Skills — سطح مساهمين مرافق.