brainstem 引擎的三個設計決定

之前寫過 brainstem 是什麼:一個裝一次就能在任何私有目錄養第二大腦的知識圖譜引擎,程式碼在 github.com/NatChung/brainstem(MIT)。這篇講它開源前,我在引擎層踩定的三個工程決定。三個都不顯眼,但都承重——而且每一個都可以遷移到你自己的工具上。

一、會吸附私料的工具,資料不能跟它的公開 repo 同住

brainstem 最早的形狀是「clone 即腦」:引擎的 skills、腳本,跟我的筆記、lens 放在同一個 repo 根。用起來沒問題,直到要開源那一刻問題才現形——這個 repo 準備以 MIT 授權公開,但只要我繼續餵料,私人想法就跟著長進去。根因是引擎的根目錄同時放了 seed 內容,一個 repo 身兼「引擎」和「一顆腦」。

修法是把兩者拆開:引擎全域安裝,腦等於任何一個標了記號的私有目錄,引擎透過一個全域指標找到腦。驗收條件我寫得很硬:runtime 的任何環節,都不准依賴公開 repo 還在磁碟上——裝完就可以刪。

可遷移的判準:凡是工具會把使用者的私料養大,先畫清「程式」和「資料」的 repo 邊界。別讓 seed 內容把資料永遠釘進工具本體,不然開源那天就是資料外洩那天。

二、散佈選最笨的機制:複製加一個版本戳

引擎怎麼裝到使用者機器上?我評估過三條路:symlink 回開發 repo、做成平台 plugin、或者最笨的——把檔案複製到全域位置,加一個 VERSION 檔,升級就重跑安裝腳本覆寫。

我選了最笨的那條,而且是刻意的。symlink 看似方便,但它綁死「repo 必須還在磁碟上」,直接違反上面那條「裝完可刪」;plugin 綁平台,skills 就只能活在那一個 runtime 裡。複製什麼都不綁:skills 可以進任何 runtime 的目錄、CLI 是純 shell 到處跑,未來要支援別家 agent 環境,成本趨近於零。

可遷移的判準:散佈機制選最笨、最不綁的那個。進階手法各自綁住一個前提——repo 在不在、跑在哪個平台;複製加版本戳,什麼前提都不需要。

三、同一個問題,只准有一個解析器

「腦在哪」這個問題,早期的 brainstem 有三套各自的答案:skills 自己往上找記號檔、doctor 腳本讀環境變數再退回自己的目錄、體檢腳本乾脆寫死在引擎路徑裡。三套答案平常看起來一致,但寫死的那套等於把腦永遠釘在引擎目錄——這正是引擎和腦分離不掉的技術根因。

修法是收斂成一支解析器:固定的優先序(環境變數、往上找記號、全域指標),所有元件都 import 同一支,skills 改成呼叫同一個 CLI 命令。之後「腦在哪」在全系統只有一個答案。

可遷移的判準:同一個問題若有 N 處各自實作,它們的差異遲早變成 bug。收斂成單一真相源,差異就結構性消失——不是靠紀律維持一致,是讓不一致沒有地方發生。

共同的主題

三個決定其實是同一件事:把邊界畫清楚——程式和資料的邊界、引擎和平台的邊界、解析和使用的邊界。畫清楚之後,很多本來要靠自律守住的規矩,變成結構上根本違反不了。工具如此,harness 也如此。