Introduction

DSH agents often need to read files, modify files, look up links, and read attachments within a local knowledge base. For an Obsidian vault, allowing the agent to operate directly using generic file tools can easily lead to issues such as path traversal, accidental deletion, concurrent overwriting, and uncontrollable attachments.

dsh-obsidian consolidates these operations into a set of obsidian_* tools and injects them only when the agent message matches a configured trigger word. It is a host-only integration that does not export a browser client or install dependencies like React, REST API, or HTTP server.

What is it

dsh-obsidian is a DeepSeek Harness (DSH) plugin maintained by gxpppp, positioned as:

Host-only Obsidian integration for DeepSeek Harness (DSH).

It targets developers who need to operate on an Obsidian vault within a DSH agent, providing tools related to vault files, knowledge retrieval, attachments, links, editors, and commands.

Core Capabilities

Tool Injection Method

  • The plugin exposes 25 obsidian_* tools.
  • Tools and related guidance information are only injected into agents that match the configured trigger vocabulary.
  • Mismatched sessions will not receive these tool schemas.

Vault Tools

Vault tools can be used without Obsidian companion:

obsidian_status
obsidian_list
obsidian_stat
obsidian_read
obsidian_write
obsidian_edit
obsidian_append
obsidian_mkdir
obsidian_copy
obsidian_move
obsidian_delete

These tools target the vault files themselves, such as listing, reading, writing, editing, appending, creating directories, copying, moving, and deleting.

Knowledge and Obsidian Semantic Tools

obsidian_search
obsidian_metadata
obsidian_frontmatter_update
obsidian_link_resolve
obsidian_links
obsidian_link_insert

This set covers search, metadata, frontmatter updates, link resolution, link lists, and link insertion.

Attachment Tools

obsidian_attachment_add
obsidian_attachment_read

Attachments accept DSH durable image references or vault-relative source paths. Host absolute paths, URLs, dot directories, and unbounded binary payloads will be rejected.

Editor and Command Tools

Editor and command tools require Obsidian companion:

obsidian_active
obsidian_inline_edit
obsidian_open
obsidian_commands_list
obsidian_command
obsidian_notice

If you only need vault, knowledge, attachment, and link tools, you can skip enabling the companion; if you need to use editor or command tools, you must install the companion.

Vault Layer Constraints

Verified vault layer constraints include:

  • vault-relative paths
  • canonical realpath containment
  • protected dot directories
  • atomic writes
  • serialized appends
  • SHA-256 revisions
  • optimistic if_match conflicts
  • binary size limits
  • cancellation
  • internal trash by default

Companion IPC

Companion communicates via Windows named pipes or Unix sockets, uses versioned JSON-lines IPC, and performs vault identity verification simultaneously.

Installation and Enablement

1. Confirm DSH Version

First, install the DSH host package to the profile where the agent actually runs and explicitly use DSH 0.1.0-rc.8.

DSH 0.1.0-rc.8 is currently a prerelease, published on the npm dist-tag next, not latest; npm’s DSH latest dist-tag still points to rc.7.

2. Install Host Plugin Package

The following command installs the published tarball to the specified profile. Replace <profile> with the profile you actually start.

dsh plugin --profile <profile> add "https://github.com/gxpppp/dsh-obsidian/releases/download/dsh-obsidian-v0.3.1/deepseek-ai-dsh-client-ui-obsidian-0.3.1.tgz"

3. Verify Release Package Hash

Before installation, you should verify the release asset hashes, comparing them to SHA256SUMS.

4. Restart Profile

After adding or upgrading a plugin, restart the corresponding profile.

5. Install Companion as Needed

If you need to use editor or command tools, install the Obsidian companion to the vault:

node scripts/install-companion.mjs --vault <vault path>

Replace <vault path> with the actual vault path.

Configuration

Configure the obsidian namespace in DSH settings. Verified configuration fields include:

obsidian.vaultPath
obsidian.mode
obsidian.approvalMode
obsidian.commandPolicy
obsidian.commandAllowlist
obsidian.triggerKeywords
obsidian.enabled
obsidian.protectedPaths
obsidian.maxTextBytes
obsidian.maxAttachmentBytes

These fields correspond to vault path, running mode, approval mode, command policy, command allowlist, trigger keywords, enable switch, protected paths, text size limit, and attachment size limit.

Typical Usage

Using Only Vault Tools

  1. Install the host plugin package.
  2. Configure obsidian.vaultPath, obsidian.triggerKeywords, and obsidian.enabled.
  3. Call vault, knowledge, attachment, or link tools in an agent that matches the trigger words.

Using Editor and Command Tools

  1. First, complete the host plugin package installation.
  2. Install the companion to the vault.
  3. Configure obsidian.mode, obsidian.approvalMode, obsidian.commandPolicy, and obsidian.commandAllowlist.
  4. Restart the profile and use editor and command tools in an Obsidian environment where the companion is enabled.

Applicable Scenarios and Notes

Suitable for use:

  • Reading and writing to an Obsidian vault within a DSH agent.
  • Controlling the injection of 25 obsidian_* tools based on trigger words.
  • Using vault, knowledge, attachment, and link tools without introducing browser-side dependencies.
  • Utilizing editor and command capabilities via Obsidian companion when needed.

Notes before use:

  • DSH 0.1.0-rc.8 is a prerelease, not the version pointed to by npm latest.
  • Node.js requires >=22.19.0, npm requires >=11, and TypeScript requires 5.7.
  • Do not mix release lines of host and companion.
  • Editor and command tools depend on the companion.
  • Attachments do not accept host absolute paths, URLs, dot directories, or unbounded binary payloads.
  • The plugin joins your running DSH plugin environment and can access the vault path and companion configured in the settings; its actual file system and process permissions depend on the current dsh process. Check the source code, license, and changelog before installing.
  • Verified resources do not indicate the license and star count; please check the current license and changelog in the repository before use.

Conclusion

The value of dsh-obsidian lies in incorporating Obsidian vault operations into DSH’s tool surface: host-only, tool injection based on trigger words, clear boundaries at the vault layer, and extension of editor and command capabilities via companion.

Directory page:

https://www.skillhub.cn/plugins/gxpppp/dsh-obsidian

GitHub repository:

https://github.com/gxpppp/dsh-obsidian