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

Documentation Index

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

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

​

مسار التحميل

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

​

سلوك manifest أولًا

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

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

​

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

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

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

​

نموذج السجل

• سجلات Plugins (الهوية، والمصدر، والمنشأ، والحالة، والتشخيصات)
• الأدوات
• الخطافات القديمة والخطافات المكتوبة
• القنوات
• المزوّدين
• معالجات 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: ملخص الطلب الأصلي، وتلميح الفصل، ومعرّف المرسل، وبيانات تعريف المحادثة

​

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

• بيانات تعريف manifest للبحث منخفض الكلفة قبل وقت التشغيل: 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 الخاص بالبوابة.
• 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" لا تتلقى نطاقات وقت تشغيل المشغل تلقائيا. فهي مخصصة لـ webhooks/التحقق من التوقيع التي يديرها 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 — barrel للمساعدات/الأنواع
• runtime-api.js — barrel خاص بوقت التشغيل فقط
• setup-entry.js — إدخال Plugin للإعداد

​

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

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

​

حل هدف القناة

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

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

​

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

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

• تصفية الاستعلام
• تطبيق الحد
• مساعدات إزالة التكرار/التطبيع
• بناء 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/config repair إلى تجسيد بيانات اعتماد وقت التشغيل فقط من أجل وصف الإعدادات.

• أعد حالة حساب وصفية فقط.
• حافظ على 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. عرّف عقد core قرر ما السلوك المشترك الذي يجب أن يملكه core: السياسة، والرجوع الاحتياطي، ودمج الإعدادات، ودورة الحياة، والدلالات المواجهة للقنوات، وشكل مساعد وقت التشغيل.
2. أضف أسطح تسجيل/وقت تشغيل typed للـ Plugin وسّع OpenClawPluginApi و/أو api.runtime بأصغر سطح قدرة typed مفيد.
3. صِل core + مستهلكي القناة/الميزة يجب أن تستهلك القنوات وPlugins الميزات القدرة الجديدة عبر core، لا عبر استيراد تنفيذ بائع مباشرة.
4. سجّل تنفيذات البائعين ثم تسجل Plugins البائعين خلفياتها مقابل القدرة.
5. أضف تغطية للعقد أضف اختبارات حتى تبقى الملكية وشكل التسجيل صريحين مع مرور الوقت.

​

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

• أنواع عقد core في src/<capability>/types.ts
• مساعد مشغّل/وقت تشغيل core في 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"]);

• يملك core عقد القدرة + التنسيق
• تملك Plugins البائعين تنفيذات البائعين
• تستهلك Plugins الميزات/القنوات مساعدي وقت التشغيل
• تبقي اختبارات العقد الملكية صريحة

​

ذو صلة

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