فرادادهٔ نمایش Matrix

OpenClaw فرادادهٔ نرمال‌شدهٔ MessagePresentation را به رویدادهای خروجی m.room.message در Matrix، زیر کلید محتوای 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) راهنماهای اختیاری هستند.
• دکمه‌ها و گزینه‌های انتخاب می‌توانند در کنار رشتهٔ قدیمی value، یک action نوع‌دار ({ "type": "command", "command": "/..." } یا { "type": "callback", "value": "..." }) داشته باشند. وقتی هر دو موجودند، action را ترجیح دهید.

رفتار جایگزین

OpenClaw همیشه یک متن سادهٔ خوانا را به‌عنوان جایگزین در body رندر می‌کند. فرادادهٔ ساخت‌یافته افزوده‌ای است و نباید برای تعامل‌پذیری پایهٔ Matrix الزامی باشد.

قواعد رندر جایگزین:

• محتوای title، text و context به‌صورت خطوط ساده رندر می‌شود.
• دکمه‌های دارای کنش command به‌شکل label: `/command` رندر می‌شوند تا فرمان قابل کپی باقی بماند. دکمه‌های دارای کنش callback یا فقط یک value قدیمی، تنها با برچسب رندر می‌شوند تا مقادیر مبهم فراخوانی خصوصی بمانند؛ دکمه‌های غیرفعال همیشه فقط با برچسب رندر می‌شوند. دکمه‌های URL و برنامهٔ وب به‌شکل label: URL رندر می‌شوند.
• بلوک‌های انتخاب، متن راهنما (یا Options:) را به‌صورت عنوان و سپس خطوط گزینه‌ها را فقط با برچسب رندر می‌کنند.
• اگر چیزی رندر نشود، برای مثال در نمایشی که فقط جداکننده دارد، بدنه به --- بازمی‌گردد.

کلاینت‌های پشتیبانی‌نشده همچنان متن جایگزین را نمایش می‌دهند. کلاینت‌های سازگار با OpenClaw می‌توانند برای نمایش، فرادادهٔ ساخت‌یافته را ترجیح دهند و در عین حال متن جایگزین را برای کپی، جست‌وجو، اعلان‌ها و دسترس‌پذیری حفظ کنند.

بلوک‌های پشتیبانی‌شده

آداپتور خروجی Matrix پشتیبانی بومی از موارد زیر را اعلام می‌کند:

• buttons
• select
• context
• divider

بلوک‌های text همیشه از طریق بدنهٔ جایگزین پشتیبانی می‌شوند. همهٔ بلوک‌ها را راهنماهای نمایشی مبتنی بر حداکثر تلاش در نظر بگیرید؛ به‌جای ناموفق کردن کل پیام، فیلدها و انواع بلوک ناشناخته را نادیده بگیرید.

تعامل‌ها

این فراداده، معناشناسی فراخوانی Matrix را اضافه نمی‌کند. مقادیر دکمه و انتخاب، بارهای تعامل جایگزین هستند که معمولاً فرمان‌های اسلش‌دار یا فرمان‌های متنی‌اند. کلاینت Matrix که می‌خواهد از تعامل پشتیبانی کند، مقدار کنترل را (action.command، سپس action.value و بعد value) تعیین می‌کند و آن را به‌صورت یک پیام عادی به اتاق بازمی‌فرستد.

برای مثال، دکمه‌ای با مقدار /model deepseek/deepseek-chat را می‌توان با ارسال همان مقدار به‌صورت یک پیام متنی رمزگذاری‌شدهٔ Matrix در همان اتاق مدیریت کرد.

ارتباط با فرادادهٔ تأیید

com.openclaw.presentation برای نمایش عمومی پیام‌های غنی است.

درخواست‌های تأیید از فرادادهٔ اختصاصی com.openclaw.approval استفاده می‌کنند، زیرا تأییدها شامل وضعیت حساس به ایمنی، تصمیم‌ها و جزئیات اجرا/Plugin هستند. اگر هر دو کلید فراداده در یک رویداد وجود داشته باشند، کلاینت‌ها باید رندرکنندهٔ اختصاصی تأیید را ترجیح دهند.

پیام‌های رسانه‌ای

وقتی یک پاسخ شامل چند URL رسانه‌ای باشد، OpenClaw برای هر URL رسانه‌ای یک رویداد Matrix می‌فرستد. متن شرح و فرادادهٔ نمایش فقط به نخستین رویداد پیوست می‌شوند تا کلاینت‌ها بدون رندرکننده‌های تکراری، یک بار ساخت‌یافتهٔ پایدار دریافت کنند. همین قاعده زمانی نیز اعمال می‌شود که متن طولانی میان چند رویداد قطعه‌بندی شود: فراداده فقط همراه نخستین رویداد ارسال می‌شود.

فرادادهٔ نمایش را فشرده نگه دارید. متن طولانی و قابل‌مشاهده برای کاربر باید در body باقی بماند و از مسیر عادی قطعه‌بندی متن Matrix استفاده کند.