توافق Plugin

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

سجل التوافق

تُتتبّع عقود توافق Plugin في سجل النواة عند src/plugins/compat/registry.ts.

يحتوي كل سجل على:

• رمز توافق ثابت
• الحالة: active أو deprecated أو removal-pending أو removed
• المالك: SDK أو التكوين أو الإعداد أو القناة أو المزوّد أو تنفيذ Plugin أو وقت تشغيل الوكيل أو النواة
• تواريخ التقديم والإهمال عند الاقتضاء
• إرشادات الاستبدال
• الوثائق والتشخيصات والاختبارات التي تغطي السلوك القديم والجديد

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

يُتتبّع توافق إصلاح Doctor والترحيل بشكل منفصل عند src/commands/doctor/shared/deprecation-compat.ts. تغطي هذه السجلات أشكال التكوين القديمة وتخطيطات سجل التثبيت ومحوّلات الإصلاح التي قد يلزم إبقاؤها متاحة بعد إزالة مسار توافق وقت التشغيل.

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

حزمة فاحص Plugin

ينبغي أن يعيش فاحص Plugin خارج مستودع OpenClaw الأساسي كحزمة/مستودع منفصل مدعوم بعقود التوافق والبيان ذات الإصدارات.

ينبغي أن تكون CLI في اليوم الأول:

openclaw-plugin-inspector ./my-plugin

ينبغي أن تُصدر:

• التحقق من البيان/المخطط
• إصدار توافق العقد الذي يجري فحصه
• فحوصات بيانات التثبيت/المصدر الوصفية
• فحوصات الاستيراد في المسار البارد
• تحذيرات الإهمال والتوافق

استخدم --json للحصول على خرج ثابت قابل للقراءة آليًا في تعليقات CI. ينبغي أن تعرض نواة OpenClaw العقود والتجهيزات التي يستطيع الفاحص استهلاكها، لكن ينبغي ألا تنشر ملف الفاحص الثنائي من حزمة openclaw الرئيسية.

مسار قبول الصيانة

استخدم Crabbox المدعوم بـ Blacksmith Testbox لمسار قبول الحزمة القابلة للتثبيت عند التحقق من الفاحص الخارجي مقابل حزم OpenClaw Plugin. شغّله من نسخة OpenClaw نظيفة بعد بناء الحزمة:

pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "pnpm install && pnpm build && npm exec --yes @openclaw/[email protected] -- ./extensions/telegram --json"pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/[email protected] -- ./extensions/discord --json"pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/[email protected] -- <clawhub-plugin-dir> --json"

أبقِ هذا المسار اختياريًا للمشرفين لأنه يثبّت حزمة npm خارجية وقد يفحص حزم Plugin مستنسخة خارج المستودع. تغطي حمايات المستودع المحلية خريطة تصدير SDK، وبيانات سجل التوافق الوصفية، وتقليص استيرادات SDK المهملة، وحدود استيراد الإضافات المضمّنة؛ أما إثبات فاحص Testbox فيغطي الحزمة كما يستهلكها مؤلفو Plugins الخارجية.

سياسة الإهمال

ينبغي ألا يزيل OpenClaw عقد Plugin موثقًا في الإصدار نفسه الذي يقدّم بديله.

تسلسل الترحيل هو:

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

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

مناطق التوافق الحالية

تشمل سجلات التوافق الحالية:

• استيرادات SDK العريضة القديمة مثل openclaw/plugin-sdk/compat
• أشكال Plugin القديمة المعتمدة على الخطافات فقط وbefore_agent_start
• نقاط دخول Plugin القديمة activate(api) أثناء ترحيل Plugins إلى register(api)
• أسماء SDK المستعارة القديمة مثل openclaw/extension-api، وopenclaw/plugin-sdk/channel-runtime، وبُنّاء حالات openclaw/plugin-sdk/command-auth، وopenclaw/plugin-sdk/test-utils (استُبدلت بمسارات اختبار فرعية مركزة ضمن openclaw/plugin-sdk/*)، والاسمين المستعارين للنوع ClawdbotConfig / OpenClawSchemaType
• سلوك قائمة السماح والتمكين لـ Plugin المضمّنة
• بيانات بيان متغيرات البيئة القديمة للمزوّد/القناة
• خطافات Plugin الخاصة بالمزوّد والأسماء المستعارة للأنواع القديمة أثناء انتقال المزوّدين إلى خطافات صريحة للكتالوج والمصادقة والتفكير وإعادة التشغيل والنقل
• أسماء وقت التشغيل المستعارة القديمة مثل api.runtime.taskFlow، وapi.runtime.subagent.getSession، وapi.runtime.stt، والمهملة api.runtime.config.loadConfig() / api.runtime.config.writeConfigFile(...)
• تسجيل تقسيم Plugin الذاكرة القديم أثناء انتقال Plugins الذاكرة إلى registerMemoryCapability
• مساعدات SDK القناة القديمة لمخططات الرسائل الأصلية، وبوابات الإشارة، وتنسيق الغلاف الوارد، وتداخل قدرة الموافقة
• مفتاح مسار القناة القديم والأسماء المستعارة لمساعد الهدف القابل للمقارنة أثناء انتقال Plugins إلى openclaw/plugin-sdk/channel-route
• تلميحات التفعيل التي يجري استبدالها بملكية مساهمات البيان
• احتياطي وقت التشغيل setup-api أثناء انتقال واصفات الإعداد إلى بيانات وصفية باردة setup.requiresRuntime: false
• خطافات discovery الخاصة بالمزوّد أثناء انتقال خطافات كتالوج المزوّد إلى catalog.run(...)
• بيانات القناة الوصفية showConfigured / showInSetup أثناء انتقال حزم القنوات إلى openclaw.channel.exposure
• مفاتيح تكوين سياسة وقت التشغيل القديمة أثناء ترحيل Doctor للمشغلين إلى agentRuntime
• احتياطي بيانات تكوين القناة المضمّنة المولدة أثناء وصول بيانات channelConfigs الوصفية ذات أولوية السجل
• أعلام البيئة القديمة لتعطيل سجل Plugin وترحيل التثبيت أثناء ترحيل مسارات الإصلاح للمشغلين إلى openclaw plugins registry --refresh و openclaw doctor --fix
• مسارات تكوين البحث في الويب والجلب من الويب وx_search المملوكة قديمًا لـ Plugin أثناء ترحيل Doctor لها إلى plugins.entries.<plugin>.config
• تكوين plugins.installs القديم المؤلف يدويًا والأسماء المستعارة لمسارات تحميل Plugin المضمّنة أثناء انتقال بيانات التثبيت الوصفية إلى سجل Plugin المُدار بالحالة

ينبغي لكود Plugin الجديد تفضيل البديل المذكور في السجل وفي دليل الترحيل المحدد. يمكن لـ Plugins القائمة الاستمرار في استخدام مسار توافق حتى تعلن الوثائق والتشخيصات وملاحظات الإصدار عن نافذة إزالة.

ملاحظات الإصدار

ينبغي أن تتضمن ملاحظات الإصدار إهمالات Plugin القادمة مع التواريخ المستهدفة وروابط إلى وثائق الترحيل. يجب أن يحدث ذلك التحذير قبل انتقال مسار توافق إلى removal-pending أو removed.