فرادادهٔ ارائهٔ Matrix

OpenClaw فرادادهٔ نرمال‌شدهٔ MessagePresentation را به رویدادهای خروجی m.room.message در Matrix، زیر کلید محتوای com.openclaw.presentation پیوست می‌کند.

کلاینت‌های استاندارد Matrix همچنان متن سادهٔ body را رندر می‌کنند. کلاینت‌های سازگار با OpenClaw می‌توانند فرادادهٔ ساخت‌یافته را بخوانند و رابط کاربری بومی مانند دکمه‌ها، فهرست‌های انتخاب، ردیف‌های زمینه و جداکننده‌ها را رندر کنند.

محتوای رویداد

{  "msgtype": "m.text",  "body": "مدل را انتخاب کنید\n\nمدل را برگزینید:\n- DeepSeek",  "com.openclaw.presentation": {    "version": 1,    "type": "message.presentation",    "title": "مدل را انتخاب کنید",    "tone": "info",    "blocks": [      {        "type": "select",        "placeholder": "مدل را برگزینید",        "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 استفاده می‌کنند، زیرا تأییدها شامل وضعیت حساس از نظر ایمنی، تصمیم‌ها و جزئیات exec/plugin هستند. اگر هر دو کلید فراداده در یک رویداد وجود داشته باشند، کلاینت‌ها باید رندرکنندهٔ اختصاصی تأیید را ترجیح دهند.

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

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

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