廢文雜談 | 工程屍 FlyPie 的異想世界

我想壟斷我自己 (I Want to Monopolize Myself)

August 30, 2026

閃亮症候群工程屍

我知道這個描述有點ㄎ一ㄤ，不過請聽我娓娓道來。

軟體壟斷 (Monopoly)

眾所周知，軟體壟斷是存在的，例如：Google 電子郵件帳號、Android 手機、微軟作業系統、臉書社交平台...。

使用軟體本身沒有問題，問題在於閉源軟體、或是軟體與平台實際上被特定的商業實體所掌控，形成供應商鎖定，例如：微軟在作業系統上強推 AI 功能、TPM 硬體；又或是 Google 在 Android 上強推集中化且侵入性的政策...。消費者總是處於權益受損的被動方。

因此這世界上有一些人是十分認真看待這件事的，它們追求去中心化、自由、平等的軟體使用體驗，我作為開源軟體的支持者多少是認同這種理念的，但是有時候更多是現實的無奈。

比如說臉書，現實就是我國有很高的基數在使用 Meta 體系的社交平台（臉書、IG、脆），而這種平台為了避免資訊外流，不僅 SEO 不友善，大部分資料都藏在 API 之後，還透過 EULA (End-User License Agreement) 保護，所以現實就是不使用就容易和周遭的人脫節。

又比如 Gmail，雖然 SMTP (Simple Mail Transfer Protocol) 本身是開放的，想要架設 Email 伺服器本身很簡單，但是想要跟其他人的 Gmail 通訊，還需要滿足 SPF、DKIM、DMARC、DNS...等等設定，即使滿足設定也要「養」IP 和 Domain 的信譽才能避免信件被這些寡頭過濾掉。

壟斷抽象層

好了，所以我使用這些商業軟體或平台是一個既定事實，並且也有需求而仰賴著它們。

事實是，受開源軟體所賜，大部分商業軟體或平台都有開源替代方案，真正的問題是這些軟體不會自己架好給人使用，而且軟體的品質參差不齊，需求不見得被滿足、bug 不見得有人修。不過沒關係，先讓我們假設有一個公司存在，它只使用開源軟體，然後我可以直接使用這個公司的服務而無須自己煩惱維護軟體的細節。

於是一個比 Google 更邪惡的公司誕生了，因為現在我使用的所有（開源）服務都集中在這間公司身上，形成壟斷。

這件事情也可以換一個描述方式：假設一個諸如保護傘公司、荒坂公司、東亞重工這種虛構作品中虛構的壟斷企業，然後假設我所使用的所有軟體或平台都來自這個企業，而不是來自 Google 或 Meta...。然後使用開源軟體來「實做」這個虛構的「壟斷抽象層」。

我壟斷我自己

開源軟體只是實做這個抽象層的要素之一，它依然需要勞動力跟決策領導者才能運作，於是我作為董事或員工進入這個企業。從而形成了「我壟斷我自己」的傑作。

這個架構能夠解決另外一個問題，如果我單純的以 side project 的方式維護 homelab，我實際上很難區分我作為自然人的休息資源以及我投入在 side project 上本質屬於勞動的資源，資源包含時間和資本，透過這個虛構的企業，我便能把自己作為消費者以及法人生產者的資源區分開來。

曌銕重工

這個蠢主意其實不是剛想到的，而是已經醞釀一陣子了，為了那個「虛構的法人」我甚至已經準備了：

曌銕重工 (Stellar Cation Heavy Industries) 組織章程（草案）

Details

第一章總則

本組織名稱為曌銕重工(以下簡稱本會)。
1. 讀作「ㄓㄠˋㄊ一ㄝˇ」。
2. 英文名稱為 Stellar Cation Heavy Industries。
本會不以獲取商業營利為最終目的，亦不進行盈餘分配；其內部治理與成員權利義務悉依本章程之約定。
本會為開源、技術探索與自由創作之非營利虛擬實體。
本會以地球本體、近地空間（Near-Earth Space）及地月系統（Earth-Moon System）之全部宙域為核心組織與治理區域。
本會以維持運作之伺服器設備與資訊基礎設施所在之虛擬網路空間為核心會址。鑑於基礎設施之物理位置具備動態移轉性，本會不設實體會址，其行政作業與通訊通聯之核心網際網路平台，授權由理事會決議並公告之。
本會之任務如下：
1. 虛擬法人實體之營運與技術與非技術項目研究與開發之管理。

第二章會員

本會會員分下列一種：
1. 個人會員：凡贊同本會宗旨之自然人，填具入會申請書，經理事會審定通過，並繳納入會費後，為個人會員。
2. 團體會員：凡贊同本會宗旨之外部專案機構或團體，填具入會申請書，經理事會通過，並繳納入會費後，為團體會員，並推派自然人代表一人行使權利。
會員(會員代表)有違反本章程或不遵守會員大會決議時，得經理事會決議，予以警告或停權處分，其危害團體情節重大者，得經會員大會決議予以除名。
會員有下列情事之一者，為出會：死亡、喪失會員資格者、或經會員大會決議除名者。
會員得以書面並敘明理由向本會聲明退會。
會員經出會或退會，已繳納之各項費用不予退還。
會員(會員代表)有表決權、選舉權、被選舉權與罷免權。每一會員為一權。
會員有遵守本會章程、決議及繳納會費之義務。連續一年未繳納會費者，視為自動退會。

第三章組織及職權

本會以會員(會員代表)大會為最高權力機構；理事會為執行機構。
會員(會員代表)大會之職權如下：
1. 訂定與變更章程。
2. 選舉或罷免理事。
3. 議決入會費、常年會費之數額及方式。
4. 議決年度工作計畫、報告及預算、決算。
5. 議決會員(會員代表)之除名處分。
6. 議決財產之處分。
7. 議決團體之解散。
8. 與會員權利義務有關之其他重大事項之議決。
本會置理事一人，由會員(會員代表)選舉之，分別成立理事會。遇理事出缺時，依序遞補，以補足原任者餘留之任期為限。理事之當選名次，依得票多寡為序，票數相同時，以抽籤定之。
理事會之職權如下：
1. 議決會員(會員代表)大會之召開事項。
2. 審定會員(會員代表)之資格。
3. 選舉或罷免常務理事、理事長。
4. 議決理事、常務理事或理事長之辭職。
5. 聘免工作人員。
6. 擬定年度工作計畫、報告及預算、決算。
7. 其他應執行事項。
理事會置常務理事一人，由理事互選之，並由理事就常務理事中選舉一人為理事長。理事長對內綜理會務，對外代表本會，並擔任會員(會員代表)大會、理事會主席。理事長應視會務需要到會辦公，其因故不能執行職務時，應指定常務理事一人代理之，不能指定時，由常務理事互推一人代理之。
理事之任期十年，連選得連任，理事長之連任，不設上限。
理事為無給職。
理事有下列情事之一者，應即解任：
1. 喪失會員(會員代表)資格者。
2. 因故辭職經理事會決議通過者。
3. 被罷免或撤免者。
4. 受停權處分期間逾任期二分之一者。
本會置總幹事(或秘書長)一人，其他工作人員若干人；依資格條件遴選工作人員，提經理事會通過後聘僱之，解聘時亦同。
本會理事得兼任會務工作人員。
本會設立分支機構，其組織簡則由理事會擬定，載明設立依據、組成、任務、經費來源等，提經會員（會員代表）大會通過後行之。
本會得由理事會聘請名譽理事長一人，名譽理事一人，顧問一人(均為義務職)，其聘期與理事之任期同。

第四章會議

會員(會員代表)大會，分定期會議與臨時會議二種，由理事長召集，召集時應於十五日前以書面或電子通訊通知之。定期會議每年召開一次；臨時會議於理事會認為必要，或經會員(會員代表)五分之一以上之請求時召開之。會員（會員代表）大會得以視訊會議或其他經理事會公告之方式召集之，簽到及表決方式則配合電子化設備功能辦理。但涉及選舉、補選、罷免事項，應以實體或具備身分驗證之特定非視訊集會方式辦理。
會員(會員代表)不能親自出席會員(會員代表)大會時，得以書面或電子授權委託其他會員(會員代表)代理，每一會員(會員代表)以代理一人為限。
會員(會員代表)大會之決議，以會員(會員代表)過半數之出席，出席人數過半數或較多數之同意行之。但下列事項之決議以出席人數三分之二以上同意行之：
1. 章程之訂定與變更。
2. 會員(會員代表)之除名。
3. 理事之罷免。
4. 財產之處分。
5. 團體之解散。
6. 其他與會員權利義務有關之重大事項。
理事會每一個月召開一次，必要時得召開臨時會議。前項會議召集時除臨時會議外，應於七日前通知，會議之決議，以理事過半數之出席，出席人數過半數或較多數之同意行之。理事會議得以視訊會議或其他經理事會公告之方式召集之，簽到及表決方式則配合電子化設備功能辦理。但涉及選舉、補選、罷免事項，應以實體或具備身分驗證之特定非視訊集會方式辦理。
理事應親自出席理事會議，不得委託他人代理；連續二次無故缺席，視同辭職。
（本條因原屬陳報主管機關之程序，於虛擬法人架構下無適用對象，故予以移除，保留編號以維繫章程結構）

第五章經費及會計

本會經費來源如下：
1. 入會費：會員入會時，應一次繳納新臺幣100元。
2. 常年會費：每年新臺幣500元。
3. 會員捐款，得區分為一般經常性捐款，或針對特定技術、創作項目之「專門指定捐款」。
4. 委託收益。
5. 基金及其孳息。
6. 其他收入。
本會會計年度自每年一月一日起至十二月三十一日止。
本會每年於會計年度開始前由理事會編造年度工作計畫及收支預算表，並於會計年度終了後三個月內由理事會編造上年度工作報告、會計報告，連同當年度工作計畫及收支預算表，提經會員(會員代表)大會通過。會員(會員代表)大會因故未能及時召開時，可先經理事會通過，事後提報大會追認。
本會於解散後，剩餘財產之歸屬，由會員(會員代表)大會決議處置之。

第六章附則

本章程未規定事項，由理事會依本會宗旨另訂內部規範辦理。
本會辦事細則，由理事會訂定之。
本章程經會員(會員代表)大會通過後施行，變更時亦同。

組織章程是拿「臺北市社會團體章程草案範例」改的，有趣的是命名時我其實面臨了抉擇，因為要法人化，因此不能使用情感連結太強的名稱，必須要是可割可棄的存在，不然到時候像賈伯斯被踢出去之後會很惱火，這麼一想，突然能理解為什麼一堆公司的名字都這麼菜市場了。

除了抽象的組織章程，落地方面，我也準備將個人的 Side Project 重新編制方式：

曌銕重工實體與專案檢索表建置與維護作業辦法（草案）

Details

目的
- 為規範本會行政助理於建置、更新「外部實體-專案檢索表」時之作業流程，確保資料登錄之準確性與即時性，以利日後行政查核時能快速透過實體名稱反查專案流水號，特訂定本辦法。
管理職責
- 本辦法之主管機關為理事會，負責外部實體識別碼之核准、表單結構之變更及不定期抽檢。本會行政助理為「外部實體-專案檢索表」之直接維護與登錄人員，應負責日常資料之依據核准登錄、變更追蹤與定期備份。
檢索表建置媒介與存取權限
1. 檢索表應建置於本會指定之試算表（Spreadsheet）或資料庫系統中。
2. 本表之「編輯權限」僅限行政助理與理事會成員；本會其餘個人會員與團體會員僅開放「檢視（唯讀）權限」。
實體識別碼之編發與核發權責
1. 實體識別碼由五碼組成，採「類別英文字母（一碼）」與「流水號（四碼）」之組合。
2. 類別英文字母定義如下：
  - 「C」開頭：代表具備獨立法人資格之公司、行號、商業實體或官方機構（如 C0012）。
  - 「P」開頭：代表自然人、個人委託者或獨立開發者（如 P0005）。
  - 「G」開頭：代表外部開源社群、非正式組織、DAO 等外部協作群體。
  - 「I」開頭：代表本會內部之特定興趣小組（Interest Group）、委員會、或本會自發性、無外部委託對象之自有研發專案（RD 性質）。
  - 「U」開頭：代表未知或無法考證之歷史實體。
3. 實體識別碼之核發遵循「唯一性」原則。同一識別碼一經核發即具備唯一性，不得重複核發予不同實體，亦不得刪除。
4. 核發程序：
  - 實體或內部單位首次與本會建立合作或立案關係時，由行政助理依時間先後順序及本條第二款之分類預編識別碼，提報理事會審查。
  - 實體識別碼須經主管機關（理事會）審查並正式核發後，始生效力。
檢索表之常態登錄與建表作業
1. 行政助理於接獲以下核准通知後，應將相關資料登錄至檢索表：
  - 通知一：主管機關（理事會）正式核發新「實體識別碼」之通知。
  - 通知二：依《研發專案字號編製作業要點》核准新「研發專案字號」之立案通知。
2. 檢索表之表頭欄位應嚴格遵循以下結構建置：
  1. 【實體識別碼】：填寫經理事會正式核發之五碼代碼。
  2. 【實體全稱】：填寫公司法人登記全名、組織官方名稱、社群群體正式名稱或個人真實姓名。
  3. 【常用別名/社群ID】：填寫網路常用暱稱、Discord ID、GitHub 帳號或機構縮寫（如：Stellar Cation Heavy Industries 加註 SCHI），以利多元關鍵字搜尋。
  4. 【完整專案字號】：必須填寫包含後綴的完整字號（如 SCHI-2026-001-ODM）。
  5. 【專案流水號（核心）】：單獨列出專案核心流水號（如 2026-001），作為核心檢索錨點。
  6. 【專案性質】：依《研發專案字號編製作業要點》第三條第四款之分類，填寫 RD、ODM 或 OEM。
  7. 【專案名稱】：填寫該專案之正式名稱或開發代號。
  8. 【立案日期】：填寫專案正式啟動或合約簽署之西元日期（格式：YYYY-MM-DD）。
  9. 【結案狀態】：分為執行中、已結案、暫停、註記作廢。
