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

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

三條規則就是整個格式

實際上只要記住三件事：One index, one truth——每個 bundle 有一個 index.md，列出內容；Typed frontmatter——每個檔在 frontmatter 標 type，agent 靠 type 路由，不用猜；Git-native——像 code 一樣 diff、review、回復版本，沒有專有格式。

最小的 bundle 長這樣

my-knowledge-bundle/
├── index.md            # manifest：列出所有內容
├── weekly-active-users.md
└── user-events.md

index.md：整個 bundle 的入口

index.md 用 frontmatter 寫下 bundle 的身分：標題、版本，以及 entries（列出包含哪些檔）。agent 從這裡進來，看到需要的概念再往下讀。

---
title: My Knowledge Bundle
version: 0.1.0
entries:
  - weekly-active-users.md
  - user-events.md
---

# My Knowledge Bundle

給 agent 用的知識庫。先讀相關節點，改動後更新對應節點。

每個概念檔：標 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 走訪到相關節點。整個過程是「走訪」而不是「搜尋」——這也是它跟向量檢索最大的差別。

我自己踩過的幾個取捨

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

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

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

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