快速开始（开发模式）

要求：Node.js ≥ 22.19（或 ≥ 24）。本机已验证 Node v24.17.0。

cd dsh-desktop
npm install          # 安装 electron + @deepseek-ai/dsh（含全部运行时依赖）
npm start            # 启动应用

国内网络若 Electron 二进制下载慢/失败：已内置 .npmrc 指向 npmmirror 镜像，无需处理。

打包成安装程序（Windows）

npm run dist        # 先构建 resources/server.zip，再产出 dist/DeepSeek Harness Desktop-0.1.0-setup.exe

产物为 NSIS 安装包，安装后可独立运行。安装包内已包含 DSH 服务与前端，目标机器 无需安装 Node（服务器可用系统 Node，或兜底用 Electron 内置 Node 24）。

两段式部署（安装快 + 插件系统兼容）

• 安装包只包含：应用外壳（main.js 等 3 个文件）+ Electron 运行时 + 一个 resources/server.zip（76MB，由 npm run server:pack 把 @deepseek-ai/dsh 全依赖树打成单文件归档）。安装时只需写少量文件，安装速度远快于逐文件解压 1.5 万个零散小文件。
• 首次启动时，应用把 server.zip 解压到 %APPDATA%\DeepSeek Harness Desktop\server\（真实文件目录）。解压是异步的， 加载窗口立即出现并显示进度（约 10–20 秒），之后启动直接复用，约 6 秒打开。
• 为什么不用 asar 打包服务器？DSH 的插件加载器会在 profile 目录建立指向安装目录 node_modules 的 junction（healProfilesModuleFallback），junction 必须指向 磁盘上的真实目录——asar 归档内的虚拟路径在 OS 层不存在，导致所有 @deepseek-ai/* 包解析失败、服务器启动即退出（ERR_MODULE_NOT_FOUND）。 解压成真实文件后该机制正常工作。
• 版本升级：server.zip 内容版本（SERVER_VERSION，main.js 中）变化时自动重新解压。

两段式部署（安装快 + 插件系统兼容）

• 安装包只包含：应用外壳（main.js 等 3 个文件）+ Electron 运行时 + 一个 resources/server.zip（76MB，由 npm run server:pack 把 @deepseek-ai/dsh 全依赖树打成单文件归档）。安装时只需写少量文件，安装速度远快于逐文件解压 1.5 万个零散小文件。
• 首次启动时，应用把 server.zip 解压到 %APPDATA%\DeepSeek Harness Desktop\server\（真实文件目录）。解压是异步的， 加载窗口立即出现并显示进度（约 10–20 秒），之后启动直接复用，约 6 秒打开。
• 为什么不用 asar 打包服务器？DSH 的插件加载器会在 profile 目录建立指向安装目录 node_modules 的 junction（healProfilesModuleFallback），junction 必须指向 磁盘上的真实目录——asar 归档内的虚拟路径在 OS 层不存在，导致所有 @deepseek-ai/* 包解析失败、服务器启动即退出（ERR_MODULE_NOT_FOUND）。 解压成真实文件后该机制正常工作。
• 版本升级：server.zip 内容版本（SERVER_VERSION，main.js 中）变化时自动重新解压。

方式 A：源码已构建（pnpm install && pnpm run build 之后）

set DSH_ROOT=D:\deepseek-harness-master npm start

方式 B：未构建的源码（该目录需先 pnpm install，用 tsx 直接跑 TS）

set DSH_ROOT=D:\deepseek-harness-master set DSH_DESKTOP_PORT=3080 npm start

主进程会优先用 /apps/cli/lib/bin.js（已构建）或
/apps/cli/src/bin.ts（源码 + tsx）。

## 常用环境变量

| 变量 | 作用 |
| --- | --- |
| DSH_DESKTOP_PORT | 固定服务器端口（默认 0 = 自动） |
| DSH_ROOT | 指向 DSH 源码/安装目录，用本地代码启动 |
| DSH_NODE | 指定服务器使用的 node 可执行文件 |
| DSH_HOME | DSH 用户数据目录（默认 ~/.dsh），沿用 CLI 语义 |
| DSH_TELEMETRY_DISABLED | 关闭遥测（任意非空值） |

## 日志

- 控制台：npm start（从终端启动）时，服务器 stdout/stderr 直接透传到终端，
  可看到 dsh web: http://127.0.0.1:
 就绪行。
- 文件：无论从终端还是双击启动，日志都会写入
  %APPDATA%\DeepSeek Harness Desktop\logs\dsh-server.log（超过 5MB 自动轮转为 .old）。
  打包版从资源管理器双击启动时没有控制台，请从这里查看日志。

> 注意：双击启动的打包版没有控制台，Electron 主进程不会向已断开的 stdout 写入
> （已加 EPIPE 防护），因此不会有 "A JavaScript error occurred in the main process" 弹窗。

## 安全说明

- 渲染窗口 contextIsolation: true、nodeIntegration: false、sandbox: true，
  不注入 preload，窗口只是本地服务器的纯浏览器视图；
- 外部链接一律交给系统浏览器打开，禁止窗口内跳转到非本机地址；
- 服务器默认只绑定 127.0.0.1（DSH 官方默认，--host 0.0.0.0 被官方禁用）。

## 应用图标

- 图标源：build/icon.svg（DSH 官方鲸鱼标志，即网页 favicon.svg）；
- 已渲染为 build/icon.png（512x512，深色底 + 白色标志，任务栏/安装包/快捷方式均可见）；
- 修改图标：替换 build/icon.svg 后运行 `node scripts/make-icon.mjs`，再 `npm run dist`。

## 已知限制 / 后续可做
- Windows 上退出时用 taskkill /T /F 结束服务器进程树（SIGTERM 在 Windows 上无法
  触发 Node 信号处理），会话数据为增量写入，不影响持久化。
- 未做自动更新（可接入 electron-updater）。
- macOS/Linux 打包目标已在配置中预留，未在本机验证。