XMarkdown 为 AI 报告加入图表与交互

AI 生成一份带图表的报告，往往还要输出大量 HTML 和 SVG：坐标轴、刻度、连线，以及反复出现的样式。XMarkdown 想把这些重复工作交给渲染器，让模型继续用 Markdown 写解释，只为图表补充数据和配置。

作者已经做出了可安装的 MVP，也给出了源码长度和处理性能的测量。但目前能确认的是特定样例更紧凑、部分流式处理更快，距离证明 AI 调用更便宜、报告更好用，还缺真实模型实验和用户研究。

为什么让模型写数据，比让它画坐标轴更合适

XMarkdown 的核心做法是「描述内容，复用渲染」。普通段落交给 markdown-it，标题、列表、引用、表格、删除线等继续使用熟悉的语法；需要图表时，再加入可选的扩展块。

下面是一份完整的柱状图配置，它解决的是「提供业务数据后，由渲染器生成图形」：

~~~x-chart
{
  "type": "bar",
  "title": "Requests per day",
  "description": "Monday 24; Tuesday 31; Wednesday 28.",
  "x": "day",
  "y": "requests",
  "data": [
    {"day": "Mon", "requests": 24},
    {"day": "Tue", "requests": 31},
    {"day": "Wed", "requests": 28}
  ]
}
~~~

重点看 "x": "day" 和 "y": "requests"：作者指定数据如何映射到坐标轴，具体的 SVG 几何、刻度和标签由库生成。description 则为图形提供文字解释。

这套分工适合重复生成同类报告。模型不用每次重新描述一张柱状图的画法，宿主应用也能统一维护展示规则。

代价同样明确：文档作者或模型需要学习配置结构，应用需要加载专用渲染器。在 DEV 这样的普通 Markdown 环境里，扩展块只会显示成代码。

项目也没有停留在单张图表。网站提供了 18 个示例，其中一个架构场景包含三层结构、七张服务卡片，以及存储端点、曲线连接、渐变、网格、蒙版和裁剪。这证明了表达范围，但还不能证明复杂图形都容易编写。

接入 React 后，文档能交互到什么程度

目前实现使用 JavaScript，Node、浏览器 API 和 React 共用核心。网站保存的示例通过 Node 入口渲染，编辑后的内容通过浏览器入口处理。Python、Go、Rust 尚无独立解析器，其他服务端语言需要通过 Node/HTTP 桥接。

原文给出的安装命令是：

npm install xmarkdown-renderer

当前包版本为 0.2.1，包含 TypeScript 声明；React 示例要求 React 18+，受支持的开发和运行环境为 Node.js 22+。

React 组件从 xmarkdown-renderer/react 导入 XMarkdown，样式使用 xmarkdown-renderer/styles.css。示例通过 source 更新文档，使用 onError 显示错误，并在 onDiagnostics 回调中清除错误状态。服务端渲染还可以传入已解析的文档。

交互通过 x-widget 声明。原文的容量示例把滑块 rate 设置为最小 0、最大 180、初值 80，再用表达式 max(0, rate - 100) 显示每分钟请求积压量。旁边可以放公式 $\lambda < \mu$，解释稳定到达所需的条件。

这种交互适合让读者调整假设、观察结果。它的边界是受支持的输入和表达式，文档作者不能加入任意 JavaScript。

在 JavaScript 模板字符串中，~~~ 围栏可以避免与反引号冲突，反引号围栏也受支持；String.raw 用来保留 TeX 的反斜杠。共享样式只需在应用中导入一次。

少了多少 token，快了多少，分别测的是什么

源码更短、渲染更快、AI 调用更省钱，是三个需要分别验证的结论。

源码比较包含 12 组配对示例。完整演示文档使用 XMarkdown 时为 208 个 token，紧凑 HTML/SVG 为 1,219 个，减少 82.9%；对比复用图形组件的 HTML，减少幅度为 20.3%。

