做 GraphRAG 之前，為什麼要先「穩定 Schema」？CtxFST 的規格化之路

當大家在討論如何建立 Entity Graph、如何透過 LanceDB 與 HelixDB 檢索、如何用 OpenAI 跑 Embedding 的時候，往往會忽略一個最基礎、卻也最致命的環節：你的資料庫基底（Schema）到底穩不穩定？

我目前的建議是：先不要急著做 Embedding Graph，也不要急著做 GraphRAG Demo 或產品化；先把 CtxFST 這個格式本身定清楚、固定下來。

這篇文章將與大家分享，為什麼我們要先把文件格式變成一個「可靠、可驗證、可教學、可被其他工具依賴」的標準，以及具體做出的三大核心交付物。

一、為什麼要先做「穩定 Schema」？

如果你的底層 Schema 還在飄浮不定（今天 entities 是選填，明天變必填；剛決定的 id 格式過幾天又改變），後面所有仰賴它的系統都會跟著不穩、甚至崩潰：

換句話說：Schema 是地基。
如果地基還沒確認好，後面做相似度計算（Similarity）、匯入圖資料庫（Graph DB）、到 RAG 的檢索，全都會面臨無盡的「返工（Rework）」。必須要讓任何人看到一份 CtxFST 文件，都知道它長什麼樣、怎麼驗證、怎麼匯出。

在 CtxFST 裡，穩定 Schema 就是要訂清以下結構規則：

文件層：YAML frontmatter + <Chunk> body 有沒有這兩個頂層區塊？
實體（Entity）層：必須具備 id, name, type！aliases 是選填。
區塊（Chunk）層：定義何者為核心（Core Required：id），何者為強烈建議（Strongly Recommended：context, entities），何者為選填擴充（Optional：tags, created_at, priority, dependencies）。
匯出層（Export）：最終的 JSON 匯出結構是不是永遠固定為 {"entities": [...], "chunks": [...]}。
驗證層（Validation）：怎麼判斷一份檔案是合法（Valid），例如：Chunk 引用的 Entity 一定要事先在頂層宣告。

⚠️ 「穩定」不是說永遠不能改。
它的意思是：先定一個 v1 正式版，之後的新增欄位都當作延伸擴充（Extension）。不能隨便去變更有破壞性的核心規則，遇到新欄位時，要有一套向後相容處理（Backward Compatibility）的原則。

為了解決這個「地基」的問題，我把 CtxFST 從單純「好用的 Markdown 轉換指令」，拉拔成了一個嚴謹可被企業系統或下游 Agentic 應用依賴的資料標準。以下是我們為這套標準化所準備的三大支柱：

我們在這份規格書裡明確畫出了「什麼是 CtxFST」的版本邊界，確保未來看文件的人知道什麼是標準、什麼是延伸：

v1.0 (Core 層)：最核心的精神。限定 chunks[] 必須要有 id、context、content 與 tags。這保證了系統具備基本的 Vector Search 查詢能力。
v1.1 (Entity Graph 層)：知識圖譜升級。規範了頂層的 entities[] 目錄（Catalog），以及 chunks[].entities 的連動關係。
v1.2 (Agentic / Temporal 層)：將 priority、created_at、version 等進階應用的欄位定義為延伸欄位。

同時，這份 Spec 訂出了強硬的**「向後相容規則（Backward Compatibility）」**：即便 Parser（解析器）遇到不認識的欄位時也不可以噴錯（Crash），而是忽略它。這保證了未來整個生態系升級時的穩定性。

為了讓其他語言（不論是 Python、Go、Rust 或 TS 開發者）在撰寫 Importer、Exporter 時可以「輕易驗證」我們匯出的 JSON，我在目錄下建立了一個符合標準 JSON Schema Draft-07 格式的驗證檔 (schema.json)。

裡面直接用程式級的硬限制把雜訊擋在門外：

陣列結構：強制要有 chunks Array（Required），而且裡面最少要有一個 Chunk 節點。
Regex 嚴格驗證：chunks.id 的字串必須符合特定 Regex 格式（例如 category:topic）。而 entities 裡的 id 必須符合 entity:kebab-case-name。
列舉值限制（Enum）：強制規定 entities 裡面的 type 屬性只能使用指定的標準詞彙（例如 skill, tool, framework, database 等），這將從物理上徹底杜絕系統產生 Graph Noise（圖譜雜訊）。

最後，是讓所有要使用這個格式的人知道：「現在 CtxFST 是穩定的」。

skill-chunk-md/README.md：新增了一大段 Schema Versioning & Stability，聲明這是一個「被穩定版本控管」的資料格式，並直接附上 ctxfst-spec.md 與 schema.json 的連結。
專案首頁介紹：在 ctxfst: Structured Frontmatter Format 區塊最上方加上宣示：「它是一個針對 RAG 所設計的、高度版本鎖定且嚴謹的標準。」

schema 是地基。

有這三根堅固的柱子（Spec 規格書、JSON Schema 驗證檔、穩定聲明文件）撐著，即便我們後續再怎麼發展 Embedding Pipeline、建立 GraphRAG 或者外掛各類進階 LLM Agent，都不用再害怕底層資料結構因為隨意變更而發生大翻車了！ 🚀

現在，地基打穩了，我們終於可以放心地向 Entity Graph Similarity 邁進了。