dsh-plugin-obsidian

把 DeepSeek Harness（DSH） 和 Obsidian 连起来：让 DSH 里的模型可以直接、快速地查询你的 Obsidian 笔记，写入（新建 / 覆盖 / 追加 / 按标题插入 / 合并 frontmatter），也能整理（移动 / 重命名并自动更新链接，删除默认进 .trash/ 可恢复）。

• 零依赖：只用 Node 内置模块，没有构建步骤，装进 profile 就能跑。
• 零配置：自动从 Obsidian 自己的 obsidian.json 里发现仓库（vault），自动读取该仓库的 .obsidian/ 设置（日记格式、模板等）。
• 离线可用：直接读文件系统 + 内存索引，Obsidian 关着也能查、能写。
• 在线联动：如果仓库装了社区插件 Local REST API，还能操作正在运行的 Obsidian：打开笔记、读取当前笔记、用 Obsidian 自己的实时搜索、打开日记、列出/执行命令、列标签。API Key 与端口自动从插件配置里读取，不需要手工填写。

---

1. 安装

方式一：插件市场（推荐）

打开 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:）

把本仓库克隆到本地，以 link: 方式装进 profile（等价于 GUI 里「设置 → 插件」的安装操作）：

dsh plugin --profile <你的profile> add "E:\path\to\dsh-plugin-obsidian"

关于生效时机：新增 bundle 行会被正在运行的 DSH 热加载（无需重启即可用上 7 个工具）。 但修改插件源码后必须重启 DSH 才会加载新代码——ESM 模块缓存会继续返回旧模块（在「设置 → 插件」里禁用/启用本插件也无法绕过它）。 如果想让源码改动自动生效，可以在 profile 的 patch 里把本插件目录加进 HMR 的监视根：

- id: hmr
  name: '@deepseek-ai/dsh-hmr'
  config:
    root:
      - 'E:\path\to\dsh-plugin-obsidian'

安装后 11 个工具直接出现在模型可调用列表里，可用 obsidian_vaults 确认状态。

插件列表里的中文名与中文描述

DSH 的插件页显示的是插件自己声明的标题与描述，取自包内的 locale/<语言>.json：

{ "meta": { "title": "Obsidian 笔记", "description": "让 DeepSeek Harness 直接搜索、读取和写入 Obsidian 笔记……" } }

• 本插件提供 locale/zh.json（中文）与 locale/en.json（英文）：界面语言为中文时显示中文，英文时显示英文；两者都没有时才回退到 package.json 的 name / description。
• 卡片图标取自 package.json 的 icon：相对路径的 SVG/PNG/JPEG/WebP，≤256 KiB，且必须留在包目录内。本插件用 assets/icon.svg。
• 这些文件必须通过包的 exports 暴露（./locale/en.json、./locale/zh.json、./package.json），否则读不到。
• 改完标题/描述不需要重启：插件页每次打开都会重新读盘（页面已打开就重新打开一次）。

---

2. 工具一览

工具	作用
obsidian_vaults	列出 / 添加 / 切换仓库，查看索引与在线桥接状态
obsidian_search	全文、标签、路径、frontmatter、标题、正则搜索
obsidian_read	读取笔记（行窗口 + frontmatter + 标签 + 标题 + 链接 + 反向链接）
obsidian_list	目录树 / 平铺列表 / 标签云 / 文件夹统计
obsidian_links	出链、反向链接、指向不存在笔记的链接
obsidian_tasks	全库收集 - [ ] / - [x] 任务（状态 / 文本 / 文件夹过滤，带行号可精确改写）
obsidian_write	新建 / 覆盖 / 追加 / 前置 / 按标题插入，支持 frontmatter 合并、模板占位符、@daily 与 dry-run
obsidian_move	移动 / 重命名笔记，自动更新引用它的 wikilink 与 markdown 链接（支持 dry-run）
obsidian_delete	删除笔记：默认移入 .trash/ 可恢复，permanent: true 彻底删除；报告悬空反向链接
obsidian_attach	把本地图片 / PDF 等复制进仓库附件目录，返回 ![[...]] 嵌入链接，可顺手追加到笔记
obsidian_app	操作正在运行的 Obsidian（状态、打开、当前笔记、实时搜索、日记、命令、标签）