歷史專案與實體之補登程序
1. 針對本會成立前或本辦法實施前之歷史舊案，行政助理應協同專案負責人考證歷史資料，提出溯及補登申請，經理事會審查通過後，於一個月內完成「實體-專案檢索表」之登錄。
2. 若歷史專案之委託或合作對象已無法考證，經理事會核准後，【實體識別碼】欄位依序配發「U」開頭之未知實體代號（如 U0001），【實體全稱】欄位則註明「未知或無法考證之歷史實體」。
行政檢索操作指引（查找特定專案流水號）
- 行政助理或會內成員於日後需要查找特定專案資訊時，應依下列步驟進行操作：
  1. 步驟一：開啟「外部實體-專案檢索表」，使用快捷鍵（如 Ctrl + F）開啟搜尋功能。
  2. 步驟二：輸入欲查找之實體名稱、別名或社群 ID。
  3. 步驟三：定位至該實體之資料列，即可直接於同列之【專案流水號（核心）】或【完整專案字號】欄位中，查得該特定專案的流水號。
  4. 步驟四：若欲查找該實體歷年來的所有合作，可直接對【實體識別碼】欄位啟用試算表之「篩選（Filter）」功能，即可一鍵列出該實體名下的所有歷史專案。
資料維護與更正機制
1. 實體識別碼與專案字號一經核發並登錄，行政助理不得任意刪除或變更。
2. 倘專案後續發生撤案或終止，助理應依據理事會之決議或通知，將【結案狀態】欄位更改為「註記作廢」，並於備註欄說明原因。
3. 外部實體或內部單位更名時，助理應檢具更名證明文件提報理事會，經核准後更新【實體全稱】欄位，但原有的【實體識別碼】與其對應之歷史專案流水號一律保持不變，以維持歷史資料的真實性。
施行
- 本辦法自發布之日起實施，修改時亦同。

曌銕重工專案字號編製作業要點（草案）

Details

主管機關
- 本作業要點主管機關為理事會。
專案立號義務
- 凡本會之研發專案，均應依本要點之規定編製專案字號，以資識別、統計及檔案分類管理。
字號組成格式
- 專案字號由「組織代碼」、「年份」、「年度序號」與「專案性質」組合而成，區分為四段式結構，各碼間以半形連接號（-）銜接。其標準格式如下：
  - SCHI-<年份>-<年度序號>-<專案性質> （範例：SCHI-2026-001-AD）
- 各區段定義如下：
  1. 組織代碼：固定為「SCHI」（Stellar Cation Heavy Industries），用以標示本會所屬專案。
  2. 年份：採西元紀年，以四位數計（如 2025），用以標示專案立案之年度。
  3. 年度序號：採三位數流水號（自 001 開始），不分專案性質，一律依專案申請登記之先後順序，依序編發。
  4. 專案性質：用以識別專案之運營模式與法律責任分類，分為以下四類：
    - RD（Research & Development）：本會自有之核心技術探索、開源專案與自由創作項目。
    - ODM（Original Design Manufacturer）：本會為主導規劃、設計並開發，但智慧財產權與實體成果歸屬外部委託方之專案。
    - OEM（Original Equipment Manufacturer）：純屬承接外部明確規格、按圖施工之純技術勞務代工項目。
    - AD（Artistic Design）：凡屬本會自製或受託承接之視覺傳達、平面設計、LOGO識別、多媒體美術創作等美術設計類項目。
序號更易與管理機制
- 專案字號之年度序號遵循「每年更易一次」原則。每逢新結算年度（跨年）時，號碼應重新起算，自 001 開始編列，不得延續上一年度之流水號。
- 專案字號之前置核心「SCHI-<年份>-<年度序號>」一經核發，即具備唯一性。同一年度序號不得重複核發予不同專案，亦不得因末端「專案性質」之不同而重複遞補使用（例如：已核發 SCHI-2025-001-RD 後，該年度即不得再出現 SCHI-2025-001-ODM）。倘專案後續發生變更、暫停或終止（撤案），該字號應予保留或註記作廢，不得刪除。
歷史專案之溯及編列與常態補登機制
- 本要點實施前已存在、啟動或結束之歷史研發專案，應追溯納入本字號編製體系。
- 歷史專案之字號編列原則如下：
  1. 年份認定基準：一律以該專案當初「實際發起、首次程式碼提交（Commit）、公開發表或首度執行」之西元年份為准。
  2. 歷史序號整編原則：歷史溯及專案之補登，於各該歷史年度內，仍應自 001 開始依實際發起時間之先後順序依序編列。於本要點通過後六個月之整編期內，專案管理人員得打破既有登記順序，對同一歷史年度之專案流水號進行調整與插編，以還原真實歷史排序。
  3. 外部專案與歷史代工移轉認列：
  - 凡個人會員或團體會員於入會前（或本會成立前）所獨立發展或承接之舊有項目，有助於彰顯成員技術履歷與本會歷史貢獻者，得申請追溯認列為本會歷史專案。
  - 前項歷史專案經理事會審查通過後，依其最初發起年份發給專案字號，並依第三條第四款之標準認定其專案性質，據以配發 RD、ODM 或 OEM 之性質尾碼。
  1. 常態補登與歷史序號凍結限制：本要點通過實施屆滿六個月後，歷史專案之整編期即告結束，該歷史年度已存在之流水號序位予以凍結，不得再進行任何因應歷史排序之插編或變更。整編期結束後，會員仍得隨時申請補登歷史專案，主管機關應依其歷史年份予以認列，惟其流水號應承接於該歷史年度既有最後一號之後，依申請時間順序遞增編列。

本來是想把手邊的三台舊筆電用 Talos 拼成 Kubernetes 叢集運行 email 和 Kimai 作為曌銕重工的第一號財產，選擇的理由很簡單：

email 可以說是數位基礎建設，雖然跟 ID Provider 是兩回事，但是實務上它就是 ID 之源，其他帳號的密碼都可以忘，就是 email 的不行。對我而言它應該已經像是郵政服務一般的存在了，政府沒有在這方面努力對我而言算是十分的不解，不過這又是另外一個話題了。
Kimai 是用來「打卡上班」的基礎設施，也可以說是 HR 的自動化基礎設施，畢竟人力資源是生產要素基本中的基本。

至於這個規劃為什麼拖延了許久？說來話長。

原本選擇筆電叢集的原因之一是基於「這輩子大概跟（機架式）伺服器沒什麼緣份」的前提定調的，然而最近卻因緣際會跟它結了緣，~~現在上班都會有伺服器用它的風扇聲在我腳邊喵喵叫~~。總之，因為這樣我不得不經歷思想鬥爭：繼續往筆電叢集的道路前進，還是考慮比較能和職業結合的機架式伺服器體系。

另一方面是因為搬了家，沒有管理室幫忙收包裹的情況購買鐵力士層架這種大型物品簽收會變得很麻煩，目前房間又沒有比較合適的空間可以安置這三台筆電構成的叢集。

除此之外亦有來自週邊影響的「AI 焦慮」，不得不把一些精力和時間分配給相關主題...。

結論

總之，看到這裡，你應該對於「我想壟斷我自己」有比較具體的想像了。至於它究竟是一個神經病得幻想還是實際上有點意義的概念？

之後我們或許就知道了。

Agentic 網路訪問雜記

August 24, 2026

Wei Ji

閃亮症候群工程屍

最近開始試著使用 CLI/TUI 的 LLM Agent 工具，選擇了 crush。

然後想把之前在 Local Deep Research 的使用習慣轉移過來，原因是 Local Deep Research 彈性略差，加上它的主要賣點之一是研究內容在伺服器端是加密的，但是這個設計造成 UX 上的缺陷：光是開啟清單頁面都需要運行解密而造成網頁會花不少時間在等待解密完成。

把 Local Deep Research 的提示詞抽出來隨便搓了一個 Skill:

https://github.com/FlySkyPie/simple-research-skills

但是發現了一個問題：

恩？為什麼我架的 SearXNG 看起來都搜不到東西？是 MCP 壞掉了嗎？

原來是被搜尋引擎擋了。

但是 crush 的內建工具為什麼可以運作？

翻了一下程式碼發現它是使用鴨鴨 (DuckDuckGo)：

有趣的是，當時 DuckDuckGo 算是第一個在我的 SearXNG 會擋機器人的搜尋引擎，因此它很早之前就被我從 SearXNG 的設定中停用了。

前情提要

請見：Biomes 研究筆記 7

Zod Schema

Biomes 的 shared 模組中定義了很多資料，當中不少檔案是超過 500 行的，並且不少有循環仰賴：

export const zBiscuitAttributeAssignment = z.lazy(
  memoize(() =>
    z.discriminatedUnion("kind", [
      zParentTrayAssignment,
      zConstantAssignment,
      zReferenceAssignment,
      zUnassignment,
      zInferenceAssignment,
    ])
  )
) as ZodType<BiscuitAttributeAssignment>;

export const zParentTrayAssignment = z.object({
  kind: z.literal("parentTray"),
  to: zBiscuitAttributeAssignment,
});

為了對仰賴關係有更細的理解，避免太多東西被 import，而把定義資料檔案拆成獨立的檔案，然而循環仰賴會造成 runtime error。

加上很多型別是用 Zod 的 schema 本身進行推論的：

export const zShotMetadata = z.object({
  coordinates: zVec3f,
  cameraLookAt: zVec3f.optional(),
  shotInMinigameId: zBiomesId.optional(),
  shotInMinigameInstanceId: zBiomesId.optional(),
  shotInMinigameType: zMinigameType.optional(),
});

export type ShotMetadata = z.infer<typeof zShotMetadata>;

造成仰賴 type 的時候依然會 import 到實作，加劇了循環仰賴的問題。

由上而下的嘗試

五月份的時候有 Biomes 的內部人員修復了素材包缺失的問題，原本該專案自動化腳本會去 GCP 下載預先打包的素材包，但是該資源已經無法被訪問，修復的內容就是在 GitHub 上 release 一份，並且更新自動化腳本。

在這之前我是以由下而上，從仰賴鏈末端的基本元件慢慢重構與編譯往上組合的。既然原始團隊的人已經做了一些修復並且聲稱自己測試過可以運行，我就試著由上而下跑跑看吧。

Bob

Biomes 的程式碼可以看到不少名為 Bob 的東西：

├── deploy/
│   └── k8/
│       └── services/
│           └── bob.yaml
├── Dockerfile.bob
├── scripts/
│   └── deploy_bob.sh
└── src/
    └── server/
        └── bob/

因為最後是以 Docker 的形式存在，K8s 編排內也有，我之前一直以為這是遊戲本體的內部代號，最近仔細看了一下實作才知道它是手搓的自動化程式，被擬人化為一個名為 Bob 的 Agent。

這個程式在做的事情就是輪詢 Git、運行 Bazel 與 Docker (DnD)、推送映像檔、觸發 Discord 通知...等。給人一種「不知道 CI/CD 為何物的前端仔用 Typescript 搓出來的東西」的感覺。

GCP 重度仰賴

程式運行後會被 GCP/Firebase 的鑑權擋住，仔細查看程式碼會發現實作高度耦合 BigQuery、Firestore、GCP Storage、App Engine...等 Google 的服務。

幾乎可以想見該團隊被微軟體系的 OpenAI 收購之後會有什麼樣的衝擊。

過期的進入點

調查 Dockerfile.bob 和 Dockerfile.biomes 的建構流程會發現明顯有設計 Next.js 和 Webpack 的建置流程。

但是調查 K8s 設定會看到諸如這樣的內容：

      containers:
        - image: us-central1-docker.pkg.dev/zones-cloud/b/biomes:devin-deploy-2
          name: biomes
          args:
            - '-r'
            - ts-node/register
            - src/server/gaia_v2/main.ts
            - '--bikkieCacheMode'
            - redis
            - '--biscuitMode'
            - redis2
            - '--chatApiMode'
            - redis
            - '--firehoseMode'
            - redis
            - '--serverCacheMode'
            - redis
            - '--storageMode'
            - firestore
            - '--worldApiMode'
            - hfc-hybrid
            - '--simulations'
            - restoration
            - lifetime
            - ore_growth

所有微服務都是不經過建置，直接用 Typescript 運行的。由此可知程式碼內部有嚴重的割裂，不同時期的進入點同時存在，可能還有不少類似的廢棄程式碼存在。

小結

由上而下大概是走不通的路線，因為必須要建立完整的 GCP 專案以及完整的 K8s 服務簇才有可能把程式跑起來，跟 GCP 的仰賴又有嚴重耦合，很難透過簡單的重構抽換成其他替代微服務。

OpenBMC 的歷史

July 11, 2026

Wei Ji

閃亮症候群工程屍

最近在學習 OpenBMC，於是爬了一下它的歷史，有點意外跟傳說中的 Gentoo 扯上關係。年份僅供參考，只是用來做相對時間順序的比較之用。

FreeBSD Ports collections，於 1994 年發布。
Portage 是 Gentoo 的包管理器，Gentoo 於 2002 年發布，高度參考 FreeBSD 的 Ports。
Linux Foundation 在 2010 年宣佈 Yocto；2011 正式啟動。
OpenEmbedded 社群起源於 2003 年，在 2011 年建立 OpenEmbedded-Core 與 Yocto 合作。
BitBake 由 OpenEmbedded 開發，於 2004 年釋出，啟發自 Gentoo 的 Portage。
2015 年 IBM 使用 Yocto 建立 OpenBMC 專案。
2018 年 Linux Foundation 建立了OpenBMC 計畫，並繼承 IBM 時期的技術棧。

