Ian Chou's Blog

CtxFST CH12 - v2.0 落地：為什麼我把它重構成 World Model First

CtxFST CH12：v2.0 落地，為什麼我把它重構成 World Model First

如果 CH11 是架構宣言，那這一章就是實際落地後的交代。

前一章我講的是：

CtxFST 不該只是一個 chunking format，
它應該升級成 agent-ready 的 semantic world model format。

這句話如果只是停在概念層，還不夠。

因為一旦你真的決定往這個方向走，就不只是多加幾個欄位而已，而是整個 repo 的定位都要一起改：

而且更關鍵的是：

如果 world model 才是 CtxFST 的核心價值，那它就不該繼續藏在 optional addon 裡。

所以這次我做的，不是小修小補，而是一次很明確的定位重構：

CtxFST v2.0 從「GraphRAG chunk format」正式轉向「Semantic World Model Format」。

先說結論：這一章是一定要寫的

我認為這章不只是「可以寫」，而是「必須寫」。

原因很簡單。

如果你已經把 repo 重構成 World Model First，但文章還停留在舊心智模型，讀者就會發生三種誤解：

  1. 以為 CtxFST 只是多加了幾個 optional 欄位
  2. 以為 state / action / goal 只是邊緣功能
  3. 以為這次重構只是為了 agent demo，不是規格主體

這三個理解都會讓 v2.0 的價值被稀釋掉。

所以這章最重要的任務不是列 changelog，而是幫讀者換掉舊心智模型。

從 Additive Layer 到 World Model First，差在哪？

先看最簡單的對照。

舊理解

CtxFST = chunk format
       + entity layer
       + similarity graph
       + optional world model fields

這種理解下，world model 只是附加能力。

新理解

CtxFST = semantic world model format
       = chunks + entities + states + actions + goals + edges + runtime contracts

這種理解下：

它們全部一起變成 world model 的一級公民。

這個轉向，才是 v2.0 真正的 breaking point。

為什麼我最後接受 breaking change？

因為如果一個系統真正的價值主張已經變了，但規格還故意維持舊定位，最後只會讓兩邊都不清楚。

更白話地說：

那使用者最後只會把你當成又一個分塊工具。

這對 CtxFST 其實很傷。

所以我現在的看法很直接：

如果 world model 是主軸，就要把 world model 寫成主軸。

即使這意味著：

這反而比較誠實，也比較有產品辨識度。

這次重構，真正改了哪些東西？

如果從 repo 層級來看，這次 v2.0 重構不是改一個檔，而是把整個 contract 重排了一遍。

1. README 的產品定位變了

這一步看起來像文案，其實很重要。

以前如果 README 主打的是：

那讀者進 repo 的第一眼直覺就會是：

這是一個為 RAG 做資料整理的格式。

但 v2.0 應該改成：

這是一個給 agent / semantic graph / world state 使用的 semantic world model format。

這個調整看起來像 marketing，其實不是。

它會直接影響：

所以 README 重寫，不是附帶工作，而是架構重構的一部分。

2. Spec 的主語變了

這次最根本的變化，其實是 spec 的主語從：

文件如何被切成可檢索 chunk

變成：

一個 agent 可操作的語意世界，應該如何被描述

這看起來只是敘事方式改了，但其實會連帶影響整份規格的優先順序。

在舊視角裡，重要的是：

在新視角裡，重要的是：

也就是說，v2.0 的 spec 不只是「舊規格加幾段」，而是整個問題定義都換了。

3. Schema 不再只描述概念，也要描述狀態與行動

這次 schema 最大的觀念改變，是 entity type 不再只服務知識圖，而要服務 world model。

所以除了原本的：

還要把下面這些 type 拉進核心視野：

這代表 schema 現在不只是在描述：

世界裡有什麼概念？

而是在描述：

世界現在處於什麼狀態？有哪些可執行動作？目標是什麼？證據在哪裡？

這個差別，就是 semantic graph 與 world model 的分水嶺。

4. Edge 不再只有相似，而是世界轉移的一部分

在 v1.x 裡，edge 的重心非常清楚：

這當然很有價值，因為它能幫你：

但 world model 需要的，不只是「像不像」，而是「能不能走」。

所以 v2.0 的 edge vocabulary 必須擴到至少這些：

這件事很重要，因為它直接改變 graph 的用途：

也就是說，graph 從「概念空間」進一步升級成「可轉移空間」。

5. SKILL.md 不再只是技能描述，而是 action contract

這次我覺得最值得強調的一點，就是 SKILL.md 的身份改變。

以前它比較像：

現在它更像：

也就是說，一份 SKILL.md 至少該能回答：

這才是 world model 裡真正的 action 定義。

如果沒有這層，agent 雖然有技能，但不知道它們在圖上扮演什麼角色。

6. Runtime layer 從旁支變成核心

如果說前幾個改動都還能被理解成「規格升級」，那 runtime layer 就是整個 v2.0 真的踏進 agent world 的證據。

