前言¶
在 DeepSeek Harness（DSH）里跑 Agent 时，个人知识库往往落在 Obsidian：一堆 Markdown、YAML frontmatter 和 [[wikilink]]。若只能靠「把全文塞进上下文」或手写脚本读写目录，检索、按行编辑、改 frontmatter、重命名还要自己维护双链，既慢也易出错。
dsh-obsidian-vault 把上述能力做成一组注册到 Harness 的工具：针对 vault 文件夹列出、读取、搜索、新建与编辑笔记，管理 frontmatter，按标签查询，并在移动或重命名时默认修复指向该笔记的 wikilink。不需要启动 Obsidian，也不依赖 Obsidian 插件。
这是什么¶
维护者 jinferth 在 GitHub 开源的 DSH 插件，npm 包名为 @jinferth/dsh-obsidian-vault（版本 1.0.0，MIT），社区目录分类为「记忆」。定位一句话：Obsidian vault tools for DeepSeek Harness——在纯 Markdown 层面操作笔记库。
核心功能¶
插件向 Agent 暴露多类工具，README 中的能力如下。
库信息与列举¶
obsidian_info：返回 vault 绝对路径、是否存在、笔记数量；不确定当前连的是哪个库时，应先调用。obsidian_list：列出笔记，可按文件夹或 glob（如Projects/**、*.md）过滤；结果数量受maxResults限制（默认 200）。
读与搜¶
obsidian_read：按 vault 相对路径读单篇；.md可省略；行号与obsidian_edit对齐。obsidian_search：在标题与正文中搜索，支持字面量或regex。
写与改¶
obsidian_new：新建笔记，可带 frontmatter；已有文件则拒绝覆盖。obsidian_append：在文末追加 Markdown；文件不存在则创建。obsidian_edit：四种模式——replace（字面替换，须唯一除非replaceAll）、replaceLines、insertLines、deleteLines。obsidian_frontmatter：对单个 frontmatter 键执行get/set/delete，不改动正文。
查询、移动与删除¶
obsidian_query：按 frontmatter 属性、标签和路径查找；多个标签为 AND。obsidian_move：移动或重命名笔记，默认重写全库中指向它的 wikilink。obsidian_delete：将笔记移入 vault 内.trash，而非直接删除文件。obsidian_insert_image：把图片复制进 vault 并在笔记中引用。obsidian_batch：将上述多个操作作为同一事务执行；任一步失败则回滚先前步骤。
安全与编码¶
路径必须留在 vault 内，绝对路径与 .. 穿越会触发 VaultPathError。.obsidian/、.trash/、.git/ 不参与列举、搜索或写入。写入先写临时文件再 rename，避免中断导致截断。保留 CRLF 与 BOM。删除进 .trash 便于恢复。
安装与启用¶
包未发布到 npm，且 npm 上裸名 dsh-obsidian-vault 属于另一位作者；须用 GitHub 路径安装。
dsh plugin --profile web add github:jinferth/dsh-obsidian-vault
重启 profile 后确认工具已加载：
dsh --profile web --dump-config
运行环境要求 Node.js >= 20（见 package.json 的 engines）。
配置 vault 路径¶
插件按以下顺序解析 vault：
cordis.patch.yml中的config.vaultPath- 环境变量
OBSIDIAN_VAULT - Obsidian 上次打开的库（Windows：
%APPDATA%\obsidian\obsidian.json；macOS：~/Library/Application Support/obsidian/obsidian.json；Linux：$XDG_CONFIG_HOME/obsidian/obsidian.json）
若要固定某一库，可在 patch 中插入如下块：
- insert:
- id: obsidian-vault
name: '@jinferth/dsh-obsidian-vault'
config:
vaultPath: '/home/me/Obsidian'
maxResults: 200
maxResults 限制 obsidian_list 与 obsidian_search 单次返回条数。装好后若提示未配置库，可在 Obsidian 中打开一次目标库、设置 OBSIDIAN_VAULT，或在 patch 中写明 vaultPath。
典型用法思路¶
下面是一套可与 README 对照的协作顺序，而非虚构对话案例。
- 调用
obsidian_info确认当前 vault 路径与笔记数。 - 用
obsidian_search或obsidian_query定位目标笔记。 - 用
obsidian_read加载内容；小改动可用obsidian_edit的replaceLines/insertLines；元数据用obsidian_frontmatter。 - 整理结构时用
obsidian_move，依赖默认 wikilink 修复，避免全库断链。 - 多篇联动变更可打包进
obsidian_batch，降低半途而废留下脏状态的风险。
Harness 处于开发者预览，插件为兼容宿主动态：不导入 @deepseek-ai/*，仅通过 ctx.tools.register 注册工具；注册失败时写日志而不拖垮 profile 启动。上游仓库说明可用 npm test 对临时 vault 跑 25 项检查（无网络、无真实 Obsidian）。
适用场景与注意¶
适合已在 Obsidian 沉淀 Markdown、又希望在 DSH Agent 中做检索、增量编辑、frontmatter 与双链维护的开发者。vault 即普通文件夹，与 Obsidian 桌面端可并行使用，但 Agent 写入会直接改磁盘上的文件，操作前宜有版本管理或备份习惯。
插件在 当前 dsh 进程的用户权限 下读写 vault；安装与启用前应自行查看 GitHub 仓库 源码与 MIT 许可证。社区插件目录由 SkillHub 等站点维护，与 DeepSeek / 幻方无官方从属关系，安装来源以 README 与目录页为准。
结尾¶
dsh-obsidian-vault 把 Obsidian 笔记库变成 Harness 可调用的工具面：列举、搜索、编辑、frontmatter、标签查询与带 wikilink 修复的移动，并在路径、原子写入与软删除上做了约束。需要了解分类与简介时，可打开 SkillHub 目录页；安装命令与工具说明以 GitHub README 为准。
