Lucsimong/DSH-Desktop

DSH-Desktop

DeepSeek Harness 的原生桌面客户端 —— 用系统 WebView2 承载 Harness Web GUI，
一个体积小、内存低、双击即用的 Windows 桌面壳。

Languages / 语言: English · 简体中文 · Español · Deutsch · Italiano · Français

目录

- 这是什么
- 项目特色
- 实现方法（工作原理）
- 零基础：从安装到运行
- 环境变量（进阶）
- 安装
- 验证结果
- 目录结构
- 隐私与安全
- 常见问题排查

这是什么

DSH-Desktop 是 DeepSeek Harness 的桌面客户端。

DeepSeek Harness 本身通过命令行 dsh web 启动一个本地 Web 服务，然后你在浏览器里打开
http://127.0.0.1:3080 使用。DSH-Desktop 把这个流程包装成一个独立的 Windows 桌面程序：

- 双击图标，弹出一个原生窗口，里面就是完整的 Harness 界面；
- 程序自动帮你启动/找到后端的 Harness 服务，你不需要碰命令行、不需要开浏览器；
- 关掉窗口，它拉起的后台进程也会一并干净退出。

项目特色

| 特色 | 说明 |
| --- | --- |
| 🪶 极低内存占用 | 基于 Tauri 2（Rust）+ 系统 WebView2，不打包 Chromium、不自带 Node。实测安装包约 7.4 MB，运行时主进程工作集约 27 MB——只有 Electron 类方案（通常 200–400 MB）的十分之一左右 |
| 🖥️ 原生窗口，不依赖浏览器 | 打开的是独立的原生窗口，可固定到任务栏、有独立标题栏和图标，不再是浏览器里的一张标签页 |
| ⚡ 智能后端管理 | 自动判断：已有 Harness 在跑就挂接复用；没有就自己拉起；退出时只清理自己拉起的进程，绝不误杀你已有的实例 |
| 🔌 零配置开箱即用 | 无需配置接口地址、无需手动起服务。找不到 dsh 命令时还能自动通过 npx 下载 |
| 🛡️ 免管理员安装 | NSIS 安装包按当前用户安装，不弹 UAC 管理员授权；自动创建开始菜单项和桌面快捷方式 |
| 🔒 数据留在本地 | 不内置任何 API 密钥，账号凭据与会话数据都在本机 ~/.dsh 目录，由 Harness 自己管理，客户端不碰 |

实现方法（工作原理）

技术选型：为什么是 Tauri + WebView2

桌面客户端常见的做法是用 Electron（网页套 Chromium 壳）。它的问题在于：每个应用都要
打包一整份 Chromium 内核，体积动辄上百 MB，内存占用高。

DSH-Desktop 改用 Tauri 2：

- 外壳用 Rust 写成，产出一个几 MB 的原生程序；
- 界面渲染直接复用 Windows 10/11 自带的 WebView2 运行时（Edge 内核），不重复打包浏览器；
- 因此体积和内存都远低于 Electron，同时保留了"用网页技术做 UI"的开发效率。

架构

┌───────────────────────────────┐         ┌─────────────────────────────┐
│  dshd.exe  （Rust / Tauri 2）   │  spawn  │  node dsh --profile web      │
│  ┌─────────────────────────┐   │ ──────► │  （DeepSeek Harness 后端）     │
│  │  WebView2 原生窗口        │   │         │  监听 127.0.0.1:        │
│  │  加载 http://127.0.0.1:  │   │ ◄────── │  提供 UI + /api + SSE 等      │
│  │  /                │   │  URL    └─────────────────────────────┘
│  └─────────────────────────┘   │
└───────────────────────────────┘

关键点：界面不是客户端自己写的，而是加载 Harness 后端 dsh web 提供的页面。
Harness 服务端在返回的首页 HTML 里注入了 window.__DSH_BOOT__ 引导数据，所以
WebView2 只要打开 http://127.0.0.1:/ 就能得到和浏览器里完全一致的界面——
这个注入由服务端完成，客户端无需关心前端细节。

