عرض الرسائل

• أقسام النص
• نص سياق/تذييل صغير
• فواصل
• أزرار
• قوائم اختيار
• عنوان البطاقة ونبرتها

​

العقد

import type {
  MessagePresentation,
  ReplyPayloadDelivery,
} from "openclaw/plugin-sdk/interactive-runtime";

type MessagePresentation = {
  title?: string;
  tone?: "neutral" | "info" | "success" | "warning" | "danger";
  blocks: MessagePresentationBlock[];
};

type MessagePresentationBlock =
  | { type: "text"; text: string }
  | { type: "context"; text: string }
  | { type: "divider" }
  | { type: "buttons"; buttons: MessagePresentationButton[] }
  | { type: "select"; placeholder?: string; options: MessagePresentationOption[] };

type MessagePresentationAction =
  | { type: "command"; command: string }
  | { type: "callback"; value: string };

type MessagePresentationButton = {
  label: string;
  action?: MessagePresentationAction;
  /** Legacy callback value. Prefer action for new controls. */
  value?: string;
  url?: string;
  webApp?: { url: string };
  /** @deprecated Use webApp. Accepted for legacy JSON payloads only. */
  web_app?: { url: string };
  priority?: number;
  disabled?: boolean;
  reusable?: boolean;
  style?: "primary" | "secondary" | "success" | "danger";
};

type MessagePresentationOption = {
  label: string;
  action?: MessagePresentationAction;
  /** Legacy callback value. Prefer action for new controls. */
  value?: string;
};

type ReplyPayloadDelivery = {
  pin?:
    | boolean
    | {
        enabled: boolean;
        notify?: boolean;
        required?: boolean;
      };
};

• يشغّل action.type: "command" أمر شرطة مائلة أصليًا عبر مسار أوامر النواة. استخدم هذا لأزرار الأوامر والقوائم المضمنة.
• يحمل action.type: "callback" بيانات Plugin مبهمة عبر مسار تفاعل القناة. يجب ألا تعيد Plugins القنوات تفسير بيانات callback كأوامر شرطة مائلة.
• value هي قيمة callback مبهمة قديمة. ينبغي أن تستخدم عناصر التحكم الجديدة action حتى تتمكن Plugins القنوات من ربط الأوامر وcallbacks دون التخمين من النص.
• url هو زر رابط. يمكن أن يوجد دون value.
• يصف webApp زر تطبيق ويب أصليًا للقناة. يعرض Telegram هذا على أنه web_app ولا يدعمه إلا في الدردشات الخاصة. لا يزال web_app مقبولًا في حمولات JSON المرنة للتوافق، لكن ينبغي أن يستخدم منتجو TypeScript webApp.
• label مطلوب ويُستخدم أيضًا في احتياطي النص.
• style إرشادي. ينبغي أن تربط العارضات الأنماط غير المدعومة بقيمة افتراضية آمنة، لا أن تُفشل الإرسال.
• priority اختياري. عندما تعلن قناة حدود الإجراءات ويجب إسقاط عناصر تحكم، تحتفظ النواة بالأزرار الأعلى أولوية أولًا وتحافظ على الترتيب الأصلي بين الأزرار ذات الأولوية المتساوية. عندما تتسع كل عناصر التحكم، يُحفظ الترتيب المؤلّف.
• disabled اختياري. يجب أن تشترك القنوات صراحةً عبر supportsDisabled؛ وإلا تخفض النواة عنصر التحكم المعطل إلى نص احتياطي غير تفاعلي.
• reusable اختياري. قد تبقي القنوات التي تدعم callbacks أصلية قابلة لإعادة الاستخدام الإجراء متاحًا بعد تفاعل ناجح. استخدمه للإجراءات القابلة للتكرار أو idempotent مثل التحديث أو الفحص أو مزيد من التفاصيل؛ واتركه غير مضبوط للموافقات العادية ذات الاستخدام الواحد والإجراءات التدميرية.

• يحمل options[].action معنى الأمر/callback نفسه مثل زر action.
• options[].value هي قيمة التطبيق المحددة القديمة.
• placeholder إرشادي وقد تتجاهله القنوات التي لا تدعم الاختيار الأصلي.
• إذا لم تدعم قناة الاختيارات، يسرد النص الاحتياطي التسميات.

​

أمثلة المنتجين

