نظرة عامة على SDK الخاص بالـ Plugin

حزمة SDK الخاصة بالمكونات الإضافية هي العقد المطبوع بين المكونات الإضافية والنواة. هذه الصفحة هي المرجع لـ ما يجب استيراده و ما يمكنك تسجيله.

اصطلاح الاستيراد

استورد دائما من مسار فرعي محدد:

كل مسار فرعي هو وحدة صغيرة ومكتفية ذاتيا. يحافظ ذلك على سرعة بدء التشغيل ويمنع مشكلات الاعتماد الدائري. بالنسبة إلى مساعدات الإدخال/البناء الخاصة بالقنوات، فضّل openclaw/plugin-sdk/channel-core؛ واحتفظ بـ openclaw/plugin-sdk/core من أجل السطح الأوسع والمساعدات المشتركة مثل buildChannelConfigSchema.

بالنسبة إلى إعدادات القناة، انشر JSON Schema المملوك للقناة من خلال openclaw.plugin.json#channelConfigs. المسار الفرعي plugin-sdk/channel-config-schema مخصص لأساسيات المخططات المشتركة والباني العام. تستخدم مكونات OpenClaw المضمّنة plugin-sdk/bundled-channel-config-schema لمخططات القنوات المضمّنة المحتفظ بها. تبقى صادرات التوافق المهملة على plugin-sdk/channel-config-schema-legacy؛ ولا يشكل أي من مساري المخطط المضمّن نمطا للمكونات الإضافية الجديدة.

مرجع المسارات الفرعية

تُعرض حزمة SDK الخاصة بالمكونات الإضافية كمجموعة من المسارات الفرعية الضيقة المجمعة حسب المجال (إدخال المكون الإضافي، القناة، المزوّد، المصادقة، وقت التشغيل، القدرة، الذاكرة، ومساعدات المكونات الإضافية المضمّنة المحجوزة). للاطلاع على الفهرس الكامل، مجمعا ومربوطا، راجع مسارات حزمة SDK الخاصة بالمكونات الإضافية الفرعية.

يوجد مخزون نقاط إدخال المترجم في scripts/lib/plugin-sdk-entrypoints.json؛ وتُنشأ صادرات الحزمة من المجموعة العامة الفرعية بعد طرح المسارات الفرعية المحلية للاختبارات/الداخلية في المستودع المدرجة في scripts/lib/plugin-sdk-private-local-only-subpaths.json. شغّل pnpm plugin-sdk:surface لتدقيق عدد الصادرات العامة. تُتبع المسارات الفرعية العامة المهملة القديمة بما يكفي وغير المستخدمة بواسطة كود الإنتاج الخاص بالإضافات المضمّنة في scripts/lib/plugin-sdk-deprecated-public-subpaths.json؛ وتُتبع براميل إعادة التصدير المهملة الواسعة في scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json.

واجهة API للتسجيل

يتلقى استدعاء register(api) كائنا من نوع OpenClawPluginApi بهذه الطرق:

تسجيل القدرات

الأدوات والأوامر

يمكن لأوامر المكونات الإضافية تعيين agentPromptGuidance عندما يحتاج الوكيل إلى تلميح توجيه قصير مملوك للأمر. اجعل ذلك النص حول الأمر نفسه؛ ولا تضف سياسة خاصة بالمزوّد أو المكون الإضافي إلى بناة الموجهات في النواة.

البنية التحتية

خطافات المضيف لمكونات سير العمل الإضافية

خطافات المضيف هي مسارات SDK للمكونات الإضافية التي تحتاج إلى المشاركة في دورة حياة المضيف بدلا من مجرد إضافة مزوّد أو قناة أو أداة. إنها عقود عامة؛ يمكن أن يستخدمها وضع الخطة، وكذلك سير عمل الموافقات، وبوابات سياسة مساحة العمل، والمراقبات الخلفية، ومعالجات الإعداد، ومكونات واجهة المستخدم المرافقة.

استخدم فضاءات الأسماء المجمعة لكود المكونات الإضافية الجديد:

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

تبقى الطرق المسطحة المكافئة متاحة كأسماء مستعارة توافقية مهملة للمكونات الإضافية الحالية. لا تضف كود مكونات إضافية جديدا يستدعي api.registerSessionExtension أو api.enqueueNextTurnInjection أو api.registerControlUiDescriptor أو api.registerRuntimeLifecycle أو api.registerAgentEventSubscription أو api.emitAgentEvent أو api.setRunContext أو api.getRunContext أو api.clearRunContext أو api.registerSessionSchedulerJob أو api.registerSessionAction أو api.sendSessionAttachment أو api.scheduleSessionTurn أو api.unscheduleSessionTurnsByTag مباشرة.

scheduleSessionTurn(...) هي أداة تيسير على نطاق الجلسة فوق مجدول Cron في Gateway. يملك Cron التوقيت وينشئ سجل مهمة الخلفية عند تشغيل الدور؛ لا يقيّد Plugin SDK إلا الجلسة الهدف، والتسمية المملوكة للـ Plugin، والتنظيف. استخدم api.runtime.tasks.managedFlows داخل الدور المجدول عندما يحتاج العمل نفسه إلى حالة Task Flow متينة متعددة الخطوات.

