Markdown 格式化

OpenClaw 在格式化出站 Markdown 时,会先将其转换为共享的中间表示(IR),然后再渲染成各个 Channel 专属的输出格式。IR 保持源文本不变,同时携带样式和链接的位置信息,这样分块和渲染就能在所有 Channel 上保持一致。

设计目标

一致性:解析一次,多处渲染。
安全分块:在渲染前分割文本,确保行内格式不会在分块边界处断开。
适配 Channel:将同一个 IR 映射到 Slack mrkdwn、Telegram HTML 和 Signal 样式范围,无需重新解析 Markdown。

处理流程

解析 Markdown -> IR
- IR 是纯文本加上样式片段(粗体/斜体/删除线/代码/隐藏)和链接片段。
- 偏移量使用 UTF-16 代码单元,这样 Signal 的样式范围能对齐其 API。
- 只有当 Channel 选择启用表格转换时才会解析表格。
分块 IR(格式优先)
- 分块发生在 IR 文本渲染之前。
- 行内格式不会跨分块分割;每个分块会切分对应的样式片段。
按 Channel 渲染
- Slack:mrkdwn 标记(粗体/斜体/删除线/代码),链接格式为 <url|label>。
- Telegram:HTML 标签(<b>、<i>、<s>、<code>、<pre><code>、<a href>)。
- Signal:纯文本 + text-style 范围;当标签与 URL 不同时,链接变成 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 渲染。
其他 Channel(WhatsApp、iMessage、MS Teams、Discord)仍然使用纯文本或它们自己的格式化规则,启用时会在分块前应用 Markdown 表格转换。

表格处理

Markdown 表格在各个聊天客户端的支持并不一致。使用 markdown.tables 可以按 Channel(和账号)控制转换方式。

code:将表格渲染为代码块(大多数 Channel 的默认值)。
bullets:将每行转换为项目符号列表(Signal + WhatsApp 的默认值)。
off:禁用表格解析和转换;原始表格文本直接传递。

配置示例:

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

分块规则

分块限制来自 Channel 适配器或配置,应用于 IR 文本。
代码围栏作为单个块保留,并带有尾随换行符,这样 Channel 能正确渲染。
列表前缀和引用块前缀是 IR 文本的一部分,所以分块不会在前缀中间分割。
行内样式(粗体/斜体/删除线/行内代码/隐藏)永远不会跨分块分割;渲染器会在每个分块内重新打开样式。

如果你想深入了解跨 Channel 的分块行为,可以看看流式传输 + 分块。

链接策略

Slack:[label](url) -> <url|label>;裸 URL 保持原样。解析时禁用自动链接以避免重复链接。
Telegram:[label](url) -> <a href="url">label</a>(HTML 解析模式)。
Signal:[label](url) -> label (url),除非标签与 URL 匹配。

隐藏文本

隐藏标记(||spoiler||)只为 Signal 解析,会映射到 SPOILER 样式范围。其他 Channel 将其视为纯文本。

如何添加或更新 Channel 格式化器

解析一次:使用共享的 markdownToIR(...) 辅助函数,配合 Channel 适当的选项(自动链接、标题样式、引用块前缀)。
渲染:用 renderMarkdownWithMarkers(...) 和样式标记映射(或 Signal 样式范围)实现渲染器。
分块:在渲染前调用 chunkMarkdownIR(...);渲染每个分块。
连接适配器:更新 Channel 出站适配器以使用新的分块器和渲染器。
测试:添加或更新格式测试,如果 Channel 使用分块,还要添加出站传递测试。

常见陷阱

Slack 的尖括号标记(<@U123>、<#C123>、<https://...>)必须保留;安全转义原始 HTML。
Telegram HTML 需要转义标签外的文本以避免标记损坏。
Signal 样式范围依赖 UTF-16 偏移量;不要使用码点偏移量。
为代码围栏保留尾随换行符,这样闭合标记能单独占一行。