dsh-desktop — DSH 桌面应用插件

把 DeepSeek Harness Web 界面（dsh web）封装成无浏览器元素的桌面应用：独立原生窗口、应用图标、自定义标题栏。点击桌面应用就是在后台调用 dsh web，但窗口里看不到地址栏、URL、命令、菜单和开发者工具。

本文档是插件安装说明（功能介绍 + 安装步骤）。产品整体介绍（含 exe 部署使用）见 README.OVERVIEW.md。

---

功能介绍

• 桌面壳：原生无边框窗口 + 自定义标题栏（拖动区 / 最小化 / 最大化 / 关闭），无任何浏览器元素。
• 一键启动：dsh web 侧边栏新增「桌面应用」入口，点击即弹出桌面窗口；也支持双击桌面快捷方式独立启动。
• 闭环跳转：网页版点「桌面应用」打开桌面壳；桌面壳内点「打开网页版」跳回浏览器（经系统默认浏览器打开同一服务地址），来回切换无阻碍。
• 服务自举：独立启动时若本地服务未运行，会隐藏地启动 dsh web（无控制台窗口，Windows 下不弹任何终端），就绪后自动加载；断线自动恢复。
• 单实例：重复打开只聚焦已有窗口。
• 托盘驻留：点窗口右上角 X（系统或自定义标题栏）不退出程序，而是最小化到右下角系统托盘后台驻留；点击托盘图标重新打开窗口，右键托盘菜单可「显示主窗口」或「退出」。
• 退出清理：独立启动时由桌面应用自启的 dsh web 服务会在应用退出时一并关闭，不留控制台窗口和孤儿进程；插件已运行的宿主服务不受影响。
• 信息隐藏：内部 URL 与 dsh web 命令只存在于进程参数与宿主内部，UI 永不展示；禁止弹窗/跳转、禁用开发者工具。
• 可配置：窗口尺寸、是否无边框、应用名可在 DSH 设置面板调整。
• Agent 集成：模型可通过 desktop_launch 工具直接打开桌面应用。
• 懒自举：Electron 运行时缺失时，首次点击自动补装，无需手动配置。

---

插件安装

前置要求：已安装 dsh 并运行 dsh web（插件模式用户本来就在用，无需额外准备）；本机 Node.js ≥ 22.19.0（推荐 24.18.0）。

1. 从插件市场安装（推荐）

# 国内网络强烈建议先设 Electron 镜像
$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
dsh plugin --profile web add @cheramvb/dsh-desktop

安装过程分两阶段：插件包本体（约 45 KB，秒下）+ Electron 运行时（zip 约 138 MB，解压后约 347 MB；若安装时未装上，首次点击会自动补装）。

2. 重启服务

dsh web

刷新浏览器后，侧边栏出现「桌面应用」入口，点击即弹出桌面窗口。

免重启热挂载（dsh web 保持运行）

