桌面客户端 liuliyisui/dsh-desktop

DeepSeek Harness 桌面端

对标 Codex Desktop 的本地桌面 GUI 客户端，基于 DeepSeek-Harness (dsh) 开源框架。

技术栈：Electron + React + @deepseek-ai/dsh-web-app 内核（复用 dsh Cordis 插件系统与全部原生能力）。

特性（对照需求清单）

| 需求 | 实现 |
| 本地桌面窗口（非浏览器网页） | Electron BrowserWindow 承载 dsh Web GUI；WebView 内核即 Electron/Chromium |
| Windows / macOS | electron-builder 输出 exe（NSIS）与 dmg |
| 工作区目录选择 | 菜单/按钮「选择工作区文件夹…」→ 服务以该目录为 cwd 重启 |
| Agent 对话 · 流式输出 · 工具调用链 | dsh-web-app 原生：流式渲染、工具调用树、可批准/拒绝（权限预设） |
| 插件市场 | 🚧 规划中——当前仓库未包含 market/ 与 electron/plugins.js，代码中暂无引用 |
| 会话保存 / 历史回溯 | dsh 原生：会话持久化 JSONL + 侧边栏历史 |
| 导出会话日志 | dsh 原生：对话内 /export 命令 → 下载对话框 |
| 插件热加载 | dsh 原生：dsh-client-hmr 客户端重载链；服务重启后新插件生效 |
| 文件读写 / bash 沙箱 / str_replace_editor | dsh 原生：工具集 + sandbox ACL 权限隔离 |
| 深浅主题 | dsh 原生：设置 → 外观（Appearance），明暗切换 |
| 设置页（API Key / 沙箱权限 / 模型选择） | dsh 原生：设置 → 模型（API Key、Provider）/ 权限预设 / 模型选择 |

核心原则（约束 1）：不重复实现 Agent 运行内核。dsh 的 web profile 本身就是完整的 Agent 客户端；桌面端只做「服务生命周期管理 + 原生窗口 + 工作区 + 插件市场」四件事。

⚠️ 当前实现状态：本仓库已包含「服务生命周期管理 + 原生窗口 + 工作区选择」及下述桌面端增强；插件市场（market/ + electron/plugins.js）尚未实现。文档中与之相关的内容均为规划中的设计，代码里没有任何引用，对应菜单项与命令当前不可用（相关段落已标注 🚧）。

桌面端增强（借鉴 xuboboo/dsh-gui，MIT）

| 增强 | 说明 |
| 🎬 品牌启动动画 | 深色渐变 + logo 呼吸光晕 + 双环加载动画（assets/splash.html，纯 CSS）；服务就绪后自动切入 GUI |
| 🎨 DeepSeek 设计语言主题 | token 级覆盖层（dsw-override.css）：品牌蓝按钮、浅蓝气泡、圆角滚动条、选区/焦点环 |
| 📋 复制按钮修复 | 放行 clipboard-sanitized-write 权限（官方 launcher 默认拒绝一切权限，复制按钮曾静默失效） |
| 🔌 端口可配置 | 环境变量 DSH_DESKTOP_PORT=3082 可改端口，解决端口冲突 |
| 📊 Token 用量统计（可选） | 借鉴其 ui-settings-token-usage 客户端插件，设置页新增用量统计（需复制到 profile 并注册 roster） |

主题覆盖层修改的是 node_modules/@deepseek-ai/dsh-web-frontend/dist/（dsw-override.css + index.html 注入 link）；重装依赖后需重新复制（与 API 网关白名单同类的部署说明）。

架构

┌────────────────────────────── Electron 主进程 ─────────────────────────────┐ │ electron/main.js 窗口、菜单、IPC 注册 │ │ electron/service.js 拉起 dsh web 服务（ELECTRON_RUN_AS_NODE，无需 Node）│ │ DSH_HOME → %APPDATA%\dsh-desktop\dsh-home │ │ electron/plugins.js 插件市场后端：GitHub 搜索 / 安装（git clone/API 下载 │ │ → bundle/roster 注册 → npm 依赖） / 卸载 │ │ electron/preload.js contextBridge：window.dshDesktop API │ └───────────────┬───────────────────────────────────────┬────────────────────┘ │ spawn(dsh CLI, cwd=工作区) │ loadURL / loadFile ▼ ▼ ┌──────────────────────────────┐ ┌──────────────────────────────┐ │ dsh web 服务（端口 3080） │ │ 渲染进程 │ │ = @deepseek-ai/dsh-web-app │ │ · 主窗口：dsh Web GUI │ │ （Agent 内核 / 工具 / 会话） │ │ · 市场窗口：market/dist │ └──────────────────────────────┘ │ （React + Vite 构建） │ └──────────────────────────────┘

📌 架构图与目录树中的 electron/plugins.js、market/ 为 🚧 规划中组件，当前仓库未包含。

目录结构

dsh-desktop/
├── package.json # 主包：electron + @deepseek-ai/dsh + electron-builder ├── electron/ │ ├── main.js # 主进程入口（窗口 / 菜单 / IPC） │ ├── service.js # dsh web 服务生命周期（启动/就绪探测/重启/停止/崩溃自愈） │ ├── plugins.js # 🚧 规划中（当前未包含） │ ├── preload.js # contextBridge 白名单桥 │ └── constants.js # 端口 / DSH_HOME / GitHub API 常量 ├── market/ # 🚧 规划中：插件市场页面（React + Vite），当前未包含 │ ├── package.json / vite.config.js / index.html │ └── src/ App.jsx · main.jsx · market.css ├── assets/ │ ├── icon.png / icon.ico # 应用图标（用户提供，2000×2000 → 512） │ ├── source-icon.jpeg # 图标源图 │ └── logo.svg # 备用 logo（深蓝鲸鱼） ├── scripts/ │ └── ensure-profile.js # postinstall：初始化 AppData 下 DSH_HOME 骨架 ├── 启动桌面端.cmd # Windows 双击入口（开发/运行） └── README.md

