桌面工作台 Huang-yu-xin/dsh-desktop

DeepSeek Harness Desktop

语言 / Language： English · 中文

官方 DeepSeek Harness Web UI 的 Windows 原生桌面封装。一个封装官方 DeepSeek Harness Web UI 的原生 Windows 桌面应用。

DeepSeek Harness 处于开发者预览阶段，各版本可能会破坏兼容性。本应用固定使用某一个 harness 版本（见 src/main/config.ts），并有意识地对其进行升级。

功能特性

- 工作区选择器 —— 通过原生对话框选择项目文件夹；该文件夹将成为 harness 的工作目录，且绝不会被本应用修改。
- 自动的 harness 生命周期 —— 启动、就绪检测、页面加载以及退出时的进程树清理全部自动完成；无需 PowerShell，无需手动 npx，无需浏览器标签页。
- 动态端口 —— 应用启动 dsh web --host 127.0.0.1 --port 0，由操作系统分配空闲端口，因此不会出现端口冲突，即使有其他 harness 实例正在运行也是如此。
- 官方就绪信号 —— 应用会等待文档中所述的 dsh web: http://… stdout 输出行，然后通过 HTTP 200 检查确认后再加载页面。
- 加载页与错误页 —— harness 启动期间显示分阶段进度；失败时显示包含原因、脱敏日志、重试（Retry）和选择其他工作区（Choose Another Workspace）的页面。
- 最近工作区 —— 最近打开的 10 个文件夹，支持一键重新打开、移除以及 (missing) 标记。仅存储目录路径和时间戳。
- 干净关闭 —— 退出时通过 taskkill /T /F 终止整个 harness 进程树；不会残留孤立的 node.exe 或 cmd.exe 进程。
- 健康监控（V1.1） —— UI 启动后，每 5 秒仅针对 harness 源执行一次轻量级 GET / 检查。连续失败会将状态标记为 disconnected 并显示连接丢失页面；监控器本身绝不会终止仍在运行的进程。
- 崩溃恢复（V1.1） —— 检测并分类意外进程退出、进程错误和健康检查失败（进程已退出 / 进程错误 / 健康检查失败 / 意外退出码）；重启 Harness（Restart Harness）会在操作系统新分配的空闲端口上重新启动同一工作区，同时保持原生会话存储不变。
- 返回工作区（V1.1） —— 从正在运行的 harness 返回工作区页面（菜单 Harness → Back to Workspaces，Ctrl+Shift+B），并通过正常的启动 → 就绪 → 加载流程启动另一个工作区。
- 窗口状态（V1.1） —— 宽度、高度、位置和最大化状态持久保存在 userData 中；屏幕外的坐标会回退到可见位置。
- 日志查看器（V1.1） —— 按流显示 stdout/stderr 的尾部内容，并支持复制日志（Copy Logs）；在内容到达 UI 之前，类似凭据的模式会被脱敏。
- 单实例（V1.1） —— 第二次启动会激活现有窗口，而不是启动第二个后端。
- 内置离线运行时（V1.2） — 固定版本的 Harness 发行版作为生产依赖随应用一起发布，并运行在 Electron 自带的嵌入式 Node 上（ELECTRON_RUN_AS_NODE=1）；打包后的应用无需 Node.js、npm 或 npx，也从不访问 npm registry。
- Windows 产物（V1.2） — win-unpacked、便携版 exe、NSIS 安装程序，以及解包构建的 zip 包（参见 release/）。

前置条件

- Windows x64。
- 打包后的应用（V1.2）：无需其他任何东西 — 不需要 Node.js、npm、npx 或 PowerShell；首次启动不会执行任何下载。
- 开发构建额外需要系统级安装的 Node.js ^22.19.0 || >=24.0.0 以及 npm。
- DeepSeek API 密钥保存在 Harness 自己的凭据存储中（在 Harness UI 中配置，存储在 $DSH_HOME/.credentials.yaml 下）；本应用从不管理密钥。

快速开始

npm install # 一次性
npm run dev # 构建并启动

点击 Open Folder，选择一个项目目录，官方 Harness UI 便会在窗口中打开。

命令

| 命令 | 用途 |
| npm install | 安装开发依赖（Electron、TypeScript） |
| npm run build | 编译 TypeScript 并将渲染器资源复制到 dist/ |
| npm start | 运行已构建的应用 |
| npm run dev | 先构建，再运行 |
| npm run verify | 运行脚本化的最小循环验证 |
| npm run stage | 为打包组装生产依赖树（release-stage/） |
| npm run dist | 构建、暂存并打包 Windows 产物（release/） |

