الأجزاء الداخلية لبنية Plugin

​

مسار التحميل

1. يكتشف جذور Plugin المرشحة
2. يقرأ بيانات الحزم الأصلية أو المتوافقة وبيانات تعريف الحزمة
3. يرفض المرشحين غير الآمنين
4. يطبّع إعدادات Plugin (plugins.enabled، وallow، وdeny، وentries، وslots، وload.paths)
5. يقرر التمكين لكل مرشح
6. يحمّل الوحدات الأصلية الممكّنة: تستخدم الوحدات المضمّنة المبنية محمّلًا أصليًا؛ ويستخدم مصدر TypeScript المحلي التابع لجهة خارجية بديل Jiti الطارئ
7. يستدعي خطافات register(api) الأصلية ويجمع التسجيلات في سجل Plugin
8. يعرّض السجل للأوامر/أسطح وقت التشغيل

​

السلوك القائم أولًا على البيان

• تحديد Plugin
• اكتشاف القنوات/Skills/مخطط الإعدادات المعلنة أو قدرات الحزمة
• التحقق من plugins.entries.<id>.config
• تعزيز تسميات/عناصر نائبة في Control UI
• عرض بيانات تعريف التثبيت/الفهرس
• الحفاظ على واصفات التنشيط والإعداد الرخيصة دون تحميل وقت تشغيل Plugin

• يضيّق تحميل CLI إلى plugins التي تملك الأمر الأساسي المطلوب
• يضيّق إعداد القناة/حل Plugin إلى plugins التي تملك معرّف القناة المطلوب
• يضيّق إعداد المزوّد الصريح/حل وقت التشغيل إلى plugins التي تملك معرّف المزوّد المطلوب
• يستخدم تخطيط بدء Gateway activation.onStartup للاستيرادات الصريحة عند بدء التشغيل وعمليات إلغاء بدء التشغيل؛ أما plugins التي لا تحتوي على بيانات تعريف بدء التشغيل فلا تُحمّل إلا عبر مشغلات تنشيط أضيق

​

حدود ذاكرة Plugin المؤقتة

• PluginLoaderCacheState وسجلات وقت التشغيل النشطة المتوافقة
• ذاكرات jiti/الوحدات المؤقتة وذاكرات محمّل الأسطح العامة المؤقتة المستخدمة لتجنب استيراد سطح وقت التشغيل نفسه بشكل متكرر
• ذاكرات نظام الملفات المؤقتة لقطع Plugin المثبتة
• خرائط قصيرة العمر لكل استدعاء لتطبيع المسارات أو حل التكرارات

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

​

نموذج السجل

• سجلات Plugin (الهوية، المصدر، الأصل، الحالة، التشخيصات)
• الأدوات
• الخطافات القديمة والخطافات المعرّفة بأنواع
• القنوات
• المزوّدين
• معالجات Gateway RPC
• مسارات HTTP
• مسجلات CLI
• خدمات الخلفية
• الأوامر المملوكة لـ Plugin

• وحدة Plugin -> تسجيل السجل
• وقت التشغيل الأساسي -> استهلاك السجل

​

ردود نداء ربط المحادثة

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // A binding now exists for this plugin + conversation.
        console.log(event.binding?.conversationId);
        return;
      }

      // The request was denied; clear any local pending state.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" أو "denied"
• decision: "allow-once"، أو "allow-always"، أو "deny"
• binding: الربط المحسوم للطلبات الموافق عليها
• request: ملخص الطلب الأصلي، وتلميح الفصل، ومعرّف المرسل، وبيانات تعريف المحادثة

​

خطافات وقت تشغيل المزوّد

• بيانات تعريف البيان للبحث الرخيص قبل وقت التشغيل: setup.providers[].envVars، وتوافق قديم مهمل providerAuthEnvVars، وproviderAuthAliases، وproviderAuthChoices، وchannelEnvVars.
• خطافات وقت الإعدادات: catalog (القديم discovery) بالإضافة إلى applyConfigDefaults.
• خطافات وقت التشغيل: أكثر من 40 خطافًا اختياريًا تغطي المصادقة، وحل النموذج، وتغليف البث، ومستويات التفكير، وسياسة إعادة التشغيل، ونقاط نهاية الاستخدام. راجع القائمة الكاملة ضمن ترتيب الخطافات والاستخدام.

​

ترتيب الخطافات والاستخدام