启动时的判断流程（核心方法）

客户端启动后，按下面顺序决定后端的来源：

1. 探测默认端口（DSHD_PORT，默认 3080）：发起一个本地 TCP/HTTP 请求，
检查返回的 HTML 是否包含 __DSH_BOOT__ 标记。
- 包含 → 说明已有一个 Harness 在跑，挂接它：直接用它的地址，不再启动新进程，
退出时也不去关闭它（避免误杀你现有的会话）。
- 不含（端口被别的程序占用）→ 按第 2 步，但改用 --port 0（由操作系统分配一个空闲端口）。
2. 自己拉起后端：执行 dsh --profile web --host 127.0.0.1 --port ，
并从它的标准输出里解析下面这行拿到真实地址：
dsh web: http://127.0.0.1:/

（即便用 --port 0，也能从这行得到最终端口。）
3. 加载：拿到 URL 后，让窗口 navigate 到这个地址。

整个判断和拉起逻辑都在 src-tauri/src/backend.rs 里，
启动 SDK 找、拉起、URL 解析全部不依赖第三方大库（甚至没用 HTTP 客户端库，直接手写
TCP 探测），这也是体积能做到这么小的原因之一。

如何找到 dsh 命令（解析优先级）

客户端需要执行 dsh 这个命令行工具，按下面顺序查找：

1. DSHD_DSH_BIN 环境变量 —— 显式指定的入口（.js 文件会用 node 运行，其它按可执行文件直接运行）；
2. DSHD_DSH_DIR 环境变量 —— 指定一个安装根目录，取其 node_modules/@deepseek-ai/dsh/lib/bin.js；
3. PATH 里已全局安装的 dsh 命令；
4. 自动扫描本机 %LOCALAPPDATA%\npm-cache\_npx\ 里已有的 dsh 缓存，选最新一份用 node 直接运行（绕开 npm 生成脚本在 Windows 上的兼容问题）；
5. 全部都没有 → npx -y @deepseek-ai/dsh 在线下载（首次需要联网）。

进程生命周期（退出清理）

- 若后端是本应用拉起的，关闭窗口时会用 Windows 的 taskkill /T /F 杀掉整棵进程树，避免残留；
- 若后端是挂接的现有实例，关闭窗口时不动它，你的浏览器会话继续正常。

零基础：从安装到运行

下面的步骤假设你对命令行完全不熟。每一步都会告诉你"输入什么、看到什么算成功"。

第 1 步：确认你的系统

- 需要 Windows 10 或 11（Win10 请先更新到较新版本）。
- 系统需要 WebView2 运行时：Win11 及大多数 Win10 已内置。若弹出"需要安装 WebView2"
的提示，点击提示里的链接下载安装一次即可（微软官方地址）。

第 2 步：安装 Node.js

Harness 后端是 Node.js 程序，所以需要 Node。

1. 打开浏览器，访问 https://nodejs.org ，点绿色的 LTS 下载按钮；
2. 双击下载好的 .msi 安装包，一路「Next」默认装完（不要改动默认选项）；
3. 验证是否装好：按 Win 键，输入 PowerShell，回车打开 PowerShell，输入并回车：
node -v

看到类似 v22.x.x 的版本号即成功（需要 ≥ 18，推荐 22+）。

第 3 步：安装 Rust（含 C++ 构建工具）

外壳是 Rust 写的，需要 Rust 编译环境。

1. 访问 https://rustup.rs ，下载并运行 rustup-init.exe；
2. 安装时遇到选择，直接按回车用默认选项（默认就是 MSVC 工具链）；
3. 再安装 Visual Studio 2022 Build Tools（C++ 链接器）：
- 访问 https://visualstudio.microsoft.com/visual-cpp-build-tools/ ；
- 下载运行后，在「工作负载」里勾选 「使用 C++ 的桌面开发」，点安装；
- 这一步约下载几个 GB，耐心等待。
4. 验证：新开一个 PowerShell，输入：
rustc -V

