Introduction

When developing DSH plugins, the local Obsidian vault often serves as a long-term knowledge base: notes, reference materials, and creative resources may all be stored within it. Directly accessing the file system is simple but lacks the indexing and command capabilities of the running Obsidian instance. Conversely, relying solely on the Local REST API requires Obsidian to be online.

Here, we introduce dsh-obsidian-assistant. It is a DeepSeek Harness plugin (Cordis toolset) that unifies operations on the same vault: the file channel operates independently of Obsidian’s runtime, while the REST channel automatically enhances functionality when Obsidian is online.

What Is This

dsh-obsidian-assistant is maintained by iamzcr and licensed under MIT.

It provides search, read/write notes, bidirectional linking / relationship graphs, batch organization; and leverages Obsidian’s “Local REST API” community plugin to access advanced capabilities (high-speed full-text search, triggering commands / templates).

Core Features

File Channel

These capabilities do not depend on Obsidian running.

  • obsidian_search: Full-text / title search, supports filtering by tag, returns path + snippet + tags.
  • obsidian_read_note: Reads a single note, including frontmatter + content, can be called with or without the .md extension.
  • obsidian_create_note: Creates a new note, can include YAML frontmatter, refuses to overwrite existing notes.
  • obsidian_update_note: Literal replacement / append editing, idempotent and safe.
  • obsidian_list_structure: Folder tree + tag statistics + orphan notes.
  • obsidian_backlinks: Backlinks + outgoing links + tag affiliation graph.
  • obsidian_batch: Batch move / rename, automatically rewrites [[wikilink]] across the entire vault.
  • obsidian_export_novel: Cleans chapter notes named in the format ChapterX-Title from the vault into TXT / Markdown drafts suitable for pasting into novel platforms.

REST Channel

Requires Obsidian to be running and the Local REST API community plugin installed.

  • obsidian_rest_search: Obsidian’s internal indexing for high-speed full-text search, ideal for large vaults.
  • obsidian_list_commands: Lists Obsidian commands (id + name).
  • obsidian_run_command: Triggers commands (Templater / Dataview re-rendering, etc.).
  • obsidian_rest_query: Passes through arbitrary REST endpoints, useful for fallback / advanced usage.

When the REST API is unavailable, all read/write operations automatically fall back to file mode with seamless degradation.

Installation and Enabling

The original installation instructions are not provided in the official documentation. Below is the method based on the verified profile bundle configuration. Add it to the profile’s bundles list, then configure vaultPath for it.

  1. Add dsh-obsidian-assistant to the dsh.profile.bundles in $DSH_HOME/profiles/<name>/package.json.

  2. Append the plugin entry to the top-level array in $DSH_HOME/profiles/<name>/cordis.patch.yml, and include the required vaultPath in the config:

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

vaultPath is the absolute path to the vault root directory and is required. Optional configurations include: apiUrl, apiToken, enableRestApi, excludePatterns, maxResults; documentation states they have default values.

excludePatterns supports directory name prefix matching and * wildcards.

Typical Usage

Search and Read

Search first, then read. obsidian_search performs full-text / title search, can filter by tag, and returns paths, snippets, and tags. obsidian_read_note reads a single note, with or without the .md extension, and the result includes frontmatter and content.

Create and Edit

Use obsidian_create_note to create new notes, which can include YAML frontmatter and refuses to overwrite existing notes.

Use obsidian_update_note to edit existing notes, supporting literal replacement and append editing, suitable for tasks requiring idempotency and repeatability.

obsidian_list_structure provides folder trees, tag statistics, and orphan notes.

obsidian_backlinks provides backlinks, outgoing links, and tag affiliation graphs, useful for reviewing reference relationships before organizing.

Batch Move / Rename

obsidian_batch supports batch move / rename and automatically rewrites [[wikilink]] across the entire vault, also returning the number of updated links.

Known limitation: The harness FileSystem service lacks delete / rename APIs. Under the harness ctx.fs backend, move is implemented as “copy + source file clearing” (sourceRemoved: false); only under pure Node fallback does it perform a true rename (sourceRemoved: true). Data will not be lost, but empty files may remain at the source location.

Novel Export

If the vault contains chapter notes named in the format ChapterX-Title, you can use obsidian_export_novel to clean them into TXT / Markdown drafts for easy pasting into novel platforms.

For example, ask the model to execute:

Export the chapters from the Novel/ directory to txt for publishing on Qidian

This is equivalent to:

obsidian_export_novel({ folder: 'Novel', format: 'txt' })

If there are drafts or duplicate chapters in the vault, they can be excluded. For example:

Export Novel, but exclude Chapter 3 and drafts with "Romantic Code" in the title

This is equivalent to:

obsidian_export_novel({
  folder: 'Novel',
  format: 'txt',
  exclude: ['3', 'Romantic Code']
})

Commands and Dataview

The Local REST API does not have a native Dataview endpoint. To perform Dataview queries, first find the Dataview command id via obsidian_list_commands, then trigger it with obsidian_run_command.

Commands like Templater re-rendering can also be triggered via obsidian_run_command.

REST Channel Smoke Test

If Local REST API is configured, you can run a live smoke test:

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

This command verifies that Channel B is operational.

Notes

  • vaultPath is required; apiUrl, apiToken, enableRestApi, excludePatterns, maxResults have default values.
  • All paths must be relative to the vault; escape sequences (../) are always rejected.
  • When the REST API is unavailable, all read/write operations automatically use file mode.
  • The Local REST API defaults to HTTPS + self-signed certificates; the plugin tolerates this at the request layer using node:https (rejectUnauthorized: false), so no additional environment variable setup is needed.
  • The plugin runs with the current DSH process permissions; review the source code and license before installation.

Links

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

Plugin directory hint: https://www.skillhub.cn/plugins/iamzcr/dsh-obsidian-assistant (This address comes from plugin hints and has not been verified in the fetched documentation).