前言¶
DeepSeek Harness (DSH) 的理念是“一切皆插件”。DSH 內置版 Obsidian（dsh-knj-obsidian）爲 AI agent 提供項目級知識庫（wiki）的構建能力。Agent 可以通過工具將對話、文檔、網頁等源材料蒸餾爲結構化知識頁，落盤到項目根目錄的 .wiki/，形成可複用、可維護的知識資產。
該插件由 yangdongzhen590 維護，當前版本包含 v1 構建、v2 檢索、v3 圖譜導出、v4 UI 和 v5 筆記編輯能力。
安裝與啓用¶
安裝前需確保環境滿足以下要求：
* Node.js >= 20
* 已安裝 DSH 宿主（提供 dsh CLI 與 web profile）
執行以下步驟安裝插件：
# 1. 在插件目錄內打包
npm pack
# 2. 在插件目錄內執行：安裝到 DSH 的 web profile
dsh plugin --profile web add ./dsh-knj-obsidian-2026.8.257.tgz
# 3. 重啓 DSH，確認宿主日誌無相關報錯
安裝後，插件會在 DSH 啓動時向 agent 暴露工具，並隨包分發 wiki-query skill，無需額外配置。
v1 構建：寫入側¶
插件提供三個核心工具用於知識庫的構建與維護。
wiki_ingest¶
將 Agent 提取好的知識頁批量寫入 wiki。支持 contentHash 增量合併，當源內容 SHA-256 與 manifest 記錄一致時整體跳過，實現增量寫入。
wiki_capture¶
快速沉澱。採用 quick 模式，默認寫入 references/ 目錄，confidence 標記爲 inferred。適合將對話結論即時落盤。
wiki_lint¶
健康度檢查。檢查孤兒頁（無入鏈或出鏈）、斷鏈（[[wikilink]] 指向不存在的頁面）以及缺 frontmatter 的情況，並返回報告。
知識庫結構位於項目根目錄的 .wiki/，包含 index.md、_system/、concepts/、entities/、references/、synthesis/、projects/ 等目錄。
v2 檢索：雙通道¶
檢索能力基於同一 .wiki/ 知識庫，提供雙通道機制，均爲只讀操作。
wiki_query 工具¶
內置工具，DSH 啓動即暴露。Agent 在被問到“之前關於 X 踩過什麼坑”等既有知識問題時自動調用。
wiki-query skill¶
隨包分發的獨立 skill，作爲工具的 fallback。在工具不可用時，Agent 可通過該 skill 使用 grep / glob / read 完成同等分層檢索。
分層檢索策略¶
兩者共用 L1–L4 分層層級：
1. L1 — index 快速層：讀取 .wiki/index.md。
2. L2 — 標題 + 標籤層：grep 標題與標籤，命中即停。
3. L3 — 正文層：打開正文定位，截取上下文。
4. L4 — 圖譜鄰居：解析 [[wikilink]] 出鏈，取一跳鄰居。
v3 圖譜導出¶
wiki_export 工具¶
Agent 被問到“導出圖譜”時自動調用。提供兩種格式：
- html：生成
graph.html，單文件交互可視化，內聯 SVG + 原生 JS，零外部依賴。 - json：生成
graph.json，包含節點、邊、孤兒、統計信息，供外部工具使用。
產物寫入 <vault>/wiki-export/。
v4 UI：側邊欄¶
安裝後，DSH 右側邊欄會出現“知識庫”標籤，提供筆記/圖譜工作臺入口。
v5 筆記編輯¶
筆記編輯器支持富渲染、雙鏈原地跳轉、源碼視圖與全文編輯。
本地語義檢索¶
除關鍵詞分層檢索外，插件提供 wiki_search_semantic 工具，支持本地語義檢索。此功能依賴 QMD 庫，默認不安裝。
啓用步驟¶
需手動安裝 QMD 及下載模型：
# 1. 安裝 QMD
dsh plugin --profile web add @tobilu/qmd@2.8.3
# 2. 手動下載模型（約 320 MB）
# 放置到：%USERPROFILE%\.dsh\qmd\models\embeddinggemma-300M-Q8_0.gguf
離線約束¶
語義檢索嚴格離線。QMD 的雲端模型路徑會被禁用，索引與查詢全程零網絡。索引狀態可通過 API 輪詢。
注意事項¶
- 依賴安裝：
@tobilu/qmd爲 optional peerDependency，DSH 默認不會自動安裝。需顯式執行上述安裝命令。 - 模型下載：需手動下載模型文件並放置到指定路徑，插件不會自動下載。
- 環境要求：需 Node.js >= 20 和已安裝的 DSH 宿主。
