deepseek-harness-desktop

把 DeepSeek Harness 的 WebUI（dsh web）封装成桌面应用，跨平台支持 macOS 与 Windows。

技术栈与平台

版本	技术栈	平台	说明
electron/（推荐）	Electron + electron-builder	macOS + Windows	单一代码库；内置 @deepseek-ai/dsh，用 Electron 内置 Node 直接跑 dsh web，用户机器无需安装 Node.js / dsh
DSHDesktop/（可选）	Swift + AppKit + WKWebView	macOS 原生	无运行时依赖，但仅支持 macOS

Electron 版特性

• 原生窗口 + 菜单栏（刷新 ⌘R/Ctrl+R、浏览器打开 ⇧⌘O/Ctrl+Shift+O、退出、全屏）
• macOS 原生窗口观感：隐藏内嵌标题栏（hiddenInset），交通灯悬浮在页面左上角；自动注入 44px 安全区条带让页面内容避开交通灯、顶部条带可拖动窗口，页面背景色与系统明暗主题同步（无加载白闪）
• 服务器生命周期自动管理：
  • http://127.0.0.1:3080 已有 dsh web 在跑 → 直接连接（不重复启动）
  • 否则以子进程启动内置 dsh web --port <port>（ELECTRON_RUN_AS_NODE=1 + --expose-internals），就绪后加载页面
  • 退出应用（含 SIGTERM）自动关闭子进程，不留孤儿
• 找不到服务器时的启动过渡页、错误中文提示
• 内置自检模式 --selftest（自动化验证用）

构建（macOS）

前置：Node.js 20+、Xcode Command Line Tools（swiftc/clang，用于重编 node-pty）。

cd electron
npm install                 # 国内网络走 .npmrc 配置的 npmmirror 镜像
npm run rebuild:native      # 把 node-pty 重编为 Electron ABI（重要！）
npm start                   # 开发模式运行
npm run selftest            # 自检：SELFTEST_OK url=... server=owned|external
npm run build:mac           # 打包 dmg + zip（产物在 release/）

构建（Windows）

必须在 Windows 机器上构建（node-pty 等原生模块需按目标平台编译；macOS 交叉构建的 Windows 包其原生模块不可用）。

前置：Node.js 20+、npm、Visual Studio Build Tools（含 "Desktop development with C++" 工作负载）与 Python 3（node-gyp 需要）。

cd electron
npm install
npm run rebuild:native      # 在 Windows 上用 MSVC 重编 node-pty（重要！）
npm start                   # 开发模式运行
npm run selftest
npm run build:win           # 打包 NSIS 安装包 + 便携版 exe（产物在 release/）

提示：electron-builder 依赖的 Electron 二进制 / NSIS 工具默认从 GitHub 下载，electron/.npmrc 已配置 npmmirror 镜像；如你的网络可直连 GitHub，可删除该文件。

配置（环境变量，透传给应用与 dsh 子进程）

变量	作用
DSH_DESKTOP_URL	覆盖服务器地址，默认 http://127.0.0.1:3080
DSH_HOME	dsh 数据目录，默认 ~/.dsh（Windows 为 %USERPROFILE%\.dsh）

自检

# macOS（开发模式）
cd electron && npm run selftest
# 打包后的应用
"./release/mac-arm64/DeepSeek Harness.app/Contents/MacOS/DeepSeek Harness" --selftest

输出 SELFTEST_OK url=http://... server=owned|external（0）或 SELFTEST_FAIL ...（2）。

已知边界

• 产物为未签名构建：macOS 本地运行正常；对外分发需 Apple Developer 签名 + 公证；Windows 分发需代码签名（否则 SmartScreen 提示）。
• Windows 包必须在 Windows 上执行 npm run rebuild:native 后构建（见上）。
• @deepseek-ai/dsh 固定为 0.1.0-rc.6（内置版本），如需升级请改 electron/package.json 并重新构建。
• harness 的工具若需调用系统 node/git/shell（如部分 agent 工具），依赖用户机器的 PATH；应用启动 dsh 时会自动补充常见 Node 安装路径。

目录结构

electron/                   # 跨平台 Electron 应用
  src/main.js               # 主进程：服务器生命周期、窗口、菜单、自检
  src/preload.js            # 预加载（沙箱 + contextIsolation）
  src/loading.html          # 启动过渡页
  build/                    # 图标（icon.icns / icon.ico / icon.png）
  scripts/rebuild-native.mjs# 原生模块 Electron ABI 重编脚本
  scripts/make-ico.mjs      # Windows 图标打包
  .npmrc                    # npmmirror 镜像配置
DSHDesktop/                 # （可选）macOS 原生 Swift 版，见 DSHDesktop/build.sh