توافق Plugin

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

# سجل التوافق

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

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

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

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

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

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

# حزمة مفتش Plugins

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

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

openclaw-plugin-inspector ./my-plugin

يجب أن تُصدر:

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

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

# مسار قبول المشرفين

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

blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
blacksmith testbox run --id <tbx_id> "pnpm install && pnpm build && npm exec --yes @openclaw/[email protected] -- ./extensions/telegram --json"
blacksmith testbox run --id <tbx_id> "npm exec --yes @openclaw/[email protected] -- ./extensions/discord --json"
blacksmith testbox run --id <tbx_id> "npm exec --yes @openclaw/[email protected] -- <clawhub-plugin-dir> --json"
blacksmith testbox stop <tbx_id>

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

# سياسة الإيقاف

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

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

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

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

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

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

• استيرادات SDK العريضة القديمة مثل openclaw/plugin-sdk/compat
• أشكال Plugins القديمة القائمة على الخطافات فقط و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 المضمنة
• بيانات تعريف بيان متغيرات البيئة القديمة للمزود/القناة
• خطافات Plugins الخاصة بالمزودين وأسماء الأنواع المستعارة القديمة أثناء انتقال المزودين إلى خطافات كتالوج ومصادقة وتفكير وإعادة تشغيل ونقل صريحة
• أسماء وقت التشغيل المستعارة القديمة مثل 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 المضمنة المستعارة القديمة أثناء انتقال بيانات تعريف التثبيت إلى سجل Plugins المدار بالحالة

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

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

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