配置位置（约束 2）

所有用户配置位于系统 AppData 目录（Electron userData）：

- Windows：%APPDATA%\dsh-desktop\
- macOS：~/Library/Application Support/dsh-desktop/

其中 dsh-home\ 是独立的 DSH_HOME（settings.yaml、sessions、profiles 都在内），与 npx 版完全隔离。

启动 / 打包

1. 安装依赖 bash 根工程（electron、electron-builder、@deepseek-ai/dsh 内核）
npm install

插件市场页面依赖 —— 🚧 market/ 规划中，当前仓库未包含，此步暂不需要

首次 npm install 会拉取 Electron 与 dsh 全家桶，请耐心等待。postinstall 会自动创建 AppData 下的 DSH_HOME 骨架。

Electron 二进制下载慢/失败（国内网络常见）：使用 npmmirror 镜像

bash
Windows（PowerShell） $env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
npm install
macOS (bash)
export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
npm install

⚠️ 不要再设 ELECTRON_CUSTOM_DIR="{{ version }}"：electron-builder（app-builder）不会替换该占位符，会拼出 .../electron/{{ version }}/electron-vX-win32-x64.zip 直接 404。只设 ELECTRON_MIRROR 即可，版本目录由 app-builder 自动补上（实测 121 MB 约 4 秒）。那行 {{ version }} 写法是 @electron/get 的语法，对 electron-builder 无效。

2. 启动开发模式 bash 方式 A：启动 Electron（开发模式）
npm run dev

方式 B：直接启动
npm start

启动后主窗口自动加载 http://127.0.0.1:3080（首次启动 dsh 会自动初始化 web profile）。菜单栏可随时「选择工作区」「重启服务」。（「打开插件市场」为 🚧 规划中功能，当前不可用。）

3. 打包桌面客户端 bash
npm run dist:win # Windows：release\.exe（NSIS 安装包）
npm run dist:mac # macOS：release\.dmg（x64 + arm64）
npm run dist # 当前平台
npm run pack # 仅解包目录（调试用，不打安装包）

- Windows 图标：assets/icon.ico；macOS：assets/icon.png（自动转 icns）。
- 打包体积较大（dsh 内核 + Electron），属预期。
- 产物在 release\ 目录；安装后桌面创建快捷方式（NSIS 配置）。
- ⚠️ Windows 打包常见坑：electron-builder 会从 GitHub 下载 winCodeSign 工具包（用于给 exe 写图标与版本信息），国内容易连续踩两个坑，需要分别处理：
1. 下载超时 —— 加二进制镜像解决：

bash
Windows（PowerShell） $env:ELECTRON_BUILDER_BINARIES_MIRROR = "https://npmmirror.com/mirrors/electron-builder-binaries/"
npm run pack

2. 下载成功但解压失败（ERROR: Cannot create symbolic link ... libcrypto.dylib）—— 该压缩包内含 macOS 符号链接，Windows 下创建符号链接需要权限，加镜像解决不了这一步。解法：开启 Windows「开发者模式」（设置 → 系统 → 开发者选项），或以管理员身份运行一次终端。（若之前解压失败过，先清掉 %LOCALAPPDATA%\electron-builder\Cache\winCodeSign 再重试。）

- 本机实测结论（供参考）：Electron 走镜像约 4 秒下完、配置加载与打包流程正常，产物落在 release\win-unpacked\；但当前机器未开启开发者模式，winCodeSign 解压会卡在符号链接这一步。临时加 win.signAndEditExecutable: false 可绕过（代价是 exe 丢失自定义图标与版本信息，不适合出正式安装包，仅用于验证打包链路本身是否通）。

插件市场（🚧 规划中，当前仓库未包含）

以下为设计说明，market/ 与 electron/plugins.js 尚未实现，当前不可用。

- 打开方式：菜单「插件 → 打开插件市场」（快捷键 Ctrl+Shift+M）。
- 数据源：GitHub topic:dsh-plugin（与社区插件市场同源，可搜索关键词）。
- 安装流程（与官方 dsh plugin add 行为一致，不依赖 pnpm）：
1. git clone（自动兼容失效镜像重写；失败回退 GitHub API 递归下载）；
2. 复制到 dsh-home\profiles\web\node_modules\；
3. 按包形态注册：bundle 型 → 加入 dsh.profile.bundles；普通型 → 插入 cordis.patch.yml roster；
4. 有 npm 依赖自动执行 npm install --legacy-peer-deps；
5. 点击「立即重启服务」生效。
- 卸载：移除注册项 + 删除目录 + 重启。

备注

- 沙箱权限隔离（约束 3）：Agent 的 bash/文件工具受 dsh 的 sandbox + permission-presets 管控，与官方一致；桌面端不放松任何权限。
- 会话导出：对话中输入 /export 使用官方导出对话框。
- 故障排查：服务日志见 dsh-home\profiles\web（或主进程 stderr）；服务崩溃会自动重启（3s 间隔）。
- 内核为 dsh 官方 @deepseek-ai/dsh（^0.1.5-rc.1），升级内核 = 升级依赖版本后重启。