فرادادهٔ نمایش ماتریس

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

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

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

فراداده در محتوای رویداد Matrix ذخیره می‌شود:

{
  "msgtype": "m.text",
  "body": "Select model\n\n- DeepSeek: /model deepseek/deepseek-chat",
  "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 نسخهٔ طرح‌وارهٔ فرادادهٔ ارائهٔ Matrix است. type یک تفکیک‌گر پایدار برای کلاینت‌های آگاه از OpenClaw است. کلاینت‌ها باید مقدارهای ناشناختهٔ type، نسخه‌های ناشناخته‌ای را که نمی‌توانند با اطمینان تفسیر کنند، و انواع بلوک ناشناخته را نادیده بگیرند.

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

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

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

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

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

• buttons
• select
• context
• divider

کلاینت‌ها باید این بلوک‌ها را به‌عنوان راهنمایی‌های ارائهٔ best-effort در نظر بگیرند. فیلدهای ناشناخته و انواع بلوک ناشناخته باید نادیده گرفته شوند، نه اینکه باعث شکست رندر کل پیام شوند.

# تعامل‌ها

این فراداده معناشناسی callback در Matrix اضافه نمی‌کند. مقدارهای گزینهٔ دکمه و انتخاب‌گر، payloadهای تعامل جایگزین هستند، معمولاً دستورهای اسلش یا دستورهای متنی. یک کلاینت Matrix که می‌خواهد از تعامل پشتیبانی کند، می‌تواند مقدار انتخاب‌شده را به‌عنوان یک پیام عادی به اتاق بفرستد.

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

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

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

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

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

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

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