前言¶
在 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；否则默认使用文件系统路径。
