离线应用安装 RaulLazaro/dsh-pwa-plugin

DSH PWA 插件

为 DeepSeek Harness 打造的 PWA 插件，加入离线支持，还能把应用装到桌面。

功能

- Service Worker，带智能缓存策略
- PWA Manifest，配好 maskable 图标
- 自动更新 —— 静默激活新版本
- 离线优先，针对静态资源
- 官方 DSH 鲸鱼图标 —— 取自上游 SVG favicon

安装

1. 添加为依赖

在 DSH web 配置档的 package.json 里：

{
"dependencies": {
"dsh-pwa-plugin": "file:~/workspace/dsh-pwa-plugin"
}
}

2. 注册插件

在配置档的 cordis.patch.yml 里：

- insert:
- id: dsh-pwa
name: 'dsh-pwa-plugin'

3. 重启 DSH

dsh web

生成 PNG 图标

插件自带预构建的 PNG 图标。要重新生成（需要 sharp）：

cd dsh-pwa-plugin
node scripts/generate-icons.js

脚本读取官方 public/favicon.svg，产出：

| 文件 | 尺寸 | 用途 |
| icon-192.png | 192×192 | 普通（any） |
| icon-192-maskable.png | 192×192 | Maskable（20% 安全区） |
| icon-512.png | 512×512 | 普通（any） |
| icon-512-maskable.png | 512×512 | Maskable（20% 安全区） |

工作原理

1. 宿主插件提供 /sw.js、/manifest.webmanifest 和图标文件
2. 它往 HTML 里注入一段 service worker 注册脚本
3. service worker 缓存静态资源（含图标），供离线使用
4. manifest 让应用可以按 PWA 安装
5. 自动检测更新，并静默激活
6. DSH 内置的 /favicon.svg 原样使用（不覆盖）

缓存策略

| 资源类型 | 策略 | 说明 |
| HTML | 网络优先 | 总是尝试拉取最新版本 |
| JS/CSS/字体/图片 | 缓存优先 | 有缓存就直接用缓存 |
| API 调用 | 不缓存 | 一律走网络 |

限制

- 需要 HTTPS 才能工作（localhost 除外）
- service worker 无法缓存 API 调用
- 更新需要刷新页面（检测到后自动刷新）

项目结构

dsh-pwa-plugin/
├── src/
│ ├── host/
│ │ └── index.js # Host plugin (Node.js)
│ └── sw.js # Service Worker
├── public/
│ ├── manifest.webmanifest # PWA Manifest
│ ├── favicon.svg # DSH whale icon (same as upstream)
│ └── icons/ # PWA icons (maskable + regular)
├── scripts/
│ ├── generate-icons.js # Icon generator (sharp)
│ ├── install.js # Verification script
│ └── verify.js # Verification
├── cordis.patch.yml # Plugin registration
├── LICENSE
└── package.json

测试

npm test

零依赖测试套件，跑在 Node 内置 runner（node --test）上：

- test/manifest.test.mjs —— manifest 必填字段、图标密度（普通 +
- test/icons.test.mjs —— 校验图标集（192/512 尺寸下可遮罩），并确认每个图标文件都真实存在于磁盘上。
- test/sw.test.mjs —— 让 service worker 跑在伪造的 self 上：install/activate 缓存生命周期、绕过规则（非 GET、非 HTTP 协议、/api、/plugins、/ws、/hooks、websocket 升级）、网络优先的 HTML 及其离线兜底、缓存优先的静态资源及其 200/basic 缓存校验，还有 GET_VERSION / SKIP_WAITING 消息。
- test/host.test.mjs —— 路由注册（sw、manifest、4 个图标、version）、响应头、index-HTML 脚本注入，以及 HMR 卸载时用到的 effect 清理。

License

MIT