OKF bundle 怎麼寫：一個目錄、三條規則、一個最小可跑範例

第一次看 OKF 規格，我有點意外它有多小。它不是一套資料庫、SDK 或查詢語言——它就是一個目錄的 markdown 檔，加上幾條約定。這篇直接帶你把一個最小可跑的 bundle 寫出來。

三條規則：規格第 11 節的合格條件

規格第 11 節列出三條合格條件，這篇稱為「三條規則」。第一，每個非保留的 .md 檔都有可解析的 YAML frontmatter；保留檔名指 index.md 和 log.md。第二，每個 frontmatter 都有非空的 type。第三，index.md 和 log.md 如果存在，要照規格第 8、9 節的結構。三條都符合，就是合格的 OKF bundle。

規格也寫明：沒有 schema registry、沒有中央機構，也沒有必用的工具。因為全是純文字檔，你可以像 code 一樣用 Git diff、review、回復版本。這是格式帶來的好處，不是規格條文。

最小的 bundle 長這樣

my-knowledge-bundle/
├── index.md            # 目錄清單：列出這一層的檔案
├── weekly-active-users.md
└── user-events.md

index.md：整個 bundle 的入口

index.md 是目錄清單，規格稱為 Directory listing。它不寫 frontmatter。內文分成一個或多個「# 分組標題」區段，每條寫成「* [標題](相對路徑) - 一句描述」。描述最好直接取自該概念檔 frontmatter 的 description。唯一例外是 bundle 根目錄的 index.md：它的 frontmatter 只可以放 okf_version，例如 okf_version: "0.2"。下面的範例省略這一欄。agent 從這裡進來，看到需要的概念再往下讀。

# 指標

* [Weekly Active Users](weekly-active-users.md) - 每週至少開啟產品一次的不重複使用者

# 資料表

* [使用者事件表](user-events.md) - 每一筆有效事件的原始紀錄

每個概念檔：標 type、寫連結

每個非保留的 markdown 檔案要有可解析的 frontmatter，而且必須有非空的 type。type 可以是 concept、howto、reference、decision、metric 等。title、description 等其他欄位是建議，不是必填。概念之間用普通 markdown link 連起來——這些連結就是知識圖。

---
type: metric
title: Weekly Active Users
description: 每週至少開啟產品一次的不重複使用者
---

# 定義

計算過去七天至少產生一次有效事件的不重複使用者。

# 關聯

- [使用者事件表](user-events.md)

agent 怎麼用它

重點在 type 和連結。agent 從 index.md 進來，用 type 判斷這個檔是概念、操作、還是決策，不用靠關鍵字猜；需要更多脈絡時，沿著 markdown link 走訪到相關節點。整個過程是「走訪」而不是「搜尋」——這也是它跟向量檢索最大的差別。

實例：拿本站的 /knowledge 對三條規則

上面的範例是示意。下面這份是真的：本站 repo 的 knowledge 目錄。我在 2026 年 11 月 4 日數過，裡面有 25 個 .md 檔。index.md 列出其餘 24 個節點。目錄裡沒有 log.md；規格寫 log.md 是可以有（MAY），不是必要。

knowledge/
├── index.md                          # 根目錄清單，frontmatter 只有 okf_version
├── how-agents-use-this.md            # type: howto
├── architecture-i18n-routing.md      # type: reference
├── architecture-ssr-prerender.md     # type: concept
├── gotcha-hydration-mismatch-418.md  # type: decision
└── ……其餘 20 個節點

挑一個短節點看全文。節點越短，越容易看出一個合格節點最少要有什麼。architecture-i18n-routing.md 共 27 行，記中英文網址怎麼分、內部連結該用哪個元件：

---
type: reference
title: i18n 與路由
description: "中英文網址前綴與語系切換規則。"
---

# i18n 與路由

## 語言
- 繁中（`zh`）為預設，在根路徑 `/`；英文（`en`）在 `/en` 前綴下。
- i18next 設定在 `src/i18n/index.ts`，語言依 pathname 判定（`/en` 開頭 → en，
  否則 zh）。翻譯字串在 `src/i18n/zh.json` / `en.json`。
- 路由樹 `src/App.tsx`：`localizedRoutes` 同時掛在 `/`（zh）與 `/en`（en）之下。

