Object spec:raw/ 檔案

Object: raw/ 目錄底下的原始來源檔案

適用範圍:規範什麼內容可以進 raw/,以及 raw/assets/ 歸類搬出這一項生命週期例外的操作判準。不含 wiki/ 頁面本身的規則。

規格本體

合法來源範疇

來源不限外部資料;使用者自己的創作、理解、心得與反思也可作為原始來源,走相同的 Ingest 流程。

雜記寶庫

raw/雜記寶庫/ 收純粹留存、不預期被查詢或引用的原始來源,不經 Ingest、不建對應 wiki 頁面。

該目錄的 index.md 為 append-only,新項目一律加在檔案末尾,格式:## [YYYY-MM-DD] 檔名 加一段留存原因與內容摘要。

唯讀鐵律

原始來源檔案不得竄改或遺失。除下面「assets 搬出例外」這一項生命週期操作外,只能新增,不得修改、刪除或搬移既有內容。

raw/ 底下由 Hoard 自己維護的目錄索引(例如 raw/雜記寶庫/index.md)不是原始來源,不受這條約束,依其所屬規則更新。

assets 搬出例外

路徑搬移僅限於 raw/assets/(尚未歸類或來源附帶的圖片等附件,不視為正式 wiki 內容)歸類搬出這個生命週期操作,且須以 git mv 保留歷史、確保內容不變。判定合法的兩個條件(缺一不可):

  1. Git 判定為 rename 且相似度 100%(內容逐位元組不變)。
  2. 舊路徑在 raw/assets/ 底下、新路徑不在 raw/ 樹內。

不符合以上兩點的搬移或刪除視為異常。

驗證方式

  • 機械:既有原始來源檔案的內容是否被修改(diff 比對,目錄索引除外)、搬移是否同時符合上面兩個條件——hoard-lint、hoard-status 已實作這些檢查。
  • 語意,不可自動化:某段內容算不算「合法來源」(例如使用者的心得反思是否值得收錄)由 Ingest 判斷時決定,不是機械規則。