(其他補充野史)

Linux From Scratch 1999 年初版。

補充

有些人可能會困惑為什麼我要特別提及 Linux From Scratch 跟 Gentoo 兩個跟 OpenBMC 沒有直接關聯的東西。

大部分人使用應用程式都是直接從某個地方下載執行檔然後使用，也就是預建置 (pre-build) 二進制檔案，Linux 的大部份發行版也是如此，然而 Open source 的圈子內有一種概念：

我沒看到原始碼，我不放心。

所以 Gentoo 的邏輯就是「所有東西都從原始碼編譯的 Linux 發行版」。

Linux From Scratch 定位則比較像是教科書，讓人更了解如何自己親手操作獲得 Linux，但是歷史悠久，因此後進的 Linux 使用者即便沒有親自動手做一遍也會有所耳聞。

所以「從 source 編譯 Linux」這件事情對我而言具有神聖的色彩，感覺是只有真正的太古神獸或是大佬才知道的事情。

然而入職的第一周，「恩？你說我剛剛已經從頭編譯一個 Linux 了？」。

另外，如果仔細觀察，會發現每一個企劃發起的時間都比它實際使用的工具來得近代；換句話說，這些計畫都沒有自行開發一套解決方案，而是直接使用已經存在的解決方案進行統整。

雖然經常覺得自己站在巨人的肩膀上，但是即便是這些巨人似乎也是站在其他巨人的肩膀上呢。

前情提要

最近在寫一些小工具，涉及比較敏感的資料，所以不能直接用雲端的 LLM，要用地端/本地的 LLM 處理。過程中遇到一點問題想記錄下來，但是背景有點複雜，建議先閱讀前一篇文章：

佈署 LLM 的方法 (2026-06-24)

預計開發的小工具是這樣的：

透過 inotify 偵測特定資料夾（我是用 Python 的套件 watchfiles）。
使用 GNOME Document Scanner 將我從 EPSON ES-50 掃描的信用卡簽單 pdf 丟進該資料夾。
檔案的變化事件觸發歸檔作業。
先用 OCR 抽取簽單資訊。
再用 LLM 根據嵌端資訊推論歸檔路徑與檔名。
完成歸檔(例如指令路徑：YYYY/MM/YYYY-MM-DD_{STORENAME}_{AMOUNT}NTD.pdf)並刪除原始檔案。

不過隨著佈署 LLM 和 OCR 的過程中，謎團越來越多，我只好中止開發先來搞清楚究竟是怎麼回事。

無線網路瓶頸

因為我的對外網路是（有限流方案） 4G 無線網路，除了下載速度很感人以外，根據經驗從 Docker Hub 拉取超過 1 GB 的映像檔很高機率會失敗，像這樣：

$ podman pull ghcr.io/ggml-org/llama.cpp:full-vulkan-b9776
Trying to pull ghcr.io/ggml-org/llama.cpp:full-vulkan-b9776...
Getting image source signatures
Copying blob 4f4fb700ef54 skipped: already exists  
Copying blob d1f56e4c7f2f skipped: already exists  
Copying blob d4a637e5a2c3 [=========>----------------------------] 130.0MiB / 497.0MiB | 458.8 KiB/s
Copying blob 534ac9e261fe done   | 
Copying blob d2bfdcbbb65a done   | 
Copying blob a92b05b64059 [===================>------------------] 120.0MiB / 223.3MiB | 105.4 KiB/s
Copying blob 81e2f2053c8f skipped: already exists  
Error: copying system image from manifest list: writing blob: storing blob to file "/var/tmp/container_images_storage936046123/2": happened during read: Digest did not match, expected sha256:a92b05b640591907c483d83fccf883b9f5d2b4d90369cd44cca5be58bbf7ea8e, got sha256:38656550ac584269f4bff1c74b238fea1d77c997d8439b484f75d803e7952012

llama.cpp 越來越胖了

原本使用 llama.cpp 的原因之一就是它比 ollama 瘦很多，很適合作為微服務使用，不過最近觀察到它越來越胖了：

$ podman images | grep llama.cpp
ghcr.io/ggml-org/llama.cpp              server-vulkan-b9755    40547717e769  2 days ago     905 MB
ghcr.io/ggml-org/llama.cpp              server-vulkan-b9737    274d563f216f  3 days ago     905 MB
ghcr.io/ggml-org/llama.cpp              server-vulkan-b9102    74d080b604c3  6 weeks ago    538 MB
ghcr.io/ggml-org/llama.cpp              server-vulkan-b8496    33a2ea3a7ef4  3 months ago   530 MB
ghcr.io/ggml-org/llama.cpp              server-vulkan-b8248    954707a036be  3 months ago   502 MB
ghcr.io/ggml-org/llama.cpp              server-vulkan-b8234    4af8b883a4d8  3 months ago   501 MB
ghcr.io/ggml-org/llama.cpp              server-vulkan-b7129    35763dc5caad  7 months ago   428 MB

所以我有點擔心它會在不久的將來觸及到我的網路環境極限。無線路由器的升級計畫以及調高無線網路資費方案已經排入待辦事項。

Gemma 4 很肥

想說現在是 2026 年了，試著用用看性價比評價很高的 Gemma 4 看看，但是即便是 Q8_0 量化的 gemma-4-E2B-it 也有 5GB 左右。

後來試著抓了 ggml-org/SmolLM3-3B-GGUF 來用，Q4_K_M 只要 2GB 左右，但是沒開 thinking 的話會笨笨的，連「strawberry 有幾個 r」都會回答錯...

curl Post

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "To find the number of r's in the word \"strawberry,\" let's break it down letter by letter:\n\ns-t-r-a-w-b-e-r-r-y\n\nNow, we can look for the letter 'r':\n\n1. The first 'r' appears at the third position.\n2. The second 'r' appears at the eighth position.\n\nSo, there are two 'r's in the word \"strawberry.\""
      }
    }
  ],
  "created": 1782281452,
  "model": "SmolLM3-Q4_K_M.gguf",
  "system_fingerprint": "b8234-213c4a0b8",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 89,
    "prompt_tokens": 82,
    "total_tokens": 171
  },
  "id": "chatcmpl-dQKDcL7Torw1Y2hGtyKJr9OtD7L0lpHM",
  "timings": {
    "cache_n": 81,
    "prompt_n": 1,
    "prompt_ms": 98.934,
    "prompt_per_token_ms": 98.934,
    "prompt_per_second": 10.10774860007682,
    "predicted_n": 89,
    "predicted_ms": 6249.039,
    "predicted_per_token_ms": 70.2139213483146,
    "predicted_per_second": 14.242189879115813
  }
}

開了 reasoning 可以改善這個問題，不過因為輸出的 token 量變多，所以反應時間會變長：

curl Post

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The word **\"strawberry\"** contains **3** instances of the letter **\"r\"**. \n\nBreaking it down:\n- **Position 3**: \"R\"\n- **Position 8**: \"R\"\n- **Position 9**: \"R\"\n\nSo the total number of r's is **3**. \n\n**Answer:** 3",
        "reasoning_content": "\nOkay, let me try to figure out how many times the letter 'r' appears in the word \"strawberry.\" First, I need to write out the word and look at each letter one by one. Let me start by spelling it out: S-T-R-A-W-B-E-R-R-Y. \n\nAlright, starting from the beginning, the first letter is 'S'. Not an 'r'. Next is 'T', still not 'r'. Then the third letter is 'R'. So that's one 'r'. Let me keep going. After the 'R', we have 'A', then 'W', 'B', 'E', and the next letter is another 'R'. So that's the second 'r'. Then there's another 'R' right after that, making it the third 'r'. \n\nLet me double-check. The word is S-T-R-A-W-B-E-R-R-Y. Breaking it down:\n\n1. S\n2. T\n3. R\n4. A\n5. W\n6. B\n7. E\n8. R\n9. R\n10. Y\n\nSo positions 3, 8, and 9 are 'R's. That would make three 'r's in total. Wait, is that right? Let me count again. Starting from the first letter:\n\n1. S\n2. T\n3. R (1)\n4. A\n5. W\n6. B\n7. E\n8. R (2)\n9. R (3)\n10. Y\n\nYes, that's three 'r's. Did I miss any? Let me visualize the word again. \"Strawberry\" – maybe there's a different way to spell it? No, the correct spelling is S-T-R-A-W-B-E-R-R-Y. The 'r' after the 'w' and the two after the 'e' make three. I don't see any other 'r's in there. So the answer should be three.\n"
      }
    }
  ],
  "created": 1782354762,
  "model": "SmolLM3-Q4_K_M.gguf",
  "system_fingerprint": "b8496-312d870a8",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 491,
    "prompt_tokens": 262,
    "total_tokens": 753,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  },
  "id": "chatcmpl-J02gP2dc5X4IxzJcadTUDxZAOZWpGnvb",
  "timings": {
    "cache_n": 0,
    "prompt_n": 262,
    "prompt_ms": 1341.488,
    "prompt_per_token_ms": 5.12018320610687,
    "prompt_per_second": 195.30551149171666,
    "predicted_n": 491,
    "predicted_ms": 42248.081,
    "predicted_per_token_ms": 86.04497148676171,
    "predicted_per_second": 11.621829640025545
  }
}

要留意，根據官方文件說明，要使用 thinking/reasoning 必須給予 --jinja 參數¹，但是較舊的 llama.cpp 似乎不支援這個參數，如：ghcr.io/ggml-org/llama.cpp:server-vulkan-b8248，關於 llama.cpp 版本的坑後面還會提到更多。

llama.cpp 呼叫 Hugging Face 的行為

大約在 b8496 (2026-04-24) 和 b9102 (2026-05-11) 兩個版本之間，llama.cpp 從 Hugging Face 上拉取模型的行為發生了變化，具體是哪個版本我懶得調查了。

當使用這樣的參數時：

    environment:
      - LLAMA_ARG_HF_REPO=ggml-org/SmolLM3-3B-GGUF
      - LLAMA_ARG_MODEL=SmolLM3-Q4_K_M.gguf

b8496 以前的版本會使用像這樣的路徑下載：

/ggml-org/SmolLM3-3B-GGUF/resolve/main/SmolLM3-Q4_K_M.gguf

b9102 以後則是會先去呼叫這個路徑：

/api/models/ggml-org/SmolLM3-3B-GGUF/refs

而 /refs 這個 API 在我使用的鏡像方案 Olah 並未實做。

llama.cpp 的架構問題

在 Python 的體系中，應用程式和 LLM 模型之間還夾了 SDK、Hugging Face Transform、PyTorch，當某人發布了新的 LLM，它的架構會在 SDK 那層會處理。但是 llama.cpp 只有 C++ 實做和 GGUF 模型，所有架構都必須在 llama.cpp 的 C++ 實作內 hard coding。

這造成了 llama.cpp 支援模型的能力高度被 llama.cpp 的更新進度榜定，例如在 b8248 中試圖運行 Gemma 4的話會得到：

llm-1  | llama_model_load: error loading model: error loading model architecture: unknown model architecture: 'gemma4'
llm-1  | llama_model_load_from_file_impl: failed to load model
llm-1  | common_init_from_params: failed to load model '/root/.cache/llama.cpp/unsloth_gemma-4-E2B-it-GGUF_gemma-4-E2B-it-Q4_K_M.gguf'
llm-1  | srv    load_model: failed to load model, '/root/.cache/llama.cpp/unsloth_gemma-4-E2B-it-GGUF_gemma-4-E2B-it-Q4_K_M.gguf'
llm-1  | srv    operator(): operator(): cleaning up before exit...
llm-1  | main: exiting due to model loading error
llm-1 exited with code 0 

Docker Registry API V2

b8496 以下的版本使用這個配置的話可以正常下載模型：

    environment:
      - LLAMA_ARG_HF_REPO=ggml-org/SmolLM3-3B-GGUF
      - LLAMA_ARG_MODEL=SmolLM3-Q4_K_M.gguf

但是當需要使用像 PaddlePaddle/PaddleOCR-VL-1.5 這樣的模型時，下載一個檔案是不夠的，需要多個檔案才能讓模型在 llama.cpp 內運作：

PaddleOCR-VL-1.5.gguf
PaddleOCR-VL-1.5-mmproj.gguf
chat_template.jinja

這是因為它屬於多模態模型，而不是單純的 LLM，（應該）可以使用以下參數來來下載多個檔案：

    environment:
      - LLAMA_ARG_HF_REPO=ggml-org/SmolLM3-3B-GGUF:Q4_K_M

但是會出現以下錯誤：

