Plugin maintainer reference

توافق Plugin

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

سجل التوافق

تُتتبَّع عقود توافق Plugin في السجل الأساسي في src/plugins/compat/registry.ts. يحتوي كل سجل على:

رمز توافق ثابت
الحالة: active أو deprecated أو removal-pending أو removed
المالك: sdk أو config أو setup أو channel أو provider أو plugin-execution أو agent-runtime أو core
تواريخ الإدخال والإهمال عند الاقتضاء
إرشادات البديل
الوثائق والتشخيصات والاختبارات التي تغطي السلوك القديم والجديد

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

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

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

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

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

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

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

مجالات التوافق الحالية

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

عمليات استيراد SDK العامة القديمة مثل openclaw/plugin-sdk/compat
أشكال Plugin القديمة التي تقتصر على الخطافات وbefore_agent_start
أسماء خطافات التنظيف القديمة api.on("deactivate", ...) أثناء انتقال Plugins إلى gateway_stop
نقاط دخول 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
قائمة السماح وسلوك التمكين لـ Plugins المضمّنة
بيانات بيان متغيرات البيئة القديمة للمزوّد/القناة
خطافات Plugin القديمة للمزوّد والأسماء المستعارة للأنواع أثناء انتقال المزوّدين إلى خطافات صريحة للفهرس والمصادقة والتفكير وإعادة التشغيل والنقل
الأسماء المستعارة القديمة لبيئة التشغيل مثل api.runtime.taskFlow، وapi.runtime.subagent.getSession، وapi.runtime.stt، والدالتين المهملتين api.runtime.config.loadConfig() / api.runtime.config.writeConfigFile(...)
حقول الاستدعاء المسطّحة في WebInboundMessage لـ WhatsApp (انظر أدناه)
حقول القبول ذات المستوى الأعلى في WebInboundMessage لـ WhatsApp (انظر أدناه)
التسجيل المنقسم القديم لـ Plugin الذاكرة أثناء انتقال Plugins الذاكرة إلى registerMemoryCapability
التسجيل القديم لمزوّد التضمين الخاص بالذاكرة أثناء انتقال مزوّدي التضمين إلى api.registerEmbeddingProvider(...) و contracts.embeddingProviders
مساعدات 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
مسارات التهيئة القديمة المملوكة لـ Plugin للبحث في الويب وجلب محتوى الويب وx_search أثناء ترحيل Doctor لها إلى plugins.entries.<plugin>.config
تهيئة plugins.installs القديمة التي يكتبها المستخدم والأسماء المستعارة لمسارات تحميل Plugin المضمّنة أثناء انتقال بيانات التثبيت الوصفية إلى سجل Plugin المُدار بالحالة

الأسماء المستعارة المسطّحة لاستدعاء WhatsApp الوارد

تسلّم استدعاءات بيئة تشغيل WhatsApp النوع WebInboundMessage: سياقات event وpayload وquote وgroup وplatform المتداخلة والمعتمدة، بالإضافة إلى أسماء مستعارة مسطّحة مهملة لحقول الاستدعاء المشحونة. ينبغي أن تقرأ شيفرة الاستدعاء الجديدة السياقات المتداخلة. يمكن للشيفرة التي تنشئ رسائل استدعاء متداخلة نظيفة استخدام WebInboundCallbackMessage؛ أما مستمعو التوافق الذين ما زالوا يحقنون رسائل اختبار أو Plugin مسطّحة قديمة، فينبغي أن يستخدموا LegacyFlatWebInboundMessage أو WebInboundMessageInput.

تظل الأسماء المستعارة المسطّحة متاحة حتى 2026-08-30؛ وتنطبق هذه النافذة فقط على الوصول عبر الأسماء المستعارة المسطّحة، لا على الشكل المتداخل، الذي يمثّل عقد بيئة التشغيل المعتمد. تسمّي ملاحظة TypeScript @deprecated لكل اسم مستعار مسطّح بديله المتداخل الدقيق. أمثلة شائعة:

تنتقل id وtimestamp وisBatched إلى داخل event.
تنتقل body وmediaPath وmediaType وmediaFileName وmediaUrl وlocation وuntrustedStructuredContext إلى داخل payload.
تنتقل to وchatId وحقول المرسل/الذات وsendComposing وreply(...) وsendMedia(...) إلى داخل platform.
تنتقل حقول replyTo* إلى داخل quote؛ وتنتقل حقول موضوع المجموعة والمشاركين والإشارات إلى داخل group.

يُستخرج payload.untrustedStructuredContext من حمولات المزوّد الواردة. ينبغي أن تفحص Plugins الحقول label وsource وtype قبل اعتبار payload الخاص به مصدرًا موثوقًا.

حقول قبول WhatsApp الواردة

تحمل رسائل استدعاء WhatsApp المقبولة الحقل admission، وهو مغلف آمن للعرض العام لقرار التحكم في الوصول الذي سمح بقبول الرسالة. ينبغي أن تقرأ شيفرة الاستدعاء الجديدة حقائق القبول من msg.admission بدلًا من حقول القبول القديمة ذات المستوى الأعلى.

تظل الحقول ذات المستوى الأعلى متاحة حتى 2026-08-30. تسمّي ملاحظة TypeScript @deprecated لكل حقل بديله:

ينتقل from وconversationId إلى admission.conversation.id.
ينتقل accountId إلى admission.accountId.
يُعد accessControlPassed عرض توافق مشتقًا من admission.ingress.decision === "allow"؛ وفي الرسائل التي تحمل admission بالفعل، لا تؤدي كتابة القيمة المنطقية القديمة إلى إعادة كتابة مخطط الدخول.
ينتقل chatType إلى admission.conversation.kind.

حزمة أداة فحص Plugin

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

openclaw-plugin-inspector ./my-plugin

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

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

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

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 -- <clawhub-plugin-dir> --json"

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

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

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

Was this useful?