deepseek-harness-desktop

English | 中文

把网页版 DeepSeek Harness（dsh web）封装成 Windows 桌面应用：一个薄 Electron 壳， 负责拉起/关停 dsh web 服务器并在原生窗口中显示其界面。不 fork、不 patch dsh 任何代码， 因此 dsh 预览版的每日升级天然兼容。

⚠️ 本项目是非官方社区封装，与 DeepSeek 官方无关联、未经其背书。

工作原理

┌─────────────────────────────── DSH Desktop（Electron 主进程）──────────────────────────────┐
│  engine-manager  ──校验/安装/原子切换/回滚──►  <引擎闭包目录>                                  │
│        │                                        engine/node_modules/@deepseek-ai/dsh (launcher) │
│        ▼                                          + 全部依赖（dsh-base / dsh-web-app / …）       │
│  spawn  node.exe …/dsh/lib/bin.js web --port N                                               │
│        │ stdout: "dsh web: http://127.0.0.1:PORT"  ← url-detector 解析就绪行                   │
│        ▼                                                                                     │
│  BrowserWindow.loadURL(http://127.0.0.1:PORT)  ← 与网页版完全相同的 GUI（同一份 $DSH_HOME 数据）│
└──────────────────────────────────────────────────────────────────────────────────────────────┘

关键事实（代码取证，@deepseek-ai/dsh-app-boot）：

• 升级单元 = 整个 npm 闭包目录：dsh 的 profile bundle（dsh-base、dsh-web-app）解析是 “安装锚点优先”（resolveBundleDir 先查 launcher 所在安装），$DSH_HOME/profiles/node_modules 只是指向该闭包内真实目录的 junction 链接，每次启动自动改指（healProfilesModuleFallback）。 因此替换整个引擎目录 = 完成升级，用户数据零触碰。
• 用户数据隔离：$DSH_HOME（默认 %USERPROFILE%\.dsh：profiles / sessions / storages / settings / credentials）与引擎目录完全分离。与网页版共享同一份数据。
• 无需用户安装 pnpm：缺 profiles/web 时 dsh 按内置模板自动初始化（写几个文件即可），无需网络；桌面壳仅为引擎安装内置 pnpm。

升级与回滚（半自动）

• 启动 12 秒后后台异步运行 npm view @deepseek-ai/dsh dist-tags（尊重你的 .npmrc registry / 镜像）检查更新，绝不阻塞窗口。默认跟踪上游预览通道 next；在 config.json 中设 engineUpdateChannel: "latest" 可只跟踪保守发布通道。
• 升级流程：内置 pnpm add 到暂存目录 → 冒烟校验（--version + --profile web --dump-default-config，DSH_HOME 指向临时目录，绝不碰真实数据）→ 停服 → 原子换名 engine ↔ engine.prev-<旧版本> → 重启服务。下载和校验期间旧服务继续运行；校验或 切换失败自动保持/恢复旧版本。下载和校验完全在后台进行，当前网页不会被替换；仅原子切换时显示数秒状态页。
• 安装、校验与 registry 查询均为异步进程；慢速镜像不会卡死界面。更新下载或校验阶段可从 菜单或托盘“取消引擎更新”，会终止整个安装进程树并保留旧引擎。
• 为兼容已安装的旧引擎，桌面壳仅在 dsh >= 0.1.0-rc.8 时传递 --no-open；旧引擎会 正常启动并可先完成升级。
• 托盘菜单“回滚引擎到上一版本”可随时回滚（保留最近 2 个旧版本）。
• 更新会重启服务：运行中的后台任务会中断，但会话数据已持久化，不丢失。

目录与配置

路径	用途
%APPDATA%\DSH Desktop\config.json	应用配置
%APPDATA%\DSH Desktop\logs\	滚动日志（壳 + dsh 子进程 stdout/stderr）
%LOCALAPPDATA%\DSH Desktop\engine\	托管引擎闭包（可整个删除后自动重装）
%LOCALAPPDATA%\DSH Desktop\engine.prev-*	旧引擎（回滚用）
%USERPROFILE%\.dsh	dsh 用户数据（与网页版共享，升级引擎绝不触碰）

config.json 常用键：port（默认 3080）、host、closeToTray、autoUpdateEngine、 engineUpdateChannel（next 或 latest）、maxAutoRestarts、startupTimeoutMs。环境变量：DSH_DESKTOP_CONFIG_DIR、 DSH_DESKTOP_ENGINE_BASE、DSH_DESKTOP_NODE（测试/自定义用）。

开发

npm install --include=dev     # 本机全局 .npmrc 若配置了 omit=dev / NODE_ENV=production 需加 --include=dev
npm start                     # dev 模式：自动探测 npm 缓存里现有的 dsh 闭包（如 npx 缓存）免网络启动

dev 模式默认端口 3080；若 3080 被网页版占用，会弹出“随机端口 / 连接现有实例”选择。

构建安装包（Windows x64）

npm run prepare:resources     # 下载便携 Node 24、内置 pnpm 11.7.0（NODE_DIST_MIRROR 可换镜像）+ 引擎离线快照
npm run dist                  # electron-builder → build/DeepSeek Harness Desktop-<ver>-setup.exe

• 安装包为 per-user NSIS 安装器（免管理员），附带 Node 运行时与引擎离线快照， 目标机器无需安装 Node，首次启动无需网络；联网后正常检查更新。
• 构建期下载可用镜像：Electron → ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/； Node → NODE_DIST_MIRROR=https://npmmirror.com/mirrors/node/；pnpm/npm 均走你的 registry 配置。
• 未签名安装包首次运行会触发 SmartScreen 提示（“更多信息 → 仍要运行”）；正式分发建议代码签名。

兼容性契约（壳的唯一依赖，均有兜底）

1. dsh web 旗标族 --port / --host（dsh-web-app 的 commander 解析）。
2. stdout 就绪行 dsh web: http://127.0.0.1:<port>（dsh-web-app 的 printUrl）。
3. dsh --version 输出 semver；致命错误非零退出码。
4. 兜底链：无 URL 行 → 探测配置端口（要求响应含 __DSH_BOOT__ 才视为就绪）→ 都失败 → 弹出兼容性提示（含引擎版本 + 日志尾部），绝不静默卡死。

安全

• 渲染进程 nodeIntegration:false、contextIsolation:true、sandbox:true，只加载 loopback URL； will-navigate / setWindowOpenHandler 拦截外部跳转并转交系统浏览器。
• 不覆盖 DSH_HOME、DSH_TELEMETRY_DISABLED 等用户环境变量。

故障排查

• 端口被占：启动时自动检测，可选随机端口或连接现有实例。
• 引擎损坏/缺失：自动重装 registry 最新版；无网络时用安装包内离线快照。
• 升级失败或取消：当前引擎保持不变；托盘菜单可手动回滚已成功切换过的版本。
• 子进程崩溃：自动重启（默认最多 3 次）后弹窗提示并附日志。
• 日志位置：%APPDATA%\DSH Desktop\logs\（托盘“查看日志目录”）。

版权与致谢

• 本项目是 DeepSeek Harness 的非官方桌面封装（Electron 薄壳），不包含 上游源码：引擎（@deepseek-ai/dsh 等 npm 包）在构建/运行时从 npm registry 安装。上游为 MIT 许可（Copyright © 2026 DeepSeek），详见 THIRD_PARTY_NOTICES.md。
• 应用图标取自上游 dsh-web-frontend 的 DeepSeek 鲸鱼标识（MIT 包内文件）； 鲸鱼是 DeepSeek 的商标，本项目与 DeepSeek 官方无关联、未经其背书。
• 本项目自身代码以 MIT 许可发布（见 LICENSE）。