Markdown 格式化（Markdown formatting）

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

目标

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

管道（Pipeline）

  1. 解析 Markdown -> IR
    • IR 是纯文本加上样式范围（bold/italic/strike/code/spoiler）和链接范围。
    • 偏移量是 UTF-16 代码单元，以便 Signal 样式范围与其 API 对齐。
    • 表格仅在频道选择进行表格转换时解析。
  2. 分块 IR（格式优先）
    • 分块发生在渲染之前的 IR 文本上。
    • 内联格式化不会跨块拆分；范围按每个块切片。
  3. 按频道渲染
    • Slack： mrkdwn 令牌（bold/italic/strike/code），链接为 <url|label>。
    • Telegram： HTML 标签（<b>、<i>、<s>、<code>、<pre><code>、<a href>）。
    • 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 出站适配器（outbound adapters）从 IR 渲染。
  • 其他频道（WhatsApp、iMessage、MS Teams、Discord）仍使用纯文本或它们自己的格式化规则，在启用时在分块之前应用 Markdown 表格转换。

表格处理（Table handling）

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

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

配置键：

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

分块规则（Chunking rules）

  • 分块限制来自频道适配器/配置，并应用于 IR 文本。
  • 代码围栏（Code fences）保留为带有尾随换行符的单个块，以便频道正确渲染它们。
  • 列表前缀和块引用前缀是 IR 文本的一部分，因此分块不会在前缀中间拆分。
  • 内联样式（bold/italic/strike/inline-code/spoiler）永远不会跨块拆分；渲染器在每个块内重新打开样式。

如果您需要更多关于跨频道分块行为的信息，请参见 流式传输 + 分块（Streaming + chunking）。

链接策略（Link policy）

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

剧透（Spoilers）

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

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

  1. 解析一次： 使用共享的 markdownToIR(...) 辅助函数，配合适当于频道的选项（autolink、heading style、blockquote prefix）。
  2. 渲染： 使用 renderMarkdownWithMarkers(...) 和样式标记映射（或 Signal 样式范围）实现渲染器。
  3. 分块： 在渲染之前调用 chunkMarkdownIR(...)；渲染每个块。
  4. 连接适配器： 更新频道出站适配器以使用新的分块器和渲染器。
  5. 测试： 添加或更新格式测试以及出站传递测试（如果频道使用分块）。

常见陷阱（Common gotchas）

  • Slack 尖括号令牌（<@U123>、<#C123>、<https://...>）必须保留；安全地转义原始 HTML。
  • Telegram HTML 需要转义标签外的文本以避免标记破损。
  • Signal 样式范围依赖于 UTF-16 偏移量；不要使用代码点偏移量。
  • 为围栏代码块保留尾随换行符，以便关闭标记位于它们自己的行上。
← 返回文档首页