KLucenの启示录

为什么会有这个插件#

dsh web 是本地优先的服务,日常用其实挺舒服:浏览器打开就是完整 GUI,不占资源、不上云。但「本地服务」嘛,总有点桌面应用才有的别扭感:

• 启动要开终端:先找到终端,敲 dsh web,等它起来,再手动开浏览器;
• 退出没入口:界面里没有「关掉服务」的按钮,关掉浏览器只是断开连接,服务还在后台占着 3080 端口,要么留着吃内存,要么回终端 Ctrl+C。

其实之前有 @linxin666/dsh-desktop-launcher 这个插件解决过类似问题,但它已经退役了。与其依赖别人维护,不如自己动手独立重建一个:能按自己的习惯调整,许可证干净(Apache-2.0,派生关系见仓库 NOTICE),于是就有了这个插件。

它能做什么#

插件是双面结构:

• Host 端 插件(注入 webServer),提供两个 API,负责「生成桌面图标」和「优雅退出」;
• Client 端:加载进 dsh web 页面,右下角多出两个小按钮。

整体就是下图这么个关系:

1
┌─────────────────── dsh web 进程(Host) ───────────────────┐
2
│  /api/dsh-desktop_quick_launcher/create   → 生成桌面图标   │
3
│  /api/dsh-desktop_quick_launcher/shutdown → 优雅退出进程   │
4
│              ▲                               ▲           │
5
│              └────────── fetch ──────────────┘           │
6
│   Client(浏览器右下角悬浮按钮):                           │
7
│     ⏻ 一键退出 · ＋ 一键生成/刷新桌面图标                  │
8
└──────────────────────────────────────────────────────────┘

安装#

还没发布到 npm,先走 GitHub:

1
dsh plugin --profile web add github:KLucen/dsh-desktop_quick_launcher
2
# 重启 dsh web 后生效(客户端产物是启动时装载的)
3
dsh web

直连不了 github.com 的话(比如在墙内),用镜像地址:

1
dsh plugin --profile web add "https://gh-proxy.com/https://codeload.github.com/KLucen/dsh-desktop_quick_launcher/tar.gz/refs/heads/main"

重启后进页面,右下角应该能看到按钮了;点「生成图标」→ 桌面出现 DSH-Web → 以后双击就能开,用完点电源按钮就能关,再也不用为它专门开终端了。

小提醒:第一次双击启动时服务要冷启动(最长 150 秒),别在就绪前反复双击——多个脚本实例会各自拉起一个 dsh web,后来的会因 3080 端口被占用而退出(日志里会提示),等第一次启动完成就好。

踩坑记录(写给想写 dsh web 插件的人)#

开发过程中最折腾的不是功能本身,而是 Client 端产物怎么让 dsh web 正常加载:

• DSH 的浏览器端 loader 要求每个插件的 ./client 入口是 classic script,并且必须通过 window.__ModuleLoader__.load({ id, factory }) 自注册(react/react-dom 是由 loader 的 require 注入的);
• 如果直接发一个纯 ESM 的 client.mjs,dsh web 会启动中止,报 loaded without registering ... via ModuleLoader.load;
• 解决方案:pnpm build 里用 esbuild 做一个包装步骤(scripts/wrap-client.mjs)产出 lib/client.js,再在 VM 里校验产物(scripts/verify-client.mjs)。
• 血泪教训:别图省事用 PowerShell 手写包装文件——会破坏 UTF-8,界面中文直接变乱码,老老实实从源码 rebuild。

手动升级也有个坑:直接 bump 版本后 pnpm install,顶层 node_modules 里的条目可能还链着旧版本的 store 目录。正确姿势是先 dsh plugin --profile web remove dsh-desktop_quick_launcher,再重新 add。

已知限制(如实说)#

• 退出按钮会终止整个 dsh web 进程:正在跑的会话/任务会被中断(会话有持久化,重启后可恢复);
• /create 和 /shutdown 刻意只限 loopback:通过远程浏览器连接局域网暴露的服务时,这两个按钮不可用;
• Windows 下生成的图标固定叫 DSH-Web.lnk,同名快捷方式会被覆盖;
• macOS / Linux 的启动脚本由同一套模板生成,但主要在 Windows 上开发验证,那边有问题欢迎带 launcher.log 反馈;
• SDK 依赖锁定在 @deepseek-ai/* 0.1.2-rc.1 一线,会随 DSH 发布节奏更新。

尾巴#

至此,dsh web 终于有点「正经本地应用」的样子了:桌面上双击图标就能开,用完点一下电源按钮就走,不用再记命令、不用再找终端。

如果这个插件对你有用,欢迎去 GitHub 仓库 点个 Star,有问题或建议直接开 issue;中文 README 里有更完整的安装和故障排查说明。

水完这篇,证明博主还活着(确信)。