gxpppp/dsh-obsidian
dsh-obsidian is a host-only Obsidian integration for DeepSeek Harness (DSH). The main branch targets DSH 0.1.0-rc.8 exactly. The rc.7 implementation is preserved on legacy/dsh-rc7 and tag dsh-obsidian-v0.2.0; the older rc.6 implementation remains on legacy/dsh-rc6 and tag v0.1.0.
catalog 简介 / catalog descriptioncatalog description：Obsidian bridge plugin for DSH
安装Install
dsh plugin --profile web add @deepseek-ai/dsh-client-ui-obsidian@0.3.1把 gxpppp/dsh-obsidian 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
dsh-obsidian
dsh-obsidian is a host-only Obsidian integration for DeepSeek Harness (DSH). The main branch targets DSH 0.1.0-rc.8 exactly. The rc.7 implementation is preserved on legacy/dsh-rc7 and tag dsh-obsidian-v0.2.0; the older rc.6 implementation remains on legacy/dsh-rc6 and tag v0.1.0.
The plugin exposes 25 obsidian_* tools. Tools and guidance are injected only into the agent whose message matches the configured trigger vocabulary; unrelated sessions do not receive the schemas.
Current release line: dsh-obsidian-v0.3.1, built for DSH dsh-v0.1.0-rc.8. DSH rc.8 is currently a prerelease published under npm dist-tag next, not latest.
Capabilities
Vault tools, available without Obsidian:
obsidian_status · obsidian_list · obsidian_stat · obsidian_read · obsidian_write · obsidian_edit · obsidian_append · obsidian_mkdir · obsidian_copy · obsidian_move · obsidian_delete
The filesystem layer uses vault-relative paths, canonical realpath containment, protected dot directories, atomic writes, serialized appends, SHA-256 revisions, optimistic if_match conflicts, binary size limits, cancellation, and an internal trash by default.
Knowledge and Obsidian semantic tools:
obsidian_search · obsidian_metadata · obsidian_frontmatter_update · obsidian_link_resolve · obsidian_links · obsidian_link_insert
Search is bounded and paginated. Metadata, frontmatter processing, backlinks, unresolved links, and Obsidian-generated links use the companion's native metadata cache and file manager when available.
Attachments:
obsidian_attachment_add · obsidian_attachment_read
Attachments accept a DSH durable image reference or a vault-relative source path. Host absolute paths, URLs, dot directories, and unbounded binary payloads are rejected.
Editor and command tools, requiring the companion:
obsidian_active · obsidian_inline_edit · obsidian_open · obsidian_commands_list · obsidian_command · obsidian_notice
Inline edits carry the active path, document revision, selection offsets, and expected text. A concurrent user edit or note switch returns a conflict instead of overwriting content.
Install
Install the DSH host package into the profile that actually runs your agent. Use DSH 0.1.0-rc.8 explicitly (@next or the exact version); npm's DSH latest dist-tag still points to rc.7. DSH supports npm, GitHub, and local link package specs:
# Preferred: prebuilt tarball attached to the GitHub Release
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"
# Exact GitHub tag; requires a build-capable npm environment because prepare builds from source
dsh plugin --profile <profile> add "github:gxpppp/dsh-obsidian#dsh-obsidian-v0.3.1"
# npm registry, when the package has been published by an account with @deepseek-ai scope access
dsh plugin --profile <profile> add @deepseek-ai/dsh-client-ui-obsidian@0.3.1
# Local development checkout
dsh plugin --profile <profile> add "link:E:\\path\\to\\dsh-obsidian"
Replace <profile> with the profile you actually boot, such as web or headless; the profile must use DSH 0.1.0-rc.8. After adding or upgrading, restart that profile. The exact release tag is dsh-obsidian-v0.3.1; rc.7 is archived at legacy/dsh-rc7 / dsh-obsidian-v0.2.0, and rc.6 at legacy/dsh-rc6 / v0.1.0. Do not mix host and companion release lines.
The host package and Obsidian companion are separate artifacts. The package remains host-only: it does not export a browser client and does not install React, REST API, or HTTP server dependencies.
The package is a DSH bundle because package.json declares dsh.bundle.patch and cordis.patch.yml inserts the ui-obsidian Cordis row. DSH discovers this metadata during dsh plugin ... add; no special Git tag is required for installation.
Install the Obsidian companion into the vault. From a checkout or unpacked host tarball:
node scripts/install-companion.mjs --vault "C:\\path\\to\\vault"
A standalone dsh-obsidian-bridge-0.3.1.zip is also attached to the GitHub Release; extract main.js and manifest.json into <vault>/.obsidian/plugins/dsh-obsidian-bridge/, then enable the plugin. Verify release asset hashes against SHA256SUMS before installation.
Reload Obsidian after installation. The companion stores its token in its own data.json; the host reads it automatically only when the configured vaultPath resolves to the same canonical vault.
Configuration
The obsidian namespace is rendered by DSH settings and applies live:
obsidian:
vaultPath: 'C:\\path\\to\\vault'
mode: auto # auto | fs | companion
companionEndpoint: '' # optional named-pipe/socket override
protectedPaths: [.obsidian, .trash, .git, .claudian]
maxTextBytes: 5242880
attachmentFolder: Attachments
maxAttachmentBytes: 26214400
approvalMode: dangerous # none | dangerous | writes | all
commandPolicy: approval # deny | allowlist | approval
commandAllowlist: []
announceToAgent: true
autoActivate: true
triggerKeywords: [obsidian, vault, 笔记, 日记, 知识库, 当前笔记, 选中文本]
enabled: true
The schema rejects relative/nonexistent vaults, invalid sizes, unsafe protected-path entries, invalid attachment folders, and an empty command allowlist when allowlist mode is selected.
Development
Requirements: Node.js >=22.19.0, npm >=11, TypeScript 5.7, DSH 0.1.0-rc.8, and an Obsidian desktop API-compatible development environment.
npm install --ignore-scripts
npm run typecheck
npm run check:companion
npm test
npm run build
npm run install:companion -- --vault "C:\\path\\to\\vault"
npm run smoke:companion -- --vault "C:\\path\\to\\vault" # requires Obsidian + companion
npm test compiles the host and tests with tsconfig.tests.json, then runs every compiled *.spec.js with Node's built-in test runner. The current suite covers 38 tests across activation, DSH IPC, editor context, vault security, revisions, binary limits, cancellation, and path normalization.
Architecture
src/index.ts: rc.8 settings, runtime lifecycle, skill facade, and per-agent activation.src/activation.ts: trigger matching, 25-tool scoped injection, approval policy, and reversible disposers.src/vault/: canonical path boundary and persistentVaultFs.src/bridge/: versioned JSON-lines IPC client and vault identity verification.companion/: desktop-only Obsidian plugin using a Windows named pipe or Unix socket.src/tools/: Vault, knowledge, attachment, link, editor, and command tool definitions.
See ARCHITECTURE.md, MIGRATION.md, SECURITY.md, and CHANGELOG.md for design, migration, security, and release history.
Publishing and DSH ecosystem
DeepSeek Harness does not require community plugins to use a special Git tag, npm dist-tag, or pull request to the official Harness repository. The official repository's guidance is to add the GitHub repository topic dsh-plugin for discoverability. This repository has that GitHub Topic and publishes its own plugin-scoped release tags such as dsh-obsidian-v0.3.1; the core Harness tag format dsh-v0.1.0-rc.8 belongs to the Harness repository, not this plugin.
For a release, keep these values synchronized:
package.json.versioncompanion/manifest.json.version- the companion runtime version and smoke-test expectation
- the plugin-scoped Git tag
dsh-obsidian-v<version> - the DSH compatibility version documented in this README and
MIGRATION.md
The package must retain the dsh.bundle.patch metadata and cordis.patch.yml entry so DSH can discover it as a bundle. Validate with npm run typecheck, npm run check:companion, npm test, npm run build, npm run verify:release, npm pack --dry-run, and an isolated DSH profile dump before pushing a release. Tag pushes build a verified host tarball, companion ZIP, and SHA256SUMS through the release workflow. Publishing the scoped npm package additionally requires an npm account authorized for the @deepseek-ai scope; GitHub Release assets do not depend on that permission.
Compatibility
| dsh-obsidian | DSH host | Companion | Obsidian | Status |
|---|---|---|---|---|
0.3.x / dsh-obsidian-v0.3.1 |
0.1.0-rc.8 |
0.3.1 |
Desktop >=1.4.0 |
Supported |
0.2.x / dsh-obsidian-v0.2.0 |
0.1.0-rc.7 |
0.2.0 |
Desktop >=1.4.0 |
Legacy branch legacy/dsh-rc7 |
0.1.x / v0.1.0 |
rc.6 line | 0.1.0 |
Desktop >=1.4.0 |
Legacy branch legacy/dsh-rc6 |
0.3.x |
rc.7 or another unsupported DSH version | any | any | Unsupported |
The host and companion major/minor versions must match. The companion also requires protocol version 1 and a canonical vault identity match. companionToken is normally read from the matching vault's plugin data.json; set it explicitly only when deployment-managed secret configuration is required.
Package identities
- DSH host package:
@deepseek-ai/dsh-client-ui-obsidian - DSH bundle row:
ui-obsidian - Obsidian companion plugin:
dsh-obsidian-bridge - GitHub discovery topic:
dsh-plugin
The official DeepSeek Harness repository does not require a special Git tag, npm dist-tag, or pull request for community plugins. Its explicit ecosystem guidance is the dsh-plugin GitHub topic. The core tag dsh-v0.1.0-rc.8 belongs to the Harness repository; this plugin uses dsh-obsidian-v0.3.1.
DSH rc.8 upgrade warning
DSH rc.8 is a prerelease and its release notes explicitly state that the optional SQLite session-persistence storage format is incompatible with the previous build and has no in-place migration. Back up the DSH home/session data before upgrading a real profile, and validate this plugin first with an isolated DSH_HOME. This warning does not concern Obsidian vault files or the companion IPC data. The rc.8 API Proxy-to-Remote migration note is marked proposed; this plugin uses neither API Proxy nor ctx.remote, so no Remote migration is applied here.
Security
The companion never requests a URL. It listens only on an OS-local IPC endpoint, requires a random 32-byte token, uses constant-time token comparison, caps messages at 1 MiB, and verifies the canonical vault identity on every session. Server-side request URLs elsewhere in the project are not used by the current main branch.
Vault tools fail closed on traversal, absolute paths, control characters, protected dot directories, symlink/junction escapes, stale revisions, oversized payloads, unauthorized commands, and cancellation.
License
相关推荐Related
- deepseek-ai/deepseek-harness DeepSeek Harness: Everything is a Plugin.
- deepseek-ai/deepseek-harness DeepSeek Harness (dsh) — 由 DeepSeek AI 开发的开源 agent harness（智能体框架）。一切皆插件：核心 + 插件 + 技能 = 可热插拔的 AI 编程工作台。DeepSeek Harness: …
-
ruvnet/ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build c…
-
amruthpillai/reactive-resume
A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source a…
-
volcengine/OpenViking
Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
-
Molunerfinn/PicGo
:rocket: The Ultimate Image Uploader for Efficient Creators. Supports Obsidian, Typora, VS Code etc. and 60+ image hosti…
-
titanwings/colleague-skill
将冰冷的离别化为温暖的 Skill，欢迎加入数字生命1.0！Transforming cold farewells into warm skills? It's giving rebirth era. Welcome to Digital …
-
nocobase/nocobase
NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything fr…