ترحيل SDK الخاص بـ Plugin

انتقل OpenClaw من طبقة توافق عكسي واسعة إلى بنية Plugin حديثة ذات عمليات استيراد مركزة وموثقة. إذا كان Plugin لديك قد بُني قبل البنية الجديدة، فسيساعدك هذا الدليل على الترحيل.

ما الذي يتغير

كان نظام Plugin القديم يوفر سطحين مفتوحين على نطاق واسع يسمحان لـ Plugins باستيراد أي شيء تحتاجه من نقطة دخول واحدة:

• openclaw/plugin-sdk/compat - عملية استيراد واحدة أعادت تصدير عشرات المساعدات. قُدمت لإبقاء Plugins القديمة المعتمدة على الخطافات تعمل بينما كانت بنية Plugin الجديدة قيد البناء.
• openclaw/plugin-sdk/infra-runtime - حزمة مساعدات تشغيل واسعة مزجت أحداث النظام، وحالة Heartbeat، وصفوف التسليم، ومساعدات الجلب/الوكيل، ومساعدات الملفات، وأنواع الموافقة، وأدوات غير مترابطة.
• openclaw/plugin-sdk/config-runtime - حزمة توافق إعدادات واسعة لا تزال تحمل مساعدات التحميل/الكتابة المباشرة المهملة أثناء نافذة الترحيل.
• openclaw/extension-api - جسر منح Plugins وصولا مباشرا إلى مساعدات جانب المضيف مثل مشغّل الوكيل المضمّن.
• api.registerEmbeddedExtensionFactory(...) - خطاف إضافة مضمّنة خاص بـ Pi وقد أُزيل، وكان يستطيع مراقبة أحداث المشغّل المضمّن مثل tool_result.

أصبحت أسطح الاستيراد الواسعة الآن مهملة. لا تزال تعمل وقت التشغيل، لكن يجب ألا تستخدمها Plugins الجديدة، وينبغي أن ترحّل Plugins الموجودة قبل أن يزيلها الإصدار الرئيسي التالي. أُزيلت واجهة API الخاصة بتسجيل مصنع الإضافات المضمّنة الخاص بـ Pi؛ استخدم وسيط نتائج الأدوات بدلا منها.

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

لماذا تغير هذا

تسبب النهج القديم في مشكلات:

• بدء تشغيل بطيء - كان استيراد مساعد واحد يحمّل عشرات الوحدات غير المرتبطة
• اعتماديات دائرية - جعلت عمليات إعادة التصدير الواسعة إنشاء دورات استيراد أمرا سهلا
• سطح API غير واضح - لم تكن هناك طريقة لمعرفة أي الصادرات مستقرة وأيها داخلية

يصلح SDK الحديث لـ Plugin هذا: كل مسار استيراد (openclaw/plugin-sdk/\<subpath\>) هو وحدة صغيرة مستقلة بذاتها ذات غرض واضح وعقد موثق.

أزيلت أيضا مسارات التسهيل القديمة للمزوّدين الخاصة بالقنوات المضمّنة. كانت مسارات المساعدات ذات علامات القنوات اختصارات خاصة بالمستودع الأحادي، وليست عقود Plugin مستقرة. استخدم بدلا منها مسارات SDK فرعية عامة وضيقة. داخل مساحة عمل Plugin المضمّن، أبقِ المساعدات المملوكة للمزوّد في api.ts أو runtime-api.ts الخاصين بذلك Plugin نفسه.

أمثلة المزوّدين المضمّنين الحالية:

• يحتفظ Anthropic بمساعدات التدفق الخاصة بـ Claude في مسار api.ts / contract-api.ts الخاص به
• يحتفظ OpenAI ببناة المزوّد، ومساعدات النموذج الافتراضي، وبناة مزوّد الوقت الفعلي في api.ts الخاص به
• يحتفظ OpenRouter بباني المزوّد ومساعدات الإعداد/التكوين في api.ts الخاص به

خطة ترحيل Talk والصوت في الوقت الفعلي

تنتقل شيفرة Talk الخاصة بالصوت في الوقت الفعلي، والاتصالات الهاتفية، والاجتماعات، والمتصفح من تتبّع الأدوار المحلي لكل سطح إلى متحكم جلسة Talk مشترك يصدّره openclaw/plugin-sdk/realtime-voice. يملك المتحكم الجديد غلاف أحداث Talk المشترك، وحالة الدور النشط، وحالة الالتقاط، وحالة إخراج الصوت، وسجل الأحداث الحديثة، ورفض الأدوار القديمة. ينبغي لـ Plugins المزوّدين أن تواصل امتلاك جلسات الوقت الفعلي الخاصة بالبائع؛ وينبغي لـ Plugins الأسطح أن تواصل امتلاك خصائص الالتقاط، والتشغيل، والاتصالات الهاتفية، والاجتماعات.