查询

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")             # 用 Obsidian 自己的实时搜索

mode：all（默认，全部词命中）/ any / phrase / regex / tag / path / frontmatter / title。 其他过滤参数：folder、path、exclude、tags、tag、caseSensitive、maxMatchesPerFile、vault。

为什么快：首次扫描建立「路径 → mtime/size」元数据索引（默认 3 秒 TTL，indexTtlMs 可调），已解析笔记按字节预算（默认 48MB）做 LRU 缓存；内容变化（mtime/size 变了）自动失效。重复查询通常几十毫秒。

读取

obsidian_read(note="Projects/Alpha")                  # 支持文件名 / 路径 / [[wikilink]] / 别名
obsidian_read(note="Home", offset=10, limit=30, backlinks=true)

写入

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（null = 删除该键）
obsidian_write(note="Inbox/想法", mode="append", content="预览", dryRun=true) # 只预览 diff，不落盘
obsidian_write(note="Inbox/想法", mode="append", content="写完后打开", open=true)
obsidian_write(note="@daily", mode="append", content="10:30 开始写周报")      # 离线日记：今天（或 @daily-2026-10-26）
obsidian_write(note="Meetings/评审会", template="会议记录")                    # 从模板创建（{{title}}/{{date}}/{{time}}）

• @daily：写入日记的快捷方式，路径由仓库自己的日记设置（.obsidian/daily-notes.json）计算，Obsidian 关着也能用；文件不存在就按日记设置创建。
• template：从模板文件夹（.obsidian/templates.json → folder）读取模板创建笔记，替换 {{title}}、{{date}}、{{time}} 与 {{date:格式}} / {{time:格式}}；模板自身的 frontmatter 会带过来；不能与 content 或非 create 的 mode 同时使用。

要点：

• 目标定位规则：note 里含 /（或 \）时按精确路径处理，不存在就新建；不含分隔符的裸名字才会按文件名 / wikilink / 别名模糊匹配到已有笔记。这样 blocker/child.md 这类显式路径绝不会被悄悄改写到另一个同名笔记里。
• 省略 mode 且有 content → create；省略 mode 且无 content → 只更新已有笔记的 frontmatter。
• mode="create" 遇到已存在的笔记会报错，可用 ifExists: append|overwrite|skip 改变行为。
• mode="insert" 插入到指定标题所在小节末尾；标题不存在时 headingFallback: end|error（默认 end）。若上一行与插入内容同为列表项，会直接续行而不插入空行。
• prepend 会插到 frontmatter 之后。
• content 自带 --- frontmatter 块时会被识别并规范化，不会重复写两遍。

写入安全性：同目录临时文件 + rename 原子替换（失败会清理临时文件）；路径必须落在仓库内（拒绝 ..、绝对路径、NUL）；拒绝 Windows 保留名（CON/NUL…）与以点或空格结尾的文件名；只允许 writableExtensions（默认 .md/.markdown/.txt）；readOnly: true 时拒绝一切写入；dryRun 只返回 diff；文件系统错误会转换成可自纠的提示（如「路径里有个文件不是文件夹」）。

整理笔记（移动 / 重命名 / 删除）

obsidian_move(note="Projects/Alpha", to="Archive/")                       # 移入 Archive，保留文件名
obsidian_move(note="Projects/Alpha", to="Archive/Alpha V2")               # 移动 + 重命名（缺扩展名自动补 .md）
obsidian_move(note="Projects/Alpha", to="Alpha Renamed", dryRun=true)     # 同文件夹重命名，先预览
obsidian_move(note="Projects/Alpha", to="Archive/", updateLinks=false)    # 只移动，不改任何链接
obsidian_delete(note="Inbox/旧想法")                                       # 默认移入 .trash/Inbox/旧想法.md
obsidian_delete(note="Inbox/旧想法", permanent=true, dryRun=true)          # 预览彻底删除与悬空链接

