DSH 采用“一切皆插件”的理念。在 Windows 环境下，直接启动 dsh web 往往面临依赖复杂、进程残留或窗口闪烁等问题。dsh-launcher 作为一个轻量级启动器，旨在解决这些问题，提供一个无需额外运行时、关闭浏览器即自动清理的启动方案。
这是什么¶
dsh-launcher 是一个用 Rust 编写的单文件 Windows OS 启动器，专门用于启动 dsh (DeepSeek Harness) 的 Web UI。它不依赖 WebView2，不携带额外的运行时依赖，体积仅几百 KB。
安装与启用¶
该插件以 dsh 插件的形式分发，安装过程无额外拦截。
dsh plugin --profile web add github:alvinpro/dsh-launcher
安装后，可执行文件会随包进入 node_modules\dsh-launcher\dist\dsh-launcher.exe。
基本用法¶
1. 默认启动¶
双击 dsh-launcher.exe 即可运行。无需配置文件，默认以 dsh web 启动，监听端口 3080。
2. 命令行启动¶
如需自定义端口或参数，可通过命令行覆盖。
dsh-launcher.exe --port 8899 --args "web --port 8899"
3. 配置文件（可选）¶
config.json 是可选的。优先级顺序为：命令行参数 > config.json > 内置默认值。
若需固定端口或参数，可复制 config.example.json 并修改。
{
"dsh_path": "",
"url": "http://127.0.0.1:8899",
"port": 8899,
"timeout_secs": 40,
"package": "dsh",
"args": ["web", "--port", "8899"]
}
4. 验证解析链¶
在不实际启动的情况下，仅验证 dsh 命令的解析链。
.\dsh-launcher.exe --check
工作原理¶
该启动器通过六个步骤管理 dsh 的生命周期：
- 探测：检查端口是否已就绪。若已就绪，直接打开浏览器并退出，避免重复启动。
- 解析：按顺序尝试从配置路径、本地离线包 (
vendor\dsh\)、系统 PATH 以及npx获取 dsh，并用dsh --version校验可用性。 - 拉起：使用
CREATE_NO_WINDOW隐藏窗口拉起cmd.exe，并立即绑定 JobObject，确保后续的进程树管理。 - 就绪：进行 TCP 连通性检查与 HTTP 响应双重校验（端口通 ≠ 服务就绪）。校验通过后，使用
ShellExecuteExW前台唤起浏览器。 - 联动：关闭拉起的浏览器会导致 dsh 自动停服；若浏览器本就在运行，则进入常驻模式，通过托盘图标退出。
- 清理：无论通过何种方式退出（正常、托盘、强杀），JobObject 均会终止整个进程树，实现零残留。
核心特性¶
- 自动发现：支持配置路径、本地离线包、系统 PATH 和 npx 的自动发现，无需全局安装。
- 真实就绪探测：采用 TCP + HTTP 双重校验，并具备自适应退避和超时保护机制。
- 零残留：利用 JobObject 的
KILL_ON_JOB_CLOSE属性，确保任何退出路径下进程树被彻底清理。 - 浏览器联动：关闭浏览器自动停服，共享实例则进入常驻模式，不会误杀正在使用的浏览器窗口。
- 调用系统默认浏览器：不捆绑浏览器，直接调用系统默认浏览器打开服务地址。
- 无窗体验：GUI 子系统运行，无控制台窗口，无黑屏闪烁。日志落盘于
dsh-launcher.log，出错时弹窗提示。 - 异常守护：探测期 dsh 提前退出或超时均有明确的错误处理逻辑。
- 单文件：约 360KB 的 exe，内嵌图标，零运行时依赖。
- 不依赖 WebView2：原生 Win32 托盘与弹窗，无需安装 Edge/WebView2 运行时，兼容 Windows 7+。
退出码说明¶
| 退出码 | 含义 |
|---|---|
| 0 | 正常退出 |
| 1 | 配置错误或 dsh 启动失败 |
| 2 | 端口已就绪但服务响应异常 |
| 3 | 等待服务超时 |
| 4 | dsh 进程提前或异常退出 |
| 5 | dsh 命令解析或自动安装失败（含 npm 不存在） |
适用场景与注意事项¶
- 系统要求：仅支持 Windows 7 及以上系统。
- 权限说明：插件以当前 dsh 进程的权限运行。安装前建议检查源码与许可证（MIT）。
- 快捷方式：首次运行
dsh plugin add后，桌面快捷方式会自动创建一次，指向随包附带的 exe，之后不再重建。
总结¶
DSH-Launcher 解决了 Windows 下启动 DSH Web UI 的核心痛点：依赖复杂、进程残留和窗口闪烁。通过 Rust 实现的单文件、零依赖设计，它提供了一个极简且可靠的启动方案。
