--- read_when: - أنت تتولى صيانة Plugin لـ OpenClaw - تظهر لك رسالة تحذير بشأن توافق Plugin - تخطط لترحيل مجموعة تطوير البرمجيات الخاصة بـ Plugin أو ملف البيان summary: عقود توافق Plugin، وبيانات الإيقاف التدريجي الوصفية، وتوقعات الترحيل title: توافق Plugin x-i18n: generated_at: "2026-05-11T20:37:27Z" model: gpt-5.5 provider: openai source_hash: 1afd37697f55721ca8419256a6e8187c398d4b20fb11a65776b755050dd5368b source_path: plugins/compatibility.md workflow: 16 --- يبقي 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 في اليوم الأول: ```sh openclaw-plugin-inspector ./my-plugin ``` ينبغي أن تُصدر: - التحقق من البيان/المخطط - إصدار توافق العقد الذي يجري فحصه - فحوصات بيانات التثبيت/المصدر الوصفية - فحوصات الاستيراد في المسار البارد - تحذيرات الإهمال والتوافق استخدم `--json` للحصول على خرج ثابت قابل للقراءة آليًا في تعليقات CI. ينبغي أن تعرض نواة OpenClaw العقود والتجهيزات التي يستطيع الفاحص استهلاكها، لكن ينبغي ألا تنشر ملف الفاحص الثنائي من حزمة `openclaw` الرئيسية. ### مسار قبول الصيانة استخدم Crabbox المدعوم بـ Blacksmith Testbox لمسار قبول الحزمة القابلة للتثبيت عند التحقق من الفاحص الخارجي مقابل حزم OpenClaw Plugin. شغّله من نسخة OpenClaw نظيفة بعد بناء الحزمة: ```sh pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "pnpm install && pnpm build && npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/telegram --json" pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/discord --json" pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- --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..config` - تكوين `plugins.installs` القديم المؤلف يدويًا والأسماء المستعارة لمسارات تحميل Plugin المضمّنة أثناء انتقال بيانات التثبيت الوصفية إلى سجل Plugin المُدار بالحالة ينبغي لكود Plugin الجديد تفضيل البديل المذكور في السجل وفي دليل الترحيل المحدد. يمكن لـ Plugins القائمة الاستمرار في استخدام مسار توافق حتى تعلن الوثائق والتشخيصات وملاحظات الإصدار عن نافذة إزالة. ## ملاحظات الإصدار ينبغي أن تتضمن ملاحظات الإصدار إهمالات Plugin القادمة مع التواريخ المستهدفة وروابط إلى وثائق الترحيل. يجب أن يحدث ذلك التحذير قبل انتقال مسار توافق إلى `removal-pending` أو `removed`.