富文本渲染测试
概述
富文本渲染测试是一个专为 LLM（大语言模型）流式输出场景设计的富文本渲染引擎测试工具。它让你能够在可视化的环境中测试、调试和对比不同渲染器版本对 Markdown、HTML、数学公式、Mermaid 图表等内容的渲染效果，是开发智能体应用时的"渲染实验室"。
核心功能
- 四引擎对比测试：支持 V1（Markdown-it）、V2（自研 AST 解析器）、Pure Markdown-it、Hybrid V3 四种渲染器，一键切换对比
- 流式输出模拟：模拟 LLM 打字机效果，支持自定义速度、延迟和波动模式，测试流式渲染的实时表现
- 动态样式编辑：所见即所得地调整 Markdown 元素（标题、粗体、引用块等）的颜色、阴影、边框等 CSS 样式
- 复杂内容覆盖：预设 24+ 个测试用例，覆盖代码块、表格、Mermaid 图表、KaTeX 公式、LLM 思考块、HTML 沙箱、VCP 工具调用等场景
- 可视化 AST 调试：实时展示渲染引擎的抽象语法树（AST）结构，支持稳定区/待定区染色，辅助排查渲染问题
一句话总结
如果你需要确认一段 LLM 输出的 Markdown 内容在各种渲染模式下看起来什么样——这就是你要找的工具。
快速上手
首次测试 5 步走
第一步：打开工具
在左侧工具列表中找到 富文本渲染测试，点击进入。页面默认采用"上输入 + 下预览"的双栏布局。
TODO: 截图 - 工具整体界面，标注输入区、预览区、配置面板、预设列表
第二步：选择一个预设内容
点击工具栏的 预设 下拉菜单，选择一个测试用例。建议从 基本测试 (basic) 开始——它包含了最常用的 Markdown 语法元素，适合快速验证基础渲染效果。
TODO: 截图 - 预设下拉菜单展开，展示预设列表
第三步：查看渲染效果
预设内容会自动填入输入区，右侧预览区会立即展示渲染后的效果。你可以看到：
- Markdown 语法被正确解析（标题、粗体、列表等）
- 代码块带有语法高亮
- 表格以规范的表格形式展示
- 链接可点击、图片可预览
TODO: 截图 - 基本测试的输入内容与渲染结果对比
第四步：切换渲染器版本
在右侧的 渲染配置 区域，找到 渲染器版本 下拉菜单。试试从默认的 V2 - Custom Parser 切换到 V1 - Markdown-it，观察同一个内容在不同引擎下的渲染差异。
TODO: 截图 - 渲染器版本切换下拉菜单
第五步：尝试流式模式
在工具栏关闭 流式模式 开关（默认开启），然后点击 重新渲染 按钮。内容会以打字机效果逐字输出，模拟 LLM 的实时响应体验。
TODO: 截图 - 流式模式开关位置标注
功能详解
输入区
输入区位于页面顶部，用于输入或编辑待测试的 Markdown/HTML 内容。
基本操作
- 直接输入：在编辑器中直接输入 Markdown 文本，预览区会实时更新
- 清空内容：点击工具栏的 清空 按钮重置输入
- 从预设加载：从预设下拉菜单选择一个预设，内容自动填入
输入格式支持
输入区支持标准的 Markdown 语法，以及以下扩展格式：
| 格式 | 语法示例 | 说明 |
|---|---|---|
| 标准 Markdown | # 标题、**粗体** | 标题、粗体、斜体、列表、链接、图片等 |
| GFM 扩展 | - [ ] 任务、| 表格 | | 任务列表、表格、删除线 |
| KaTeX 公式 | $E=mc^2$、$$\sum_{i=1}^n$$ | 行内和块级数学公式 |
| Mermaid 图表 | ```mermaid ... | 流程图、时序图、甘特图等 |
| HTML 混合 | <div style="...">...</div> | HTML 与 Markdown 深度嵌套 |
| LLM 思考块 | <think>...</think> | 可折叠的思考过程块 |
| VCP 工具调用 | <<<[TOOL_REQUEST]>>> | VCP 协议工具调用格式 |
TODO: 截图 - 输入区编辑器，标注代码编辑器顶部工具栏
预览区
预览区位于页面底部，实时展示输入内容的渲染结果。这是你在测试中主要关注的区域。
渲染模式
预览区支持四种渲染器版本，通过右侧配置面板的 渲染器版本 下拉菜单切换：
| 版本 | 标识 | 特点 | 推荐场景 |
|---|---|---|---|
| V1 - Markdown-it | v1-markdown-it | 基于 markdown-it 的增量解析器 | 兼容性测试、性能对比 |
| V2 - Custom Parser | v2-custom-parser | 推荐自研 AST 解析器，支持复杂 HTML 和 LLM 思考块 | 日常测试、新功能验证 |
| Pure Markdown-it | pure-markdown-it | 纯 markdown-it 无增量优化 | 基准测试 |
| Hybrid V3 | hybrid-v3 | 混合策略 V3 版本（规划中） | 预留 |
TODO: 截图 - 同一内容在 V1 和 V2 下的渲染对比
可视化块状态
在右侧 渲染配置 中开启 可视化块状态 开关后，预览区中的每个 AST 节点都会显示其状态标签：
- 🟢 stable：语法完整的稳定节点，不会再次变化
- 🟡 pending：待定区的节点，可能随着新内容到达而改变
这在调试流式渲染问题时特别有用，可以直观地看到哪些内容还在变化中。
TODO: 截图 - 开启可视化块状态后的预览区，标注 stable 和 pending 标签
配置面板
配置面板位于预览区右侧，是工具的核心控制区域，分为多个功能区块。
渲染配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| 渲染器版本 | 选择渲染引擎 | V2 - Custom Parser |
| 节流时间 (ms) | AST 更新节流间隔，控制打字机更新频率 | 80ms |
| 启用节流 | 是否启用 AST 更新节流 | ✅ 开启 |
| 启用流式平滑化 | 平滑 Token 发射节奏，避免视觉卡顿 | ✅ 开启 |
| 可视化块状态 | 显示稳定区/待定区状态标签 | ❌ 关闭 |
| 启用调试日志 | 输出详细渲染日志到控制台（会刷屏） | ❌ 关闭 |
TODO: 截图 - 渲染配置区块
样式编辑器
样式编辑器让你可以所见即所得地调整 Markdown 元素的 CSS 样式：
- 全局开关：控制是否应用任何自定义样式
- 元素列表：段落、粗体、斜体、删除线、引用、块引用、警告块、行内代码、链接、H1-H6 标题
- 每个元素可调整：
- 颜色
- 背景色
- 字体粗细 / 斜体 / 装饰线
- 文字发光（text-shadow）
- 边框发光（box-shadow）
- 边框圆角
TODO: 截图 - 样式编辑器面板，展示某个元素的编辑状态
LLM 思考规则
用于配置哪些 XML 标签应被识别为"思考节点"。默认已包含两个规则：
| 规则 | 标签名 | 显示名称 | 默认折叠 |
|---|---|---|---|
| standard-think | <think> | 思考过程 | ✅ 折叠 |
| gugu-think | <guguthink> | 咕咕的思考 | ❌ 展开 |
你可以：
- 添加新规则：指定标签名、显示名称和是否默认折叠
- 编辑规则：修改现有规则的参数
- 删除规则：移除不需要的规则
- 重置为默认：一键恢复默认配置
TODO: 截图 - LLM 思考规则编辑器
安全配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| 默认渲染 HTML | 是否默认渲染 HTML 代码块 | ❌ |
| HTML 无边框模式 | HTML 预览无边框渲染 | ❌ |
| CDN 本地化 | 自动替换 CDN 链接为本地资源 | ✅ |
| 允许危险 HTML | 允许渲染 script/iframe 等标签 | ❌ |
| 启用进入动画 | 新增节点是否带淡入动画 | ✅ |
| 允许外部脚本 | 是否允许加载外部 CDN 脚本 | ❌ |
| 默认展开代码块 | 代码块默认展开 | ❌ |
| 默认折叠工具调用 | 工具调用默认折叠 | ❌ |
TODO: 截图 - 安全配置区块
流式配置
当开启流式模式时，以下配置控制流式模拟的行为：
| 配置项 | 说明 | 默认值 |
|---|---|---|
| 流式速度 | 输出速度（字符/秒） | 100 |
| 初始延迟 | 开始输出前的等待时间（ms） | 500 |
| 启用波动 | 模拟真实网络环境下的发包抖动 | ❌ |
| 延迟波动 | 延迟的随机波动范围（min~max ms） | 50~200 |
| 字符波动 | 单次输出字符数的随机波动范围 | 1~10 |
TODO: 截图 - 流式配置区块
测试报告
测试报告功能让你可以将测试结果导出为结构化报告，用于问题复现和团队协作。
点击工具栏的 复制报告 按钮，会弹出一个配置对话框，让你选择报告包含的内容：
| 报告内容 | 说明 |
|---|---|
| 测试配置 | 包含渲染器版本、流式参数等配置信息 |
| 原文 | 输入的原始 Markdown 内容 |
| 渲染 HTML | 渲染后的 HTML 代码 |
| 规范化原文 | 经过规范化处理后的原文 |
| 规范化渲染 | 规范化处理后的渲染结果 |
| 对比结果 | 原文与渲染结果的逐行对比 |
| 样式配置 | 当前的样式编辑器设置 |
选择完成后点击复制，报告会以 JSON 格式复制到剪贴板。
TODO: 截图 - 复制报告配置对话框
实时 AST 查看器
AST 查看器以树状结构实时展示当前内容的抽象语法树。每个节点显示：
- 节点类型（如
paragraph、heading、code_block） - 节点属性（如 heading 的 level、code_block 的 language）
- 子节点层级展开/折叠
这是深入理解渲染引擎内部结构的最佳工具——你可以清楚地看到一段 Markdown 文本是如何被拆解成层级化的 AST 节点的。
TODO: 截图 - AST 查看器的树状结构展示
高级用法
复杂场景组合测试
通过不同的预设组合和配置调整，你可以测试各种复杂的渲染场景：
场景一：HTML 沙箱渲染测试
- 选择一个包含复杂 HTML 的预设，如 复杂渲染测试 (complex-rendering-test)
- 确保渲染器版本为 V2 - Custom Parser
- 开启 默认渲染 HTML 开关
- 观察 HTML 内容如何在沙箱中渲染，包括内部的 SVG、交互元素等
场景二：流式状态下思考块行为
- 选择 LLM 思考节点 (llm-think-nodes) 预设
- 开启流式模式并设置较慢的流式速度（如 50 chars/s）
- 观察思考块在流式过程中如何从"思考中"状态过渡到"已完成"状态
- 尝试修改思考规则，添加自定义标签名来测试新的思考块类型
场景三：样式效果对比
- 选择 基本测试 (basic) 预设
- 打开样式编辑器，为标题设置不同的颜色和文字发光效果
- 在 V1 和 V2 渲染器之间切换，观察样式是否在两种引擎下表现一致
- 调整
--card-opacity相关的透明度值，验证动态主题的通透效果
正则规则预处理
如果你需要在渲染前对内容进行预处理转换，可以在 正则配置（Regex Config） 中设置自定义正则规则。规则会在内容进入渲染器之前执行，实现自动替换和格式转换。
TODO: 截图 - 正则配置面板
测试对比与回归
当你修改了渲染引擎的代码后，可以使用这个工具进行回归测试：
- 逐个运行所有预设用例
- 使用 复制报告 功能保存当前版本的渲染结果作为基线
- 修改代码后重新测试，对比报告差异
- 确认所有预设的渲染效果均符合预期
常见问题
Q：V1 和 V2 渲染器有什么区别？我应该用哪个？
V1（Markdown-it）是行业标准的 Markdown 解析器，兼容性好但功能有限——不支持 LLM 思考块、VCP 工具调用和复杂 HTML 嵌套。V2（Custom Parser）是自研的 AST 解析器，在这些 LLM 特定场景下有更好的表现。日常测试推荐使用 V2，在遇到兼容性问题时可以切换到 V1 做对比验证。
Q：为什么我的 HTML 内容没有渲染？
请检查以下配置：
- 是否开启了 默认渲染 HTML 开关（默认关闭）
- 如果使用了
script、iframe等标签，需要开启 允许危险 HTML - 如果引用了外部 CDN 资源，确保 允许外部脚本 已开启
- 如果是裸 HTML 页面（以
<!DOCTYPE html>开头），引擎会自动包裹在代码块中，防止 UI 爆破
Q：流式模拟时页面卡顿怎么办？
可以尝试以下优化：
- 降低 流式速度（减少字符/秒）
- 增加 节流时间（如从 80ms 调整到 150ms）
- 关闭 启用流式平滑化（减少缓冲层开销）
- 关闭 启用进入动画（减少动画渲染压力）
- 如果仍然卡顿，可以切换到 Pure Markdown-it 模式做基准对比
Q：如何测试一个自定义的 LLM 思考块标签？
在右侧配置面板的 LLM 思考规则 区域，点击 添加规则：
- 规则 ID：输入唯一标识（如
my-custom-think） - 标签名：输入自定义 XML 标签名（如
mythink——不要包含尖括号） - 显示名称：输入 UI 显示名称（如 "我的思考"）
- 默认折叠：选择是否默认折叠
- 保存后在输入区使用
<mythink>...内容...</mythink>即可看到效果
Q：样式编辑器中调整后没有变化？
可能的原因：
- 检查 全局开关 是否已开启（在样式编辑器顶部）
- 检查对应元素的 启用 开关是否已开启
- 尝试切换一次渲染器版本，强制刷新样式绑定
- 自定义样式只在 V1 和 V2 渲染器中生效，Pure Markdown-it 模式下不会应用
Q：如何将测试结果分享给团队？
使用 复制报告 功能：
- 点击工具栏的 复制报告 按钮
- 在配置对话框中选择需要包含的内容
- 点击复制，报告以 JSON 格式存入剪贴板
- 将 JSON 内容粘贴到文档、Issue 或聊天中
- 报告包含完整的测试配置、原文、渲染结果和对比信息，团队成员可以据此复现问题