跳到主要内容

Markdown 格式化

Clawdbot 通过在渲染特定渠道的输出之前，将传出的 Markdown 转换为共享的中间表示（IR）来对其进行格式化。IR 保持源文本完整，同时携带样式/链接跨度（spans），以便分块和渲染在不同渠道之间保持一致。

目标​

  • 一致性：一次解析，多个渲染器。
  • 安全分块：在渲染之前拆分文本，这样行内格式永远不会跨块断开。
  • 渠道适配：在不重新解析 Markdown 的情况下，将相同的 IR 映射到 Slack mrkdwn、Telegram HTML 和 Signal 样式范围。

流水线​

  1. 解析 Markdown -> IR
    • IR 是纯文本加上样式跨度（粗体/斜体/删除线/代码/剧透）和链接跨度。
    • 偏移量是 UTF-16 代码单元，因此 Signal 样式范围与其 API 对齐。
    • 仅当渠道选择加入表格转换时，才会解析表格。
  2. 分块 IR（格式优先）
    • 分块在渲染之前的 IR 文本上进行。
    • 行内格式不会跨块拆分；跨度按块进行切片。
  3. 按渠道渲染
    • Slack：mrkdwn 标记（粗体/斜体/删除线/代码），链接为 <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.clawd.bot).

IR（示意图）：

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

使用位置​

  • 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 文本。
  • 代码围栏（code fences）保留为带有尾随换行符的单个块，以便渠道正确渲染它们。
  • 列表前缀和引用块前缀是 IR 文本的一部分，因此分块不会在中途拆分前缀。
  • 行内样式（粗体/斜体/删除线/行内代码/剧透）永远不会跨块拆分；渲染器在每个块内重新开启样式。

如果您需要更多关于跨渠道分块行为的信息，请参阅 串流 + 分块。

链接策略​

  • 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(...) 助手，并带有适合渠道的选项（自动链接、标题样式、引用块前缀）。
  2. 渲染：使用 renderMarkdownWithMarkers(...) 和样式标记映射（或 Signal 样式范围）实现渲染器。
  3. 分块：在渲染之前调用 chunkMarkdownIR(...)；渲染每个分块。
  4. 接入适配器：更新渠道传出适配器以使用新的分块器和渲染器。
  5. 测试：如果渠道使用分块，添加或更新格式测试和传出交付测试。

常见陷阱​

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