1,100 條規則的紫微斗數引擎,工程做得比多數 AI 產品好

一個用 TypeScript 寫的中式命盤計算儲存庫,這週在 GitHub 上有 16,868 顆星。這比多數開發者工具一輩子拿到的還多,而主題是多數西方工程師會歸類在「不算軟體」的那一類。
有趣的部分不是主題。而是這個儲存庫的工程品質,比很多掛著「AI 產品」標籤出貨的東西更好。
ziwei-doushu 是一個開源的紫微斗數引擎,建立在倪海廈在天紀講座裡教的系統上。命盤完全在瀏覽器裡計算。沒有 API 金鑰、沒有模型、沒有推理。它是算術、查表,和 1,100 行格局規則。
而且它附了 768 張回歸命盤。
它到底算了什麼
如果你不熟悉這個領域,README 的能力表同時也是一份「這類計算會出錯的方式」清單。
真太陽時校正。時鐘上記錄的出生時間,不是那個地點的太陽時。引擎校正經度差加上均時差,讓一張在國土東邊排出的命盤不會差一個時辰。這是命理版的時區 bug,也是天真的實作第一個壞掉的地方。
1986 到 1991 年的中國日光節約時間。那個國家實行了六年日光節約時間,然後停止。引擎會偵測這個區間,但刻意不自動減掉那一小時——README 明確說,時鐘讀數由使用者確認,然後透過獨立的 clock-adjust.ts 轉換。那是正確的直覺。悄悄調整使用者的輸入,正是你產出「自信地錯誤」的命盤的方式。
閏月的四種慣例。各派對於閏月屬於前一個月、後一個月、按日切分,還是算自己一個月,意見不一。引擎把它做成設定,而不是選邊站。星曜亮度也一樣,不同流派——以及同一套商業軟體的不同版本——用不同的級距。支援七級,另外有一個較粗的三級分類作為顯示備援。
晚子時的換日。23:00 到 23:59 算隔天;00:00 到 00:59 算當天。如果有提供出生地點,判斷會用真太陽時,讓兩條規則保持一致。
在此之上是四化與飛星、十二神煞在先天盤與流年盤之間移動的安放,以及一套超過 1,100 條規則的格局庫——紫府同宮、日月並明、七殺朝斗等等。

測試就是論證
任何人都能宣稱自己的命盤引擎是對的。這一個公開了一套在每次 push 和 pull request 都跑的測試,而它檢查的清單是整個儲存庫資訊量最大的部分:
768 張命盤對照這套系統的鐵律。日光節約時間區間。立春的邊界——這個曆法裡年份更換的地方,也是幾乎每個實作都會差一的地方。紅鸞和天喜的安放。樣本命盤之間的時辰索引一致性。時辰索引的邊界條件。日期有效性。兩個四化落在同一個宮的情況。
那不是行銷清單。那是一份被每一項輪流咬過的人寫的清單。光是立春邊界,就會讓天真的實作在每一年、對每個二月第一週出生的人出錯。
安裝
三個指令:
git clone https://github.com/Renhuai123/ziwei-doushu.git
cd ziwei-doushu
npm install
可選 cp .env.example .env.local,然後 npm run dev。驗證是 npm run typecheck 跑完整的 TypeScript 檢查,以及 npm test 跑命盤引擎的回歸測試。
排盤或顯示命盤都不需要 API 金鑰,合盤也不需要。一切都在客戶端執行,對於一個由出生日期和出生地點建構出來的東西,這是對的選擇。
作者劃下的界線,以及為什麼這是 README 裡最誠實的東西
開源版不包含後端 API 路由。排盤、顯示命盤、合盤排盤全都在本地。但 AI 解讀端點——/api/interpret——和合盤分析端點沒有實作。
沒有這些,介面會平白地說,開源版不包含那個端點。而 README 補了一句,解決了大家一直開的問題:設定 API 金鑰不會讓那些功能動起來。Issue #30 之所以存在,就是因為使用者以為會。
那是一個不尋常的決定。容易的做法是出一個 stub,呼叫一個模型,產出聽起來合理的評論。但這個儲存庫是一台計算機,拒絕假裝自己是神諭。考慮到這個主題在網路上的存在有多少是自信的胡說,一個停在自己能計算的邊界上的工具,值得注意。
命名方式,以及為什麼讀起來像一個函式庫
程式碼是圍繞這門學問實際被教的方式組織的,這就是它可讀的原因。
lib/ziwei/algorithm.ts 存放排盤順序:安命宮、定五行局、安十四主星、安輔星、排大限與流年。constants.ts 存放天干、地支和星曜清單。sihua.ts 存放四化——祿、權、科、忌,包括飛星自化的情況。然後是格局庫和亮度表的獨立模組。
如果你懂這個主題,那個對應很明顯。如果你不懂,它還是讀得出來:常數、然後算術、然後規則、然後接近解讀的資料。領域不熟悉,結構卻是熟悉的,這就是好軟體的樣子——當它是由一個懂這件事、而不是懂這個趨勢的人寫出來的時候。
TypeScript 這個選擇也有關係。命盤是一棵宮位的樹,每個宮裡有星曜,被彼此引用的規則轉換。一個能表達「一個宮包含一組星曜,每顆有固定集合中的一個亮度等級」的型別系統,在編譯期就抓到一整類 bug,而這個儲存庫在做任何事之前先跑完整的型別檢查。對一個有這麼多列舉值的領域來說,那不是裝飾。
為什麼一個 AI 部落格要寫一套命理引擎
因為它是對現在多數 AI 產品怎麼被打造的一個乾淨反例。
這裡有一個系統,每個輸出都是確定性的,每條規則都能追溯到一個具名的流派,每個模糊的慣例都是一個設定開關而不是一個主張,而正確性由 768 個回歸案例強制。你問它同一個問題兩次,得到同一個答案。沒有東西被幻覺,因為沒有東西被生成。
然後是它明確不做的那部分:解讀。解讀層——需要判斷、不同執業者會有歧見的那部分——留給使用者,或留給另外實作的端點。
多數用語言模型建東西的團隊,都能從複製這個切分中受益。把能算的算準,並且明確說出解讀從哪裡開始。替代方案是一個對兩者之間的差別聽起來很權威的系統,而那正是這個儲存庫被設計來避免的失敗模式。
程式碼是 MIT。資料集是 CC BY 4.0。古典文本是公有領域。講師自己的話是採非商業授權,README 也這麼寫。這些全部都有記錄,比多數專案對爭議性小得多的素材做到的還多。
你不需要相信這個主題,也能從它的工程裡學到東西。那通常是一件做得好的東西的標記。