error from HF API (http://huggingface.mirrors.solid.arachne/v2/ggml-org/SmolLM3-3B-GGUF/manifests/Q4_K_M), response code: 404, data: {"error":"Sorry, we can't find the page you are looking for."}

因為這是 Docker Registry API，而 Olah 沒有實作。

OCI AI Payload

恩？明明是從 Hugging Face 下載模型，怎麼連 Docker Registry API 都來參一腳了？

稍微搜尋了一下發現這個東西：

https://hub.docker.com/r/ai/gemma4

而且它不能直接用 Podman 下載：

$ podman pull docker.io/ai/gemma4:E2B
Trying to pull docker.io/ai/gemma4:E2B...
Error: parsing image configuration: unsupported image-specific operation on artifact with type "application/vnd.cncf.model.manifest.v1+json" 

原因是這是特殊的 OCI 封裝格式²，據我所知是因為它沒有 roofs 的資訊，必須使用像這樣的指令拉取：

podman unshare skopeo copy \
  --insecure-policy \
  docker://harbor.mirrors.liquid.arachne/docker-hub-proxy/ai/gemma4:E2B \
  dir:./

簡單來說，Hugging Face API 目前雖然作為實質產業標準，但是 CNCF 有意對「怎麼佈署與傳輸類神經模型檔案」訂出標準。

llama.cpp 也支援該界面：

Argument	Explanation
`-dr, --docker-repo [<repo>/]<model>[:quant]`	Docker Hub model repository. repo is optional, default to ai/. quant is optional, default to :latest. example: gemma3 (default: unused) (env: LLAMA_ARG_DOCKER_REPO)

如果這個方案可以普及，我的 Olah 就可以退役了，轉而使用更可靠的 Harbor。不過目前只有 Docker Hub 在使用，而 Docker Hub 的流量限制本身就是害我拉大檔案拉不下來的因素之一。

OCR 模型表現不穩定

[ocr]        | srv  params_from_: Chat format: peg-native
[ocr]        | slot get_availabl: id  3 | task -1 | selected slot by LRU, t_last = -1
[ocr]        | slot launch_slot_: id  3 | task -1 | sampler chain: logits -> ?penalties -> ?dry -> ?top-n-sigma -> top-k -> ?typical -> top-p -> min-p -> ?xtc -> temp-ext -> dist 
[ocr]        | slot launch_slot_: id  3 | task 0 | processing task, is_child = 0
[ocr]        | slot update_slots: id  3 | task 0 | new prompt, n_ctx_slot = 4096, n_keep = 0, task.n_tokens = 1179
[ocr]        | slot update_slots: id  3 | task 0 | n_tokens = 0, memory_seq_rm [0, end)
[ocr]        | slot update_slots: id  3 | task 0 | prompt processing progress, n_tokens = 5, batch.n_tokens = 5, progress = 0.004241
[ocr]        | slot update_slots: id  3 | task 0 | n_tokens = 5, memory_seq_rm [5, end)
[ocr]        | srv  process_chun: processing image...
[ocr]        | encoding image slice...
[ocr]        | image slice encoded in 21944 ms
[ocr]        | decoding image batch 1/5, n_tokens_batch = 256
[ocr]        | image decoded (batch 1/5) in 197 ms
[ocr]        | decoding image batch 2/5, n_tokens_batch = 256
[ocr]        | image decoded (batch 2/5) in 576 ms
[ocr]        | decoding image batch 3/5, n_tokens_batch = 256
[ocr]        | image decoded (batch 3/5) in 335 ms
[ocr]        | decoding image batch 4/5, n_tokens_batch = 256
[ocr]        | image decoded (batch 4/5) in 412 ms
[ocr]        | decoding image batch 5/5, n_tokens_batch = 142
[ocr]        | image decoded (batch 5/5) in 428 ms
[ocr]        | srv  process_chun: image processed in 23892 ms
[ocr]        | slot init_sampler: id  3 | task 0 | init sampler, took 0.01 ms, tokens: text = 13, total = 1179
[ocr]        | slot update_slots: id  3 | task 0 | prompt processing done, n_tokens = 1179, batch.n_tokens = 8
[ocr]        | slot print_timing: id  3 | task 0 | 
[ocr]        | prompt eval time =   24747.40 ms /  1179 tokens (   20.99 ms per token,    47.64 tokens per second)
[ocr]        |        eval time =   93429.63 ms /  2917 tokens (   32.03 ms per token,    31.22 tokens per second)
[ocr]        |       total time =  118177.03 ms /  4096 tokens
[ocr]        | slot      release: id  3 | task 0 | stop processing: n_tokens = 4095, truncated = 1
[ocr]        | srv  update_slots: all slots are idle
[ocr]        | srv          stop: cancel task, id_task = 0
[ocr]        | srv  update_slots: all slots are idle
[ocr]        | srv    operator(): got exception: {"error":{"code":500,"message":"Failed to parse input at pos 0: TQ；的既然既然  既然既然 称即作四作作作�는戒инин 교 교浦に��집집집 அமை作 (ӀэӀэӀэӀэ的的��ده层透明透明ண்டுண்டு羡羡 the the\n\n\n裔5�(，，，�輒放放��貲支����ver.جی顯顯由於宇丁ine  的有เพ阵年是 ilesuணணஸஸ�興�����。那那那ӀэӀэӀэ蚚��图的疾 ..,то角角���ололол���浆â�，，，的的��，，，，的的�，，場从shshdd�，0，，贺的的的的的的\n\n的的200,,,，，，禹.\nmff..，只有在y���转  .，，，争www-----��      iew徒��\n\n\n\n\nimetையில்ையில்ையில்ையில்友ssss ,,,,,,，，，的的���，，的 war and and and and andsw81生\n({{\\市ne季季食生生生生�清清��在在评ans芽lan\n\n\n\n        ���，，，的的的��，，，，,���，，，，,�����-,((���ek of     的的的���，，，00,，，的的的失失失���，，的的的���，，，,,的��，，，99  简称oofCCèге�顯顯韓韓韓韓韓友���的\n�夫夫��与非与非与非与非————��ataadyofofofofof涓,,,niluoppnnnn..，，，，���，，，的的成，ansuu�，，，，，，��，，，\n‌00ofn�.，，，，ிறிறிறிறிற\n1ไ\n\n\n\n\n\n r.�,,,评\n\n\nbu-..-.-首位ofuns党 from\n评gg\n\n\nss\n\n\n\n\n W I I  \n\n\n   \n,.\n\n               in in in in in in in in in e sl  el��      \n\n\n1  ไ\n�.，，，，的��否o�----08��，，\n\n\n\n\n\n1情  \n 妇\n�,，，，，，��，，， or     1 and and and and\n\n\nlot\nر  \n\n\n۹   \n\n\n\n\n\n，，，的���，，，，回归--..，\n\n\n   �,，，的的的�蛛��--         in in\n\n fa以下的    \n ofans\n       F F E E E E连连连新新 F的的的的的的的的 W Group\\.��âè以下的以下的以下的以下的类和�� स्�}}) ,,，，，的wy��域intLLLLLau ,  江江\n\n\n�，，，的的的�� of of of欢欢欢欢G� of of������ 相ǎ� ，，，的的的 I   的的 of\n\n\n\n\nl ,------1111 from,,,, of江,,,,,�u\n\n\n\n\n的的的的1���，，的的的的的��艺� (\n Ю�\n of of\n\n\n\n\nзна�\n\n\n\n\n\n\n W资�， Sc6\n\n\n\n的 मा \n\n\n\n\n\n\nssss的�\n江66666是�和在在在在在在在在       …. or or和111在�n�.., or\n\n决定场场场场生, (\n\n\n\n\n\n         的的��   G G G G,天天天6的的的的的 ( (学习方法omuuu\n11111111���，९和\n\n\n\n\n\n S S C C C C C C C C C C۳\n\n\n\n\n\n\n\n\n\ncc1��，，，，的的的�,的的的的�的的的的的的的的的的的的在在在在恢复正常\n\n1111111��，，，，，的的�不可oooooââ�\n�\n    .222，，，行文文文生生�文\n��连         请\n\n\n\n\n\n在在在�\n\n\n\n\n\n (�\n�大有有有的的的的���，，，，，的的的���，，，，的的法�\n\n\n\n\n\n的�� \n\n\n\n\n\n\n\n\n\\\\\\\\\\\\��，�阵战委天天天天内内非LL在在在在在在在在在在的\n\n的的的的的的的的的�غ行\n\n\n\n\n\n            �����,�1nn0,，，，，的的的 R\n�清有的的的的的的的的的������，，， (\n境\n���\n\n\n C�\n\n and��的的的的的晙�\n\n掉\n\n\n\n\n\n C C C C C C C C C C C C C C C C C C C C C C C C C C C C政政政政政生、,\n天天�掉\n�\n6000,,，，，，的的���， Wh W\n G G G G C C C C C迁迁迁迁 of,    ofลง�WW�WL��\nand暚\n\n\n非非 G Out Out Out未婚汲汲汲汲汲諾諾諾�\n\n\n\nC在在在在在          \n大大的\n\n领域的�\n�，，\n\n\n\n\n\n\n\n\n C C C C C C\n\n\n，,，，，\n\n\n\n\n\n\n\n��0,，，，，，��，，，，\n\n\n\n\n\naaaasssss\n�城amâéâââ以下的以下的以下的以下的法和类和 स् WIลงорт政政质质质�\n\nSکن�\n\n\n\n\nandR�.生生\n\n\n\n\n\n\ngauauorotimesotimesotimes.—.—.—諾諾諾諾諾â��,， and天天\n\n�0,，，，，，，\nธ� .,，，，，，的 of of of ofofofofofof灰灰灰\nand��0，\n\nandand�艺\n\n\n\n\nandR�生失失\n\n\n\n\n\n\n in in in in in in in in in in\n\n\n\n\n的的的的的在在在在在前前前前前在âi�n�,,,，资格\nธâl�.艺\n\n���000，，，\n\n\n\n\nธR .��财非非非非非非非非非\n生生\n\n��0,,，，，�ab99�ââ�，，，生生生生生城\n\n\n\n\n\n\naaaaaa C C C C C e e e e e e e评,\n\n\n\n\n\n\n\n6R政\n\n\n\n 함 함 함 함 of of of ofofofofofofofofer\n\nWGGGLL\n\n\n\nGâéâè以下的以下的以下的法和\n\n\nธ城城�开工� and���iideideideideideideararauâ\n\n\n\n\n\n\n\n在在在在在����，ans\n\n\n\nâââ以下的以下的以下的类和类和类和 Duranteवन\n\n\n\nââ\n\n\n\n\n0、生行\n�â�以下的以下的ons域域域000\n\n\n\n\n\n\n\n旧旧旧旧otimes���er掉\nâand and\n\n�âant and and,�行�ââân�,,，的�\n\n\n\n\naa000I的的的的的的的的的的的的的的的的���नानाना新新ererer低估低估汲汲汲汲\n\n\n\n\n\n\n C C C C C C C C C C C C C C���兽骏骏 함 함 함 함 함secsecsecsec骏骏骏 文\n�â�\n\n\n\n\n�R���\n\n\n\n跨跨跨跨��\n\n\n\naaaaaarerereotimes汲汲ना\n (院\n\n\n\n\n\n11111���\n\n�����\n\n\n\n\n\n\n中的的的的的�â�\n\n�\n\n�\n\n\n0���(\n\n\n\n\n\n\n\n\n\n\n\n\n\n在在在在在在在在在在的的的的��and�\n\n\n\n\n\n\nG新新在在在在在在在在在的1���RR2�，\n�\n\n\n\n\n\n\n\n\n  ��，，，，，\n\n\n\n\n\n\n\n12��，，，，，的的的�\n\n\n\n\n\nG，，，，，\n\n(R�\n\n\n\n\n\n\n非非非非非icic,�âââ以下的以下的以下的以下的以下的类和类和� Durante\n�0，,，，，，���\n\n\n\n\n\n,1�\n\n\n\n\n���90，，，，的的的的�\n\n\n\n\n�RRRnnnnnnnRFnnn，，，，，，的的���，，，，，的�\n\n\n\n\n\n (RRR者\n\n\n\n\ng新在在在�\n\n\n\n\n\n\n\n在在�\n��111\n\nธ�大大的的的在龙\n\n\n\n\n\n (\n���有有有有境言go\nate\n\n\n\n\n\nL1111���，\n�\n�，\n\n�有\n�\n�要要要要nnnF在在在FF1��，，，，的的���，，，，�\n\n\n\n\n\n\n\n\n在在在在在在在在在在在在在在在在在在在在在1���，，，言言L�i�âââââ  âand櫫��ââ�\n���âââ\n\n\n\n\nG，，，۹�艺艺艺����������城城�\n������������言境\n66��â��，\n\n�\n�艺�\n���，，，，，的����â\n\n�éâ以下的以下的以下的一向�\n\n\n�\n��\n�������������â��，，","type":"server_error"}}
[ocr]        | srv  log_server_r: done request: POST /v1/chat/completions 10.89.62.26 500

有的時候 PaddleOCR-VL-1.5-GGUF 會異常，原因未知。

llama.cpp 快取失蹤

這個參數不會下載到 /root/.cache/llama.cpp，而是直接放在 /app 之下：

    environment:
      - LLAMA_ARG_HF_REPO=ggml-org/SmolLM3-3B-GGUF
      - LLAMA_ARG_MODEL=SmolLM3-Q4_K_M.gguf

這個才會，volume 設定才有用：

    environment:
      - LLAMA_ARG_HF_REPO=ggml-org/SmolLM3-3B-GGUF
      - LLAMA_ARG_HF_FILE=SmolLM3-Q4_K_M.gguf
    volumes:
      - data:/root/.cache/llama.cpp

模型下載問題

前面講的多模態檔案可以用以下配置解決：

services:
  downloader:
    image: docker.io/huggingface/downloader:0.17.3
    entrypoint: ["sh", "-ec"]
    command:
      - |
        echo "Download model... ";
        huggingface-cli download "PaddlePaddle/PaddleOCR-VL-1.5-GGUF" \
                  --include "PaddleOCR-VL-1.5-mmproj.gguf" "PaddleOCR-VL-1.5.gguf" "chat_template.jinja" \
                  --cache-dir=/hf-cache \
                  --local-dir=/data/PaddleOCR-VL-1.5-GGUF \
                  --local-dir-use-symlinks=False
    volumes:
      - model-cache:/data
      - hf-cache:/hf-cache
  ocr:
    image: ghcr.io/ggml-org/llama.cpp:server-vulkan-b8248
    restart: always
    devices:
      - /dev/dri/:/dev/dri/
    ports:
      - 8080:8080
    entrypoint: /app/llama-server
    volumes:
      - model-cache:/data
    environment:
      - LLAMA_ARG_MODEL=/data/PaddleOCR-VL-1.5-GGUF/PaddleOCR-VL-1.5.gguf
      - LLAMA_ARG_MMPROJ=/data/PaddleOCR-VL-1.5-GGUF/PaddleOCR-VL-1.5-mmproj.gguf
      - LLAMA_ARG_CHAT_TEMPLATE_FILE=/data/PaddleOCR-VL-1.5-GGUF/chat_template.jinja
      - LLAMA_ARG_WEBUI=disabled
      - LLAMA_ARG_N_GPU_LAYERS=all
      - LLAMA_ARG_CTX_SIZE=20000
      - LLAMA_ARG_TEMP=0
      - LLAMA_ARG_JINJA=1
      - LLAMA_ARG_FIT=off
    depends_on:
      downloader:
        condition: service_completed_successfully
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 10s
      timeout: 20s
      retries: 3

volumes:
  model-cache:
  hf-cache:

一個容器專門跑下載，另外一個容器專門運行模型。不過這個配置有兩個問題：

在 docker compose 可以正常運作，但是 podman compose 對於 depends_on 的支援度不夠高因此不會按照預期的順序啟動容器。
我可能還沒找到正確配置 huggingface-cli 指令的方式，即便檔案已經存在它也不會自動忽略而是重新下載一次。

ggml-org/SmolLM3-3B-GGUF · Hugging Face. https://huggingface.co/ggml-org/SmolLM3-3B-GGUF ↩
model-spec/docs/spec.md at main · modelpack/model-spec https://github.com/modelpack/model-spec/blob/main/docs/spec.md ↩

前情提要

最近在寫一些小工具，涉及比較敏感的資料，所以不能直接用雲端的 LLM，要用地端/本地的 LLM 處理。不過過程中遇到一點問題，想留個紀錄，但是背景有點複雜，於是想說單獨寫一篇解釋一下我目前的各種技術決策。

雲端 LLM

Application 端: OpenAI-Compatible API
可觀測端：TensorZero
模型端：Open Weight Models

warning

TensorZero 已經於 2026-06-12 停止維護。

OpenAI-Compatible API 基本上實質產業標準了，不過僅限 LLM 體系，非 LLM 的模型（例如影像或音訊處理）生態比較複雜，沒辦法被這種 API 設計完全覆蓋了。

LLM 可觀測的用途是可以紀錄各種模型、Token 量、費時提示詞以及 reasoning（一般不會直接顯式在應用程式上）。當時選擇 TensorZero 的原因是相對於 Langfuse 和 LiteLLM 的組合更輕量，而且有故障的經驗（雖然事後得知是 ClickHouse 配置失誤的原因）。

模型端則是只使用開放權重的模型，避免供應商鎖定。

地端 LLM

Application 端: OpenAI-Compatible API
GPU 端：Vulkan
模型運行端：GGUF
Runtime 佈署端：OCI (Open Container Initiative)
OCI 佈署端：Docker Registry API V2
模型佈署端：Hugging Face API
模型快取/鏡像：Olah
OCI 快取/鏡像：Harbor
OCI 編排端：Podman-Compose

應用程式同樣使用 OpenAI-Compatible API 使用 LLM。

使用 llama.cpp 運行 LLM，因為它支援多種 GPU 後端（包含主流的 CUDA、ROCm、SYCL...），特別是其中的 Vulkan 可以避免供應商鎖定。其使用的 GGUF 檔案則是針對量化的支援度很高，使用量化模型在該生態系可以說是預設行為，生態系中的模型大多經過量化，量化後的模型較小，可以節省傳輸流量以及運行時的 VRAM 消耗。同時官方提供可以開箱即用的預建置 OCI (Open Container Initiative) 映像檔，對雲原生環境十分親和。

使用 Podman Compose 運行 OCI 容器。使用 Podman 是因為想要試著脫離 Docker 的體系，並且嘗試 Rootless/Daemonless 的方案。Podman 生態系的 Dokcer Compose 對標容器編排方案是 Quadlet；一個 systemd 風味的方案，但是這樣做會偏離主流開發者太遠，所以我使用 Podman Compose 來繼續使用 docker-compose.yaml。

我的 homelab 對外網路是 4G 無線路由器加上方案有被限流，所以大部分涉及「套件下載」的東西我都有架設本地鏡像/快取來節省流量，包含：apt、npm、pypi、OCI、Hugging Face。同時把快取的職責甩給 homelab，工作電腦就可以經常清掉暫時用不到的快取，有必要再直接從 homelab 拉下來用。

如此一來就可以在本地快速建立一個 LLM 實例供開發測試使用：

services:
  llm:
    image: ghcr.io/ggml-org/llama.cpp:server-vulkan-b8496
    restart: always
    devices:
      - /dev/dri/:/dev/dri/
    ports:
      - 8080:8080
    entrypoint: /app/llama-server
    environment:
      - LLAMA_ARG_HF_REPO=ggml-org/SmolLM3-3B-GGUF
      - LLAMA_ARG_MODEL=SmolLM3-Q4_K_M.gguf
      - LLAMA_ARG_WEBUI=disabled
      - LLAMA_ARG_N_GPU_LAYERS=all
      - LLAMA_ARG_CTX_SIZE=20000
      - LLAMA_ARG_TEMP=0
      - HF_ENDPOINT=http://huggingface.mirrors.solid.arachne
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 10s
      timeout: 20s
      retries: 3

後記

問題的部份下一篇文章再提。

TiddlyRAG Dev Log - TiddlyWeb 程式碼回顧與重構

June 8, 2026

Wei Ji

閃亮症候群工程屍

前情提要

MWS (MultiWikiServer) 是正在開發中的 TiddlyWiki 後端方案。
MWS 的主要開發者是 TiddlyWiki 社群的核心人物，同時 MWS 相關的開發資訊是掛在 TiddlyWiki 的組織帳號以及網域下，因此地位上是「TiddlyWiki 正宗承認的後端專案」。
經過田野調查後有以下發現：
- AuthZ 方案選擇使用 ACL，大部分的 Issue 都在繞著 ACL 相關的問題討論。
  - 然而 MWS 的資料模型是建立在 Recipe-Bag 多對多關係下，ReBAC 才是合適的 ACM。換句話說，這個專案正在經歷錯誤的技術決策造成的泥沼。
- 關於 Admin UI 的討論則是第二多的討論。
  - 然而此時 MWS 的核心運作依然不穩定，並沒有提供方便 DevOps 快速搭建服務的選項（如：預建置 OCI 映像檔）。
  - 其中甚至涉及透過 RPC 實現前後端混合渲染之類的話題。（基本上重新發明 Nest.js）
- 程式碼風格延續 TiddlyWiki 時期的邊界模糊。
  - 可靠性堪憂。
  - 安全性堪憂。
  - 「社群自 high 專案」，無法吸引使用主流技術棧的開發者。
  - 大量的「重複輪子」程式碼。
- 主要開發者認為「Docker 對使用者不友善」。
TiddlyWeb 是起於 2008 年，止於 2021 年 Python 實做的 TiddlyWiki 後端。Recipe-Bag 的模型源自於此。
- TiddlyWeb 的程式碼大小大約為 600 KiB， MWS 則是 MiB。
- TiddlyWeb 的 API 較為乾淨，沒有複雜的 RPC 或是混亂的 ACL 設計。
- TiddlyWeb 內有單元測試。
- TiddlyWeb 的程式碼多停留在 Python 2.7 時期，部份實做 2.7/3.3 兼容程式。

簡短結論

先講結論，我把核心邏輯的實做跟測試案例都搬到 Python 3.12 去了，程式碼在此：

https://github.com/FlySkyPie/tiddlyrag-poc/tree/poc/type-e

不過 HTTP API 的實作就沒繼續了，後面會說明原因。

原訂計畫

大方向上，在遵守 TiddlyWiki 社群共識的模型與 API，製作一個兼容的 API 伺服器，不只作為 TiddlyRAG 的微服務組件，更能回饋 TiddlyWiki 社群。拆成兩個階段：

PyNest 階段
1. PyNest 是仿造 NestJS 風格的 Python/FastAPI 後端伺服器框架
2. 將 TiddlyWeb 的實作逐步遷移到現代框架/環境中。
NestJS 階段
1. 將 PyNest 專案轉譯成 NestJS，回歸 TiddlyWiki 的 Node.js 系統。

第一階段的細節，使用乾淨架構：

Domain
- 不仰賴函式庫
- 使用缺血模型模仿 TiddlyWeb 的資料結構
- 使用 typing.Protocol 抽象 TiddlyWeb 的模型方法
Infrastructure
- TiddlyWeb 的實作與測試會置於這一層
Application
- PyNest 的實作，主要是 HTTP 伺服器一類的邏輯。

如此設計的原因是 TiddlyWeb 的實做缺乏現代開發的邊界感，實作往往有高度的耦合性，很難直接切割，重構策略：

Legacy_Model = 缺血模型 + 界面 + Infrastructure 實作
Legacy_Test(Infrastructure 實作)

盡可能保持原始的界面，來重複使用單元測試，確保複製原始的業務邏輯。

整個過程會是 Strangler Fig Pattern：

大部分實做會置於 Infrastructure 層
HTTP 相關的落伍實作會由 Application 層取代
足夠乾淨的實作會放到 Domain 層

過程中可以慢慢把舊的領域模型與業務邏輯轉譯成現代軟體的建模方式（Service, Repository...）。

重構（遷移）過程與程式碼回顧

這邊解釋一下為什麼要把原本的充血模型分解掉：

Legacy_Model = 缺血模型 + 界面 + Infrastructure 實作
Legacy_Test(Infrastructure 實作)

因為在現代後端，Query 類的問題幾乎都交由資料庫進行優化，而從資料庫檢索出來的東西也就只有資料，沒有方法，所以當模型仰賴資料庫進行持久化時，最好不要假設有太多方法的存在。

除此之外，遷移過程我還進行了一些修改，確保程式碼符合現代風格，或是為過度到現代風格做準備。

OOP

TiddlyWeb 的大部分實做都是函式，並且透過 environ 來傳遞大部分資訊，只有少部份的邏輯有封裝成物件。這似乎是 CGI (Common Gateway Interface)/WSGI 延續化來的風格。

info

CGI 時期的 web server 實作其實是一個執行檔，仰賴環境變數與 STDIO 與 parent process 溝通。parent process 是真正對外開埠的程式，在收到 request 之後把 URI 轉換成環境變數去呼叫 CGI 程式，再把拿到的字串作為 response 返回。

透過將原始實做封裝到物件內，我就可以將方法抽離成 Protocol，並且透過建構子解偶對其他函式的仰賴，之後就能清楚的的知道整個仰賴鏈，舉例來說這是重構後測試程式的片段：

    specialbag_mock = MagicMock(spec=SpecialBagInterface)
    helper = TextSerialization(specialbag_mock)
    serializer = SerializationFacade(helper)
    store_helper = MemTextStoreHelper(serializer)
    store = StoreFacade(store_helper)

    select_filter = SelectFilter(store)
    sort_filter = SortFilter(store)
    filter_facade = FilterFacade(select_filter, sort_filter)
    resolver = OverlayResolver(filter_facade)

Facade 模式

TiddlyWeb 本身有使用 OOP 的實作都是 Facade 模式，並且有這幾個：

Serializer
- html
- json
- text
Store
- text

物件對外是用像這樣的語法被使用：

serializer = Serializer('json')

內部則是使用像這樣的語法動態載入：

imported_module = __import__('tiddlyweb.serializations.%s'
        % self.engine, {}, {}, ['Serialization'])

一股 Javascript 弱型別特性語言的 require() 味撲鼻而來...

如同你在前面測試程式碼看到的，這的部份我也是用 ID (Dependency Injection) 處理掉了。

另外一個部份 TiddlyWeb 也有使用類似於 Facade 模式的東西，雖然沒有建立 class：

filters
- limit
- select
- sort

先建立規則表：

FILTER_PARSERS = {
        'select': select_parse,
        'sort': sort_parse,
        'limit': limit_parse,
}

然後根據輸入的 filter 規則視情況選擇具體的解析實做

    filters = []
    leftovers = []
    for string in strings:
        query = parse_qs(string)
        try:
            key, value = list(query.items())[0]

            # We need to adapt to different types from the
            # query_string. It changes per Python version,
            # and per store (because of Python version).
            # Sometimes we will already be unicode here,
            # sometimes not.
            try:
                argument = unicode(value[0], 'UTF-8')
            except TypeError:
                argument = value[0]

            func = FILTER_PARSERS[key](argument)
            filters.append((func, (key, argument), environ))
        except(KeyError, IndexError, ValueError):
            leftovers.append(string)

    leftovers = '&'.join(leftovers)
    return filters, leftovers

Overlay

解明 Recipe-Bag 的模型邏輯算是調查的重點之一，在 TiddlyWeb 中是被放在名為 control.py 的檔案中，因為它需要從 GET /recipes/{recipe_name:segment}/tiddlers[.{format}] 這樣的路徑中挑選真正的 tiddler。

但是這會和現代 MCV 架構中的 Controller 撞名，於是我把相關邏輯風裝在名為 OverlayResolver 的物件內。

測試案例

在遷移完核心邏輯之後，就是遷移相關的測試案例，整個過程就是不斷的重複這個步驟：

commit 4630d5c8e58e0531342b64bca8cf3a849d7b854c
Author: Wei Ji (FlySkyPie) <c445dj544@gmail.com>
Date:   Sat Jun 6 20:24:31 2026 +0800

    feat: adjust test

commit 86e77b44f8603b4fe47ec9e2195fb14987b79c9b
Author: Kilo Code v4.153.0 <deepseek+deepseek-v4-flash@openrouter.ai>
Date:   Sat Jun 6 20:20:09 2026 +0800

    test: refactoring test to match current project

commit db58f75f56c4aaa9c2f63ef2eebdb91c32d0d909
Author: Wei Ji (FlySkyPie) <c445dj544@gmail.com>
Date:   Sat Jun 6 20:17:14 2026 +0800

    chore: move test file from legacy

把原本的測試檔案移到 Infrastructure 中，這個時候跑 pytest 會直接壞掉，因為有嚴重的語法錯誤。
讓 LLM 做重構，這時 pytest 就會恢復功能，可以看到 PASSED 跟 FAILED
Review 看有沒有測試案例被 LLM "偷懶"刪掉的，如果有就補回去，或是適度的刪掉過期的測試案例，例如前面講的動態 import 就有測試案例在測這個，不過既然我不使用字串動態 import 了，有些"預期無效字串錯誤"的案例就可以刪掉了。
有時候測試案例是好的，但是遷移過程中遺漏的邏輯造成失敗，就把實作補回去。

一開始的測試案例我都白嫖 Gemini Flash，後面等到模式建立起來之後就用開放權重的模型跑了，提示詞不複雜：

Your task:
- Read `tiddlymicroweb/infrastructure/store/tests/test_tiddler_slash.py`
- Refactoring `tiddlymicroweb/infrastructure/entities/test_user.py` by following previous refactoring pattern.

一次重構的最終上下文大約為 40k 左右。

info

最終上下文是指最後一個步驟的 token 數，整個 ReAct 過程總用量要再乘以次數除以二。

另外補充，TiddlyWeb 的程式碼我是透過 Git Subtree 放進專案的，目的是為了保留歷史上下文，同時必要時 ReAct 可以回去檢視 Legacy code。

`MemTextStoreHelper`

TiddlyWeb 原本只實做了 text，會直接把資料寫入檔案系統的 store 實做，並且所有測試都是整合測試，實例之間又有複雜的仰賴，對 store 進行 Mock 其實不切實際。

於是我使用 pyfilesystem2，保留界面與大部分內部實作邏輯，把寫入對象從系統的檔案系統改成記憶體虛擬出來的檔案系統。如此一來便可在最少修改的前提下讓原本的整合測試能夠更「單元」一點。

結論

在 TiddlyWeb 中，關鍵的業務邏輯被分成了三個區塊：

Filter
Overlay
Store

然而這帶來了一個問題，這在現代後端都是需要跟資料庫溝通的行為，通常被抽象化成 Repository。先不談 Overlay 和 Store 在現代架構下可以被合併成一體，問題在於 Filter。

Filter 存在的目的是提供類似 TiddlyWiki 的語法，但是目前實作都是在 Python 內進行的，如果想要保持兼容性，標準的解法是使用 DSL (Domain-specific language) 或 AST (Abstract syntax tree) 作為 Filter 語法和 SQL 的中介層，但是建構並維護這樣一個中介層的成本非常的高。

另外，因為測試案例都是整合測試，因此當軟體結構遷移到現代的抽象方式時(Service, Repository...)，這些測試都變得毫無用處。

簡言之，雖然我成功把核心的業務邏輯以及相關的測試案例重構到現代環境，因為建模的方式依然和現代模型之間存在巨大的鴻溝，實在很難在完整兼容的前提遷移到現代系統。

抽出 OpenAPI 模型，並在理解舊有實作和測試案例的前提下直接重新實作一個部份兼容的 API Server 可能是更好的選擇。

TiddlyRAG Dev Log - MWS 與 ETL

June 3, 2026

Wei Ji

閃亮症候群工程屍

前情提要

TiddlyRAG Dev Log - MWS API | 工程屍 FlyPie 的異想世界

在前一篇文章中，我提到了 MWS (MultiWikiServer) 時做了一個名為 Recipe-Bag 多對多模型，用來展現類似於 OverlayFS 的行為。

但是我依然不能百分之百確定這個模型的設計哲學以及正確的行為是什麼，舉例來說：

對 Recipe 名下的某個 Tiddler 寫入時，是永遠寫到 Bag 的最上層嗎？這是不是代表每個 Recipe 都至少包含一個 Bag 作為 Overlay？
Recipe-Bag 模型是從哪裡來的？是如我直覺的啟發自 OverlayFS 還是其實長得很像但是細節不太一樣？

翻譯 ETL

於是我計畫建構一個 ETL (Extract, Transform, and Load) 來處理這個問題：透過 GitHub API 拉出 Issue 和 Comment （討論紀錄）、進行翻譯、最後輸出成方便我閱讀的 Markdown。

除了表面的目的以外還有其他考量：最近我在 104 看職缺的時候，發現一些關於 ETL 的職位會提到 Perfect 這類工具，於是我想這是一個嘗試新東西的機會。

雖然我也可以嘗試透過最近完成的 EC-BT (Entity Component Behavior Tree) 進行資料探勘，但是我依然需要對標準的 ETL Pipeline 有基本的認識才能避免重複發明輪子。

一開始我是試著搭建 Prefect 的環境，不過過程中我看到了這個：

這讓我的開源雷達亮紅燈。加上它的文件不是很清楚，我沒辦法一下子搞清楚誰是 Client？誰是 Server？誰是 Workder？

另外一點，這是 Luigi 的官方範例¹：

class AggregateArtists(luigi.Task):
    date_interval = luigi.DateIntervalParameter()

    def output(self):
        return luigi.LocalTarget("data/artist_streams_%s.tsv" % self.date_interval)

    def requires(self):
        return [Streams(date) for date in self.date_interval]

    def run(self):
        artist_count = defaultdict(int)

        for input in self.input():
            with input.open('r') as in_file:
                for line in in_file:
                    timestamp, artist, track = line.strip().split()
                    artist_count[artist] += 1

        with self.output().open('w') as out_file:
            for artist, count in artist_count.iteritems():
                print(artist, count, file=out_file)

它顯式的表明了一個 Task 的輸入與輸出，比較符合我對 ETL 的想像，畢竟是 ETL (Extract, Transform, and Load) 對吧？

反之 Prefect 的官方範例則是長這樣：

from prefect import flow, task
import httpx


@task(log_prints=True)
def get_stars(repo: str):
    url = f"https://api.github.com/repos/{repo}"
    count = httpx.get(url).json()["stargazers_count"]
    print(f"{repo} has {count} stars!")


@flow(name="GitHub Stars")
def github_stars(repos: list[str]):
    for repo in repos:
        get_stars(repo)


# run the flow!
if __name__ == "__main__":
    github_stars(["PrefectHQ/prefect"])

好，你定義了一個像是 Pipeline 的東西，但是你的 Load 勒？

另外，最近學習 NestJS 和 FastAPI 的經驗讓我對於 Prefect 的語法有一點防禦心理。FastAPI 高度仰賴 Dep 注入函式的方式建構，副作用就是專案的組織充滿可能性，造成程式碼很雜亂，反而是 NestJS 基於物件的結構直接隱式的決定了程式碼的位置以及如何在專案中組織。

看起來好像有點用... 但老實說，我覺得用一個簡單的 Makefile 就能搞定所有這些東西了。用這種工具的好處是什麼啊？

路易吉的確是受到 GNU make 的啟發（文章裡不同地方有提到），而且文章裡的微型範例並沒有展現它所有的功能。它跟 Spark 和 Hadoop 這樣的框架配合得很好，它支援開箱即用的不同資料儲存目標，你有錯誤報告、依賴關係圖視覺化等等。 ²

這個算是我嘗試 Luigi 的原因之一，CMake 或 Bazel 這類本地建置工具長什麼樣子我心裡有底，所以我需要的是一個光譜在 CI/CD 或本地自動化工具以外的 ETL/Data Orchestration 工具來了解領域模型。

貼文有 11 年老，但是 Luigi 看起來還有在維護，UI 以現代眼光來看也不會太差。初試 Prefect 無果之後我便嘗試 Luigi，

然後沒遇到什麼問題就接著實作，最後把我的需求解決掉了。

Luigi

先講結論，程式碼在此：

https://github.com/FlySkyPie/github-issue-simple-etl

它在 Luigi 的框架下運行了 ETL：

從 GitHub 下載 Issue
利用 LLM (OpenAI-Compatible API) 翻譯
將翻譯結果做成適合閱讀的 Markdown
適度的暫存與事務 (Transaction) 操作

我用過 Jenkins 之類的 CI/CD，也用過 CMake 之類的本地自動化，這個所謂的 ETL 工具憑什麼自立一個名為 Data Orchestration 的領域？

我沒有完整的答案，但從快速瀏覽的氣流教學來看，最明顯的是它是一個自上而下的 DAG 規格，並手動建立節點之間的連接。

相比之下，Luigi 元素之間的連接是隱式的，而且是自下而上的。 ³

注意，這裡的上下不是組件的基礎與抽象的上下，而是資料上游下游的上下。CI/CD 這種需要某種東西觸發 (Git Branch 更新)的 Pipeline 就是由上而下，而由下而上更長出現在本地自動化，比如 Makefile：

main: main.o sub.o
    gcc main.o sub.o -o main
main.o: main.cpp
    gcc main.cpp -c
sub.o: sub.cpp
    gcc sub.cpp -c
clean:
    rm -rf main.o sub.o

我想要 main 的時候，會觸發它的仰賴 main.o 和 sub.o 於是自動化工具一路找到最上游還沒進行的任務把事情做掉。這一事實會讓工具變成冪等性的，而這也是 Luigi 具備但是不屬於 CI/CD 核心的特性（某些 CI/CD 會透過 Artifact 優化 Pipeline，但是不是特別重視這個特性，它們比較在意產出 latest）。

令一方面 ETL 比起本地自動化更注重分散負載，即 CI/CD 常用的 Server-Worker 架構，ETL 則是缺乏「佈署」或「觸發」的概念，因此多了一個直接操作 Pipeline 的 Client。

不過我認為 ETL 最重要的特性之一是「動態 Pipeline」，不論是 CI/CD 還是本地自動化，參數通常是一開透過設定檔、平台變數或是環境變數決定的，然後 Pipeline 的「形狀」通常是固定的，然而以我的實作為例：

實際上我只定義了五種 Task：

DownloadIssues
GenerateDocument
GenerateSingleDocument
StoreTranslation
TranslateSingleIssue

運作後的 Pipeline 中的很多實際任務節點是根據 GitHub repo 下的 Issue 數量與號碼指定的，對於一個翻譯任務節點而言，它的設定如下：

class TranslateSingleIssue(Task):
    target_repo: Parameter = Parameter(
        description="The issues of GitHub Repo going to translate",
    )

    api_base: Parameter = Parameter(
        description="API base url of OpenAI-Compatible API",
    )

    model_name: Parameter = Parameter(
        description="model name of LLM",
    )

    language_name: Parameter = Parameter(
        description="Target language of translation",
    )

    issue_number: IntParameter = IntParameter()

api_base、model_name 和 language_name 是可以在 .cfg 檔案設定的，但是 target_repo 和 issue_number 是它的下游指定的：

class GenerateSingleDocument(Task):
    def requires(self):
        return [
            TranslateSingleIssue(
                target_repo=self.target_repo,  # type: ignore
                issue_number=self.issue_number,
            )
        ]

如此一來資料操作者可以輕易的設定全域變數或是指定某個下游任務的參數，它會自己「把訂單往上游傳」然後動態的根據不同的仰賴結構建構不同的 Pipeline。

MWS 的調查結果

在我閱讀了 111 個 Issue 後，我驚訝的發現討論大部份圍繞在 ACL (Access Control List) 上，Admin UI 的討論則是次之。

專案的 ACM (Access Control Model) 選擇使用 ACL 是缺陷這個我在前一篇文章就講過了。我沒講的是 Recipe-Bag 這種多對多模型如果要處理 AuthZ (Authorization) 最簡單可靠的方式就是引入 ReBAC (Relationship-based access control)。

好，他們正在錯誤的技術決策上打轉，然後又過度關注 UI，與此同時我還是沒有一個可靠的微服務組件可以使用，怎麼回事？說到底 Recipe-Bag 這個模型到底怎麼來的？

The bags and recipes model is a reference architecture for how tiddlers can be shared between multiple wikis. It was first introduced by TiddlyWeb in 2008.⁴

於是我回去翻了一下 tiddlyweb 的 Git 紀錄：

看起來是非常早期的 commit 的引入的設計，甚至還在 SVN 時期，我大概很難找到相關討論了，總之這麼模型甚至被 TiddlyWiki 的官方文件收錄了。

另外一個發現是它們在討論某種前後端同步或是後端渲染的機制，這對我而言就是「重新發明 Next.js」！這也解釋了為什麼 API 裡面會有這麼多奇怪的 RPC (Remote procedure call)。

最後讓我得出結論的是這個，MWS 的主要貢獻者說道：

Docker itself doesn't strike me as being very friendly to new users. I'm not sure how you mean we should support Docker Compose.⁵

如果一個後端專案的主力開發者無法正視 Docker 在現代生態系的意義，那這個專案可以丟進垃圾桶了。

下一步

tiddlyweb 用 repomix 打包只有 600 KiB 左右，反觀 MWS 則是 2 MiB，tiddlyweb 抽出來的 OpenAPI 也比較簡潔，沒有 ACL 或是「類 Nest.js」造成的臃腫。我決定把 tiddlyweb 作為 rewrite 對象而不是 MWS。

後記

最近我意外得知，研究方法中除了定量分析以外，還有一種注重少量樣本與群體，更重視「故事」與「脈絡」的質性研究。這才意識到自己其實是對軟體專案進行質性研究呢。

Example – Top Artists — Luigi 3.8.1 documentation. https://luigi.readthedocs.io/en/stable/example_top_artists.html ↩
用 Luigi 在 Python 裡建資料管道 : r/Python. https://www.reddit.com/r/Python/comments/3rjkry/comment/cwppm86/?tl=zh-hant&utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button ↩
用 Luigi 在 Python 裡建資料管道 : r/Python. https://www.reddit.com/r/Python/comments/3rjkry/comment/cwppm86/?tl=zh-hant&utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button ↩
Bags and Recipes: TiddlyWiki v5.4.0 — a non-linear personal web notebook. https://tiddlywiki.com/static/Bags%2520and%2520Recipes.html ↩
Feature Request: Support installation and deployment using Docker Compose · Issue #122 · TiddlyWiki/MultiWikiServer. https://github.com/TiddlyWiki/MultiWikiServer/issues/122#issuecomment-3702946673 ↩

TiddlyRAG Dev Log - MWS API

May 30, 2026

Wei Ji

閃亮症候群工程屍

前情提要

POC Type-A 探索了向量資料庫、嵌入模型並對外暴露 MCP (Model Context Protocol)：

POC Type-B 探索了 AsyncFuncAI/deepwiki-open 專案處理「如何把 Git Repo 轉換成文件？」這個問題的方式，並做出了一些改良，其中一個重點改良是將 Git Repo 微服務化，TiddlyRAG 不直接與檔案系統中的 Git Repo 互動，而是透過 Gitea 提供的 API：

如此一來 Git Repo 相關的業務邏輯就變成了 TiddlyRAG 不關注的通用域問題。舉例來說，TiddlyRAG 不再需要考慮 git clone 失敗與否產生的各種 edge case，只需要呼叫 Gitea 中 migrate 的 API 即可。

透過 HTTP API 操作，更容易實現權限控制與訪問審計等需求，這在基於 LLM 建構的智能體 (Agent) 系統帶來的不可空性中顯得更為重要。

POC Type-C 探索了 ECS (Entity-Component-System) 與行為樹 (Behavior Tree) 建構的智能體框架：

並實做了簡單的深度優先遍歷與廣度優先遍歷作為概念驗證。

TiddlyWiki 微服務

在 POC Type-A 中，TiddlyWiki 是以相對隨便定義的方式儲存在 TiddlyRAG 內的資料庫中，但是就像 POC Type-B 處理的問題一樣，「TiddlyWiki」的儲存並不是 TiddlyRAG 關注的問題，因此在 TiddlyRAG 的微服務架構中，應該要有一個專門用儲存 TiddlyWiki 的實例。

以下是我經過調查，跟這個主題有關的專案：

https://github.com/Arlen22/TiddlyServer
- 265 ⭐
https://github.com/tiddlyhost/tiddlyhost-com
- 222 ⭐
https://github.com/tiddlyweb/tiddlyweb
- 104 ⭐
https://github.com/TiddlyWiki/MultiWikiServer
- 54 ⭐

TiddlyServer 的作者同時也是 MultiWikiServer 的主要貢獻者，並且在 README 明確的表明該專案已經中止，後續的開發能量會轉移給 MultiWikiServer。

tiddlyhost-com 雖然有「多租戶」的概念，但是它的主要運作方式是以 static asset 的方式 serve 多個 TiddlyWiki 檔案，因此就算它有 API，原子操作也是 TddilyWiki （整個網頁）而不是 Tiddler （條目）。

tiddlyweb 是完全以 Python 實做的伺服器，然而大部分實作依然停留在 Python 2.7 時期，甚至連 Python 3.3 的遷移也尚未完成就已經中止開發。

並且它是基於 TiddlyWiki 2.0 設計的，現代的 TiddlyWiki (TW5) 要使用這個專案必須做一些調整¹。

MultiWikiServer 似乎是 TiddlyWiki 生態系中以官方的角色建構的「TiddlyWiki 微服務後端方案」，然而它依然存在一些問題。

MWS 的問題

接下來解釋一下 MWS (MultiWikiServer) 有哪些問題，如果依照 README 上的指南試著建立環境：

npm init @tiddlywiki/mws@latest my-folder
cd my-folder
npx mws init-store
npx mws listen --listener

會遇到很多光怪陸離的事情。

其他套件管理工具不友善

因為在 @tiddlywiki/create-mws 寫死 npm，所以就用：

pnpm create @tiddlywiki/mws@latest my-folder

得到的 node_modules 會報錯。

hard code 仰賴

試圖安裝並執行 mws 指令時也會報錯，因為：

{
  "dependencies": {
    "prisma-client": "file:prisma/client",
  }
}

package.json 的仰賴是寫死的。

Docker 安裝

如果依照 README 的 docker 安裝步驟：

# Create your data directory
mkdir my-mws-data
cd my-mws-data

# Download the required files
curl -O https://raw.githubusercontent.com/TiddlyWiki/MultiWikiServer/main/docker-compose.directory.yml
curl -O https://raw.githubusercontent.com/TiddlyWiki/MultiWikiServer/main/Dockerfile

# Create store directory
mkdir -p store

# Start MWS
docker-compose -f docker-compose.directory.yml up -d

# Initialize the database (required on first run)
docker-compose -f docker-compose.directory.yml exec mws npx mws init-store

# Access at http://localhost:8080
# Default credentials: admin / 1234

則會得到一個非常簡易的 React.js 前端頁面。

設計哲學與程式風格

MWS 的設計依然部份延續 TiddlyWiki 的路徑，也就是軟體邊界模糊（前後端不分），以及為了保持自舉的特性，很多功能不使用函式庫而是自己重複造輪子。

舉例來說，透過 Docker 運行起來後，我的瀏覽器插件顯示它的前端使用 React，於是我便調查一下的程式碼，確實有前後端分離的跡象，但是依然出現疑似 JSX 輪子的東西：

packages/jsx-runtime/jsx-render.ts

import { MaybeArray } from "./jsx-utils";

export const JSXElementSymbol: unique symbol = Symbol("__is_jsx_element__");

const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
const MATH_NAMESPACE = "http://www.w3.org/1998/Math/MathML";
const SVG_NAMESPACE = "http://www.w3.org/2000/svg";

const OldPropsSymbol: unique symbol = Symbol("__old_props__");
const KeyChildren: unique symbol = Symbol("__key_children__");
const OwnKeySymbol: unique symbol = Symbol("__own_key__");
const DOMElementSymbol: unique symbol = Symbol("__dom_element__");

const observer = new MutationObserver((mutations) => {
  for (const mutation of mutations) {
    const callbacks = observerCallbacks.get(mutation.target as Element);
    if (callbacks) for (const cb of callbacks) cb();
  }
});

const observerCallbacks = new WeakMap<Element, (() => void)[]>();

export function render(root: Element | DocumentFragment, child: MaybeArray<JSX.Node>) {
  updateChildren(root, [child].flat(Infinity) as JSX.Node[]);
}

另一方面則是不使用 Express.js 之類主流的後端路由框架，而是自己創造另外一種模式：

packages/mws/src/managers/wiki-external.ts

  handleLoadBagTiddler = zodRoute({
    method: ["GET", "HEAD"],
    path: BAG_PREFIX + "/:bag_name/tiddlers/:title",
    bodyFormat: "ignore",
    zodPathParams: z => ({
      bag_name: z.prismaField("Bags", "bag_name", "string"),
      title: z.prismaField("Tiddlers", "title", "string"),
    }),
    inner: async (state) => {
      const { bag_name, title } = state.pathParams;
      const bag = await state.assertBagAccess(bag_name, false);
      throw await state.$transaction(async (prisma) => {
        const server = new WikiStateStore(state, prisma);
        return await server.serveBagTiddler(bag.bag_id, bag_name, title);
      });
    }
  });

或是手刻 HTTP body 解析：

packages/mws/src/managers/wiki-utils.ts

export async function recieveTiddlerMultipartUpload(state: ZodState<"POST", "stream", any, any, zod.ZodTypeAny>) {

  // Process the incoming data
  const inboxName = new Date().toISOString().replace(/:/g, "-");
  const inboxPath = resolve(state.config.storePath, "inbox", inboxName);
  mkdirSync(inboxPath, { recursive: true });

  const parts: MultipartPart[] = [];

  interface UploadPart2 {
    inboxFilename?: string;
    value?: string;
    hasher?: Hash;
    length: number;
    fileStream?: Writable;
    hash?: string;
  }

  const incomingParts = new WeakMap<MultipartPart, UploadPart2>();
  const inboxFiles = new WeakMap<MultipartPart, string>();
  const valueParts = new WeakMap<MultipartPart, string>();

  await state.readMultipartData({
    cbPartStart: async function (part) {
      const part2: UploadPart2 = {
        hasher: createHash("sha-256"),
        length: 0,
      };

      if (part.filename) {
        const inboxFilename = (parts.length).toString();
        const inboxFilename2 = resolve(inboxPath, inboxFilename);
        part2.fileStream = createWriteStream(inboxFilename2);
        inboxFiles.set(part, inboxFilename2);
      } else {
        part2.value = "";
      }

    },
    cbPartChunk: async function (part, chunk) {
      const part2 = incomingParts.get(part)!;
      if (part2.fileStream) {
        await new Promise<void>((res) => {
          part2.fileStream!.write(chunk) ? res() : part2.fileStream!.once("drain", () => res());
        });
      } else {
        const encoding = part.headers.get("content-type")?.charset || "utf8";
        if (!Buffer.isEncoding(encoding)) {
          throw new SendError("MULTIPART_INVALID_PART_ENCODING", 400, {
            partIndex: parts.length,
            partEncoding: encoding,
          });
        }
        part2.value! += chunk.toString(encoding as BufferEncoding);
      }
      part2.length += chunk.length;
      part2.hasher!.update(chunk);
    },
    cbPartEnd: async function (part) {
      const part2 = incomingParts.get(part)!;

      if (part2.fileStream) part2.fileStream.end();
      else valueParts.set(part, part2.value ?? "");

      part2.hash = part2.hasher!.digest("base64url");
      part2.fileStream = undefined;
      part2.hasher = undefined;
      incomingParts.delete(part);
      parts.push(part);
    },
  });

  const partFile = parts.find(part => part.name === "file-to-upload" && !!part.filename);

  if (!partFile) throw state.sendSimple(400, "Missing file to upload");

  const missingfilename = "File uploaded " + new Date().toISOString();

  const type = partFile.headers.get("content-type")?.mediaType;
  const tiddlerFields: TiddlerFields = { title: partFile.filename ?? missingfilename, type, };

  for (const part of parts) {
    const tiddlerFieldPrefix = "tiddler-field-";
    if (part.name?.startsWith(tiddlerFieldPrefix)) {
      const name = part.name.slice(tiddlerFieldPrefix.length);
      const value = valueParts.get(part)?.trim() ?? "";
      (tiddlerFields as any)[name] = value;
    }
  }

  const contentTypeInfo = state.config.getContentType(type);

  const file = await readFile(inboxFiles.get(partFile)!);

  tiddlerFields.text = file.toString(contentTypeInfo.encoding as BufferEncoding);

  rmSync(inboxPath, { recursive: true, force: true });

  return tiddlerFields;
}

結論與策略

MWS 依然處於非常早期的開發狀態，並沒有穩定到足夠被當作微服務使用，另外它已經實作一些 ACL (Access Control List) 相關的邏輯，如果在缺乏配套的情況下在 POC 中當作微服務使用會構成阻礙。例如：缺乏聲明式配置，必須手動初始化使用者，或是想要進行簡單的 CRUD 卻被 ACL 的 bug 阻擋。

然而就算撇開「開發早期」這個條件不談，差勁的程式碼職責分離除了會造成專案的成長受限以外（實作偏離範式，其他開發者看不懂、無法理解就無法貢獻），這種程式碼很容易產生漏洞，產生漏洞就不能有可靠的安全性保證，造成其身份驗證的功能虛有其表、形同虛設，不只無法提供安全性，反而拖累開發能量。經過調查之後我還發現它的 ACM (Access Control Model) 有根本性的缺陷，這個等等再補充。

因此我打算採取的策略是，根據原始實作抽出 HTTP API 界面，並使用它的資料庫設計當作參考，直接用 NestJS 重新實做，建立一個「MWS API 兼容伺服器」。

一來是出於對官方原始設計的尊重，並且透過兼容的方式避免跟 TiddyWiki 原始的生態系走太遠。二來是當我的實作走得比較前面時，發現的問題或解決方案可以反過來向 TiddlyWiki 的官方回報或貢獻。

目前進展

經過三天的研究，已經成功抽出 API 定義並且用 OpenAPI YAML 紀錄：

LLM (Large Language Model) 非常擅長幹這種事情，不過隨著進展到特定 API 的細節時往往還是會發現錯誤（幻覺），所以需要在原始實作跟生成的文件中來回閱讀。

昨天進展到這幾個 API 的實做時：

POST /bag/{bag_name}/tiddlers
POST /admin/bag_create_or_update

才開始研究 API 行為跟資料庫之間的互動具體是怎麼進行的。

我們可以看到 Tiddler （條目）實際上是被掛在 Bag （知識包）之下，並且有一個名為 Recipe 的抽象會決定一個 TiddlyWiki 最後要長怎樣。同時 MWS 存在這樣的 API：

這是一個類似 OverlayFS 的設計，POST "/recipe/:recipe_name/tiddlers"，實際上是去找到最上層的 Bag 進行寫入。這個模型設計似乎是延續自 TiddlyWeb。

然而我看到這裡我就瞬間感覺使用 ACL 是一個錯誤的技術決策。Recipe 和 Bag 是多對多關係，同時 Tiddler 的操作界面是 Recipe 的視角看過去，這種關聯性授權 (Authorization) 控制應該由 ReBAC (Relationship-based access control) 處理。

況且我的目的是建立一個支援多租戶邏輯的 TiddlyWiki 的儲存實例，AuthN/AuthZ (Authentication/Authorization) 不是我首要關注的問題。

TiddlyWiki in the Sky (or TiddlyWeb for TW5) - Pleasant Programmer. Retrieved 2026-05-30, from https://pleasantprogrammer.com/posts/tiddlywiki-in-the-sky-or-tiddlyweb-for-tw5.html ↩

TiddlyRAG Dev Log

May 18, 2026

Wei Ji

閃亮症候群工程屍

前情提要

TiddlyRAG 的概念最早我在這篇文章就已經提出：

2025-10-06 一種人類友善 llms.txt 構想

試著在本地運行嵌入模型：

2026-03-12 llama.cpp 本地嵌入伺服器初體驗

調查幾個開源 LLM 應用程式在處理 RAG 相關的功能：

完成 POC Type-A，能夠匯入 TiddlyRAG 進行嵌入；並透過 MCP 進行檢索：

2026-04-28 POC Type-A

研究卡片化 (Zettelize) 的其中用例，將 Git Repo 轉換成文件，調查已經存在的實作，沒想到卻十分差勁：

2026-05-01 從 Zettelize 到糞坑：評點 deepwiki-open 程式碼

完成 POC Type-B，試著從 deepwiki-open 抽出部份邏輯重新實做：

2026-05-06 POC Type-B

接著回到本文的重點。

僵化的資料探勘策略

deepwiki-open 的實作方式是採取兩步驟：

建立大綱（8~12頁）。
根據大綱對每一頁生成內容。

並且輸入是從事先把所有文件嵌入的資料中檢索 20 個檔案出來，但是我實際實驗發現在特定情況會有問題。

以 deepwiki-open 自己的 Repo 為例，它包含了 10 個不同語言的 README，因此使用 README 進行向量檢索的時候，會得到一堆不同語言的 README 跟一些 i18n 的檔案，完全不能作為有效的參考資訊。

所以我完成 POC Type-B 到一個程度後沒打算繼續深入，因為這明顯是一條死路。

根本性的原因是僵化的資料探勘策略，Git Repo 的不確定性很高：

這是一個後端/後端/嵌入式系統/函式庫/UI 庫...專案？
這是一個程式專案？
這是一個文件專案？
這是一個 Monorepo？
這是很多 Microservice？
...

需要一種非固定流水線 (Pipeline) 的機制才有可能處理這種不確定性。

決策算法

我的直覺是透過行為樹 (Behavior Tree) 建立兼富彈性與可控性的資料探勘策略，不過在正式使用以前，我需要調查一下同樣在遊戲界常用的演算法，因此有了以下幾篇文章：

GOAP 和 HTN 建立在 STRIPS 模型之上，而 STRIPS 模型要求建模者必須對環境有一定程度的理解與掌控，用在遊戲環境沒問題（環境是遊戲開發者自己設定的），但是在 Git Repo 這種不確定性高的環境就顯得不合適。

Utility AI 是另外一個遊戲常用的古典 AI，它的行為比較簡單我就沒有特別深入研究寫文章了，基本上運作機制很接近感知機 (Perceptron) 配上可客製化的激勵函數，所以它的可預測性與可解釋性比 BT (Behavior Tree) 來得差。

所以最後還是選擇行為樹。

行為樹生態

下一步是了解行為樹的生態，一個完整的行為樹解決方案應該包含以下條件：

Runtime SDK：用來運行 BT 的函式庫。
序列化與反序列化：BT 能夠以檔案形式存在，而不是硬編碼在程式內。
日誌：運行時紀錄下 BT 的狀態，用於事後除錯。
靜態視覺化：能夠以 GUI 瀏覽 BT 檔案。
動態視覺化：能夠以 GUI 遙測或模擬 BT。
視覺化編輯器：能夠以 GUI 編輯行為樹。

話雖如此，但是不考慮遊戲引擎生態的，因為它們的 BT 通常和遊戲引擎高度整合。因此條件變得更嚴苛了，要滿足上述條件還要有解偶與高內聚的特性。

BehaviorTree.CPP 是唯一一個我找到滿足上述條件的，另外一個發現是看來 BT 不只是用在遊戲產業，（實體）機器人產業似乎也有使用。

BehaviorTree.CPP 生態系內一款名為 Groot 的視覺化工具，包含了編輯、遙測與回放功能，乍看之下似乎很完美。就算我另外用 Javascript 做，只要照著 Spec 刻就能對接 BehaviorTree.CPP 的生態系直接使用 Groot。

然而隨著深入調查卻發現不盡人意的事實，Groot 1 不再維護，且僅支援到 BehaviorTree.CPP 3.X （最新版為 4.9），Groot 2 則採取閉源訂閱制付費的方案。

接著我一邊看著 Mistreevous 的行為與文件，並和 BehaviorTree.CPP 的文件比較，我發現我無法理解「正宗行為樹」的邏輯應該為何。BehaviorTree.CPP 的文件經常使用反應式 (Reactive)、非同步 (Async)、觸發 (Trigger)、中斷 (Interrupt)...等詞彙，但是根據描述我又無法跟我平時開發 Javascript 的經驗做連結。

於是我花了一、兩天整理了行為樹的一些先備知識：

https://flyskypie.github.io/microproject-wikis/behavior-tree.html

簡單來說：

BT 最早是無狀態的，但是因為這樣每個 Cycle 都需要重新遍歷，這在大型或複雜的樹中會造成效能方面的問題。

於是狀態被引入了，讓下一個 Cycle 可以根據情況從特定的節點開始檢查，減少重複運算。但是這造成另外一個問題，當環境發生變化時，行為樹無法適應這些變化，因為一些檢查被跳過去了。

於是反應式 (Reactive)、非同步 (Async)、觸發 (Trigger)、中斷 (Interrupt) ...之類概念又被引入，用於抵銷狀態帶來的行為；可以在有狀態的 Scope 下條件性的觸發重新遍歷。

這個歷史過程造成了一些概念上的混淆，然而大部分 BT 教學並沒有提及這個過程。

如果不把一些觀念釐清（Cycle vs Tick, 有狀態 vs 無狀態），跟 LLM 討論會陷入雞同鴨講的情況。

Javascript 行為樹技術選型

調查了一下列一個清單：

https://github.com/behavior3/behavior3js
- 428 ⭐
- https://github.com/behavior3/behavior3editor
  - 701 ⭐
- https://github.com/renatopp/behavior3js
  - 145 ⭐
- https://github.com/renatopp/behavior3js/wiki/JSON
- https://github.com/mybios/behavior3-typescript
  - Typescript Fork
https://github.com/Calamari/BehaviorTree.js
- 339 ⭐
- https://github.com/Calamari/BehaviorTree.js-Examples
https://github.com/yantra-core/Sutra.js
- 188 ⭐
- 作者大概非常不喜歡 Typescript¹
https://github.com/nikkorn/mistreevous
- 132 ⭐
- 作者大概很喜歡 Typescript
- https://github.com/nikkorn/mistreevous-visualiser

behavior3js 乍看是聲望最高、又有視覺化工具，但是它自 2018 年以來就沒有更新了，而且文件十分凌亂，分散在程式碼內、GitHub Wiki、死掉的網站連結...內，所以我沒辦法快速的搞清楚這東西要怎麼使用。

BehaviorTree.js 則是 2021 年以來沒有更新，2026 年有推出支援 Typescript 的 beta 版本，不過缺乏生態系其他配套（特別是視覺化）。

Sutra.js 就算撇除作者在 Reddit 跟別人筆戰「Javascript 不需要型別」以外，README 映入眼簾的是 if/else 語法以及事件驅動等功能，完全背離 BT 的設計哲學。並且同樣缺乏 BT 視覺化配套。

Mistreevous 的聲望（星星數）並不是最高的，但是從文件的易用性、原生 Typescript 支援、視覺化的支援、序列化與反序列化的重視程度...綜合考量下是一個優秀的選擇。

具體差異我就不在這邊解釋，情況有一點複雜。

資料組織方案

這邊我要先補充一個關於 BT 的先備知識，BT 原則上是無狀態的，典型的 BT 會使用「黑板模式」：所有狀態是儲存在一個叫做黑板 (blackboard) 的東西裡面，簡單來說就是一個 key-value 表，然而實務上容易變成「一堆放在一起的全域變數」。

這對我而言是無法接受的，而碰巧我有使用 ECS (Entity-Component-System) 的經驗：

ECS 學習與 aimAndShoot 重構之旅

於是這件事就這樣自然發生了：

簡單來說 ECS 和 BT 都遵守 DoP (Data-oriented programming) 的哲學，因此資料跟邏輯本來就解偶了，所以把 ECS 中處理的資料的 EC 嫁接到 BT 上非常容易。

POC

結論，我完成了一個能夠在「深度優先遍歷」與「廣度優先遍歷」切換的 BT：

https://github.com/FlySkyPie/tiddlyrag-poc/tree/poc/type-c

「僵化的資料探勘策略」的問題並未完全解決，但是 POC 的策略就是一次只驗證一件事情，我認為完成一個具有彈性的 BT 框架就算完成階段性任務了。

下一步？

以下節錄自我的腦力激盪過程：

原始的設計期望透過「逐步探索」的方式來降低無用的資訊，並假設可以無須遍歷所有檔案，但是這個構想當中存在著謬誤。

LOD (Level of Development) 是在多媒體中經常被使用的技巧，白話來說就是越不重要的東西做得越粗糙，其中一個經典的應用就是遊戲場景，遠景時使用低面數、粗糙的模型，當攝影機拉近時再切換成高面數、精緻的模型。

但是即便如此，LOD 能夠運作的前提是先有一個高面數的理想模型，再對其進行降低面數的處理，因此低模存在的前提是該模型的細緻特徵已知。

再回過頭看原始「逐步探索」的設計就顯得不合理，因為資訊聚合 (Aggregation) 的前提是要先具備完整資訊。

最後我將這個問題定位為：探索與利用問題 (Exploration and Exploitation)。

我已經稍微回顧了：

多臂老虎機問題 (multi-armed bandit problem, MAB)
ϵ-greedy
UCB (Upper Confidence Bound)
Thompson Sampling

下一步的重點可能會放在「如何用蒙地卡羅樹搜尋 (MCTS, Monte Carlo tree search) 解決這個資料探勘問題」上。

題外話

因為 TiddlyRAG 這個 Side Project 我也跑好一陣子了，最近想該給它一個正式的 LOGO 了，於是這張圖就產生了：

Sutra.js - Fluent Behavior Trees for JavaScript Game Development : r/javascript. https://www.reddit.com/r/javascript/comments/194e8ef/ ↩

軟體壟斷 (Monopoly)​

壟斷抽象層​

我壟斷我自己​

曌銕重工​

第一章 總則​

第二章 會員​

第三章 組織及職權​

第四章 會議​

第五章 經費及會計​

第六章 附則​

結論​

前情提要​

Zod Schema​

由上而下的嘗試​

Bob​

GCP 重度仰賴​

過期的進入點​

小結​

補充​

前情提要​

無線網路瓶頸​

llama.cpp 越來越胖了​

Gemma 4 很肥​

llama.cpp 呼叫 Hugging Face 的行為​

llama.cpp 的架構問題​

Docker Registry API V2​

OCI AI Payload​

OCR 模型表現不穩定​

llama.cpp 快取失蹤​

模型下載問題​

Footnotes​

前情提要​

雲端 LLM​

地端 LLM​

後記​

前情提要​

簡短結論​

原訂計畫​

重構（遷移）過程與程式碼回顧​

OOP​

Facade 模式​

Overlay​

測試案例​

MemTextStoreHelper​

結論​

前情提要​

翻譯 ETL​

Luigi​

MWS 的調查結果​

下一步​

後記​

Footnotes​

前情提要​

TiddlyWiki 微服務​

MWS 的問題​

其他套件管理工具不友善​

hard code 仰賴​

Docker 安裝​

設計哲學與程式風格​

結論與策略​

目前進展​

Footnotes​

前情提要​

僵化的資料探勘策略​

決策算法​

行為樹生態​

Javascript 行為樹技術選型​

資料組織方案​

POC​

下一步？​

題外話​

Footnotes​

軟體壟斷 (Monopoly)

壟斷抽象層

我壟斷我自己

曌銕重工

第一章總則

第二章會員

第三章組織及職權

第四章會議

第五章經費及會計

第六章附則

結論

前情提要

Zod Schema

由上而下的嘗試

Bob

GCP 重度仰賴

過期的進入點

小結

補充

前情提要

無線網路瓶頸

llama.cpp 越來越胖了

Gemma 4 很肥

llama.cpp 呼叫 Hugging Face 的行為

llama.cpp 的架構問題

Docker Registry API V2

OCI AI Payload

OCR 模型表現不穩定

llama.cpp 快取失蹤

模型下載問題

Footnotes

前情提要

雲端 LLM

地端 LLM

後記

前情提要

簡短結論

原訂計畫

重構（遷移）過程與程式碼回顧

OOP

Facade 模式

Overlay

測試案例

`MemTextStoreHelper`

結論

前情提要

翻譯 ETL

Luigi

MWS 的調查結果

下一步

後記

Footnotes

前情提要

TiddlyWiki 微服務

MWS 的問題

其他套件管理工具不友善

hard code 仰賴

Docker 安裝

設計哲學與程式風格

結論與策略

目前進展

Footnotes

前情提要

僵化的資料探勘策略

決策算法

行為樹生態

Javascript 行為樹技術選型

資料組織方案

POC

下一步？

題外話

Footnotes