Mainstream messaging

Siêu dữ liệu trình bày của Matrix

OpenClaw đính kèm siêu dữ liệu MessagePresentation đã chuẩn hóa vào các sự kiện Matrix m.room.message gửi đi dưới khóa nội dung com.openclaw.presentation.

Các ứng dụng Matrix tiêu chuẩn vẫn hiển thị body ở dạng văn bản thuần. Các ứng dụng hỗ trợ OpenClaw có thể đọc siêu dữ liệu có cấu trúc và hiển thị giao diện người dùng gốc như nút, danh sách chọn, hàng ngữ cảnh và đường phân cách.

Nội dung sự kiện

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 là phiên bản lược đồ siêu dữ liệu; phiên bản hiện tại là 1. type là giá trị phân biệt ổn định, luôn là "message.presentation". Bộ điều hợp Matrix chỉ phát các tải trọng có chính xác phiên bản và kiểu này; tương tự, ứng dụng nên bỏ qua các phiên bản không xác định mà chúng không thể diễn giải an toàn, các giá trị type không xác định và các kiểu khối không xác định.
title và tone (info, success, warning, danger, neutral) là các gợi ý không bắt buộc.
Nút và tùy chọn chọn có thể mang một action được định kiểu ({ "type": "command", "command": "/..." } hoặc { "type": "callback", "value": "..." }) cùng với chuỗi value cũ. Ưu tiên action khi cả hai cùng xuất hiện.

Hành vi dự phòng

OpenClaw luôn hiển thị nội dung dự phòng dạng văn bản thuần có thể đọc được vào body. Siêu dữ liệu có cấu trúc chỉ mang tính bổ sung và không được là yêu cầu bắt buộc để có khả năng tương tác Matrix cơ bản.

Quy tắc hiển thị dự phòng:

Nội dung title, text và context được hiển thị thành các dòng văn bản thuần.
Nút có hành động command được hiển thị thành nhãn: `/command` để lệnh vẫn có thể sao chép được. Nút có hành động callback hoặc chỉ có value cũ chỉ hiển thị nhãn để các giá trị gọi lại không rõ nghĩa vẫn được giữ riêng tư; nút bị vô hiệu hóa luôn chỉ hiển thị nhãn. Nút URL và ứng dụng web được hiển thị thành nhãn: URL.
Khối chọn hiển thị phần giữ chỗ (hoặc Tùy chọn:) làm tiêu đề, theo sau là các dòng tùy chọn chỉ có nhãn.
Nếu không hiển thị được nội dung nào, chẳng hạn một phần trình bày chỉ có đường phân cách, phần nội dung sẽ dùng --- làm dự phòng.

Các ứng dụng không được hỗ trợ vẫn hiển thị văn bản dự phòng. Các ứng dụng hỗ trợ OpenClaw có thể ưu tiên siêu dữ liệu có cấu trúc để hiển thị, đồng thời giữ lại nội dung dự phòng cho việc sao chép, tìm kiếm, thông báo và khả năng tiếp cận.

Các khối được hỗ trợ

Bộ điều hợp gửi đi của Matrix công bố hỗ trợ gốc cho:

buttons
select
context
divider

Các khối text luôn được hỗ trợ thông qua phần nội dung dự phòng. Hãy coi tất cả các khối là gợi ý trình bày theo khả năng tốt nhất; bỏ qua các trường và kiểu khối không xác định thay vì làm hỏng toàn bộ thông báo.

Tương tác

Siêu dữ liệu này không bổ sung ngữ nghĩa gọi lại cho Matrix. Giá trị của nút và tùy chọn chọn là các tải trọng tương tác dự phòng, thường là lệnh bắt đầu bằng dấu gạch chéo hoặc lệnh văn bản. Ứng dụng Matrix muốn hỗ trợ tương tác sẽ phân giải giá trị điều khiển (action.command, sau đó là action.value, rồi đến value) và gửi giá trị đó trở lại phòng dưới dạng thông báo thông thường.

Ví dụ: một nút có giá trị /model deepseek/deepseek-chat có thể được xử lý bằng cách gửi giá trị đó dưới dạng thông báo văn bản Matrix được mã hóa trong cùng phòng.

Mối quan hệ với siêu dữ liệu phê duyệt

com.openclaw.presentation dùng để trình bày thông báo đa dạng nói chung.

Lời nhắc phê duyệt sử dụng siêu dữ liệu chuyên dụng com.openclaw.approval vì các phê duyệt chứa trạng thái nhạy cảm về an toàn, quyết định và chi tiết thực thi/Plugin. Nếu cả hai khóa siêu dữ liệu cùng xuất hiện trên một sự kiện, ứng dụng nên ưu tiên trình hiển thị phê duyệt chuyên dụng.

Thông báo đa phương tiện

Khi câu trả lời chứa nhiều URL đa phương tiện, OpenClaw gửi một sự kiện Matrix cho mỗi URL đa phương tiện. Văn bản chú thích và siêu dữ liệu trình bày chỉ được đính kèm vào sự kiện đầu tiên để ứng dụng nhận được một tải trọng có cấu trúc ổn định mà không có trình hiển thị trùng lặp. Quy tắc tương tự áp dụng khi văn bản dài được chia thành nhiều phần trên các sự kiện: siêu dữ liệu chỉ đi kèm sự kiện đầu tiên.

Hãy giữ siêu dữ liệu trình bày gọn nhẹ. Văn bản dài hiển thị cho người dùng nên được giữ trong body và sử dụng luồng chia nhỏ văn bản Matrix thông thường.

Was this useful?