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），升级内核 = 升级依赖版本后重启。