semi-brain 知識庫品質升級（融合版 v8）：Consolidation Pass v2+ 完成 + Phase 3 視覺化啟動與 Tooltip HTML Bug¶

文檔資訊

分類: architecture
難度: intermediate
預估閱讀時間: 20 分鐘
標籤: knowledge-management, mkdocs, obsidian, backlinks, knowledge-graph, semantic-search, wiki-migration, python, deduplication, consolidation, visualization, docker

摘要¶

針對 semi-brain 知識庫品質不佳（單向連結、概念碎片化、無語義關聯），設計並執行三階段改造。Phase 1 實作 backlink_pass.py + mkdocs-roamlinks-plugin；Phase 2 整合 obra/knowledge-graph 語義索引 + 語義重複檢查，完成 44 篇文件遷移。v6：Consolidation Pass v1 完成（18 頁碎片 → 4 頁 canonical）。v7：Consolidation Pass v2+ 多主題系統性整合。v8 新增：Phase 3 視覺化提前啟動（知識圖譜節點互動視覺化已上線），發現 tooltip 顯示原始 HTML tag 的 UI bug（ 未渲染），以及 Docker image 過舊需重 build 的維運問題。v7 中「Phase 3 延後」的結論被推翻。

關鍵學習¶

Phase 3 視覺化不需等全庫 consolidation 完成才能啟動：當主要主題整合到一定程度後，視覺化反而能協助識別剩餘碎片
知識圖譜 tooltip 若直接顯示 HTML 內容，需確認渲染層是 innerHTML 而非 textContent，否則等 tag 會以原始字串顯示
Docker image 與程式碼的版本同步是持續維運問題：每次重大改動後都需判斷是否需要重 build，而非依賴舊 image
全庫 consolidation 的系統性多輪執行模式已驗證有效：Pass v1（18→4 頁）→ Pass v2+（多主題）→ 視覺化啟動形成正向循環
語義重複「檢查」≠「合併」：歷史存量碎片需要專門的 batch merge pass，進入時去重只對新文章有效
高信心群組優先策略可安全擴大範圍：v1 基準 4.5:1 壓縮比是後續 Pass 的品質參考指標
碎片化是全庫普遍現象，不限於單一主題：1m CCU 等主題均發現大量重複
obra/knowledge-graph（Option B）比純向量搜尋（Option A）更能揭示知識結構，長期價值更高
consolidation 完成前做視覺化的擔憂有部分被推翻：實際操作中，邊整合邊視覺化能提供即時回饋
Docker image hash 是版本追蹤的可靠依據：8e5b8dcb91f5... 這樣的具體 hash 可用來判斷是否落後

技術細節¶

問題診斷¶

原始知識庫存在三個核心缺陷：

單向連結：文章間只有 A→B 的引用，B 無法知道誰引用了它
概念碎片化：相似主題分散成多篇文章，缺乏語義去重
無語義關聯：文章間連結靠人工維護，無自動化索引

Phase 1：低風險、高回報（已完成）¶

backlink_pass.py 掃描所有 .md 文件，建立 incoming_links dict，在每篇文章底部注入 ## Backlinks 區塊。

mkdocs-roamlinks-plugin 讓作者可用 [[Wikilink]] 語法，將 [aurora-rds-proxy](<../concepts/aurora-rds-proxy.md>) 自動解析為正確相對路徑。

Phase 2：關鍵能力升級（已完成）¶

整合 obra/knowledge-graph 作為 CI 步驟，每次 push 後自動產出語義索引 JSON。選擇 Option B（obra/knowledge-graph）而非 Option A（純向量搜尋）：Option B 多 2 小時工作量，但省下未來 2-3 天自建成本，且能揭示知識結構。

在 wiki_manager.py 概念提取階段加入語義相似度檢查（cosine similarity > 0.85 視為重複）。共完成 **44 篇文件**的 Wiki 遷移。

殘存問題：語義重複「檢查」只對新進入的文章有效，歷史存量碎片需要 batch merge pass。

