DeepSeek Harness for Obsidian

Status: released · Desktop only（Windows / macOS）· English · 中文

Embed the native DSH Web UI into your vault — one-click setup, silent operation, a two-way bridge between your notes and DSH, and it keeps working as DSH evolves.

**把 DSH 原生 Web UI 无痕嵌入 Obsidian：一键配置、静默运行、笔记与 DSH 双向桥接，随 DSH 版本演进持续可用。

Note:

Compatible with DSH version 0.1.5-rc.1. Incompatible with DSH 0.1.2-0.1.3.

DSH is under active development and ships new versions frequently. Each release can change the internal seams this plugin connects to, so plugin support is adapted and verified version by version — a newly released DSH version may need a little time before the plugin catches up. If something stops working right after a DSH update, check for a plugin update first.

---

English

An Obsidian desktop plugin that embeds the native DeepSeek Harness (DSH) Web UI directly into your vault — a seamless graft of two open-source tools: no DSH source is touched (connected through DSH's official extension seam), so it keeps working as DSH evolves. The plugin talks to DSH only over localhost; DSH itself makes outbound requests (e.g. AI model APIs) when you use it.

Features & Usage

• One-click setup — installs or detects DSH, auto-installs missing tools (git / Node.js / pnpm) with a live progress bar; no command line needed.
• Silent operation — the DSH service starts quietly in the background: no console windows, no terminal to keep open; crashes are detected and reconnected in one click.
• Native Web UI — the real DSH interface (iframe embed) with adjustable zoom (0.5×–2.0×) and theme-following styling.
• BRIDGES is delivering packages for you…… — select text in a note and it auto-injects an implicit info line (exact line:col + word count, no original text) into the DSH chat, so DSH can read the file itself and edit even partial-line selections; conversely, DSH artifacts/paths inside your vault open in Obsidian with one click.
• Shortcut passthrough — Obsidian global shortcuts (e.g. Ctrl+; for properties) still work while focus is inside the DSH panel; it auto-reads your hotkey settings.
• Self-healing bridge — the bridge is rewritten automatically after DSH or plugin updates, so it stays compatible.
• Bottom padding — add 0–30px space under the panel (default 20) when the Obsidian status bar covers the panel bottom.
• Bilingual UI — Chinese / English, follows your system language.
• Self-maintaining — auto-checks GitHub for DSH updates (with a read-only mirror fallback), applies on confirmation; restart the service anytime from settings.
• Version-aware updates — installs DSH's official latest release: the 0.1.5 line is verified compatible, only 0.1.2–0.1.4 are flagged as incompatible (the 0.1.1 line also works), and an installed CLI in the bad range is upgraded automatically.
• Safe upgrades — before updating DSH every DSH process is stopped first (this avoids the Windows file locks that can leave an in-place upgrade half-broken), your session history is backed up, and readability is re-checked afterwards.
• Session format repair — if a DSH upgrade leaves older sessions unreadable (format drift between DSH versions), a built-in checker scans them with DSH's own migration chain: one click backs up and repairs (nothing is rewritten without that click).
• Credential self-heal — after an upgrade or service restart the panel reloads with the new launch credential automatically, so you never hit a stale-auth 401.
• Error, explained — failures show plain-language reasons plus one-click reconnect / "Ask AI how to fix".
• AED rescue — when DSH won't start, one click downloads and runs dsh-fix to enter safe mode and recover, with a mirror fallback for downloads.
• Privacy, your call — data flows where you configure them (see Privacy & Data Use).

Performance

• Capability probing results (e.g. --no-open support) are cached and reused, so repeated starts skip the slow probe and the panel opens faster.
• A startup timing log (plugin load → service probe → service start → panel ready) is shown in Settings → Diagnostics, so slow or failed starts can be located quickly.
• These optimizations apply to the plugin layer only; DSH itself starts at its own pace.

Requirements

• Obsidian desktop v1.7.2+ (Windows / macOS)
• DSH itself: the plugin can install it for you (git / Node.js / pnpm are auto-installed if missing; mirror fallback when the official source is blocked). Supported DSH lines: 0.1.1 series or 0.1.5+ — 0.1.2–0.1.4 are known incompatible and the update dialog warns before installing them.
• A model API key for DSH (default: DeepSeek API; any OpenAI/Anthropic-compatible endpoint — including a local model — can be configured)

Install: Obsidian → Settings → Community plugins → Browse → search "DeepSeek Harness" → Install. Build from source is also supported.

Credits: Thanks to the DeepSeek and Obsidian open-source teams — the open, shared spirit of the internet is what makes tools like this possible. And thank you to Claudian (an AI coding-agent plugin for Obsidian), whose design inspired this plugin's select-and-send interaction.

---

中文

这是什么

一个把 DeepSeek Harness（DSH）原生 Web UI 无痕嫁接到 Obsidian 的桌面插件。不改 DSH 一行源码（走官方扩展机制），DSH 升级即可用。插件与 DSH 之间仅走本机回环；DSH 使用时会自行发起外网请求（如调用 AI 模型 API）。

功能与用法

省心接入

• 一键配置：自动安装或识别 DSH，缺失的 git / Node.js / pnpm 自动装好，进度条实时可见；小白零命令行上手
• 静默运行：DSH 服务后台静默启动——无控制台窗口、不用挂终端；服务崩溃自动检测，一键重连/重启
• 自动维护：自动检查 GitHub 上的 DSH 更新，确认后一键更新（官方源被墙时自动走只读镜像，可在设置中自定义镜像地址）

原生体验

• 原生 DSH Web UI：iframe 直接嵌入，与浏览器访问完全一致；页面可缩放（0.5×–2.0×），外观跟随 Obsidian 主题
• BRIDGES is delivering packages for you……：①笔记里框选文字 → 自动以隐式信息行注入 DSH 聊天框（含精确行:列位置与字数，不含原文；DSH 按「路径 + 行:列」读取文件定位处理，可改任意非整行选区；隐式行生成在你已输入的文字之上、不覆盖你的输入；取消框选仅清除隐式行、保留你的输入），也可切换为仅右键发送或关闭；②DSH 产物/路径若在 Vault 内 → 点击即在 Obsidian 打开，无缝回跳笔记
• 快捷键透传：光标聚焦在 DSH 面板内时，Obsidian 全局快捷键（如 Ctrl+; 打开属性）仍可响应，自动读取你的快捷键设置
• 桥接自动维护：DSH 或插件更新后自动重写桥接，保持兼容
• 底部垫高：Obsidian 状态栏遮挡面板底部时，可调 0–30px 留白（默认 20）
• 中英双语界面：跟随系统语言，非中文系统自动英文
• AED 抢救：DSH 无法启动时，一键下载并运行 dsh-fix 进入安全模式抢救，下载走镜像兜底

兼容与修复

• 版本感知更新：一键安装/更新取 DSH 官方最新版——0.1.5 系已实测适配，仅 0.1.2–0.1.4 会红字劝退（0.1.1 系同样可用）；检测到已装 CLI 落在不兼容区间时自动升级
• 升级更稳：更新 DSH 前先结束所有 DSH 进程（避免 Windows 文件锁导致就地升级半途损坏），自动备份会话目录（失败即中止升级），升级后复检历史可读性
• 会话格式修复：DSH 版本漂移导致旧会话打不开时，内置检查器用 DSH 自带迁移链逐会话体检，一键「备份并修复」；检查为只读，不点击不改写任何会话文件
• 认证自愈：升级/重启服务后自动按新的启动凭证重载面板，不再出现 dsh web authentication required

隐私可控

• 数据流向由你掌控：默认 DeepSeek 官方 API；可配置任意 OpenAI/Anthropic 兼容端点（含本地模型）；Vault 索引、会话记录与 API key 凭证均存于本机

平台支持：Windows / macOS（仅桌面端）

环境要求

• Obsidian 桌面版 v1.7.2+（Windows / macOS）
• DSH 本体：插件可一键安装（git / Node.js / pnpm 缺失自动补齐，官方源被墙时走镜像）。支持的 DSH 版本线：0.1.1 系或 0.1.5 及以上——0.1.2–0.1.4 已知不兼容，更新弹窗会在安装前红字提醒
• DSH 模型 API key：默认 DeepSeek 官方 API；可配置任意 OpenAI/Anthropic 兼容端点（含本地模型）

性能

• 启动更省时：DSH 能力探测结果（如 --no-open 支持）缓存复用，避免每次启动重复耗时探测，面板打开更快
• 启动耗时可观测：设置 →「诊断」区显示各阶段耗时（插件加载 → 服务探测 → 服务启动 → 面板就绪），启动慢/失败时可快速定位
• 以上优化仅作用于插件层；DSH 本体按自身节奏启动

致谢

感谢 DeepSeek 与 Obsidian 开源团队——开放、共享的互联网精神，让这样的工具得以诞生。向所有开源贡献者致敬；感谢 Claudian（Obsidian 内的 AI 编码 agent 插件）——本插件的「框选发送」交互正源自其设计灵感。

---

Key settings

Setting	Default	Description
Interface language	Follow Obsidian	Chinese / English; any other system language falls back to English
Service port	3080	Port the DSH Web GUI listens on
Startup command / working directory	empty	Customize how dsh web starts (supports the {port} placeholder)
Auto-start when offline	on	Start the service if the port has none when the panel opens
Detached persistent process	on	Keep DSH running after Obsidian exits
One-click install DSH	button	Auto-install dependencies → clone (live percentage) → install dependencies (progress bar) → auto-configure
Auto-check updates	on	Auto-detect new DSH versions when opening the panel / starting the service (prompts only when an update is found; view GitHub changes or update now)
Check for updates	button	Manual check; falls back to a read-only mirror if the official source fails
Session format repair	button	Scan old sessions with DSH's own migration chain; back up and repair the unreadable ones (read-only scan; rewriting requires an explicit click)
Plugin info	row	Shows the installed plugin version; in-app changelog modal + "check plugin updates" (opens the official Obsidian store page) + GitHub repo URL (feedback & issues welcome)
Bottom padding	20px	Empty space below the panel (0–30px) when the Obsidian status bar covers the panel bottom
Shortcut passthrough	on	Obsidian global shortcuts still work while focus is inside the DSH panel (auto-reads your hotkey settings)
Bridge Obsidian → DSH chat	on	Select text in a note and right-click to send it to the DSH chat; the DSH panel opens automatically after sending
Bridge DSH chat → Obsidian	on	Readable files generated by DSH inside your vault open in Obsidian with one click
Changelog	link	Open the DSH GitHub Releases page (for DSH itself) to read per-version changes; the plugin's own changelog opens in an in-app modal
AED for DSH	button	Download and run dsh-fix and start DSH in safe mode; then instruct DSH to self-repair
Start in safe mode	button	Start DSH in safe mode only (disables all user plugins); a second button exits safe mode and restores them
Update mirror URL	empty	Custom update mirror; empty auto-falls back to gh-proxy
Install URL	official repo	Clone URL; switch to a proxy mirror on restricted networks
Diagnostics	log	Startup timing log (last 5 runs): plugin load → service probe → service start → panel ready

Privacy & Data Use

• Plugin layer: the plugin contains no DSH implementation; it talks to DSH only over localhost (127.0.0.1). The only outbound requests the plugin itself makes are the ones you trigger (cloning DSH, checking updates). No telemetry.
• DSH layer: DSH is an AI agent framework — when you run a task it makes outbound requests as needed (e.g. AI model APIs, tool/web access); what is sent depends on the task you run.
• Data flow is yours to configure: DSH sends model requests to the provider you configure (default: DeepSeek API; baseURL supports OpenAI-completions/Responses, Anthropic-messages and other protocols — including a local model such as Ollama/vLLM, in which case data never leaves your machine). Vault index, session history and API keys stay on your machine (local credentials store).
• No telemetry, no third-party relay: the plugin runs no telemetry beacons; there is no cloud relay between Obsidian, the plugin and DSH.

Troubleshooting

Symptom / error	Cause	Fix
Panel won't open	Wrong working directory, pnpm not on PATH, port taken	The error view shows the reason + a copy-paste manual startup command
spawn dsh ENOENT / "dsh not found"	Windows .cmd shim not resolvable by Node	Plugin already wraps npm-style commands via cmd.exe; reload the plugin (fully restart Obsidian)
EADDRINUSE / port 3080 taken	A stale DSH process holds the port	Settings → Quick actions → Restart service
"Bridge not ready, sent directly instead"	Bridge script not yet injected into the panel	Settings → Quick actions → Restart service (after updating the plugin, fully restart Obsidian before restarting the DSH service)
koffi.node EBUSY during CLI update	The running DSH locks its native module	The plugin stops the service before updating the CLI; otherwise stop DSH manually and retry
Chat history missing or a session won't open after a DSH upgrade	Session format drift between DSH versions (the format version number does not change between releases)	Settings → Quick actions → Session format repair → "Back up and repair" (also offered automatically when the post-upgrade check finds unreadable sessions)
DeepSeek request extension preparation failed (only the DeepSeek provider fails; other providers work)	An older bridge installed as a loose module in the profile directory, whose owning manifest has no version	Update the plugin (2.4.0+ installs the bridge as its own package); if it persists, run the repair checker
dsh web authentication required after upgrading or restarting DSH	The launch token is generated per process; the plugin cached the previous one	2.4.0+ reloads the panel with the new credential automatically; otherwise Settings → Quick actions → Restart service
Could not resolve host / update fails	github.com blocked or flaky	Use the update mirror URL, or check the network
npm global install hangs at the end	Known npm behavior on this package	Verify by reading the installed package's package.json version, not the console

Architecture

src/
├── main.ts                  # Plugin entry: commands, menus, bridge wiring, profiler
├── service-manager.ts       # DSH service probe / spawn / restart (kill port owner)
├── bridge.ts                # DSH official extension seam: patch entry + packaged bridge plugin (profile/dsh-obsidian-bridge/)
├── session-repair.ts        # Session format drift: precheck + backed-up repair (zstd multi-frame, DSH catalog validation)
├── session-repair-modal.ts  # Repair modal (read-only scan → back up and repair → re-check)
├── dsh-api.ts               # Local RPC client (session.list/prompt/history) over 127.0.0.1
├── startup-profiler.ts      # Startup timing log (phases → data.json)
├── installer.ts             # One-click install: deps (winget/npm/mirror) + clone + build + CLI
├── updater.ts               # Update check (official + mirror), stable-version gate
├── aed.ts                   # dsh-fix safe-mode recovery
├── view.ts                  # Embedded panel (iframe) with error view
├── settings.ts              # Settings tab (language / bridge / diagnostics)
├── changelog.ts             # In-app plugin changelog modal (+ changelog-data.ts)
├── i18n.ts                  # Chinese / English dictionary
└── win-exec.ts              # Windows .cmd wrapper for npm-style commands

Development

npm run dev        # esbuild watch mode
npm run build      # production build + install
npm test           # unit tests
npm run typecheck  # tsc --noEmit
npm run release:check   # full release gate (tests + lint + typecheck + review-style checks)

Verification harnesses (optional, require an isolated DSH install — see the scripts' headers):

node scripts/verify-embed.mjs <dsh-bin.js> <isolated-home> auth   # panel embedding auth matrix
node scripts/verify-session-repair.mjs <isolated-home> <dsh-package-dir>  # session drift repair end-to-end
python scripts/sandbox_ui_test.py                                  # real iframe UI checks (Playwright + system Chrome)

---

安装

方式一：商店安装（推荐） Obsidian → 设置 → 第三方插件 → 浏览 → 搜索 「DeepSeek Harness」 → 安装。无需 GitHub 链接。

方式二：本机已有 DSH 启用插件后，在设置中点「一键检测配置」即可自动识别并填充。

方式三：从源码构建

cd "07 coding project/dsh-obsidian"
npm install
npm run build   # 自动安装到 .obsidian/plugins/dsh-harness/

快速上手

1. 启用插件，侧边栏出现鲸鱼图标
2. 第一次用：设置 →「一键安装 DSH 本体」（或已装过 DSH 则点「一键检测配置」）
3. 点侧边栏图标打开面板，即开即用

主要设置

设置	默认	说明
界面语言	跟随 Obsidian	中文 / English，其他系统语言自动英文
服务端口	3080	DSH Web GUI 监听端口
启动命令 / 工作目录	空	自定义 dsh web 启动方式（支持 {port} 占位）
离线时自动启动	开	打开面板时若无服务自动拉起
进程独立常驻	开	关闭 Obsidian 后 DSH 继续运行
一键安装 DSH 本体	按钮	自动装依赖 → 克隆（实时百分比）→ 装依赖（进度条）→ 自动配置
自动检查更新	开	打开面板/启动服务时自动检测 DSH 新版本（有新版才弹窗，可查看 GitHub 更新内容或立即更新）
检查 DSH 更新	按钮	手动检查；官方源失败自动走只读镜像
会话格式修复	按钮	用 DSH 自带迁移链逐会话体检，把不可读的旧会话先备份再修复（检查只读；不改写必须显式点击）
插件信息	行	显示插件已安装版本；内置更新日志弹窗 + 「检查插件更新」（打开 Obsidian 官方商店页）+ GitHub 主页网址原文链接（使用反馈欢迎留言）
底部垫高	20px	面板底部留白（0–30px）：Obsidian 状态栏遮挡面板底部时使用
快捷键透传	开	光标聚焦在 DSH 面板内时 Obsidian 全局快捷键仍可响应（自动读取你的快捷键设置）
Obsidian 桥接到 DSH 聊天框	开	框选笔记文字自动发送（隐式信息行）；发送后自动打开 DSH 面板查看处理
DSH 聊天框桥接到 Obsidian	自动发送	三选项：取消 / 自动发送 / 右键发送；非「取消」时 DSH 生成的库内可阅读文件（如产物路径）点击即在 Obsidian 内打开阅读
更新日志	链接	打开 DSH（本体）GitHub Releases 页，查看各版本更新内容；插件自身的更新日志为内置弹窗
AED for DSH	按钮	下载并运行dsh-fix，并以安全模式启动DSH；请在DSH进入安全模式后命令DSH进行自我修复
安全模式启动	按钮	仅以安全模式启动 DSH（禁用全部用户插件）；旁边按钮可退出安全模式并恢复插件
更新镜像地址	空	自定义更新镜像；留空自动用 gh-proxy 兜底
安装地址	官方仓库	克隆地址，网络受限可换代理镜像
诊断	日志	启动耗时记录（最近 5 次）：插件加载 → 服务探测 → 服务启动 → 面板就绪

隐私与数据使用

• 插件层：插件不包含 DSH 的任何实现，界面与能力来自本机运行的 DSH Web GUI（dsh web）；插件与 DSH 之间仅通过本机回环（127.0.0.1）通信；插件自身发起的外网请求只有你主动触发的（克隆 DSH、检查更新）。无遥测。
• DSH 层：DSH 是 AI agent 框架，你使用它执行任务时，它会按需发起外网请求（如调用 AI 模型 API、访问工具/网页等），这些请求的内容由你所执行的任务决定。
• 数据流向由你掌控：DSH 将模型请求发往你配置的 provider（默认 DeepSeek 官方 API；baseURL 支持 OpenAI-completions/Responses、Anthropic-messages 等协议——可指向本地模型如 Ollama/vLLM，此时数据不出本机）。Vault 索引、会话记录与 API key 凭证均存于本机（本地凭证库）。
• 无遥测、无第三方中转：插件不运行遥测信标；Obsidian、插件与 DSH 之间没有云中转。

故障排查

症状 / 报错原文	原因	修复
面板打不开	工作目录不对、pnpm 不在 PATH、端口被占用	错误视图会给出原因与手动启动命令（复制即用）
spawn dsh ENOENT / 「找不到 dsh」	Windows 下 npm 系 .cmd shim 无法被 Node 直接执行	插件已内置 cmd.exe 包装；重载插件（彻底重启 Obsidian）
EADDRINUSE / 端口 3080 被占用	残留 DSH 进程占着端口	设置 →「快捷操作」→「重启服务」
「桥接未就绪，改为直接发送」	桥接脚本尚未注入面板	设置 →「快捷操作」→「重启服务」（插件更新后请先彻底重启 Obsidian 再重启 DSH 服务）
更新 CLI 时 koffi.node EBUSY	运行中的 DSH 锁住了原生模块	插件更新前会先停服务；否则手动停 DSH 后重试
DSH 升级后聊天记录缺失 / 某个会话打不开	DSH 各版本间的会话格式漂移（header 里的版本号从不变化，升级/降级都不会被拦）	设置 →「快捷操作」→「会话格式修复」→「备份并修复」；升级后预检发现不可读会话时也会自动打开该入口
DeepSeek request extension preparation failed（只有 DeepSeek 官方 provider 挂、换 provider 正常）	旧版桥接以「松散模块」装在 profile 目录，而它归属的清单缺 version	升级插件（2.4.0 起桥接为独立插件包）；仍出现则跑一次「会话格式修复」
升级/重启后 dsh web authentication required	启动 token 每进程重新生成，插件缓存了旧凭证	2.4.0 起会自动按新凭证重载面板；否则 设置 →「快捷操作」→「重启服务」
Could not resolve host / 更新失败	github.com 被墙或不稳定	检查网络；或换用「更新镜像地址」
npm 全局安装收尾挂起	该包的已知 npm 行为	以安装后 package.json 的版本为准验证，而非控制台输出

架构

src/
├── main.ts                  # 插件入口：命令/菜单/桥接接线/打点
├── service-manager.ts       # DSH 服务探活/启动/重启（清理端口占用）
├── bridge.ts                # DSH 官方扩展缝：补丁条目 + 独立包的桥接插件（profile/dsh-obsidian-bridge/）
├── session-repair.ts        # 会话格式漂移：只读预检 + 带备份修复（zstd 多帧切分，DSH catalog 复验）
├── session-repair-modal.ts  # 修复弹窗（只读体检 → 备份并修复 → 自动复检）
├── dsh-api.ts               # 本机 RPC 客户端（session.list/prompt/history，走 127.0.0.1）
├── startup-profiler.ts      # 启动耗时打点（各阶段 → data.json）
├── installer.ts             # 一键安装：依赖（winget/npm/镜像）+ 克隆 + 构建 + CLI
├── updater.ts               # 更新检查（官方+镜像），仅正式版门禁
├── aed.ts                   # dsh-fix 安全模式抢救
├── view.ts                  # 内嵌面板（iframe）+ 错误视图
├── settings.ts              # 设置页（语言/桥接/诊断）
├── changelog.ts             # 插件更新日志弹窗（+ changelog-data.ts 数据）
├── i18n.ts                  # 中英双语词典
└── win-exec.ts              # Windows npm 系命令的 cmd.exe 包装

开发

npm run dev        # esbuild 监听模式
npm run build      # 生产构建并安装
npm test           # 单元测试
npm run typecheck  # 类型检查（tsc --noEmit）
npm run release:check  # 发布前全量门禁（测试+lint+类型检查+审核风格校验）

验证脚本（可选，需要一个隔离的 DSH 安装；用法见脚本头部注释）：

node scripts/verify-embed.mjs <dsh-bin.js> <隔离 home> auth            # 面板嵌入认证矩阵
node scripts/verify-session-repair.mjs <隔离 home> <DSH 安装包目录>     # 会话漂移修复端到端
python scripts/sandbox_ui_test.py                                      # 真实 iframe UI 检查（Playwright + 系统 Chrome）