haoliangwu/dsh-pwa

dsh-pwa

让正在运行的 dsh web 实例可作为 PWA 安装——包含 manifest + service worker + 图标，并支持 basePath 以适配反向代理部署。

一个用于 DeepSeek Harness 的纯宿主端插件。Web 前端在其 dist 中已经附带了 manifest 和 favicon，但没有 service worker 或 SW 注册脚本——因此 Chrome 的可安装性检查会失败。本插件填补了这一空缺，并允许应用挂载在反向代理的子路径下。

- 一行安装，无需构建步骤。 lib/ 和 assets/ 已提交——git 安装即可直接使用。
- 恰好填补一个空缺。 原版 dist 已经附带了 manifest 和 favicon；本插件添加了缺失的 service worker + 注册脚本，从而使 Chrome 的可安装性检查通过。
- 反向代理就绪。 每条路由和 URL 都以 basePath 为根，并带有规范化处理（''/'/' → /，/dsh → /dsh/，……），且拒绝包含 ?/# 的值。
- 五条路由，零每请求读取。 manifest.webmanifest、sw.js、icon-192.png/icon-512.png、favicon.svg——静态资源在 apply 时缓存于处理函数闭包中。

安装

dsh plugin --profile web add github:haoliangwu/dsh-pwa

已构建的 lib/ 和 assets/ 已提交，因此 git 安装只需一行——无需 prepare 脚本，无需构建步骤。安装后重启 dsh --profile web（bundle 层堆叠在启动时组合）。

配置

basePath 默认为 /（安装在源站根路径）。对于挂载在 /dsh/ 的反向代理部署，请通过 insert 形式将插件添加到你的 profile 的 cordis.patch.yml（~/.dsh/profiles/web/cordis.patch.yml）中（config-overlay 形式只能调整已在 dsh.profile.bundles 中列出的插件）：

- insert:
- id: dsh-pwa
name: dsh-pwa
config:
basePath: /dsh/

在 dsh plugin add 安装后，裸的 - id: dsh-pwa 行已经就位；只需追加 config: 块来调整 basePath。

规范化会自动应用：''/'/' → '/'，'/dsh' → '/dsh/'，'dsh/' → '/dsh/'，'/dsh/' 保持不变。包含 ? 或 # 的值会被拒绝。

工作原理

在 apply(ctx, config) 时，插件在 ${basePath}pwa/* 下注册五条 WebServer 路由：

- manifest.webmanifest → Web manifest，在 JS 中构建，URL 以 basePath 为根，以 application/manifest+json 提供
- sw.js → assets/sw.js，以 text/javascript 提供
- icon-192.png / icon-512.png → assets/icon-192.png / assets/icon-512.png，以 image/png 提供
- favicon.svg → assets/favicon.svg，以 image/svg+xml 提供

每个静态资源在 apply 时读取一次并缓存于处理函数闭包中（无每请求磁盘读取），返回的 disposer 通过 ctx.effect 释放，以便 HMR/卸载时清理。
它还调用 ctx.webServer.tapIndex(transform) 来重写 index.html：

- 将  重新指向 ${basePath}pwa/manifest.webmanifest
- 将  重新指向 ${basePath}pwa/favicon.svg
- 在  之前注入一个 serviceWorker.register('${basePath}pwa/sw.js', { scope: '${basePath}' }) 脚本

验证

1. 启动 dsh --profile web。
2. 打开 Chrome DevTools → Application 面板 → Manifest。确认名称、图标（192/512/svg）以及以 basePath 为根的 start_url/scope。
3. Application → Service Workers 应列出一个来自 ${basePath}pwa/sw.js 的活动 worker。
4. 打开 Lighthouse（或查看 Application → 可安装性横幅）——该站点现在应通过安装检查清单，并在首次访问时显示 beforeinstallprompt。

从源码构建

pnpm install
pnpm gen-icons   # regenerates assets/icon-192.png + assets/icon-512.png from assets/favicon.svg
pnpm build       # emits lib/index.js, lib/invariant.js
pnpm test        # config normalization + manifest/tapIndex unit tests

lib/ 和 assets/ 已提交，因此 git 安装无需构建步骤即可工作。更改源码后，运行 pnpm build（当图标源更改时还需运行 pnpm gen-icons）并提交这两个目录树。

许可证

MIT