إضافة الإمكانات (دليل المساهمين)

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

القاعدة:

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

لا تربط جهة مورّدة مباشرةً بقناة أو أداة. عرّف القدرة أولًا.

متى تنشئ قدرة

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

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

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

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

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

موضع كل جزء

نقاط الربط للمزوّد وإطار التشغيل

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

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

أبقِ نقطتي الربط محدودتين:

• تمتلك النواة سياسة إعادة المحاولة والاحتياط.
• تمتلك 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. تتيح النواة api.runtime.imageGeneration.generate(...) و.listProviders(...).
4. تسجّل Plugins الجهات المورّدة (comfy، وdeepinfra، وfal، وgoogle، وlitellm، وmicrosoft-foundry، وminimax، وopenai، وopenrouter، وvydra، وxai) عمليات تنفيذ مدعومة من الجهات المورّدة.
5. تسجّل الجهات المورّدة المستقبلية العقد نفسه من دون تغيير القنوات أو الأدوات.

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

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

أبقِهما منفصلين لكي تظل سياسات الاحتياط والسياسات العامة صريحة.

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

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

واجهة API الأقدم للتسجيل الخاص بالذاكرة والعقد memoryEmbeddingProviders مهملان. استخدم registerEmbeddingProvider وembeddingProviders لجميع مزوّدي التضمينات الجدد.

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

قبل إصدار قدرة جديدة، تحقّق مما يلي:

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

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

ذو صلة

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