Preface¶

In the DeepSeek Harness (dsh) plugin ecosystem, a common requirement is to enable agents to directly manipulate local tools and local data. For example, if you use Obsidian for daily note management and want the dsh agent to search, read, modify, and move these notes. If you go through additional services, it often introduces components like MCP server, OAuth, or Local REST API community plugins; the approach of dsh-obsidian is more straightforward: treat the local Obsidian vault as a Markdown file system.

dsh-obsidian is a DSH plugin maintained by mingzeng21, licensed under MIT. It connects the dsh agent to the local Obsidian vault, supporting search, read, write, move, and delete (move to trash) operations on notes.

What is this¶

One-line positioning: dsh-obsidian is an Obsidian vault plugin for DeepSeek Harness (dsh), mounting a set of obsidian_* tools to allow the dsh agent to directly manipulate local Markdown notes.

The core problem it solves is: enabling dsh to complete common note operations within the local vault without relying on additional servers or browser plugins. After installation, the plugin parses the vault root directory and mounts 12 obsidian_* tools to the agent, covering search, read, write, append, move, delete, backlink queries, tag statistics, and frontmatter property setting and deletion.

Core Features¶

Direct Read/Write of Vault File System¶

dsh-obsidian directly reads and writes the vault file system without needing an MCP server, OAuth, or Local REST API community plugin.

The default path is FsAccess, based on node:fs with frontmatter and wikilink parsing. Upon startup, it parses the vault according to the following rules:

1. If an explicit vaultPath is configured, it is used first.
2. Otherwise, it automatically detects the currently opened vault from obsidian.json.

Mounts 12 obsidian_* Tools¶

All tools accept path parameters relative to the vault root directory, for example:

Folder/Note.md

Optional Delegation to obsidian CLI¶

useCli is disabled by default. When enabled and the obsidian CLI is detected, property:set and property:remove can be delegated to the CLI for execution; all other operations always go through FsAccess. If the CLI execution fails, it silently falls back to FsAccess.

Installation and Enablement¶

Environment Requirements¶

• DeepSeek Harness (dsh)
• Node.js ≥ 22.12.0
• package.json version 0.2.2
• Depends on yaml ^2.7.0
• peerDependencies includes:
• @deepseek-ai/cordis
• @deepseek-ai/dsh-tools
• @deepseek-ai/schemastery

Compatibility verified up to dsh v0.1.1-rc.2 (including v0.1.0-rc.8).

Installation¶

Run the following command to install to the current profile:

dsh plugin --profile web add dsh-obsidian

web is just a profile name; you can replace it with the profile you actually use to run the agent, such as headless, tui, etc.

Version Locking¶

To lock to version 0.2.2:

dsh plugin --profile web add dsh-obsidian@0.2.2

Updating¶

Re-running add will fetch the latest version:

dsh plugin --profile web add dsh-obsidian

After updating, restart the harness or refresh the Web UI:

dsh web

Then confirm the version with the following command:

dsh plugin --profile web list

Uninstallation¶

dsh plugin --profile web remove dsh-obsidian

Configuration¶

If you know the vault location explicitly, you can configure vaultPath; otherwise, the plugin automatically detects it from obsidian.json.

Typical Usage¶

Below are the daily operation paths covered by the plugin. The specific calls to tools are made by the dsh agent based on the task.

1. Search notes: obsidian_search performs full-text search, returning matching lines and context.
2. Read notes: obsidian_read reads the body and frontmatter; if only properties are needed, use obsidian_frontmatter.
3. Create or modify notes: obsidian_write can create new or overwrite; use obsidian_append for appending content only.
4. Move or rename: obsidian_move moves the file and synchronously updates related [[links]].
5. Delete notes: obsidian_delete moves notes to the vault’s .trash/, not permanently deleted.
6. Handle frontmatter: obsidian_set_property sets or updates a single YAML property; obsidian_delete_property deletes a specific property.
7. Query link relationships: obsidian_backlinks finds notes that link to a specific note.
8. Tag statistics: obsidian_tags lists all tags in the vault along with usage counts.

Path parameters are relative to the vault root directory. For example, to handle notes in a subdirectory:

Projects/DSH/dsh-obsidian.md

Applicable Scenarios and Notes¶

Suitable for daily management of local Obsidian vaults: search, read, write, append, move, delete, backlink queries, tag statistics, and frontmatter property maintenance.

A few points to note before use:

• The plugin runs with the permissions of the current dsh process. Check the source code, dependencies, and license before installation.
• Path boundary protection: All path parameters are parsed and validated; they must fall within the vault root directory; attempts to escape via ../ or absolute paths are rejected.
• Reversible deletion: obsidian_delete only moves notes to the vault’s .trash/, not permanently deleted.
• Default avoidance of .obsidian/: Search and listing exclude .obsidian/, .git/, and .trash/ by default.
• Frontmatter and wikilink protection: Reading and writing should not damage YAML properties and [[links]], unless the task explicitly requires modification.
• If you rely on the obsidian CLI to manage frontmatter, you can enable useCli; otherwise, the default file system path is used.

Links¶

• GitHub: https://github.com/mingzeng21/dsh-obsidian
• Plugin Directory Page: https://www.skillhub.cn/plugins/mingzeng21/dsh-obsidian