笔记内嵌控制台 hjxcloud-tech/dsh-harness

DeepSeek Harness for Obsidian

状态：已发布 · 仅桌面端（Windows / macOS）· English · 中文

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

Obsidian 桌面端插件，把原生 DeepSeek Harness（DSH）Web UI 嵌入你的仓库。它不改动 DSH 源码（走 DSH 官方扩展接缝），随 DSH 演进持续可用，无需命令行，默认通过本地回环访问 DSH。

功能

- 一键配置 —— 安装或检测 DSH，自动补装缺失的工具（git / Node.js / pnpm），并显示实时进度条。
- 静默运行 —— DSH 服务在后台启动，不弹控制台窗口；崩溃能被检测到，一键重连。
- 原生 Web UI —— iframe 里就是真正的 DSH 界面，支持 0.5×–2.0× 缩放，样式跟随主题。
- 双向桥接 —— 在笔记里选中文字，会向 DSH 对话注入一行隐式信息（精确到行:列 + 字数，不含原文），DSH 据此自行读取并编辑该文件；DSH 产物落在仓库内，点一下就能在 Obsidian 打开。
- 快捷键穿透与自愈 —— Obsidian 全局快捷键在面板内照常生效；DSH 或插件更新后，桥接与启动凭据自动刷新。
- 多配置档共存 —— 把面板绑定到另一个 DSH 配置档（例如 test），与桌面应用的 web 并存；插件按 web 模板构建它，用独立端口启动，且只重启自己启动的进程。
- 版本感知更新，只用官方包 —— 一键安装/更新，按你选的通道（stable / pushed rc & beta / alpha）取 DSH 官方最新版；兼容性说明跟随已验证范围；同名第三方 npm 包绝不会被误认成 DSH。
- 安全升级与会话修复 —— 更新前停掉所有 DSH 进程（Windows 文件锁），备份会话并重新校验；只读检查器加一键「备份并修复」，处理格式漂移导致读不了的会话。
- 静默兼容性判定 —— 版本、实时桥接检查，以及超出已验证上限的只读接缝自检，都在状态行和设置里以纯文本显示，绝不弹对话框。
- AED 救援 —— DSH 无法启动时，一键运行 dsh-fix（独立的 npm 全局命令行工具，持续保持最新），进入安全模式把它救回来，然后验证启动结果并给出修复建议；它覆盖的症状列在设置行「What it can fix」弹窗里，会话无法读取的情况归 Session repair 管。
- 自定义端点与原生 HTTPS —— 把插件指向 DSH 绑定的本地地址（IPv4/IPv6，可选通过 --tls-cert/--tls-key 启用 https）；细节见 Key settings。
- 一键手机访问（Service runtime 分组顶部）—— 生成本地 HTTPS 证书，填好局域网主机 / 协议 / 证书 / 密钥路径，并把 rootCA.pem 放到桌面，附带预检风险、iOS/Android 设置步骤，以及一键重置端点设置。手机使用期间，电脑要保持开机、不休眠。
- 错误讲人话，启动更快 —— 失败时给出通俗原因，附一键重连 /「Ask AI how to fix」；能力探测结果会缓存，启动耗时日志在 Settings → Diagnostics。

环境要求与安装

- Obsidian 桌面版 v1.7.2+（Windows / macOS）。
- DSH：插件可以帮你装（git / Node.js / pnpm 自动安装；官方源被墙时回退镜像）。已验证范围：DSH 0.1.5-rc.1 ~ 0.2.1-rc.4；0.1.2–0.1.4 已知不兼容，超出范围不做任何承诺。
- 一个供 DSH 使用的模型 API key（默认：DeepSeek API；任何 OpenAI/Anthropic 兼容端点都行，包括本地模型）。
- 三种安装方式：从社区商店安装（Settings → Community plugins → Browse → 搜索 "DeepSeek Harness"）；从已有的本地 DSH 安装（Settings →「One-click detect & configure」）；从源码安装（npm install && npm run build，装到 .obsidian/plugins/dsh-harness/）。

Key settings

