الانتقال إلى المحتوى الرئيسي

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

هذا دليل للمساهمين لمطوري نواة OpenClaw. إذا كنت تبني Plugin خارجيًا، فراجع بناء plugins بدلًا من ذلك. لمرجع البنية المعمّق (نموذج الإمكانات، الملكية، مسار التحميل، مساعدات وقت التشغيل)، راجع داخليات Plugin.
استخدم هذا عندما يحتاج 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 الصور.
أبقِهما منفصلين حتى يظل الرجوع الاحتياطي والسياسة صريحين.

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

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

​
ذو صلة