بيانات Matrix الوصفية للعرض

يرفق OpenClaw بيانات تعريف MessagePresentation الموحّدة بأحداث Matrix الصادرة من النوع m.room.message ضمن مفتاح المحتوى com.openclaw.presentation.

تستمر تطبيقات Matrix القياسية في عرض النص العادي في body. ويمكن للتطبيقات المتوافقة مع OpenClaw قراءة بيانات التعريف المنظّمة وعرض واجهة مستخدم أصلية، مثل الأزرار وقوائم الاختيار وصفوف السياق والفواصل.

محتوى الحدث

{  "msgtype": "m.text",  "body": "Select model\n\nChoose model:\n- DeepSeek",  "com.openclaw.presentation": {    "version": 1,    "type": "message.presentation",    "title": "Select model",    "tone": "info",    "blocks": [      {        "type": "select",        "placeholder": "Choose model",        "options": [          {            "label": "DeepSeek",            "value": "/model deepseek/deepseek-chat"          }        ]      }    ]  }}

• يمثّل version إصدار مخطط بيانات التعريف؛ والإصدار الحالي هو 1. أما type فهو مُميّز ثابت، وقيمته دائمًا "message.presentation". ولا يُصدر محوّل Matrix إلا حمولات تحمل هذا الإصدار والنوع بالضبط؛ وبالمثل، ينبغي للتطبيقات تجاهل الإصدارات غير المعروفة التي لا يمكنها تفسيرها بأمان، وقيم type غير المعروفة، وأنواع الكتل غير المعروفة.
• يُعدّ title وtone (info، وsuccess، وwarning، وdanger، وneutral) تلميحين اختياريين.
• يمكن للأزرار وخيارات قوائم الاختيار أن تحمل action ذا نوع محدد ({ "type": "command", "command": "/..." } أو { "type": "callback", "value": "..." }) إلى جانب السلسلة القديمة value. فضّل action عند وجود كليهما.

سلوك الرجوع الاحتياطي

يعرض OpenClaw دائمًا نصًا عاديًا احتياطيًا قابلًا للقراءة داخل body. وتُعدّ بيانات التعريف المنظّمة إضافة اختيارية، ويجب ألا تكون مطلوبة لتحقيق التوافق الأساسي مع Matrix.

قواعد العرض الاحتياطي:

• يُعرض محتوى title وtext وcontext كأسطر نصية عادية.
• تُعرض الأزرار التي تتضمن إجراء command بالصيغة label: `/command` حتى يبقى الأمر قابلًا للنسخ. أما الأزرار التي تتضمن إجراء callback أو قيمة value قديمة فقط، فتُعرض بتسميتها وحدها كي تظل قيم الاستدعاء غير الشفافة خاصة؛ وتُعرض الأزرار المعطّلة دائمًا بتسميتها وحدها. وتُعرض أزرار عناوين URL وتطبيقات الويب بالصيغة label: URL.
• تعرض كتل الاختيار النص النائب (أو Options:) كعنوان، متبوعًا بأسطر خيارات تحتوي على التسميات فقط.
• إذا لم يُعرض أي شيء، كما في عرض تقديمي لا يحتوي إلا على فاصل، يرجع النص في body إلى ---.

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

الكتل المدعومة

يعلن محوّل Matrix الصادر عن دعم أصلي لما يلي:

• buttons
• select
• context
• divider

تُدعم كتل text دائمًا عبر النص الاحتياطي في body. تعامل مع جميع الكتل كتلميحات عرض تُطبّق بأفضل جهد ممكن؛ وتجاهل الحقول وأنواع الكتل غير المعروفة بدلًا من رفض الرسالة بأكملها.

التفاعلات

لا تضيف بيانات التعريف هذه دلالات استدعاء إلى Matrix. تمثّل قيم الأزرار وقوائم الاختيار حمولات تفاعل احتياطية، وتكون عادةً أوامر تبدأ بشرطة مائلة أو أوامر نصية. وعلى تطبيق Matrix الذي يريد دعم التفاعل أن يستخرج قيمة عنصر التحكم (action.command، ثم action.value، ثم value) ويرسلها مجددًا إلى الغرفة كرسالة عادية.

على سبيل المثال، يمكن التعامل مع زر قيمته /model deepseek/deepseek-chat بإرسال تلك القيمة كرسالة Matrix نصية مشفّرة في الغرفة نفسها.

العلاقة ببيانات تعريف الموافقة

يُستخدم com.openclaw.presentation للعرض العام للرسائل الغنية.

تستخدم مطالبات الموافقة بيانات التعريف المخصصة com.openclaw.approval لأن الموافقات تحمل حالة وقرارات وتفاصيل تنفيذ/Plugin حساسة للسلامة. وإذا وُجد مفتاحا بيانات التعريف كلاهما في الحدث نفسه، فينبغي للتطبيقات تفضيل عارض الموافقة المخصص.

رسائل الوسائط

عندما يحتوي الرد على عدة عناوين URL لوسائط، يرسل OpenClaw حدث Matrix واحدًا لكل عنوان URL لوسيط. ولا يُرفق نص التسمية التوضيحية وبيانات تعريف العرض إلا بالحدث الأول، بحيث تحصل التطبيقات على حمولة منظّمة واحدة ثابتة دون عارضات مكررة. وتنطبق القاعدة نفسها عند تقسيم النص الطويل على عدة أحداث: تُرفق بيانات التعريف بالحدث الأول فقط.

حافظ على إيجاز بيانات تعريف العرض. وينبغي أن يبقى النص الكبير الظاهر للمستخدم في body وأن يستخدم مسار تقسيم نص Matrix المعتاد.