​

مثال مزوّد

api.registerProvider({
  id: "example-proxy",
  label: "Example Proxy",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "Auto" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

​

أمثلة مضمّنة

​

مساعدو وقت التشغيل

const clip = await api.runtime.tts.textToSpeech({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

• يعيد textToSpeech حمولة إخراج TTS العادية من النواة لأسطح الملفات/الملاحظات الصوتية.
• يستخدم إعدادات messages.tts الأساسية واختيار المزوّد.
• يعيد مخزن صوت PCM + معدل العينة. يجب على Plugins إعادة أخذ العينات/الترميز للمزوّدين.
• listVoices اختياري لكل مزوّد. استخدمه لمنتقيات الصوت أو تدفقات الإعداد المملوكة للمورّد.
• يمكن أن تتضمن قوائم الأصوات بيانات وصفية أغنى مثل اللغة المحلية والجنس ووسوم الشخصية للمنتقيات الواعية بالمزوّد.
• يدعم OpenAI وElevenLabs الاتصال الهاتفي اليوم. Microsoft لا يدعمه.

api.registerSpeechProvider({
  id: "acme-speech",
  label: "Acme Speech",
  isConfigured: ({ config }) => Boolean(config.messages?.tts),
  synthesize: async (req) => {
    return {
      audioBuffer: Buffer.from([]),
      outputFormat: "mp3",
      fileExtension: ".mp3",
      voiceCompatible: false,
    };
  },
});

• أبقِ سياسة TTS والرجوع وتسليم الرد في النواة.
• استخدم مزوّدي الكلام لسلوك التخليق المملوك للمورّد.
• يتم تطبيع إدخال Microsoft القديم edge إلى معرّف المزوّد microsoft.
• نموذج الملكية المفضّل متمحور حول الشركة: يمكن لـ Plugin مورّد واحد أن يملك مزوّدي النص والكلام والصورة والوسائط المستقبلية بينما يضيف OpenClaw عقود القدرات هذه.

api.registerMediaUnderstandingProvider({
  id: "google",
  capabilities: ["image", "audio", "video"],
  describeImage: async (req) => ({ text: "..." }),
  transcribeAudio: async (req) => ({ text: "..." }),
  describeVideo: async (req) => ({ text: "..." }),
});

• أبقِ التنسيق والرجوع والإعدادات وربط القنوات في النواة.
• أبقِ سلوك المورّد داخل Plugin المزوّد.
• يجب أن يبقى التوسع الإضافي ذا نوع محدد: طرق اختيارية جديدة، وحقول نتائج اختيارية جديدة، وقدرات اختيارية جديدة.
• يتبع توليد الفيديو النمط نفسه بالفعل:
  • تملك النواة عقد القدرة ومساعد وقت التشغيل
  • تسجّل Plugins المورّدين api.registerVideoGenerationProvider(...)
  • تستهلك Plugins الميزات/القنوات api.runtime.videoGeneration.*

const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.5",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "Use the printed fields as the source of truth." },
  ],
  instructions: "Return entities and searchable tags.",
  schemaName: "example.evidence",
  jsonSchema: {
    type: "object",
    properties: {
      entities: { type: "array", items: { type: "string" } },
      tags: { type: "array", items: { type: "string" } },
    },
  },
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Optional when MIME cannot be inferred reliably:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* هو السطح المشترك المفضّل لفهم الصور/الصوت/الفيديو.
• extractStructuredWithModel(...) هو الحد الموجّه إلى Plugin للاستخراج المحدود المملوك للمزوّد والمعتمد أولًا على الصورة. ضمّن إدخال صورة واحدًا على الأقل؛ إدخالات النص سياق تكميلي. تملك Plugins المنتج مساراتها ومخططاتها بينما يملك OpenClaw حد المزوّد/وقت التشغيل.
• يستخدم إعدادات صوت فهم الوسائط في النواة (tools.media.audio) وترتيب الرجوع بين المزوّدين.
• يعيد { text: undefined } عندما لا يتم إنتاج إخراج نسخ (مثل إدخال متخطى/غير مدعوم).
• يبقى api.runtime.stt.transcribeAudioFile(...) كاسم بديل للتوافق.

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider وmodel تجاوزات اختيارية لكل تشغيل، وليست تغييرات جلسة دائمة.
• لا يكرّم OpenClaw حقول التجاوز هذه إلا للمتصلين الموثوقين.
• بالنسبة إلى تشغيلات الرجوع المملوكة لـ Plugin، يجب على المشغّلين الاشتراك عبر plugins.entries.<id>.subagent.allowModelOverride: true.
• استخدم plugins.entries.<id>.subagent.allowedModels لتقييد Plugins الموثوقة على أهداف provider/model معيارية محددة، أو "*" للسماح بأي هدف صراحةً.
• لا تزال تشغيلات subagent من Plugins غير الموثوقة تعمل، لكن يتم رفض طلبات التجاوز بدلًا من الرجوع بصمت.
• تُوسم جلسات subagent التي تنشئها Plugins بمعرّف Plugin المُنشئ. قد يحذف رجوع api.runtime.subagent.deleteSession(...) تلك الجلسات المملوكة فقط؛ ما يزال حذف الجلسات العشوائي يتطلب طلب Gateway بنطاق مسؤول.

const providers = api.runtime.webSearch.listProviders({
  config: api.config,
});

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "OpenClaw plugin runtime helpers",
    count: 5,
  },
});