scripts/ 下的验证脚本：verify-v11.ps1 运行可靠性场景套件（崩溃恢复、HTTP 断连、返回工作区、窗口状态、日志、单实例、IPC 门控、最近记录 — 共 55 项检查），check-sanitize.mjs 断言日志脱敏的单元用例，verify-longtask.ps1 在健康监控下运行约 60 秒的忙碌 agent 模拟，verify-real-agent.ps1 agent|persist 运行真实 agent 与会话持久化的回归测试。

工作原理

1. 选择一个工作区文件夹，或为脚本化运行传入 --workspace 。
2. 主进程通过 Electron 自带的嵌入式 Node（process.execPath + ELECTRON_RUN_AS_NODE=1 + --expose-internals，这是必需的，以便官方加载器能在此运行时上访问 Node 内部模块），从内置依赖树中启动固定版本的 @deepseek-ai/dsh@0.1.0-rc.6（参见 src/main/config.ts），以工作区作为 cwd，并使用固定参数 dsh web --host 127.0.0.1 --port 0。运行时从不使用 npm/npx；缺少内置运行时会生成一个本地错误页面，而绝不会回退下载。
3. 就绪状态以官方 stdout 行 dsh web: http://127.0.0.1: 为准，随后进行 HTTP 200 检查；只有通过后，窗口才会加载 http://127.0.0.1:。
4. 退出时，使用 taskkill /T /F 终止 harness 进程树。
5. UI 运行期间，健康监控每 5 秒轮询一次 GET /（超时 2 秒）。连续三次失败会将状态标记为 disconnected —— Desktop 会显示连接丢失页面，其中包含 Restart Harness / Show Logs / Back to Workspaces，但绝不会终止正在运行的进程本身。意外进程退出会通过 exit/close/error 检测到，并归类为一个原因。

项目结构

src/
├── main/ Electron 主进程 │ ├── config.ts 固定的包规格、固定 argv、超时 │ ├── harness.ts HarnessController 状态机（spawn → readiness → stop） │ ├── process.ts 工具链查找、npx spawn、进程树终止 │ ├── workspace.ts 文件夹校验和最近工作区存储 │ └── index.ts 窗口、导航守卫、IPC 处理器、退出流程 ├── preload/ 渲染进程与主进程之间唯一的桥接 └── renderer/ 外壳页面（Choose / Loading / Error），原生 TypeScript scripts/ 构建辅助脚本和端到端验证脚本

安全模型

- contextIsolation: true、nodeIntegration: false、sandbox: true、webSecurity: true。
- preload 暴露六个固定操作；每个 IPC 处理器都会拒绝非本地外壳页面的调用者，因此 Harness UI 无法获得任何可用的 Electron 接口。
- harness 命令行由主进程中的常量组装：没有 shell 字符串跨 IPC 传递，也没有用户输入被拼接到命令中。
- 主框架导航被限制为外壳页面和确切的 harness 源；新窗口在系统浏览器中打开，绝不在应用内打开。
- Harness 日志在到达 UI 之前会被脱敏（类似凭据的模式）。
- 最近工作区存储仅包含目录路径和时间戳；其 IPC 接口不暴露给 Harness 页面。

验证

- scripts/verify-loop.ps1 —— 对最小循环进行脚本化端到端检查：spawn、readiness 行、HTTP 200、页面标题、load 事件、干净关闭窗口、electron 退出、harness pid 消失、端口关闭。
- scripts/verify-real-agent.ps1 agent|persist 配合 scripts/verify-agent.mjs —— 通过 Chrome DevTools Protocol 驱动真实 UI：创建会话，运行只读任务（只读工具，工作区哈希快照不变），然后验证应用重启后的原生会话持久化。
- scripts/analyze-session.mjs —— 解析官方 zstd-frame 会话日志格式。
- agent 套件继承端口 3080 上正在运行的 harness 的凭据环境；它从不读取或存储密钥。

已知限制

- 开发构建需要系统安装 Node.js/npm；打包后的应用不需要。
- 固定版本为 0.1.0-rc.6；升级是有意的版本提升。
- 终止是强制性的（taskkill /F）：在 Windows 上，harness 的优雅处置路径无法从外部到达，这与官方行为一致。
- 健康监控仅进行检测——它不会在 disconnected 后自动恢复已恢复的 HTTP 端点；用户通过丢失页面重启。
- 便携版 exe 每次启动时都会重新解压其载荷（在普通机器上约 1 分钟；防病毒扫描可能会延长此时间）。安装程序和 win-unpacked 的 zip 包避免了每次启动时的解压。
- 产物未签名：在配置用于公开发布的代码签名证书之前，Windows SmartScreen 会显示“未知发布者”。

