前言¶
DeepSeek Harness（DSH）采用「一切皆插件」的架构，将插件视为与模型对话的工具集。在构建智能体时，让模型直接操作笔记系统是一个常见需求。通常需要自己写脚本、维护索引或依赖外部 API，既增加维护成本，又容易引入依赖与配置。
下面介绍 dsh-plugin-obsidian，这是一个为 DeepSeek Harness 提供的 Obsidian 仓库桥接插件。它让 DSH 里的模型可以直接查询本地笔记，也能写入（新建/覆盖/追加/按标题插入/合并 frontmatter），同时支持离线模式与在线联动。
插件概述¶
该插件由 Yaemikoreal 维护，分类为「记忆」。它将 Obsidian vault 作为 DSH 的工具集，提供 7 个工具函数：仓库管理、搜索、读取、列表、链接分析、写入以及与正在运行的 Obsidian 应用联动。
核心价值在于零依赖、零配置：只用 Node 内置模块，自动从 Obsidian 的 obsidian.json 发现仓库，直接读文件系统 + 内存索引，无需构建步骤。如果仓库安装了社区插件 Local REST API，还能操作正在运行的 Obsidian。
安装¶
插件安装后 7 个工具会直接出现在模型可调用列表里，可用 obsidian_vaults 确认状态。
方式一：插件市场（推荐）¶
打开 DSH 的「设置 → 插件市场」，搜索 obsidian，点「安装」即可。
方式二：命令行安装¶
从 GitHub Release 安装预构建 tarball：
dsh plugin --profile <你的profile> add https://github.com/Yaemikoreal/dsh-plugin-obsidian/releases/latest/download/dsh-plugin-obsidian.tgz
或直接从 GitHub 源码安装：
dsh plugin --profile <你的profile> add https://github.com/Yaemikoreal/dsh-plugin-obsidian
卸载：
dsh plugin --profile <你的profile> remove dsh-plugin-obsidian
方式三：本地开发¶
把本仓库克隆到本地，以 link: 方式装进 profile：
dsh plugin --profile <你的profile> add "E:\path\to\dsh-plugin-obsidian"
修改插件源码后必须重启 DSH 才会加载新代码。
工具一览¶
| 工具 | 作用 |
|---|---|
obsidian_vaults |
列出 / 添加 / 切换仓库，查看索引与在线桥接状态 |
obsidian_search |
全文、标签、路径、frontmatter、标题、正则搜索 |
obsidian_read |
读取笔记（行窗口 + frontmatter + 标签 + 标题 + 链接 + 反向链接） |
obsidian_list |
目录树 / 平铺列表 / 标签云 / 文件夹统计 |
obsidian_links |
出链、反向链接、指向不存在笔记的链接 |
obsidian_write |
新建 / 覆盖 / 追加 / 前置 / 按标题插入，支持 frontmatter 合并 |
obsidian_app |
操作正在运行的 Obsidian（状态、打开、当前笔记、实时搜索、日记、命令、标签） |
查询¶
obsidian_search 支持多种搜索模式，默认为 all（全部词命中），也支持 any / phrase / regex / tag / path / frontmatter / title。
示例：
obsidian_search(query="部署", mode="all", context=1, limit=10)
obsidian_search(query="project", mode="tag")
obsidian_search(query="status:done", mode="frontmatter")
obsidian_search(query="Projects/*.md", mode="path")
obsidian_search(query="(?i)api[_ ]key", mode="regex")
obsidian_search(query="周报", source="app")
首次扫描会建立「路径 → mtime/size」元数据索引，默认 3 秒 TTL，已解析笔记按字节预算（默认 48MB）做 LRU 缓存。内容变化（mtime/size 变了）会自动失效。重复查询通常几十毫秒。
读取¶
obsidian_read 支持文件名 / 路径 / [[wikilink]] / 别名。
示例：
obsidian_read(note="Projects/Alpha")
obsidian_read(note="Home", offset=10, limit=30, backlinks=true)
写入¶
obsidian_write 支持多种写入模式：
obsidian_write(note="Inbox/想法", content="# 想法\n\n正文\n") # create（默认）
obsidian_write(note="Inbox/想法", mode="append", content="追加一段")
obsidian_write(note="Inbox/想法", mode="prepend", content="> 摘要")
obsidian_write(note="Inbox/想法", mode="insert", heading="待办", content="- [ ] 新任务")
obsidian_write(note="Inbox/想法", mode="overwrite", content="# 全新内容\n")
obsidian_write(note="Inbox/想法", frontmatter={status: "done", owner: null}) # 只改 frontmatter
obsidian_write(note="Inbox/想法", mode="append", content="预览", dryRun=true) # 只预览 diff
目标定位规则：note 里含 /（或 \）时按精确路径处理，不存在就新建；不含分隔符的裸名字才会按文件名 / wikilink / 别名模糊匹配到已有笔记。
在线联动¶
如果仓库装了社区插件 Local REST API，可用 obsidian_app 操作正在运行的 Obsidian：
obsidian_app(action="status")
obsidian_app(action="open", note="Projects/Alpha")
obsidian_app(action="active")
obsidian_app(action="search", query="部署", contextLength=120)
obsidian_app(action="daily", date="2026-10-10")
obsidian_app(action="command", query="template")
obsidian_app(action="command", command="editor:save-file")
obsidian_app(action="tags")
桥接不可用时插件会给出可执行的提示，文件系统类工具不受影响。
配置（可选）¶
不配置也能用：自动发现 Obsidian 注册表里最近打开的仓库。
需要指定仓库或调整行为时，在 profile 的 patch 文件（%USERPROFILE%\.dsh\profiles\<profile>\cordis.patch.yml）里加：
- id: obsidian
name: dsh-plugin-obsidian
config:
vault: 'C:\Users\you\Documents\My Vault'
vaults:
- 'D:\Notes\Work'
excludes:
- 'templates/**'
indexTtlMs: 3000
maxCacheBytes: 50331648
readOnly: false
dailyFolder: Daily
dailyFormat: YYYY-MM-DD
配置会在挂载时校验，写错会明确报错。切换/新增仓库后会把选择持久化到 %USERPROFILE%\.dsh\obsidian-plugin.json。
故障排查¶
| 现象 | 处理 |
|---|---|
| 提示找不到仓库 | 先在 Obsidian 里打开一次该仓库；或用 obsidian_vaults(action="add", path="...") |
| 搜索不到刚写的内容 | 索引默认 3 秒 TTL；obsidian_vaults(action="status", refresh=true) 可强制刷新 |
obsidian_app 说桥接不可用 |
确认 Obsidian 正在运行，且「设置 → 第三方插件」启用了 Local REST API |
| 改了源码没生效 | 重启 DSH 桌面端 |
写入报 not writable |
该扩展名不在 writableExtensions 内，或仓库被设为 readOnly |
开发与测试¶
本地开发时可以运行：
cd dsh-plugin-obsidian
node --test
测试覆盖 YAML/frontmatter 往返、标签/链接/标题解析、索引与缓存失效、8 种搜索模式、写入的 5 种模式与 ifExists、路径安全、工具参数校验，以及针对本机真实 Obsidian 仓库的在线测试。
限制与不提供的能力¶
- 不提供删除 / 重命名工具（避免模型误删笔记）。
- 不修改
.obsidian/下的配置。 - 不跟随仓库内指向外部的符号链接（路径检查基于字符串解析）。
适用场景¶
适合需要让模型直接操作本地笔记系统的 DSH 用户，尤其是需要离线可用、零依赖的智能体场景。使用前应检查源码与许可证。
结语¶
dsh-plugin-obsidian 将 Obsidian vault 作为 DSH 的工具集，提供了从查询、读取到写入的完整能力，同时支持离线模式与在线联动。通过 7 个工具函数，模型可以像操作本地文件系统一样操作笔记，无需额外脚本或配置。
