Markdown 格式化

OpenClaw 通过将出站 Markdown 转换为共享的中间表示(IR),然后渲染特定于通道的输出来格式化 Markdown。IR 保持源文本完整,同时携带样式/链接范围,使分块和渲染能够在各个通道之间保持一致。

目标

**一致性:**一次解析步骤,多个渲染器。
**安全分块:**在渲染之前拆分文本,使内联格式化永远不会跨块中断。
**通道适配:**将同一个 IR 映射到 Slack mrkdwn、Telegram HTML 和 Signal 样式范围,无需重新解析 Markdown。

管道

解析 Markdown -> IR
- IR 是纯文本加上样式范围(粗体/斜体/删除线/代码/隐藏内容)和链接范围。
- 偏移量是 UTF-16 代码单元,使 Signal 样式范围与其 API 对齐。
- 仅当通道选择启用表格转换时才解析表格。
分块 IR(格式优先)
- 分块在渲染前对 IR 文本进行。
- 内联格式化不会跨块拆分;范围按每个块进行切片。
按通道渲染
- Slack: mrkdwn 标记(粗体/斜体/删除线/代码),链接为 <url|label>。
- Telegram: HTML 标签(<b>, <i>, <s>, <code>, <pre><code>, <a href>)。
- Signal: 纯文本 + text-style 范围;当标签与 URL 不同时,链接变为 label (url)。

IR 示例

输入 Markdown:

markdown

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

IR(示意图):

json

{
  "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:禁用表格解析和转换;原始表格文本直接通过。

配置键:

yaml

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 样式范围。其他通道将它们视为纯文本。

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

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

常见陷阱

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

Markdown 格式化 ​

目标 ​

管道 ​

IR 示例 ​

使用场景 ​

表格处理 ​

分块规则 ​

链接策略 ​

隐藏内容 ​

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

常见陷阱 ​