如果一個項目的 README 從第一屏開始就是一大張 Mermaid 圖你會先覺得專業(yè)還是先在心里存一個疑點我最近在看一類被稱為“autonomous OSS 創(chuàng)作集體”的開源項目時越來越傾向于后者。并不是說圖不能畫而是當 Mermaid 的出場率高到某種程度它就不再是一種圖表工具而變成了一種風格指紋。你甚至不需要看作者署名只要看到那種節(jié)點密、箭頭多、子圖疊子圖的渲染方式就能猜出背后的流程大概有機器深度參與。Dex Horthy 在技術(shù)討論里調(diào)侃這個現(xiàn)象時很多人的第一反應是大笑第二反應是“我也見過”。但調(diào)侃底下藏著一個不太容易消化的結(jié)論流程可以自動化表達的取舍卻不能全部外包。1. 一句玩笑背后不是 Mermaid 的錯而是文檔正在“通脹”1.1 “autonomous OSS 創(chuàng)作集體”是一個什么輪廓很多第一次看到“autonomous OSS 創(chuàng)作集體”這個說法的人會誤以為它是一個工具名或者某個具體平臺。更準確的讀法是把它理解成一種協(xié)作形態(tài)的描述它更像是傳統(tǒng)開源協(xié)作與“自動化內(nèi)容生產(chǎn)”之間的一段光譜。傳統(tǒng)開源項目通常由人主導人寫 issue、人寫代碼、人評審、人維護文檔。即使有 CI 和輔助工具它們也只是流程中的一部分。而當協(xié)作走向“autonomous”那一端時大量生成、修改、排版甚至發(fā)布環(huán)節(jié)會由腳本或模型完成。創(chuàng)作的內(nèi)容不一定只是代碼也可能是博客、文檔、圖表、新聞稿或?qū)W習材料。整個項目本身以開源倉庫的形式存在所以叫“autonomous OSS”。這個形態(tài)里出現(xiàn)了一個很有意思的中間詞“open code”。它不只是指開源代碼更指一種表達方式把創(chuàng)作成果用代碼形式保存下來。文檔不是只讀長文而是倉庫里的 Markdown插圖不是設計稿而是可以用文本描述的圖表流程不是口頭共識而是能自動運行的腳本和配置。當創(chuàng)作過程變成代碼自動化就變得順理成章。問題是機器最容易生成的文本輸出里有一種東西非常顯眼Mermaid 圖。1.2 Mermaid 為什么會被這種協(xié)作方式選中Mermaid 的優(yōu)勢在今天已經(jīng)不需要科普。它用文本寫圖表天然可以進入 git 倉庫它不產(chǎn)生二進制圖片diff 時能看到具體改動它能在 GitHub 等平臺上直接渲染不需要額外設計資源對自動化系統(tǒng)來說生成幾十行 Mermaid 代碼的成本遠遠低于生成一張布局合理的圖片。所以你會看到幾乎每一個嘗試做“發(fā)布內(nèi)容自動化”的開源項目都會把 Mermaid 當成默認可視化語言。但問題也隨之而來當幾乎所有候選內(nèi)容都由同一類模型生成并按照同一類 prompt 模板輸出時產(chǎn)出的圖表風格會迅速收斂。收斂不是問題問題在于這種收斂反映的不是某家公司的審美而是一種“機器認為合理”的默認值。被調(diào)侃的 Mermaid 渲染風格通常長這樣節(jié)點很多每個組件都要有自己的框箭頭很多但很多箭頭并沒有解釋因果只是表示“這兩個東西有關系”子圖很多但子圖邊界常常只是服務模塊劃分而不是幫助讀者理解問題域圖上沒有明顯主路徑讀者必須自己從一堆分支里找入口和出口。這種圖乍看很完整細看很空。它不是某個人的技術(shù)不行而是文檔正在經(jīng)歷一種“通脹”同樣的信息正在用越來越多的視覺單元去表達。2. 為什么自動化程度越高的項目圖反而更容易雷同2.1 生成器擅長模仿形態(tài)不擅長判斷“讀者此刻缺什么”理解這個問題的關鍵是先接受一件事圖不是給作者看的是給讀者看的。作者畫出十個節(jié)點是因為他知道這十個節(jié)點之間的關系。機器生成十個節(jié)點是因為它在大量訓練文本中看到“架構(gòu)圖”往往會包含很多組件。一個模型可以通過 token 概率推斷出“下一步該畫一個服務、一條連線或一個子圖”但它很難判斷現(xiàn)在的讀者是否需要知道這個服務當自動化系統(tǒng)承擔文檔創(chuàng)作時它最常犯的錯誤是“把所有信息都平鋪出來”。原因不復雜很多結(jié)構(gòu)生成任務都會要求模型“完整、全面、不要遺漏”。于是模型把每個組件都描述出來每條可能鏈路都畫進去結(jié)果是一張圖里找不到重點。這不是模型故意把圖變復雜而是它缺少一個關鍵的心智模型讀者現(xiàn)在只需要一個路徑而不是一張系統(tǒng)全圖。2.2 自動化流程需要可視化“完成證據(jù)”另一個容易被忽略的原因是激勵結(jié)構(gòu)。在自動化協(xié)作流程里任務是拆分給機器去做的。一個 agent 完成一輪生成后需要一個能被審查者看見的產(chǎn)出物。文字改動常常藏在 PR diff 里不容易一眼看出價值但一張 Mermaid 圖渲染出來以后會非常醒目地出現(xiàn)在頁面中像一份“我做完了”的證據(jù)。于是工作流會慢慢形成一種激勵不是讓內(nèi)容更精準而是讓交付物更可見。圖表天然滿足這個需求。這種激勵結(jié)構(gòu)一旦成立文檔容量會不斷增長。每個任務都配上一張圖每個流程變更都重生成一張圖最后倉庫里的圖越堆越多但信息密度沒有同比例上升。這正是被調(diào)侃現(xiàn)象產(chǎn)生的現(xiàn)實土壤圖本身不是項目的必需品卻成了自動化產(chǎn)出的“過程證明”。2.3 統(tǒng)一工具鏈會催生統(tǒng)一審美而審美又會反噬表達當同類項目使用同一套生成模板、同一套繪圖工具、同一套 Prompt 框架時它們產(chǎn)出的圖風格高度雷同幾乎是必然的。風格趨同是不是壞事不一定。一個團隊內(nèi)部統(tǒng)一圖表風格反而能降低閱讀成本。但當整個技術(shù)社區(qū)都開始用同一種“高密度、去分層、無主次”的方式表達架構(gòu)時就會出現(xiàn)一個副作用讀者不再能從排版和結(jié)構(gòu)中獲得判斷依據(jù)。你看到節(jié)點很多無法判斷它是不是真的復雜你看到箭頭很密無法區(qū)分關鍵鏈路和旁支細節(jié)所有圖都長成一個樣子于是那些真正需要復雜度的系統(tǒng)也被淹沒在同樣的視覺噪聲里。這也是調(diào)侃能引起共鳴的原因大家不是在笑某一種配色而是在笑一種“用圖的數(shù)量替代思考的深度”的文檔狀態(tài)。3. 不是圖不夠多而是“語義密度”太低3.1 先看一張“看起來很忙”的 Mermaid 圖下面這個例子是對一類典型圖表的簡化模仿。你可以只看最終感受不需要糾結(jié)節(jié)點的具體含義flowchart TD A[收集靈感] -- B[生成大綱] B -- C[生成初稿] C -- D{是否通過評審} D -- 否 -- C D -- 是 -- E[生成配圖] E -- F[生成 Mermaid 圖] F -- G[發(fā)布] G -- H[收集反饋] H -- I[生成改進計劃] I -- J[創(chuàng)建新 issue] J -- A這張圖有一個完整的閉環(huán)也有判斷分支。但它有一個致命問題它想表達的信息可能只需要兩句話“創(chuàng)作流程是一個從靈感到發(fā)布再到反饋的閉環(huán)如果評審不通過就回到初稿重新生成?！边@兩句話里沒有任何一個信息要求你必須看圖才能理解。圖里的每個箭頭、每個節(jié)點只是在把原來的文字翻譯成視覺語言并沒有增加新的判斷依據(jù)。這就是典型的“低語義密度”圖。3.2 再看一張只保留核心路徑的圖同樣描述創(chuàng)作流程如果先明確“我要讓一個新讀者在 30 秒內(nèi)知道內(nèi)容是怎么從起點走到終點的”那這張圖可以變成更短的形式flowchart LR A[選題] -- B[寫初稿] B -- C{評審} C -- 通過 -- D[發(fā)布] C -- 不通過 -- B這張圖的信息量反而更高。它讓人一眼看到入口是選題出口是發(fā)布評審不通過則回到初稿。它沒有畫配圖、反饋、issue、計劃不是因為那些環(huán)節(jié)不重要而是因為它們不是“核心路徑”的一部分。如果讀者需要了解完整 SOP可以用文字列出細節(jié)如果讀者需要理解團隊如何收集反饋可以再單獨畫一張反饋流程圖。一張圖只解決一個問題。這是一個簡單但很有用的原則。3.3 用“語義密度”判斷一張圖是不是多余我建議用一個不太精確但很好用的指標來判斷一張 Mermaid 圖是否值得存在語義密度 讀者真正獲得的結(jié)論數(shù)量 ÷ 圖上所有需要處理的視覺節(jié)點數(shù)量。視覺節(jié)點包括每個框、每根箭頭、每個標簽。讀者獲得的結(jié)論數(shù)量是指那些“如果他不知道就無法繼續(xù)理解”的信息單元。如果一張圖刪掉一半節(jié)點剩余圖表仍然能回答核心問題那說明被刪掉的部分很可能是裝飾。真正需要保留的節(jié)點通常滿足兩個條件它改變了讀者對流程或系統(tǒng)的理解它是讀者做出下一步判斷所必需的信息。如果一個節(jié)點既不改變理解也不影響判斷那它就該被刪掉。這在自動生成場景里特別重要因為機器默認會保留所有與主題相關的節(jié)點而人必須主動做減法。4. 給 Mermaid 上“護欄”從畫圖到表達邊界4.1 畫圖之前先回答四個問題我自己的習慣是任何一張 Mermaid 圖合入倉庫之前先回答下面四個問題。如果回答不流暢就說明圖還不該生產(chǎn)這張圖要給誰看是給用戶、給開發(fā)者、給運維還是給新加入項目的人我希望他在 30 秒內(nèi)得出一個什么結(jié)論這個結(jié)論能不能用兩三行文字直接表達如果能為什么還要圖如果只能保留其中的五個節(jié)點我會保留哪五個第四個問題最關鍵是。它逼著畫圖的人或者生成圖的人做取舍。自動生成往往不考慮取舍它只考慮覆蓋而一張有價值的圖恰恰是取舍的結(jié)果。4.2 一個簡易的“Mermaid 體檢表”在實際項目里硬性規(guī)則很難覆蓋所有真實場景但一個參考維度可以提醒你有問題。這里分享一個我在團隊 review 時常用的體檢表檢查項參考閾值超限后建議動作主圖節(jié)點數(shù)5 到 10 個超過 10 個先拆出另一張圖關鍵分支數(shù)量不超過 2 到 3 個分支過多說明圖沒有唯一主路徑箭頭標簽盡量用“動詞或條件”只寫“數(shù)據(jù)”或“連接”的箭頭要刪除子圖數(shù)量不超過 3 個超過 3 個說明讀者需要先理解邊界渲染后的寬度盡量控制在單屏以內(nèi)超寬圖通常是沒有分層的表現(xiàn)這個表格更像是一份提醒不是一份標準。有些系統(tǒng)圖天生復雜也確實需要很多節(jié)點但如果一張圖需要專門花 5 分鐘講解那它不是圖是謎題。4.3 分支多不是問題重點是先有主路徑很多被調(diào)侃的 Mermaid 圖本質(zhì)上不是“復雜”而是“沒有主路徑”。讀者不知道應該從左往右看還是從中間往兩邊看不知道哪個節(jié)點是入口哪個節(jié)點是結(jié)果。拆分思路很簡單先畫一張“主路徑圖”只包含從入口到出口的關鍵步驟把關鍵分支拆成單獨圖把非核心細節(jié)放到文字段落或列表里如果同一張圖需要服務不同讀者就按照讀者類型拆而不是按組件拆。例如用戶想知道“一次請求會發(fā)生什么”時不需要看到內(nèi)部部署結(jié)構(gòu)開發(fā)者想知道“組件如何依賴”時不需要看到完整用戶流程。兩者應分別畫圖而不是合成一張。5. 在自動協(xié)同流程里人工守護應該落在哪個環(huán)節(jié)5.1 先文字后圖示把“理解”留在生成之前如果你處在類似 autonomous OSS 創(chuàng)作集體的協(xié)作模式里最容易犯的錯就是一上來讓機器生成“結(jié)構(gòu)圖”。自動化系統(tǒng)的能力很強但它對“該畫什么”的理解來自 prompt 指令和訓練分布。如果一開始就沒有人明確說清這張圖要解決什么問題最終結(jié)果大概率是“什么都有但什么都不精”。更好的順序是先在 issue 中用文字寫清目標讀者和核心結(jié)論用純文字描述流程控制在 100 字以內(nèi)人工確認這段文字已經(jīng)準確再讓機器根據(jù)這段文字生成 Mermaid 草稿最后復查圖是否和文字表達一致。這里的重點是文字模型要先于圖表模型。文字本身就是在建立語義結(jié)構(gòu)如果文字沒有想清楚生成出來的圖只會放大模糊。5.2 把 Mermaid 代碼當成代碼來審而不是只做渲染合成在自動化產(chǎn)出場景里Mermaid 圖以文本形式進入代碼倉庫所以它也應該被當成代碼來審查。審查時不能只看渲染后的畫面“好不好看”。你需要看這次改動為什么動了這張圖新增節(jié)點是否真正帶來了新的判斷是否為了“重新生成一遍”而引入了原本可以避免的布局變化這張圖是否已經(jīng)超出了它最初承擔的解釋范圍如果一次 PR 只是修改了一行文案卻把整張圖的節(jié)點布局全部重排那說明這張圖的穩(wěn)定性還不夠不應該直接合入。自動生成工具可以把圖改得很頻繁但這不一定是優(yōu)化可能是噪聲。如果要加一點技術(shù)護欄可以用一個簡單的腳本統(tǒng)計 Mermaid 圖中的節(jié)點數(shù)量和箭頭數(shù)量超過閾值就在 PR 里自動提醒。注意這只能是提醒不是硬性失敗條件因為特殊情況下大圖確實必要。提醒的意義是讓人停下來看一眼而不是直接替代人的判斷。5.3 定期做“圖表清理”比不停新增圖更重要長期維護的文檔項目最終都會面對同樣的問題圖一旦進入倉庫就很少被刪掉。尤其當圖表由自動化流程生成時刪除需要人工判斷而人工最缺的是時間。我的建議是項目里維護一個docs/diagrams/README.md為每張圖寫一行說明它存在的理由。理由不是“描述系統(tǒng)”而是“這張圖幫助讀者弄明白了什么”。如果一張圖已經(jīng)沒有對應的流程或者它已經(jīng)被另一張圖覆蓋就可以刪除。刪圖不等于承認之前的自動化做得不對而是承認文檔是有維護成本的。長期看文檔倉庫的可靠性和代碼倉庫一樣修剪和新增同樣重要。6. 調(diào)侃的盡頭是一道關于注意力的選擇題6.1 一個可復用的四步閥門面對一張 Mermaid 圖不管是人畫的還是機器生成的我會用下面這個四步過濾器決定是否保留它。第一步這個結(jié)論用文字能說清楚嗎如果能就不強行畫圖。第二步這張圖只服務一個核心路徑嗎分支是否超過兩個刪掉一半節(jié)點后信息還成立嗎第三步合入倉庫前有沒有被一個項目之外的人看過他能否在 30 秒內(nèi)復述出這張圖的主路徑第四步未來讀者會不會因為這張圖而更省時間如果會留下如果不會刪掉。前兩步解決“圖畫得對不對”后兩步解決“圖在該項目里值不值得存在”。這個過濾器對純?nèi)藢懳臋n、半自動寫作、全自動產(chǎn)出都適用只是執(zhí)行方式不同。6.2 自動化的真正價值不是讓內(nèi)容變多而是讓內(nèi)容變得可迭代很多人把自動化創(chuàng)作理解成“生成更快、批量更大”。這個理解并不完整。自動化真正有價值的地方是它能快速產(chǎn)生候選內(nèi)容并且在系統(tǒng)發(fā)生變化時批量生成新的版本供人選擇。比如一個項目的架構(gòu)變了如果圖是用 Mermaid 寫的自動化可以快速更新候選圖然后讓人來決定哪些節(jié)點值得保留、哪些路徑需要突出。機器負責“做得快”人負責“選擇得對”這才是人機協(xié)作更健康的形態(tài)。如果反過來機器負責“選擇保留什么”人只負責“接受已經(jīng)渲染好的結(jié)果”那么項目會迅速進入一種失去重點的狀態(tài)。所有文檔都在增長所有圖都在更新但沒有一個人能說出整個項目最核心的路徑是什么。這是比“圖表風格相似”更值得警惕的事。6.3 風格背后其實是工程判斷力一次針對 Mermaid 渲染風格的調(diào)侃真正拿出來討論的不應該只是“圖好不好看”而是自動化創(chuàng)作軟件如何用更少的表達解決更多的問題。被記住的文檔風格通常不是因為它用了多高級的繪圖工具而是因為作者敢于放棄。放棄裝飾性的節(jié)點、放棄多余的箭頭、放棄“為了顯得完整而把所有內(nèi)容都放在一起”的沖動。下次再看到一大張來自自動生成流程的 Mermaid 圖別急著修改配色或調(diào)整連線。先刪掉一半節(jié)點試試。刪完之后如果它的信息仍然成立那張圖就活了刪完之后它頓時散架那它本來就沒有承載什么。這大概就是那句調(diào)侃真正想提醒我們的事。