RaulLazaro/dsh-pwa-plugin

DSH PWA 插件

用于 DeepSeek Harness 的 PWA 插件，添加离线支持和安装为应用的能力。

功能特性

- Service Worker，采用智能缓存策略
- PWA Manifest，带有合适的可遮罩图标
- 自动更新 —— 静默激活新版本
- 离线优先，针对静态资源
- 官方 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 | 常规（任意） |
| icon-192-maskable.png | 192×192 | 可遮罩（20% 安全区） |
| icon-512.png | 512×512 | 常规（任意） |
| icon-512-maskable.png | 512×512 | 可遮罩（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          # 宿主插件（Node.js）
│   └── sw.js                 # Service Worker
├── public/
│   ├── manifest.webmanifest  # PWA Manifest
│   ├── favicon.svg           # DSH 鲸鱼图标（与上游相同）
│   └── icons/                # PWA 图标（可遮罩 + 常规）
├── scripts/
│   ├── generate-icons.js     # 图标生成器（sharp）
│   ├── install.js            # 验证脚本
│   └── verify.js             # 验证
├── cordis.patch.yml          # 插件注册
├── LICENSE
└── package.json

许可证

MIT