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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

ما الذي يتغير

• 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.

​

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

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

​

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

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

​

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

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/

​

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

​

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

// 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 للقنوات
• إضافات Plugin للمزوّدين - بناء إضافات Plugin للمزوّدين
• الأجزاء الداخلية لPlugin - تعمق في البنية
• بيان Plugin - مرجع مخطط البيان