• أبقِ اختيار المزوّد وحل بيانات الاعتماد ودلالات الطلب المشتركة في النواة.
• استخدم مزوّدي بحث الويب لوسائل نقل البحث الخاصة بالمورّد.
• api.runtime.webSearch.* هو السطح المشترك المفضّل لـ Plugins الميزات/القنوات التي تحتاج إلى سلوك البحث من دون الاعتماد على غلاف أداة الوكيل.

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "A friendly lobster mascot", size: "1024x1024" },
});

const providers = api.runtime.imageGeneration.listProviders({
  config: api.config,
});

• generate(...): توليد صورة باستخدام سلسلة مزوّدي توليد الصور المهيأة.
• listProviders(...): سرد مزوّدي توليد الصور المتاحين وقدراتهم.

​

مسارات HTTP في Gateway

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

• path: مسار التوجيه ضمن خادم HTTP الخاص بـ Gateway.
• auth: مطلوب. استخدم "gateway" لطلب مصادقة Gateway العادية، أو "plugin" لمصادقة/تحقق Webhook يديره Plugin.
• match: اختياري. "exact" (الافتراضي) أو "prefix".
• replaceExisting: اختياري. يسمح لـ Plugin نفسه باستبدال تسجيل مساره الموجود.
• handler: أعد true عندما يكون المسار قد عالج الطلب.

• تمت إزالة api.registerHttpHandler(...) وسيتسبب في خطأ تحميل Plugin. استخدم api.registerHttpRoute(...) بدلا منه.
• يجب أن تعلن مسارات Plugin عن auth صراحة.
• تُرفض تعارضات path + match الدقيقة ما لم يكن replaceExisting: true، ولا يمكن لـ Plugin واحد استبدال مسار Plugin آخر.
• تُرفض المسارات المتداخلة ذات مستويات auth المختلفة. أبق سلاسل التمرير الاحتياطي exact/prefix على مستوى المصادقة نفسه فقط.
• مسارات auth: "plugin" لا تتلقى نطاقات تشغيل المشغل تلقائيا. هي مخصصة لـ Webhook/تحقق التوقيع الذي يديره Plugin، وليست لاستدعاءات مساعدين Gateway ذات الامتيازات.
• تعمل مسارات auth: "gateway" داخل نطاق تشغيل طلب Gateway، لكن هذا النطاق محافظ عمدا:
  • مصادقة حامل السر المشترك (gateway.auth.mode = "token" / "password") تبقي نطاقات تشغيل مسار Plugin مثبتة على operator.write، حتى إذا أرسل المستدعي x-openclaw-scopes
  • أوضاع HTTP الموثوقة الحاملة للهوية (على سبيل المثال trusted-proxy أو gateway.auth.mode = "none" على مدخل خاص) تحترم x-openclaw-scopes فقط عندما يكون الرأس موجودا صراحة
  • إذا كان x-openclaw-scopes غائبا في طلبات مسار Plugin الحاملة للهوية هذه، يعود نطاق التشغيل إلى operator.write
• القاعدة العملية: لا تفترض أن مسار Plugin بمصادقة Gateway هو سطح إدارة ضمني. إذا كان مسارك يحتاج سلوكا مخصصا للمسؤول فقط، فاطلب وضع مصادقة حامل للهوية ووثق عقد الرأس الصريح x-openclaw-scopes.

