DeepSeek Harness

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 版本演进持续可用。

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 compatibility note in the dialog follows registration (since v2.8.8 it is generated from the verified range and upper bound: "verified ✓" inside it, "not yet registered" above it, with the seam self-check previewed). 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.
• Official package only — the local DSH version is read from the official manifests (@deepseek-ai/dsh for the global CLI, @deepseek-ai/dsh-root for a source checkout). Third-party same-named community packages on npm (e.g. @x1a0f3n9/dsh-web-app, dsh-workspace, which share the official 0.1.5-rc.x number space: 0.1.5-rc.3 exists in both — official on 2026-09-22, third-party rc.3/4/5 on 09-18~09-20) are never mistaken for DSH; when a version can't be verified, it is displayed but not used for a verdict or a dialog.
• 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), the process scope is narrowed to official identities (better to miss one than to kill a stranger), your session history is backed up, and readability is re-checked afterwards.
• Session format repair — if a DSH upgrade leaves sessions unreadable (the session format drifts between DSH versions), a built-in checker scans every session with DSH's own format chain and reports which are readable, then one click backs up and repairs the ones the current format rejects. Sessions still on an older format than your DSH are left untouched, because DSH migrates those itself when opening them (the scan is read-only; 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.
• Multi-profile coexistence — bind the panel to another DSH profile (e.g. test) while the desktop app keeps its own (typical: web on 3080). The plugin creates the profile from the web template, installs its bridge into it, launches it on its own port, and restarts only what it launched — foreign DSH instances are never killed.
• Attachment upload works inside the panel — dragged/pasted files upload with native percentage progress (fixed the cross-site-iframe 401 on DSH 0.1.5 upload workers).
• Silent compatibility verdict — the plugin checks the local DSH version against its verified range and whether the bridge is actually live in the served page (a bridge file on disk is not the same as a live bridge: DSH loads its patch layer only at service start). The result is shown in plain text only — in the status row and under Current compatibility in settings. It never interrupts you with a dialog; when something is really wrong, the features themselves tell you.
• Seam self-check (v2.8.8 — you no longer have to ask "is the new DSH OK?") — whenever the local DSH is newer than the verified upper bound (and comes from a verified official global install), the plugin runs a read-only seam self-check after startup: all 27 integration seams are re-counted against the fingerprint captured when that bound was registered, and a one-line verdict is appended to the Current compatibility row (all present / changed / missing / not run). It is an early warning only: "all present" never registers support (the sandbox-suite rule stands), and "missing" still says nothing in a dialog.
• Update channel you control — stable only / follow the pushed version (rc & beta, default) / include alpha, with an optional automatic check after startup (24h by default) that asks before installing, because updating stops every local DSH process first.
• 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 (a standalone npm global CLI, not a DSH plugin; the plugin keeps it at the latest version and falls back to npmmirror when the official registry is unreachable) to enter safe mode and recover, then verifies the boot and offers one-click fixes. Typical breakages it can bring back: ① plugins conflict so DSH won't start or crashes during initialisation; ② cordis.patch.yml fails to parse and the whole plugin layer never loads; ③ a plugin package is missing or left behind by an uninstall (cannot find module / MODULE_NOT_FOUND); ④ a bundle-layer plugin installed via dsh plugin add breaks startup (out of reach of patch-layer disables); ⑤ safe-mode leftovers disabled the bridge or client modules (blank panel, client.js did not export the bootstrap module face, selection injection silently dead); ⑥ the process answers on the port but the page lacks the boot injection. That list also sits behind the inline "What it can fix" link, keeping the row itself to one short description. Not for: unreadable sessions (use the Session repair button), model or credential configuration, or an unsupported DSH version.
• 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). Verified range: DSH 0.1.5-rc.1 ~ 0.2.0-rc.2 (shown in Settings → plugin info and "current compatibility") — 0.1.2–0.1.4 are known incompatible and the update dialog warns before installing them. Outside the verified range the panel still works, but nothing is promised; the verdict is displayed in settings without interrupting you.
• 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 更新，确认后一键更新（官方源被墙时自动走只读镜像，可在设置中自定义镜像地址）
• 多 Profile 协同：桌面版等其他实例继续用它们的 profile（常见为 web / 3080）时，面板可绑定另一个 profile（如 test）——插件基于 web 模板代建、把桥接装入该 profile、在独立端口自管拉起；「重启服务」只终止插件自己拉起的实例，绝不杀外部 DSH 进程
• 面板内附件上传：拖拽/按钮上传附件正常且保留原生百分比进度（修复 DSH 0.1.5 跨站 iframe 下上传 Worker 无凭据 401 的问题）

