前言¶
DSH 的核心理念是“一切皆插件”，這意味着工具需要具備極強的環境連接能力。對於使用 Obsidian 作爲知識庫的開發者，最大的痛點在於：Obsidian 默認不掃描代碼倉庫，它僅索引 vault 裏的 .md 文件和 [[wiki 鏈接]]。因此，關鍵不在於讓 Obsidian 去掃描項目，而在於將本地項目的元數據（如依賴、技術棧）轉化爲 Obsidian 能理解的 Wiki 鏈接結構。
dsh-obsidian 插件通過 DSH 掃描本地項目，生成對應的筆記與圖譜邊，使 Obsidian 圖譜視圖自動呈現項目間的知識關聯。它是一個獨立、非官方的 DSH 集成方案。
核心功能¶
- 原生 DSH 集成：在 DSH 的設置中直接提供原生標籤頁，無需額外 UI 組件。
- 本地項目掃描：掃描器支持 manifest 探測，能夠提取技術棧與項目信息。
- 確定性知識圖譜：自動生成依賴、技術、區域、主題四種類型的邊，結構確定，無虛構關聯。
- 雙傳輸模式：支持本地 REST API（loopback）與文件系統回退模式。若不啓用 REST 插件，可使用文件系統直寫。
- 增量寫入：通過
graph/.dsh-obsidian-state文件管理狀態，僅重寫或刪除插件管理的文件。 - 安全與預覽：具備嚴格的 loopback + 同源保護機制。設置頁中提供迷你力導向圖預覽。
安裝與啓用¶
使用以下命令將插件安裝到 DSH Web 配置文件中：
dsh plugin --profile web add ./artifacts/harness-flow-dsh-obsidian-0.1.0-alpha.0.tgz
安裝完成後，在 DSH 設置頁開啓插件，即可使用“掃描項目”與“生成知識圖譜”功能。
典型用法¶
- 配置環境變量（可選）：
若需指定 vault 路徑或掃描根目錄，可通過環境變量覆蓋默認行爲：
export DSH_OBSIDIAN_VAULT="/path/to/vault"
export DSH_OBSIDIAN_SCAN_ROOTS='["/path/to/project1", "/path/to/project2"]'
-
執行生成：
在 DSH 設置頁點擊“掃描項目”，確認識別到本地項目後，點擊“生成知識圖譜”。 -
在 Obsidian 中查看：
打開對應的 Obsidian vault，進入圖譜視圖。生成的筆記位於graph/命名空間下，通過[[鏈接]]將項目、技術棧與區域關聯起來。
注意事項¶
- 完全離線：Obsidian 應用無需在生成筆記期間運行，插件以當前 DSH 進程權限工作，完全本地化處理。
- 數據安全：無數據會離開本機。
- 基本功能：基礎功能無需安裝 Obsidian 的 REST 插件，依賴文件系統即可運行。
- 文件管理：插件僅會重寫或刪除其自身管理的文件，不會影響用戶手動編寫的筆記。