تقسم العقود الصلاحية عمدا:

• يمكن للـ Plugins الخارجية امتلاك امتدادات الجلسة، وواصفات واجهة المستخدم، والأوامر، وبيانات تعريف الأدوات، وحقن الدور التالي، والخطافات العادية.
• تعمل سياسات الأدوات الموثوقة قبل خطافات before_tool_call العادية، وهي مخصصة للحزم المضمنة فقط لأنها تشارك في سياسة سلامة المضيف.
• ملكية الأوامر المحجوزة مخصصة للحزم المضمنة فقط. ينبغي للـ Plugins الخارجية استخدام أسماء أوامرها أو أسمائها البديلة.
• يعطل allowPromptInjection=false الخطافات التي تعدل الموجهات، بما في ذلك agent_turn_prepare، وbefore_prompt_build، وheartbeat_prompt_contribution، وحقول الموجهات من before_agent_start القديم، وenqueueNextTurnInjection.

أمثلة على مستهلكين خارج Plan:

تسجيل اكتشاف Gateway

تتيح api.registerGatewayDiscoveryService(...) للـ Plugin الإعلان عن Gateway النشط على نقل اكتشاف محلي مثل mDNS/Bonjour. يستدعي OpenClaw الخدمة أثناء بدء تشغيل Gateway عندما يكون الاكتشاف المحلي مفعلا، ويمرر منافذ Gateway الحالية وبيانات تلميح TXT غير السرية، ويستدعي معالج stop المعاد أثناء إيقاف Gateway.

api.registerGatewayDiscoveryService({  id: "my-discovery",  async advertise(ctx) {    const handle = await startMyAdvertiser({      gatewayPort: ctx.gatewayPort,      tls: ctx.gatewayTlsEnabled,      displayName: ctx.machineDisplayName,    });    return { stop: () => handle.stop() };  },});

يجب ألا تتعامل Plugins اكتشاف Gateway مع قيم TXT المعلن عنها كأسرار أو مصادقة. الاكتشاف تلميح توجيه؛ وما زالت مصادقة Gateway وتثبيت TLS يمتلكان الثقة.

بيانات تعريف تسجيل CLI

تقبل api.registerCli(registrar, opts?) نوعين من بيانات تعريف الأوامر:

• commands: أسماء أوامر صريحة يملكها المسجل
• descriptors: واصفات أوامر وقت التحليل المستخدمة لمساعدة CLI، والتوجيه، وتسجيل CLI الخاص بالـ Plugin المحمل كسولا
• parentPath: مسار أمر أب اختياري لمجموعات الأوامر المتداخلة، مثل ["nodes"]

للميزات ذات العقدة المقترنة، فضّل api.registerNodeCliFeature(registrar, opts?). إنه مغلف صغير حول api.registerCli(..., { parentPath: ["nodes"] }) ويجعل أوامر مثل openclaw nodes canvas ميزات عقدة صريحة مملوكة للـ Plugin.

إذا أردت أن يبقى أمر Plugin محملا كسولا في مسار CLI الجذري العادي، فقدم descriptors تغطي كل جذر أمر علوي يكشفه ذلك المسجل.

api.registerCli(  async ({ program }) => {    const { registerMatrixCli } = await import("./src/cli.js");    registerMatrixCli({ program });  },  {    descriptors: [      {        name: "matrix",        description: "Manage Matrix accounts, verification, devices, and profile state",        hasSubcommands: true,      },    ],  },);

تتلقى الأوامر المتداخلة الأمر الأب المحلول باسم program:

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "Capture or render canvas content from a paired node",        hasSubcommands: true,      },    ],  },);

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

تسجيل خلفية CLI

تتيح api.registerCliBackend(...) للـ Plugin امتلاك التكوين الافتراضي لخلفية CLI محلية للذكاء الاصطناعي مثل codex-cli.

• يصبح id الخاص بالخلفية بادئة المزوّد في مراجع النماذج مثل codex-cli/gpt-5.
• يستخدم config الخاص بالخلفية الشكل نفسه مثل agents.defaults.cliBackends.<id>.
• يظل تكوين المستخدم هو الغالب. يدمج OpenClaw agents.defaults.cliBackends.<id> فوق افتراض Plugin قبل تشغيل CLI.
• استخدم normalizeConfig عندما تحتاج خلفية إلى إعادة كتابات توافق بعد الدمج (مثل تسوية أشكال الرايات القديمة).
• استخدم resolveExecutionArgs لإعادة كتابة argv محددة بنطاق الطلب وتنتمي إلى لهجة CLI، مثل ربط مستويات التفكير في OpenClaw براية جهد أصلية.

للاطلاع على دليل تأليف شامل، راجع Plugins خلفية CLI.

الخانات الحصرية

محولات تضمين الذاكرة

