Obsidian 笔记读写therain2020/dsh-obsidian-sync

dsh-plugin-obsidian-sync

一个 DeepSeek Harness 插件，为 dsh agent 提供对本地 Obsidian 仓库的读写访问能力。

包含两个包：

| 包 | 作用 |
|---|---|
| packages/plugin/obsidian-sync | 插件本体——注册 obsidian_write_note 和 obsidian_read_note 工具，并添加一段系统提示词 |
| packages/bundle/obsidian-sync-bundle | profile 包——一个补丁层，将插件挂载到 dsh 组合中 |

功能说明

- obsidian_write_note —— 将 markdown 笔记写入配置的仓库。标题会成为文件名（经过清理）；可选的 directory 会将其放到仓库相对路径的子文件夹下；除非 overwrite: true，否则拒绝替换已存在的笔记。
- obsidian_read_note —— 通过仓库相对路径读回笔记。

安全特性（全部强制执行，全部经过测试）：

- 路径限制 —— 绝对路径和 .. 片段会被拒绝，且每个解析后的路径都会再次对照仓库根目录进行检查。即使 agent 尝试，也无法写入仓库之外。
- 大小上限 —— 可配置的 maxNoteBytes（默认 1 MiB）同时适用于读取和写入，因此杂散的二进制文件不会淹没上下文窗口。
- 无静默覆盖 —— 除非 overwrite: true，否则已存在的笔记会报错，这样模型会明白该参数很重要，而不会覆盖你的笔记。

使用场景：agent 将会话摘要、研究发现和持久决策直接写入你的知识库——无需复制粘贴。

环境要求

- Node ^22.19.0 || >=24.0.0
- pnpm（仅用于 dsh plugin 安装）
- dsh 0.1.1-rc.2（@deepseek-ai/dsh- 包作为一套一起发布；本插件固定使用该版本）

快速开始

pnpm install
pnpm run check        # typecheck + lint + test + build

pnpm run check 通过意味着：插件能在 dsh 自身的编译器设置下编译，其工具 schema 有效，能在真实的 dsh 工具注册表上挂载，并在销毁时干净地撤销。

安装到 dsh

从 npm 安装：

dsh plugin --profile web add dsh-bundle-obsidian-sync

从本地检出安装：

pnpm run pack:bundle
dsh plugin --profile web add ./dsh-bundle-obsidian-sync-0.1.0.tgz

配置 —— 插件在没有 vaultPath 时拒绝挂载，因此请在补丁层中设置它：

$DSH_HOME/cordis.patch.yml  (defaults to ~/.dsh/cordis.patch.yml; hot-reloaded)
- insert:
- id: plugin-obsidian-sync
name: 'dsh-plugin-obsidian-sync'
config:
vaultPath: 'D:/GitHub/MyVault'   # absolute path to your vault — required
notesDir: agent                  # default directory when a call omits one
maxNoteBytes: 1048576            # read/write size cap

然后验证该行已出现在组合后的树中，并开始使用：

dsh --profile web --dump-config   # the row should appear with your config
dsh web
让 agent 保存一些东西——例如“把这次会话的结论存成笔记”——它就会调用 obsidian_write_note。

层级顺序、不使用 pnpm 的路径以及热重载行为记录在 docs/loading-into-dsh.md 中。

布局

packages/plugin/obsidian-sync/src/index.ts 是接线部分；文件系统逻辑就在它旁边的 notes.ts 中（纯函数，不依赖 Cordis），因此无需启动 Context 也能保持可单元测试。测试在真实的 dsh 工具注册表上挂载插件，并断言模型实际看到的内容，以及卸载时的释放。

dsh 版本

本项目针对一个 dsh 发行版，并在每个 @deepseek-ai/dsh- 依赖中固定该版本。它们作为一组一起发布，彼此并不独立兼容，因此请一起升级。pnpm run trace @deepseek-ai/dsh-tools 会打印已安装的版本以及在哪里阅读其契约。

许可证

MIT