واجهة برمجة التطبيقات الصادرة للقناة

تعرض Plugins القنوات سلوك الرسائل الصادرة من openclaw/plugin-sdk/channel-outbound. استخدم openclaw/plugin-sdk/channel-inbound لتنسيق الاستقبال/السياق/الإرسال.

تتولى النواة الاصطفاف، والاستمرارية، وسياسة إعادة المحاولة العامة، والخطافات، والإيصالات، وأداة message المشتركة. ويتولى Plugin استدعاءات الإرسال/التحرير/الحذف الأصلية، وتوحيد الوجهة، وسلاسل المحادثات الخاصة بالمنصة، والاقتباسات المحددة، وأعلام الإشعارات، وحالة الحساب، والآثار الجانبية الخاصة بالمنصة.

المحوّل

تعرّف معظم Plugins محوّل message واحدًا:

   defineChannelMessageAdapter,  createMessageReceiptFromOutboundResults,} from "openclaw/plugin-sdk/channel-outbound"; export const demoMessageAdapter = defineChannelMessageAdapter({  id: "demo",  durableFinal: {    capabilities: {      text: true,      replyTo: true,      thread: true,      messageSendingHooks: true,    },  },  send: {    text: async ({ cfg, to, text, accountId, replyToId, threadId, signal }) => {      const sent = await sendDemoMessage({        cfg,        to,        text,        accountId: accountId ?? undefined,        replyToId: replyToId ?? undefined,        threadId: threadId == null ? undefined : String(threadId),        signal,      });       return {        receipt: createMessageReceiptFromOutboundResults({          results: [{ channel: "demo", messageId: sent.id, conversationId: to }],          kind: "text",          threadId: threadId == null ? undefined : String(threadId),          replyToId: replyToId ?? undefined,        }),      };    },  },});

صرّح فقط بالإمكانات التي يحافظ عليها النقل الأصلي فعليًا. غطِّ كل إمكانية معلنة للإرسال، والإيصال، والمعاينة المباشرة، وإقرار الاستلام باستخدام مساعدات العقد المصدّرة من هذا المسار الفرعي.

تنقية النص العادي

استخدم sanitizeForPlainText(...) عندما يحتاج محوّل صادر إلى تحويل وسوم تنسيق HTML المدعومة إلى ترميز نصي خفيف. يحافظ الإعداد الافتراضي على علامات الخط العريض والشطب الحالية بأسلوب الدردشة. مرّر { style: "markdown" } فقط عندما تعيد القناة تحليل الناتج بوصفه Markdown:

 const chatText = sanitizeForPlainText(text);const markdownText = sanitizeForPlainText(text, { style: "markdown" });

يستخدم نمط Markdown العلامتين **bold** و~~strikethrough~~؛ بينما يحتفظ الخط المائل والكود المضمّن بعلامات _italic_ وعلامات الشرطة المائلة العكسية في كلا النمطين. حدّد النمط عند حدود القناة بدلًا من إعادة كتابة نص العلامات بعد التنقية.

أدلة التسليم

يسجّل MessageReceipt النتيجة التي يعيدها محوّل القناة. تُظهر معرّفات رسائل المنصة الفعلية أن مسار إرسال المنصة قد قبل الرسالة؛ لكنها لا تثبت أن جهاز المستلم عرضها أو قرأها. الإيصالات التي لا تتضمن معرّفات رسائل المنصة ليست سوى بيانات وصفية محلية للإيصال. ينبغي للقنوات التي تدعم إيصالات القراءة أو حالة التسليم إلى الجهاز تتبّع هذه الحقائق عبر مسار منفصل خاص بالقناة.

إذا كان بإمكان محوّل القناة إثبات أن إعادة محاولة عملية فاشلة لا يمكن أن تكرر إرسالًا مرئيًا للمستلم، وأنه لم يبدأ أي استدعاء قادر على الإنهاء، فألقِ new PlatformMessageNotDispatchedError("...", { cause: error }) من openclaw/plugin-sdk/error-runtime. يمكن للنواة حينها مسح أدلة محاولة الإرسال القديمة وإعادة محاولة القصد الموجود في قائمة الانتظار بأمان. لا يجوز إجراء هذا التأكيد إلا للمحوّل الذي يملك حد الإرسال النهائي. لا تستخدم العلامة مطلقًا بعد بدء استدعاء الإنهاء/الإرسال أو إذا أعاد نتيجة ملتبسة؛ فقد يؤدي وضع علامة خاطئة إلى تكرار الرسائل.

محوّلات الإرسال الصادر الحالية

إذا كانت القناة تتضمن بالفعل محوّل outbound متوافقًا، فاشتق محوّل الرسائل بدلًا من تكرار كود الإرسال:

 export const messageAdapter = createChannelMessageAdapterFromOutbound({  id: "demo",  outbound,  durableFinal: {    capabilities: {      text: true,      media: true,    },  },});

عمليات الإرسال المستدامة

توجد أيضًا مساعدات الإرسال وقت التشغيل في channel-outbound:

• sendDurableMessageBatch(...)
• withDurableMessageSendContext(...)
• deliverInboundReplyWithMessageSendContext(...)
• مساعدات بث المسودة/التقدم مثل resolveChannelDraftStreamingChunking(...)

تعيد sendDurableMessageBatch(...) نتيجة صريحة واحدة:

استخدم payloadOutcomes عندما تجمع دفعة بين حمولات مرسلة ومُلغاة وفاشلة. لا تستنتج إلغاء الخطاف من نتيجة تسليم مباشر قديمة فارغة.

قبول التسليم المؤجل

استخدم message.durableFinal.admitDeferredDelivery(...) عندما يتعذر على حساب محلول قبول التسليم الصادر أو المؤجل الذي تديره النواة بأمان. تستدعي النواة هذا الخطاف تزامنيًا قبل العمل الصادر المباشر، بما في ذلك المسارات التي تتخطى استمرارية قائمة الانتظار، ومرة أخرى قبل إعادة تشغيل قصد مستعاد. يتضمن السياق cfg وchannel وto وaccountId، وphase بقيمة live أو recovery.

أعِد { status: "allowed" } للمتابعة. أعِد { status: "permanent_rejection", reason } عندما يجب عدم حفظ التسليم أو إرساله مباشرة أو إعادة تشغيله. يفشل الرفض المباشر قبل إنشاء قائمة الانتظار أو خطافات الرسائل أو عمل المنصة. يضع رفض الاستعادة علامة الفشل على السجل الموجود في قائمة الانتظار ويتخطى التسوية وإعادة التشغيل. يعني حذف الخطاف السماح.

الخطاف قرار قبول تزامني، وليس مسار إرسال. اقرأ فقط الإعدادات المحمّلة مسبقًا أو حالة وقت التشغيل؛ ولا تنفّذ عمليات إدخال/إخراج غير متزامنة عبر الشبكة أو نظام الملفات أو غيرهما. ينبغي لاختبارات العقد اختبار كلتا المرحلتين وكلا نوعي النتائج من خلال ChannelMessageDurableFinalAdapter من openclaw/plugin-sdk/channel-outbound.

إرسال التوافق

أنشئ إرسال الردود الواردة عبر dispatchChannelInboundReply(...) من channel-inbound. أبقِ تسليم المنصة في محوّل التسليم؛ واستخدم channel-outbound لمحوّلات الرسائل، وعمليات الإرسال المستدامة، والإيصالات، والمعاينة المباشرة، وخيارات مسار معالجة الردود.