V1 中不包含

重建 Harness UI、自定义插件、自动更新、MCP/技能管理器、多模型路由、多 Harness 编排、云同步以及捆绑的 Node 运行时均有意不在 V1 的范围内。

DeepSeek Harness 处于 Developer Preview 阶段，版本之间可能存在破坏性变更。本应用固定使用一个 Harness 版本（见 src/main/config.ts），升级时由开发者显式变更。

功能

- 工作区选择 — 用系统原生对话框选择项目目录；该目录成为 Harness 的工作目录，应用不会修改其中的任何文件。
- 自动化 Harness 生命周期 — 启动、就绪检测、页面加载、退出时的进程树清理全自动；无需打开 PowerShell、手动执行 npx 或开浏览器标签页。
- 动态端口 — 以 dsh web --host 127.0.0.1 --port 0 启动，端口由操作系统分配，即使有其他 Harness 实例在运行也零端口冲突。
- 官方就绪信号 — 等待官方文档化的 stdout 行 dsh web: http://…，再做一次 HTTP 200 确认，之后才加载页面。
- 加载页与错误页 — 启动过程中分阶段显示进度；失败时展示原因、脱敏日志、Retry 与 Choose Another Workspace。
- 最近工作区 — 保存最近打开的 10 个目录：一键重新打开、可移除、路径失效时标注 (missing)；只存目录路径与时间戳。
- 干净退出 — 退出时用 taskkill /T /F 终止整个 Harness 进程树，不残留孤儿 node.exe 或 cmd.exe 进程。
- 健康监控（V1.1） — UI 就绪后每 5 秒对 Harness origin 做一次轻量 GET / 检查。连续失败进入 disconnected 状态并显示连接丢失页；监控只检测，绝不会自行杀掉仍然存活的进程。
- 崩溃恢复（V1.1） — 意外进程退出、进程错误与健康检查失败均被检测并按类别归因（进程退出 / 进程错误 / 健康检查失败 / 意外退出码）；Restart Harness 在同一工作区、新的 OS 分配端口上重启，Harness 原生会话数据完整保留。
- 返回工作区列表（V1.1） — 运行中可通过菜单 Harness → Back to Workspaces（Ctrl+Shift+B）返回工作区页，再经完整的 spawn → 就绪 → 加载流程打开另一个工作区。
- 窗口状态（V1.1） — 尺寸、位置、最大化状态保存在 userData；屏幕外坐标自动回退到可见位置。
- 日志查看器（V1.1） — stdout/stderr 分路展示，支持 Copy Logs；凭据类模式在进入 UI 前一律脱敏。
- 单实例（V1.1） — 第二次启动只会激活已有窗口，不会创建第二个后端。
- 内置离线运行时（V1.2） — 固定版本的 Harness 作为 production dependency 随应用分发，并在 Electron 自带 Node（ELECTRON_RUN_AS_NODE=1）上运行；打包后的应用不需要 Node.js、npm 或 npx，也从不访问 npm registry。
- Windows 产物（V1.2） — win-unpacked、portable exe、NSIS 安装器以及 unpacked 构建的 zip 包（见 release/）。

前置要求

- Windows x64。
- 打包后的应用（V1.2）：无其它要求 — 不需要 Node.js、npm、npx 或 PowerShell；首次启动不进行任何下载。
- 开发构建额外需要系统级 Node.js ^22.19.0 || >=24.0.0 与 npm。
- DeepSeek API Key 保留在 Harness 自己的凭据存储中（在 Harness UI 内配置，存放于 $DSH_HOME/.credentials.yaml）；本应用不管理任何密钥。

快速开始

npm install # 一次性
npm run dev # 构建并启动

点击 Open Folder，选择一个项目目录，官方 Harness UI 即会在窗口中打开。

命令

| 命令 | 用途 |
| npm install | 安装开发依赖（Electron、TypeScript） |
| npm run build | 编译 TypeScript 并把渲染层静态资源复制到 dist/ |
| npm start | 运行已构建的应用 |
| npm run dev | 构建后运行 |
| npm run verify | 运行脚本化的最小闭环验证 |
| npm run stage | 组装打包用的 production 依赖树（release-stage/） |
| npm run dist | 构建、staging 并打包 Windows 产物（release/） |

