Alvinpro/DSH-Launcher

这是什么 / What it is

一个用 Rust 编写的单文件 Windows OS 启动器,用于启动 dsh(DeepSeek Harness)Web UI——免 WebView2、零运行时依赖、体积仅几百 KB。双击即起，关闭浏览器即自动清理整个进程树——不用守着终端、不会残留 node 进程占端口、全程无黑窗闪烁。

A single-file Rust Windows OS launcher for the dsh (DeepSeek Harness) web UI — no WebView2, no runtime deps, just a few hundred KB. Double-click to start; close the browser and the whole process tree is torn down — no terminal to babysit, no leftover node processes holding the port, no console flash.

快速开始 / Quick start

1. 双击 dsh-launcher.exe —— 无需任何配置,默认以 dsh web 启动、端口 3080。
Double-click dsh-launcher.exe — no config file needed. Defaults: dsh web on port 3080.
2. 需要自定义?命令行参数(可选) / Customize via command line (optional):
dsh-launcher.exe --port 8899 --args "web --port 8899"
3. 关闭浏览器:dsh 自动停服、零残留。(浏览器本就在用?托盘图标右键退出。)
Close the browser: dsh shuts down, zero residue. (Browser already open? Right-click the tray icon to exit.)

| 命令行参数 / CLI option | 说明 / Description |
| --- | --- |
| --url  | 服务地址 / Service URL(默认 http://127.0.0.1:3080) |
| --port  | 就绪探测端口 / Readiness probe port(默认取 url 端口) |
| --timeout  | 就绪等待超时 / Readiness timeout(默认 30s) |
| --package  | npm 包名 / npm package for npx(默认 dsh) |
| --args  | dsh 启动参数 / dsh launch args, overrides config(覆盖配置文件) |
| --dsh-path  | 显式 dsh 入口,跳过解析链 / Explicit dsh entry |
| --check | 仅验证解析链 / Validate the resolution chain only |
| -h, --help | 用法说明弹窗 / Usage dialog |

config.json 是可选的 —— 只写需要覆盖的字段。优先级:命令行 > config.json > 内置默认。需要固定端口/固定参数时,复制 config.example.json 起步。
config.json is optional — only override the fields you need. Precedence: command line > config.json > built-in defaults. Copy config.example.json to start one if you need a fixed port / permanent args.

{
"dsh_path": "",
"url": "http://127.0.0.1:8899",
"port": 8899,
"timeout_secs": 40,
"package": "dsh",
"args": ["web", "--port", "8899"]
}

| 字段 / Field | 说明 / Description | 默认 / Default |
| --- | --- | --- |
| dsh_path | 显式 dsh 入口路径,设置后跳过其余解析链 / Explicit dsh entry; skips the rest of the chain when set | 空(自动解析) / empty |
| url | 服务就绪后浏览器打开的地址 / URL opened in the browser once ready | http://127.0.0.1:3080 |
| port | 就绪探测端口(不设则从 url 解析) / Readiness probe port (falls back to url port) | url port |
| timeout_secs | 最大等待超时;npx 首次拉取自动放宽到 60s / Max wait; auto-extended to 60s for first npx pull | 30 |
| package | npm 包名(npx 拉取用) / npm package name (used by npx) | dsh |
| args | 透传给 dsh 的启动参数 / Extra args passed to dsh | [] |

dsh 即 DeepSeek Harness;Web UI 入口为 dsh web(即 dsh --profile web)。端口等参数通过 args 传入。
dsh is DeepSeek Harness; the web UI entry is dsh web (a.k.a. dsh --profile web). Pass port etc. via args.
dsh 是 DeepSeek Harness,Web 界面入口为 dsh web(等价 dsh --profile web),端口等参数按需透传。

Only validate the resolution chain, don't actually start / 仅验证 dsh 命令解析链,不实际启动
.\dsh-launcher.exe --check

工作原理 / How it works

1. 探测 / Probe: 端口已就绪?直接开浏览器退出,绝不拉第二个进程。
Service already running? Open the browser and exit — never a second instance.
2. 解析 / Resolve: 解析链:配置路径 → vendor\dsh\ 离线包 → PATH 中的 dsh → npx --yes dsh 自动拉取,dsh --version 校验可用性。
Config path → vendor\dsh\ offline bundle → dsh on PATH → npx --yes dsh, validated with dsh --version.
3. 拉起 / Launch: CREATE_NO_WINDOW 隐藏窗口拉起,立即绑定 JobObject。
cmd.exe /C hidden with CREATE_NO_WINDOW, immediately bound to a JobObject.
4. 就绪 / Ready: TCP 连通 + HTTP 响应双重校验(端口通 ≠ 服务就绪),就绪后用 ShellExecuteExW 前台唤起浏览器。
TCP connect + HTTP GET double check (port open ≠ ready), then ShellExecuteExW opens the browser foreground-activated.
5. 联动 / Linked: 关闭拉起的浏览器 → 自动关服;浏览器本就开着 → 降级常驻,托盘图标退出。
Freshly launched browser closes → dsh auto-shuts-down; browser already running → resident mode, exit via tray icon.
6. 清理 / Cleanup: 任何退出方式(正常 / 托盘 / 被强杀),JobObject 连根终止进程树,零残留。
Every exit path (normal / tray / force-killed) — JobObject kills the whole process tree, zero residue.

特性 / Features

- 自动发现 / Auto-discovery: 解析链自动发现 dsh:配置路径 → 离线 vendor\dsh\ → PATH → npx,免全局安装
Config path → offline vendor\dsh\ → PATH → npx, no global install required
- 真实就绪探测 / Real readiness probe: TCP 连通 + HTTP 响应双重校验,自适应退避 + 超时保护
TCP + HTTP double check with adaptive backoff and timeout guard
- 零残留 / Zero residue: JobObject KILL_ON_JOB_CLOSE:正常 / 托盘 / 任务管理器强杀,进程树全部自动终止
JobObject KILL_ON_JOB_CLOSE — normal, tray, or task-manager exit all terminate the full tree
- 浏览器联动 / Browser-linked lifecycle: 关闭拉起的浏览器 → 自动停服;共享实例降级常驻(托盘退出),不误杀正在用的窗口
Close the launched browser → auto shutdown; shared instance → resident mode (tray exit), never kills your windows
- 调用系统默认浏览器 / Opens your default browser: 用系统默认浏览器打开 dsh web(Chrome / Edge / Firefox / 你惯用的任何浏览器),不捆绑浏览器、不强绑内核;浏览器联动自动识别常见浏览器进程
ShellExecuteExW respects the OS default browser (Chrome / Edge / Firefox / whatever you use) — no bundled browser, no hardcoded engine; browser-link lifecycle tracks common browsers
- 无窗体验 / Silent UX: GUI 子系统无控制台、无黑窗闪烁;日志落盘 dsh-launcher.log,出错弹窗提示
GUI subsystem, no console window, no black-window flicker; log to dsh-launcher.log, errors pop a dialog
- 异常守护 / Failure guards: 探测期 dsh 提前退出立即报错(退出码 4);超时自动清理(退出码 3)
dsh dies during probing → report immediately (exit 4); timeout → cleanup (exit 3)
- 单文件:约 360 KB 的 exe,内嵌应用图标,零运行时依赖
- 不依赖 WebView2:纯 Win32 托盘 + 对话框——无需 Edge/WebView2 运行时,无需 100+ MB 的 webview 负载,适用于任何 Windows 7+

退出码

| 码 | 含义 |
| --- | --- |
| 0 | 正常退出 |
| 1 | 配置错误 / dsh 启动失败 |
| 2 | 端口已打开但 HTTP 异常 |
| 3 | 等待超时 |
| 4 | dsh 提前/意外退出 |
| 5 | dsh 解析/自动安装失败(包括无 npm) |

通过 dsh 插件安装

DSH-Launcher 也以 dsh 插件形式发布(仅限 Windows):dsh plugin add 一次成功,零摩擦——exe 随包携带(仓库 dist/dsh-launcher.exe,无生命周期脚本,绝不触发 pnpm ≥10 的构建脚本门禁)。

安装(一次性;exe 随包进入 node_modules)
dsh plugin --profile web add github:alvinpro/dsh-launcher

安装后 exe 已就位(node_modules\dsh-launcher\dist\dsh-launcher.exe)。桌面快捷方式——直接指向捆绑的 exe(零复制、零残留)——可以通过两种方式创建。它仅在首次运行时创建一次;之后 dsh web 启动时不会再重新创建,即使你自己删除了快捷方式也是如此(要恢复:重新运行 dsh plugin add,或删除标记文件 node_modules\dsh-launcher\.shortcut-created 并重启 dsh):

方式 1(立即):一键脚本——add + 初始化一步完成,快捷方式立即出现
powershell -ExecutionPolicy Bypass -File scripts\install-plugin.ps1

方式 2(自动):只需启动 dsh web——插件的 apply() 在首次运行时创建快捷方式
dsh --profile web

开发/调试:直接从本仓库安装
dsh plugin --profile web add .

卸载(移除插件,然后删除桌面快捷方式——无需清理其他内容)
dsh plugin --profile web remove dsh-launcher
Remove-Item "$([Environment]::GetFolderPath('Desktop'))\DSH Launcher.lnk" -Force
原理:仓库根是一个纯 JS 的 dsh bundle(声明 dsh.bundle.patch),无 lifecycle 脚本,所以
pnpm ≥10 不会拦截,add 一次成功;exe 打进包内 dist/(add 时随 git clone 自带,零下载)。
桌面快捷方式由 install.js 创建并直接指向包内 exe(不复制到 AppData,dsh plugin remove
后 exe 随包删除,无残留),首次创建后写入 .shortcut-created 标记,后续启动直接跳过。

离线分发 / 内网离线分发

无网环境无法走 npx:把 dsh 包拷入 exe 同目录 vendor\dsh\(支持 dsh.exe / dsh.cmd / bin\dsh.exe / bin\dsh.cmd / main.js),解析链自动命中。

构建 / 构建

cargo build --release
产物 / 产物: target\release\dsh-launcher.exe

前置要求 / 前置要求: Rust 稳定版工具链(edition 2024)/ Rust 稳定版工具链(edition 2024)。

cargo test --release

实测通过 / 实测通过: 完整启动(浏览器自动打开、无黑窗闪烁——二次稽核)、托盘退出、关闭浏览器自动停服、握手降级(共享实例 → 常驻)、强杀清理(进程归零、端口释放)、提前退出检测、超时清理、shim 解析。

设计决策 / 设计决策

- 为什么不用 Tauri 2.0 / 为什么不用 Tauri 2.0: 启动器无 UI 需求,WebView 只会徒增体积与依赖;托盘、弹窗用原生 Win32 即可。真需要界面时按设计文档的升级路线迁移,进程管理代码原样复用。
- where vs where.exe: PowerShell 里 where 是 Where-Object 别名,检测命令必须用 where.exe dsh。
- npm shim 三件套 / npm shim 三件套: dsh(无扩展名)、dsh.cmd(可执行)、dsh.ps1(仅 PowerShell)——启动器只认 .cmd/.exe。

许可证 / 许可证

MIT 许可证——详见 LICENSE / MIT 许可证——详见 LICENSE