{
  "title": "Deploy approval",
  "tone": "warning",
  "blocks": [
    { "type": "text", "text": "Canary is ready to promote." },
    { "type": "context", "text": "Build 1234, staging passed." },
    {
      "type": "buttons",
      "buttons": [
        { "label": "Approve", "value": "deploy:approve", "style": "success" },
        { "label": "Decline", "value": "deploy:decline", "style": "danger" }
      ]
    }
  ]
}

{
  "blocks": [
    { "type": "text", "text": "Release notes are ready." },
    {
      "type": "buttons",
      "buttons": [{ "label": "Open notes", "url": "https://example.com/release" }]
    }
  ]
}

{
  "blocks": [
    {
      "type": "buttons",
      "buttons": [{ "label": "Launch", "web_app": { "url": "https://example.com/app" } }]
    }
  ]
}

{
  "title": "Choose environment",
  "blocks": [
    {
      "type": "select",
      "placeholder": "Environment",
      "options": [
        { "label": "Canary", "value": "env:canary" },
        { "label": "Production", "value": "env:prod" }
      ]
    }
  ]
}

openclaw message send --channel slack \
  --target channel:C123 \
  --message "Deploy approval" \
  --presentation '{"title":"Deploy approval","tone":"warning","blocks":[{"type":"text","text":"Canary is ready."},{"type":"buttons","buttons":[{"label":"Approve","value":"deploy:approve","style":"success"},{"label":"Decline","value":"deploy:decline","style":"danger"}]}]}'

openclaw message send --channel telegram \
  --target -1001234567890 \
  --message "Topic opened" \
  --pin

{
  "pin": {
    "enabled": true,
    "notify": true,
    "required": false
  }
}

​

عقد العارض

const adapter: ChannelOutboundAdapter = {
  deliveryMode: "direct",
  presentationCapabilities: {
    supported: true,
    buttons: true,
    selects: true,
    context: true,
    divider: true,
    limits: {
      actions: {
        maxActions: 25,
        maxActionsPerRow: 5,
        maxRows: 5,
        maxLabelLength: 80,
        maxValueBytes: 100,
        supportsStyles: true,
        supportsDisabled: false,
      },
      selects: {
        maxOptions: 25,
        maxLabelLength: 100,
        maxValueBytes: 100,
      },
      text: {
        maxLength: 2000,
        encoding: "characters",
        markdownDialect: "discord-markdown",
      },
    },
  },
  deliveryCapabilities: {
    pin: true,
  },
  renderPresentation({ payload, presentation, ctx }) {
    return renderNativePayload(payload, presentation, ctx);
  },
  async pinDeliveredMessage({ target, messageId, pin }) {
    await pinNativeMessage(target, messageId, { notify: pin.notify === true });
  },
};

type ChannelPresentationCapabilities = {
  supported?: boolean;
  buttons?: boolean;
  selects?: boolean;
  context?: boolean;
  divider?: boolean;
  limits?: {
    actions?: {
      maxActions?: number;
      maxActionsPerRow?: number;
      maxRows?: number;
      maxLabelLength?: number;
      maxValueBytes?: number;
      supportsStyles?: boolean;
      supportsDisabled?: boolean;
      supportsLayoutHints?: boolean;
    };
    selects?: {
      maxOptions?: number;
      maxLabelLength?: number;
      maxValueBytes?: number;
    };
    text?: {
      maxLength?: number;
      encoding?: "characters" | "utf8-bytes" | "utf16-units";
      markdownDialect?: "plain" | "markdown" | "html" | "slack-mrkdwn" | "discord-markdown";
      supportsEdit?: boolean;
    };
  };
};

​

تدفق عرض النواة

1. تطبّع حمولة العرض.
2. تحل محوّل الخروج للقناة الهدف.
3. تقرأ presentationCapabilities.
4. تطبّق حدود الإمكانات العامة مثل عدد الإجراءات، وطول التسمية، وعدد خيارات الاختيار عندما يعلنها المحوّل.
5. تستدعي renderPresentation عندما يستطيع المحوّل عرض الحمولة.
6. تعود إلى نص محافظ عندما يكون المحوّل غائبًا أو لا يستطيع العرض.
7. ترسل الحمولة الناتجة عبر مسار تسليم القناة العادي.
8. تطبّق بيانات تعريف التسليم مثل delivery.pin بعد أول رسالة مُرسلة بنجاح.

​

قواعد التدهور

