Mainstream messaging

Metadane prezentacji Matrix

OpenClaw dołącza znormalizowane metadane MessagePresentation do wychodzących zdarzeń Matrix m.room.message pod kluczem zawartości com.openclaw.presentation.

Standardowe klienty Matrix nadal renderują zwykły tekst z pola body. Klienty obsługujące OpenClaw mogą odczytywać metadane strukturalne i renderować natywny interfejs użytkownika, taki jak przyciski, listy wyboru, wiersze kontekstowe i separatory.

Zawartość zdarzenia

json

{  "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 to wersja schematu metadanych; bieżąca wersja to 1. type jest stabilnym dyskryminatorem, zawsze równym "message.presentation". Adapter Matrix emituje wyłącznie ładunki o dokładnie tej wersji i tym typie; klienty powinny analogicznie ignorować nieznane wersje, których nie mogą bezpiecznie interpretować, nieznane wartości type oraz nieznane typy bloków.
title i tone (info, success, warning, danger, neutral) są opcjonalnymi wskazówkami.
Przyciski i opcje wyboru mogą zawierać typowaną właściwość action ({ "type": "command", "command": "/..." } lub { "type": "callback", "value": "..." }) obok starszej wartości tekstowej value. Gdy występują obie, preferuj action.

Zachowanie awaryjne

OpenClaw zawsze renderuje w polu body czytelną reprezentację awaryjną w postaci zwykłego tekstu. Metadane strukturalne są dodatkiem i nie mogą być wymagane do podstawowej interoperacyjności z Matrix.

Reguły renderowania awaryjnego:

Zawartość title, text i context jest renderowana jako zwykłe wiersze.
Przyciski z akcją command są renderowane jako etykieta: `/command` , aby polecenie można było skopiować. Przyciski z akcją callback lub wyłącznie starszą wartością value są renderowane tylko jako etykieta, aby niejawne wartości wywołań zwrotnych pozostały prywatne; wyłączone przyciski są zawsze renderowane tylko jako etykieta. Przyciski adresów URL i aplikacji internetowych są renderowane jako etykieta: URL.
Bloki wyboru renderują tekst zastępczy (lub Opcje:) jako nagłówek oraz wiersze opcji zawierające wyłącznie etykiety.
Jeśli nic nie zostanie wyrenderowane, na przykład w prezentacji zawierającej wyłącznie separator, treścią awaryjną będzie ---.

Nieobsługiwane klienty nadal wyświetlają tekst awaryjny. Klienty obsługujące OpenClaw mogą preferować metadane strukturalne do wyświetlania, zachowując tekst awaryjny na potrzeby kopiowania, wyszukiwania, powiadomień i ułatwień dostępu.

Obsługiwane bloki

Adapter wychodzący Matrix deklaruje natywną obsługę następujących typów:

buttons
select
context
divider

Bloki text są zawsze obsługiwane za pośrednictwem treści awaryjnej. Wszystkie bloki należy traktować jako opcjonalne wskazówki dotyczące prezentacji; zamiast odrzucać całą wiadomość, należy ignorować nieznane pola i typy bloków.

Interakcje

Te metadane nie dodają semantyki wywołań zwrotnych Matrix. Wartości przycisków i opcji wyboru są awaryjnymi ładunkami interakcji, zazwyczaj poleceniami z ukośnikiem lub poleceniami tekstowymi. Klient Matrix, który chce obsługiwać interakcje, ustala wartość elementu sterującego (action.command, następnie action.value, a następnie value) i wysyła ją z powrotem do pokoju jako zwykłą wiadomość.

Na przykład przycisk o wartości /model deepseek/deepseek-chat można obsłużyć, wysyłając tę wartość jako zaszyfrowaną wiadomość tekstową Matrix w tym samym pokoju.

Relacja z metadanymi zatwierdzania

com.openclaw.presentation służy do ogólnej prezentacji rozbudowanych wiadomości.

Monity o zatwierdzenie używają dedykowanych metadanych com.openclaw.approval, ponieważ zatwierdzenia zawierają stan istotny dla bezpieczeństwa, decyzje oraz szczegóły wykonania i Pluginów. Jeśli oba klucze metadanych występują w tym samym zdarzeniu, klienty powinny preferować dedykowany mechanizm renderowania zatwierdzeń.

Wiadomości multimedialne

Gdy odpowiedź zawiera wiele adresów URL multimediów, OpenClaw wysyła po jednym zdarzeniu Matrix dla każdego adresu URL. Tekst podpisu i metadane prezentacji są dołączane wyłącznie do pierwszego zdarzenia, dzięki czemu klienty otrzymują jeden stabilny ładunek strukturalny bez powielonych mechanizmów renderowania. Ta sama reguła obowiązuje, gdy długi tekst jest dzielony między zdarzenia: metadane są przesyłane wyłącznie w pierwszym zdarzeniu.

Metadane prezentacji powinny być zwarte. Obszerny tekst widoczny dla użytkownika powinien pozostać w polu body i korzystać ze standardowego mechanizmu dzielenia tekstu Matrix.

Was this useful?