第二个比较更有参考价值：组件方案已经把重复绘图逻辑收进库里，XMarkdown 仍有优势，但差距明显缩小。收益并非全部来自一种新语法，复用软件本身就能省下大量描述。

计数使用 o200k_base，同时保留 cl100k_base 结果；源码统一使用 LF 换行。紧凑 SVG 将数值属性四舍五入到 0.001 单位，同时保留元素、标签、描述和坐标轴。片段计数排除了共享运行时和格式说明，后者单独占 383 个 o200k_base token。

因此，208 对 1,219 不能直接换算成模型账单。格式提示、示例、无效输出和修复轮次都要计入。原文也承认，导入现成 SVG 还会多出围栏，定制矢量场景仍需描述几何，压缩效果取决于内容。

性能测试则回答另一件事。对于 6,320 字符的纯文本，裸 markdown-it 耗时 0.259 ms，XMarkdown 为 0.268 ms。数据不支持作者早期设想的通用 50× 解析提速。

扩展流式负载取得了 5.48× 的处理速度优势，对照方式是不断重新解析、渲染越来越长的完整前缀。XMarkdown 会先输出临时分节更新，结束时完整解析，以保留引用等全文语义；有界缓存复用已验证配置和几何，并为每次放置重写 SVG ID。

但短数学样例只有 0.78×，反而更慢。文档形态和分块方式会改变结果。

这些测量在 Windows、Node.js 22.22.0 下完成，功能基准经过预热和七轮计时，轮换条件顺序并报告中位数。扩展缓存为空时，依赖仍已加载；首次使用的启动成本另行记录。测量对象是 2026 年 11 月 8 日的 v0.2.0，依赖 markdown-it 14.3.3；当前 0.2.1 已改用 markdown-it 15.0.3，不能混称为同一版本结果。

仓库通过 npm run compare 和 npm run bench:features 复现比较。浏览器布局、绘制、网络、模型生成和总堆内存均未纳入这些计时。

我的判断

我认同它对报告类产品的分工：模型写解释和数据，应用维护可测试的展示规则。对于反复生成相同图表的场景，这比每次生成完整页面更容易约束，也方便修改数据。

不过，20.3% 的组件对照差距提醒我们：已有成熟 React 图表组件的团队，可以先评估复用组件是否已足够。原文尚未提供模型生成成功率、修复成本和用户理解效果的对照数据，不能据此认定 XMarkdown 必然更省钱、更易用。

安全也仍有前提。结构化场景和 x-svg 导入都会验证，但当前静态 SVG 范围排除了脚本、事件处理器、外部资源、foreignObject、滤镜和动画；控件表达式使用有界解释器，不使用 eval。这些限制有助于明确边界，却不等于完成了安全验证。作者明确表示还需要模糊测试和独立安全审查，处理恶意输入时宿主仍需隔离和资源预算。

项目已有 Node 22、24 的 CI，但图路由、更多图表、浏览器 worker、无障碍覆盖及完整框架应用仍待完善；Mermaid、任务列表复选框和外部图片处理也属于后续工作。1.0 前 API 和语法可能变化。纯文字继续使用普通 Markdown，自由页面布局继续使用 HTML 和 JavaScript，都是合理取舍。

能拿来做什么

• 在现有 React 报告页中选一条范围明确的流程试用，例如固定图表类型的容量报告，先验证数据修改、错误反馈和展示效果。
• 给 AI 报告功能做一次真实对照，把 XMarkdown 与现有 HTML 或组件方案放在同一任务下，统计包含格式说明的输入输出 token、有效输出率和修复轮次。
• 对流式报告分别测量生成、验证、渲染和交互延迟，并覆盖自己的文档长度与分块方式，避免直接套用 5.48×。
• 如果报告需要公式和假设调整，可以先尝试声明式控件；同时验证目标读者能否理解、编辑结果，再决定是否扩大使用范围。