全庫 Consolidation 多輪執行（v4–v7）¶

Pass v1（v6 成果）： - 策略：Option A — 先 apply 高信心群組 - 成果：18 頁**同 session 碎片 → **4 頁 canonical（壓縮比 4.5:1）

Pass v2+（v7 成果）： - 觸發：發現 1m CCU 等多個主題同樣有大量重複 - 執行：多輪識別 → 確認 → 合併，涵蓋多個主題領域

Phase 3：視覺化啟動（v8 新增，推翻 v7 結論）¶

v7 文檔預測「Phase 3 視覺化持續延後至整合完成後執行」，但實際上 Phase 3 在 Consolidation Pass v2+ 進行中即已啟動。知識圖譜節點互動視覺化已上線並可供用戶使用。

Tooltip HTML Bug（v8 新發現）：

節點 hover 時顯示的說明含有原始 HTML tag，如 標題 以字面字串顯示而非渲染為粗體。根本原因是 tooltip 內容設定使用了 textContent 或 .title 屬性而非 innerHTML，或者 tooltip 的 DOM 元素不支援 HTML 渲染。

Docker Image 版本問題（v8 新發現）：

用戶查看到 Docker image hash 8e5b8dcb91f5db15a06d2085b6350db6a0f694a4d5977f10e9e0da7c1ce0bb63 已過舊，Phase ⅔ 的改動（知識圖譜、backlink 注入等）不會反映在舊 image 中，需要重 build。

What Changed¶

架構層面¶

知識庫從「單純 MkDocs 靜態文件」升級為「具備雙向連結 + 語義索引 + 互動視覺化的知識圖譜」。新增 backlink_pass.py 作為建置前置步驟，mkdocs-roamlinks-plugin 改善撰寫體驗，obra/knowledge-graph 整合提供語義索引，知識圖譜節點視覺化提供探索介面。

流程層面¶

Consolidation 進入系統性多輪執行模式（Pass v1 → v2+），視覺化層也已啟動。wiki_manager.py 概念提取流程加入語義重複檢查，CI pipeline 加入知識圖譜產出步驟。

認知修正演化（v2 → v8）¶

v2：Phase 2 完成後語義重複問題已解決。 v3：語義重複檢查 ≠ 合併，歷史存量需要 batch merge pass。 v4：確認全庫 consolidation 決策。 v5：從「決策」進入「執行」。 v6：Pass v1 完成（18→4 頁）。 v7：發現碎片化不限 ComfyUI，全庫整合進入多輪執行，Phase 3 延後。 v8：Phase 3 提前啟動（推翻 v7 結論），發現 tooltip HTML bug 與 Docker image 過舊問題，視覺化與整合可並行推進。

So What¶

v8 的核心意義有三點：

1. Phase 3 時序假設被推翻：v7 認為視覺化必須等 consolidation 完全結束，但實際執行說明「邊整合邊視覺化」是可行的，甚至有助於用視覺回饋識別剩餘碎片。這是重要的流程修正。

2. Tooltip HTML Bug 暴露了視覺化層的實作細節盲點：知識圖譜節點的 tooltip 使用了不支援 HTML 渲染的方式設定說明文字，這是前端整合知識庫 Markdown 內容時的常見陷阱。

3. Docker image 版本管理是持續維運問題：改動代碼後若不重 build image，用戶看到的是舊行為，造成預期不符。需要建立明確的「何時需要重 build」判斷標準。

Trade-offs¶