看到 rustc 1.xx.x 即成功。

说明：其实你也可以只记两条——装完 Node 和 Rust + C++ 构建工具，就能往下走。

第 4 步：获取项目代码

在 GitHub 建好仓库后，克隆到本地：

git clone https://github.com/Lucsimong/DSH-Desktop.git
cd DSH-Desktop

（如果你已经有这份代码，跳到下一步。）

第 5 步：构建产生可执行文件

进入项目目录后，任选一种方式：

方式 A（推荐，一条命令）：

.\scripts\build.ps1 -Release

方式 B（等价的原生命令）：

cd src-tauri
cargo build --release

- 首次构建会从网上下载几百个 Rust 依赖，需要数分钟，请耐心等它显示 Finished；
- 成功后产物在 src-tauri\target\release\dshd.exe（约 7.4 MB）。

若 PowerShell 提示"禁止运行脚本"，先执行一次：
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

询问时输入 Y 回车，再重试方式 A。

第 6 步：运行

最简单的方式——双击：

scripts\start-dshd.cmd

或者在 PowerShell 里：

.\src-tauri\target\release\dshd.exe

想让它常驻桌面/任务栏：右键 dshd.exe 或 start-dshd.cmd → 「发送到」→「桌面快捷方式」。

第 7 步：第一次启动会发生什么

1. 程序会先探测 3080 端口有没有已在运行的 Harness：
- 有（比如你正开着浏览器版）→ 直接复用，窗口秒开，两边还能看到同一份会话；
- 没有 → 程序自动拉起一个 Harness 后端，等它打印出地址后加载界面。
2. 窗口中间会先出现一个"正在启动…"的加载页，后端就绪后自动跳转到 Harness 界面。
3. 如果你本机还没有 dsh 命令，第一次会通过 npx 在线下载，需要联网，之后走缓存。

环境变量（进阶）

大多数情况不需要设置。仅在需要自定义时使用：

| 变量 | 作用 |
| --- | --- |
| DSHD_PORT | 期望的后端端口，默认 3080（被占用时自动改用随机端口） |
| DSHD_DSH_BIN | 显式指定 dsh 入口：.js 文件用 node 运行，其它按可执行文件运行 |
| DSHD_DSH_DIR | 指定一个含 node_modules/@deepseek-ai/dsh 的安装根目录 |
| DSHD_CWD | 后端进程的工作目录（Harness 的 agent 工作区），默认继承客户端 |
| DSH_HOME | Harness 数据目录（由 dsh 本身读取；默认 ~/.dsh） |

示例（指定端口为 4000）：

$env:DSHD_PORT = "4000"
.\src-tauri\target\release\dshd.exe

安装

普通用户：从 GitHub Releases 安装

最简单的安装方式是从 Releases 页面
下载安装包：

1. 下载最新版安装包——目前是 DSH-Desktop_0.1.0_x64-setup.exe（版本号会随发布更新）；
2. 运行它——按当前用户安装，无需管理员权限，并自动创建开始菜单项和桌面快捷方式；
3. 若系统缺少 WebView2 运行时，安装器会自动在线下载安装。

开发者：自行构建安装包

发布用的安装包由 GitHub Actions 在每次推送 v 标签时自动构建
（见 .github/workflows/release.yml）。若要本地构建：

cargo install tauri-cli --version '^2'   # 只需一次
.\scripts\build.ps1 -Installer

产物在 src-tauri\target\release\bundle\nsis\*.exe，可直接分享或作为 GitHub Release 附件发布。

安装包不包含 Node.js、dsh CLI、API 密钥或 ~/.dsh 用户数据——这些要么在目标机器上
已存在，要么由客户端在首次启动时自动准备。