​

مسارات استيراد Plugin SDK

• index.js — إدخال Plugin مدمج
• api.js — برميل مساعدات/أنواع
• runtime-api.js — برميل مخصص للتشغيل فقط
• setup-entry.js — إدخال Plugin للإعداد

​

مخططات أدوات الرسائل

• presentation لكتل العرض الدلالية (text, context, divider, buttons, select)
• delivery-pin لطلبات التسليم المثبت

​

حل هدف القناة

• يقرر messaging.inferTargetChatType({ to }) ما إذا كان ينبغي التعامل مع هدف مطبع على أنه direct أو group أو channel قبل البحث في الدليل.
• يخبر messaging.targetResolver.looksLikeId(raw, normalized) النواة بما إذا كان الإدخال ينبغي أن يتجاوز مباشرة إلى حل يشبه المعرف بدلا من البحث في الدليل.
• تسرد messaging.targetResolver.reservedLiterals الكلمات المجردة التي تكون مراجع قناة/جلسة لذلك المزود. يحافظ الحل على إدخالات الدليل المهيأة قبل رفض الكلمات المحجوزة، ثم يفشل مغلقا عند عدم وجود مطابق في الدليل.
• messaging.targetResolver.resolveTarget(...) هو تراجع Plugin عندما تحتاج النواة إلى حل نهائي مملوك للمزود بعد التطبيع أو بعد عدم وجود مطابق في الدليل.
• يمتلك messaging.resolveOutboundSessionRoute(...) بناء مسار الجلسة الخاص بالمزود بمجرد حل الهدف.

• استخدم inferTargetChatType لقرارات الفئة التي ينبغي أن تحدث قبل البحث في الأقران/المجموعات.
• استخدم looksLikeId لفحوصات “عامل هذا كمعرف هدف صريح/أصلي”.
• استخدم resolveTarget كتراجع للتطبيع الخاص بالمزود، وليس للبحث الواسع في الدليل.
• أبق المعرفات الأصلية للمزود مثل معرفات الدردشة، ومعرفات السلاسل، وJIDs، والمقابض، ومعرفات الغرف داخل قيم target أو المعاملات الخاصة بالمزود، لا في حقول SDK العامة.

​

أدلة مدعومة بالإعدادات

• أقران الرسائل المباشرة المدفوعة بقائمة السماح
• خرائط القنوات/المجموعات المهيأة
• تراجعات دليل ثابتة ضمن نطاق الحساب

• ترشيح الاستعلام
• تطبيق الحد
• مساعدات إزالة التكرار/التطبيع
• بناء ChannelDirectoryEntry[]

​

كتالوجات المزودين

• { provider } لإدخال مزود واحد
• { providers } لعدة إدخالات مزودين

• simple: مزودون عاديون مدفوعون بمفتاح API أو env
• profile: مزودون يظهرون عند وجود ملفات تعريف مصادقة
• paired: مزودون يصطنعون عدة إدخالات مزودين مرتبطة
• late: آخر تمريرة، بعد المزودين الضمنيين الآخرين

• لا يزال discovery يعمل كاسم مستعار قديم، لكنه يصدر تحذير إهمال
• إذا تم تسجيل كل من catalog وdiscovery، يستخدم OpenClaw catalog
• augmentModelCatalog مهمل؛ ينبغي للمزودين المدمجين نشر الصفوف التكميلية عبر registerModelCatalogProvider

​

فحص القناة للقراءة فقط

• resolveAccount(...) هو مسار التشغيل. يسمح له بافتراض أن بيانات الاعتماد مجسدة بالكامل ويمكنه الفشل بسرعة عندما تكون الأسرار المطلوبة مفقودة.
• ينبغي ألا تحتاج مسارات أوامر القراءة فقط مثل openclaw status, وopenclaw status --all, وopenclaw channels status, وopenclaw channels resolve, وتدفقات doctor/إصلاح الإعدادات إلى تجسيد بيانات اعتماد التشغيل لمجرد وصف الإعدادات.

