ترحيل Plugin SDK

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

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

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

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

أصبحت أسطح الاستيراد الواسعة الآن مهملة. لا تزال تعمل وقت التشغيل، لكن يجب ألا تستخدمها Plugins الجديدة، وينبغي أن ترحّل Plugins القائمة قبل أن يزيلها الإصدار الرئيسي التالي. أزيلت API تسجيل مصنع Plugin المضمّن المخصص لـ 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 مباشرة واحدة في Gateway hello-ok.features.events: 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 });
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 العام.

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

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

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

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

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

// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });

// After
const 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 build
pnpm test -- my-plugin/

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

هذا الجدول هو عمدا مجموعة فرعية مشتركة للهجرة، وليس سطح SDK الكامل. توجد القائمة الكاملة التي تضم أكثر من 200 نقطة دخول في 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 القديمة بالبديل القياسي لها.

// Before
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// After
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

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

// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

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

تم ترحيل جميع إضافات النواة بالفعل. يجب على الإضافات الخارجية الهجرة قبل الإصدار الرئيسي التالي.

# كتم التحذيرات مؤقتا

عيّن متغيرات البيئة هذه أثناء العمل على الهجرة:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

هذا مخرج مؤقت، وليس حلا دائما.

# ذات صلة

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