前言¶
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 仓库：
