状态和媒体
发布频道运行时状态、解析媒体限制,并整形原生负载。属于构建频道插件指南的一部分。
运行时生命周期状态¶
对于由频道编写的运行时状态,ChannelAccountSnapshot.lifecycle 是 healthState 的后续替代。现有插件在迁移期间可以继续发布 healthState,且核心派生的策略写入仍受支持。没有移除日期;移除将等待外部频道插件完成采用。
输入状态指示器¶
如果你的频道支持在入站回复之外的输入状态指示器,请在频道插件上暴露 heartbeat.sendTyping(...)。核心会在心跳模型运行开始前,使用已解析的心跳投递目标调用它,并采用共享的输入状态保活/清理生命周期。当平台需要显式停止信号时,请添加 heartbeat.clearTyping(...)。
媒体源参数¶
使用来自 openclaw/plugin-sdk/account-helpers 的 resolveChannelMediaMaxBytes(...) 解析账户媒体限制。将已合并账户的 mediaMaxMb 传递给 resolveChannelLimitMb;该辅助函数仅在账户/频道限制缺失时应用智能体默认值。其可选的字节结果必须传递给实际的媒体加载器,并受任何传输上限的约束。当未配置限制时,保留加载器现有的默认值。
聚焦的账户辅助导入让设置和账户解析无需媒体分析运行时。旧的 media-runtime 导出仍可供现有的外部插件使用,但新的调用方及随包附带的调用方应使用聚焦导入。
如果你的频道添加了携带媒体源的消息工具参数,请通过 plugin.actions.describeMessageTool(...).mediaSourceParams 暴露这些参数名。核心使用该显式列表进行沙箱路径规范化和出站媒体访问策略,因此插件无需为提供方特定的头像、附件或封面图片参数设置共享核心特例。
建议使用以 action 为键的映射,例如 { "set-profile": ["avatarUrl", "avatarPath"] },这样不相关的操作不会继承另一操作的媒体参数。对于有意在每个暴露操作之间共享的参数,扁平数组仍然有效。
必须为平台侧媒体获取暴露临时公共 URL 的频道,可以使用 openclaw/plugin-sdk/outbound-media 中的 createHostedOutboundMediaStore(...),并配合插件状态存储。将平台路由解析和令牌强制逻辑保留在频道插件中;共享辅助函数仅负责媒体加载、过期元数据、分块行和清理。
prepareUrl({ mediaAccess }) 将主机授权的本地媒体访问转发给共享的出站加载器。托管媒体容量默认为 overflowPolicy: "evict-oldest" 以保持兼容性。当已签发 URL 必须在过期前一直有效时,请使用 "reject-new",并将两个后备键控存储都配置为 "reject-new",这样独立的写入方就无法逐出活动行。当传输层必须拒绝某类负载时,使用 validateBeforePersist 检查受保护加载器的确切字节和元数据。将其缓冲区视为只读,并在创建能力或写入任何存储之前抛出异常以拒绝。在调用 read(...) 之前,使用 readMetadata(...) 对 Bearer 请求进行身份验证,这样无效令牌和 HEAD 请求就不会加载已存储的媒体分块。
入站附件使用有序事实,而非并行的 Media* 字段。使用 openclaw/plugin-sdk/channel-inbound 中的 toInboundMediaFacts(...) 规范化频道记录,并在构建入站上下文时将它们作为 media 传入。当插件必须授权本地媒体读取时,请从聚焦的 openclaw/plugin-sdk/media-local-roots 子路径导入 getAgentScopedMediaLocalRoots(...) 或 getAgentScopedMediaLocalRootsForSources(...)。智能体作用域的根目录不会授予共享沙箱父目录。要发送在活动沙箱中生成的文件,请将其权威会话工作目录作为第三个参数传递给 getAgentScopedMediaLocalRoots(...),或作为 sessionWorkspaceDir 传递给 sources 辅助函数。该值必须来自可信的主机会话上下文;绝不要从请求的媒体路径推导。没有该上下文时,仅工作目录策略会刻意拒绝沙箱路径。旧的 agent-media-payload 构建器/根门面已弃用,仅作兼容保留。
原生负载整形¶
仅当负载发送方负责多附件分组时,才设置 outbound.sendPayloadGroupsMedia: true。在这种情况下,如果该发送方的持久化负载和对账能力允许,核心会为其保留多媒体列表。没有这个显式选择加入,普通附件将保持逐项投递。
分组发送方必须在每次实际发送之前以及等待的准备工作之后检查出站上下文的 signal,并在每个发送边界保留平台分发回调和当前所有者回调。仅声明通用负载支持并不会让插件承担这一责任。
如果你的频道需要为 message(action="send") 提供提供方特定的整形,请优先使用 actions.prepareSendPayload(...)。将原生卡片、块、嵌入或其他持久数据放在 payload.channelData.<channel> 下,并让核心通过出站/消息适配器发送。仅在负载无法序列化和重试时,才将 actions.handleAction(...) 用于发送,作为兼容性回退。
对于发送操作,在调用 sendDurableMessageBatch(...) 时,保留可信上下文的 onPlatformSendDispatch、assertDirectAdapterHandoff 和 skipQueue。这些字段来自主机,而非操作参数。在每次实际发送之前等待分发回调,然后在准备工作或限流等待之后、平台 I/O 之前立即调用同步断言。已关闭的所有者必须停止所有剩余发送。
skipQueue: true 让与实时运行绑定的发送不进入可重放恢复流程。单独的 deliveryRetryOwner 字段控制由谁处理失败投递;它不会扩展运行的权限。操作员的发送保留正常的持久化队列。不要序列化任一权限回调,也不要在面向模型的 action schema 中暴露这些字段。
进度卡片交接¶
等待回复可以在其回复分发上下文中携带可选的宿主拥有的 info.adoptProgressDraft(draft) 能力。可编辑进度适配器使用它,在子项或分离媒体生成运行、回合等待运行时,保持已可见的卡片处于活动状态,而不是发送替换卡片或把最终答案投递计入其中。
排空并刷新现有草稿,重新检查 assertPlatformSendAuthorized,并确认平台已接受该卡片。暂存内容或发送结果不明确均不算数。然后传入一个具有两个同步方法的草稿:push(item) 在同一张卡片上渲染一个已准备好的进度项,retire() 删除它。只有 true 结果才会转移控制权:分离旧流,但不删除其消息。如果该能力不存在或被拒绝,保持普通回复投递,包括与等待文本并排的任何媒体或控件。
适配器继续负责渲染、限流和删除。retire() 立即撤销该卡片:拒绝任何在网络 I/O 之前仍在等待平台准入的编辑。切勿序列化该能力、在操作参数中暴露它,或复用旧回合的回调。
基于回执的 info.adoptProgressContinuation(receipt) 自 2026.9.8 起保持源码兼容,但已弃用。宿主不再提供它,因此检查它的适配器保持普通等待回复投递。
投递后的固定¶
outbound.pinDeliveredMessage 接收与消息发送相同的可选 assertDirectAdapterHandoff 回调。该字段将现有投递所有者的权限带入后续的固定操作;接受消息并不会授权在该所有者关闭之后的后续固定请求。在异步准备过程中保留该回调,并在每次提供商请求(包括重试)之前立即检查它。Telegram 会将其转发到现有的 assertPlatformSendAuthorized 传输选项,该选项在账户限流释放每个请求之后进行检查。
使用同步断言进行此检查。onPlatformSendDispatch 还会记录分发计时,并且不能替代权限断言。一旦固定请求已提交,保留其已接受的结果,而不是在响应之后再次检查权限。可选固定失败仍保持投递成功;必需固定失败会在 sendDurableMessageBatch 的 partial_failed 结果中保留已发送的消息和回执。
新的固定上下文字段是可选的,因此现有调用方和插件签名保持源码兼容。没有该字段的调用方保留其现有行为;请勿在配置、操作模式或存储的负载中暴露它。有关固定选项,请参阅消息展示与投递。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw