5.20 Markdown格式

核心概念核心概念

OpenClaw 通过将 Markdown 转换为共享的中间表示（IR）来格式化出站消息，然后再渲染特定频道的输出。IR 保持源文本完整，同时携带样式/链接跨度，以便分块和渲染可以在各频道保持一致。

目标

  • 一致性：一次解析步骤，多个渲染器
  • 安全分块：在渲染前拆分文本，以便内联格式永远不会跨块中断
  • 频道适配：将相同的 IR 映射到 Slack mrkdwn、Telegram HTML 和 Signal 样式范围，无需重新解析 Markdown

处理流程

  1. 解析 Markdown → IR
    • IR 是纯文本加样式跨度（粗体/斜体/删除线/代码/剧透）和链接跨度
    • 偏移量是 UTF-16 代码单元，以便 Signal 样式范围与其 API 对齐
    • 仅当频道选择表格转换时才解析表格
  2. 分块 IR（格式优先）
    • 分块在渲染前对 IR 文本进行
    • 内联格式不会跨块拆分；跨度按块切片
  3. 按频道渲染
    • Slack：mrkdwn 标记（粗体/斜体/删除线/代码），链接为 <url|label>
    • Telegram：HTML 标签（<b>、<i>、<s>、<code>、<spoiler>）
    • Signal：纯文本 + text-style 范围；当标签不同时，链接变为 label (url)

IR 示例

输入 Markdown：

Hello **world** — see [docs](https://docs.openclaw.ai).

IR（示意）：

{
  "text": "Hello world — see docs.",
  "styles": [{ "start": 6, "end": 11, "style": "bold" }],
  "links": [{ "start": 19, "end": 23, "href": "https://docs.openclaw.ai" }]
}

使用场景

  • Slack、Telegram 和 Signal 出站适配器从 IR 渲染
  • 其他频道（WhatsApp、iMessage、MS Teams、Discord）仍使用纯文本或自己的格式规则，启用时在分块前应用 Markdown 表格转换

表格处理

Markdown 表格在聊天客户端上的支持不一致。使用 markdown.tables 按频道（和账户）控制转换。

  • code：将表格渲染为代码块（大多数频道的默认值）
  • bullets：将每行转换为项目符号点（Signal + WhatsApp 的默认值）
  • off：禁用表格解析和转换；原始表格文本通过

配置示例：

channels:
  discord:
    markdown:
      tables: code
accounts:
  work:
    markdown:
      tables: off

分块规则

  • 块限制来自频道适配器/配置，应用于 IR 文本
  • 代码围栏作为单个块保留，带有尾随换行符，以便频道正确渲染它们
  • 列表前缀和块引用前缀是 IR 文本的一部分，因此分块不会在前缀中间拆分
  • 内联样式（粗体/斜体/删除线/内联代码/剧透）永远不会跨块拆分；渲染器在每个块内重新打开样式

链接策略

  • Slack：[label](url) → <url|label>；裸 URL 保持裸露。在解析期间禁用自动链接以避免双重链接
  • Telegram：[label](url) → <a href="url">label</a>（HTML 解析模式）
  • Signal：[label](url) → label (url)，除非标签与 URL 匹配

剧透标记

剧透标记（||spoiler||）仅为 Signal 解析，它们映射到 SPOILER 样式范围。其他频道将它们视为纯文本。

如何添加或更新频道格式化器

  1. 解析一次：使用共享的 markdownToIR(...) 助手，带有频道适当的选项（自动链接、标题样式、块引用前缀）
  2. 渲染：使用 renderMarkdownWithMarkers(...) 和样式标记映射（或 Signal 样式范围）实现渲染器
  3. 分块：在渲染前调用 chunkMarkdownIR(...)；渲染每个块
  4. 连接适配器：更新频道出站适配器以使用新的分块器和渲染器
  5. 测试：如果频道使用分块，添加或更新格式测试和出站传递测试

常见陷阱

  • 必须保留 Slack 尖括号标记（<@U123>、<#C123>、<url|label>）；安全地转义原始 HTML
  • Telegram HTML 需要转义标签外的文本以避免损坏标记
  • Signal 样式范围取决于 UTF-16 偏移量；不要使用代码点偏移量
  • 为围栏代码块保留尾随换行符，以便关闭标记位于自己的行上
提示
OpenClaw 的 Markdown 处理确保在不同消息平台上保持一致的格式化体验。中间表示（IR）是这一致性的关键。