backlink_pass.py 建置時間增加：文件量大時需考慮快取
mkdocs-roamlinks-plugin 依賴：需納入 requirements.txt 版本鎖定
語義重複閾值 0.85：過低造成誤判，過高則漏過真正重複，需根據實際語料調整
obra/knowledge-graph CI 成本：每次 push 觸發語義索引重建
語義去重時機盲點：現有機制只對新進文章有效，歷史存量需額外 batch merge pass
高信心優先策略的覆蓋率限制：中低信心碎片仍需後續 Pass 處理
全庫 consolidation 的人工審查成本：隨主題數量線性增長
Phase 3 與 consolidation 並行的同步風險：視覺化可能展示仍在整合中的不完整結構
Tooltip HTML 渲染方式選擇：innerHTML 支援富文字但有 XSS 風險；textContent 安全但失去格式；需在 tooltip 層做 sanitize
Docker image 重 build 頻率判斷：太頻繁增加 CI 成本，太少造成版本落後，需建立明確觸發條件

Try It Fast¶

# 安裝 mkdocs-roamlinks-plugin
pip install mkdocs-roamlinks-plugin

# 執行 backlink 注入
python scripts/backlink_pass.py docs/

# 本地預覽（確認 backlink 和 wikilink 是否正確）
mkdocs serve

# 驗證 backlink 是否正確注入
grep -r '## Backlinks' docs/ | head -10

# 確認 Consolidation Pass 成果
git log --oneline | grep -i 'consolidat\|merge\|canon'

# 追蹤整合進度（量化壓縮比）
git diff HEAD~N --stat | grep -E '(deleted|files changed)'

# 診斷 tooltip HTML bug：確認 D3/vis.js tooltip 使用 innerHTML
# 正確方式（支援 HTML 渲染）
# tooltip.node().innerHTML = content  ← 支援 <b></b>
# 錯誤方式（只顯示純文字）
# tooltip.text(content)               ← <b></b> 以字面顯示

# 確認 Docker image 版本
docker images --format '{{.Repository}}:{{.Tag}} {{.ID}} {{.CreatedAt}}' | grep semi-brain

# 強制重 build（加 --no-cache 確保拿到最新依賴）
docker build --no-cache -t semi-brain:latest .

# backlink_pass.py 核心邏輯
import re
from pathlib import Path
from collections import defaultdict

def build_backlink_index(docs_dir: str) -> dict:
    """掃描所有 .md 檔，建立 {target: [source, ...]} 索引"""
    index = defaultdict(list)
    for md_file in Path(docs_dir).rglob('*.md'):
        content = md_file.read_text()
        links = re.findall(r'\[.*?\]\(([^)]+\.md)\)', content)
        for link in links:
            index[link].append(str(md_file))
    return dict(index)

Recommendation¶

修復 tooltip HTML 渲染 bug（高優先）— 將 tooltip 內容設定方式從 textContent/.text() 改為 innerHTML，並加入 DOMPurify sanitize 防止 XSS，讓  等 tag 正確渲染
重 build Docker image（高優先）— Phase ⅔ 的改動（知識圖譜、backlink 注入、語義索引）需要新 image 才能反映，建議建立「改動 wiki_manager.py 或 scripts/ 後必須重 build」的規則
量化每次 Pass 的壓縮比例（高優先）— 記錄「輸入頁數 → 輸出 canonical 頁數」，v1 基準：18:4（4.5:1），後續每輪對比此基準
建立 Consolidation 完成標準（中優先）— 定義可量化指標（例如全庫無 > 0.85 相似度的文章對），避免無限迴圈
系統性掃描剩餘主題（中優先）— 以 1m CCU 模式為範本，逐一掃描所有主要主題，排入 Pass v3+ 計畫
建立 Docker image 版本追蹤慣例（中優先）— 在 CI 中記錄每次 build 的 git commit hash，方便用戶確認 image 是否與當前代碼同步
驗證 backlink_pass.py 的連結解析正確性（低優先）— 相對路徑與絕對路徑混用會導致 backlink 索引錯誤，需加入單元測試
consolidation 後做完整視覺化 Phase 3（低優先）— 當前視覺化已啟動但仍在 consolidation 進行中，整合完成後重新產出完整圖譜

本文檔由 Semi-Brain 自動生成

Session ID: a0379709-073f-4231-a61f-87b8486559f7

分析信心度: 91%