Excalidraw与Mermaid语法互转可行性研究

Excalidraw与Mermaid语法互转可行性研究

在技术文档和系统设计日益依赖图形表达的今天，如何平衡“高效书写”与“直观呈现”成为团队协作中的关键挑战。我们常常面临这样的场景：一个开发人员用几行 Mermaid 代码就画出了清晰的流程图，而产品经理却更愿意在白板上自由勾勒逻辑关系；又或者，设计师在 Excalidraw 中完成了一幅精巧的架构草图，却难以将其嵌入自动化生成的 API 文档中。

如果能让手绘风格的草图自动变成可版本控制的文本，也能让一段简洁的 DSL 脚本渲染成可交互的视觉图示——这种双向流动的能力，正是当前可视化协作工具演进的重要方向。Excalidraw 和 Mermaid，恰好代表了两种主流范式：一个是基于画布的自由表达工具，另一个是基于代码的结构化建模语言。它们看似对立，实则互补。那么问题来了：能否在这两者之间建立一条可靠的转换通道？

答案是肯定的，但需要深入理解两者的底层机制，并在语义映射、布局还原和风格保留之间做出合理权衡。

Excalidraw 的本质是一个以 JSON 驱动的图形状态管理系统。每一个矩形、箭头或文本块都被表示为具有明确属性的对象，整个画布的状态可以被完整序列化并跨平台同步。它的数据结构开放透明，没有任何黑盒封装：

{ "type": "excalidraw", "version": 2, "source": "https://excalidraw.com", "elements": [ { "id": "A1", "type": "rectangle", "x": 100, "y": 100, "width": 200, "height": 80, "strokeColor": "#000", "backgroundColor": "transparent", "roughness": 2.5 }, { "id": "B2", "type": "arrow", "points": [[200, 140], [350, 140]], "startArrowhead": null, "endArrowhead": "arrow", "startBinding": { "elementId": "A1" }, "endBinding": { "elementId": "B2" } } ] }

这个 JSON 不仅包含了视觉信息（位置、颜色），还承载了语义连接关系——通过startBinding和endBinding字段，箭头与目标元素建立了动态绑定。这意味着即使你拖动矩形，箭头也会自动跟随。这种“带语义的图形对象模型”，为外部解析和转换提供了坚实基础。

相比之下，Mermaid 完全走的是另一条路：它不关心像素坐标，也不提供自由排版能力。你写下的每一行代码：

flowchart LR A[开始] --> B{条件判断} B -->|是| C[执行操作] C --> D[结束] B -->|否| D

都会被解析成抽象语法树（AST），再由布局引擎 dagre 自动计算节点位置，最终输出 SVG。它的核心优势在于“确定性”——同样的输入永远生成相同的图，且无需人工干预排版。更重要的是，这段文本可以直接放入 Markdown 文件，在 Git 中进行 diff 比对，完美融入现代软件工程流程。

从工程角度看，这两种模式各有边界。Excalidraw 强于表现力，弱于可维护性；Mermaid 强于自动化，弱于灵活性。但如果能把 Mermaid 的结构化逻辑导入 Excalidraw 成为可编辑草图，又能将 Excalidraw 中的结构化图形导出为 Mermaid 文本用于文档发布，岂不是一举两得？

要实现这一点，关键是构建一个中间层——通用图表抽象模型（Common Graph AST）。我们可以设想这样一个转换流程：

[Mermaid Text] ⇩ (Parse → AST) [Abstract Syntax Tree] ⇧ (Generate ← AST) [Excalidraw JSON] ⇩ (Render) [Excalidraw Canvas]

在这个架构中，Mermaid 文本首先被解析为包含节点、边及其标签的 AST；然后该 AST 被转换为 Excalidraw 元素数组。这里有几个技术难点需要注意：