ترحيل Talk هذا كاسر عن قصد وبشكل نظيف:

1. أبقِ بدائيات المتحكم/التشغيل المشتركة في plugin-sdk/realtime-voice.
2. انقل الأسطح المضمّنة إلى المتحكم المشترك: ترحيل المتصفح، وتسليم الغرف المُدارة، والوقت الفعلي للمكالمات الصوتية، وSTT المتدفق للمكالمات الصوتية، ووقت Google Meet الفعلي، وميزة الضغط للتحدث الأصلية.
3. استبدل عائلات RPC القديمة الخاصة بـ Talk بواجهة API النهائية talk.session.* و talk.client.*.
4. أعلن عن قناة أحداث Talk حية واحدة في hello-ok.features.events الخاصة بـ Gateway: talk.event.
5. احذف نقطة نهاية HTTP القديمة الخاصة بالوقت الفعلي وأي مسار لتجاوز التعليمات وقت الطلب.

ينبغي ألا تستدعي الشيفرة الجديدة createTalkEventSequencer(...) مباشرة إلا إذا كانت تنفذ محوّلا منخفض المستوى أو تجهيز اختبار. فضّل المتحكم المشترك حتى لا يمكن إصدار الأحداث ذات نطاق الدور من دون معرّف دور، ولا يمكن لاستدعاءات turnEnd / turnCancel القديمة أن تمسح دورا أحدث نشطا، وتبقى أحداث دورة حياة إخراج الصوت متسقة عبر الاتصالات الهاتفية، والاجتماعات، وترحيل المتصفح، وتسليم الغرف المُدارة، وعملاء Talk الأصليين.

شكل واجهة API العامة المستهدف هو:

// Gateway-owned Talk session API.await gateway.request("talk.session.create", {  mode: "realtime",  transport: "gateway-relay",  brain: "agent-consult",  sessionKey: "main",});await gateway.request("talk.session.appendAudio", { sessionId, audioBase64 });await gateway.request("talk.session.cancelOutput", { sessionId, reason: "barge-in" });await gateway.request("talk.session.submitToolResult", {  sessionId,  callId,  result: { status: "working" },  options: { willContinue: true },});await gateway.request("talk.session.submitToolResult", {  sessionId,  callId,  result: { status: "already_delivered" },  options: { suppressResponse: true },});await gateway.request("talk.session.submitToolResult", { sessionId, callId, result });await gateway.request("talk.session.close", { sessionId }); // Client-owned provider session API.await gateway.request("talk.client.create", {  mode: "realtime",  transport: "webrtc",  brain: "agent-consult",  sessionKey: "main",});await gateway.request("talk.client.toolCall", { sessionKey, callId, name, args });

تستخدم جلسات WebRTC/مقبس ويب المزوّد المملوكة للمتصفح talk.client.create، لأن المتصفح يملك تفاوض المزوّد ونقل الوسائط بينما يملك Gateway بيانات الاعتماد، والتعليمات، وسياسة الأدوات. talk.session.* هو السطح المشترك المُدار من Gateway للوقت الفعلي عبر gateway-relay، والنسخ عبر gateway-relay، وجلسات STT/TTS الأصلية للغرف المُدارة.

ينبغي إصلاح الإعدادات القديمة التي وضعت محددات الوقت الفعلي بجانب talk.provider / talk.providers باستخدام openclaw doctor --fix؛ لا يعيد Talk وقت التشغيل تفسير إعداد مزوّد الكلام/TTS بوصفه إعداد مزوّد وقت فعلي.

مجموعات talk.session.create المدعومة صغيرة عن قصد:

خريطة الطرق المُزالة:

مفردات التحكم الموحدة ضيقة عمدا أيضا:

لا تضف حالات خاصة للمزوّد أو المنصة في النواة لجعل هذا يعمل. النواة تملك دلالات جلسة Talk. وتملك Plugins الخاصة بالمزوّدين إعداد جلسات المورّدين. وتملك مكالمات الصوت وGoogle Meet محولات الاتصال الهاتفي/الاجتماعات. وتملك المتصفحات والتطبيقات الأصلية تجربة مستخدم التقاط الجهاز/التشغيل.

سياسة التوافق

بالنسبة إلى Plugins الخارجية، يتبع عمل التوافق هذا الترتيب:

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

