Knowledge-Base 知識庫協議

結構化 Markdown 知識庫的最小公共管理協議，通過 references/ 適配具體知識庫。

本文件分為兩層：

• 核心協議：所有知識庫都應遵守的最小公共約定
• 推薦實踐：預設最佳實現，可由 references 覆蓋或替換

知識庫根路徑

由 references/ 配置檔案定義。預設參考：references/hansphere.md

目錄約定

預設推薦結構

預設推薦採用以下分層結構，具體路徑和目錄命名以 references 配置為準：

知識庫根目錄/
├── README.md              # 倉庫總覽
└── Notes/
    ├── 00-Inbox/          # 臨時收集箱
    ├── 01-Daily/          # 日報/工作日誌
    ├── 02-Sources/        # 外部來源
    │   └── Fulltext/      # 全文存檔
    ├── 03-Concepts/       # 通用概念
    ├── 04-Issues/         # 問題模型
    ├── 05-Projects/       # 專案資料
    ├── 06-Architecture/   # 架構設計
    ├── 07-Patterns/       # 工作方法
    ├── 08-Reviews/        # 復盤總結
    ├── 09-Indexes/        # 索引導航
    ├── 10-Operations/     # 操作日誌+體檢
    ├── 98-Templates/      # 模板庫
    └── 99-Archive/        # 歸檔區

各目錄職責：

• Inbox → 臨時收集，定期清理
• Daily → 當天事實記錄
• Sources → 外部文章/資料（摘要+全文）
• Concepts → 可複用知識點
• Issues → 故障排查記錄
• Projects → 專案資料（個人+公司統一管理）
• Architecture → 架構決策/ADR

  小蔥技能站7w4.net發現了升級外掛。

• Patterns → 工作方法/SOP
• Reviews → 週報/月報/階段復盤
• Indexes → 索引導航
• Operations → 操作日誌+體檢報告
• Templates → 筆記模板
• Archive → 長期歸檔

上述目錄結構與職責為預設推薦對映，實際目錄和職責邊界以 references 配置為準。

執行流

輕量流

適用：Daily / Inbox / 已知檔案更新 / 小修訂

1. 判斷目標檔案
2. 套用已有模板/結構
3. 寫入或更新
4. 回寫 updated
5. 核心必檢 6 項
6. 必要時補 ops

標準流

適用：新建 Issue/Concept/Pattern/Project / 歸檔/遷移 / 批次整理 / 建索引

1. 搜尋防重複
2. 判斷型別
3. 讀取規則（首次進入該型別時讀目錄 README + 模板；同會話內沿用上下文）
4. 建立/更新
5. 補關聯欄位
6. 回寫 updated
7. 追加 ops（按工作批次收口）
8. 判斷索引更新（延遲觸發）
9. 完整質量清單

規則上下文快取

• 首次處理某型別筆記時，讀取目錄 README 和模板
• 同會話內同類型連續處理，沿用上下文，不重複讀取

核心協議

以下規則適用於所有知識庫：

1. 語義型別判定

新輸入按以下語義角色判斷型別（語義型別到實際目錄的對映由 references 定義）：

邊界裁決：

• 問題排查 圍繞"具體故障/排查結論"；概念知識 圍繞"原理/機制"
• 外部文章即使和專案強相關，仍先進 Sources，再在 related 關聯專案
• 臨時收集 內容 7 天內必須歸檔或刪除
• 時序記錄 中出現可複用結論/排障閉環/架構決策/流程最佳化時，必須升格為長期筆記

2. 防重複搜尋

新建長期知識類筆記前必須搜尋同主題已有內容：

已有內容高度重合 → 更新舊文件，不新建。

3. 相對連結

• 知識庫內部使用可點選的 Markdown 相對連結：[簡短說明](相對路徑)
• 禁止使用絕對本地路徑

4. 更新回寫

• 每次修改筆記必須回寫 updated 欄位為當天日期
• created 僅在首次建立時設定，後續不修改

5. 不寫敏感資訊

• 不寫入密碼、Token、API Key、基礎設施私鑰、客戶隱私或商業機密

6. 核心必檢 6 項

每次寫入後檢查：

• [ ] 路徑符合型別判定規則
• [ ] 檔名符合命名約定（見 references）
• [ ] Front Matter 完整（id/title/type 必填）
• [ ] updated 已回寫
• [ ] 不出現敏感資訊
• [ ] 無明顯重複（按搜尋規則執行；可跳過型別無需強制搜尋）

推薦實踐

以下實踐為預設最佳方案，可由 references 覆蓋。

以下型別名（Source/Issue/Concept 等）採用預設實現命名，僅作為推薦實踐示例。

命名約定

檔名應體現型別字首 + 主題/描述 + 日期，確保可讀且可排序。

具體命名格式見 references 配置。參考實現：

Front Matter 標準欄位

原則：沒有事實依據的欄位寧可留空，不要猜。

related / source 預設規則：

• 預設實踐中，來源資料 應提供 source 欄位
• 預設實踐中，問題排查 應儘量關聯相關筆記；首次記錄無關聯物件可暫空，驗證閉環前補齊
• 時序記錄 / 孤立輸入 允許都沒有

生命週期

使用 status 欄位管理筆記狀態：

最小正文骨架

必須章節可簡寫，但不得省略核心資訊。

建議章節（可選）見完整模板。

歸檔規則

archived 狀態與物理移動到 Archive 目錄是兩個獨立動作：

• 僅改狀態：短期不再活躍
• 移動到 Archive：長期不再維護，須同時更新關聯連結和索引

禁止只移動檔案而不修複相關連結。歸檔後原路徑保留簡短說明 或 更新索引標註（二選一）。

索引生成

觸發條件：某主題 ≥ 5 篇 / 專案跨多模組 / 問題鏈路涉及多型別文件。

延遲觸發：僅明確新建索引/使用者要求/批次操作時立即更新，其他場景延後統一處理。

操作日誌

按工作批次收口，30 分鐘內同主題多次修改合併為一條。僅記錄有意義的知識動作（新建/結構調整/歸檔/體檢等），不記錄格式清理。

專案目錄

專案目錄應包含穩定入口檔案（如 00-Index/INDEX.md），可按需要包含以下分層：Overview / Requirements / Architecture / Modules / Interfaces / Data / Environments / Issues / Change-Logs / Todos / Decisions / Reviews。

實際目錄結構由 references 定義。

知識庫體檢

定期體檢應覆蓋：結構完整性、連結健康、命名規範、孤立頁面、終端頁面、報告輸出。

具體評分權重和體檢工具由 references 配置。

安全邊界

不寫入認證資訊（密碼、Token、API Key）、基礎設施私鑰、客戶隱私或商業機密。敏感值使用佔位符。

配置擴充套件機制

通過 references/<kb-name>.md 定義具體知識庫的實現配置。reference 檔案可定義以下維度：

當前配置：references/hansphere.md