前言¶
DSH 的智能體經常需要在一個本地知識庫裏讀文件、改文件、查鏈接、讀附件。對 Obsidian vault 來說，直接讓 agent 用通用文件工具操作，容易出現路徑越界、誤刪、併發覆蓋、附件不可控等問題。
dsh-obsidian 把這類操作收斂成一組 obsidian_* 工具，並且只在 agent 消息匹配觸發詞時注入工具。它是 host-only 集成，不導出瀏覽器客戶端，也不安裝 React、REST API 或 HTTP server 依賴。
這是什麼¶
dsh-obsidian 是 gxpppp 維護的 DeepSeek Harness (DSH) 插件，定位是：
Host-only Obsidian integration for DeepSeek Harness (DSH).
它面向需要在 DSH agent 中操作 Obsidian vault 的開發者，提供 vault 文件、知識檢索、附件、鏈接、編輯器和命令相關工具。
核心能力¶
工具注入方式¶
- 插件暴露 25 個
obsidian_*工具。 - 工具和相關引導信息只注入給匹配 configured trigger vocabulary 的 agent。
- 不匹配的會話不會收到這些工具 schema。
Vault 工具¶
Vault 工具可以在沒有 Obsidian companion 的情況下使用：
obsidian_status
obsidian_list
obsidian_stat
obsidian_read
obsidian_write
obsidian_edit
obsidian_append
obsidian_mkdir
obsidian_copy
obsidian_move
obsidian_delete
這些工具面向 vault 文件本身，例如列出、讀取、寫入、編輯、追加、創建目錄、複製、移動和刪除。
知識與 Obsidian 語義工具¶
obsidian_search
obsidian_metadata
obsidian_frontmatter_update
obsidian_link_resolve
obsidian_links
obsidian_link_insert
這一組覆蓋搜索、元數據、frontmatter 更新、鏈接解析、鏈接列表和鏈接插入。
附件工具¶
obsidian_attachment_add
obsidian_attachment_read
附件接受 DSH durable image reference 或 vault-relative source path。host absolute paths、URLs、dot directories 和 unbounded binary payloads 會被拒絕。
Editor 與命令工具¶
Editor 和命令工具需要 Obsidian companion：
obsidian_active
obsidian_inline_edit
obsidian_open
obsidian_commands_list
obsidian_command
obsidian_notice
如果你只需要 vault、知識、附件和鏈接工具，可以不啓用 companion；如果需要使用編輯器或命令工具，需要安裝 companion。
Vault 層約束¶
已覈實的 vault 層約束包括：
- vault-relative paths
- canonical realpath containment
- protected dot directories
- atomic writes
- serialized appends
- SHA-256 revisions
- optimistic
if_matchconflicts - binary size limits
- cancellation
- internal trash by default
Companion IPC¶
Companion 通過 Windows named pipe 或 Unix socket 通信，並使用 versioned JSON-lines IPC，同時做 vault identity verification。
安裝與啓用¶
1. 確認 DSH 版本¶
先把 DSH host package 安裝到實際運行 agent 的 profile，並顯式使用 DSH 0.1.0-rc.8。
DSH 0.1.0-rc.8 當前是 prerelease，發佈在 npm dist-tag next，不是 latest；npm 的 DSH latest dist-tag 仍指向 rc.7。
2. 安裝 host 插件包¶
下面命令把發佈 tarball 安裝到指定 profile。把 <profile> 替換爲你實際啓動的 profile。
dsh plugin --profile <profile> add "https://github.com/gxpppp/dsh-obsidian/releases/download/dsh-obsidian-v0.3.1/deepseek-ai-dsh-client-ui-obsidian-0.3.1.tgz"
3. 校驗發佈包哈希¶
安裝前應校驗 release asset hashes，對照對象是 SHA256SUMS。
4. 重啓 profile¶
添加或升級插件後，重啓對應 profile。
5. 按需安裝 companion¶
如果需要使用 editor 或 command 工具，把 Obsidian companion 安裝到 vault：
node scripts/install-companion.mjs --vault <vault path>
把 <vault path> 替換爲實際 vault 路徑。
配置¶
在 DSH settings 中配置 obsidian namespace。已覈實的配置字段包括：
obsidian.vaultPath
obsidian.mode
obsidian.approvalMode
obsidian.commandPolicy
obsidian.commandAllowlist
obsidian.triggerKeywords
obsidian.enabled
obsidian.protectedPaths
obsidian.maxTextBytes
obsidian.maxAttachmentBytes
這些字段分別對應 vault 路徑、運行模式、審批模式、命令策略、命令允許列表、觸發詞、啓用開關、受保護路徑、文本大小限制和附件大小限制。
典型用法¶
只用 Vault 工具¶
1、安裝 host 插件包。
2、配置 obsidian.vaultPath、obsidian.triggerKeywords 和 obsidian.enabled。
3、在匹配觸發詞的 agent 中調用 vault、知識、附件或鏈接工具。
使用 Editor 和命令工具¶
1、先完成 host 插件包安裝。
2、把 companion 安裝到 vault。
3、配置 obsidian.mode、obsidian.approvalMode、obsidian.commandPolicy 和 obsidian.commandAllowlist。
4、重啓 profile，並在啓用 companion 的 Obsidian 環境中使用 editor 和 command 工具。
適用場景與注意¶
適合使用：
- 在 DSH agent 中讀寫 Obsidian vault。
- 按觸發詞控制 25 個
obsidian_*工具的注入。 - 使用 vault、知識、附件和鏈接工具，且不引入瀏覽器端依賴。
- 在需要時使用 Obsidian companion 的 editor 和 command 能力。
使用前注意：
- DSH
0.1.0-rc.8是 prerelease，不是 npmlatest所指版本。 - Node.js 要求
>=22.19.0，npm 要求>=11，TypeScript 要求5.7。 - 不要混用 host 和 companion 的 release lines。
- editor 和 command 工具依賴 companion。
- 附件不接受 host absolute paths、URLs、dot directories 和 unbounded binary payloads。
- 插件會加入你啓動的 DSH 插件環境，並能訪問配置中的 vault 路徑和 companion；它實際擁有的文件系統與進程權限取決於當前 dsh 進程。安裝前應檢查源碼、許可與變更內容。
- 已覈實資料沒有給出許可證和星標數量；使用前請到倉庫查看當前許可與變更。
結尾¶
dsh-obsidian 的價值在於把 Obsidian vault 操作收進 DSH 的工具面：host-only、工具按觸發詞注入、vault 層有明確邊界，並且 editor 和 command 能力通過 companion 擴展。
目錄頁：
https://www.skillhub.cn/plugins/gxpppp/dsh-obsidian
GitHub 倉庫：
