渠道展示重构计划

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

​

状态

• ReplyPayload.presentation 承载语义化消息 UI。
• ReplyPayload.delivery.pin 承载已发送消息的置顶请求。
• 共享消息操作暴露 presentation、delivery 和 pin，而不是 provider 原生的 components、blocks、buttons 或 card。
• Core 会通过插件声明的出站能力来渲染或自动降级 presentation。
• Discord、Slack、Telegram、Mattermost、MS Teams 和飞书渲染器会消费通用契约。
• Discord 渠道控制面代码不再导入基于 Carbon 的 UI 容器。

​

问题

• Core 通过 buildCrossContextComponents 持有一个 Discord 形态的跨上下文渲染器钩子。
• Discord 的 channel.ts 可以通过 DiscordUiContainer 导入原生 Carbon UI，这会把运行时 UI 依赖拉入渠道插件控制面。
• agent 和 CLI 暴露了原生负载逃逸口，例如 Discord 的 components、Slack 的 blocks、Telegram 或 Mattermost 的 buttons，以及 Teams 或飞书的 card。
• ReplyPayload.channelData 同时承载传输提示和原生 UI 容器。
• 通用的 interactive 模型虽然存在，但它比 Discord、Slack、Teams、飞书、LINE、Telegram 和 Mattermost 已经使用的更丰富布局要窄。

​

目标

• Core 根据声明的能力为消息决定最佳语义化展示。
• 扩展声明能力，并将语义化展示渲染为原生传输负载。
• Web 控制 UI 与聊天原生 UI 保持分离。
• 原生渠道负载不通过共享 agent 或 CLI 消息表面暴露。
• 不支持的展示特性会自动降级为最佳文本表示。
• 置顶已发送消息之类的投递行为属于通用投递元数据，而不是展示内容。

​

非目标

• 不为 buildCrossContextComponents 提供向后兼容 shim。
• 不为 components、blocks、buttons 或 card 提供公开的原生逃逸口。
• 不在 core 中导入渠道原生 UI 库。
• 不为打包渠道提供 provider 特定的 SDK 断点。

​

目标模型

type MessagePresentationTone = "neutral" | "info" | "success" | "warning" | "danger";

type MessagePresentation = {
  tone?: MessagePresentationTone;
  title?: string;
  blocks: MessagePresentationBlock[];
};

type MessagePresentationBlock =
  | { type: "text"; text: string }
  | { type: "context"; text: string }
  | { type: "divider" }
  | { type: "buttons"; buttons: MessagePresentationButton[] }
  | { type: "select"; placeholder?: string; options: MessagePresentationOption[] };

type MessagePresentationButton = {
  label: string;
  value?: string;
  url?: string;
  style?: "primary" | "secondary" | "success" | "danger";
};

type MessagePresentationOption = {
  label: string;
  value: string;
};

• interactive 文本块映射到 presentation.blocks[].type = "text"。
• interactive 按钮块映射到 presentation.blocks[].type = "buttons"。
• interactive 选择块映射到 presentation.blocks[].type = "select"。

​

投递元数据

type ReplyPayloadDelivery = {
  pin?:
    | boolean
    | {
        enabled: boolean;
        notify?: boolean;
        required?: boolean;
      };
};

• delivery.pin = true 表示将首个成功投递的消息置顶。
• notify 默认为 false。
• required 默认为 false；不支持的渠道或置顶失败会自动降级为继续投递。
• 现有消息仍保留手动 pin、unpin 和 list-pins 操作。

​

运行时能力契约

type ChannelPresentationCapabilities = {
  supported: boolean;
  buttons?: boolean;
  selects?: boolean;
  context?: boolean;
  divider?: boolean;
  tones?: MessagePresentationTone[];
};

type ChannelDeliveryCapabilities = {
  pinSentMessage?: boolean;
};

type ChannelOutboundAdapter = {
  presentationCapabilities?: ChannelPresentationCapabilities;

  renderPresentation?: (params: {
    payload: ReplyPayload;
    presentation: MessagePresentation;
    ctx: ChannelOutboundSendContext;
  }) => ReplyPayload | null;

  deliveryCapabilities?: ChannelDeliveryCapabilities;

  pinDeliveredMessage?: (params: {
    cfg: OpenClawConfig;
    accountId?: string | null;
    to: string;
    threadId?: string | number | null;
    messageId: string;
    notify: boolean;
  }) => Promise<void>;
};

