前言¶
在 DeepSeek Harness（dsh）的插件生態裏，一個常見的訴求是讓 agent 直接操作本地工具與本地數據。比如你日常用 Obsidian 管理筆記，又希望 dsh agent 能搜索、讀取、修改、移動這些筆記。如果走額外服務，往往會引入 MCP server、OAuth、Local REST API 社區插件等組件；而 dsh-obsidian 的思路更直接：把本地 Obsidian vault 作爲 Markdown 文件系統來處理。
dsh-obsidian 是一個 DSH 插件，由 mingzeng21 維護，採用 MIT 許可證。它把 dsh agent 連接到本地 Obsidian vault，支持搜索、讀取、寫入、移動和刪除（移入回收站）筆記。
這是什麼¶
一句話定位：dsh-obsidian 是 DeepSeek Harness（dsh）的 Obsidian vault 插件，掛載一組 obsidian_* 工具，讓 dsh agent 直接操作本地 Markdown 筆記。
它解決的核心問題是：讓 dsh 不用依賴額外 server 或瀏覽器插件，就能完成本地 vault 裏的常見筆記操作。安裝後，插件會解析 vault 根目錄，並把 12 個 obsidian_* 工具掛載給 agent，覆蓋搜索、讀取、寫入、追加、移動、刪除、反鏈查詢、標籤統計、frontmatter 屬性設置和刪除。
核心功能¶
直接讀寫 vault 文件系統¶
dsh-obsidian 直接讀寫 vault 文件系統，無需 MCP server、OAuth 或 Local REST API 社區插件。
默認路徑是 FsAccess，基於 node:fs 與 frontmatter、wikilink 解析。啓動時按以下規則解析 vault：
- 如果配置了顯式
vaultPath，優先使用它。 - 否則從
obsidian.json自動探測當前打開的 vault。
掛載 12 個 obsidian_* 工具¶
| 工具 | 作用 |
|---|---|
obsidian_list |
列出 vault 裏的筆記，可按子目錄過濾、限制條數 |
obsidian_search |
全文檢索，返回匹配行 + 上下文；大小寫不敏感，只搜 .md |
obsidian_read |
讀取一篇筆記，包括正文和解析後的 frontmatter |
obsidian_frontmatter |
只讀筆記的 YAML 屬性 |
obsidian_backlinks |
找出鏈接到某篇筆記的筆記，基於 [[wikilink]] |
obsidian_write |
新建或覆蓋一篇筆記；父目錄不存在時自動創建 |
obsidian_append |
向筆記末尾追加內容 |
obsidian_move |
移動或重命名筆記，純文件系統同步更新 [[鏈接]] |
obsidian_delete |
把筆記移入 .trash/，可逆，不永久刪除 |
obsidian_set_property |
設置或更新筆記的單個 frontmatter 屬性 |
obsidian_delete_property |
刪除筆記的某個 frontmatter 屬性 |
obsidian_tags |
列出 vault 中所有標籤及使用次數 |
所有工具的路徑參數都相對於 vault 根目錄，例如：
Folder/Note.md
可選委託 obsidian CLI¶
useCli 默認關閉。開啓且檢測到 obsidian CLI 時，property:set 與 property:remove 可以委託給 CLI 執行；其餘操作始終走 FsAccess。如果 CLI 執行失敗，會靜默回退到 FsAccess。
安裝與啓用¶
環境要求¶
- DeepSeek Harness（dsh）
- Node.js ≥ 22.12.0
package.json版本爲0.2.2- 依賴
yaml ^2.7.0 peerDependencies包含：@deepseek-ai/cordis@deepseek-ai/dsh-tools@deepseek-ai/schemastery
已驗證兼容至 dsh v0.1.1-rc.2（含 v0.1.0-rc.8）。
安裝¶
執行下面的命令安裝到當前 profile：
dsh plugin --profile web add dsh-obsidian
web 只是 profile 名，可以換成你實際運行 agent 所用的 profile，例如 headless、tui 等。
鎖定版本¶
如果你想鎖定 0.2.2：
dsh plugin --profile web add dsh-obsidian@0.2.2
更新¶
重跑 add 會拉取 latest：
dsh plugin --profile web add dsh-obsidian
更新後重啓 harness，或刷新 Web UI：
dsh web
然後用下面的命令確認版本：
dsh plugin --profile web list
卸載¶
dsh plugin --profile web remove dsh-obsidian
配置¶
| 配置項 | 默認值 | 說明 |
|---|---|---|
vaultPath |
自動探測 | vault 的絕對路徑；留空則按平臺從 obsidian.json 自動探測當前打開的 vault |
useCli |
false |
可用時把 property:set / property:remove 委託給 obsidian CLI |
excludeDirs |
[".obsidian", ".git", ".trash"] |
搜索與列出時排除的目錄 |
如果你明確知道 vault 在哪裏，可以顯式配置 vaultPath；否則插件會從 obsidian.json 自動探測。
典型用法¶
下面是插件覆蓋的日常操作路徑。具體由 dsh agent 根據任務調用對應工具。
- 搜索筆記：
obsidian_search做全文檢索，返回匹配行和上下文。 - 讀取筆記：
obsidian_read讀取正文與 frontmatter；如果只需要屬性，用obsidian_frontmatter。 - 新建或修改筆記：
obsidian_write可新建或覆蓋；只想追加內容時用obsidian_append。 - 移動或重命名：
obsidian_move會移動文件，並同步更新相關[[鏈接]]。 - 刪除筆記：
obsidian_delete把筆記移入 vault 的.trash/，不會永久刪除。 - 處理 frontmatter：
obsidian_set_property設置或更新單個 YAML 屬性；obsidian_delete_property刪除某個屬性。 - 查詢鏈接關係：
obsidian_backlinks找出鏈接到某篇筆記的筆記。 - 統計標籤：
obsidian_tags列出 vault 中所有標籤及使用次數。
路徑參數都相對於 vault 根目錄。例如要處理某個子目錄下的筆記：
Projects/DSH/dsh-obsidian.md
適用場景與注意¶
適合本地 Obsidian vault 的日常管理：搜索、讀取、寫入、追加、移動、刪除、反鏈查詢、標籤統計，以及 frontmatter 屬性維護。
使用前需要注意幾點：
- 插件以當前 dsh 進程權限運行。安裝前應檢查源碼、依賴與許可證。
- 路徑越界防護：所有路徑參數都會解析並校驗，必須落在 vault 根目錄內；
../或絕對路徑逃逸會被拒絕。 - 刪除可逆：
obsidian_delete只把筆記移入 vault 的.trash/，不永久刪除。 - 默認不觸碰
.obsidian/：搜索與列出默認排除.obsidian/、.git/、.trash/。 - frontmatter 與 wikilink 保護：讀取和寫入不應破壞 YAML 屬性和
[[鏈接]]，除非任務明確要求修改。 - 如果你依賴
obsidianCLI 管理 frontmatter，可以開啓useCli；否則默認使用文件系統路徑。
