消息适配器
消息适配器¶
声明并接入 message 适配器,核心(core)通过它经由你的渠道发送消息。本指南是 构建渠道插件 的一部分。
使用 openclaw/plugin-sdk/channel-outbound 中的 defineChannelMessageAdapter 暴露一个 message 适配器。只声明你的原生传输实际支持的持久最终发送能力,并由契约测试证明原生副作用和返回的回执。将文本/媒体发送指向旧版 outbound 适配器所使用的同一套传输函数。有关完整 API 契约、能力矩阵、回执规则、实时预览定稿、接收确认策略、测试和迁移表,请参阅 Channel outbound API。
如果你现有的 outbound 适配器已经具备正确的发送方法和能力元数据,请使用 createChannelMessageAdapterFromOutbound(...) 派生 message 适配器,而不要手写另一套桥接。适配器发送返回 MessageReceipt 值。对于旧版 id,请使用 listMessageReceiptPlatformIds(...) 或 resolveMessageReceiptPrimaryId(...) 派生它们,而不是保留并行的 messageIds 字段。
对于聚合已确认可见发送的回合适配器,请使用 openclaw/plugin-sdk/channel-inbound 中的 createAcceptedChannelDeliveryResult(...)。它将原生 results 与逻辑 deliveryResults 组合在一起,并包含部分投递错误中已被接受的子集。逻辑结果的回执优先于其旧版消息 ID。该结果携带回执、messageIds(包括空数组)以及 visibleReplySent: true;路由字段保留在回执中。可选 content 会原样传递,kind 和 replyToId 遵循回执构建器的规则。
对于将已接受文本以换行符拼接的批次,请使用 openclaw/plugin-sdk/channel-outbound 中的 createChannelDeliveryAccumulator({ kind?, replyToId? })。仅在每次物理发送成功后调用 add(source, acceptedText?)。size 对已接受的发送计数,result() 返回它们合并后的回执和非空文本;对于空批次,则返回 no_visible_result 抑制结果。失败时,抛出 partialError(error) 以保留之前的发送以及嵌套的部分投递错误中已被接受的子集;在任何接受之前的失败则原样传递。传输接受副作用、其他内容拼接规则,以及无身份结果是否需要回执,这些都由适配器自行处理。
渠道动作和适配器能力来自所选插件注册。省略的 actions、message 或 outbound 接口不会被另一个具有相同渠道 ID 的插件填充。在注册表作用域内创建的已准备投递处理器,在调用者离开该作用域后调用时仍保留该句柄。
精确声明实时(live)和定稿(finalizer)能力——核心(core)使用这些来决定渠道能做什么,声明行为与实际行为之间的漂移会导致契约测试失败:
| 接口 | 值 |
|---|---|
message.live.capabilities |
draftPreview、previewFinalization、progressUpdates、nativeStreaming、quietFinalization |
message.live.finalizer.capabilities |
finalEdit、normalFallback、discardPending、previewReceipt、retainOnAmbiguousFailure |
支持预览的渠道应使用 openclaw/plugin-sdk/channel-outbound 中的 createLivePreviewLifecycle(...) 来处理最终接受、提升和清理。请提供真实的传输操作和明确的投递结果,而不是保留渠道本地的 final/cleanup 标志。原生流式传输和持久卡片保留其传输特定的定稿方式;它们不需要假装成可删除的草稿。参见 Progress and preview delivery ownership。
让已声明能力由 verifyChannelMessageLiveCapabilityAdapterProofs(...) 和 verifyChannelMessageLiveFinalizerProofs(...) 测试提供支持,从而确保原生进度、编辑、回退/保留、清理和回执行为不会静默漂移。
进度可见性接受¶
进度回调报告的是操作员实际能看到的内容,而不仅仅是插件已排队的内容。在接受可见进度后返回 true;在投递待处理或没有发生可见更新时返回 false。现有返回 void 的同步和异步回调保持向后兼容,并被视为可见;新的接受感知实现应使用显式布尔值。
静默进度呈现¶
原生进度渲染器在工具行被禁用时,必须保留审批请求,以及作者编写的进度文本和计划行。中间工具失败和非零命令退出遵循工具行可见性设置;它们不得绕过静默模式。最终任务错误仍使用正常错误投递。共享进度组合器会将该策略应用于其快照。
resolveChannelStreamingPreviewToolProgress(entry, defaultValue?, mode?) 在第二个参数省略或为 undefined 时保持其内置默认值 true。内置渠道将 mode !== "progress" 作为第二个参数,并将其解析出的流式模式作为第三个参数传入,因此未配置的 progress 草稿会隐藏普通工具行,而 partial 和 block 预览会显示它们。
组合器和格式化器的 presentation: "summary" 选项以及检查清单格式化器的 plain: true 选项已弃用,但在下一个破坏性 SDK 版本发布之前仍保留其显式输出。新调用方应省略它们,并使用 streaming.progress.toolProgress 配合标准进度标记来控制工具行。
在使用已准备的 agent 条目时,请以 preparedItems: true 创建组合器。然后 pushItemEvent 负责可见工具进度;原始工具、命令输出和补丁回调保留诊断性簿记,而不会添加重复行。对于使用原始回调的现有插件,请省略该选项。它们的参数、详情模式、自定义行构建器以及终端命令/补丁渲染仍然受支持。这是一项适配器能力,而非用户配置设置。
Telegram 和 Discord 还会传递 showWorkStatus: true。在隐藏详细工具日志的情况下,合成器会保留一条当前操作状态,以及来自已准备条目的有界子代理状态行。该投影会排除参数、命令标题、输出和私有子级文本;它会保留真实的条目 ID,用于更新和撤回。其他适配器会保持其现有展示方式,除非它们选择启用此能力。
对于默认开启的草稿,请在回复选项中传递 progressRequiresReply: true。
Dispatch 会使用其已承认的回复预期,以保持可选的静默轮次私密;排队轮次使用其自身的预期,而不是前一轮次的预期。
这不会抑制必需的持久工具结果,例如审批或媒体。
静默确认与合并进度¶
createStatusReactionController({ presentation: "acknowledgement", ... })
会在工作过程和成功期间保留初始反应,跳过非活动警告,
并保留现有的错误/清理生命周期。默认 activity 策略
继续暴露详细生命周期反应。
对于编辑或原生进度,createDraftStreamLoop 和可最终化草稿
控件接受 coalesceInFlight: true,以便将发送期间到达的后台更新
保留到下一个节流窗口。显式 flush() 仍然会绕过延迟,
用于注意和最终化。在关闭或轮换流之前,取消待处理更新并等待
进行中的工作。
使用 createFinalizableDraftLifecycle 来管理物理删除托管,而不是
维护插件本地的重试队列。retire(id) 会认领一个已分离的预览;
retire(id, { defer: true }) 会记录它而不立即删除它。
cleanupPending() 会重试已退役的 ID,而不会删除当前预览。
当传输清理策略必须更改时,向 cleanupPending 传递一个同步 prepareCleanup
回调;它会按顺序与清除操作一起运行,先于删除。
被拒绝的删除仍保持所有权,用于稍后的清理尝试。
对于同步轮次轮换,reset() 会推进 generation,重新打开投递,
并重置当前消息和待处理更新。已发布消息仍由适配器负责。reset("discard") 还会在早期代次的创建项结算时将其退役。在序列化发送循环内调用 createMessage(send, publish);其同步 publish 回调只会安装当前代次的回执。在编辑前捕获 generation,并在发布其结果前重新检查它。retireCurrent(stopForClear) 类似地为等待中的清理设置栅栏。已在轮换前结算其发送的适配器可以使用 resetMessage() 来重置身份和待处理/节流状态,而无需重新打开投递或推进代次。
当轮换必须保留现有节流窗口和计划刷新时,将 "keep" 作为节流参数传递给 resetMessage("keep") 或 reset("discard", "keep")。默认会重置两者。在清理期间决定过期预览处置的传输可以将 { defer: true } 作为第三个参数传递给 createMessage;过期的已丢弃回执随后进入删除托管,而不会立即尝试删除。
评论投递所有权¶
当频道支持持久评论消息时,设置 commentaryPayloadsEnabled: true。
通常在一个不断演进的进度草稿中渲染评论的频道还可以提供
shouldDeliverCommentaryPayloads。Core 会为当前轮次冻结详细可见性,通过 onVerboseProgressVisibility 注册该 getter,在分发前评估一次投递回调,并快照该结果以用于整个轮次。会话更改将在下一轮次生效。
除非 commentaryPayloadsEnabled 也为 true,否则该回调处于非活动状态;没有该静态选择启用,Core 既不会评估回调,也不会冻结已注册的可见性 getter。
当草稿拥有正常进度时返回 false,当详细进度使该草稿让位于持久评论时返回 true。保持回调同步,并且只读取频道拥有的、已准备好的状态。省略它会为使用静态选择启用的现有插件保留持久投递。该回调不控制推理、部分回复、工具进度或最终答案。
延迟平台确认的入站接收器应声明
message.receive.defaultAckPolicy 和 supportedAckPolicies,而不是将确认时机隐藏在监视器本地状态中。使用
verifyChannelMessageReceiveAckPolicyAdapterProofs(...) 覆盖每个已声明的策略。
TTS 语音投递¶
在 capabilities.tts.voice 下声明原生语音消息行为。当 TTS 提供商应生成原生语音消息格式时,设置
synthesisTarget: "voice-note"。仅当出站语音操作接受可见的最终文本并执行其传输的字幕和溢出规则时,才设置 captionedFinalText: true。然后 Core 会为该操作保留最终模式的流式文本,并在语音负载被证明未发送时回退到文本。
旧版 dispatchInboundReplyWithBase 辅助函数仍可从已弃用的 openclaw/plugin-sdk/inbound-reply-dispatch 兼容垫片中获取。
不要在新频道代码中使用它;请改为从 openclaw/plugin-sdk/channel-outbound 上的 message 适配器、回执以及接收/发送生命周期辅助函数开始。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw