前言¶
在 DeepSeek Harness（DSH）裏做帶上下文的對話或 Agent，常見做法是手寫檢索腳本、臨時拷貝筆記片段，或把整個目錄丟進通用文件工具。Obsidian 庫往往體量大、路徑分散，整庫上傳既不現實，也難保證引用可追溯。dsh-obsidian-bridge（界面名 Obsidian Vault Studio）由 spark-ai-boy 維護，在 DSH 側邊欄提供本地索引、檢索與「先提案、後寫入」的筆記操作，索引與向量留在本機。下文按安裝、首次運行與對話用法說明可復現步驟。
這是什麼¶
dsh-obsidian-bridge 是 DSH 第三方插件，npm 包名與倉庫同名，當前資料中的版本爲 0.1.18，許可證 MIT。它解析本地 Obsidian 庫的 Markdown（含 frontmatter、標籤、標題、修改時間），在機器上建立索引與可選向量，不將整庫上傳；模型通過一組 obsidian_* Agent 工具檢索、閱讀並在你批准後追加或新建筆記。DSH 社區目錄將其歸類爲「記憶」，與官方應用商店無從屬關係，安裝來源以 SkillHub 目錄頁 與 GitHub 倉庫 爲準。
核心功能¶
下面能力均來自項目 README，按使用路徑歸納。
本地索引與檢索¶
插件在本地解析筆記結構，不上傳完整庫。默認 Keyword 檢索，支持英文前綴匹配與輸入時即時結果；若在設置中配置 OpenAI 兼容或 Ollama 的 embedding 端點、模型與維度，經「Test connection」並 Rebuild index 後可使用語義或混合模式。檢索可按文件夾、標籤過濾，並將段落加入 Context 托盤，複製帶來源標註的上下文包，或交由 Agent 通過工具搜索。
數據大盤¶
側邊欄 Obsidian Vault Studio 首頁展示筆記數、字數、標籤數、分塊數、7 日更新等統計；365 日熱力圖、14 日活動曲線、Agent 調用計數、最近筆記與標籤分佈亦在同一面板，便於對照庫活躍度與工具使用情況。
對話接入開關¶
Allow vault context in conversations 默認關閉。關閉時，所有 obsidian_* Agent 工具在執行前被拒絕；插件內的搜索與瀏覽仍可用。開啓後，模型才能通過工具訪問庫內容；用畢建議關閉，後續工具調用將被拒絕。README 另說明：該開關僅約束 obsidian_*；若需硬邊界，還需結合 DSH 工作區/沙箱權限，避免通用 read、grep、bash 觸及庫路徑。
安全寫入¶
模型不能刪除、移動、重命名或直接覆蓋筆記。寫入路徑爲：模型提出新建或追加 → 界面展示目標路徑與 diff → 你批准後執行；寫入有備份，會話內可撤銷。對應工具爲 obsidian_propose_write 與 obsidian_apply_write，撤銷用 obsidian_undo_write。
Agent 工具一覽¶
| 工具 | 作用 |
|---|---|
obsidian_search |
按模式、文件夾或標籤搜索段落 |
obsidian_read_note |
讀取整篇筆記 |
obsidian_list_notes |
列出或篩選筆記 |
obsidian_stats |
讀取索引、統計與工作區狀態 |
obsidian_propose_write |
創建追加/新建提案（不寫盤） |
obsidian_apply_write |
在你批准後應用提案 |
obsidian_undo_write |
撤銷本會話內的一次寫入 |
obsidian_index_status |
查看索引與 embedding 進度 |
對話中只有實際檢索或讀入的段落進入上下文，不會自動注入整庫。系統提示要求模型在 Obsidian 工具失敗時如實上報，且不得借通用文件工具繞過 Vault Studio 與接入開關。
隱私¶
索引、向量、設置與使用計數均本地保存；插件無遙測、不上傳庫。索引與向量數據路徑由你在設置中指定的 vault 與插件本地存儲決定，運行權限等同於當前 DSH 桌面進程，安裝前宜瀏覽源碼與 MIT 許可證。
安裝與啓用¶
環境要求¶
- DeepSeek Harness 0.2.x 桌面版，並已允許安裝第三方插件（
package.json中engines.dsh爲>=0.2.1-rc.5） - 本機已有的 Obsidian 庫目錄
安裝源¶
DSH 可從下列任一來源安裝，勿自行拼接未在文檔出現的 CLI 命令：
- GitHub 倉庫：
https://github.com/spark-ai-boy/dsh-obsidian-bridge - npm 包名：
dsh-obsidian-bridge
步驟¶
- 在 DSH 側邊欄打開 Plugins。
- 選擇 Add plugin → Install third-party plugin。
- 填入上述 GitHub 倉庫 URL 或 npm 包名，安裝完成後點擊 Enable。
- 在側邊欄打開 Obsidian Vault Studio。
首次運行¶
- 打開 Settings，選擇 vault 路徑，點擊 Save。
- 點擊 Rebuild index；首次索引完成後大盤與搜索可用。
- 檢索模式默認爲 Keyword，無需額外配置。
- 若需語義或混合檢索：在 Settings 填寫 OpenAI 兼容或 Ollama 的 embedding 端點、模型、維度，Test connection，保存後再次 Rebuild index。
- 大盤上的 Allow vault context in conversations 默認關；需要 Agent 讀庫時再打開。
典型用法¶
在界面中搜索與組上下文¶
在 Search 頁輸入關鍵詞或前綴，結果隨輸入更新；可按文件夾、標籤篩選，將段落加入 Context，複製帶引用的上下文包，或在關閉/開啓接入開關的前提下自行瀏覽 Notes 頁。
在對話中使用庫¶
- 在大盤打開 Allow vault context in conversations。
- 向模型提出與庫相關的任務，例如 README 中的表述：
- “Find my notes about RAG and cite the sources.”
- “Append today’s meeting notes to the project note.” - 確認僅檢索到的內容進入對話；不用時關閉接入開關。
模型改筆記¶
流程與 Notes 頁一致：提案 → 查看路徑與 diff → 批准 → 必要時 Undo。自動刪除、移動、重命名、覆蓋均不提供。
適用場景與注意¶
適合已經在 Obsidian 中沉澱筆記、希望在 DSH Agent 對話裏做可引用檢索、並控制寫盤風險的開發者或個人用戶。keyword 模式開箱即用；語義/混合檢索依賴你可用的 embedding 服務與本機重建索引的時間。
插件以 DSH 進程權限訪問你配置的 vault 路徑；第三方插件應從可信來源安裝，並結合 DSH 沙箱限制通用文件工具。社區目錄上的 star 數等元數據會變動，以頁面與 GitHub 實時顯示爲準。
結尾¶
dsh-obsidian-bridge 把 Obsidian 庫的索引、混合檢索、大盤統計與帶審批的寫入收進 DSH 側邊欄，在默認關閉 Agent 接入的前提下儘量把數據留在本機。進一步瞭解功能與截圖見倉庫 README；安裝與分類信息見 SkillHub 目錄，源碼與 issue 見 GitHub。
