عرض الرسائل
عرض الرسائل هو العقد المشترك في OpenClaw لواجهة الدردشة الغنية للرسائل الصادرة. وهو يتيح للوكلاء وأوامر CLI وتدفقات الموافقة وPlugins وصف هدف الرسالة مرة واحدة، بينما يقوم كل Plugin قناة بعرض أفضل شكل أصلي متاح لديه. استخدم العرض لواجهة رسائل قابلة للنقل:- أقسام النص
- نص سياق/تذييل صغير
- فواصل
- أزرار
- قوائم منسدلة
- عنوان البطاقة ونبرتها
components في Discord أو blocks في Slack
أو buttons في Telegram أو card في Teams أو card في Feishu إلى
أداة الرسائل المشتركة. فهذه نواتج عرض يملكها Plugin القناة.
العقد
يستورد مؤلفو Plugins العقد العام من:valueهي قيمة إجراء تطبيق تُعاد عبر مسار التفاعل الحالي في القناة عندما تدعم القناة عناصر تحكم قابلة للنقر.urlهو زر رابط. ويمكن أن يوجد من دونvalue.labelمطلوب ويُستخدم أيضًا في النص الاحتياطي.styleتوجيهي. يجب على أدوات العرض تحويل الأنماط غير المدعومة إلى قيمة افتراضية آمنة، لا أن تفشل عملية الإرسال.
options[].valueهي قيمة التطبيق المحددة.placeholderتوجيهي وقد تتجاهله القنوات التي لا تدعم القوائم المنسدلة أصلًا.- إذا كانت القناة لا تدعم القوائم المنسدلة، فإن النص الاحتياطي يسرد التسميات.
أمثلة للمنتِج
بطاقة بسيطة:عقد أداة العرض
تعلن Plugins القنوات دعم العرض في المهايئ الصادر الخاص بها:تدفق العرض في Core
عندما يتضمنReplyPayload أو إجراء رسالة ما presentation، فإن core:
- يطبع حمولة العرض.
- يحدد مهايئ الإرسال الصادر للقناة المستهدفة.
- يقرأ
presentationCapabilities. - يستدعي
renderPresentationعندما يتمكن المهايئ من عرض الحمولة. - يعود إلى نص احتياطي محافظ عندما يكون المهايئ غائبًا أو غير قادر على العرض.
- يرسل الحمولة الناتجة عبر مسار تسليم القناة العادي.
- يطبق بيانات وصفية للتسليم مثل
delivery.pinبعد أول رسالة تم إرسالها بنجاح.
قواعد التدرج
يجب أن يكون العرض آمنًا للإرسال على القنوات المحدودة. يتضمن النص الاحتياطي:titleكسطر أول- كتل
textعلى شكل فقرات عادية - كتل
contextعلى شكل أسطر سياق مضغوطة - كتل
dividerعلى شكل فاصل مرئي - تسميات الأزرار، بما في ذلك عناوين URL لأزرار الروابط
- تسميات خيارات القوائم المنسدلة
- Telegram مع تعطيل الأزرار المضمنة يرسل نصًا احتياطيًا.
- القناة التي لا تدعم القوائم المنسدلة تسرد خياراتها كنص.
- زر يعتمد على URL فقط يصبح إما زر رابط أصليًا أو سطر URL احتياطيًا.
- لا تؤدي حالات فشل التثبيت الاختيارية إلى فشل الرسالة المرسلة.
delivery.pin.required: true؛ فإذا طُلب التثبيت بوصفه
مطلوبًا ولم تتمكن القناة من تثبيت الرسالة المرسلة، يبلغ التسليم عن فشل.
ربط الـ provider
أدوات العرض المجمعة الحالية:| القناة | هدف العرض الأصلي | ملاحظات |
|---|---|---|
| Discord | Components وحاويات المكونات | يحافظ على channelData.discord.components القديم للجهات الحالية المنتجة للحمولات الأصلية الخاصة بالـ provider، لكن يجب أن تستخدم عمليات الإرسال المشتركة الجديدة presentation. |
| Slack | Block Kit | يحافظ على channelData.slack.blocks القديم للجهات الحالية المنتجة للحمولات الأصلية الخاصة بالـ provider، لكن يجب أن تستخدم عمليات الإرسال المشتركة الجديدة presentation. |
| Telegram | نص بالإضافة إلى inline keyboards | تتطلب الأزرار/القوائم المنسدلة إمكانية الأزرار المضمنة في السطح المستهدف؛ وإلا يُستخدم النص الاحتياطي. |
| Mattermost | نص بالإضافة إلى props تفاعلية | تتدرج الكتل الأخرى إلى نص. |
| Microsoft Teams | Adaptive Cards | يُضمَّن نص message العادي مع البطاقة عندما يتم توفير الاثنين معًا. |
| Feishu | بطاقات تفاعلية | يمكن أن يستخدم رأس البطاقة title؛ ويتجنب المتن تكرار ذلك العنوان. |
| القنوات العادية | نص احتياطي | ما تزال القنوات التي لا تملك أداة عرض تحصل على ناتج قابل للقراءة. |
Presentation مقابل InteractiveReply
يُعدInteractiveReply المجموعة الداخلية الأقدم المستخدمة بواسطة الموافقة ومساعدات
التفاعل. وهو يدعم:
- النص
- الأزرار
- القوائم المنسدلة
MessagePresentation فهو عقد الإرسال المشترك القياسي. ويضيف:
- العنوان
- النبرة
- السياق
- الفاصل
- الأزرار المعتمدة على URL فقط
- بيانات وصفية عامة للتسليم عبر
ReplyPayload.delivery
openclaw/plugin-sdk/interactive-runtime عند الربط مع
الشفرة الأقدم:
MessagePresentation مباشرة أو تنتجه مباشرة.
تثبيت التسليم
التثبيت هو سلوك تسليم، وليس عرضًا. استخدمdelivery.pin بدلًا من
الحقول الأصلية الخاصة بالـ provider مثل channelData.telegram.pin.
الدلالات:
pin: trueيثبت أول رسالة تم تسليمها بنجاح.- القيمة الافتراضية لـ
pin.notifyهيfalse. - القيمة الافتراضية لـ
pin.requiredهيfalse. - تتدرج حالات فشل التثبيت الاختيارية وتبقي الرسالة المرسلة كما هي.
- تؤدي حالات فشل التثبيت المطلوبة إلى فشل التسليم.
- في الرسائل المقسمة إلى مقاطع، يتم تثبيت أول مقطع مُسلَّم، وليس المقطع الأخير.
pin وunpin وpins موجودة
للرسائل الحالية التي يدعم فيها الـ provider تلك العمليات.
قائمة التحقق لمؤلف Plugin
- صرّح بـ
presentationمنdescribeMessageTool(...)عندما تتمكن القناة من عرض العرض الدلالي أو تدرجه بأمان. - أضف
presentationCapabilitiesإلى مهايئ الإرسال الصادر في وقت التشغيل. - نفّذ
renderPresentationفي شيفرة وقت التشغيل، وليس في شيفرة إعداد Plugin في مستوى التحكم. - أبقِ مكتبات واجهة المستخدم الأصلية خارج مسارات الإعداد/الفهرسة الساخنة.
- حافظ على حدود المنصة في أداة العرض والاختبارات.
- أضف اختبارات احتياطية للأزرار غير المدعومة والقوائم المنسدلة غير المدعومة وأزرار URL
وتكرار العنوان/النص وعمليات الإرسال المختلطة بين
messageوpresentation. - أضف دعم تثبيت التسليم عبر
deliveryCapabilities.pinوpinDeliveredMessageفقط عندما يتمكن الـ provider من تثبيت معرّف الرسالة المرسلة. - لا تكشف حقولًا أصلية جديدة خاصة بالـ provider للبطاقات/الكتل/المكونات/الأزرار عبر مخطط إجراء الرسائل المشترك.