| 设置项 | 默认值 | 说明 |
| Interface language | Follow Obsidian | 中文 / 英文；其他系统语言回退到英文 |
| Service address | 127.0.0.1 | 面板连接的服务端点主机 —— 必须与 dsh web --host 一致：本地 IPv4 或 IPv6 字面量（127.0.0.1、192.168.1.5、::1），不带 scheme/端口/通配符；非回环地址会把 DSH 暴露到局域网（仅限 https 和可信网络） |
| Service port | 3080 | DSH Web GUI 监听的端口（与上面的地址、下面的协议一起构成端点） |
| Service protocol | http | http 或 https；https 需要下面两个证书路径（DSH 0.2.1-rc.2 的 --tls-cert / --tls-key） |
| HTTPS 证书 PEM | 空 | 证书 PEM 的路径（不是内容）。作为 --tls-cert 传给 DSH，同时用作插件的信任锚，所以必须是包含叶子证书的服务器证书链（把私有 CA 拼进同一个文件；自签名单证书本身就是自己的锚）。如果自定义命令自己提供了 --tls-cert，这里可以改为指向签发 CA |
| HTTPS 私钥 PEM | 空 | 私钥 PEM 的路径（不是内容），与证书配对；作为 --tls-key 传入 |
| DSH 配置档 | web | 选一个已有配置档，或输入新名字（会先询问）；非 web 配置档从 web 模板构建，有自己的桥接和端口；内置名字（acp / headless / sdk / sdk-minimal）会被拒绝 |
| 自动启动 / 分离进程 | 开 / 开 | 打开面板时若没有服务在运行就启动服务；Obsidian 退出后让 DSH 继续运行 |
| 启动超时 | 300s | 自动启动后等待服务的最大时长（60–600s）；首次启动可能要 1–2 分钟 |
| 启动命令 / 工作目录 | 空 | 留空 = 插件用上面的端点拼出命令；填了值就保留你自己的参数，插件只补上缺失的 --host / --tls-cert / --tls-key（你已写好的参数优先） |
| 一键安装 DSH | 按钮 | 依赖 → 克隆（实时百分比）→ 安装（进度条）→ 配置；克隆 URL 可以切换到代理镜像 |
| DSH 更新 | 官方发布 | 默认在所选通道上最多每 24 小时自动检查一次：仅稳定版 / 跟随官方发布（rc 和 beta）/ 包含 alpha；只有版本出现在官方仓库的 GitHub Release 后才会推送，所以 npm 先收到的预发布版（next 标签）不会被推送；查不到 Release 时回退到基于 npm 的检查；手动检查和自定义镜像 URL 在同一行，且绝不会静默安装 |
| 当前兼容性 | 行 | 检测到的版本和结论（支持 ✓ / 已知不兼容 ✗ / 比已验证版本旧或新 ⚠ / 缺少桥接 / 无法验证），带「立即重新检查」；只显示文字，不弹对话框 |
| 会话修复 | 按钮 | 用 DSH 自己的格式链做只读扫描；备份并修复当前格式拒绝的会话（旧格式会话留给 DSH 迁移） |
| 插件信息 | 行 | 插件版本、应用内更新日志和 DSH 兼容性弹窗、「检查插件更新」、GitHub 仓库；DSH 更新日志链接打开它的 Releases 页面 |
| 底部留白 | 20px | Obsidian 状态栏遮住面板时，面板下方的空白（0–30px） |
| 快捷键穿透 | 开 | 焦点在 DSH 面板内时，Obsidian 全局快捷键仍然有效 |
| 双向桥接 | 开 / 自动发送 | 笔记选中 → DSH 聊天（隐式信息行）；DSH 产物 → Obsidian：取消 / 自动发送 / 右键发送 |
| DSH 急救 | 按钮 | 下载并运行 dsh-fix 进入安全模式，抢救无法启动的 DSH，然后验证启动结果；内联的「What it can fix」链接列出可修复的症状 |
| 移动端访问设置 | 按钮 + 链接 | 位于 Service runtime 分组顶部：Generate & fill 生成自签名 HTTPS 证书（Desktop rootCA.pem），自动安装到当前 Windows 用户的受信任根证书（无需管理员权限；macOS 需手动操作），并填入主机（LAN IPv4）/ 协议 / 证书 / 密钥；「How it works」链接列出适用场景、要求、限制（包括保持电脑不休眠）以及完整的手机连接流程与 token 获取方式（在 Quick actions 中使用 Copy token link——浏览器重定向后会从地址栏丢掉 ?token=——或读取 dsh-web-out-<port>.log）；Reset endpoint defaults 恢复为 127.0.0.1 / http / 空路径，自动重启服务并重新加载面板，同时保留证书文件和已安装的信任（已打开的外部浏览器标签页需关闭后重新打开） |
| 连接地址 | 行 + 按钮 | 显示插件实际连接的端点（http(s)://host:port），并执行只读的 TCP + GET / 检查：未运行 / 超时 / 证书不受信任、不匹配或已过期（附带原始 TLS 错误码） |
| 诊断 | 日志 | 启动耗时日志（最近 5 次）：插件加载 → 服务探测 → 服务启动 → 面板就绪 |

隐私与数据使用

