消息适配器

声明并接入核心用于通过你的通道发送的 message 适配器。这是构建通道插件指南的一部分。

消息适配器¶

使用来自 openclaw/plugin-sdk/channel-outbound 的 defineChannelMessageAdapter 暴露一个 message 适配器。仅声明你的原生传输实际支持的持久最终发送能力，并由契约测试证明原生副作用和返回的回执。将文本/媒体发送指向旧版 outbound 适配器使用的相同传输函数。完整的 API 契约、能力矩阵、回执规则、实时预览最终化、接收确认策略、测试和迁移表，请参见通道出站 API。

如果你的现有 outbound 适配器已经具备正确的发送方法和能力元数据，请使用 createChannelMessageAdapterFromOutbound(...) 派生 message 适配器，而不是手写另一个桥接。适配器发送返回 MessageReceipt 值。对于旧版 ID，请使用 listMessageReceiptPlatformIds(...) 或 resolveMessageReceiptPrimaryId(...) 派生它们，而不是保留并行的 messageIds 字段。

对于聚合已确认可见发送的回合适配器，请使用来自 openclaw/plugin-sdk/channel-inbound 的 createAcceptedChannelDeliveryResult(...)。它将原生 results 与逻辑 deliveryResults 组合在一起，包括部分投递错误的已接受子集。逻辑结果的回执优先于其旧版消息 ID。该结果携带回执、messageIds（包括空数组）以及 visibleReplySent: true；路由字段保留在回执中。可选的 content 会透传，kind 和 replyToId 使用回执构建器的规则。将接受副作用、内容合并、抑制以及无身份结果是否需要回执保留在适配器中。

通道操作和适配器能力来自所选插件注册。省略的 actions、message 或 outbound 接口面不会从具有相同通道 ID 的其他插件中填充。在注册表作用域内创建的预置投递处理程序，在调用者离开作用域后被调用时仍保留该处理程序。

精确声明实时和最终化器能力——核心使用这些能力来决定通道可以做什么，声明行为与实际行为之间的偏差会导致契约测试失败：

具有预览的通道应使用来自 openclaw/plugin-sdk/channel-outbound 的 createLivePreviewLifecycle(...) 进行最终接受、提升和清理。提供真实的传输操作和显式投递结果，而不是保留通道本地的最终/清理标志。原生流和持久卡片保留其传输特定的最终化；它们无需假装是可删除的草稿。参见进度和预览投递所有权。

确保声明的能力由 verifyChannelMessageLiveCapabilityAdapterProofs(...) 和 verifyChannelMessageLiveFinalizerProofs(...) 测试支撑，使原生进度、编辑、回退/保留、清理和回执行为不会悄然漂移。

进度可见性验收¶

进度回调报告操作员可以看到的内容，而不仅仅是插件排队的内容。在接受可见进度后返回 true，在投递待定或未发生可见更新时返回 false。现有返回 void 的同步和异步回调保持向后兼容，并被视为可见；新的支持验收的实现应使用显式布尔值。

静默进度展示¶

当工具行被禁用时，原生进度渲染器必须保留审批请求，同时保留编写的进度文本和计划行。中间工具失败和非零命令退出遵循工具行可见性设置；它们不得绕过静默模式。终结任务错误仍使用正常错误投递。共享进度合成器将此策略应用于其快照。

当第二个参数被省略或为 undefined 时，resolveChannelStreamingPreviewToolProgress(entry, defaultValue?, mode?) 保持其出厂默认值 true。捆绑通道将 mode !== "progress" 作为第二个参数，并将其解析后的流模式作为第三个参数，因此未配置的 progress 草稿会隐藏普通工具行，而 partial 和 block 预览会显示它们。

合成器和格式化器的 presentation: "summary" 选项以及清单格式化器的 plain: true 选项已弃用，但在下一个破坏性 SDK 版本发布前仍保留其显式输出。新调用方应省略它们，并使用 streaming.progress.toolProgress 通过标准进度标记控制工具行。

在消费预置代理项时，使用 preparedItems: true 创建合成器。随后 pushItemEvent 负责可见工具进度；原始工具、命令输出和补丁回调保留诊断记录，而不会添加重复行。对于使用原始回调的现有插件，请省略此选项。它们的参数、详细模式、自定义行构建器以及终端命令/补丁渲染仍受支持。这是一个适配器能力，而不是用户配置设置。

静默确认与合并进度¶

createStatusReactionController({ presentation: "acknowledgement", ... }) 在工作期间和成功时保留初始反应，跳过非活动警告，并保留现有的错误/清理生命周期。默认 activity 策略继续暴露详细生命周期反应。

对于编辑或原生进度，createDraftStreamLoop 和可终结草稿控制接受 coalesceInFlight: true，以将发送期间到达的后台更新保留到下一个节流窗口。显式 flush() 仍会绕过延迟，用于注意和终结。在关闭或轮换流之前，取消待处理更新并等待进行中的工作。

使用 createFinalizableDraftLifecycle 用于物理删除的托管，而不是维护插件本地重试队列。retire(id) 会认领一个已分离的预览；retire(id, { defer: true }) 会记录它而不立即删除。cleanupPending() 会重试已退役 ID，而不删除当前预览。当传输清理策略必须更改时，向 cleanupPending 传入同步 prepareCleanup 回调；它会与清除操作按顺序运行，且在删除之前执行。被拒绝的删除仍保持所有权，供后续清理尝试使用。

评论投递所有权¶

当通道支持持久化评论消息时，设置 commentaryPayloadsEnabled: true。通常在一个不断演进的进度草稿中渲染评论的通道，也可以提供 shouldDeliverCommentaryPayloads。核心会冻结本轮的详细可见性，通过 onVerboseProgressVisibility 注册该 getter，在分发前评估一次投递回调，并将该结果快照用于整轮。会话更改将在下一轮生效。除非 commentaryPayloadsEnabled 也为 true，否则该回调不生效；没有该静态选择加入，核心既不会评估回调，也不会冻结已注册的可见性 getter。

当草稿拥有正常进度时返回 false，当详细进度使该草稿让位于持久化评论时返回 true。保持回调同步，并只读取通道所有、已准备好的状态。省略它会为使用静态选择加入的现有插件保留持久化投递。该回调不控制推理、部分回复、工具进度或最终答案。

延迟平台确认的入站接收器应声明 message.receive.defaultAckPolicy 和 supportedAckPolicies，而不是将确认时序隐藏在监控器本地状态中。使用 verifyChannelMessageReceiveAckPolicyAdapterProofs(...) 覆盖每个已声明的策略。

TTS 语音投递¶

在 capabilities.tts.voice 下声明原生语音留言行为。当 TTS 提供商应生成原生语音留言格式时，设置 synthesisTarget: "voice-note"。仅当出站语音操作接受可见最终文本并执行其传输的字幕和溢出规则时，设置 captionedFinalText: true。然后核心会为该操作保留最终模式流式文本，并在证明语音负载未发送时回退到文本。

旧版 dispatchInboundReplyWithBase 辅助函数仍可从已弃用的 openclaw/plugin-sdk/inbound-reply-dispatch 兼容垫片中获取。不要在新通道代码中使用它；请改用 openclaw/plugin-sdk/channel-outbound 上的 message 适配器、回执以及接收/发送生命周期辅助函数。