DeepSeek Harness 便携版（Electron 封装）

把 DeepSeek Harness 的 Web UI （即 npx @deepseek-ai/dsh web 提供的浏览器界面）封装为免安装的 Electron 桌面应用：

• 免安装、免环境：内置便携版 Node.js 运行时与全部 @deepseek-ai/dsh 依赖， 目标机器无需安装 Node.js / npm，解压后双击即可使用；
• 数据留在应用目录：对话记录、设置、API 密钥、配置等全部保存在应用目录下的 data\ 中，随应用文件夹一起移动/备份；
• 自包含离线：Web 前端资源与全部依赖随包分发，除调用大模型 API 外不需要联网。

一、直接使用（已构建产物）

1. 打开 dist\DeepSeek-Harness\ 目录（或解压 dist\DeepSeek-Harness-portable-win-x64.zip）；
2. 双击 DeepSeek-Harness.exe；
3. 首次启动会初始化配置（十几秒），随后进入 Web 界面；
4. 在界面“设置 → Models”中配置模型与 API 密钥即可开始对话。

整个 DeepSeek-Harness\ 文件夹就是应用本体：拷到 U 盘 / 移动硬盘 / 其他电脑均可直接运行。 提示：未签名的便携 exe 在陌生电脑上可能触发 SmartScreen，选“更多信息 → 仍要运行”即可。

二、数据目录（全部在应用目录内）

DeepSeek-Harness\
├─ DeepSeek-Harness.exe       应用入口
├─ runtime\                  内置运行时（Node.js + dsh 全部依赖）
├─ resources\app\            Electron 应用代码
└─ data\                     所有用户数据（删除本目录 = 清空全部数据）
   ├─ dsh\                   DeepSeek Harness 数据根（DSH_HOME）
   │  ├─ sessions\           对话记录（JSONL）
   │  ├─ settings.yaml       界面设置（模型选择等，热加载）
   │  ├─ .credentials.yaml   API 密钥（受管凭据，仅本机使用）
   │  └─ profiles\web\       配置文件（cordis.patch.yml 等）
   ├─ workspace\             默认工作目录（agent 读写文件的位置）
   ├─ electron-profile\      界面浏览器数据（主题、localStorage、缓存）
   └─ logs\                  electron.log / server.log 运行日志

数据根固定为 data\dsh（不继承外部 DSH_HOME，保证便携性一致）；如需放到其他位置，可设置环境变量 DSH_PORTABLE_DATA。

三、工作原理

Electron 主进程
  ├─ 用内置 runtime\node\node.exe 启动子进程:
  │     dsh web --host 127.0.0.1 --port 3080   (DSH_HOME=<app>\data\dsh)
  ├─ 轮询 http://127.0.0.1:3080/ 等待服务就绪（端口被占用自动 +1 重试）
  ├─ BrowserWindow 加载该地址（与 Web UI 同源，/api 请求天然受信）
  └─ 退出时 taskkill 结束服务进程树；Chromium 数据与 dsh 数据都在 data\ 下

四、从源码构建

# 1. 安装构建依赖（electron；缓存重定向到 .cache\）
$env:npm_config_cache = (Resolve-Path .).Path + '\.cache\npm'
$env:ELECTRON_CACHE   = (Resolve-Path .).Path + '\.cache\electron'
$env:electron_config_cache = $env:ELECTRON_CACHE
npm install

# 2. 构建（自动执行 prepare-runtime：下载便携 Node.js + 安装 dsh 依赖，然后打包）
npm run build

# 产物：
#   dist\DeepSeek-Harness\                        便携应用目录
#   dist\DeepSeek-Harness-portable-win-x64.zip     便携压缩包

开发调试：npm start（需先执行一次 npm run prepare-runtime）。

自动冒烟测试：设 DSH_ELECTRON_SMOKE=<png路径> 后启动，应用加载成功会截图并自动退出。

五、升级内置 dsh 版本

npm run update-dsh -- -Version 0.1.0-rc.7

脚本会更新 runtime\server\package.json 依赖版本、重新安装依赖并重新打包。

六、常见问题

• 端口被占用：应用会自动尝试 3080–3099；仍失败会显示错误页，可打开日志排查。
• 界面打不开/报错：查看 data\logs\server.log 与 data\logs\electron.log。
• exFAT U 盘：dsh 需要在数据目录创建目录联接（junction），exFAT 不支持； 请放在 NTFS 分区，或用 DSH_PORTABLE_DATA 指向 NTFS 目录。
• 移动应用文件夹后：junction 会在下次启动自动重新指向新位置，无需处理。
• 残留服务进程：异常退出后 3080 被占用时应用自动使用下一端口； 也可在任务管理器结束残留的 node.exe。

七、环境变量

变量	作用
DSH_HOME	由应用固定为 <app>\data\dsh（不继承外部环境，保证数据始终在应用目录）
DSH_PORTABLE_DATA	显式覆盖 dsh 数据根位置（一般无需设置）
DSH_APP_ROOT	覆盖应用根目录探测（默认 exe 所在目录）
PORTABLE_EXECUTABLE_DIR	便携包场景下的应用目录（与 electron-builder portable 兼容）
DSH_PERMISSION_MODE	透传给 dsh：文件沙箱与审批策略（默认 workspace-write + ask）

八、许可与组件

• 本封装：MIT
• DeepSeek Harness（@deepseek-ai/dsh）：MIT，见 runtime\server\node_modules\@deepseek-ai\dsh\LICENSE
• Electron：MIT，见产物根目录 LICENSE.electron.txt
• Node.js：见产物 runtime\node\LICENSE.node.txt