# 1) 把包链接进 profile 的 node_modules（junction）
New-Item -ItemType Junction -Path "<profile>\node_modules\@cheramvb\dsh-desktop" `
  -Target "<插件目录绝对路径>"

# 2) 在 <profile>/cordis.patch.yml 插入行（几秒内热生效）
- insert:
    - id: desktop
      name: '@cheramvb/dsh-desktop'

刷新浏览器页面即出现入口。注意：不要与上面的 bundle 安装叠加（下次启动会报重复行 id）。

---

使用

插件版共提供 四种触发方式，任选其一即可打开桌面应用：

1. 左侧导航栏（推荐）

• dsh web 侧边栏出现「桌面应用」入口，点击即弹出桌面窗口（单实例，已打开则聚焦）。
• 桌面壳内侧边栏显示「打开网页版」→ 在系统默认浏览器中打开网页版（与网页版构成闭环，来回切换）。

2. 桌面快捷方式

插件包自带 desktop/create-shortcut.vbs，运行一次即在桌面创建「DeepSeek Harness」快捷方式（快捷方式指向 start-hidden.vbs，由它以隐藏控制台方式运行 node desktop/start.mjs）：

# 进入插件 desktop 目录（热挂载路径，根据自己的路径匹配 )
cd ".dsh\profiles\web\node_modules\@cheramvb\dsh-desktop\desktop"
wscript create-shortcut.vbs    # 无弹窗运行；想看结果提示用 cscript create-shortcut.vbs

• 桌面上生成 DeepSeek Harness.lnk，双击即可打开；图标取 desktop/icon.png。
• 注意：不要单独拷贝 vbs 使用——脚本以自身所在目录为基准定位 start-hidden.vbs / start.mjs。
• 前提：Node.js 需在 PATH 上；若 Electron 二进制缺失，快捷方式路径不会自动补装，需先手动 node <profile>\node_modules\electron\install.js。
• 不需要时直接删除桌面的 DeepSeek Harness.lnk 即可（脚本只创建这一个文件）。

3. Agent 打开

对话中说「打开桌面版 / 打开桌面应用」，模型会调用 desktop_launch 工具直接打开桌面应用。

4. 命令行（类 cmd）启动

# 直接跑插件里的启动器（服务未运行时自动隐藏启动 dsh web）
node "<插件目录>\desktop\start.mjs"

# 或用 profile 安装后生成的 bin（等价）
"<profile>\node_modules\.bin\dsh-desktop.CMD"

窗口行为（四种方式通用）：单实例；点 X 最小化到托盘驻留（不退出），托盘菜单可重新打开或退出；独立启动自启的 dsh web 随应用退出关闭；从插件启动时关闭窗口不影响宿主服务；断线自动隐藏重启并恢复。

---

插件与 exe 的关系（常见疑问）

exe 里并不包含插件代码。 electron-builder.yml 的 files 白名单只打包壳的 7 个文件（main.js / preload.js / splash.html / core.js / icon.js / package.json / icon.png），lib/（路由、工具、侧边栏按钮）不在 exe 里。exe 只是一个"空壳浏览器窗口"，网页内容永远是它连的 dsh web 现场提供的。

因此改功能/修复时的生效方式分三类：

改了什么	在哪生效	需要重打 exe 吗
lib/（插件代码：侧边栏按钮、路由、工具）	dsh web 每次加载页面时现场下发	否——刷新页面即生效（壳里也一样，它只是个浏览器）
desktop/（壳代码：main.js / preload.js 等）	壳进程，读的是插件目录源码	否——重启壳即生效
dist\ 里的 exe	只在你双击 exe 时才用到	⚠️ 分发前必须重打：exe 是打包那一刻的快照，旧 exe 不含新功能

一句话：插件模式下你跑的永远是源码，改完刷新/重启即可，不需要重打 exe；只有要把新功能带给"用 exe 的人"时，才需要 npm run build:exe 重新打包。

---

常见问题

现象	解决
Electron 下载慢/卡住	$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/" 后重装
首次点击长时间无反应/提示「未安装桌面运行组件」	首次点击会自动补装 Electron（按钮显示「正在安装桌面组件…」，约 1~4 分钟），完成后自动启动；补装失败时提示设置 ELECTRON_MIRROR 镜像，或手动执行 node <profile>\node_modules\electron\install.js
缓存目录不可写（EPERM ...\AppData\Local\electron）	设 $env:electron_config_cache = "<可写目录>"（小写）
窗口顶部被自定义标题栏遮挡	设置中关闭「无边框窗口」回退系统标题栏

---

安全说明

• /api/dsh-desktop/* 路由带回环信任围栏，局域网暴露的 dsh web 无法调用。
• 窗口禁止弹窗与外部跳转、禁用开发者工具，仅开放剪贴板与全屏权限。
• 内部 URL 与 dsh web 命令不展示在任何界面文案中。