Mermaid 渲染器从PNG改用SVG：一个被忽视的质量盲区

自动化测试说"通过"，人类放大后说"模糊"。这两件事之间的距离，往往比我们想象的更远。

一个"看起来没问题"的PNG

故事的开头很普通。为了不让 AI Agent 每次画流程图都要启动一个无头 Chrome 浏览器，开发者自己写了一个 Mermaid 渲染器。第一版逻辑直接：固定宽度渲染，返回 base64 编码的 PNG。

测试阶段一切正常——字节能正确解码，图片尺寸和预期一致，测试用例全绿。按照自动化测试的标准，这个功能"已完成"。

问题出现在一个自动化测试永远覆盖不到的场景：有人把生成的流程图粘贴到幻灯片里，然后放大。文字是模糊的。不是损坏，不是缺失，只是被栅格化到了一个"不放大就看不出问题"的分辨率。

PNG（Portable Network Graphics）是一种基于像素栅格的位图格式，图像由固定数量的像素点构成，每个像素记录颜色信息。它采用无损压缩，适合存储需要精确保留像素信息的图像，但分辨率在生成时就被锁定。当图片被放大显示时，软件只能在原有像素之间做插值估算，边缘和文字笔画会因此变得模糊、出现锯齿。这种模糊不是文件损坏，而是栅格格式的固有属性：它记录的是"某个尺寸下每个点长什么样"，而不是"图形本身由哪些线条和形状构成"。正因如此，PNG 在需要缩放、高清打印或高倍率查看的场景中，天然存在清晰度上限。

就本例而言，开发者选择固定宽度渲染并返回 base64 编码的 PNG。base64 编码只是把二进制图像数据转换为可由文本协议传输的字符序列，并不改变图像本身的分辨率或清晰度。因此全部自动化测试都能通过——字节能正确解码、尺寸也符合预期——但"固定宽度"这一前提，已经悄悄决定了这张图在放大后的清晰度上限。

"渲染正确"和"渲染得好"是两回事

这件事的价值不在于 PNG 和 SVG 的技术差异——这是常识。真正值得思考的是：自动化测试验证的是"有没有返回图片"，而不是"人能不能看清图上的标签"。

开发者自己的总结非常精准："渲染正确"（renders correctly）和"渲染得好"（renders well）是不同的验收标准，而后者通常对那个宣布前者通过的自动化测试完全不可见。

这不是某一个人的疏忽。在 Agent 工具链的开发中，输出结果往往被当成中间产物——只要下游能解析就行。但当输出最终要经过人眼审视时，"能解析"和"能阅读"之间就出现了一道裂缝。

修复方案：默认 SVG，PNG 降级为选项

最终的修复既不复杂也不新潮：把默认输出格式改为 SVG。

效果很直接——矢量图任意缩放不失真，文件体积反而更小，图表在任何缩放级别都保持清晰。PNG 并没有被移除，只是从默认变成了可选：邮件附件、部分聊天客户端、旧管线仍然需要像素格式的图片，显式传入格式参数即可获取。

改动本质上只有一个参数的默认值翻转，但它把曾经作为默认行为暴露给所有用户的失败模式，变成了需要主动选择才会触发的可选项。

这个渲染器已经打包发布，无需浏览器栈即可完成 Mermaid 到图片的转换，地址在 x402.freeq.one。

SVG（Scalable Vector Graphics）是一种基于 XML 的矢量图形格式，它不记录每个像素的颜色，而是用数学描述的线条、曲线、路径和文本元素来定义图形。渲染时由显示引擎按当前尺寸实时计算，因此无论放大多少倍，边缘都保持锐利，文字也不会模糊。因为存储的是几何描述而非像素阵列，同样一幅简单流程图，SVG 的文件体积通常比高分辨率 PNG 更小。SVG 的另一个优势是文本在很多时候仍是可选中、可搜索的真实文本，而不是被"烧"进图像的像素。它的局限在于不适合表现照片等连续色调内容，且不同渲染引擎对复杂特性的支持存在细微差异。对于流程图、图表、示意图这类由线条和文字构成的图形，矢量格式几乎总是更合适的选择。

这也解释了为什么把默认格式从 PNG 改为 SVG 是一个高杠杆改动：它没有增加任何新功能，却让最常见的使用路径——粘贴到幻灯片、文档后放大查看——不再触发模糊这一失败模式。

对 AI Agent 工具开发的启示

这个案例折射出 Agent 工具链中一个普遍存在的品控盲区。

测试断言的是存在性，用户感知的是质量。 自动化测试擅长回答"函数有没有返回预期类型的值"，但对"返回值在真实使用场景中够不够好"几乎无能为力。分辨率、字体可读性、颜色对比度——这些维度天然难以被断言覆盖。

格式选择应该匹配消费场景。 面向 Agent 的 API 倾向于返回最通用的格式，但"通用"不等于"合适"。当输出可能进入人类视野——演示文稿、文档、报告——矢量格式几乎总是更安全的选择。默认值的选择本质上是为大多数用户预设一个不容易出错的路径。

失败模式默认化是隐蔽的技术债。 把低质量输出设为默认，等于把风险分摊给了所有用户，而只有那些恰好放大了图片的人才会发现。把它设为可选，则把选择权交还给了知道自己需要什么的调用方。

一个参数的改动，解决的不是性能问题，不是架构问题，而是"我们以为测过了"和"用户真的看了"之间的认知差。