- 插件层——插件不含 DSH 实现，通过本地 HTTP(S) 访问 DSH：默认走本地回环，也可用你配置的其他本地绑定地址。它只发起你触发的出站请求（克隆 DSH、检查更新）。无遥测，无第三方中转。
- DSH 层——DSH 是 AI 智能体框架；运行任务时它会按需发起出站请求（模型 API、工具/网页访问），发送内容取决于任务本身。
- 你的数据，你的服务商——模型请求发往你配置的服务商（默认 DeepSeek API；OpenAI-completions/Responses、Anthropic-messages，或 Ollama/vLLM 等本地模型，数据不出你的机器）。Vault 索引、会话历史和 API 密钥都留在本地。
- LAN 暴露——服务地址不是回环地址时，DSH 会暴露到你的网络；请使用 https，且只在可信网络中使用。

故障排查

| 症状 / 错误 | 原因 | 修复 |
| 面板打不开 | 工作目录错误、缺少 pnpm、端口被占用，或服务地址/协议与运行实例不匹配 | 错误视图会显示原因和可直接复制的启动命令；让服务地址与 dsh web --host 保持一致 |
| spawn dsh ENOENT / "dsh not found" | Node 无法解析 Windows 的 .cmd shim | 插件通过 cmd.exe 包装 npm 风格命令；重新加载插件（完全重启 Obsidian） |
| EADDRINUSE / 端口 3080 被占用 | 残留的 DSH 进程占着端口 | 设置 → 快捷操作 → 重启服务 |
| 「Bridge not ready, sent directly instead」 | Bridge 脚本还没注入面板 | 重启服务（插件更新后，先彻底重启 Obsidian） |
| DSH 升级后聊天记录丢失，或某个会话打不开 | DSH 各版本之间会话格式有差异 | 设置 → 快捷操作 → 会话修复 → 「备份并修复」；旧格式会话留给 DSH 在打开时自行迁移 |
| 升级或重启 DSH 后出现 dsh web authentication required | 启动 token 按进程生成，缓存里的已经过期 | 重启服务；面板会用新凭据重新加载 |
| 自签名证书不受信任（DEPTH_ZERO_SELF_SIGNED_CERT / UNABLE_TO_VERIFY_LEAF_SIGNATURE） | 证书不在系统信任库中，且/或插件没配置证书 PEM | 导入系统信任根（Windows「受信任的根证书颁发机构」；macOS 钥匙串「始终信任」），并把同一份 PEM 粘贴到 TLS certificate |
| ERR_TLS_CERT_ALTNAME_INVALID / 证书 SAN 里没有这个地址 | 证书是给别的主机名签发的 | 重新签发，把你实际输入的地址（192.168.1.5、主机名……）写进 SAN，或改用回环地址 |
| 手机上装完证书仍提示不受信任 | iOS：描述文件装了，但没在「证书信任设置」里启用。Android：文件装成了 VPN/其他配置档，或只装进了用户凭据，而浏览器仍校验系统存储。另外：每次「生成并填充」都会换掉证书，旧的 rootCA.pem 就对不上了 | iOS：设置 → 通用 → 关于本机 → 证书信任设置 → 启用根证书。Android：以「CA 证书」（不是 VPN）重新安装，并检查手机时钟。重新生成后，重发最新的 Desktop rootCA.pem |
| 切到局域网 HTTPS 地址后 Obsidian 面板一片空白 | Windows 信任库缺少 rootCA（插件版本较旧，或自动安装失败）——浏览器会提供「仍然继续」，iframe 不会 | 2.9.2+ 会自动安装；否则把 Desktop 的 rootCA.pem 导入当前用户的「受信任的根证书颁发机构」，再重启 Obsidian |
| 手机过一会儿就断连 | 电脑睡眠或休眠了——手机只能连到运行中的 DSH | 手机使用期间关掉睡眠：设置 → 系统 → 电源和电池 → 屏幕和睡眠 → 从不；笔记本还要关掉「合盖睡眠」，或一直插着电 |
| 执行「重置端点默认值」后，外部浏览器标签页仍显示旧的 https 局域网地址 | 插件改不了浏览器标签页的 URL，只会重新加载 Obsidian 面板 | 关掉那个标签页，用「在浏览器中打开 DSH」重新打开默认地址（面板已自动切回 127.0.0.1） |
| 生成时报「No LAN IPv4 address found」 | 这台机器没有带私有 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（带这些参数的自定义命令只有升级后才生效） |
| 自定义了 --host，插件却仍探测 127.0.0.1 | 服务地址设置没改 | 在「服务地址」里填同一个地址 |
| 填完手机访问配置后服务起不来，「Open DSH in browser」仍显示 http://127.0.0.1:3080 | 启动命令是探测出来的默认值，比如 dsh web --port {port} --no-open；≤2.9.1 会原样使用它，host/TLS 设置就被悄悄忽略了 | 2.9.2+ 会自动补上缺失的 --host / --tls-cert / --tls-key —— 更新插件并重启服务。在 2.9.1 或更早版本上，先清空「启动命令」字段（或自己加上这些参数）再重启 |
| 在终端里启动的 DSH 实例在面板里用不了 | 嵌入 token 只从插件启动的进程里获取 | 插件仍能探测到它并在浏览器里打开；嵌入面板需要插件启动的服务 —— 「重启服务」会接管端口 |
| Could not resolve host / 更新失败 | github.com 被墙或网络不稳 | 设置更新镜像 URL，或检查网络 |
| npm 全局安装卡在最后 | 这个包上 npm 的已知行为 | 读已安装包的 package.json 版本号来确认，别信控制台输出 |

