Workbench PWA（单文件数据工作台 + 手机 App 化）
概述
把「数据看板 / 工作台 / 热榜 / 每日打卡」这类需求，做成一个单文件 index.html：桌面端有侧栏 + 多模块，发布成 https 链接后能在 iPhone/Android 上像原生 App 一样全屏打开（PWA），并通过每日自动化让数据持续更新、自动同步到手机。
何时使用
- 用户要搭「工作台」「看板」「dashboard」「热榜」「每日打卡」「数据面板」
- 用户要「把网页做成手机 App」「像 App 一样打开」「加到主屏」「PWA 化」
- 用户要「数据每天/定时自动更新并同步到手机」
核心流程（五阶段，按序执行）
阶段 1：单文件 HTML 架构
- 起步直接用
assets/template.html—— 一份完整可运行的最小骨架（含侧栏 + 3 模块 + 移动端抽屉 + PWA meta + SW 注册 + DATA/renderX/导航切换全套代码），复制为index.html后按需增删模块即可，不必从零搭结构。 - 单文件 index.html：内联 CSS + JS，Tailwind CDN + Chart.js（无构建步骤）
- 数据集中在
const DATA = {...}，用renderX()函数渲染，state对象管 UI 筛选/排序 - 左侧栏 + 多模块切换（
.nav-item+data-target+.module.active） - 视觉规范可配置；默认给「印章红 #C8252C + 墨黑 + 米白宣纸 + Noto Serif SC」的东方文化风
- 架构约定、DATA 字段、代码模式见
references/architecture.md
阶段 2：真实数据接入
- 热榜：
hot-topicsskill →60s.viki.moe/v2/{douyin,weibo,zhihu,bili,toutiao,baidu}API - 选题/文旅/长尾/学习内容：WebSearch +
trend-hotspot-pool - 用
refresh.py（Python regexreplace_block()）把数据安全写回 DATA 区段 - 模板见
scripts/refresh_template.py
阶段 3：移动端响应式
@media (max-width:768px)桌面优先；grid-cols-1 md:grid-cols-N天然适配单列堆叠- 侧栏 → 顶部抽屉（汉堡按钮 + 遮罩 + ESC 关闭）；表格行 → flex-column 卡片化
- 详见
references/architecture.md移动端章节
阶段 4：PWA 化
manifest.json（standalone + icons + theme_color）sw.js：数据文件 network-first，静态资源 cache-first（关键，见下方避坑 #1）- iOS meta +
viewport-fit=cover+ 安全区（刘海/Home 条）适配 - 图标用 PIL 重绘（避开 AI 生图水印），脚本
scripts/make_icon.py - 完整清单 + sw.js 模板见
references/pwa.md
阶段 5：发布 + 每日自动化
- 用
workbuddy_sites_deploy发布（language: static，复用同目录可保链接不变） - 自动化 = refresh.py + 重新部署 两步（关键：本地更新 ≠ 线上更新，见避坑 #2）
- 用 WorkBuddy Automation 定时（如
FREQ=DAILY;BYHOUR=9;BYMINUTE=0）
关键避坑（实战验证，务必遵守）
- SW 缓存会挡住每日数据更新：数据文件（index.html）绝不能 cache-first，否则手机永远读到旧缓存。必须 network-first（在线拉最新、断网回退缓存）；只有图标/manifest 等真正不变的静态资源才 cache-first。
- 本地更新 ≠ 线上更新：refresh.py 只改本地文件，线上副本必须显式重新部署；每日自动化要把「刷新 + 部署」串成两步，否则手机永远看不到新数据。
- Python
replace_block重复调用会累积],导致 JSSyntaxError: Unexpected token ']'、整页交互失效。写 refresh.py 时要对每个区段加防御性检查（避免重复闭合）。 - http server 用
run_in_background起，nohup ... &会被 sandbox 杀掉导致请求失败。 - 图标用 PIL 重绘，不要用 AI 生图（AI 生图常带水印 + 浅色边角）。
- jsdom 验证数据：
const DATA不会挂到window，要验证数据看渲染后的 DOM（如#dy-hotlist里的hot-row数量），而不是读window.DATA。
Resources
assets/template.html— 完整可运行的最小工作台骨架（复制为 index.html 起步）scripts/make_icon.py— 用 PIL 生成印章风格 App 图标（多尺寸 + apple-touch-icon）scripts/refresh_template.py— 数据刷新脚本模板（replace_block 安全写回模式）references/architecture.md— 单文件 HTML 架构、DATA 字段约定、渲染模式、移动端适配references/pwa.md— PWA 完整清单（manifest + sw.js 模板 + iOS meta + 安全区）
