桌面客户端 P1ut0z/dsh-desktop

DSH Desktop

把 DeepSeek Harness 的 Web UI 打包成桌面应用，支持 Windows 与 macOS。内置 dsh 运行时，下载安装即可使用，无需安装 Node.js。

GitHub Release
License
Platform

✨ 特性

- 开箱即用：内置 @deepseek-ai/dsh 完整运行时，目标机器零依赖
- 本地运行：会话数据、API 配置与网页服务全部留在本机，不经过任何第三方服务器
- 后台驻留：Windows 关闭窗口隐藏到托盘，macOS 关窗后留在 Dock 与菜单栏；两种情况下服务都继续运行
- 平台原生：Windows 用沉浸式标题栏与托盘；macOS 为红绿灯让出一条窄带——侧边栏展开时只从侧边栏顶部让位，会话区仍然顶到窗口边缘，收起时红绿灯比那条 55px 的导航条宽，改由整页让位；另配标准菜单快捷键、继承登录 shell 的环境
- 随机端口：启动时由操作系统分配空闲端口，不与浏览器中已有的实例冲突
- 沙箱渲染：渲染进程完全沙箱化（nodeIntegration: false、contextIsolation: true、sandbox: true）
- 单实例：重复启动只唤起已有窗口
- 保留全部插件能力：与官方 Web GUI 相同的插件组合（工具、模型、会话、客户端 UI），支持通过用户层目录定制（Windows %USERPROFILE%\.dsh、macOS ~/.dsh）

📦 下载安装

前往 Releases 下载对应平台的安装包。

Windows — DSH.Desktop.Setup..exe，双击安装即可。

- 安装包约 135MB；解压文件较多，首次安装可能需要数分钟（企业杀毒软件逐文件扫描会明显加长耗时）
- 安装包未签名，首次运行 Windows SmartScreen 会提示"未知发布者"，请点 更多信息 → 仍要运行

macOS（Apple Silicon）— DSH Desktop--arm64.dmg，约 152MB，打开后把应用拖进"应用程序"。

- 应用只做了 ad-hoc 签名，未向 Apple 公证，首次打开会被 Gatekeeper 拦下并提示"无法验证开发者"。macOS 15 起 Apple 移除了右键 → 打开的绕过方式，改为：先双击一次让系统记录这次拦截，再到 系统设置 → 隐私与安全性，在下方的提示旁点 仍要打开；macOS 14 及更早版本仍可在"应用程序"里 右键 → 打开
- 若提示"已损坏，无法打开"，执行 xattr -dr com.apple.quarantine "/Applications/DSH Desktop.app" 后重试
- dsh 读写工作区目录时，系统会弹出文件夹访问授权，同意即可

🚀 从源码运行

前置要求：Node.js ≥ 22.19（npm 自带）。

npm install
npm start

⚙️ 配置

首次运行后生成默认配置，位置为 Windows %APPDATA%\DSH Desktop\config.json、macOS ~/Library/Application Support/DSH Desktop/config.json：

{
"command": null,
"cwd": null,
"window": { "width": 1280, "height": 860 },
"urlTimeoutMs": 60000
}

| 字段 | 说明 |
| command | null = 使用内置 dsh；或指定外部命令的 argv 数组，如 ["dsh", "web", "--port", "3080"] |
| cwd | dsh 子进程的工作目录（影响 .env / DSH_HOME 解析），默认应用数据目录 |
| window | 窗口初始宽高 |
| urlTimeoutMs | 等待服务就绪的超时时间 |

应用启动时的环境变量（如 DEEPSEEK_API_KEY）会原样传给 dsh 子进程；也可在 GUI 的设置页中配置模型凭据。

macOS 上从 Dock 或 Finder 启动的应用不会读取 ~/.zshrc，只能拿到 launchd 的最小 PATH（/usr/bin:/bin:/usr/sbin:/sbin）。为了让 dsh 的 bash 与代码执行工具能找到 node、git、uv 这些命令，应用启动时会执行一次登录 shell（$SHELL -ilc）取回完整环境后再传给子进程。取回结果会记录在日志的 [env] 行，排查"命令找不到"时先看这里。

日志位于 Windows %APPDATA%\DSH Desktop\logs\、macOS ~/Library/Application Support/DSH Desktop/logs/。

🛠 开发

npm start # 开发运行（electron .）
npm run dist:win # Windows：NSIS 安装器 → dist/
npm run dist:win:dir # Windows：只出 dist/win-unpacked，发布前快速验证
npm run dist:mac # macOS：arm64 dmg → dist/
npm run dist:mac:dir # macOS：只出 dist/mac-arm64/DSH Desktop.appsh
node scripts/make-icon.mjs # 从 assets/deepseek_harness_fish_logo.svg 重新生成两平台图标

每个平台的包都必须在对应系统上构建：asar: false + npmRebuild: false 意味着打进包里的就是宿主机 node_modules 的原样内容。

macOS 构建两点说明：

- 本机没有 Apple 签名身份时 electron-builder 不会重签，bundle 里会留着 Electron 自己的签名且与内容不一致。scripts/adhoc-sign.cjs（afterPack 钩子）用 ad-hoc 签名重新封装，原因见该文件注释
- 目前只出 arm64。Intel 包需要在 Intel 机器上构建，或先用 npm i --os=darwin --cpu=x64 装一份对应架构的 node_modules——koffi 与 node-addon-require-builtin 是按架构分发的 optional 依赖，在 arm64 机器上装出来的树打不出可用的 x64 包