• 解析目标渠道和运行时适配器。
• 请求展示能力。
• 在渲染前降级不支持的块。
• 调用 renderPresentation。
• 如果不存在渲染器，则将 presentation 转换为文本回退。
• 在成功发送后，当请求了 delivery.pin 且目标渠道支持时，调用 pinDeliveredMessage。

​

渠道映射

• 在仅运行时模块中将 presentation 渲染为 components v2 和 Carbon 容器。
• 将 accent color 辅助函数保留在轻量模块中。
• 从渠道插件控制面代码中移除 DiscordUiContainer 导入。

• 将 presentation 渲染为 Block Kit。
• 移除 agent 和 CLI 的 blocks 输入。

• 将文本、上下文和分隔符渲染为文本。
• 在已配置且目标表面允许的情况下，将操作和选择渲染为内联键盘。
• 当内联按钮被禁用时使用文本回退。
• 将 ACP topic 置顶迁移到 delivery.pin。

• 在已配置时将操作渲染为交互按钮。
• 将其他块渲染为文本回退。

• 将 presentation 渲染为 Adaptive Cards。
• 保留手动 pin/unpin/list-pins 操作。
• 如果 Graph 对目标会话的支持可靠，可选实现 pinDeliveredMessage。

• 将 presentation 渲染为交互卡片。
• 保留手动 pin/unpin/list-pins 操作。
• 如果 API 行为可靠，可选实现用于已发送消息置顶的 pinDeliveredMessage。

• 在可能的情况下将 presentation 渲染为 Flex 或模板消息。
• 对不支持的块回退为文本。
• 从 channelData 中移除 LINE UI 负载。

• 使用保守格式将 presentation 转换为文本。

​

重构步骤

1. 重新应用 Discord 发布修复：将 ui-colors.ts 与基于 Carbon 的 UI 分离，并从 extensions/discord/src/channel.ts 中移除 DiscordUiContainer。
2. 将 presentation 和 delivery 添加到 ReplyPayload、出站负载规范化、投递摘要和钩子负载中。
3. 在狭窄的 SDK/runtime 子路径中添加 MessagePresentation schema 和解析辅助工具。
4. 用语义化展示能力替换消息能力中的 buttons、cards、components 和 blocks。
5. 为展示渲染和投递置顶添加运行时出站适配器钩子。
6. 用 buildCrossContextPresentation 替换跨上下文组件构造。
7. 删除 src/infra/outbound/channel-adapters.ts，并从渠道插件类型中移除 buildCrossContextComponents。
8. 将 maybeApplyCrossContextMarker 改为附加 presentation，而不是原生参数。
9. 更新插件分发发送路径，使其仅消费语义化展示和投递元数据。
10. 移除 agent 和 CLI 的原生负载参数：components、blocks、buttons 和 card。
11. 删除用于创建原生消息工具 schema 的 SDK 辅助工具，改为使用展示 schema 辅助工具。
12. 从 channelData 中移除 UI/原生容器；在每个剩余字段完成审查前，仅保留传输元数据。
13. 迁移 Discord、Slack、Telegram、Mattermost、MS Teams、飞书和 LINE 的渲染器。
14. 为消息 CLI、渠道页面、插件 SDK 和能力 cookbook 更新文档。
15. 对 Discord 和受影响的渠道入口点运行导入扇出分析。

​

测试

• 展示规范化测试。
• 针对不支持块的展示自动降级测试。
• 插件分发和 core 投递路径的跨上下文标记测试。
• Discord、Slack、Telegram、Mattermost、MS Teams、飞书、LINE 和文本回退的渠道渲染矩阵测试。
• 证明原生字段已移除的消息工具 schema 测试。
• 证明原生标志已移除的 CLI 测试。
• 覆盖 Carbon 的 Discord 入口点导入惰性回归测试。
• 覆盖 Telegram 和通用回退的投递置顶测试。

​

未决问题

• delivery.pin 是否应在第一阶段就为 Discord、Slack、MS Teams 和飞书实现，还是先只做 Telegram？
• delivery 未来是否应吸收现有字段，例如 replyToId、replyToCurrent、silent 和 audioAsVoice，还是保持专注于发送后的行为？
• 展示是否应直接支持图片或文件引用，还是媒体暂时应与 UI 布局分离？

​

相关内容

• 频道概览
• 消息展示