dsh-desktop

Codex 风格的 DeepSeek Harness 桌面 App —— 把 DSH 的 Web GUI 包进一个原生 macOS 窗口，双击即用，自动管理 dsh web 服务进程。图标采用 DeepSeek 官方蓝鲸鱼。

前置依赖：本机已安装 DeepSeek Harness CLI （dsh 命令可用）、Node.js ≥ 22、macOS（Intel / Apple Silicon）。

特性

• 双击即用：启动时自动探测端口，若没有服务在运行则自动拉起 dsh web， 窗口就绪后直接显示 DSH GUI；退出 App 时自动优雅关闭它拉起的服务
• 服务看门狗：运行期间每 8 秒探测一次服务——如果你在终端 Ctrl+C 干掉了 手动启动的 dsh web，App 会自动接管并重新拉起服务，窗口自动恢复， 从此 App 可以完全独立于终端使用
• 智能接管：如果 dsh web 已经在运行（比如你自己在终端启动的），直接连接， 退出时不会误关你的服务
• 后台常驻：菜单栏托盘图标——点击显示/隐藏窗口，右键可管理；关闭窗口后 App 留在后台，服务不中断
• 开机自启：菜单或托盘勾选「开机时启动」，登录后以后台模式自动运行
• 原生体验：macOS 原生菜单（编辑/视图/窗口）、Dock 图标、深色窗口、 Cmd+Q 退出、关闭窗口后从 Dock 恢复
• 服务状态：App 菜单 →「服务状态」查看当前服务由谁管理

使用

npm install          # 安装依赖（含 Electron）
npm start            # 开发模式启动（连接/拉起 dsh web，默认端口 3080）

可选参数：

npm start -- --port 4000     # 换一个端口
npm start -- --hidden        # 后台启动（无窗口，从托盘/Dock 打开）
npm start -- --dsh-bin /path/to/dsh   # 指定 dsh 可执行文件
npm start -- --bg /path/to/bg.jpg     # 指定 GUI 背景图
DSH_BIN=/path/to/dsh npm start        # 或通过环境变量

自定义背景图

窗口里的 GUI 默认是纯色底（--dsw-alias-bg-base）。想换成背景图，任选一种：

1. 直接把图片放进 assets/ 目录（任意文件名、png/jpg/jpeg/webp 都行， 取最新的一张；npm run pack 打包时也会自动把它带进 .app 的 Contents/Resources/，不用额外配置）
2. 启动时指定：npm start -- --bg ~/Pictures/xxx.png
3. 环境变量：DSH_DESKTOP_BG=~/Pictures/xxx.png npm start

图片会以 cover 方式铺满整个窗口（侧边栏、聊天区、右侧面板全部透出， 各区域都压了同样强度的雾化遮罩保证文字可读）。 实现上主进程读取图片并以 data: URL 内联进 CSS —— 因为 GUI 页面是 http 源，Chromium 会拦掉 file:// 本地图（图片加载失败会导致黑屏）。 不配置时外观与原来完全一致。

雾化强度（图太抢眼/文字看不清时调这个）

图片和聊天内容之间有一层主题色遮罩，默认强度 0.75（图可见但很淡， 文字清晰）。想让图更清楚调小，更淡调大（0=原图全亮，1=完全盖住只留底色）：

npm start -- --bg-dim 0.5           # 图更清晰一些
DSH_DESKTOP_BG_DIM=0.85 npm start   # 图更淡一些
open "dist/DSH Desktop.app" --args --bg-dim 0.5   # 打包版同样可用

毛玻璃模糊（可选）

默认关闭。想加 macOS 风毛玻璃（图片虚化、文字和控件保持清晰）：

npm start -- --bg-blur 18           # 模糊半径 18px（0-40，越大越糊）
DSH_DESKTOP_BG_BLUR=12 npm start    # 或环境变量
open "dist/DSH Desktop.app" --args --bg-blur 18

雾化和模糊可以组合：npm start -- --bg-dim 0.6 --bg-blur 14。

打包成 .app

npm run pack
# 产物: dist/DSH Desktop.app — 拖到「应用程序」即可使用
# （内部使用 @electron/packager + 自动安装 Dock 图标）

冒烟测试

npm run smoke                 # attach 已有服务（3080）
npx electron . --smoke-test --port 3100   # 走「自己拉起服务」路径

通过时输出 SMOKE OK: loaded <url>，失败输出 SMOKE FAIL: ...，退出码对应 0/1。

工作原理

DSH Desktop.app
 ├─ 主进程 (src/main.js)
 │    ├─ 定位 dsh：DSH_BIN 环境变量 → PATH → ~/.npm/_npx/*/node_modules/.bin/dsh
 │    ├─ 探测端口：有服务则 attach（不管理），无服务则 spawn `dsh web --port <n>`
 │    ├─ 等待 HTTP 就绪 → 创建 BrowserWindow 加载 http://127.0.0.1:<port>
 │    ├─ 托盘 (Tray)：显示/隐藏窗口、开机自启开关、退出
 │    ├─ 后台模式 --hidden：启动无窗口，托盘/Dock 按需打开
 │    └─ 退出：SIGTERM 子进程，2.5s 未退则 SIGKILL（确保无残留）
 ├─ 预加载 (src/preload.js)：向页面暴露最小只读桥 `window.dshDesktop`
 └─ 图标 (build/icon.svg → icon.icns)：终端风格 Dock 图标

目录

dsh-desktop/
├── src/main.js          # Electron 主进程
├── src/preload.js       # 预加载桥
├── scripts/pack.mjs     # 打包脚本（@electron/packager + 图标安装）
├── scripts/render-icon.js  # SVG → PNG 图标渲染辅助
├── scripts/pngstats.py  # PNG 像素校验辅助（无第三方依赖）
├── build/               # 图标资源（svg / png / icns + 组装脚本）
└── dist/DSH Desktop.app # 打包产物（git 忽略）

开源与贡献

MIT License，欢迎 PR。改动 UI 外壳后跑一次冒烟测试再提：

npm run smoke                 # attach 模式
npx electron . --smoke-test --port 3100   # spawn 模式

图标链：改 build/icon.svg → npm run icon（Chromium 渲染 PNG）→ python3 build/assemble-icns.py（组装 icns）→ npm run pack。