发布新版本： sh
1. 修改 package.json 的 version
2. 在各自平台上构建，再上传到同一个 Release
npm run dist:win # 在 Windows 上
npm run dist:mac # 在 macOS 上
gh release create v \
"dist\DSH Desktop Setup .exe" \
"dist/DSH Desktop--arm64.dmg" \
--repo P1ut0z/dsh-desktop --title "DSH Desktop v" --notes-file release-notes.md

构建环境直连 GitHub 不稳定时，Electron 二进制与打包工具链会自动走 npmmirror 镜像（见 .npmrc）。

📁 项目结构

dsh-desktop/
├── src/
│ ├── main.js # 生命周期接线 │ ├── dsh.js # dsh 子进程：启动、就绪探测、回收、目录对话框桥 │ ├── window.js # 主窗口、注入的拖拽条与控件让位、导航拦截 │ ├── config.js # config.json 读取与校验 │ ├── logger.js # 日志与致命错误弹窗 │ ├── assets.js # 图标资源查找 │ ├── lifecycle.js # 共享的退出标志 │ └── platform/ # 平台差异全部收敛在这里 │ ├── index.js # 按 process.platform 选择实现 + 契约说明 │ ├── win32.js # 托盘图标随主题切换、cmd shim 解析、taskkill │ ├── darwin.js # 应用菜单、红绿灯让位、模板图标、关窗语义 │ └── posix.js # 进程组回收、登录 shell 环境探测 ├── assets/ # 图标（ico/png、托盘图与 macOS 模板图、SVG 源文件） ├── build/ # entitlements.mac.plist ├── scripts/ │ ├── make-icon.mjs # SVG → 两平台图标 │ └── adhoc-sign.cjs # macOS afterPack：ad-hoc 签名 ├── patches/ # 让 dsh 的目录选择器改走 Electron 原生对话框 ├── package.json # 依赖与 electron-builder 配置 └── dist/ # 构建产物（git 忽略）

新增平台支持只需要在 src/platform/ 下补一个模块并在 index.js 里加一个分支，其余代码不出现任何 process.platform 判断。

❓ 常见问题

安装为什么这么慢？
安装器包含约 2.2 万个松散文件（dsh 以 Node 模式运行，需要真实目录结构），解压 + 杀毒逐文件扫描是主要耗时，一次性成本。

提示“找不到 cordis-plugin-group”？
旧版安装包（v0.2.1 之前）的依赖裁剪缺陷所致，安装最新 Release 即可。

macOS 提示“已损坏”或“无法验证开发者”？
应用未向 Apple 公证。macOS 15 及以上：双击一次后到 系统设置 → 隐私与安全性 点 仍要打开；macOS 14 及以下：在“应用程序”里右键 → 打开。仍不行就执行 xattr -dr com.apple.quarantine "/Applications/DSH Desktop.app"。

macOS 上 dsh 报找不到 node / git / uv？
从 Dock 启动的应用拿不到 shell 的 PATH，应用会执行一次登录 shell 取回。先看日志里的 [env] 行确认取回的 PATH：如果显示探测失败，说明你的 shell 配置在非交互式启动时报错或卡住；如果 PATH 正常但仍找不到命令，说明该命令本来就不在登录 shell 的 PATH 里。

能和浏览器里的 dsh web 同时用吗？
不建议。两个实例会写同一份 DSH_HOME 会话存储，请二选一。

为什么体积这么大（Windows 安装包约 135MB、macOS dmg 约 152MB，装完约 520MB）？
Electron 运行时 + dsh 全量依赖树（约 200 个插件包、2.2 万个文件）。dsh 以 Node 模式运行，需要真实目录结构，所以关掉了 asar 打包，装完的体积就是依赖树的原样大小。换来的是目标机器零依赖。

🔧 维护者须知升级 dsh 版本时：package.json 中除 @deepseek-ai/dsh 外的 19 个 @deepseek-ai/dsh-* 直接依赖是必需的。dsh 的 bundle 以 peerDependencies 引用这些包，npm 会安装它们，但 electron-builder 计算生产依赖闭包时忽略 peer 边、会将其裁掉，导致安装后启动报 ERR_MODULE_NOT_FOUND。升级后请重新扫描 lockfile 中 peer: true 的包，把新增的运行时 peer 补进 dependencies（开发期 peer 如 electron-winstaller、postject 保持忽略）。

npm ≥ 11 的安装脚本白名单：npm 11.17+ 默认不执行未批准的 install 脚本，npm install 时对带脚本的包只警告并跳过。仓库根 package.json 的 allowScripts 字段声明了本项目所需的批准项（@deepseek-ai/dsh-subprocess-local、node-pty、koffi、protobufjs、@google/genai、electron-winstaller）。升级依赖后若出现新的 "install scripts not yet covered by allowScripts" 警告，请用 npm approve-scripts 补登记。Windows 目标机上这些脚本缺失不致命（预编译二进制随包分发），但 macOS/Linux 打包前必须完整。

🙏 致谢

- deepseek-ai/deepseek-harness（MIT）——本项目的全部内核能力
- 应用图标基于 DeepSeek 官方 logo 生成，归 DeepSeek 所有

📄 License

MIT