因為一旦有了：

你就已經不是單純在處理靜態知識，而是在處理：

一個會隨著 action 執行而演化的世界。

這層一出現，CtxFST 的性質就變了。

它不再只是資料格式，而是進入了「操作環境描述層」。

你這次修掉的 3 個問題，為什麼很重要？

這次 feedback 裡的三個問題，我認為都不是小 bug，而是 world model contract 是否可信的關鍵。

問題 1：Namespace mismatch

你把原本混用的 state: prefix 統一改成 entity:，這件事非常對。

原因是 world model 最怕的不是欄位多，而是：

同一個系統裡，ID 命名空間不一致。

如果 graph layer 用一套 ID，runtime layer 又用另一套 ID，那後面一定會出現：

所以這不是命名潔癖，而是跨層 contract 一致性的基本功。

問題 2：Validation 太鬆

你強化 validate_chunks.py，要求：

真的指向 type == state 的 entity，這件事也非常重要。

因為 world model 的可用性，很大一部分取決於：

這些欄位到底是真的有語意，還是只是看起來像 state 的字串。

如果 validation 不夠嚴格，最後會發生一個很危險的情況：

這時系統最麻煩，因為它不是直接爆，而是默默產生錯誤推理。

所以 strict validation 在 v2.0 不是 nice to have，而是必要條件。

問題 3：Graph output compliance 不夠硬

你把 build_entity_graph.py 對未知 relation 的處理改成直接 sys.exit(1)，我覺得也是對的。

因為 v2.0 一旦把 graph 升級成 operational graph，edge relation 就不只是註解，而是系統語意的一部分。

如果 relation type 拼錯、亂寫、或不在規範裡，還照樣輸出成功，那後面所有依賴 relation 的邏輯都會一起被污染。

所以這裡不能只是 warning。

它應該被視為：

world model contract violated

既然 contract 壞了，就該 fail fast。

這次重構後，新的心智模型應該怎麼記？

如果要我用最簡單的方式重新定義 CtxFST v2.0，我會這樣教：

1. chunks

不是單純切段，而是世界中的可引用語意證據。

2. entities

不是單純抽取出的關鍵概念，而是世界裡可被識別、可被連線、可被推理的節點。

3. state

不是附加 metadata，而是 world model 的當前條件。

4. action

不是抽象概念，而是 agent 真正可執行的 primitive。

5. SKILL.md

不是使用說明，而是把 action 的 preconditions / postconditions / routing hints 明文化的 contract。

6. entity-graph.json

不是只有 similarity 的知識圖，而是同時承載導航邊與操作邊的 world graph。

7. world-state.json

不是 export 產物，而是 session 中世界目前狀態的 runtime snapshot。

如果把這七點記住，v2.0 的理解就會很穩。

一張圖看懂這次重構

flowchart LR
    A[Markdown / CtxFST Document] --> B[Chunks
semantic evidence]
    A --> C[Entities
skills states actions goals]
    C --> D[World Graph
SIMILAR REQUIRES LEADS_TO]
    E[SKILL.md
preconditions postconditions] --> F[Skill Selector]
    D --> F
    G[world-state.json
active states completed skills] --> F
    F --> H[Execute Skill]
    H --> I[Runtime Update]
    I --> G
    I --> D

這張圖裡，左邊還保留了 CtxFST 原本的 document lineage，右邊則是 v2.0 新增的 runtime world loop。

這也是我認為最準確的說法：

v2.0 不是把 document format 丟掉，而是讓 document format 長出可執行世界。

那原本的 GraphRAG 能力還重要嗎？

重要，而且我反而覺得它現在有了更清楚的位置。

在 v2.0 裡：

也就是說：

只是它們現在扮演的角色更明確了：

它們負責幫 agent 看見世界，
但不再是整個世界模型的全部。

這個定位我覺得比以前更強。

如果我要幫讀者下最短的版本

那我會這樣講：

CtxFST v1.x 的重點是把知識切乾淨、連乾淨、查乾淨。
CtxFST v2.0 的重點是讓 agent 能在這個語意世界裡判斷、行動、更新狀態。

這就是兩代之間最本質的差異。

結語：這次不是升級欄位，而是升級野心

如果只從檔案差異來看，這次重構會被描述成：

但如果從系統設計角度看，真正發生的事情其實是：

CtxFST 不再只想當資料整理格式，而是想成為 agent 可以直接操作的 semantic world model substrate。

這件事風險比較高，因為它不再是保守升級。

但我反而覺得這樣更對。

因為如果你真的相信未來的 agent 系統需要的不是更多散亂文件，而是：

那 CtxFST 的方向就不該停在 chunking。

它就應該往 world model 走。

而這次 v2.0 的重構，正是把這個方向正式寫進規格、程式與文件裡的第一步。

📌 以前的 CtxFST 比較像知識整理格式；現在的 CtxFST 開始變成 agent 可操作的語意世界底座。