Markdown 格式化
OpenClaw 在渲染特定频道的输出之前,会将出站 Markdown 转换为共享的中间表示(IR)。IR 保留纯文本以及样式/链接跨度,因此一次解析步骤即可服务所有频道,且分块永远不会在格式化跨度的中途断开。
流水线¶
- 将 Markdown 解析为 IR (
markdownToIR) - 纯文本加上样式跨度(粗体、斜体、删除线、代码、代码块、剧透、引用块、1-6 级标题)和链接跨度。偏移量以 UTF-16 代码单元为单位,因此 Signal 样式范围可直接与其 API 对齐。仅当频道选择了表格模式时,才会解析表格。 - 将 IR 分块 (
chunkMarkdownIR/renderMarkdownIRChunksWithinLimit) - 样式和链接跨度随文本一起切片。基于渲染大小的分块器在频道转义和链接重写后测量每个候选块,并返回被接受的源切片及其渲染后的负载。 - 按频道渲染 (
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 样式标记 | 使用共享 IR;样式化分块在渲染后进行测量 |
IR 示例¶
输入 Markdown:
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。
分块规则¶
- 分块限制来自频道适配器/配置。
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** 后接可见正文,从而不会隐藏或丢失任何内容。
添加或更新频道格式化器¶
- 仅解析一次,使用
markdownToIR(...),并传入适合频道的选项(autolink、headingStyle、blockquotePrefix、tableMode)。 - 渲染,使用
renderMarkdownWithMarkers(...)和样式标记映射(或针对 Signal 等传输方式的自定义样式范围逻辑)。 - 分块,使用
chunkMarkdownIR(...)或renderMarkdownIRChunksWithinLimit(...)。后者返回已测量的rendered负载;请直接使用它,而不是再次渲染源内容。 - 接入适配器,使其在出站发送路径中调用新的分块器和渲染器。
- 测试,使用格式测试;如果频道会分块,则还需进行出站投递测试。
对于互不重叠的文本替换和插入,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