Semi-Brain Knowledge Management System¶
概念概覽
系統分數演進與對應改進¶
核心知識¶
系統分數演進與對應改進¶
| 分數 | 主要改進 |
|---|---|
| 68→83 | 移除舊 API pipeline、修正 ledger 語義、統一 tags.json 資料契約、發布後自動更新 indexes/graph/stats |
| 83→92 | 補 27 個測試、GitPublisher 記錄 subprocess returncode、接 CI、依賴分層、retry-failed 指令 |
| 92→94 | slug collision 防護、frontmatter schema 驗證、session_id 進 frontmatter |
tags.json 資料契約統一¶
build-indexes、build-graph、generate-stats 三個模組需讀取相同格式：
格式不統一是造成系統各部分行為不一致的根本原因之一。
依賴分層架構¶
requirements.txt → core: jinja2
requirements-docs.txt → docs: mkdocs, mkdocs-material, pyyaml
requirements-extras.txt → memory/graph: mem0ai, sentence-transformers, graphiti-core
mkdocs 屬於部署/預覽層，不是核心依賴，應拆開以降低安裝負擔。
Bash Subshell 計數問題¶
# 錯誤：echo pipe 產生 subshell，外層讀不到計數變數
echo "$list" | while read item; do count=$((count+1)); done
# 正確：here-string 避免 subshell
while read item; do count=$((count+1)); done <<< "$list"
Slug Collision 防護¶
同名文檔自動加 -2, -3 後綴，防止覆蓋已有文檔。
Frontmatter 驗證策略¶
目前為 warning 非 hard gate，保守策略避免阻斷發布流程。升級到 95 分的最後一步是將其提升為真正的品質門檻。
經驗教訓¶
-
「有野心的原型」到「可持續運作的 v1」需要資料契約、測試、CI、去重語義同時到位
-
bash while loop 透過 pipe 讀取會產生 subshell，導致計數變數在外層不可見，用 here-string 解決
-
validate-docs --strict 排除 reports/data/stats 後掃描文件數為 0，quality gate 形同虛設，需確認掃描範圍
常見陷阱¶
-
bash while loop 用 echo pipe → subshell 計數變數外層讀不到
-
tags.json 格式不統一 → build-indexes/graph/stats 行為不一致
-
validate-docs --strict 排除太多目錄 → 實際掃描 0 個文件，quality gate 失效
最佳實踐¶
-
多模組共用資料格式時，先定義契約再各自實作，避免格式漂移
-
依賴按使用場景分層（core/docs/extras），降低必要安裝負擔
-
Subprocess 呼叫記錄 returncode，即使 non-fatal 也需可見以便追蹤
相關概念¶
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- Knowledge Consolidation Pass — 共享：
knowledge-management,semi-brain/ 獨特：consolidation,deduplication - Knowledge Consolidation — 共享：
knowledge-management,semi-brain/ 獨特：consolidation,content-quality
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-03-18 | b0b2a293-9dc3-4b1b-a41f-7ab423a8fd45 | 記錄從 68 分到 94 分的系統架構演進：資料契約統一、slug collision 防護、frontmatter 驗證、依賴分層，以及各品質層次的具體改進點 |