要点：

• to 的三种写法：以 / 结尾（或指向已存在的文件夹）→ 移入该文件夹并保留文件名；带扩展名 → 作为目标完整路径（文件夹不存在会自动创建）；其余情况（无分隔符的裸名字）→ 同文件夹重命名。
• 链接自动更新（updateLinks，默认开）：引用该笔记的 wikilink / markdown 链接会被改写，被移动笔记自己的相对链接也会修正，行为对齐 Obsidian 自带的重命名。改写规则：写死路径的链接在路径失效后改写为新位置（优先最短可解析形式）；裸名字链接只要仍能解析到该笔记就保持原样（出现同名歧义时改写为带路径的消歧形式）；代码块与行内代码里长得一样的文本不会被误改。
• 删除默认可恢复：默认移入仓库的 .trash/（保留原子目录避免重名，加数字后缀处理冲突）；permanent: true 才会真正删除文件。两种方式都会在结果里报告将悬空的反向链接，方便随后清理。
• 安全性与写入一致：路径必须落在仓库内、拒绝点目录（不能把笔记移进 .trash/ 或 .obsidian/ 绕过索引）、目标已存在时报错、readOnly 仓库拒绝整理、dryRun 只返回计划不改文件。

任务收集

obsidian_tasks()                                    # 全库未完成任务（默认 status "open"）
obsidian_tasks(status="all", folder="Projects")     # 指定文件夹 / 全部状态
obsidian_tasks(status="all", query="部署", limit=50)

每条任务带 path、line（1-based 行号）、status（open / done / other，[/] 这类自定义标记归入 other 且只在 all 里出现）和原文；代码块里的假任务不会误报。改任务状态：按 path + line 读到原文后改写该笔记即可。

附件

obsidian_attach(source="E:\\pics\\chart.png")                        # 复制进仓库附件目录，返回 ![[chart.png]]
obsidian_attach(source="...", note="@daily")                         # 复制并把嵌入链接追加进今天的日记
obsidian_attach(source="...", folder="Images/Deep", name="架构图")     # 自定义落点与文件名

落点遵守 Obsidian 自己的附件设置（.obsidian/app.json → attachmentFolderPath：""/"/" 仓库根、"./" 所链接笔记的文件夹、其余为固定文件夹），每次调用可用 folder 覆盖；重名自动加 -1 后缀。只接受本地文件（网络图片请先下载到本地）；允许的扩展名默认 png/jpg/jpeg/gif/webp/svg，可用配置 attachmentExtensions 调整。dry-run 预览落点。

在线联动（Local REST API）

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")

桥接不可用时会给出可执行的提示（例如「未安装 Local REST API 插件」），文件系统类工具不受影响。

行为引导（Agent 自主查库与记笔记）

工具只是能力，Agent 用不用、什么时候用，由注入到系统提示里的行为引导决定。插件通过 ctx.systemPrompt.section() 注册一段引导（obsidian:agent-guidance，可配置关闭），内容只有两条：

• 何时查库：用户提到他的笔记 / 过去的讨论 / 计划 / 决定时；复用已有记录能省去重复解释时；以及在下「我们从没聊过 X」这类结论之前——先搜一下，比错误断言便宜。
• 何时落笔：一轮实质性对话或任务结束后自主判断是否值得记：决定及其理由、方案与排障结论、项目进展、值得回看的参考、会议纪要。值得就直接写，不必请示——今天的日记追加一行（@daily），或写到话题匹配的文件夹；闲聊与瞬时问答不记。
• 另附一条纪律：建新笔记前先搜，优先扩展已有笔记而不是造近似重复。

