dsh-webui-launcher — cross-platform Web UI launcher for DeepSeek Harness

English | [中文](README.zh.md)

A DSH plugin that starts, stops, checks and opens the DeepSeek Harness Web UI from inside the harness — cross-platform (Windows / macOS / Linux), no desktop scripts needed.

Install

dsh plugin --profile web add github:YV3507/dsh-webui-launcher

or from a checkout:

cd dsh-webui-launcher
npm install && npm run build
dsh plugin --profile web add .

What it adds

• Model tools webui_status, webui_start, webui_stop, webui_open — start the Web UI (spawning dsh --profile web in the background), wait until it answers HTTP 200, report or stop it, open the default browser.
• A /webui start|stop|status|open slash command.
• A "Web UI Launcher" card on the Settings page of the web GUI (browser half, exports["./client"]), driving the same /webui/* JSON endpoints.
• Desktop shortcut: on the first plugin start, a launcher shortcut is created on the desktop (.lnk on Windows, .desktop on Linux, .command on macOS) that starts the Web UI and opens the browser once ready. Headless hosts (no Desktop, no DISPLAY) skip creation silently — the plugin never crashes on a server. Disable with desktopShortcut: false.
• dsh default icon: the shortcut uses the official dsh icon by default (the web app favicon rasterized and bundled in the plugin's assets/; .ico on Windows, .png on Linux). The icon is copied into the persistent state directory, so a plugin reinstall never orphans it.
• Custom shortcut icon: upload any image (PNG/JPEG/BMP/GIF/TIFF) from the Settings card; it is converted automatically (multi-size .ico on Windows, .png on Linux) and the existing shortcut's icon is updated immediately. Without a shortcut (headless/disabled), the converted icon is still persisted for a future creation. An explicit shortcutIconPath config overrides the default icon.
• Plugin config: port (default 3080), host (127.0.0.1), cliBin ("" = reuse the running CLI), startupTimeoutMs (120000), openBrowserOnStart (true), desktopShortcut (true), shortcutName ("DeepSeek Harness Web UI"), shortcutIconPath ("" = use the bundled dsh default icon; a path overrides it).

Behavior and robustness

• Adopt-or-start: a server already listening on the port is adopted — never restarted, never stopped. webui_stop kills the process tree this plugin spawned, and also an adopted server whose PID the desktop launcher (or an earlier plugin instance) recorded — only when the recorded PID is the one currently listening, and with the same node.exe identity guard before killing. A foreign server without a PID record is never touched.
• Explicit state machine: idle → starting → running → stopping, with single-flight serialization — concurrent start/stop calls never interleave.
• Orphan cleanup: when the plugin unloads or hot-reloads, any server it spawned — and any PID-recorded launcher server — is stopped (ctx.effect dispose).
• PID identity guard: before killing, the process is re-checked (alive, still our child, and on Windows still node.exe via tasklist) so a recycled PID is never touched.
• Abort/timeout hygiene: an aborted or timed-out start kills the child it spawned and surfaces the output tail in the error.
• CLI location fallback chain: the running CLI (process.argv[1]) → the @deepseek-ai/dsh package → explicit cliBin config; resolution failure throws an actionable error.

Development

npm run build    # esbuild → lib/index.js (host) + lib/client.js (browser)
npm test         # node --test, zero-dependency (mocks the two external packages)

The state-machine failure paths (child death, timeout, abort, sibling adoption, concurrency, dispose) are unit-tested against the built bundle with scripted fake dependencies — no real processes or timers.

Security

Loopback-only by default, no elevation, no external network. The plugin kills only the process tree it spawned, after verifying the PID still belongs to that process.

License

MIT