前言¶

做 DSH 插件时，本地 Obsidian vault 常被当作长期知识库：笔记、资料索引、创作素材都可能放在里面。若只用文件系统直读，简单但拿不到 Obsidian 运行时的索引与命令能力；若只接 Local REST API，又必须保证 Obsidian 在线。

下面介绍 dsh-obsidian-assistant。它是 DeepSeek Harness 插件（Cordis toolset），统一操作同一个 vault：文件通道不依赖 Obsidian 运行，REST 通道在 Obsidian 在线时自动增强。

这是什么¶

dsh-obsidian-assistant 由 iamzcr 维护，许可证为 MIT。

它提供搜索、读写笔记、双向链接 / 关系图谱、批量整理；并通过 Obsidian 的「Local REST API」社区插件调用高级能力（高速全文搜索、触发命令 / 模板）。

核心功能¶

文件通道¶

下面这些能力不依赖 Obsidian 运行。

• obsidian_search：全文 / 标题检索，支持按 tag 过滤，返回路径 + 片段 + 标签。
• obsidian_read_note：读单篇笔记，包含 frontmatter + 正文，可带 / 不带 .md 后缀。
• obsidian_create_note：新建笔记，可带 YAML frontmatter，拒绝覆盖已存在笔记。
• obsidian_update_note：字面量替换 / 追加编辑，幂等、安全。
• obsidian_list_structure：文件夹树 + 标签统计 + 孤立笔记。
• obsidian_backlinks：反向链接 + 出链 + tag 归属图谱。
• obsidian_batch：批量移动 / 重命名，自动重写全库 [[wikilink]]。
• obsidian_export_novel：把 vault 里按 第X章-标题 命名的章节笔记，清洗成可粘贴到小说平台的 TXT / Markdown 文稿。

REST 通道¶

需要 Obsidian 运行，并安装 Local REST API 社区插件。

• obsidian_rest_search：Obsidian 内部索引高速全文搜索，大库首选。
• obsidian_list_commands：列出 Obsidian 命令（id + 名称）。
• obsidian_run_command：触发命令（Templater / Dataview 重渲染等）。
• obsidian_rest_query：透传任意 REST 端点，适合兜底 / 高级用法。

REST API 不可用时，所有读写自动走文件模式，无感知降级。

安装与启用¶

资料未提供官方安装命令原文，下面按已核实的 profile bundle 配置方式接入。先把它加进 profile 的 bundles 列表，再为它配置 vaultPath。

1、在 $DSH_HOME/profiles/<name>/package.json 的 dsh.profile.bundles 中加入 dsh-obsidian-assistant。

2、在 $DSH_HOME/profiles/<name>/cordis.patch.yml 顶层数组追加插件条目，并在 config 中写必填项 vaultPath：

# $DSH_HOME/profiles/<name>/cordis.patch.yml
- id: dsh-obsidian-assistant
  config:
    vaultPath: 'D:/my-notes'

vaultPath 是 vault 根目录绝对路径，必填。可选配置有：apiUrl、apiToken、enableRestApi、excludePatterns、maxResults，资料说明它们有默认值。

excludePatterns 支持目录名前缀匹配和 * 通配。

典型用法¶

检索与读取¶

先检索，再读取。obsidian_search 做全文 / 标题检索，可按 tag 过滤，返回路径、片段和标签。obsidian_read_note 读单篇笔记，可带或不带 .md 后缀，读取结果包含 frontmatter 和正文。

新建与编辑¶

新建笔记用 obsidian_create_note，可带 YAML frontmatter，并拒绝覆盖已存在笔记。

编辑已有笔记用 obsidian_update_note，支持字面量替换和追加编辑，适合需要幂等、可重复执行的任务。

结构与链接¶

obsidian_list_structure 提供文件夹树、标签统计和孤立笔记。

obsidian_backlinks 提供反向链接、出链和 tag 归属图谱，适合在整理前先看引用关系。

批量移动 / 重命名¶

obsidian_batch 支持批量移动 / 重命名，并自动重写全库中的 [[wikilink]]，同时返回更新了几处链接。

这里有一个已知限制：harness 的 FileSystem 服务无 delete / rename API。在 harness ctx.fs 后端下，move 是「复制 + 源文件清空」（sourceRemoved: false）；在纯 Node fallback 下才是真正的 rename（sourceRemoved: true）。数据不会丢失，但源位置可能残留空文件。

小说导出¶

如果 vault 里有一批按 第X章-标题 命名的章节笔记，可以用 obsidian_export_novel 清洗成 TXT / Markdown 文稿，方便粘贴到小说平台。

例如，让模型执行：

把 小说/ 目录下的章节导出成 txt 方便我发布到起点

等价于：

obsidian_export_novel({ folder: '小说', format: 'txt' })

如果库里有废稿或重复章节，也可以排除。例如：

导出 小说，但排除第 3 章和标题带 "浪漫代码" 的废稿

等价于：

obsidian_export_novel({
  folder: '小说',
  format: 'txt',
  exclude: ['3', '浪漫代码']
})

命令与 Dataview¶

Local REST API 无原生 dataview 端点。要做 Dataview 查询，先通过 obsidian_list_commands 找到 Dataview 命令 id，再用 obsidian_run_command 触发。

Templater 重渲染等命令也可以通过 obsidian_run_command 触发。

REST 通道冒烟¶

如果已经配置好 Local REST API，可以跑实时冒烟：

OBSIDIAN_API_KEY=<key> OBSIDIAN_API_URL=https://127.0.0.1:27124 npm run rest:smoke

这条命令用于验证通道 B 是否可用。

注意¶

• vaultPath 必填；apiUrl、apiToken、enableRestApi、excludePatterns、maxResults 有默认值。
• 所有路径必须是 vault 相对路径，逃逸（../）一律拒绝。
• REST API 不可用时，所有读写自动走文件模式。
• Local REST API 默认 HTTPS + 自签名，插件已在请求层用 node:https（rejectUnauthorized: false）容忍，无需额外设置环境变量。
• 插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。

链接¶

GitHub：https://github.com/iamzcr/dsh-obsidian-assistant

插件目录线索：https://www.skillhub.cn/plugins/iamzcr/dsh-obsidian-assistant（该地址来自插件线索，未在本次抓取资料中核实）