验证结果

本机已实测通过（scripts/smoke-test.ps1）：

| 场景 | 结果 |
| --- | --- |
| 挂接模式：3080 已有 dsh web 时启动 | ✅ 不重复启动后端，窗口直接加载现有 GUI；关闭客户端后原实例不受影响 |
| 拉起模式：DSHD_PORT=0 启动 | ✅ 自动 spawn dsh web（新 node 进程），解析 stdout 的 dsh web: http://127.0.0.1: 并加载 |
| 退出清理 | ✅ 关闭窗口（WM_CLOSE）→ 客户端优雅退出 → 自己拉起的后端进程树被 taskkill /T /F 清理，零残留 |
| 后端就绪探测 | ✅ 通过 TCP 探测 + 响应 HTML 含 __DSH_BOOT__ 标记判定是否为 DSH GUI |
| 产物尺寸/内存 | ✅ 单文件约 7.4 MB，主进程工作集约 27 MB |

复现：.\scripts\smoke-test.ps1 -Attach 或 -Spawn（需先设置 DSHD_DSH_BIN）。

目录结构

DSH-Desktop/
├── dist/                        # 启动加载页（随二进制嵌入）
├── scripts/
│   ├── build.ps1                # 构建：默认 debug | -Release | -Installer
│   ├── start-dshd.cmd           # 一键启动（自动定位 dsh CLI 后拉起 dshd.exe）
│   └── smoke-test.ps1           # 双模式冒烟测试（-Attach / -Spawn）
├── src-tauri/
│   ├── src/
│   │   ├── main.rs              # Windows 入口（不显示控制台窗口）
│   │   ├── lib.rs               # Tauri 生命周期：建窗口、托管后端状态、退出清理
│   │   └── backend.rs           # 核心：后端探测 / 拉起 / URL 解析 / 进程树清理
│   ├── tauri.conf.json          # Tauri 配置：productName、NSIS 打包等
│   ├── Cargo.toml / Cargo.lock  # Rust 依赖
│   ├── build.rs                 # tauri-build 入口
│   └── icons/icon.ico           # 应用图标（dsh.ico）
└── README.md

隐私与安全

- 代码仓库不含任何密钥：无 API key、token、密码、私钥、.env 文件。
- 不含个人路径：代码里用环境变量（如 %LOCALAPPDATA%）而非硬编码的绝对路径，可移植。
- 数据留本地：会话记录、凭据都在本机 ~/.dsh（由 Harness 管理），客户端只负责起停服务，不收集、不上传。
- 后端仅监听 127.0.0.1（本机回环），不对外开放端口；--host 0.0.0.0 已被 Harness 主动禁用。

常见问题排查

Q：双击后没有任何窗口，或闪一下就没了？
在 PowerShell 里前台运行 .\src-tauri\target\release\dshd.exe，看报错信息。
最常见原因是没装 Node.js（node -v 无输出）或 Rust 构建工具没有 C++ 链接器。

Q：PowerShell 说"无法加载脚本，因为在此系统上禁止运行脚本"？
执行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned（输入 Y 确认）后重试。

Q：首次构建特别慢或下载失败？
Rust 依赖较大，属正常。国内网络可给 cargo 配镜像加速（写进 ~/.cargo/config.toml）：

[source.crates-io]
replace-with = "rsproxy-sparse"

[source.rsproxy-sparse]
registry = "sparse+https://rsproxy.cn/index/"

Q：提示找不到 dsh / npx 下载卡住？
可提前全局安装一次：npm i -g @deepseek-ai/dsh，之后客户端会优先从 PATH 找到它。

Q：端口 3080 被别的程序占了？
客户端会自动改用随机端口；也可用 $env:DSHD_PORT = "其他端口" 指定。

Q：我想同时用浏览器版和桌面版？
可以。客户端会自动挂接已有的 3080 后端，两边共用同一份本地数据。