用 Markdown 把組織知識標準化：Google 的 OKF（Open Knowledge Format）

最近參加活動時認識到 OKF，並在內部分享了 Google Cloud 開源的 OKF（Open Knowledge Format）。核心概念很單純：把組織知識用 Markdown + YAML frontmatter 標準化，讓人和 AI agent 都能讀懂。

OKF 想解決什麼問題

組織裡的知識通常是散落的：一部分在資料庫，一部分在文件，一部分在程式碼裡，還有很大一部分只存在於特定幾個人的腦袋中。新人需要靠問人才能找到答案，AI agent 也需要可查詢的資料來源；在這種情況下，組織都很難找到一個明確的知識入口。

OKF 給的想法是：不要求你先把原始資料搬家。BigQuery 的表還是留在 BigQuery，API 還是那個 API，它只要求你把「這項知識是什麼、怎麼用、從哪裡來」整理成一份格式一致的 Markdown 文件。

官方的定義是「a universal, vendor-neutral format for representing knowledge as plain markdown files with YAML frontmatter」——重點在 vendor-neutral，不綁任何平台或框架，純文字、可版控、可攜。

本文以 OKF v0.2 規格為準。這個格式目前還在 0.x 階段快速演進，欄位與細節之後可能會調整，實作前建議再對照一次官方 SPEC。

目標可以濃縮成三個詞：知識標準化、可連結、可追蹤。

建置流程四步驟

1. 盤點：先列清單，不急著搬資料

第一步只做一件事——把現有來源列出來。例如：

BigQuery 或其他資料表
API 與程式碼 README
操作流程、政策文件

這一步刻意不動資料，只是把「我們到底有哪些知識散在哪裡」攤開來看。

2. 拆分：一個主題一份文件

原則很直白，一個概念一份 Markdown：

一張資料表 → 一份文件
一個 API → 一份文件
一個業務指標 → 一份文件
一份政策或操作流程 → 一份文件

一個資料夾就是一個 bundle，裡面放相關主題的 Markdown 檔，再加一份 index.md 當目錄。這樣人或 agent 進來時可以先看總覽，再決定往下讀哪一份，官方文件把這個行為叫 progressive disclosure（漸進式揭露）。

一個典型的 bundle 長這樣：

sales-knowledge/
├── index.md
├── tables/
│   ├── orders.md
│   └── customers.md
├── metrics/
│   └── revenue.md
└── policies/
    └── revenue-policy.md

3. 標記：加上 YAML frontmatter

每份文件開頭補上一段 frontmatter，這是整個格式真正「可查詢」的部分：

欄位	用途
`type`	這是什麼類型的知識
`title`	顯示名稱
`description`	簡短說明
`resource`	實際資源的位置
`tags`	分類標籤

其中只有 type 是必填，其餘都是建議或選填欄位。

實際的文件會像這樣：

---
type: BigQuery Table
title: Customer Orders
description: 已完成的客戶訂單
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, revenue]
---

# 用途
用於查詢已完成訂單與計算營收。

# 重要欄位
- `order_id`：訂單識別碼
- `customer_id`：客戶識別碼
- `total_amount`：訂單金額

# 使用提醒
計算正式營收前，請參考營收認列政策。

注意 resource 那行：文件本身不複製資料，只是指路。這就是前面說的「不搬家」——這份 Markdown 是「說明書」，不是「副本」。

除了上面這幾個基本欄位，v0.2 還新增了一些跟知識品質有關的欄位，團隊規模大一點之後會滿有用的：

generated：標記是誰／什麼產生的
verified：由誰（人、自動化程序或 agent）確認過；規格依此區分「機器確認」與「人工審閱」兩種信任層級
status：目前是否仍然有效
stale_after：這份內容的「有效期限」，填的是一個具體日期時間（例如 2026-12-31T00:00:00Z），過了這個時間點就視為過期、該重新檢查，而不是「每隔 30 天」這種週期
sources：來源出處與可信度

我自己的感覺是，stale_after 和 verified 這兩個欄位是這套格式跟一般 wiki 拉開差距的地方——它一開始就假設「知識會過期」，而不是等到有人踩雷才發現文件三年沒更新。

v0.2 還有一個比較進階的功能叫 Attested Computation（可驗證計算）。前面的欄位回答的是「這份知識從哪裡來、有沒有人確認過」；它要回答的則是「這個數字是不是照規定的方法算出來的」。例如營收該怎麼算，文件裡可以附上一段官方認可的計算方式，AI agent 每次都得照著跑，再由一段固定的檢查程式（不經過 LLM）確認結果，避免 agent 自己即興換一種算法。這篇先不展開，有興趣可以直接看官方 SPEC。

4. 連結與版控

文件寫好之後，用一般的 Markdown link 互相連結就好：

1	計算營收前請先讀 [營收認列政策](../policies/revenue-policy.md)。

這樣整組文件會從「樹狀目錄」變成「圖狀結構」——資料夾給出階層，連結再把不同分支的文件串起來。對 AI agent 來說，它可以靠 type 和 tags 篩出相關文件，再透過 index.md 逐層往下找，而不是一次把整包塞進 context。

然後把整個 bundle 丟進 Git，你會直接拿到這些好處：

用 Pull Request 審查知識的修改，知識跟程式碼走同一套流程
用 diff 看清楚這次改了什麼
用 blame 追是誰改的、哪一次 commit 引進的、當時的 commit message 怎麼說
用歷史紀錄回復舊版本
搭配工具把文件之間的連結畫成關係圖

「用 PR 審查知識」這件事我覺得是整套做法最值得偷的一點。文件放在 wiki 或雲端硬碟時，改動通常是靜默發生的；放進 Git 之後，知識的變更跟程式碼的變更享有一樣的把關強度。

幾個實務上的觀察

它本質上是一層 metadata，不是搬家計畫。 導入成本主要落在「寫說明」這件事，而不是資料遷移，這讓它比較有可能在真實團隊裡推得動。

最大的受益者其實是 AI agent。 人讀文件靠搜尋和直覺，agent 需要的是結構化的線索——type、tags、index.md 就是給它的導航系統。純文字、可版控、格式一致，剛好是 agent 最好消化的形態。

維護仍然是人的問題。 格式解決的是「怎麼寫」，不是「有沒有人願意寫、願意更新」。stale_after 只是提醒你文件過期了，不會自己去更新它。

小結

OKF 沒有發明什麼新技術——Markdown、YAML frontmatter、Git 都是現成的東西。它的價值在於把這幾樣東西組合成一套團隊可以共用的約定：一個概念一份檔案、統一的 frontmatter 欄位、資料夾即 bundle、index 當入口、全部交給 Git。

如果你的團隊正在煩惱「要怎麼提供知識給 AI agent」，這套格式值得先拿一個小範圍（例如一組資料表或一組 API）試試看，成本低，而且就算最後沒導入 agent，留下來的也是一批整理過的文件。

參考資料

Open Knowledge Format（OKF）— GoogleCloudPlatform/knowledge-catalog