Flora：一个为AI构建（并与AI共同构建）的图表库

十天前，作者从零开始构建一个图表库，如今发布了 Flora——一个容错、兼容 Mermaid 的图表库，能将不完美的输入渲染为精美的交互式 SVG。本文不仅介绍 Flora，更想分享其构建过程，因为过程本身比产品更令人惊喜。

为什么需要另一个图表库？

作为一名数据工程师，设计架构是日常工作的重要部分。在构建数据管道之前，总需要先画图：数据如何流动、存放在哪里、各组件如何交互。图表既是思考的方式，也是说服他人的工具。

在 AI 原生的世界里，Mermaid 已成为“图表即代码”的通用语言——LLM 用它生成图，GitHub 用它渲染图，作者过去几年也一直使用它。图表即代码的核心思想很棒：图表像 Markdown 文本一样存放在仓库中，可被评审，永不腐烂。但有两件事一直困扰着作者。

首先是美观问题。每当想定制图表外观——例如整个文档站使用统一配色，或者让圆柱体不挤压标签——就会遇到限制。一位同事构建的图表设计工具能产生非常漂亮的输出，但所有内容都是硬编码的 SVG。修改一个节点就得重新生成整张图。为了美观而牺牲 Mermaid 的声明式能力，作者立刻怀念起后者。

其次，LLM 经常生成 Mermaid 代码，但几乎总是接近正确而非完全正确。一行格式错误，Mermaid 就会抛出解析错误，UI 渲染一个空白框。如果图表即文本已成为 AI 与人类之间的接口，那么渲染器不应在文本 95% 正确时报错。

Flora 的解决方案：使用 Mermaid 的语法，输出更美观，解析器更具弹性。

功能概览

Flora 能理解您已经会写的流程图语法。例如：

flowchart LR events[[Kafka: events]] --> enrich[Enrichment] enrich --> wh[(Snowflake)] wh --> dash([Dashboard])

上述代码在默认主题下渲染；同样代码，使用草图主题则呈现“白板草图”风格而非最终架构图。

图表开箱即支持交互：缩放、平移，以及作者最爱的功能——点击任意节点可追踪其上下游依赖链。

容错是作者最关注的设计决策。当 Mermaid 遇到无法解析的行时，它会抛出异常并显示空白框，即使图表有 40 行且其中 39 行正确。Flora 则跳过无法理解的行，渲染其余内容，并以诊断信息（含行号和列号）报告跳过的行。更重要的是，它从不猜测：格式错误行直接丢弃并标记，而非重新解释为您未编写的节点。如果希望在 CI 中严格报错，可启用 strict: true 选项让解析器抛出异常而非尽力渲染。

使用方式

Flora 提供多种集成方式：

• JavaScript/TypeScript：npm install @topspinj/flora 获取完整 API。
• 纯 HTML：CDN 包注册为 Web Component，添加 script 标签即可在页面中用标记编写图表。
• React：提供封装组件。
• Markdown 文档：rehype 插件在构建时渲染 Flora 代码块，默认在图表错误时导致构建失败。
• Python/Jupyter：pip install florajs 支持 Jupyter/marimo 笔记本及无头 SVG 导出。
• 博客/平台：hosted /embed 路由可在任何支持 iframe 的地方使用（如 Ghost、Substack、Notion）。
• 浏览器：在线游乐场实时渲染并编码图表至可分享 URL。

构建过程：GitHub Issue 作为提示词

作者真正想分享的是构建过程。作者并非 TypeScript 专家——职业生涯始于 React 和 NodeJS，但那已是十年前，之后一直使用 Python 和 SQL。在此之前，作者从未发布过 npm 包、配置过 TypeScript 构建或认真思考过解析器设计。十天之内，作者完成了所有三项，而 Python 封装从空目录到发布到 PyPI 只用了不到 30 分钟。

关键工作流是将 GitHub Issue 作为提示词。作者不再为自己或未来的贡献者写 Issue，而是直接写出供 AI 代理处理的 Issue。在《专业伪代码的理由》一文中，作者曾认为将模糊意图转化为精确规格正在成为工作的核心。本项目正是这一想法的最终实践。不是写“解析器坏了”，而是写“解析器无法理解的行应被完整跳过，并以诊断信息报告行号和列号。绝不重新解释为额外节点。所有有效内容仍应渲染。添加包含格式错误固定用例的回归测试。”

Issue 跟踪器成为通信协议。作者晚上排队 Issue，第二天处理时更像是在给一位非常快速的同事分配任务。

Fable 的加入

周三晚上，一封邮件到达：Claude Fable 5 现已可用。通常作者会将模型公告归档稍后处理，但这次手头有一个进行中的项目——真实代码库、已梳理好的代理就绪 Issue 列表、以及测试新模型的完美理由。邮件发出两小时后，Fable 已交付了 Flora 的 React 封装。

Flora 大约一半的提交历史发生在接下来的 48 小时内。CDN 包、Web Component、解析器诊断、严格模式、Python 包、在线游乐场：全部在两天内完成。但速度并非最有趣的部分。Fable 捕获了作者从未要求它查找的 bug，并反驳了作者的一些想法。当作者试图让主题控制节点间距时，Fable 认为主题应改变图表外观，而非布局——它是对的。感觉更像是代码审查，而不是自动补全。

v0.1 发布

目前还处于早期阶段，存在粗糙之处，Issue 跟踪器也诚实地列出了它们。最好的部分是作者能立即在实践中试用——工作中没有强制使用的图表工具，Flora 将直接应用于日常工作。真实用例是最佳的测试方式。

如果你曾喜爱 Mermaid 但希望它更美观、更少出错，不妨试试 Flora。