README file from
GithubDeepSeek Harness for Obsidian
Status: released · Desktop only(Windows / macOS / Linux 预览)· English · 中文
Embed the native DSH Web UI into your vault — one-click setup, silent operation, a two-way bridge, 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 into your vault. It touches no DSH source (it uses DSH's official extension seam), keeps working as DSH evolves, needs no command line, and reaches DSH over the local loopback by default.
Features
- One-click setup — installs or detects DSH and auto-installs missing tools (git / Node.js / pnpm) with a live progress bar.
- Silent operation — the DSH service starts in the background with no console window; crashes are detected and reconnected in one click.
- Native Web UI — the real DSH interface in an iframe, with 0.5×–2.0× zoom and theme-following styling.
- Two-way bridge — selecting text in a note injects an implicit line (exact line:col + word count, no original text) into the DSH chat so DSH can read and edit the file itself; DSH artifacts inside your vault (paths in chat, changed-files cards, presented-file cards) open in Obsidian with one click.
- Shortcut passthrough & self-healing — Obsidian global shortcuts still work inside the panel, and the bridge plus launch credential are refreshed automatically after DSH or plugin updates.
- Multi-profile coexistence — bind the panel to another DSH profile (e.g.
test) next to the desktop app'sweb; the plugin builds it from the web template, launches it on its own port and restarts only what it launched. - Version-aware updates, official packages only — one-click install/update takes DSH's official latest on the channel you pick (stable / pushed rc & beta / alpha), the compatibility note follows the verified range, and same-named third-party npm packages are never mistaken for DSH.
- Safe upgrades & session repair — every DSH process is stopped before an update (Windows file locks) with sessions backed up and re-checked; a read-only checker plus one-click "back up and repair" handles sessions that a format drift leaves unreadable.
- Silent compatibility verdict — version, live-bridge check and a read-only seam self-check above the verified upper bound are shown as plain text in the status row and settings, never as a dialog.
- AED rescue — when DSH won't start, one click runs dsh-fix (a standalone npm global CLI, kept up to date) to enter safe mode and rescue it, then verifies the launch and offers fixes; the symptoms it covers are listed in the "What it can fix" popup on its settings row, and unreadable sessions belong to Session repair.
- Custom endpoint & native HTTPS — point the plugin at the local address DSH is bound to (IPv4/IPv6, optionally https via
--tls-cert/--tls-key); details in Key settings. - One-click phone access (top of the Service runtime group) — generates a local HTTPS certificate, fills in the LAN host / protocol / certificate / key paths and drops
rootCA.pemon the Desktop, with pre-flight risks, iOS/Android setup steps and a one-click reset of the endpoint settings. Keep the computer powered on and awake (no sleep) while the phone is using it. - Errors explained, faster starts — failures show a plain-language reason with one-click reconnect / "Ask AI how to fix"; capability probes are cached and a startup timing log sits in Settings → Diagnostics.
Requirements & install
- Obsidian desktop v1.7.2+ (Windows / macOS; Linux is preview support — see the Linux notes below).
- DSH: the plugin can install it for you (git / Node.js / pnpm are auto-installed; mirror fallback when the official source is blocked). Verified range: DSH 0.1.5-rc.1 ~ 0.2.2-rc.5; 0.1.2–0.1.4 are known incompatible, and outside the range nothing is promised.
- A model API key for DSH (default: DeepSeek API; any OpenAI/Anthropic-compatible endpoint, including a local model).
- Install from the community store (Settings → Community plugins → Browse → search "DeepSeek Harness"), from an existing local DSH (Settings → "One-click detect & configure"), or from source (
npm install && npm run buildinstalls into.obsidian/plugins/dsh-harness/).
Linux (Ubuntu/Debian) notes. The plugin drives DSH the same way on Linux: the service is launched into its own setsid process group (no console window to hide), stopped per process group, and the panel embeds the same token-authenticated URL. What to prepare:
- Node.js ≥ 22.15 (
node -v): session repair needs the built-in zstd. Usenvm install 22 && nvm use 22or NodeSource; distro packages are often older. - git / pnpm: if missing, the one-click setup installs pnpm via
npm install -g pnpmand prints the exactapt/dnf/pacmancommand for git (it never runssudofor you). EACCESfromnpm i -g: the global prefix isn't writable (Node installed by root). Switch to a Node managed by nvm, or setnpm config set prefix ~/.local.- HTTPS for phone/LAN access: Linux trusts certificates in two stores — run both lines from the success dialog:
sudo cp ~/Desktop/rootCA.pem /usr/local/share/ca-certificates/dsh-harness.crt && sudo update-ca-certificates, thencertutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n dsh-harness -i ~/Desktop/rootCA.pem(sudo apt install -y libnss3-toolsifcertutilis missing). Electron/Chromium validate against the NSS user DB, so the system store alone is not enough. - Preview status: the Linux path is code-verified (no platform gate, POSIX branches audited,
npm testruns on Linux in CI) but not yet validated on real Ubuntu hardware by this project.
Key settings
| Setting | Default | Description |
|---|---|---|
| Interface language | Follow Obsidian | Chinese / English; other system languages fall back to English |
| Service address | 127.0.0.1 | Endpoint host the panel connects to — must match dsh web --host: a local IPv4 or IPv6 literal (127.0.0.1, 192.168.1.5, ::1), no scheme/port/wildcard; a non-loopback address exposes DSH to your LAN (https and trusted networks only) |
| Service port | 3080 | Port the DSH Web GUI listens on (with the address above and protocol below it forms the endpoint) |
| Service protocol | http | http or https; https requires the two certificate paths below (DSH 0.2.1-rc.2's --tls-cert / --tls-key) |
| HTTPS certificate PEM | empty | Path to the certificate PEM (not its contents). Passed to DSH as --tls-cert and also used as the plugin's trust anchor, so it must be the server certificate chain containing the leaf (concatenate a private CA into the same file; a self-signed single certificate is its own anchor). A custom command that supplies --tls-cert may instead point this at the issuing CA |
| HTTPS private key PEM | empty | Path to the private key PEM (not its contents), paired with the certificate; passed as --tls-key |
| DSH profile | web | Pick an existing profile or type a new name (asks first); non-web profiles are built from the web template, get their own bridge and port; built-in names (acp / headless / sdk / sdk-minimal) are rejected |
| Auto-start / detached process | on / on | Start the service when the panel opens with none running; keep DSH running after Obsidian exits |
| Startup timeout | 300s | Max wait for the service after auto-start (60–600s); the first start may take 1–2 minutes |
| Startup command / working directory | empty | Empty = the plugin builds the command from the endpoint above; a value keeps your own arguments and the plugin appends only the missing --host / --tls-cert / --tls-key (flags you already wrote win) |
| One-click install DSH | button | Dependencies → clone (live percentage) → install (progress bar) → configure; the clone URL can switch to a proxy mirror |
| DSH updates | official release | Auto-check at most once per 24h by default on the channel: stable only / follow official releases (rc & beta) / include alpha; a version is offered only after it appears as a GitHub release of the official repo, so a prerelease that npm receives first (next tag) is not pushed; if the release query is unreachable the npm-based check is used as a fallback; manual check and a custom mirror URL live on the same row, and it never installs silently |
| Current compatibility | row | Detected version and verdict (supported ✓ / known-incompatible ✗ / older or newer than verified ⚠ / bridge missing / unverifiable) with "re-check now"; text only, no dialogs |
| Session repair | button | Read-only scan with DSH's own format chain; back up and repair the sessions the current format rejects (older-format sessions are left for DSH to migrate) |
| Plugin info | row | Plugin version, in-app changelog and DSH compatibility modals, "check plugin updates", GitHub repo; the DSH changelog link opens its Releases page |
| Bottom padding | 20px | Empty space below the panel (0–30px) when the Obsidian status bar covers it |
| Shortcut passthrough | on | Obsidian global shortcuts still work while focus is inside the DSH panel |
| Two-way bridge | on / auto-send | Note selection → DSH chat (implicit info line); DSH artifacts → Obsidian: cancel / auto-send / right-click send |
| AED for DSH | button | Downloads and runs dsh-fix to enter safe mode and rescue a DSH that won't start, then verifies the launch; the inline "What it can fix" link lists the symptoms |
| Remote access setup | buttons + link | At the top of the Service runtime group: Generate & fill creates a self-signed HTTPS certificate (Desktop rootCA.pem), installs it into the current Windows user's trusted roots automatically (no admin; macOS is manual), and fills host (LAN IPv4) / protocol / certificate / key, so phones, tablets or other computers on the same LAN can reach this machine's DSH; the "Phone remote-access example" link walks through a full example — scene, steps (generate → trust rootCA.pem → restart → Copy token link → open it on the phone), result and limits (including keeping the computer awake); Reset endpoint defaults returns to 127.0.0.1 / http / empty paths, restarts the service and reloads the panel automatically, and keeps the certificate files and any trust already installed (an already-open external browser tab must be closed and reopened) |
| Connection address | row + button | Shows the endpoint the plugin actually connects to (http(s)://host:port) and runs a read-only TCP + GET / check: not running / timeout / untrusted, mismatched or expired certificate (the raw TLS code is included) |
| 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 and reaches DSH over local HTTP(S): the local loopback by default, or another local bind address you configure. The only outbound requests it makes are the ones you trigger (cloning DSH, checking updates). No telemetry, no third-party relay.
- DSH layer — DSH is an AI agent framework; when you run a task it makes outbound requests as needed (model APIs, tool/web access), and what is sent depends on the task.
- Your data, your provider — model requests go to the provider you configure (default DeepSeek API; OpenAI-completions/Responses, Anthropic-messages, or a local model such as Ollama/vLLM, where data never leaves your machine). Vault index, session history and API keys stay local.
- LAN exposure — a non-loopback service address exposes DSH to your network; use https and only trusted networks.
Troubleshooting
| Symptom / error | Cause | Fix |
|---|---|---|
| Panel won't open | Wrong working directory, pnpm missing, port taken, or the service address/protocol doesn't match the running instance |
The error view shows the reason + a copy-paste startup command; make the service address match dsh web --host |
spawn dsh ENOENT / "dsh not found" |
Windows .cmd shim not resolvable by Node; on Linux/macOS the Node/pnpm directory is missing from Obsidian's PATH |
The plugin wraps npm-style commands via cmd.exe on Windows and merges the login-shell PATH elsewhere — reload the plugin (fully restart Obsidian). If it persists on Linux, install Node globally (NodeSource) or nvm alias default 22 |
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 | Restart service (after a plugin update, fully restart Obsidian first) |
| Chat history missing or a session won't open after a DSH upgrade | Session format drift between DSH versions | Settings → Quick actions → Session repair → "Back up and repair"; older-format sessions are left for DSH to migrate when opened |
dsh web authentication required after upgrading or restarting DSH |
The launch token is generated per process and the cached one is stale | Restart service; the panel reloads with the new credential |
| Panel unavailable after upgrading DSH to a version newer than the plugin's verified range | The plugin has not been adapted to that DSH release yet (e.g. 0.2.2 moved index authorization to a Fetch request) | The unavailable page offers Fall back to adapted DSH — confirm and it installs the verified version and restarts the service; dsh web authentication required in the iframe is the usual symptom. "Open DSH in browser" keeps working until you do |
Self-signed certificate not trusted (DEPTH_ZERO_SELF_SIGNED_CERT / UNABLE_TO_VERIFY_LEAF_SIGNATURE) |
Certificate not in the OS trust store, and/or no cert PEM configured for the plugin | Import it into the system trust root (Windows "Trusted Root Certification Authorities"; macOS Keychain "Always Trust"; Linux update-ca-certificates plus the NSS user store — see the Linux notes) and paste the same PEM into TLS certificate |
| Linux: panel still reports a certificate error after generating the HTTPS config | Electron/Chromium on Linux read the NSS user database (~/.pki/nssdb), not only the system store |
Run both commands from the success dialog (update-ca-certificates, then certutil -d sql:$HOME/.pki/nssdb -A …), then restart Obsidian |
ERR_TLS_CERT_ALTNAME_INVALID / certificate SAN lacks the address |
The certificate was issued for another hostname | Re-issue it with the address you enter (192.168.1.5, a hostname, …) in the SAN, or use a loopback address |
| Phone still says the certificate is untrusted after installing it | iOS: the profile is installed but not enabled under Certificate Trust Settings. Android: the file went in as a VPN/other profile, or only into user credentials while the browser still checks the system store. Also: every "Generate & fill" replaces the certificate, so an older rootCA.pem stops matching | iOS: Settings → General → About → Certificate Trust Settings → enable the root. Android: reinstall it as a "CA certificate" (not VPN) and check the phone's clock. Re-send the latest Desktop rootCA.pem after regenerating |
| Obsidian panel is blank after switching to the LAN HTTPS address | The Windows trust store lacks the rootCA (older plugin version, or the auto-install failed) — browsers offer "proceed anyway", iframes do not | 2.9.2+ installs it automatically; otherwise import Desktop rootCA.pem into the current user's Trusted Root Certification Authorities and restart Obsidian |
| Phone loses the connection after a while | The computer went to sleep or hibernated — the phone only reaches a running DSH | Disable sleep while the phone is in use: Settings → System → Power & battery → Screen and sleep → Never; on laptops also disable “sleep when closing the lid”, or keep it plugged in |
| After "Reset endpoint defaults" an external browser tab still shows the old https LAN address | A browser tab's URL cannot be rewritten by the plugin; only the Obsidian panel is reloaded | Close that tab and reopen the default address with "Open DSH in browser" (the panel already switched back to 127.0.0.1 automatically) |
| "No LAN IPv4 address found" when generating | This machine has no Wi-Fi/Ethernet interface with a private IPv4 (hotspot-only, VPN-only, or all interfaces internal) | Connect to the LAN and retry; or keep the loopback setup and issue a certificate whose SAN contains the IP your phone can reach |
https selected but the service still starts as http |
Certificate or key empty, or the startup command already carries conflicting TLS flags | Fill both TLS fields (the plugin appends --tls-cert/--tls-key to the command); remove any conflicting flags you wrote yourself |
unknown option '--host' / '--tls-cert' when the service starts |
The installed DSH predates 0.2.1-rc.2, which added these flags | Update DSH, or keep the default loopback/http here (a custom command with these flags only works after upgrading) |
Custom --host but the plugin still probes 127.0.0.1 |
The service address setting was not updated | Enter the same address under Service address |
After filling the phone-access config the service won't start, and "Open DSH in browser" still shows http://127.0.0.1:3080 |
The startup command was a detected default such as dsh web --port {port} --no-open; ≤2.9.1 used it verbatim, so the host/TLS settings were silently ignored |
2.9.2+ appends the missing --host / --tls-cert / --tls-key automatically — update the plugin and restart the service. On 2.9.1 or older, clear the Startup command field (or add those flags yourself) before restarting |
| A DSH instance started in a terminal can't be used in the panel | The embed token is only captured from a process the plugin launched | The plugin can still detect it and open it in a browser; the embedded panel needs a plugin-launched service — Restart service takes the port over |
Could not resolve host / update fails |
github.com blocked or flaky | Set the update mirror URL, or check the network |
| Updating DSH seems to hang for minutes | npm has to write ~1.1 GB across ~95k files into the global prefix — measured 688 s even with a fully warm cache (network is not the bottleneck) | Not stuck: the dialog now shows elapsed time and the expected 5–12 minutes. Let it finish; a single stalled CDN tarball is now retried (120 s timeout) instead of waiting ~7 minutes |
| 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 & development
src/
├── main.ts · settings.ts · view.ts # entry & commands; settings tab; iframe panel
├── service-endpoint.ts # service address / protocol / TLS endpoint
├── cert-gen.ts · mobile-access-modal.ts # self-signed certificate generation; phone-access dialogs
├── service-manager.ts # probe / spawn / restart, port-owner cleanup
├── dsh-api.ts · bridge.ts # local RPC client; official extension seam + bridge package
├── aed.ts · installer.ts · updater.ts # dsh-fix safe-mode rescue; one-click install; update check
├── session-repair*.ts · startup-profiler.ts · changelog.ts # session repair / timing log / changelog
└── i18n.ts · win-exec.ts # zh/en dictionary; Windows .cmd wrapper
npm run dev # esbuild watch mode
npm run build # production build + install into .obsidian/plugins/dsh-harness
npm test # unit tests
npm run typecheck # tsc --noEmit
npm run release:check # full gate: tests + lint + typecheck + review checks
# optional verification harnesses (need an isolated DSH install; usage in each script header)
node scripts/verify-embed.mjs <dsh-bin.js> <isolated-home> auth # panel embedding auth matrix
node scripts/verify-session-repair.mjs <isolated-home> <dsh-pkg-dir> # session drift repair end-to-end
node scripts/verify-endpoint-tls.mjs # iso home: https + IPv4/IPv6 endpoint end-to-end
python scripts/sandbox_ui_test.py # real iframe checks (Playwright + Chrome)
Credits
Thanks to the DeepSeek and Obsidian open-source teams — the open, shared spirit of the internet makes tools like this possible; and to Claudian, whose select-and-send design inspired this plugin's bridge. Thanks to @chichilatte for diagnosing and fixing the permanent 401 after first install / temp cleanup.
中文
一个把 DeepSeek Harness(DSH)原生 Web UI 无痕嵌入 Obsidian 的桌面插件:不改 DSH 源码(走官方扩展缝),随 DSH 演进持续可用,无需命令行,默认经本机回环连接。
功能
- 一键配置:自动安装或识别 DSH,缺失的 git / Node.js / pnpm 自动装好,进度条实时可见。
- 静默运行:DSH 服务后台启动、无控制台窗口;崩溃自动检测,一键重连。
- 原生 Web UI:iframe 直接嵌入真实 DSH 界面,0.5×–2.0× 缩放,外观跟随主题。
- 双向桥接:笔记里框选文字 → 自动向 DSH 聊天框注入隐式信息行(精确行:列 + 字数,不含原文),由 DSH 自行读取文件处理——先判读这次是取材(存进别的文件、总结、翻译)、就地改写还是仅定位解释,框选一节标题要求改写时按整节处理;DSH 产物在 Vault 内点击即在 Obsidian 打开(对话里的文件路径、改动文件卡片、产物卡片均适用)。
- 快捷键透传与自愈:面板内仍响应 Obsidian 全局快捷键;DSH 或插件更新后自动重写桥接、按新凭证重载面板。
- 多 Profile 共存:面板可绑定另一个 profile(如 test),与桌面版的 web 并存;插件基于 web 模板代建、独立端口拉起,「重启服务」只终止插件自己拉起的实例。
- 版本感知更新、只认官方包:一键安装/更新取官方最新版,通道可选(仅正式版 / 跟随主推 rc & beta / 含 alpha),弹窗适配说明跟实测区间走,第三方同名 npm 包不会被当成本体。
- 升级更稳与会话修复:更新前先结束所有 DSH 进程(避免 Windows 文件锁),并备份会话、升级后复检;只读检查器 + 一键「备份并修复」处理格式漂移导致打不开的会话。
- 适配判定静默呈现:版本、桥接是否真正生效,以及高于上界时的只读触点自检,结论只写在状态横幅与设置页文字里,不弹窗。
- AED 抢救:DSH 起不来时,一键用 dsh-fix(独立 npm 全局命令,插件自动保持最新)进入安全模式抢救,完成后校验启动并给出修复建议;能抢救哪些症状见设置页该行「适用症状说明」,会话打不开请用「会话修复」。
- 自定义服务地址与原生 HTTPS:可对齐 DSH 绑定的本机地址(IPv4/IPv6,经
--tls-cert/--tls-key启用 https),详见「主要设置」。 - 一键手机访问(位于「服务运行」分组最上方):自动生成本机 HTTPS 自签证书并填好局域网地址 / 协议 / 证书 / 私钥路径,把
rootCA.pem放到桌面,手机浏览器即可远程访问;生成前有风险提示,成功后按 iOS / 安卓步骤安装信任,可一键恢复默认端点。手机使用期间电脑需保持开机、不睡眠。 - 报错可读、启动更快:失败时给出原因 + 一键重连 /「询问 AI 如何修复」;能力探测结果缓存,设置 →「诊断」有启动耗时记录。
环境要求与安装
- Obsidian 桌面版 v1.7.2+(Windows / macOS;Linux 为预览支持,见下方「Linux(Ubuntu / Debian)说明」)。
- DSH 本体:插件可一键安装(git / Node.js / pnpm 缺失自动补齐,官方源被墙走镜像)。实测适配区间:DSH 0.1.5-rc.1 ~ 0.2.2-rc.5;0.1.2–0.1.4 已知不兼容,超出区间不承诺。
- DSH 模型 API key:默认 DeepSeek 官方 API;可配置任意 OpenAI/Anthropic 兼容端点(含本地模型)。
- 安装:商店(设置 → 第三方插件 → 浏览 → 搜「DeepSeek Harness」);本机已有 DSH 时启用插件后点「一键检测配置」;源码构建(
npm install && npm run build,装到.obsidian/plugins/dsh-harness/)。
Linux(Ubuntu / Debian)说明。 插件在 Linux 上的运作方式与 macOS 一致:服务以独立 setsid 进程组拉起(无需隐藏控制台)、按进程组停止、面板嵌入同一个带 token 的地址。需要准备:
- Node.js ≥ 22.15(
node -v确认):会话修复依赖内置 zstd。推荐nvm install 22 && nvm use 22或 NodeSource 源;发行版自带 node 往往低于 22.15。 - git / pnpm:缺失时一键安装会用
npm install -g pnpm,并给出 git 的apt / dnf / pacman命令(不会替你执行 sudo)。 npm i -g报EACCES:全局前缀不可写(node 由 root 安装)。改用 nvm 管理的 Node,或npm config set prefix ~/.local。- 手机 / 局域网 HTTPS:Linux 的证书信任有两处,成功弹窗里的两条命令都要执行——
sudo cp ~/Desktop/rootCA.pem /usr/local/share/ca-certificates/dsh-harness.crt && sudo update-ca-certificates,以及certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n dsh-harness -i ~/Desktop/rootCA.pem(缺 certutil 先sudo apt install -y libnss3-tools)。Electron/Chromium 读 NSS 用户库,只做系统信任不够。 - 预览状态:Linux 链路已经过代码级核对(无平台门禁、POSIX 分支逐条审计、CI 的
npm test本身跑在 Linux 上),但本项目尚未在真实 Ubuntu 硬件上验收。
主要设置
| 设置 | 默认 | 说明 |
|---|---|---|
| 界面语言 | 跟随 Obsidian | 中文 / English,其他系统语言回退英文 |
| 服务地址 | 127.0.0.1 | 面板连接的端点主机,须与 dsh web --host 一致:本机 IPv4 或 IPv6 字面量(127.0.0.1、192.168.1.5、::1),不带协议/端口/通配地址;非回环地址会把 DSH 暴露到局域网(须 https + 可信网络) |
| 服务端口 | 3080 | DSH Web GUI 监听端口(与地址、协议共同组成端点) |
| 服务协议 | http | http / https;https 需填下面两项证书路径(DSH 0.2.1-rc.2 的 --tls-cert / --tls-key) |
| HTTPS 证书 PEM | 空 | 证书 PEM 的文件路径(不是内容)。作为 --tls-cert 交给 DSH,同时作插件校验锚点,须是含 leaf 的服务器证书链:私有 CA 把 CA 拼进同一文件,自签单证书本身即锚点;自定义启动命令自带 --tls-cert 时可改填签发它的 CA。自签名/私有 CA 还须把证书导入系统信任根供内嵌面板加载 |
| HTTPS 私钥 PEM | 空 | 私钥 PEM 的文件路径(不是内容),与证书成对;作为 --tls-key 交给 DSH |
| DSH Profile(配置档) | web | 下拉选已有 profile 或输入新名(切换前确认);非 web 档基于 web 模板代建、装桥接、独立端口拉起;内置档名(acp / headless / sdk / sdk-minimal)不可代建 |
| 离线自动启动 / 进程独立常驻 | 开 / 开 | 打开面板时端点无服务则拉起;关闭 Obsidian 后 DSH 继续运行 |
| 启动等待时间 | 300 秒 | 自动启动后等待服务就绪的上限(60–600 秒);首次启动可能需要 1–2 分钟 |
| 启动命令 / 工作目录 | 空 | 留空=由插件按上面的地址/端口/协议生成命令;填入则保留你的参数,插件只补缺失的 --host / --tls-cert / --tls-key(已有同名参数以命令为准) |
| 一键安装 DSH 本体 | 按钮 | 装依赖 → 克隆(实时百分比)→ 装依赖(进度条)→ 自动配置;克隆地址可换代理镜像 |
| DSH 更新 | 跟随官方发布 | 启动后自动检查(默认 24 小时至多一次)+ 通道:仅正式版 / 跟随官方发布(含 rc、beta)/ 含 alpha;只有官方 GitHub 仓库已发布为 release 的版本才会被提示——npm 抢先收到预发布(next 标签)不推送;官方 release 查询不通时回退按 npm 判定,同行可手动检查、自定义更新镜像,绝不静默安装 |
| 当前适配状态 | 行 | 显示版本与判定(已适配 ✓ / 已知不兼容 ✗ / 旧版或新版本 ⚠ / 桥接未生效 / 版本未能核验),同行可「重新检查」;只呈现文字,不弹窗 |
| 会话修复 | 按钮 | 用 DSH 自带格式链只读体检,对当前格式判定不可读的会话先备份再修复;格式更旧的会话留给 DSH 自行迁移 |
| 插件信息 | 行 | 插件版本、内置更新日志与 DSH 适配说明弹窗、「检查插件更新」、GitHub 主页;DSH 更新日志指向其 Releases 页 |
| 底部垫高 | 20px | 状态栏遮挡面板底部时留白(0–30px) |
| 快捷键透传 | 开 | 面板内仍响应 Obsidian 全局快捷键 |
| 双向桥接 | 开 / 自动发送 | 笔记框选 → DSH 聊天框(隐式信息行,DSH 据此判读取材/就地改写/仅定位,选标题则按整节);DSH 产物 → Obsidian:取消 / 自动发送 / 右键发送 |
| AED for DSH | 按钮 | 下载并运行 dsh-fix 进入安全模式抢救起不来的 DSH,完成后校验启动;行内「适用症状说明」链接列出可抢救的症状 |
| 远程访问配置 | 按钮 + 链接 | 位于「服务运行」分组最上方:「生成并填入」生成自签 HTTPS 证书(桌面 rootCA.pem),Windows 下自动装入当前用户「受信任的根证书颁发机构」(免管理员;macOS 需手动),并填好服务地址(局域网 IPv4)/ 协议 / 证书 / 私钥,供同一局域网内的手机、平板或其它电脑浏览器访问本机 DSH;行内「手机远程访问示例」以示例形式串起场景 → 步骤(生成 → 信任 rootCA.pem → 重启 → 复制 token 链接 → 手机打开)→ 结果 → 边界与风险(含电脑需保持开机、不睡眠);「恢复默认端点」退回 127.0.0.1 / http / 空路径,自动重启服务并刷新面板,证书文件保留、已安装的信任不撤销(外部浏览器里已打开的旧页面需手动关闭重开) |
| 连接地址 | 行 + 按钮 | 显示插件实际会连的端点(http(s)://host:port),并做一次只读 TCP + GET / 检查:未启动 / 超时 / 证书未受信任、地址不匹配或已过期(附原始 TLS code) |
| 诊断 | 日志 | 启动耗时记录(最近 5 次):插件加载 → 服务探测 → 服务启动 → 面板就绪 |
隐私与数据使用
- 插件层:插件不含 DSH 实现,经本机 HTTP(S) 访问 DSH——默认走本机回环,可按设置改为本机其他绑定地址;插件自身外网请求只有你主动触发的(克隆 DSH、检查更新)。无遥测、无第三方中转。
- DSH 层:DSH 是 AI agent 框架,执行任务时按需发起外网请求(模型 API、工具/网页),内容取决于任务本身。
- 数据流向由你掌控:模型请求发往你配置的 provider(默认 DeepSeek 官方 API;OpenAI-completions/Responses、Anthropic-messages,或本地模型如 Ollama/vLLM,此时数据不出本机);Vault 索引、会话记录与 API key 均存本机。
- 局域网暴露:绑定非回环地址会把 DSH 暴露到你的网络,须启用 https 且仅在可信网络使用。
故障排查
| 症状 / 报错原文 | 原因 | 修复 |
|---|---|---|
| 面板打不开 | 工作目录不对、pnpm 不在 PATH、端口被占用,或服务地址/协议与运行实例不一致 |
错误视图给出原因与可复制的手动启动命令;同时核对服务地址与 dsh web --host 一致 |
spawn dsh ENOENT /「找不到 dsh」 |
Windows 下 npm 系 .cmd shim 无法被 Node 直接执行;Linux/macOS 下 Obsidian 的 PATH 里没有 Node/pnpm 目录 |
插件已内置 Windows cmd.exe 包装,其他平台会合并登录 shell 的 PATH;重载插件(彻底重启 Obsidian)。Linux 仍失败时改为全局安装 Node(NodeSource),或 nvm alias default 22 后重启 Obsidian |
EADDRINUSE / 端口 3080 被占用 |
残留 DSH 进程占着端口 | 设置 →「快捷操作」→「重启服务」 |
| 「桥接未就绪,改为直接发送」 | 桥接脚本尚未注入面板 | 设置 →「快捷操作」→「重启服务」(插件更新后先彻底重启 Obsidian) |
| DSH 升级后聊天记录缺失 / 某个会话打不开 | DSH 各版本间会话格式漂移 | 设置 →「快捷操作」→「会话修复」→「备份并修复」;格式更旧的会话直接打开由 DSH 自行迁移 |
升级/重启后 dsh web authentication required |
启动 token 每进程重新生成,缓存的是旧凭证 | 「重启服务」,面板会按新凭证重载 |
DSH 升级到插件尚未适配的新版本后内嵌面板不可用(iframe 里是 dsh web authentication required) |
插件的嵌入适配还没跟上该版本(如 0.2.2 把首页鉴权改成了 Fetch 请求) | 不可用页面上有「回退到适配版本 DSH」:确认后自动安装已验证版本并重启服务;期间可先用「在浏览器打开 DSH」 |
自签名证书未受信任(DEPTH_ZERO_SELF_SIGNED_CERT / UNABLE_TO_VERIFY_LEAF_SIGNATURE) |
证书未进系统信任根,或未在设置里填证书 PEM | 导入系统信任根(Windows「受信任的根证书颁发机构」;macOS 钥匙串「始终信任」;Linux update-ca-certificates 加 NSS 用户库,见上方「Linux 说明」),并把同一份 PEM 填进「TLS 证书 PEM」 |
| Linux:生成 HTTPS 配置后面板仍报证书错误 | Linux 的 Electron/Chromium 校验 NSS 用户库(~/.pki/nssdb),只做系统信任不够 |
按成功弹窗的两条命令执行(先 update-ca-certificates,再 certutil -d sql:$HOME/.pki/nssdb -A …),然后重启 Obsidian |
ERR_TLS_CERT_ALTNAME_INVALID / 证书 SAN 不含所填地址 |
证书是给别的主机名签发的 | 用你填写的地址(如 192.168.1.5、主机名)重签并把地址写入 SAN,或改用回环地址 |
| 手机装完 CA 后仍提示证书不受信任 | iOS:描述文件装了但没在「证书信任设置」里打开开关;安卓:证书装成了 VPN/其它类型,或只进了用户凭据而浏览器仍校验系统库;另外每次「生成并填入」都会换新证书,旧 rootCA.pem 会失效 | iOS:设置 → 通用 → 关于本机 → 证书信任设置 → 打开该根证书;安卓:重装为「CA 证书」(不是 VPN),并确认手机时间正确;重新生成后要把桌面最新的 rootCA.pem 再装一次 |
| 切到局域网 HTTPS 地址后 Obsidian 面板白屏 | Windows 信任库里没有该根证书(旧版本或自动导入失败)——浏览器可以「继续访问」,iframe 没有这个入口 | 2.9.2+ 会自动导入;否则手动把桌面 rootCA.pem 装入当前用户「受信任的根证书颁发机构」,再重启 Obsidian |
| 恢复默认端点后,外部浏览器标签页仍是旧的局域网 https 地址 | 插件无法改写别的标签页 URL,面板会自动刷新但外部标签页不会 | 关闭该标签页,用「在浏览器打开 DSH」重新打开默认地址(面板已自动切回 127.0.0.1) |
| 更新 DSH 时进度条停着好几分钟不动 | npm 要把约 1.1 GB、9 万多个文件写进全局目录——本机缓存全热的离线安装仍需 688 秒,网络不是瓶颈 | 不是卡死:弹窗现在显示已用时,并预先说明「通常 5–12 分钟」;单个 CDN 包卡顿改为 120 秒超时后重试(不再干等 7 分钟) |
| 手机用一段时间后连不上 | 电脑进入了睡眠/休眠(手机只能访问运行中的 DSH) | 手机使用期间关闭睡眠:设置 → 系统 → 电源和电池 → 屏幕和睡眠 → 「从不」;笔记本同时关闭「合盖睡眠」或保持插电 |
| 生成时提示「未找到本机局域网 IPv4 地址」 | 本机没有带私有 IPv4 的 Wi-Fi / 有线网卡(仅热点、仅 VPN,或网卡都处于内部状态) | 连上局域网后重试;或保持回环配置,自行签一张 SAN 含手机可达 IP 的证书 |
| 选了 https,服务仍以 http 启动 | 证书或私钥为空,或启动命令里已写了冲突的 TLS 参数 | 补全两项 TLS 设置(插件会把 --tls-cert/--tls-key 补进启动命令);把自己写的冲突参数删掉 |
启动时报 unknown option '--host' / '--tls-cert' |
本机 DSH 低于 0.2.1-rc.2,尚无这些参数 | 升级 DSH;升级前把服务地址/协议保持默认回环 + http(自行在命令里写这些 flag 也要先升级) |
自定义 --host 后插件识别不到 |
设置里的服务地址没同步改 | 在「服务地址」填同一个地址 |
填完远程访问配置后服务起不来、「在浏览器打开」仍是 http://127.0.0.1:3080 |
启动命令是检测写入的默认形态(如 dsh web --port {port} --no-open),2.9.1 及更早按原样使用,导致服务地址/TLS 设置被忽略 |
升级到 2.9.2+(自动补 --host / --tls-cert / --tls-key)后重启服务;或清空「启动命令」再重启(也可自己把这些参数写进命令) |
| 用户自己在终端启动的 DSH 无法用于面板 | 嵌入 token 只能从插件拉起的进程日志捕获 | 插件能识别它并在浏览器打开;内嵌面板需由插件拉起服务——用「重启服务」接管端口 |
Could not resolve host / 更新失败 |
github.com 被墙或不稳定 | 填「更新镜像地址」,或检查网络 |
| npm 全局安装收尾挂起 | 该包的已知 npm 行为 | 以安装后 package.json 的版本为准验证,而非控制台输出 |
架构与开发
src/
├── main.ts · settings.ts · view.ts # 入口与命令;设置页;iframe 面板
├── service-endpoint.ts # 服务地址 / 协议 / TLS 端点
├── cert-gen.ts · mobile-access-modal.ts # 自签证书生成;远程访问配置弹窗
├── service-manager.ts # 探活 / 启动 / 重启,清理端口占用
├── dsh-api.ts · bridge.ts # 本机 RPC 客户端;官方扩展缝 + 桥接独立包
├── aed.ts · installer.ts · updater.ts # dsh-fix 安全模式抢救;一键安装;更新检查
├── session-repair*.ts · startup-profiler.ts · changelog.ts # 会话修复 / 启动打点 / 更新日志
└── i18n.ts · win-exec.ts # 中英词典;Windows .cmd 包装
npm run dev # esbuild 监听模式
npm run build # 生产构建并安装到 .obsidian/plugins/dsh-harness
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 安装包目录> # 会话漂移修复端到端
node scripts/verify-endpoint-tls.mjs # 隔离 home:https + IPv4/IPv6 端点端到端
python scripts/sandbox_ui_test.py # 真实 iframe UI 检查(Playwright + Chrome)
致谢
感谢 DeepSeek 与 Obsidian 开源团队——开放、共享的互联网精神让这样的工具得以诞生;感谢 Claudian,本插件「框选发送」的交互灵感源自其设计。感谢 @chichilatte:定位并修复「首装/清理临时目录后拿不到启动令牌」导致的永久 401。