ترحيل Plugin SDK

​

ما الذي يتغير

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

​

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

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

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

​

خطة ترحيل 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 القديمة للوقت الحقيقي وأي مسار لتجاوز التعليمات وقت الطلب.

// 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 });
await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });

​

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

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

​

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

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

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

{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "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 { runEmbeddedAgent } from "openclaw/extension-api";
const result = await runEmbeddedAgent({ sessionId, prompt });

// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm build
pnpm test -- my-plugin/

​

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

​

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

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

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

// Before
api.on("deactivate", async (event, ctx) => {
  await stopPluginService(ctx);
});

// After
api.on("gateway_stop", async (event, ctx) => {
  await stopPluginService(ctx);
});

// Before
api.on("subagent_spawning", async () => ({
  status: "ok",
  threadBindingReady: true,
  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },
}));

// After
api.on("subagent_spawned", async (event) => {
  await observeSubagentLaunch(event);
});

{
  "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 - مرجع كامل لاستيراد المسارات الفرعية
• Plugins القنوات - بناء plugins القنوات
• Plugins المزوّدين - بناء plugins المزوّدين
• داخليات Plugin - تعمّق في البنية
• بيان Plugin - مرجع مخطط البيان