架构与开发

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)

致谢感谢 DeepSeek 与 Obsidian 开源团队——互联网开放共享的精神，让这样的工具成为可能；也感谢 Claudian，它「选中即发送」的设计启发了本插件的桥接。

一个桌面插件，把 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）。
- DSH 本体：插件可一键安装（git / Node.js / pnpm 缺失自动补齐，官方源被墙走镜像）。实测适配区间：DSH 0.1.5-rc.1 ~ 0.2.1-rc.4；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/）。

主要设置
| 设置 | 默认 | 说明 |
| 界面语言 | 跟随 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 产物 → Obsidian：取消 / 自动发送 / 右键发送 |
| AED for DSH | 按钮 | 下载并运行 dsh-fix 进入安全模式抢救起不来的 DSH，完成后校验启动；行内「适用症状说明」链接列出可抢救的症状 |
| 手机访问配置 | 按钮 + 链接 | 位于「服务运行」分组最上方：「生成并填入」生成自签 HTTPS 证书（桌面 rootCA.pem），Windows 下自动装入当前用户「受信任的根证书颁发机构」（免管理员；macOS 需手动），并填好服务地址（局域网 IPv4）/ 协议 / 证书 / 私钥；行内「使用说明」列出适用场景、前置要求与限制（含电脑需保持开机、不睡眠），并含手机连接全流程与 token 获取方法（用快捷操作里的「复制 token 链接」按钮——浏览器跳转后地址栏会丢掉 ?token=；或读启动日志 dsh-web-out-<端口>.log）；「恢复默认端点」退回 127.0.0.1 / http / 空路径，自动重启服务并刷新面板，证书文件保留、已安装的信任不撤销（外部浏览器里已打开的旧页面需手动关闭重开） |
| 连接地址 | 行 + 按钮 | 显示插件实际会连的端点（http(s)://host:port），并做一次只读 TCP + GET / 检查：未启动 / 超时 / 证书未受信任、地址不匹配或已过期（附原始 TLS code） |
| 诊断 | 日志 | 启动耗时记录（最近 5 次）：插件加载 → 服务探测 → 服务启动 → 面板就绪 |

隐私与数据使用
- 插件层：插件不含 DSH 实现，经本机 HTTP(S) 访问 DSH——默认走本机回环，可按设置改为本机其他绑定地址；插件自身外网请求只有你主动触发的（克隆 DSH、检查更新）。无遥测、无第三方中转。
- DSH 层：DSH 是 AI 智能体框架，执行任务时按需发起外网请求（模型 API、工具/网页），内容取决于任务本身。
- 数据流向由你掌控：模型请求发往你配置的服务商（默认 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 直接执行 | 插件已内置 cmd.exe 包装；重载插件（彻底重启 Obsidian） |
| EADDRINUSE / 端口 3080 被占用 | 残留 DSH 进程占着端口 | 设置 →「快捷操作」→「重启服务」 |
|「桥接未就绪，改为直接发送」 | 桥接脚本尚未注入面板 | 设置 →「快捷操作」→「重启服务」（插件更新后先彻底重启 Obsidian） |
| DSH 升级后聊天记录缺失 / 某个会话打不开 | DSH 各版本间会话格式漂移 | 设置 →「快捷操作」→「会话修复」→「备份并修复」；格式更旧的会话直接打开由 DSH 自行迁移 |
| 升级/重启后 dsh web authentication required | 启动 token 每进程重新生成，缓存的是旧凭证 |「重启服务」，面板会按新凭证重载 |
| 自签名证书未受信任（DEPTH_ZERO_SELF_SIGNED_CERT / UNABLE_TO_VERIFY_LEAF_SIGNATURE） | 证书未进系统信任根，或未在设置里填证书 PEM | 导入系统信任根（Windows「受信任的根证书颁发机构」；macOS 钥匙串「始终信任」），并把同一份 PEM 填进「TLS 证书 PEM」 |
| 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） | 手机使用期间关闭睡眠：设置 → 系统 → 电源和电池 → 屏幕和睡眠 → 「从不」；笔记本同时关闭「合盖睡眠」或保持插电 |
| 生成时提示「未找到本机局域网 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 包装 bash
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，本插件「框选发送」的交互灵感源自其设计。