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。