參考實作
目前狀態:1 個範例
節奏是一天一個。累積速度會比一次寫一份大文件慢,但每一個都是可以打開、可以執行、可以被反駁的東西。
每個範例必須成立的四件事
這不是編輯建議,是 scripts/build-mssp.mjs 強制的契約。任何一項失敗,範例不會被發佈——而不是發佈後在頁面上標註警告。
一、它真的會跑。 meta.yaml 裡的 runnable 指令會被執行,非零離開碼直接讓 build 失敗。
二、沒有任何 TMS 引用兄弟 TMS。 機械檢查,不靠人眼。一個 TMS 單元的定義是「帶有 index 檔的目錄,否則就是單一檔案」——所以放在同一個分類目錄下的兩個檔案是兩個單元,它們之間的 import 是違規。
三、沒有空的集合目錄。 一個空的 TMS/ 什麼也沒教,卻暗示了不存在的結構。
四、README 必須寫出「這個範例沒有解決什麼」。 沒有這一節,build 失敗。
一個範例只示範一個決策
示範四件事的範例,一件也沒示範成。
好的題目長這樣:
- 把某個能力從 TMS 升到 SMS,以及升上去之後什麼壞了
- 兩個 TMS 想互相引用,SMS 契約如何解決(001 號)
- 一個 runtime 真的能檢查的 SCL 權限
- 一個把「執行成功」變成人類可驗證的 DMS 視圖
- 同一支程式重構前後,耦合量測的差別
不好的題目:「MSSP 應用於 X」而沒有具體決策,或者重寫一個大型框架。
反例是合法的範例
契約支援 kind: counterexample。刻意示範錯誤結構的範例會被網站標上警語,讓沒有人會照抄。
這一類其實比正面範例更需要:多數人不是不知道好結構長什麼樣,而是分不出自己手上的東西屬於哪一種。
每個範例都要標出「度」
這些範例大多刻意用小問題,因為小問題才能在一次閱讀裡看完整個結構。代價是:範例本身的規模通常低於它示範的結構真正划算的門檻。
所以每個範例的 README 都要說清楚自己站在哪個位置。001 號寫的是:
306 行程式碼分散在 13 個檔案。五個集合放在這裡是為了讓各部分可見;在這個規模上,兩個檔案也能寫完。要看這個結構真正換到什麼,把同樣的邊界放到門檻描述的規模上。
這一節的用途不是自我否定,而是教學用的比例尺。讀者要能分辨「這裡示範的是結構」和「這裡示範的是這個結構在正確規模上的收益」——兩者都需要,但混在一起會讓人以為方法只適用於玩具,或者反過來以為任何規模都該全套上。
路線
從小型可運行範例,逐步推進到遊戲運行框架、Agent 與世界狀態系統。這個順序不是難度排序,是驗證強度排序:小範例能被完整檢查,大系統只能被抽樣。
在能被完整檢查的規模上先把方法弄對,比在無法驗證的規模上宣稱它有效重要。
接下來要示範的
- Router。 當任務選擇不再是一次查表的時候。
- 版本與遷移。 契約改變時,舊輸入怎麼轉、舊 TMS 還能不能掛載。
- 多語言。 契約本身不綁語言;先補上另一個有真正模組邊界的語言,順便測試依賴檢查在那裡是不是可以更強。
- 中型規模的完整案例。 目前的範例都在示範單一結構;一個真的在門檻上的專案,能讓「度」從說明變成可以量的東西。