OpenClaw Matrix 通道富消息规范com.openclaw.presentation 元数据的设计与实现【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawOpenClaw 在向 Matrix 房间发送消息时除了常规的m.room.message事件body纯文本外还会附加一份结构化的MessagePresentation元数据挂载在com.openclaw.presentation事件内容键下。阅读本文你将理解这份元数据的完整字段规范、原生 Matrix 客户端的纯文本回退渲染规则、OpenClaw 感知型客户端如何解析并渲染按钮/下拉选择等原生控件以及交互回发interactions的约定同时结合extensions/matrix插件源码说明这份元数据在出站管线中是如何被生成、校验和裁剪的适合开发 Matrix 端渲染 OpenClaw 富回复的客户端开发者以及排查com.openclaw.presentation事件内容的工程师。元数据概览与设计原则OpenClaw 将归一化后的MessagePresentation元数据附加到出站 Matrixm.room.message事件的com.openclaw.presentation内容键上见 docs/channels/matrix-presentation.md。核心设计原则是附加性additive原生StockMatrix 客户端继续渲染纯文本body行为完全不受影响OpenClaw 感知的客户端可以读取结构化元数据渲染按钮、下拉选择、上下文行、分割线等原生 UI结构化元数据必须成为富展示绝不能成为基础 Matrix 互操作的前提。从源码看这一原则在 outbound.ts 中被固化为三个常量内容键名com.openclaw.presentation、稳定的类型判别值message.presentation以及空展示场景下的兜底文本---。事件内容结构一条携带展示元数据的出站事件内容形如{ 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 -s } ] } ] } }字段规范说明version元数据 schema 版本当前为1。type是稳定判别符恒为message.presentation。Matrix 适配器只会发出version与type均完全匹配的载荷客户端也应同样忽略无法安全解释的未知版本号、未知type值与未知块类型。这一点在源码中得到印证outbound.ts 中的resolveMatrixPresentationContent对传入载荷做严格校验presentation.version ! 1或presentation.type ! message.presentation时直接返回undefined拒绝附加元数据而 buildMatrixPresentationContent 在发出前会强制覆写version: 1与type保证出站载荷永远精确匹配协议契约。title与tone可选的展示提示。tone取值范围为info、success、warning、danger、neutral。按钮与下拉选项可携带类型化的action字段{ type: command, command: /... }或{ type: callback, value: ... }与遗留的字符串value并存。两者同时存在时应优先使用action。纯文本回退渲染规则OpenClaw 总会把可读的纯文本回退写入body保证任何客户端都能展示基本内容。回退渲染的具体规则为title、text、context块渲染为普通文本行携带command动作的按钮渲染为label: /command使命令保持可复制携带callback动作或仅有遗留value的按钮只渲染标签label-only让不透明的回调值保持私密禁用disabled按钮一律只渲染标签URL 与 web-app 按钮渲染为label: URLselect块将 placeholder或Options:渲染为标题行选项以 label-only 的行形式列出若所有块都渲染不出内容例如仅含分割线的展示body兜底为---。源码中该逻辑经由 plugin-sdk 的openclaw/plugin-sdk/interactive-runtime模块导入的renderMessagePresentationFallbackText完成renderMatrixPresentationPayload 以原始payload.text与presentation为输入、以emptyFallback: ---为参数生成回退文本将其替换payload.text后再在channelData.matrix.extraContent下写入com.openclaw.presentation键。随后 resolveMatrixPayloadText 在真正发送时再次兜底若文本为空但存在展示元数据仍发送---。这样即使展示块全部失效客户端也不会收到空消息。对不支持结构化元数据的客户端它们继续展示回退文本OpenClaw 感知型客户端展示时可优先使用结构化元数据同时保留回退文本用于复制、搜索、通知与无障碍accessibility场景。支持的展示块与能力声明Matrix 出站适配器对外声明advertise的原生支持块为buttonsselectcontextdividertext块始终通过回退body获得支持。所有块都应视为尽力而为best-effort的展示提示遇到未知字段或未知块类型时应忽略而不是让整个消息发送失败。从源码结构看这份能力声明集中在 MATRIX_PRESENTATION_CAPABILITIESsupported: truebuttons/selects/context/divider均为true并附带文本限制说明——markdownDialect: markdown消息正文按 Markdown 方言处理与supportsEdit: true。该能力对象被传入renderPresentationForDelivery见 prepareMatrixReplyPayload由插件 SDK 的交互运行时依据能力对展示做裁剪与渲染再交给renderMatrixPresentationPayload完成最终载荷组装。出站适配器matrixOutboundoutbound.ts在注册时同样暴露这份presentationCapabilities使网关层可以按通道能力决定是否下发富展示内容。交互机制回发普通消息而非平台回调这份元数据不引入任何 Matrix 平台回调语义。按钮与下拉选项的取值是回退式交互载荷通常就是斜杠命令或文本命令。希望支持交互的 Matrix 客户端只需解析控件值并按优先级取action.command→action.value→value然后把该值作为一条普通消息发送回所在房间即可。例如某个按钮的值为/model deepseek/deepseek-chat -s客户端可以在同一房间中以加密文本消息发送该值来触发模型切换。其中显式的会话标志-s的作用是无论 模型选择作用域 如何配置该命令都只更新当前会话而不会改写默认设置。与审批approval元数据的边界com.openclaw.presentation面向通用富消息展示审批提示approval prompts则使用专门的com.openclaw.approval元数据因为审批携带安全敏感的状态、决策结果以及 exec/plugin 细节。同一事件若同时存在两个元数据键客户端应优先使用专用的审批渲染器。这一划分与 Matrix 插件的源码结构一致extensions/matrix/src 下存在独立的审批处理模块族如approval-native.ts、approval-ids.ts、approval-handler.runtime.ts、approval-reactions.ts等与展示元数据路径outbound.ts相互独立从源码结构看两者确为并行机制。媒体消息与分块下的元数据挂载规则当一条回复包含多个媒体 URL 时OpenClaw 按“每个媒体 URL 一个 Matrix 事件”发送。文案caption与展示元数据只挂载在第一个事件上使客户端获得唯一、稳定的结构化载荷避免重复渲染。长文本跨事件分块时同样适用此规则元数据只随第一个事件发出。源码印证位于 outbound.tssendPayloadMediaSequence逐媒体发送时extraContent参数被写为isFirst ? resolveMatrixExtraContent(payload) : undefined——只有首个发送分片携带com.openclaw.presentation键。同时适配器注册了chunker: chunkTextForOutbound、chunkerMode: markdown与textChunkLimit: 4000outbound.ts对应文档的约束保持展示元数据精简大段用户可见文本应留在body中走 Matrix 常规文本分块路径。验证与延伸阅读文档中的行为在插件测试中有对应覆盖可结合阅读以验证实现契约extensions/matrix/src/outbound.test.ts出站适配器含展示内容解析与发送测试extensions/matrix/src/channel.message-adapter.test.ts通道消息适配器行为测试extensions/matrix/src/matrix/monitor/replies.presentation.test.ts 与 extensions/matrix/src/matrix/monitor/handler.reply-presentation.test.ts回复展示处理链测试。总体来看com.openclaw.presentation是一份“最小侵入”的通道富展示协议版本与类型双校验保证互操作安全纯文本回退保证原生客户端兼容首事件挂载与 4000 字符分块上限控制事件数量与体积而交互完全复用 Matrix 普通消息语义客户端实现成本极低。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OpenClaw Matrix 通道富消息规范：com.openclaw.presentation 元数据的设计与实现
OpenClaw Matrix 通道富消息规范com.openclaw.presentation 元数据的设计与实现【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawOpenClaw 在向 Matrix 房间发送消息时除了常规的m.room.message事件body纯文本外还会附加一份结构化的MessagePresentation元数据挂载在com.openclaw.presentation事件内容键下。阅读本文你将理解这份元数据的完整字段规范、原生 Matrix 客户端的纯文本回退渲染规则、OpenClaw 感知型客户端如何解析并渲染按钮/下拉选择等原生控件以及交互回发interactions的约定同时结合extensions/matrix插件源码说明这份元数据在出站管线中是如何被生成、校验和裁剪的适合开发 Matrix 端渲染 OpenClaw 富回复的客户端开发者以及排查com.openclaw.presentation事件内容的工程师。元数据概览与设计原则OpenClaw 将归一化后的MessagePresentation元数据附加到出站 Matrixm.room.message事件的com.openclaw.presentation内容键上见 docs/channels/matrix-presentation.md。核心设计原则是附加性additive原生StockMatrix 客户端继续渲染纯文本body行为完全不受影响OpenClaw 感知的客户端可以读取结构化元数据渲染按钮、下拉选择、上下文行、分割线等原生 UI结构化元数据必须成为富展示绝不能成为基础 Matrix 互操作的前提。从源码看这一原则在 outbound.ts 中被固化为三个常量内容键名com.openclaw.presentation、稳定的类型判别值message.presentation以及空展示场景下的兜底文本---。事件内容结构一条携带展示元数据的出站事件内容形如{ 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 -s } ] } ] } }字段规范说明version元数据 schema 版本当前为1。type是稳定判别符恒为message.presentation。Matrix 适配器只会发出version与type均完全匹配的载荷客户端也应同样忽略无法安全解释的未知版本号、未知type值与未知块类型。这一点在源码中得到印证outbound.ts 中的resolveMatrixPresentationContent对传入载荷做严格校验presentation.version ! 1或presentation.type ! message.presentation时直接返回undefined拒绝附加元数据而 buildMatrixPresentationContent 在发出前会强制覆写version: 1与type保证出站载荷永远精确匹配协议契约。title与tone可选的展示提示。tone取值范围为info、success、warning、danger、neutral。按钮与下拉选项可携带类型化的action字段{ type: command, command: /... }或{ type: callback, value: ... }与遗留的字符串value并存。两者同时存在时应优先使用action。纯文本回退渲染规则OpenClaw 总会把可读的纯文本回退写入body保证任何客户端都能展示基本内容。回退渲染的具体规则为title、text、context块渲染为普通文本行携带command动作的按钮渲染为label: /command使命令保持可复制携带callback动作或仅有遗留value的按钮只渲染标签label-only让不透明的回调值保持私密禁用disabled按钮一律只渲染标签URL 与 web-app 按钮渲染为label: URLselect块将 placeholder或Options:渲染为标题行选项以 label-only 的行形式列出若所有块都渲染不出内容例如仅含分割线的展示body兜底为---。源码中该逻辑经由 plugin-sdk 的openclaw/plugin-sdk/interactive-runtime模块导入的renderMessagePresentationFallbackText完成renderMatrixPresentationPayload 以原始payload.text与presentation为输入、以emptyFallback: ---为参数生成回退文本将其替换payload.text后再在channelData.matrix.extraContent下写入com.openclaw.presentation键。随后 resolveMatrixPayloadText 在真正发送时再次兜底若文本为空但存在展示元数据仍发送---。这样即使展示块全部失效客户端也不会收到空消息。对不支持结构化元数据的客户端它们继续展示回退文本OpenClaw 感知型客户端展示时可优先使用结构化元数据同时保留回退文本用于复制、搜索、通知与无障碍accessibility场景。支持的展示块与能力声明Matrix 出站适配器对外声明advertise的原生支持块为buttonsselectcontextdividertext块始终通过回退body获得支持。所有块都应视为尽力而为best-effort的展示提示遇到未知字段或未知块类型时应忽略而不是让整个消息发送失败。从源码结构看这份能力声明集中在 MATRIX_PRESENTATION_CAPABILITIESsupported: truebuttons/selects/context/divider均为true并附带文本限制说明——markdownDialect: markdown消息正文按 Markdown 方言处理与supportsEdit: true。该能力对象被传入renderPresentationForDelivery见 prepareMatrixReplyPayload由插件 SDK 的交互运行时依据能力对展示做裁剪与渲染再交给renderMatrixPresentationPayload完成最终载荷组装。出站适配器matrixOutboundoutbound.ts在注册时同样暴露这份presentationCapabilities使网关层可以按通道能力决定是否下发富展示内容。交互机制回发普通消息而非平台回调这份元数据不引入任何 Matrix 平台回调语义。按钮与下拉选项的取值是回退式交互载荷通常就是斜杠命令或文本命令。希望支持交互的 Matrix 客户端只需解析控件值并按优先级取action.command→action.value→value然后把该值作为一条普通消息发送回所在房间即可。例如某个按钮的值为/model deepseek/deepseek-chat -s客户端可以在同一房间中以加密文本消息发送该值来触发模型切换。其中显式的会话标志-s的作用是无论 模型选择作用域 如何配置该命令都只更新当前会话而不会改写默认设置。与审批approval元数据的边界com.openclaw.presentation面向通用富消息展示审批提示approval prompts则使用专门的com.openclaw.approval元数据因为审批携带安全敏感的状态、决策结果以及 exec/plugin 细节。同一事件若同时存在两个元数据键客户端应优先使用专用的审批渲染器。这一划分与 Matrix 插件的源码结构一致extensions/matrix/src 下存在独立的审批处理模块族如approval-native.ts、approval-ids.ts、approval-handler.runtime.ts、approval-reactions.ts等与展示元数据路径outbound.ts相互独立从源码结构看两者确为并行机制。媒体消息与分块下的元数据挂载规则当一条回复包含多个媒体 URL 时OpenClaw 按“每个媒体 URL 一个 Matrix 事件”发送。文案caption与展示元数据只挂载在第一个事件上使客户端获得唯一、稳定的结构化载荷避免重复渲染。长文本跨事件分块时同样适用此规则元数据只随第一个事件发出。源码印证位于 outbound.tssendPayloadMediaSequence逐媒体发送时extraContent参数被写为isFirst ? resolveMatrixExtraContent(payload) : undefined——只有首个发送分片携带com.openclaw.presentation键。同时适配器注册了chunker: chunkTextForOutbound、chunkerMode: markdown与textChunkLimit: 4000outbound.ts对应文档的约束保持展示元数据精简大段用户可见文本应留在body中走 Matrix 常规文本分块路径。验证与延伸阅读文档中的行为在插件测试中有对应覆盖可结合阅读以验证实现契约extensions/matrix/src/outbound.test.ts出站适配器含展示内容解析与发送测试extensions/matrix/src/channel.message-adapter.test.ts通道消息适配器行为测试extensions/matrix/src/matrix/monitor/replies.presentation.test.ts 与 extensions/matrix/src/matrix/monitor/handler.reply-presentation.test.ts回复展示处理链测试。总体来看com.openclaw.presentation是一份“最小侵入”的通道富展示协议版本与类型双校验保证互操作安全纯文本回退保证原生客户端兼容首事件挂载与 4000 字符分块上限控制事件数量与体积而交互完全复用 Matrix 普通消息语义客户端实现成本极低。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