引导只讲「何时 / 为何」，不复述工具参数（那是工具定义自己的事）。不想要这段提示时在配置里 agentGuidance: false 即可；没有 systemPrompt 服务的 profile 里插件照常工作，只是不带引导。

---

3. 配置（可选）

不配置也能用：自动发现 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:                                                  # 额外排除的 glob
      - 'templates/**'
    indexTtlMs: 3000
    maxCacheBytes: 50331648
    readOnly: false
    dailyFolder: Daily
    dailyFormat: YYYY-MM-DD
    attachmentFolder: attachments              # 附件落点覆盖（默认跟随 .obsidian/app.json）
    attachmentExtensions: ['.png', '.pdf']     # 附件允许的扩展名（默认 png/jpg/jpeg/gif/webp/svg）
    agentGuidance: true                        # 注入「何时查库 / 何时记笔记」的行为引导（默认开）
    # rest:
    #   enabled: true
    #   baseURL: http://127.0.0.1:27123
    #   apiKey: '...'      # 一般不需要，自动从插件 data.json 读取

配置会在挂载时校验，写错会明确报错（未知键也会报错）。切换/新增仓库后会把选择持久化到 %USERPROFILE%\.dsh\obsidian-plugin.json。

已知限制：DSH 的插件设置页只会为 zod 定义的配置渲染表单，本插件为了零依赖用的是 Standard Schema，所以那里显示为 unsupported（不影响使用，配置写在上面的 YAML 里即可）。

---

4. 故障排查

现象	处理
提示找不到仓库	先在 Obsidian 里打开一次该仓库；或用 obsidian_vaults(action="add", path="...")
搜索不到刚写的内容	索引默认 3 秒 TTL；obsidian_vaults(action="status", refresh=true) 可强制刷新
obsidian_app 说桥接不可用	确认 Obsidian 正在运行，且「设置 → 第三方插件」启用了 Local REST API
改了源码没生效	重启 DSH 桌面端（ESM 模块缓存）
写入报 not writable	该扩展名不在 writableExtensions 内，或仓库被设为 readOnly

---

5. 开发与测试

cd dsh-plugin-obsidian
node --test        # 71 个测试

测试覆盖：YAML/frontmatter 往返、标签/链接/标题解析、索引与缓存失效、8 种搜索模式、写入的 5 种模式与 ifExists、@daily 快捷方式、模板占位符渲染、移动的链接改写（裸名/路径/嵌入/代码块豁免/相对链接修正）、删除的回收站与冲突后缀、附件落点与重名后缀、任务收集与过滤、路径逃逸 / 保留文件名 / 只读拒绝、写入目标不被同名笔记劫持、工具参数校验、用 DSH 自己的 JSON-Schema 校验器校验每个工具的 parameters 与 output.schema 及真实返回值、UI 卡片呈现函数的纯函数性，以及针对本机真实 Obsidian 仓库的在线测试：2 个文件系统测试（Obsidian 关着也跑）和 3 个需要 Local REST API 的桥接测试（Obsidian 未运行或未装插件时自动跳过）。

目录结构：

lib/index.js     Cordis 插件入口：配置 schema、仓库发现、活动仓库与在线桥接的状态管理
lib/tools.js     11 个工具的 schema、执行体、render 与 UI 卡片
lib/vault.js     仓库索引、搜索、读取、写入、移动/删除、附件、任务、链接、日记
lib/markdown.js  frontmatter(YAML 子集)、标签、wikilink、标题解析
lib/rest.js      Obsidian Local REST API 客户端
lib/util.js      路径安全、glob、参数校验等工具函数

有意不做的事

• 删除默认走 .trash/（与 Obsidian 本地回收站一致）而不是直接删文件；彻底删除需要显式 permanent: true。
• 不修改 .obsidian/ 下的配置，也不把笔记移入点目录。
• 不跟随仓库内指向外部的符号链接（路径检查基于字符串解析）。

---

6. 许可

MIT