dsh-desktop

dsh-desktop

DeepSeek Harness(dsh web)的 Windows 桌面壳(Go + WebView2)——把 DSH Web UI 装进原生窗口, 而不是丢进浏览器标签页。可作 DSH 插件 bundle 发布,在插件市场(dshmarket)被发现,通过 dsh plugin 或 npm 一键安装、更新。

---

演示

占位:主窗口加载 DSH Web UI、加载态/错误态示意。

---

是什么 / 为什么

dsh-desktop 是 dsh web(默认 http://127.0.0.1:3080)的壳,只做四件事:

• 内嵌渲染:WebView2 加载 DSH Web UI。
• 服务生命周期:探测并静默启动/复用/停止 dsh web 后端。
• 单实例防重:重复启动时激活已有窗口并退出。
• 打包体验:console 子系统构建(GUI 启动时隐藏控制台)+ DeepSeek 图标 + 加载/错误页。

为什么值得用:相比直接 dsh web 在浏览器开标签页,本壳给你一个独立的原生窗口、 单实例(不会重复弹窗/堆积标签页)、默认复用已在跑的服务(二次启动更快),且 GUI 启动时不闪黑色控制台。

边界:它不承载任何 Harness 逻辑——/api 的执行/读写库、workflow 等能力全部由 dsh 负责,本壳只负责把 Web UI 包进 Windows 窗口。

需求与设计见产品 PRD(V1.1)与技术设计。

---

目录

• 环境要求
• 安装与更新
• 快速上手
• 配置
• 构建
• 目录结构
• 贡献与安全
• 许可与商标
• 文档

---

环境要求

场景	需要什么
终端用户(下载 EXE)	Windows 10 (1803+) / Windows 11;WebView2 Evergreen 运行时(Win11 预装,Win10 需装)
运行时(任何场景)	全局安装 dsh(npm i -g @deepseek-ai/dsh),且 node、dsh 均在 PATH
构建者(从源码)	额外需要 Go 1.21+(含 CGO)+ GCC/mingw-w64;重建图标时才需要 Node + sharp

---

安装与更新

1. GitHub Releases 直接下载(终端用户推荐)

到 Releases 下载 dsh-desktop-win-x64.exe,双击即可。该 EXE 内置自更新:

.\dsh-desktop.exe --check-update   # 检查是否有新版本(输出到控制台)
.\dsh-desktop.exe --update         # 下载并应用,退出(不弹窗体;请重新运行以使用新版本)

说明:这两个命令是纯 CLI 命令,结果直接输出到控制台(stdout/stderr),并同时写入 %LOCALAPPDATA%\dsh-desktop\dsh-desktop.log,不再弹出原生提示框,也不弹窗体。

控制台同步:该 EXE 用控制台子系统构建(不再用 -H=windowsgui),所以 --version/ --check-update/--update 在 PowerShell/cmd 中会像普通命令一样同步等待并内联输出,无副作用。

GUI 启动:不带这些 flag 启动时,程序会 ShowWindow(SW_HIDE) 隐藏双击产生的控制台窗口 (双击有极短暂的黑框闪现);从已有终端(PowerShell/cmd)启动 GUI 时会复用该终端控制台, PowerShell 会阻塞直到窗体关闭,或在已有实例时激活现有窗体并快速退出。

2. npm / dsh plugin(插件市场发现与一键管理)

本项目是 DSH 插件 bundle(npm 包,package.json 声明了 dsh.bundle),可被插件市场 (dshmarket 等)发现并一键安装:

# 通过 npm 全局安装
npm i -g @andykwok/dsh-desktop
dsh-desktop

# 通过 dsh 插件系统安装到某个 profile(会初始化/复用该 profile)
dsh plugin --profile web add github:andykwokatgithub/dsh-desktop

更新:

npm update -g @andykwok/dsh-desktop   # npm 途径
dsh plugin --profile web update          # dsh 插件途径(自动激活升到新版本的 bundle)

注:dsh plugin add github:... 会安装 git 源并运行包的脚本;pnpm 可能要求先在 profile 的 pnpm-workspace.yaml 的 allowBuilds 里放行本包,命令失败时按 pnpm 提示操作即可。 npm 途径安装后,命令是 dsh-desktop(不带 .exe),没有 install 脚本——预编译 EXE 已内置, 首次运行 dsh-desktop 时自动拷贝到 %LOCALAPPDATA%\dsh-desktop\dsh-desktop.exe(不在 PATH)并启动, 不联网。

3. 从源码构建(贡献者)

见构建。

---

快速上手

# 通过 npm / dsh plugin 安装后,命令是 dsh-desktop(不带 .exe):
dsh-desktop

# 直接使用从 GitHub 下载或本地构建的 EXE:
.\dsh-desktop.exe

npm 安装后,真正的二进制在 C:\Users\<你>\AppData\Local\dsh-desktop\dsh-desktop.exe,并不在 PATH 上;dsh-desktop 命令会把它拷贝到位并启动。想直接双击/引用它,可用上面这个路径。

典型场景:

• 冷启动(服务未跑):自动 dsh web --no-open 拉起服务,先显示加载态,健康后再跳转 UI。
• 热启动(服务已在跑):健康校验通过后直接复用,快速进入(≤3s)。
• 重复启动(窗口已存在):激活已有窗口并置顶(即使最小化),新进程立即退出。

---

配置

命令行 flags(--url --host --port --command --stop-on-exit --devtools --context-menu --startup-timeout --poll-ms --width --height --title --version --check-update --update):

Flag	默认值	说明
--url	（空，自动派生）	DSH Web UI 地址。可选覆盖；一旦设置必须与 --host/--port 一致（校验不通过即报错），为空时由 --host+--port 派生
--host	127.0.0.1	健康探测与 spawn 的绑定 host(禁用 0.0.0.0)
--port	3080	dsh web 的监听端口(1-65535)
--command	web	要 spawn 的 dsh 子命令(web = --profile web 别名)
--stop-on-exit	false	关闭窗口时是否同时停止 dsh 服务(默认保留,二次启动更快)
--devtools	false	开启 WebView2 开发者工具(安全默认:关闭)
--context-menu	true	保留 WebView2 默认右键菜单(默认开启;如需禁用传 --context-menu=false)
--startup-timeout	30	等待服务就绪的超时(秒,须>0)
--poll-ms	500	健康校验轮询间隔(毫秒,须>0)
--width	1200	窗口宽度(须>0)
--height	800	窗口高度(须>0)
--title	DeepSeek Harness	窗口标题(仅用于显示;单实例定位不依赖标题)
--version	false	打印版本并退出
--check-update	false	检查 GitHub Releases 是否有新版本并退出
--update	false	下载并应用最新版本,然后退出

参数校验：--host/--port/--width/--height/--startup-timeout/--poll-ms/--url 在启动前做语义校验， 值非法即在控制台(CLI 命令)或原生对话框(GUI 启动,无控制台)中报错并退出。 规范写法为双横杠 --flag；Go 的 flag 包同时兼容单横杠 -flag 输入。

---

构建

推荐(也会内嵌 DeepSeek 图标):

.\build.ps1

或直接构建(默认即 console 子系统,无需 -H=windowsgui):

go build -o dsh-desktop.exe .

版本号可通过 build.ps1 -Version X.Y.Z 或 -ldflags 注入:

.\build.ps1 -Version 1.2.3
go run . -version   # -> dsh-desktop 1.2.3

构建形态:出于让 CLI 命令在 PowerShell/cmd 中同步输出等考量,EXE 用 console 子系统构建 (不再用 -H=windowsgui)。GUI 运行时 main.hideConsole() 会隐藏双击产生的控制台窗口(有极短的 黑框闪现);从已有终端启动 GUI 时复用该终端控制台,PowerShell 会阻塞直到窗体关闭。 webview_go 依赖 CGO,需要本机 Windows + GCC;不能跨平台交叉编译。 运行 dsh-desktop.exe 会真的拉起 dsh web,不要在无 DSH 环境时盲目运行;验证请用 go run . -version 或单测。

应用图标

• assets/deepseek.ico(16–256px)、assets/deepseek-256.png。
• tools/make-icon.mjs 用 sharp 从官方 SVG 重新生成 ICO。
• rsrc_windows_amd64.syso 内嵌图标;build.ps1 在 ICO 更新时自动用 github.com/akavel/rsrc 重建。

---

目录结构

main.go                         入口(配置→单实例→服务→窗口→消息循环;含自更新命令)
internal/config/                运行配置与 flag;Version 常量
internal/service/               服务探测/spawn/生命周期/进程树清理
internal/singleinstance/        互斥体+原生窗口类+激活消息+Win32 封装
internal/update/                GitHub Releases 自更新(校验+下载+应用)
internal/webview/               安全脚本与外部链接交接
internal/ui/                    go:embed 的 loading/error 页
bin/                            npm 启动器
scripts/fetch-exe.mjs           下载并校验预编译 EXE(npm postinstall)
cordis.patch.yml                DSH bundle patch 层(市场/插件系统识别)
assets/                         应用图标
tools/make-icon.mjs             用 SVG 重新生成 .ico
rsrc_windows_amd64.syso         嵌入图标的资源对象
build.ps1                       一键构建
.github/workflows/              CI 与发版流水线
docs/                           PRD + 技术设计 + 发布指南

---

贡献与安全

• 贡献:环境要求、开发命令与提交约定见CONTRIBUTING.md。
• 安全:漏报私报方式、下载/更新校验与品牌资产关注点见SECURITY.md。
• 变更日志:见CHANGELOG.md(Keep a Changelog + 语义化版本)。

---

许可与商标

MIT License(详见LICENSE)。项目内置的 DeepSeek 鲸鱼图标及其品牌元素属于 DeepSeek 方,本许可不授予商标/Logo/品牌资产使用权,相关使用需另行取得品牌方许可。

---

文档

• 需求基线:docs/dsh-desktop-prd.md
• 技术设计:docs/dsh-desktop-technical-design.md
• 发布/收录/安装/更新指南(面向市场与维护者):docs/publish.md
• README 自身的需求基线:docs/dsh-desktop-readme-prd.md