Beautiful Mermaid：Craft 给 Mermaid 做的”换肤引擎”，SVG 与 ASCII 双输出

Mermaid 已经是技术文档里画流程图的事实标准，但它有个长期被吐槽的问题：默认长相非常程序员——默认配色、默认字体、默认圆角，放到任何稍微讲究一点的产品文档里都显得违和。文档团队要么手动写 CSS 覆盖，要么忍了。Craft 团队（做 Craft 笔记/AI Agents 那家）开源的 beautiful-mermaid 就是来填这个坑的：一个专门负责”把 Mermaid DSL 渲染得好看”的库，官方口号是”为 AI 时代设计的图表渲染器”，同时输出 SVG（给浏览器）和 ASCII（给终端/CLI/日志） 两种格式。本文基于官方演示站 agents.craft.do/mermaid 实读分析。

说明：本分片原选题 TUI Studio（news/1595）官方站点 tui.studio 已下线、GitHub 仓库也已转为私有，无法做一手调研，按流程改用备份选题 Beautiful Mermaid。

一、它解决的到底是什么问题

Mermaid 本体是”解析 DSL → 布局 → 输出 SVG”的完整管线，但主题能力一直薄弱。beautiful-mermaid 没有重新发明解析器，而是站在 Mermaid 的解析结果之上做了一层主题与渲染管线：官方页面展示的处理流程是 DSL → Parse → AST → Layout → Theme → Output，最后分成两条出口——矢量图（SVG）与文本（ASCII）。

官方给的硬指标（首页实读）：

• 16 套内置主题（Koala 周报转述为 15 套，以官方页面当前的”16 Themes”为准）；
• 170 个样例（SVG + ASCII 全部）在 1273ms 内渲染完毕——这是演示页自报的端到端基准；
• ASCII 渲染基于开源的 Mermaid-ASCII 项目二次开发；
• 覆盖流程图全部 12 种节点形状，以及时序图、类图、ER 图等 Mermaid 主流图种。

二、为什么要同时输出 ASCII

这个”双输出”看起来奇怪，其实是这个库最有 AI 时代味道的设计。SVG 是给人看的浏览器画面，ASCII 是给终端里的 AI Agent 和 CLI 工具看的——当编码助手要在终端里向用户解释一段架构，它总不能贴一张 PNG，只能贴 ASCII 框图。官方在首页直接标注”ASCII rendering based on Mermaid-ASCII”，等于把”Agent 在终端里画图”当成一等场景。

上图是官方样例库中”Parallel Links（& 语法）“的实际渲染：同一段 graph TD DSL，上方是源码，下方是渲染后的 SVG——节点对齐、箭头走线、间距都比 Mermaid 默认输出干净一截。

三、口径与局限（官方自己写的，重点看）

官方首页最诚实的一行字是：“Early preview — actively evolving”（早期预览，仍在快速演进）。结合实读内容，需要打折扣的地方：

1. “170 samples / 1273ms”是演示机上的端到端数字。 它包含了整页 170 个样例的 SVG+ASCII 渲染，但没有说明机器配置、是否冷启动、单图耗时分解——这是一个展示性数字，不是可复现 benchmark，别拿去和其他库做严谨对比。
2. 主题数会变。 “16 Themes”是演示站当前计数，官方自述在活跃迭代，发布主题数量短期就会漂移。
3. 能力边界 = Mermaid 的能力边界。 它不改 Mermaid 的 DSL 语义，也不解决 Mermaid 布局算法在复杂图下走线混乱的老问题——它只换皮。图太复杂时，好看但还是乱。
4. 开源但尚未成熟。 页面把 GitHub 入口藏在按钮后，README 与版本号、包名、集成方式需要到仓库里另行确认；作为”早期预览”，API 随时可能变。
5. 它服务于 Craft 自己的产品优先。 官方定位是”Use in Craft Agents”——开源是结果，不是目的，优先级永远排在 Craft 自家需求后面。

四、客观评价

优势：

• 切入了一个真实痛点：Mermaid 默认样式在产品文档里确实拿不出手；
• SVG + ASCII 双输出押中了”AI Agent 在终端画图”这个新兴场景；
• 16 套主题 + 在线实时编辑器，选型成本低，打开页面就能看到效果。

局限：

• 本质是渲染层换皮，不提升布局质量；
• 早期预览阶段，API/生态未稳定；
• 对已经深度定制过 Mermaid 样式的团队，迁移收益有限；
• ASCII 框图的可读性在复杂图下依然有限，终端字符网格是硬约束。

五、谁该关注

正在写技术文档/产品文档、嫌 Mermaid 默认图难看的团队；以及在做 AI Agent 产品、需要让 Agent 在终端或 CLI 里输出结构化框图的工程师——ASCII 这条线目前同类工具很少，值得盯一下它的演进。只画几张图自用、对样式无所谓的人，继续用 Mermaid 默认输出就够了。

参考来源

• Beautiful Mermaid 官方演示站（Craft）
• Koala 项目库条目（备份选题）