يمكن للمشرفين تدقيق قائمة انتظار الترحيل الحالية باستخدام pnpm plugins:boundary-report. استخدم pnpm plugins:boundary-report:summary للحصول على أعداد مضغوطة، و--owner <id> من أجل Plugin واحد أو مالك توافق واحد، و pnpm plugins:boundary-report:ci عندما يجب أن تفشل بوابة CI بسبب سجلات توافق مستحقة، أو استيرادات SDK محجوزة عابرة للمالكين، أو مسارات فرعية محجوزة غير مستخدمة في SDK. يجمع التقرير سجلات التوافق المهملة حسب تاريخ الإزالة، ويحصي مراجع الكود/الوثائق المحلية، ويعرض استيرادات SDK المحجوزة العابرة للمالكين، ويلخص جسر SDK الخاص بمضيف الذاكرة بحيث يبقى تنظيف التوافق صريحًا بدلًا من الاعتماد على عمليات بحث مرتجلة. يجب أن يكون للمسارات الفرعية المحجوزة في SDK استخدام مالك متتبع؛ ويجب إزالة تصديرات المساعدين المحجوزة غير المستخدمة من SDK العام.

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

كيفية الترحيل

await api.runtime.config.mutateConfigFile({  afterWrite: { mode: "auto" },  mutate(draft) {    draft.plugins ??= {};  },});

// Pi and Codex runtime dynamic toolsapi.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["pi", "codex"],});

{  "contracts": {    "agentToolResultMiddleware": ["pi", "codex"]  }}

// Beforeconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Afterconst program = applyWindowsSpawnProgramPolicy({  candidate,  // Only set this for trusted compatibility callers that intentionally  // accept shell-mediated fallback.  allowShellFallback: true,});

grep -r "plugin-sdk/compat" my-plugin/grep -r "plugin-sdk/infra-runtime" my-plugin/grep -r "plugin-sdk/config-runtime" my-plugin/grep -r "openclaw/extension-api" my-plugin/

// Before (deprecated backwards-compatibility layer)import {  createChannelReplyPipeline,  createPluginRuntimeStore,  resolveControlCommandGate,} from "openclaw/plugin-sdk/compat"; // After (modern focused imports)import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";

// Before (deprecated extension-api bridge)import { runEmbeddedPiAgent } from "openclaw/extension-api";const result = await runEmbeddedPiAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });

pnpm buildpnpm test -- my-plugin/

مرجع مسار الاستيراد

يقتصر هذا الجدول عمدًا على مجموعة الترحيل الفرعية المشتركة، وليس واجهة SDK الكاملة. يوجد جرد نقاط دخول المصرّف في scripts/lib/plugin-sdk-entrypoints.json؛ وتُولَّد تصديرات الحزم من المجموعة الفرعية العامة.

لم تعد واجهات الربط المساعدة المحجوزة لPlugin المضمّنة ضمن خريطة تصدير SDK العامة، باستثناء واجهات التوافق الموثقة صراحةً مثل طبقة التوافق المهملة plugin-sdk/discord التي أُبقي عليها لحزمة @openclaw/[email protected] المنشورة. توجد المساعدات الخاصة بالمالك داخل حزمة Plugin المالكة؛ وينبغي أن يمر سلوك المضيف المشترك عبر عقود SDK عامة مثل plugin-sdk/gateway-runtime، وplugin-sdk/security-runtime، وplugin-sdk/plugin-config-runtime.

استخدم أضيق استيراد يطابق المهمة. إذا لم تجد تصديرًا، فتحقق من المصدر في src/plugin-sdk/ أو اسأل المشرفين أي عقد عام ينبغي أن يملكه.

الإهمالات النشطة

إهمالات أضيق نطاقًا تنطبق عبر SDK الخاص بPlugin، وعقد المزوّد، وواجهة وقت التشغيل، والبيان. لا يزال كل منها يعمل اليوم، لكنه سيُزال في إصدار رئيسي مستقبلي. يربط المدخل أسفل كل عنصر API القديم ببديله المعتمد.

// Beforeimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Afterimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

{  "contracts": {    "externalAuthProviders": ["anthropic", "openai"]  }}

// Beforeconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Afterconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Beforeimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// Afterimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

الجدول الزمني للإزالة

تم ترحيل كل إضافات Plugin الأساسية بالفعل. ينبغي أن ترحّل إضافات Plugin الخارجية قبل الإصدار الرئيسي التالي.

إسكات التحذيرات مؤقتًا

اضبط متغيرات البيئة هذه أثناء العمل على الترحيل:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

هذا منفذ هروب مؤقت، وليس حلًا دائمًا.

ذات صلة

• بدء الاستخدام - ابنِ أول Plugin لك
• نظرة عامة على SDK - مرجع كامل لاستيراد المسارات الفرعية
• إضافات Plugin للقنوات - بناء إضافات Plugin للقنوات
• إضافات Plugin للمزوّدين - بناء إضافات Plugin للمزوّدين
• الأجزاء الداخلية لPlugin - تعمق في البنية
• بيان Plugin - مرجع مخطط البيان