scripts/ 下的验证脚本：verify-v11.ps1 运行可靠性场景套件（崩溃恢复、 HTTP 断连、返回工作区、窗口状态、日志、单实例、IPC 门禁、最近工作区，共 55 项检查），check-sanitize.mjs 断言日志脱敏用例，verify-longtask.ps1 在健康监控全程运行时执行约 60 秒的忙碌 Agent 模拟，verify-real-agent.ps1 agent|persist 执行真实 Agent 与会话持久化回归。

工作原理

1. 选择一个工作区目录（脚本化运行时也可传 --workspace ）。
2. 主进程从内置依赖树启动固定版本 @deepseek-ai/dsh@0.1.0-rc.6（见 src/main/config.ts）：以 Electron 自带 Node（process.execPath + ELECTRON_RUN_AS_NODE=1 + --expose-internals，后者是该运行时下官方 Loader 触达 Node 内部模块所必需）运行，工作区为 cwd，参数固定为 dsh web --host 127.0.0.1 --port 0。运行期从不使用 npm/npx；内置运行时缺失时进入本地错误页，绝不回退到下载。
3. 就绪判据是官方 stdout 行 dsh web: http://127.0.0.1:，再加一次 HTTP 200 确认；通过后窗口才加载 http://127.0.0.1:。
4. 退出时用 taskkill /T /F 终止 Harness 进程树。
5. UI 运行期间，健康监控每 5 秒轮询一次 GET /（单次 2 秒超时）。连续三次失败进入 disconnected 状态——桌面端显示连接丢失页（Restart Harness / Show Logs / Back to Workspaces），但绝不自行杀掉存活的进程。意外进程退出通过 exit/close/error 监听检测并归类原因。

项目结构

src/
├── main/ Electron 主进程 │ ├── config.ts 固定的包版本、固定参数、超时配置 │ ├── harness.ts HarnessController 状态机（spawn → 就绪 → stop） │ ├── process.ts 工具链定位、npx 启动、进程树终止 │ ├── workspace.ts 目录校验与最近工作区存储 │ └── index.ts 窗口、导航守卫、IPC 处理器、退出流程 ├── preload/ 渲染层与主进程之间的唯一桥梁 └── renderer/ 壳页面（Choose / Loading / Error），原生 TypeScript scripts/ 构建辅助与端到端验证脚本

安全模型

- contextIsolation: true、nodeIntegration: false、sandbox: true、webSecurity: true。
- preload 只暴露六个固定动作；所有 IPC 处理器都会拒绝非本地壳页面的调用方，Harness UI 因此得不到任何可用的 Electron 能力面。
- Harness 启动命令由主进程中的常量拼装：没有 shell 字符串跨 IPC，也没有用户输入被拼进命令。
- 主框架导航仅允许壳页面与精确的 Harness origin；新窗口一律在系统浏览器中打开，绝不在应用内打开。
- Harness 日志在进入 UI 之前经过脱敏（凭据类模式）。
- 最近工作区存储只含目录路径与时间戳；其 IPC 能力面不向 Harness 页面暴露。

验证

- scripts/verify-loop.ps1 — 最小闭环的脚本化端到端检查：spawn、就绪行、HTTP 200、页面标题、加载事件、窗口干净关闭、electron 退出、harness pid 消失、端口释放。
- scripts/verify-real-agent.ps1 agent|persist 配合 scripts/verify-agent.mjs — 通过 Chrome DevTools Protocol 驱动真实 UI：创建会话、执行只读任务（仅只读工具，工作区哈希快照不变），并在应用重启后验证原生会话持久化。
- scripts/analyze-session.mjs — 解析官方 zstd 帧格式的会话日志。
- Agent 验证套件继承本机 3080 端口上运行中 Harness 的凭据环境；它从不读取或存储密钥。

已知限制

- 开发构建需要系统 Node.js/npm；打包后的应用不需要。
- 固定版本为 0.1.0-rc.6；升级是显式的版本变更。
- 进程终止是强制的（taskkill /F）：Windows 上从外部无法触达 Harness 的优雅释放路径，这与官方行为一致。
- 健康监控只做检测：disconnected 后即使 HTTP 恢复也不会自动切回；由用户经丢失页手动重启。
- portable exe 每次启动都要重新解压载荷（正常机器约 1 分钟，杀毒软件扫描会延长）；安装器与 win-unpacked 的 zip 包无逐次解压成本。
- 产物未签名：配置代码签名证书前，Windows SmartScreen 会显示"未知发布者"。

不属于 V1 的内容

重做 Harness UI、自定义插件、自动更新、MCP/Skills 管理器、多模型路由、多 Harness 编排、云同步、内置 Node 运行时，均有意排除在 V1 范围之外。

回到顶部 / Back to top