dsh-pwa-launcher
把 DeepSeek Harness 变成真正的桌面应用：双击图标就能用。
Windows 10/11 · MIT · dsh 插件
它解决什么问题
你可能已经把 DeepSeek Harness 用 Edge/Chrome「安装为应用」固定到了桌面或任务栏。 那个图标看着像个 App，但它本质上只是一条命令：
msedge_proxy.exe --profile-directory=Default --app-id=<id> --app-url=http://127.0.0.1:3080/
它只是打开一个地址。 服务没跑的时候，你点下去看到的是一个错误页。
而这不是能绕过去的限制 —— 浏览器刻意不允许一个 PWA 快捷方式启动本机进程。 所以「点图标就把服务拉起来」这件事，必须由别的东西接管那一次点击。
这个插件就是那个东西。它会认出浏览器给你的那个快捷方式，保留它的图标和外观， 只把「要执行什么」换成启动器。你看到的东西一点没变，双击的行为变了：
服务没起 → 悄悄拉起来 → 等它就绪 → 用浏览器应用窗口打开界面 服务已在 → 直接开窗（毫秒级） 端口被别人占了 → 弹窗说清楚，不硬闯
装它之前 vs 之后
| 双击桌面图标 | |
|---|---|
| 装之前 | 服务没跑 → 错误页 |
| 装之后 | 服务没跑 → 自动拉起 → 界面打开；窗口关了服务还在 |
另外网页里会多一个入口：会话标题右侧的「⟳ 重启 | 版本」胶囊（见下文）。
安装
dsh plugin --profile web add https://github.com/liudapeng0311/dsh-pwa-launcher/archive/refs/heads/main.tar.gz
为什么是这个 tarball 直链，而不是
dsh plugin add dsh-pwa-launcher？ 这个包还没有发布到 npm，所以按包名装会失败。用上面的直链即可。为什么不用
github:liudapeng0311/dsh-pwa-launcher？ pnpm 会把它解析成git+ssh://，要求你配好 GitHub SSH key，否则报Host key verification failed。 上面这条不需要 SSH、不需要构建（本包是纯 JS，没有prepare脚本）。 想要「跟到某个版本」的话，把 URL 里的main换成 tag 名即可。
装完重启一次 dsh（Ctrl+C 停掉再跑）。插件会在启动时把启动器部署好、把图标接上。
首次生效后，桌面/开始菜单上就会出现 DeepSeek Harness 图标。
# 如果你本来就是手动跑 dsh 的
dsh web
卸载
# 1) 先把快捷方式还原（会把你原来那个浏览器 PWA 图标恢复原样）
powershell -File "$env:LOCALAPPDATA\DeepSeekHarness\scripts\shortcut.ps1" -Action Uninstall
# 2) 再从 profile 移除
dsh plugin --profile web remove dsh-pwa-launcher
顺序不要反。 先移除插件的话，图标会留在桌面上 —— 它其实还能用（启动器和
launcher.json 都还在），但已经没有任何东西会去刷新它了。
会话头部那个胶囊
界面上只有一个入口：会话标题右侧的 ⟳ 重启 │ 版本 胶囊，和 dsh 自己的
「在文件资源管理器中打开工作目录」排在同一行。
为什么它长在那里：本插件除了宿主半边，还有一个浏览器半边，注册进 dsh 的
conversation.session.header.utilities槽（open-in-app 的分裂按钮就在同一个槽里）。 由 React 跟着顶栏一起排版，所以天生不会和 dsh 自己的控件抢位置。早期的做法是往 index.html 注入脚本、把按钮悬浮在窗口右上角 —— 那个位置和 dsh 的 会话头部右上角（分栏视图按钮）重叠，于是需要一整套「扫描顶栏控件 + 整簇左移让位」 的坐标探测来补偿。那套东西已经删掉了，按钮也搬进了槽里。
注意：这个胶囊只在有会话的时候存在。dsh 在空白会话（还没开始对话）上会把整个 会话头部隐藏，连这个槽一起。所以刚打开应用时看不到它 —— 发一条消息就出来了。
⟳ 重启
把整个 DeepSeek Harness 连根重启：彻底停掉当前进程（正在跑的任务/会话会一起停）， 再自动拉起，当前窗口自己轮询到新服务并重连刷新。不用去双击桌面图标， 也不用管「关窗口只是关窗口」这件事。点击前有二次确认，之后会盖一张进度卡。
重启完成的判据是进程指纹变了并且新进程已就绪 —— 光收到
ready不够： 命令刚发出时老进程还没退，它也会答ready，只看这个会在服务真正重启前就刷新页面。
版本按钮
显示当前状态，点它就是干活：
| 显示 | 点一下会做什么 |
|---|---|
检查… |
什么都不做（正在等宿主后台那次检查的结果） |
↑ 有新版 x.y.z（高亮） |
升级：只有一个候选时直接二次确认；多个候选时先弹选版卡（见下） |
✓ 已是最新 |
重新检查一遍 |
已忽略 n |
重新检查一遍 |
未查到 |
重试一次（多半是网络抖动） |
allowSelfUpdate: false 时，↑ 有新版 只提醒、不安装，点它退化成「重新检查」。
每次 dsh 启动后，插件在后台只读地查一次 npm registry（node 内置 https 直连，带超时），
同时看 latest / next / alpha 三个通道，凡是有比你当前更新的版本就提醒 ——
把选择权交给你，不替你决定跟哪条流。
一次查不到不代表没更新。 到 npm 的连接会偶发抖动（并发请求时更明显，实测大约每 8 个 请求会挂掉 1 个），所以检查会自动重试 3 次（退避 0.4s / 1.2s），并且推迟到启动后 6 秒 才发第一个请求 —— 避开 dsh 自己引导 + 部署启动器那阵最忙的时候。失败时按钮的 tooltip 会写出 这次的具体原因（超时 /
ECONNRESET等）；离线时安静跳过，不影响服务、不弹窗。 HTTP 4xx 这类确定性失败不重试（重试也没用）。
宿主怎么算「推荐哪个」。 target = newer 里第一个未被忽略的项，而 newer 是按
updateChannels 的顺序（默认 [latest, next, alpha]，保守 → 激进）收集、且只收
严格比当前版本新的。所以推荐值是「最保守通道里的可更新项」，不是版本号最大的那个：
| 情况 | 候选 | 推荐 |
|---|---|---|
latest=0.1.6、alpha=0.1.7-alpha.2 |
两个 | 0.1.6（latest 优先） |
next=0.1.7-rc.1、alpha=0.1.7-alpha.2 |
两个 | 0.1.7-rc.1（通道更保守，且 semver 里 rc > alpha） |
next=0.1.7-rc.1、alpha=0.1.8-alpha.1 |
两个 | 0.1.7-rc.1（通道优先于版本号大小） |
latest 比当前版本旧、next 等于当前版本 |
只剩 alpha | alpha |
那条「通道优先于版本号」是有意的：
latest/next/alpha的排序本身就是对稳定性的表态。 但推荐只是推荐 —— 所以有了下面这张选版卡。
updateNotify: recommended-only时 alpha 根本不进候选，也就不会有选版卡。
选版卡：多个候选时自己挑
同时有 rc 和 alpha 可升时，宿主只能替你推荐一个（规则：按通道从保守到激进
latest → next → alpha，取第一个「比当前版本新且没被忽略」的）。这个推荐不等于「最新」
—— 比如 next=0.1.7-rc.1、alpha=0.1.8-alpha.1 时，推荐的是 rc，尽管按版本号 alpha 更大。
所以候选多于一个时，点版本按钮会先摆出选版卡：
升级到哪个版本？
当前版本 0.1.5-rc.3。下面是这次查到的全部较新版本，按通道从保守到激进排列。
◉ 0.1.7-rc.1 候选通道 · 已选
○ 0.1.8-alpha.1 前沿通道
[ 升级到 0.1.7-rc.1 ] [ 取消 ]
预发布版本（rc / alpha）可能不稳定。升级会停掉当前服务，失败会自动回滚。
几条行为约定：
- 默认选中宿主推荐的那个，多候选时不会替你决定，但也不会让你白挑一次；
- 卡片里列的是
newer的全部候选，服务端白名单校验的也正是这个列表 —— 所以 列表里任何一个都装得成，不只是被推荐的那个； - 「曾忽略」的候选照样可以选（只是标一下）。选了它提醒会恢复 —— 装完你就是那个 版本了，旧版本的忽略项不再匹配；
- 选版期间不算「进行中」：重启按钮照常可用，再点一次版本按钮就收起卡片；
- 提交前仍有一次系统确认框（写清目标和当前版本，以及失败会回滚）。
升级会真正动手：停服务 → 备份 → npm install → 校验 →
自动重启并回连当前窗口；任何一步失败都会自动回滚到原来的版本。
整个过程有一张进度卡，超时或失败会把原因写出来（并可收起继续用）。
它会自己判断你的 dsh 是怎么装的，因为「在哪跑 npm install」因装法而异：
- 本地 npm 树（npx 缓存、本地工程、锁版本的本地安装）——从运行入口往上找到 声明了
@deepseek-ai/dsh依赖的那个package.json，在它那里装- 全局安装（
npm i -g）——用npm install -g两种都认不出时会明确报错并告诉你怎么手动装，绝不会猜一个目录乱装。
校验以运行入口自己的
--version为准，而不是只看package.json里的版本号 —— 前者才是「你实际在跑什么」。
配置
改本包里的 cordis.patch.yml 中 pwa-launcher 那一行的 config，重启一次 dsh 生效。
| 键 | 默认 | 说明 |
|---|---|---|
shortcutName |
DeepSeek Harness |
图标名字，也是「优先接管哪个」的依据 |
adoptBrowserShortcut |
true |
接管浏览器给你的 PWA 快捷方式（保留其图标）。false = 自己新建一个 |
desktop / startMenu |
true |
往哪几个地方放图标 |
browser |
auto |
auto / edge / chrome / default |
appMode |
true |
应用窗口（无地址栏，和 PWA 一样）还是普通标签页 |
startTimeoutSec |
120 |
等服务就绪的上限 |
installDir |
'' |
留空 = %LOCALAPPDATA%\DeepSeekHarness |
checkForUpdates |
true |
关掉则既不查、也不注册相关路由（版本按钮会停在「检查…」） |
allowSelfUpdate |
true |
允许版本按钮一键升级；false = 只提醒，点它只重新检查 |
updatePackage |
@deepseek-ai/dsh |
拿哪个包的 dist-tags 当「可升版本」来源 |
updateVersionPackage |
@deepseek-ai/dsh-base |
拿哪个包的安装版本当「当前版本」（真正跑的应用核心） |
updateChannels |
[latest, next, alpha] |
关注哪些通道，顺序 = 保守 → 激进，第一个是「推荐」 |
updateNotify |
all |
all = 任一通道有更新都提醒；recommended-only = 只按主通道 |
updateRegistry |
https://registry.npmjs.org |
镜像 / 私有源改这里 |
updateCheckTimeoutMs |
12000 |
单次查询超时；超时按「本次没查到」安静跳过（会自动重试） |
为什么「当前版本」默认取
dsh-base而不是@deepseek-ai/dsh？ dsh 有两棵版本树： CLI 包@deepseek-ai/dsh是启动器壳，而实际渲染界面的应用核心是@deepseek-ai/dsh-base， 两者版本可能不一致。控件显示的是你真正在跑的应用那一个。 「可升版本」则取自 CLI 包的 dist-tags（它的latest/next/alpha标签是干净的）。
avoidAppButtons已经没有了。 那个配置是给早期「悬浮在右上角」的按钮做顶栏避让用的： dsh 自己的顶栏控件开始对话后才出现，位置和它们重叠，所以只能靠坐标探测整簇左移。 按钮搬进会话头部的槽之后，重叠问题从根上消失，那套探测和这个配置一起删掉了。
手动操作
# 只拉服务不开窗
powershell -File "$env:LOCALAPPDATA\DeepSeekHarness\scripts\launch.ps1" -NoOpen -Visible
# 停服务
powershell -File "$env:LOCALAPPDATA\DeepSeekHarness\scripts\stop.ps1"
# 重新接管 / 还原快捷方式
powershell -File "$env:LOCALAPPDATA\DeepSeekHarness\scripts\shortcut.ps1" -Action Install
powershell -File "$env:LOCALAPPDATA\DeepSeekHarness\scripts\shortcut.ps1" -Action Uninstall
出问题先看日志
%LOCALAPPDATA%\DeepSeekHarness\logs\desktop.log 启动器（双击图标那条链路）
%LOCALAPPDATA%\DeepSeekHarness\logs\update.log 升级 / 回滚
%LOCALAPPDATA%\DeepSeekHarness\launcher.json 当前启动参数（每次 dsh 启动重写）
会话头部那个胶囊一直显示「检查…」
它读的是宿主后台那次检查的结果，自己不联网。一直停在「检查…」基本是两种情况：
- 检查被关掉了。
checkForUpdates: false时宿主不注册/pwa-launcher/update-check， 按钮拿不到任何结果。改cordis.patch.yml里那一行再重启。 - 配置被 GUI 覆盖了。 在设置里改过本插件的配置时，用户层会压住
cordis.patch.yml那一层。去插件的设置卡片里确认checkForUpdates是开的。
会话头部没有这个胶囊
它会注册失败就整体不出现（渲染不出来时宁可不显示，也不留一个空白按钮）。按顺序查：
- 页面完整刷新过一次没有 —— 浏览器半边是在首次加载页面时随 boot 图一起注册的。
- 浏览器控制台有没有
client-modules:开头的报错（那是浏览器半边的加载失败）。 - 会话是否已经存在 —— 这个槽是 session 作用域的，空白页（还没有会话）上没有头部， 自然也不会有这个胶囊。
它内部怎么做的
双击图标
│
├─ wscript.exe <installDir>\launcher.vbs ← 无窗口入口
│ └─ powershell ...\scripts\launch.ps1
│ ├─ 端口上已经有 dsh？ ── 有 ──► 直接开窗
│ ├─ 被别的程序占了？ ── 是 ──► 弹窗说清楚，不硬闯
│ └─ 都没 ─► 隐藏启动 dsh web（cwd = 你原来的 workspace）
│ ├─ 等到 HTTP 开始应答
│ └─ 用 msedge_proxy.exe --app-id=... --app-url=<带令牌的地址> 开窗
│
└─ 关掉窗口不影响服务，它是以 detach 方式起的
网页里那两个控件只用 dsh 的官方扩展点（webServer + connection 两个服务，
不 import 任何 dsh 内部包），没有改 dsh 核心、也不依赖前端内部结构
（所以 dsh 升级不会把它们弄坏）：
ctx.webServer.register({ path }) 注册下面这几条自定义路由
ctx.connection.authorizeIndex(...) 复用 dsh 自己的会话鉴权（未登录返回 401）
ctx.connection.authenticatedUrl(...) 取本次进程的带令牌地址
POST /pwa-launcher/restart 触发一次外部重启
GET /pwa-launcher/restart-status 前端轮询新进程起来了没有（带进程指纹 nonce）
GET /pwa-launcher/update-check 后台那次版本检查的结果（含 canApply）
POST /pwa-launcher/update-check 手动重新检查一次（真连 registry）
POST /pwa-launcher/update-dismiss 忽略 / 恢复提醒某个版本
POST /pwa-launcher/update-apply 触发一次外部升级
界面上的胶囊走的是另一条路：本包同时是一个双面包，package.json 里声明了
dsh.client，浏览器半边入口是 ./client（lib/client.js）：
package.json "dsh": { "client": { "platform": "web", "inject": [...] } }
"exports": { "./client": "./lib/client.js" }
lib/client.js window.__ModuleLoader__.load({ id, factory }) ← 惰性 CJS 工厂
└─ ctx.slots.register(conversation.session.header.utilities, …)
lib/client.js 是构建产物，源文件在 client/src/：
node client/build.mjs # 合并 client/src/*.js → lib/client.js（改完源文件必须跑）
为什么要有这一步：dsh 的浏览器半边不是普通 ESM，而是「惰性 CJS 工厂」—— 外层必须是
window.__ModuleLoader__.load({ id, factory })，模块体在工厂闭包里、 import 变成显式require(...)。仓库内那些 TS 插件靠tsdown的clientBundlepreset 产出这个形状，而那个 preset 没有随包发布（见dsh-client-modules的 README：「仓库外的插件得自己复现这个构建」）。这里用 30 行 node 脚本自己复现， 不引任何第三方构建依赖。构建器只允许
require('react')一个模块 —— 它在浏览器平台种子表 （PLATFORM_MODULES）里。其它@deepseek-ai/dsh-client-ui-*包虽然在种子表里， 但它们的导出名不在本包能核对的契约里，用它们等于把「按钮能不能画出来」 赌在别的包的内部实现上，所以这个控件只用 React + 自己的 CSS。
为什么不原地重启/升级自己：插件就跑在被重启的那个 dsh 进程里，自杀再原地复活不干净
也做不到（Windows 上覆盖正在运行的文件还会撞锁）。所以它 spawn 一个游离于 node
进程树之外的 wscript → *.vbs → *.ps1 来编排，这样才停得掉自己、也换得掉自己。
兼容性
实测通过的环境：dsh 0.1.5-rc.1 / 0.1.5-rc.2 + Node 24 + Edge（Windows 10/11）。
这一行是给人看的，不是机器读的声明。
package.json里不再写dsh.compatibility—— 那个字段不在 DSH 的 manifest schema 里（官方dsh-package-manifest只定义bundle/profile/client/configTrees/sessionFormatMigration/moduleFallback）， 整个 DSH runtime 里没有任何代码读它，写了也只是装饰，反而容易让人以为装错了版本会被拦住。另外注意「dsh 版本」本身有两棵树：CLI 壳
@deepseek-ai/dsh和实际渲染界面的应用核心@deepseek-ai/dsh-base/dsh-web-app，两者可以不一致（壳 rc.1 配应用 rc.2 是实测存在的 组合）。上面的兼容环境按应用核心记。
已知限制
- 仅 Windows。
package.json声明了"os": ["win32"]，代码里还有一道运行时守卫 —— 其他系统上装不上，万一装上了也不会做任何事。 - 尚未发布到 npm。 所以
dsh plugin add dsh-pwa-launcher这种按包名的写法现在会失败， 请用上面「安装」一节里的 tarball 直链。 - 如果 Edge/Chrome 哪天把 PWA 快捷方式改回原样，下一次 dsh 启动时插件会自动再接管一次。
- 同时跑多个 dsh 实例（多 profile / 多端口）时，
launcher.json是后写覆盖， 图标会指向最后启动的那个。 - 接管只认「名字相同」或「
--app-url指向当前端口」的 PWA 快捷方式；两者都不匹配就 自己新建一个，不会去动别人的快捷方式。 - 自助升级覆盖「本地 npm 树」与「
npm i -g全局安装」两种；认不出的装法会明确报错并 提示你手动npm install @deepseek-ai/dsh@<版本>。只提醒、给版本号这部分不受影响。
关于开窗用的令牌
dsh 每次启动生成一个新的 launch token，未认证请求返回 401（不是错误页，
所以「看到 401」就代表服务已经就绪）。插件优先在进程内直接向 connection
服务要带令牌的地址（写进 launcher.json，首次双击图标前可能还没有这个文件）：
- 主路径：
launcher.json里的带令牌地址 —— 永远和当前进程一致。 - 兜底：
logs\dsh-stdout.log里的 token 行。这条只在「dsh 是被本启动器拉起的」 前提下才属于当前进程 —— 你自己手动起的 dsh，日志里留的是上一轮的旧令牌， 拿它开窗只会得到一个 401 空白页。
另一个容易踩的点：接管过的快捷方式，第二次还要找得到。 接管之后它的目标不再是
msedge_proxy.exe，所以判定顺序是「可接管的 PWA 快捷方式 → 已指向启动器的快捷方式 → 新建」。
否则第二轮会误判成「没找到」，退回备用图标把 Edge 给你的图标覆盖掉。
原始命令行（以及那个图标的位置）记在 launcher.json 同目录的 shortcut-origin.json 里 ——
卸载时就是靠它还原成原样。
开发
npm test # 全部：构建浏览器半边 → 四组测试
npm run build:client # 只重建 lib/client.js（改了 client/src/ 之后必须跑）
npm run test:plugin # 浏览器半边：胶囊、词典、点击、重启/升级状态机（26 项）
npm run test:host # 宿主路由：注册、鉴权、握手字段、版本白名单（11 项）
npm run test:retry # 更新重试与 semver 白名单（12 项）
npm run test:update # 更新探测（PS 5.1，7 项）
测试的取法是「截获插件真正加载的那段代码，放进假环境里跑」， 以及「真起一次探测流程看它认不认得出装法」——验的是实际会跑到用户机器上的代码， 而不是对它的复述。
test/plugin-test.mjs 刻意不装 React / jsdom：本包没有第三方依赖，测试也不该为了
跑一次就引入它们。里面自带一层够用的 React 替身（createElement 返回可遍历的节点树，
函数组件当场调用，useState / useEffect / useRef 在 render 期间同步落实），
验的是 lib/client.js 本身。四个已经踩过的坑写在文件注释里，别改回去：
check()必须支持异步——一半用例要走 promise，同步版本会把断言失败变成 未处理的 rejection，测试照样报「全部通过」。- 沙箱里
window和globalThis必须是同一个对象（浏览器就是这样）。 搭成两个对象的话，globalThis.__DSH_DL_NONCE__读到undefined， 「指纹没变就不跳转」那条用例会假装通过。 createElement必须当场调用函数组件，否则进度卡那类断言一直在看一个函数对象。- 等异步要用
fire(定时器)await 定时器回调返回的 promise，别用「空转 N 个微任务」 去赌链条长度。
test/host-route-test.mjs 需要一个「启动器已就位」的假安装目录（里面放空的
restart.vbs / update.vbs），否则断言会撞在 503 上、根本走不到要验的逻辑。
License
MIT © 2026 llsix
No comments yet. Be the first to write one.