• registerMemoryCapability هي واجهة API الحصرية المفضلة لـ Plugin الذاكرة.
• قد تكشف registerMemoryCapability أيضا publicArtifacts.listArtifacts(...) كي تستطيع Plugins المصاحبة استهلاك عناصر الذاكرة المصدرة عبر openclaw/plugin-sdk/memory-host-core بدلا من الوصول إلى التخطيط الخاص بـ Plugin ذاكرة محدد.
• registerMemoryPromptSection وregisterMemoryFlushPlan و registerMemoryRuntime هي واجهات API حصرية متوافقة مع القديم لـ Plugin الذاكرة.
• يمكن لـ MemoryFlushPlan.model تثبيت دور التفريغ على مرجع provider/model دقيق، مثل ollama/qwen3:8b، من دون وراثة سلسلة الاحتياط النشطة.
• تتيح registerMemoryEmbeddingProvider لـ Plugin الذاكرة النشط تسجيل معرف محول تضمين واحد أو أكثر (مثل openai أو gemini أو معرف مخصص يعرّفه Plugin).
• يحل تكوين المستخدم مثل agents.defaults.memorySearch.provider و agents.defaults.memorySearch.fallback مقابل معرفات المحولات المسجلة هذه.

الأحداث ودورة الحياة

راجع خطافات Plugin للاطلاع على أمثلة، وأسماء الخطافات الشائعة، ودلالات الحراسة.

دلالات قرار الخطاف

• before_tool_call: إرجاع { block: true } نهائي. بمجرد أن يضبطه أي معالج، يتم تخطي المعالجات الأقل أولوية.
• before_tool_call: يعامل إرجاع { block: false } كأنه لا قرار (مثل حذف block)، وليس كتجاوز.
• before_install: إرجاع { block: true } نهائي. بمجرد أن يضبطه أي معالج، يتم تخطي المعالجات الأقل أولوية.
• before_install: يعامل إرجاع { block: false } كأنه لا قرار (مثل حذف block)، وليس كتجاوز.
• reply_dispatch: إرجاع { handled: true, ... } نهائي. بمجرد أن يعلن أي معالج توليه للإرسال، يتم تخطي المعالجات الأقل أولوية ومسار إرسال النموذج الافتراضي.
• message_sending: إرجاع { cancel: true } نهائي. بمجرد أن يضبطه أي معالج، يتم تخطي المعالجات الأقل أولوية.
• message_sending: يعامل إرجاع { cancel: false } كأنه لا قرار (مثل حذف cancel)، وليس كتجاوز.
• message_received: استخدم حقل threadId المطبوع عندما تحتاج إلى توجيه سلسلة/موضوع وارد. أبق metadata للإضافات الخاصة بالقناة.
• message_sending: استخدم حقول التوجيه المطبوعة replyToId / threadId قبل الرجوع إلى metadata الخاصة بالقناة.
• gateway_start: استخدم ctx.config وctx.workspaceDir وctx.getCron?.() لحالة بدء التشغيل المملوكة للـ Gateway بدلا من الاعتماد على خطافات gateway:startup الداخلية.
• cron_changed: راقب تغييرات دورة حياة Cron المملوكة للـ Gateway. استخدم event.job?.state?.nextRunAtMs وctx.getCron?.() عند مزامنة مجدولات إيقاظ خارجية، وأبق OpenClaw مصدر الحقيقة لفحوص الاستحقاق والتنفيذ.

حقول كائن API

اصطلاح الوحدات الداخلية

داخل Plugin الخاص بك، استخدم ملفات تجميع محلية للاستيرادات الداخلية:

my-plugin/  api.ts            # Public exports for external consumers  runtime-api.ts    # Internal-only runtime exports  index.ts          # Plugin entry point  setup-entry.ts    # Lightweight setup-only entry (optional)

تفضّل الأسطح العامة لـ Plugin المضمّن والمحملة عبر الواجهة (api.ts وruntime-api.ts وindex.ts وsetup-entry.ts وملفات الدخول العامة المشابهة) لقطة إعدادات وقت التشغيل النشطة عندما يكون OpenClaw قيد التشغيل بالفعل. إذا لم تكن هناك لقطة وقت تشغيل بعد، فإنها تعود إلى ملف الإعدادات المحلول على القرص. يجب تحميل واجهات Plugin المضمّنة المعبأة عبر محمّلات واجهة Plugin في OpenClaw؛ فالاستيرادات المباشرة من dist/extensions/... تتجاوز البيان وفحوصات المرافق الجانبية لوقت التشغيل التي تستخدمها التثبيتات المعبأة للكود المملوك لـ Plugin.

يمكن لـ provider plugins كشف ملف تجميع عقد محلي ضيق خاص بـ Plugin عندما يكون المساعد مقصودًا أن يكون محددًا لمزوّد ولا ينتمي بعد إلى مسار فرعي عام في SDK. أمثلة مضمّنة:

• Anthropic: سطح عام api.ts / contract-api.ts لمساعدات ترويسة Claude التجريبية وتدفق service_tier.
• @openclaw/openai-provider: يصدّر api.ts بناة المزوّد، ومساعدات النموذج الافتراضي، وبناة مزوّد الوقت الفعلي.
• @openclaw/openrouter-provider: يصدّر api.ts باني المزوّد بالإضافة إلى مساعدات الإعداد الأولي/الإعدادات.

ذات صلة