## 內部連結一律用 LocalizedLink
- `src/components/LocalizedLink.tsx` + `src/i18n/routing.ts` 的 `localizePath()`：
  在 en 語系自動加 `/en` 前綴。**寫連結用它，不要手拼 `/en/...`。**
- 爬蟲側對應的 helper 在 `scripts/lib/render-article-html.mjs` 的 `localizeHref()`
  （鏡像同一規則）。

## SEO
- 每頁有 canonical + hreflang（zh ↔ en ↔ x-default）。
- 靜態頁（v1~v4）自帶這些 meta；React 頁由
  `scripts/generate-localized-entrypoints.mjs` 注入。

## 相關
[SSR 雙渲染器](architecture-ssr-prerender.md) · [部署](infra-deploy.md)

這個節點講三件事。中文頁在根路徑，英文頁在 /en 底下。站內連結一律用 LocalizedLink，不要手拼網址。LocalizedLink 是本站的連結元件，英文頁會自動補上 /en。每頁都有 canonical 和 hreflang。canonical 告訴搜尋引擎哪個網址是正本。hreflang 告訴它同一頁的其他語言版本在哪。agent 要改連結或路由時，讀這一頁就知道規矩。

這個節點的 frontmatter 只有 type、title、description 三欄。規格建議的欄位另有 resource 和 tags。resource 是指向實體資源的網址，例如一張資料表。這個節點講的是規則，沒有對應的單一資源，所以沒寫。最後的「相關」那行，就是連到別的節點的普通 markdown link。

我寫了一支小腳本，照三條規則逐檔檢查，結果如下。

第一條，非保留的 .md 檔都要有可解析的 frontmatter。腳本用 YAML 解析器讀 24 個節點，24 個都讀得出來。

第二條，type 不能是空的。24 個節點都有 type：concept 13 個、reference 6 個、howto 3 個、decision 2 個。規格寫 type 不集中登記，這 4 個值是我自己定的。

第三條，index.md 要照第 8 節。根目錄 index.md 的 frontmatter 只有 okf_version: "0.2" 一個鍵。24 個條目都是「* [標題](路徑) - 描述」，連到的檔都存在。

三條都過，0 個違規。腳本另外抓到 1 個小差異。工具頁那個節點，index.md 寫的描述和節點自己的 description 不一樣。規格這裡用的是 SHOULD（應該），不是 MUST（必須），所以不算違規。但同一件事寫在兩處，之後只改一處就會對不上。

想補 log.md 的話，規格第 9 節寫了格式：依日期分組，新的放前面。日期標題必須用 ISO 8601 的 YYYY-MM-DD，例如「## 2026-11-04」。每一筆用一般文字寫，說明這一天改了什麼。

這份 /knowledge 和 llms.txt、AGENTS.md 怎麼分工，另一篇有寫：

我自己踩過的幾個取捨

我替這個網站的 repo 做過一份真的 bundle，放在 /knowledge。現在有 24 個節點，涵蓋架構、決策、雷區等。有了它，Claude 跟 Codex 不用每次重爬整個 repo。實作時有幾個取捨很快就變得明顯。

節點要小，最好一個檔只放一個概念。與其塞一份大檔，不如切成互相連結的小節點，讓 agent 只讀相關的那個。

別放會過期的瑣碎狀態（某個 commit hash、暫時的 TODO），那些看 git 就好；bundle 放的是架構、決策、慣例、雷區這種比較穩定的知識。最重要的是，光有 bundle 沒用，還要把「動工前讀、改完後更新」寫進 agent 會載入的入口檔，它才活得下去。

不需要新增資料庫、查詢語言或 SDK。只靠一個目錄和三條規則，就能做出一份人可以讀、agent 可以走訪，還能用 Git 版本控制的知識庫。

更正紀錄

2026-10-17 更正。舊版的「三條規則」寫成 One index, one truth、Typed frontmatter、Git-native。這三句出自社群網站 okf.md 的整理，不是 Google 發布的規格。我先前把 okf.md 的整理當成了規格。舊版的 index.md 範例也帶了 title、version、entries 的 frontmatter。這違反規格：index.md 不寫 frontmatter，規格也沒有 entries 欄位。這次依官方 v0.2 規格第 8、11 節，改寫三條規則與 index.md 範例。「manifest」也改成規格的說法「目錄清單」。