跳转至

Markdown 格式化

OpenClaw 在渲染特定频道的输出之前,会将出站 Markdown 转换为共享的中间表示(IR)。IR 保留纯文本以及样式/链接跨度,因此一次解析步骤即可服务所有频道,且分块永远不会在格式化跨度的中途断开。

流水线

  1. 将 Markdown 解析为 IR (markdownToIR) - 纯文本加上样式跨度(粗体、斜体、删除线、代码、代码块、剧透、引用块、1-6 级标题)和链接跨度。偏移量以 UTF-16 代码单元为单位,因此 Signal 样式范围可直接与其 API 对齐。仅当频道选择了表格模式时,才会解析表格。
  2. 将 IR 分块 (chunkMarkdownIR / renderMarkdownIRChunksWithinLimit) - 样式和链接跨度随文本一起切片。基于渲染大小的分块器在频道转义和链接重写后测量每个候选块,并返回被接受的源切片及其渲染后的负载。
  3. 按频道渲染 (renderMarkdownWithMarkers) - 样式标记映射将跨度转换为频道的原生标记。

原始的内联 HTML 词法单元在解析期间保留其原始字节。属性值或可识别内联注释中的 Markdown 标记和实体不会被解析为 Markdown 内容。未序列化的作者标签范围允许支持 HTML 的渲染器解释这些标签;其他渲染器会按字面保留或转义它们。HTML 块解析保持禁用状态,因此容器内的 Markdown 仍然有效,并且其主体中的裸 URL 会保留正常的链接化行为。

共享 IR 渲染器示例:

频道 渲染器 备注
Matrix HTML 标签,包括原生表格 自动回复、直接发送和媒体说明使用相同的格式化器
Signal 纯文本 + text-style 范围 当链接文本与 URL 不同时,链接渲染为 label (url)
Slack mrkdwn 标记(*bold*、_italic_、`code`, 代码围栏) 链接变为 <url\|label>;解析期间禁用自动链接以避免双重链接
Telegram HTML 标签(<b>、<i>、<s>、<code>、<pre><code>、<a href>、<tg-spoiler>) 当 richMessages 开启时,还支持富消息表格和标题(<h1>-<h6>)
WhatsApp WhatsApp 样式标记 使用共享 IR;样式化分块在渲染后进行测量

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" }]
}

表格处理

markdown.tables 控制频道如何转换 Markdown 表格,可按频道设置,并可选择按账户设置:

模式 行为
code 在代码块内渲染为对齐的 ASCII 表格(默认回退)
bullets 将每一行转换为 label: value 项目符号项
block 在传输方式支持原生表格的情况下保留原生表格;否则回退到 code
off 禁用表格解析;原始表格文本原样通过

在所有启用的表格模式下,表格单元格中的内联代码会保留其解析后的内容,包括前导和尾随空格。

各频道的插件默认值:Matrix 默认为 block(原生表格);Mattermost 默认为 off;Signal 和 WhatsApp 默认为 bullets;Telegram 默认为 block(除非账户启用了 richMessages,否则会解析为 code)。没有显式插件默认值的频道都会回退到 code。

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

分块规则

  • 分块限制来自频道适配器/配置。chunkMarkdownIR 限制 IR 文本;renderMarkdownIRChunksWithinLimit 以传输的大小单位测量最终负载,包括转义处理后的内容和重写后的链接。
  • 围栏代码块保持为一个整体块,并带有尾随换行符,以便频道正确渲染闭合围栏。
  • 列表和引用块前缀是 IR 文本的一部分,因此分块绝不会在前缀中途断开。
  • 列表项中的段落、标题和代码块在 IR 中保持分离,包括嵌套在引用块内列表项中的段落。
  • 内联样式绝不会跨分块拆分;渲染器会在下一个分块开始时重新打开未闭合的样式。

请参阅 流式传输与分块 了解跨频道的分块边界和投递行为。

  • Slack: [label](url) -> <url|label>;裸 URL 保持为裸 URL(不自动链接)。
  • Telegram: [label](url) -> <a href="url">label</a>(HTML 解析模式)。
  • Signal: [label](url) -> label (url),除非链接文本已经与 URL 匹配。

剧透

剧透标记(||spoiler||)会针对 Signal(映射到 SPOILER 样式范围)和 Telegram(映射到 <tg-spoiler>)进行解析。其他频道将 ||...|| 视为纯文本。

可折叠详情

Control UI 和启用了 richMessages: true 的 Telegram 账户会将 <details><summary>Label</summary> 披露块渲染为原生可折叠区域。OpenClaw 仅会在当前回复界面支持该选项时,才将其告知模型。其他频道(包括未启用富消息的 Telegram 账户)会将每个披露块扁平化为 **Summary** 后接可见正文,从而不会隐藏或丢失任何内容。

添加或更新频道格式化器

  1. 仅解析一次,使用 markdownToIR(...),并传入适合频道的选项(autolink、headingStyle、blockquotePrefix、tableMode)。
  2. 渲染,使用 renderMarkdownWithMarkers(...) 和样式标记映射(或针对 Signal 等传输方式的自定义样式范围逻辑)。
  3. 分块,使用 chunkMarkdownIR(...) 或 renderMarkdownIRChunksWithinLimit(...)。后者返回已测量的 rendered 负载;请直接使用它,而不是再次渲染源内容。
  4. 接入适配器,使其在出站发送路径中调用新的分块器和渲染器。
  5. 测试,使用格式测试;如果频道会分块,则还需进行出站投递测试。

对于互不重叠的文本替换和插入,openclaw/plugin-sdk/text-chunking 导出 applyMarkdownTextEdits(text, edits)。编辑使用 UTF-16 源坐标;结果包含编辑后的 text 以及用于替换区域外部边界的 mapOffset。每个编辑都会移动其结束位置及之后的偏移量。同一位置的插入保留调用方顺序,并先于在该位置开始的替换。渲染器决定哪些样式包含替换文本。

常见陷阱

  • Slack 尖括号标记(<@U123>、<#C123>、<https://...>)必须在转义后保留;原始 HTML 仍需要安全转义。
  • Telegram HTML 要求转义标签外的文本,以避免标记损坏。
  • Signal 样式范围使用 UTF-16 偏移量,而不是码点偏移量。
  • 保留围栏代码块末尾的换行符,使结束标记位于单独一行。
  • 代码片段解析会保留全空格内容。仅当两端都存在一个相邻空格且内容不是全空格时,才会从两端各移除一个空格。
  • 助手回复清理会移除 Markdown 代码之外的有效 <final> 标记,包括嵌套或孤立标记,同时保留其包围的答案文本。将字面量 <final>payload</final> 示例放在行内代码或围栏代码块中,以保留其标签。

流式传输与分块

出站流式传输行为、分块边界以及特定频道的投递。

系统提示

模型在对话前看到的内容,包括注入的工作区文件。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw