OKF 接到 RAG 之前：來源版本、切段與查詢契約

把知識放進 OKF bundle 後，索引仍然可能把一張表切成兩半。來源有標題、連結與版本，只表示這些資訊可以被讀取；檢索管線是否保留、查詢是否使用，還是要另外實作。

本站的 knowledge/index.md 是人工維護的入口，讓 agent 沿節點讀取專案慣例。這能證明本站使用檔案導覽，不能拿來宣稱已部署向量檢索或量測過命中率。下面提出的是把這類來源接到檢索服務時可採用的設計契約。

先定義一筆檢索結果必須帶什麼

以假設的訂單保留規則為例，文件路徑可以是 policies/orders.md，段落 ID 是 retention，環境是 prod。索引還要記錄來源 revision、內容雜湊、索引版本與適用日期。路徑幫助定位；版本才能回答「讀到的是哪一次修訂」。這些欄位是本文建議的應用層設計，不是聲稱 OKF 規格強制要求的欄位。

{
  "source_id": "policies/orders.md#retention",
  "source_revision": "2",
  "environment": "prod",
  "effective_from": "2026-09-01",
  "content_hash": "<computed from source bytes>",
  "index_version": "retention-demo-v2",
  "parent_id": "policies/orders.md"
}

實例：OKF 規格只要求 type，其餘欄位要自己定

OKF v0.2 規格的 §11 列了合格條件。第 2 條原文是「Every frontmatter block contains a non-empty type field.」§4.1 也寫明，type 是唯一一定要有的鍵。title、description、resource、tags 都不是必填。上面 JSON 的 source_revision、environment、effective_from，規格裡都沒有。

規格有兩個相近的欄位可以對應。§4.1 的 resource 是唯一識別所描述資產的 URI，可以對到 source_id。§5.2 的 generated.at 是 ISO 8601 時間，原文說它標示內容「last meaningful change」。它是時間，不是修訂編號。要判斷內容有沒有變，索引建置端仍要自己存內容雜湊。

§5.5 另有選填的 stale_after，原文是「A concept is stale when now >= stale_after」。查詢端可以用它排除過期的概念。但它和上面的 effective_from 方向相反：一個標何時失效，一個標何時生效。生效日仍要另外加欄位。

規格也明說檢索層不歸它管。§1 的 Non-goals 列了「Prescribing storage, serving, or query infrastructure.」同一節的 Goals 把 search indexes 列為讀取 bundle 的一方。所以切段、索引版本、刪除同步，都由索引建置端負責。

本站 build 對 OKF 的檢查也停在來源這一階段。scripts/lib/okf.mjs 檢查非保留的 .md。每個都要有 frontmatter，type 不能是空的。scripts/check-okf.mjs 另有一條本站規則。公開 bundle 的 resource 若是本站網址，必須列在 sitemap。這兩道檢查只看來源檔。本站沒有向量索引，所以沒有「索引裡還留著舊段落」的檢查。若要接檢索，建議先補一條：索引裡每段的 source_id，都要能在目前的 bundle 找到。這是本文的建議，本站沒有實作。

切段程式要負責保留結構

建立索引時，將章節路徑、表格欄名與適用範圍放入可取回的資料。若一張表超過單段限制，可以拆列，但每列要帶欄名、單位與父節點 ID；跨段定義則要能依父節點取回全文。若只是每隔固定字數切一次，來源再整齊也可能失去語意。

明確連結也不等於 agent 已經會走關係。要決定允許哪些邊、最多走幾步、遇到循環怎麼停，以及找不到目標時如何回報。涉及存取權限時，來源讀取與檢索都要套用相同授權條件，不能先取回再期待模型自行忽略。

更新用新版本切換，別把新舊規則混在一起

假設來源由 revision 1 改到 2，先建立新的索引版本，確認新增、修改、刪除都反映在其中。驗收完成後才切換 active index；失敗就繼續使用舊版並明示資料日期。這是設計方案，不是本站現有服務的實測紀錄。

驗收至少包含四個問題：正式環境應拿到哪份規則、測試環境是否被隔離、已刪除文件是否消失，以及沒有資料的問題是否回報未知。要測試的不是 agent 能不能說出一個答案，而是它有沒有使用正確版本與範圍的來源。

查詢流程依問題選擇

已知文件 ID 時，直接取回並核對版本；只有模糊描述時，才用全文或向量搜尋尋找候選，再套用環境、有效期與權限條件。需要跨文件關係時，使用明確 ID 或連結擴展。這不是固定規定所有問題都先走 OKF，再跑向量；應依可用的識別資訊與實際漏查案例選擇。

回答端應能輸出來源 ID、revision 與引用段落；若只找到失效版本或不相容規則，回報缺口並停止下結論。檢索格式本身不能保證答案正確，這些檢查才讓問題有地方可追。

用相同案例檢查分工

「正式環境保留多久」的範例中，錯誤可能來自 test 文件排名更高，也可能是 prod 舊版尚未移除。前者要檢查環境條件，後者要檢查索引版本；兩者都不能只靠改寫 prompt 解決。痛點篇提供一段不依賴模型的排名與篩選範例，可以先用它確認欄位是否完整，再加入真正的 embedding 與答案驗收。

維護者負責 bundle 的來源內容與連結；索引建置端負責切段、版本與刪除；查詢端負責條件與取回；回答端負責引用與未知處理。把這幾個責任寫進流程，才能知道資料更新後是哪一步還沒跟上。