Markdown 格式化

OpenClaw 將出站的 Markdown 轉換成一套共享的中間表示（IR），再針對各頻道渲染成對應格式。IR 保留原始文字的同時帶有樣式/連結 span，讓分段和渲染在不同頻道之間維持一致。

目標

一致性： 一次解析，多個渲染器。
安全分段： 在渲染前就切分文字，確保行內格式不會在分段邊界被切斷。
適配頻道： 同一份 IR 可以對應到 Slack mrkdwn、Telegram HTML 和 Signal 的樣式範圍，不需要重新解析 Markdown。

管線

解析 Markdown -> IR
- IR 由純文字加上樣式 span（粗體/斜體/刪除線/行內程式碼/劇透）和連結 span 組成。
- 偏移量使用 UTF-16 code unit，以便與 Signal 樣式範圍的 API 對齊。
- 表格只有在頻道選擇啟用表格轉換時才會被解析。
分段 IR（格式優先）
- 分段在渲染前對 IR 文字進行。
- 行內格式不會跨分段切分；span 會按分段裁切。
按頻道渲染
- Slack： mrkdwn token（粗體/斜體/刪除線/行內程式碼），連結用 <url|label>。
- Telegram： HTML 標籤（<b>、<i>、<s>、<code>、<pre><code>、<a href>）。
- Signal： 純文字 + text-style 範圍；當 label 與 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 渲染。
其他頻道（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 文字的一部分，分段不會從前綴中間切斷。
行內樣式（粗體/斜體/刪除線/行內程式碼/劇透）絕不跨分段切分；渲染器會在每個分段內重新開啟樣式。

如果想瞭解更多跨頻道的分段行為，請參閱 Streaming + chunking。

連結處理策略

Slack： [label](/docs/concepts/url) -> <url|label>；裸 URL 保持原樣。解析時停用自動連結以避免重複連結。
Telegram： [label](/docs/concepts/url) -> <a href="url">label</a>（HTML 解析模式）。
Signal： [label](/docs/concepts/url) -> label (url)，除非 label 與 URL 相同。

劇透

劇透標記（||spoiler||）只在 Signal 中被解析，對應到 SPOILER 樣式範圍。其他頻道將其視為純文字。

如何新增或更新頻道格式器

解析一次： 使用共享的 markdownToIR(...) 輔助函式，搭配頻道適用的選項（自動連結、標題樣式、引用前綴）。
渲染： 實作一個渲染器，使用 renderMarkdownWithMarkers(...) 和樣式標記映射（或 Signal 樣式範圍）。
分段： 在渲染前呼叫 chunkMarkdownIR(...)；逐段渲染。
接線適配器： 更新頻道出站適配器，使用新的分段器和渲染器。
測試： 新增或更新格式測試，如果頻道使用分段，還要加出站傳送測試。

常見陷阱

Slack 角括號 token（<@U123>、<#C123>、<https://...>）必須被保留；安全地跳脫原始 HTML。
Telegram HTML 需要在標籤外部跳脫文字，避免破壞標記。
Signal 樣式範圍依賴 UTF-16 偏移量；不要使用 code point 偏移量。
保留程式碼區塊的尾隨換行，讓關閉標記落在自己的行上。

Typing Indicators