• 布局缺失问题：Mermaid 本身没有坐标概念，所以必须引入外部布局算法（如 dagre）来预计算每个节点的位置，才能在 Excalidraw 中合理摆放。
• 复合元素构造：Excalidraw 中没有“带文字的矩形”这种原生类型，因此每个流程图节点都需要拆解为一个rectangle+ 一个居中的text元素，并确保它们作为一个整体被选中和移动。
• 连接语义重建：不能仅靠箭头起点终点靠近某个形状就判定其关联，必须显式设置startBinding和endBinding，否则一旦用户移动元素，连接就会断裂。

反过来，从 Excalidraw 到 Mermaid 的反向转换更具挑战性。因为并非所有手绘内容都适合结构化提取。比如用户随手画了一个云朵标注，或是一条装饰性曲线，这些都不应参与转换。因此我们需要定义“可识别结构”的判定规则：

1. 至少存在两个以上带有文本的矩形/菱形元素；
2. 存在多个带箭头的线条，并且这些线条通过binding明确连接到图形上；
3. 图形整体呈现明显的流向趋势（水平或垂直为主）。

满足这些条件后，系统便可尝试提取节点 ID 与标签映射，还原边关系，并推断布局方向（LR 或 TB）。例如，若大多数箭头呈水平分布，则默认使用flowchart LR；反之则用TB。对于分支判断（如菱形决策框），可通过正则匹配常见关键词（“是否”、“判断”、“条件”等）辅助识别。

当然，现实中的图形远比理想情况复杂。常见的障碍包括：

值得注意的是，我们不必追求“完全无损”的双向转换。事实上，合理的转换应该是有选择性的降级与升维。比如，Mermaid 输出无法还原手绘感，这是可接受的代价；而 Excalidraw 导出时忽略涂鸦类内容，反而是提升了信号噪声比。

真正有价值的应用场景其实非常具体：

• 一位工程师在写 PR 描述时，直接粘贴一段 Mermaid 流程图，评论区自动渲染为可点击展开的 Excalidraw 草图，便于团队讨论修改；
• 产品原型评审会上，主讲人将 Excalidraw 白板中的核心逻辑一键导出为 Mermaid 代码，插入 Confluence 文档作为正式记录；
• CI 系统监听仓库中的.mermaid文件变更，自动生成对应的可视化快照并嵌入 README，提升文档可读性。

这些都不是炫技式的功能叠加，而是围绕“降低认知负荷、加速信息流转”这一根本目标展开的实际优化。

从实现路径上看，最可行的方式是开发轻量级工具链插件。比如：
- 一个 VS Code 扩展，支持右键菜单“Preview as Excalidraw”；
- 一个 Obsidian 插件，在笔记中嵌入双向同步的画布；
- 或是一个浏览器书签脚本，允许用户在任何 Excalidraw 实例中触发“Export to Mermaid”。

这类工具不需要重构现有系统，只需利用两者均已暴露的 API 接口即可完成桥接。事实上，Mermaid 提供了mermaid.mermaidAPI.parse()和render()方法，Excalidraw 也支持通过 URL 参数加载 JSON 数据，甚至可以通过window.excalidrawApi在嵌入模式下进行编程控制。

长远来看，这种“文本 ↔ 图形”的双通道表达体系，可能会逐渐成为技术组织的标准实践。就像当年 Markdown 让非专业作者也能写出格式规范的文档一样，未来的可视化协作，也应该做到“无论你会不会画画，都能准确传达想法”。

目前虽然还没有官方支持的互转方案，但由于双方的数据格式完全开放、语义清晰，技术障碍并不高。真正的难点反而在于用户体验设计：什么时候该自动转换？什么时候该让用户介入？如何避免误导性的“伪精确”转换？

或许最好的方式不是全自动，而是“半自动+可解释”。系统给出建议性转换结果，并高亮显示不确定的部分，邀请用户确认。这既保留了机器效率，又尊重了人类判断。

当我们在 Excalidraw 里拖动一个节点时，背后其实是数十个参数在实时更新；当我们写下一行 Mermaid 代码时，脑海里浮现的是一张完整的图。这两者之间的鸿沟，本质上是“直觉思维”与“逻辑表达”之间的鸿沟。而我们要做的，不过是架一座桥，让思想能更自由地流动。