前言¶

做 DSH 插件時，本地 Obsidian vault 常被當作長期知識庫：筆記、資料索引、創作素材都可能放在裏面。若只用文件系統直讀，簡單但拿不到 Obsidian 運行時的索引與命令能力；若只接 Local REST API，又必須保證 Obsidian 在線。

下面介紹 dsh-obsidian-assistant。它是 DeepSeek Harness 插件（Cordis toolset），統一操作同一個 vault：文件通道不依賴 Obsidian 運行，REST 通道在 Obsidian 在線時自動增強。

這是什麼¶

dsh-obsidian-assistant 由 iamzcr 維護，許可證爲 MIT。

它提供搜索、讀寫筆記、雙向鏈接 / 關係圖譜、批量整理；並通過 Obsidian 的「Local REST API」社區插件調用高級能力（高速全文搜索、觸發命令 / 模板）。

核心功能¶

文件通道¶

下面這些能力不依賴 Obsidian 運行。

• obsidian_search：全文 / 標題檢索，支持按 tag 過濾，返回路徑 + 片段 + 標籤。
• obsidian_read_note：讀單篇筆記，包含 frontmatter + 正文，可帶 / 不帶 .md 後綴。
• obsidian_create_note：新建筆記，可帶 YAML frontmatter，拒絕覆蓋已存在筆記。
• obsidian_update_note：字面量替換 / 追加編輯，冪等、安全。
• obsidian_list_structure：文件夾樹 + 標籤統計 + 孤立筆記。
• obsidian_backlinks：反向鏈接 + 出鏈 + tag 歸屬圖譜。
• obsidian_batch：批量移動 / 重命名，自動重寫全庫 [[wikilink]]。
• obsidian_export_novel：把 vault 裏按 第X章-標題 命名的章節筆記，清洗成可粘貼到小說平臺的 TXT / Markdown 文稿。

REST 通道¶

需要 Obsidian 運行，並安裝 Local REST API 社區插件。

• obsidian_rest_search：Obsidian 內部索引高速全文搜索，大庫首選。
• obsidian_list_commands：列出 Obsidian 命令（id + 名稱）。
• obsidian_run_command：觸發命令（Templater / Dataview 重渲染等）。
• obsidian_rest_query：透傳任意 REST 端點，適合兜底 / 高級用法。

REST API 不可用時，所有讀寫自動走文件模式，無感知降級。

安裝與啓用¶

資料未提供官方安裝命令原文，下面按已覈實的 profile bundle 配置方式接入。先把它加進 profile 的 bundles 列表，再爲它配置 vaultPath。

1、在 $DSH_HOME/profiles/<name>/package.json 的 dsh.profile.bundles 中加入 dsh-obsidian-assistant。

2、在 $DSH_HOME/profiles/<name>/cordis.patch.yml 頂層數組追加插件條目，並在 config 中寫必填項 vaultPath：

# $DSH_HOME/profiles/<name>/cordis.patch.yml
- id: dsh-obsidian-assistant
  config:
    vaultPath: 'D:/my-notes'

vaultPath 是 vault 根目錄絕對路徑，必填。可選配置有：apiUrl、apiToken、enableRestApi、excludePatterns、maxResults，資料說明它們有默認值。

excludePatterns 支持目錄名前綴匹配和 * 通配。

典型用法¶

檢索與讀取¶

先檢索，再讀取。obsidian_search 做全文 / 標題檢索，可按 tag 過濾，返回路徑、片段和標籤。obsidian_read_note 讀單篇筆記，可帶或不帶 .md 後綴，讀取結果包含 frontmatter 和正文。

新建與編輯¶

新建筆記用 obsidian_create_note，可帶 YAML frontmatter，並拒絕覆蓋已存在筆記。

編輯已有筆記用 obsidian_update_note，支持字面量替換和追加編輯，適合需要冪等、可重複執行的任務。

結構與鏈接¶

obsidian_list_structure 提供文件夾樹、標籤統計和孤立筆記。

obsidian_backlinks 提供反向鏈接、出鏈和 tag 歸屬圖譜，適合在整理前先看引用關係。

批量移動 / 重命名¶

obsidian_batch 支持批量移動 / 重命名，並自動重寫全庫中的 [[wikilink]]，同時返回更新了幾處鏈接。

這裏有一個已知限制：harness 的 FileSystem 服務無 delete / rename API。在 harness ctx.fs 後端下，move 是「複製 + 源文件清空」（sourceRemoved: false）；在純 Node fallback 下才是真正的 rename（sourceRemoved: true）。數據不會丟失，但源位置可能殘留空文件。

小說導出¶

如果 vault 裏有一批按 第X章-標題 命名的章節筆記，可以用 obsidian_export_novel 清洗成 TXT / Markdown 文稿，方便粘貼到小說平臺。

例如，讓模型執行：

把 小說/ 目錄下的章節導出成 txt 方便我發佈到起點

等價於：

obsidian_export_novel({ folder: '小說', format: 'txt' })

如果庫裏有廢稿或重複章節，也可以排除。例如：

導出 小說，但排除第 3 章和標題帶 "浪漫代碼" 的廢稿

等價於：

obsidian_export_novel({
  folder: '小說',
  format: 'txt',
  exclude: ['3', '浪漫代碼']
})

命令與 Dataview¶

Local REST API 無原生 dataview 端點。要做 Dataview 查詢，先通過 obsidian_list_commands 找到 Dataview 命令 id，再用 obsidian_run_command 觸發。

Templater 重渲染等命令也可以通過 obsidian_run_command 觸發。

REST 通道冒煙¶

如果已經配置好 Local REST API，可以跑即時冒煙：

OBSIDIAN_API_KEY=<key> OBSIDIAN_API_URL=https://127.0.0.1:27124 npm run rest:smoke

這條命令用於驗證通道 B 是否可用。

注意¶

• vaultPath 必填；apiUrl、apiToken、enableRestApi、excludePatterns、maxResults 有默認值。
• 所有路徑必須是 vault 相對路徑，逃逸（../）一律拒絕。
• REST API 不可用時，所有讀寫自動走文件模式。
• Local REST API 默認 HTTPS + 自簽名，插件已在請求層用 node:https（rejectUnauthorized: false）容忍，無需額外設置環境變量。
• 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證。

鏈接¶

GitHub：https://github.com/iamzcr/dsh-obsidian-assistant

插件目錄線索：https://www.skillhub.cn/plugins/iamzcr/dsh-obsidian-assistant（該地址來自插件線索，未在本次抓取資料中核實）