• title كسطر أول
• كتل text كفقرات عادية
• كتل context كأسطر سياق مدمجة
• كتل divider كفاصل مرئي
• تسميات الأزرار، بما في ذلك URLs لأزرار الروابط
• تسميات خيارات الاختيار

​

ظهور احتياطي قيمة الزر

• تعرض الإجراءات ذات النوع command بصيغة label: \command“ حتى يستطيع المستخدمون نسخ الأمر وتشغيله يدويًا في إدخال القناة.
• تعرض الإجراءات ذات النوع callback وحقول value القديمة كتسمية فقط. لا تُكشف قيمة callback المبهمة في النص الاحتياطي.
• تعرض أزرار url / webApp نص URL بجانب تسمية الزر، لأن URL موجّه للمستخدم.
• تعرض خيارات الاختيار كتسمية فقط. لا تُكشف قيمة الخيار الأساسية في النص الاحتياطي.

• يرسل Telegram مع تعطيل الأزرار المضمنة احتياطيًا نصيًا.
• تسرد القناة التي لا تدعم الاختيار خيارات الاختيار كنص.
• يتحول زر URL فقط إما إلى زر رابط أصلي أو سطر URL احتياطي.
• لا تُفشل إخفاقات التثبيت الاختيارية الرسالة المسلّمة.

​

ربط الموفّر

​

Presentation مقابل InteractiveReply

• النص
• الأزرار
• عناصر التحديد

• العنوان
• النبرة
• السياق
• الفاصل
• أزرار URL فقط
• بيانات تعريف تسليم عامة عبر ReplyPayload.delivery

• InteractiveReply, InteractiveReplyBlock, InteractiveReplyButton, InteractiveReplyOption, InteractiveReplySelectBlock, و InteractiveReplyTextBlock
• normalizeInteractiveReply(...)
• hasInteractiveReplyBlocks(...)
• interactiveReplyToPresentation(...)
• presentationToInteractiveReply(...)
• presentationToInteractiveControlsReply(...)
• resolveInteractiveTextFallback(...)
• reduceInteractiveReply(...)

• استخدم buildApprovalPresentationFromActionDescriptors(...) بدلًا من buildApprovalInteractiveReplyFromActionDescriptors(...)
• استخدم buildApprovalPresentation(...) بدلًا من buildApprovalInteractiveReply(...)
• استخدم buildExecApprovalPresentation(...) بدلًا من buildExecApprovalInteractiveReply(...)

​

تثبيت التسليم

• pin: true يثبّت أول رسالة يتم تسليمها بنجاح.
• القيمة الافتراضية لـ pin.notify هي false.
• القيمة الافتراضية لـ pin.required هي false.
• تتدهور حالات فشل التثبيت الاختيارية وتترك الرسالة المرسلة سليمة.
• حالات فشل التثبيت المطلوبة تفشل التسليم.
• الرسائل المجزأة تثبّت أول جزء مُسلَّم، وليس الجزء الأخير.

​

قائمة تحقق مؤلف Plugin

• أعلن عن presentation من describeMessageTool(...) عندما تستطيع القناة عرض العرض الدلالي أو تدهوره بأمان.
• أضف presentationCapabilities إلى محوّل وقت التشغيل الصادر.
• نفّذ renderPresentation في كود وقت التشغيل، وليس في كود إعداد Plugin في مستوى التحكم.
• أبقِ مكتبات الواجهة الأصلية خارج مسارات الإعداد/الفهرس الساخنة.
• أعلن حدود القدرة العامة على presentationCapabilities.limits عندما تكون معروفة.
• حافظ على حدود المنصة النهائية في العارض والاختبارات.
• أضف اختبارات رجوع للأزرار غير المدعومة، وعناصر التحديد، وأزرار URL، وتكرار العنوان/النص، وعمليات الإرسال المختلطة التي تجمع message مع presentation.
• أضف دعم تثبيت التسليم عبر deliveryCapabilities.pin و pinDeliveredMessage فقط عندما يستطيع المزوّد تثبيت معرّف الرسالة المرسلة.
• لا تكشف حقول بطاقة/كتلة/مكوّن/زر أصلية جديدة خاصة بالمزوّد عبر مخطط إجراء الرسائل المشترك.

​

المستندات ذات الصلة

• Message CLI
• نظرة عامة على Plugin SDK
• بنية Plugin
• خطة إعادة هيكلة عرض القنوات