• أعد حالة حساب وصفية فقط.
• حافظ على enabled وconfigured.
• أدرج حقول مصدر/حالة بيانات الاعتماد عند اللزوم، مثل:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• لا تحتاج إلى إرجاع قيم الرموز الخام لمجرد الإبلاغ عن توفر القراءة فقط. إرجاع tokenStatus: "available" (وحقل المصدر المطابق) يكفي لأوامر نمط الحالة.
• استخدم configured_unavailable عندما تكون بيانات الاعتماد مهيأة عبر SecretRef لكنها غير متاحة في مسار الأمر الحالي.

​

حزم الحزم

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}

• تسجيل القناة نفسها
• أي مسارات HTTP يجب أن تكون متاحة قبل أن يبدأ gateway بالاستماع
• أي أساليب أو أدوات أو خدمات gateway يجب أن تكون موجودة خلال النافذة نفسها

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

{
  "name": "@scope/my-channel",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

​

بيانات وصفية لفهرس القنوات

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: تسمية ثانوية لأسطح الفهرس/الحالة الأكثر ثراءً
• docsLabel: تجاوز نص رابط التوثيق
• preferOver: معرّفات Plugin/قناة ذات أولوية أدنى يجب أن يتفوق عليها إدخال الفهرس هذا
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: عناصر تحكم في نص سطح الاختيار
• markdownCapable: يعلّم القناة بأنها قادرة على markdown لقرارات تنسيق الصادر
• exposure.configured: إخفاء القناة من أسطح سرد القنوات المهيأة عند ضبطها إلى false
• exposure.setup: إخفاء القناة من منتقيات الإعداد/التهيئة التفاعلية عند ضبطها إلى false
• exposure.docs: تعليم القناة بأنها داخلية/خاصة لأسطح تنقل التوثيق
• showConfigured / showInSetup: أسماء مستعارة قديمة ما زالت مقبولة للتوافق؛ فضّل exposure
• quickstartAllowFrom: إدخال القناة في تدفق البدء السريع القياسي allowFrom
• forceAccountBinding: طلب ربط حساب صريح حتى عند وجود حساب واحد فقط
• preferSessionLookupForAnnounceTarget: تفضيل البحث في الجلسة عند حل أهداف الإعلان

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

Plugins محرك السياق

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("lossless-claw", (ctx) => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", (ctx) => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

إضافة قدرة جديدة

1. عرّف عقد النواة قرر السلوك المشترك الذي يجب أن تملكه النواة: السياسة، الاحتياط، دمج الإعداد، دورة الحياة، الدلالات المواجهة للقناة، وشكل مساعد وقت التشغيل.
2. أضف أسطح تسجيل/وقت تشغيل Plugin المطبّعة وسّع OpenClawPluginApi و/أو api.runtime بأصغر سطح قدرة مطبّع مفيد.
3. أوصل النواة + مستهلكي القناة/الميزة ينبغي للقنوات وPlugins الميزات استهلاك القدرة الجديدة عبر النواة، لا عبر استيراد تنفيذ مورّد مباشرة.
4. سجّل تنفيذات المورّدين تسجّل Plugins المورّدين بعد ذلك خلفياتها مقابل القدرة.
5. أضف تغطية للعقد أضف اختبارات حتى يبقى شكل الملكية والتسجيل صريحًا بمرور الوقت.

​

قائمة تحقق القدرة

• أنواع عقد النواة في src/<capability>/types.ts
• مساعد مشغّل/وقت تشغيل النواة في src/<capability>/runtime.ts
• سطح تسجيل API الخاص بـ Plugin في src/plugins/types.ts
• توصيل سجل Plugin في src/plugins/registry.ts
• تعريض وقت تشغيل Plugin في src/plugins/runtime/* عندما تحتاج Plugins الميزات/القنوات إلى استهلاكه
• مساعدو الالتقاط/الاختبار في src/test-utils/plugin-registration.ts
• تأكيدات الملكية/العقد في src/plugins/contracts/registry.ts
• توثيق المشغّل/Plugin في docs/

​

قالب القدرة

// core contract
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// plugin API
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

• يمتلك النواة عقد الإمكانية + التنسيق
• تمتلك Plugins الخاصة بالمورّدين تطبيقات المورّدين
• تستهلك Plugins الخاصة بالميزات/القنوات مساعدات وقت التشغيل
• تُبقي اختبارات العقد الملكية صريحة

​

ذات صلة

• بنية Plugin — نموذج الإمكانيات والأشكال العامة
• المسارات الفرعية لـ Plugin SDK
• إعداد Plugin SDK
• بناء Plugins