# dsh-desktop — 产品整体介绍

把 DeepSeek Harness Web 界面（`dsh web`）封装成**无浏览器元素的桌面应用**：独立原生窗口、应用图标、自定义标题栏。点击桌面应用就是在后台调用 `dsh web`，但窗口里看不到地址栏、URL、命令、菜单和开发者工具。

本产品提供**两种使用形态**：

| 形态 | 是什么 | 适用场景 |
|---|---|---|
| **插件**（npm 包 `@cheramvb/dsh-desktop`） | 集成进 dsh web，侧边栏「桌面应用」入口 + agent 工具 | 你已经在用 dsh web，想要桌面窗口体验 |
| **exe**（便携版，自包含 Electron） | 独立桌面应用，双击即用 | 想要独立图标、不依赖浏览器打开 |

> 插件详细安装文档见 [README.md](./README.md)；本文档是整体介绍：插件安装 + exe 部署使用（安装包见 [GitHub Release](https://github.com/liumian576/dsh-desktop/releases/latest) / 自己打包）。

---

## 一、前置要求：安装 dsh

两种形态都需要 dsh 提供 Web 服务（`dsh web`）。按你的习惯二选一：

### 方式 A：npm 全局安装（推荐，exe 可自动拉起服务）

```powershell
npm install -g @deepseek-ai/dsh
dsh web
```

`dsh` 进入 PATH 后，插件与 exe 都能自动找到并**隐藏拉起**服务。

### 方式 B：npx 免全局安装

```powershell
npx @deepseek-ai/dsh web
```

npx 方式下 `dsh` **不在 PATH**，exe 自动拉起服务时需要显式指定 CLI 入口：

```powershell
$env:DSH_BIN  = (Join-Path (npm root -g) "@deepseek-ai\dsh\lib\bin.js")  # 自动定位全局 dsh 包
$env:DSH_NODE = "node"
```

### 验证

```powershell
dsh web
# 浏览器打开 http://127.0.0.1:3080 能看到 DSH Web 界面即 OK
```

---

## 二、插件方式使用

### 安装

```powershell
# 国内网络建议先设 Electron 镜像
$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
dsh plugin --profile web add @cheramvb/dsh-desktop
dsh web          # 重启生效
```

刷新浏览器 → 侧边栏出现「桌面应用」入口。

### 使用（四种触发方式，任选其一）

1. **侧边栏「桌面应用」**（推荐）：点击弹出桌面窗口（单实例，已开则聚焦）；桌面壳内侧边栏有「打开网页版」，在默认浏览器中打开同一服务地址，与网页版构成闭环（来回切换）。
2. **桌面快捷方式**：插件包自带 `desktop/create-shortcut.vbs`，运行一次即在桌面创建「DeepSeek Harness」快捷方式（隐藏控制台启动，图标取 `desktop/icon.png`）。前提：Node.js 在 PATH、Electron 已装（快捷方式路径**不会**自动补装，缺失时先手动 `node <profile>\node_modules\electron\install.js`）。
3. **Agent**：对话中说「打开桌面版 / 打开桌面应用」，模型调用 `desktop_launch` 工具直接打开。
4. **命令行**：`node "<插件目录>\desktop\start.mjs"`，或 profile 安装后生成的 `"<profile>\node_modules\.bin\dsh-desktop.CMD"`。

- **设置**：窗口尺寸、无边框、应用名可在 DSH 设置面板调整。
- **窗口行为**（四种方式通用）：单实例；点 X 最小化到托盘驻留（不退出），托盘菜单可重新打开或退出；独立启动自启的 `dsh web` 随应用退出关闭；从插件启动时关闭窗口不影响宿主服务；断线自动隐藏重启并恢复。

---

## 三、exe 方式使用

### 3.1 从 GitHub Release 下载安装包（推荐）

最新安装包发布在 GitHub Release（exe 不再提交进仓库的 `dist\`）：

**下载地址**：[github.com/liumian576/dsh-desktop/releases](https://github.com/liumian576/dsh-desktop/releases/latest)

- 产物为**便携版 exe**（自包含 Electron 运行时，约 164 MB，免安装直接运行），文件名 `Lei-DeepSeek-Harness-<版本>.exe`（当前 0.1.0，Windows x64）。
- 下载后放到任意目录即可使用，以下以 `Lei-DeepSeek-Harness-0.1.0.exe` 为例。

**用法**：

| 用法 | 操作 |
|---|---|
| 直接双击 | 自动探测/拉起 `dsh web`，弹出桌面窗口（无控制台、不弹浏览器） |
| 指定服务地址 | `.\Lei-DeepSeek-Harness-0.1.0.exe --url=http://127.0.0.1:3080` |
| 指定 profile | `--profile=web` |
| 窗口参数 | `--width=1280 --height=800 --title="..." --frameless / --no-frameless` |

**要求**：
- 目标机器**无需安装 Node.js**（Electron 已内嵌），但**必须装有 dsh**（第一章方式 A 或 B）。
- 单实例；点 X 最小化到托盘驻留（不退出），托盘菜单可重新打开或退出；独立启动自启的 `dsh web` 随应用退出关闭（无控制台窗口、无孤儿进程）；断线自动隐藏重启并恢复。

### 3.2 自己部署（自行打包 exe）

想自己改代码再打包，或想换个图标/应用名：

**前置**：Node.js ≥ 22.19.0（推荐 24.18.0）、npm；本仓库已 clone 并 `npm install` 过。

```powershell
# 1) 装依赖（国内网络先设镜像，Electron 约 138 MB）
$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
npm install

# 2) 打包
npm run build:exe
```

**产物**：`dist\Lei-DeepSeek-Harness-<版本>.exe`（约 164 MB，自包含 Electron 运行时）。

**自定义项**：
- **图标**：维护 `desktop/icon.png`（**≥256×256**，小于 256 会被打包脚本用默认图覆盖）；运行时优先用它，缺失时回退自动生成默认图标。
- **应用名**：改 `desktop/main.js` 的 `APP_NAME` 与 `electron-builder.yml` 的 `productName`。
- **启动画面 logo**：替换 `assets/logo.svg` 即可（无需改代码）。

**分发**：把产出的 exe 发布到 [GitHub Release](https://github.com/liumian576/dsh-desktop/releases)（或直接发给目标机器）即可；目标机器按第一章装好 dsh。

---

## 四、常见问题

| 现象 | 解决 |
|---|---|
| 安装包（exe）在哪下载 | [GitHub Release](https://github.com/liumian576/dsh-desktop/releases/latest) 页面，下载 `Lei-DeepSeek-Harness-<版本>.exe`（便携版，免安装） |
| Electron 下载慢/卡住 | 设镜像后重装：`$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"` |
| 插件首次点击无反应/提示「未安装桌面运行组件」 | 首次点击会自动补装 Electron（按钮显示「正在安装桌面组件…」，约 1~4 分钟），完成后自动启动；补装失败（网络/磁盘）时提示设置 `ELECTRON_MIRROR` 镜像，或手动 `node <profile>\node_modules\electron\install.js` |
| exe 双击后一直转圈/连不上 | 确认 `dsh` 已装（第一章），或 `--url=` 显式指定服务地址 |
| 窗口顶部被自定义标题栏遮挡 | 设置中关闭「无边框窗口」 |

---

## 五、安全说明

- `/api/dsh-desktop/*` 路由带**回环信任围栏**，局域网暴露的 dsh web 无法调用。
- 窗口禁止弹窗与外部跳转、禁用开发者工具，仅开放剪贴板与全屏权限。
- 内部 URL 与 `dsh web` 命令只存在于进程参数与宿主内部，任何界面文案均不展示。