原生体验

• 原生 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（独立命令行工具，npm 全局包，不是 DSH 插件；插件负责装到最新，官方源不通走 npmmirror 镜像）进入安全模式抢救，完成后校验启动、异常可一键修复。能抢救回来的常见崩溃状态：①插件互相冲突导致起不来或初始化即崩；②cordis.patch.yml 解析报错、插件层整体加载不了；③插件包缺失或卸载残留（cannot find module / MODULE_NOT_FOUND）；④经 dsh plugin add 安装的 bundle 层插件拖垮启动（补丁层管不到的那一类）；⑤安全模式残留把桥接或客户端模块禁掉（面板白屏、client.js did not export the bootstrap module face、框选注入静默失效）；⑥进程在端口上应答但页面缺启动引导注入。这份清单也做成设置页 AED 行内的「适用症状说明」链接，点开即看，不占正文。不适用：会话打不开（用「会话修复」）、模型与凭据配置、DSH 版本本身不适配

兼容与修复

• 适配范围明示：插件按 DSH 版本逐版实测适配，当前实测区间 0.1.5-rc.1 ~ 0.2.0-rc.2（设置 →「插件信息」栏与「当前适配状态」直接可见）；0.1.2–0.1.4 已知不兼容，更新弹窗会在安装前红字提醒
• 适配判定静默呈现：插件会核对本机 DSH 版本是否在适配区间内、桥接是否真正生效于页面（磁盘上有桥接文件不等于生效——DSH 只在服务启动时加载补丁层），结论只写在设置页两行文字与 DSH 状态横幅里；任何情况下都不弹「不适配」提示框——真坏了，功能本身比一句提示更直观
• 触点自检（v2.8.8，检查适配不再依赖人工发起）：本机 DSH 高于实测上界时，插件开机后自动对安装树跑一次只读触点自检——按登记该上界时抓的 27 项触点指纹逐项核对符号是否仍在，结论一句话追加在「当前适配状态」行尾（全在 / 有出入 / 有消失 / 未执行）。它只是提前预警：「触点全在」不冒充实测登记（登记仍须沙盒实跑，规矩不变），「触点消失」也不弹窗——你在设置页看得见，功能坏没坏仍以实际表现为准
• 版本感知更新：一键安装/更新取 DSH 官方最新版——弹窗里的适配说明跟登记走（v2.8.8 起按实测区间与上界自动生成：区间内注明"实测适配 ✓"、高于上界如实标注"尚未登记实测"并预告开机触点自检）；仅 0.1.2–0.1.4 红字劝退（0.1.1 系同样可用）；检测到已装 CLI 落在不兼容区间时自动升级
• 更新通道可选：DSH 目前只发预发布版本，故更新检测支持仅正式版 / 跟随主推（含 rc/beta，默认）/ 含 alpha 三档；启动后按通道自动检查（默认 24 小时一次），发现新版才弹确认框，绝不静默安装
• 只认官方 DSH 包：本机版本只从官方包清单读取（全局 CLI 为 @deepseek-ai/dsh，源码仓库根为 @deepseek-ai/dsh-root）。npm 上的第三方同名社区包（如 @x1a0f3n9/dsh-web-app、dsh-workspace，与官方共用 0.1.5-rc.x 号段（官方 0.1.5-rc.3 发布于 2026-09-22；第三方同名 rc.3/rc.4/rc.5 发布于 09-18～09-20），同一版本串可能是两个不同程序）不会被当成本体；来源无法核验时只展示版本、不做适配判定也不弹窗
• 升级更稳：更新 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.5-rc.1 ~ 0.2.0-rc.2（设置 →「插件信息」与「当前适配状态」可见）——0.1.2–0.1.4 已知不兼容，更新弹窗会在安装前红字提醒；超出区间仍可使用，但插件不承诺功能正常，判定只以设置页文字呈现，不弹窗打扰；高于上界的新版开机后自动跑一次只读触点自检（v2.8.8），结论同样只写在文字里
• DSH 模型 API key：默认 DeepSeek 官方 API；可配置任意 OpenAI/Anthropic 兼容端点（含本地模型）

性能

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

致谢

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

Key settings

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

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. 点侧边栏图标打开面板，即开即用

主要设置

隐私与数据使用

• 插件层：插件不包含 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 之间没有云中转。

故障排查

架构

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）