该规范用于指导 Magic Web 仓库中 Service Worker 的开发与维护，核心约定如下。
用途：调整或设计 SW 缓存路由、TTL、容量与分区规则；处理页面级注册、自动激活与强制更新重载；配置或排查首屏关键只读 GET 接口的 StaleWhileRevalidate 缓存；处理线上自愈失败、回滚与指定缓存桶紧急清理。激活关键词包括“修改缓存规则”“新增 API 缓存”“SW 排查”“PWA 缓存优化”“清理 SW”等。
主要能力与规则：静态资源以 CacheFirst 为主，同源哈希 JS/CSS 在 Vite 构建期收集、安装期预缓存，写入 magic-web-app-app-static-assets-v1；同源哈希图片运行时拦截并限量；固定路径 WASM/WebWorker 通过 swCache=runtime 打标写入标记桶；/sw.js、入口 HTML、config.js、mockServiceWorker.js 及 /sw/canvas-design-media/** 排除在主运行时缓存之外。跨域 CDN 缓存需 credentials: "omit"。API 缓存仅限只读 GET，支持 swCacheOption 的 no-cache/cache/default 三级覆盖，受 MAGIC_ENABLE_API_CACHE 与路径白名单约束。环境变量包括 MAGIC_SW_MODE（on/kill/off）、MAGIC_SW_CLEAR_CACHES、MAGIC_MOCK、MAGIC_FORCE_ENABLE_SW_IN_DEV、MAGIC_CDNHOST 等。路径匹配前须用 URL 提取干净 pathname，白名单正则须以 ^ 开头、$ 结尾；SW 在发起请求前移除 swCache=api-runtime 查询参数。仅在响应 json.code === 1000 或 undefined 时允许写入缓存。
使用方式：新增白名单 API 缓存在 sw-constants.ts 的 CACHEABLE_API_RULES 追加规则，并确认对应 HttpClient 已注册 swCacheRequestInterceptor；新增静态资源桶需在 sw-constants.ts 定义 CACHE_NAME 并加入 MANAGED_APP_CACHE_NAMES，在 cache-runtime.ts 用 registerRoute 注册并配置 ExpirationPlugin。变更后运行 pnpm test 指定测试文件并执行 pnpm build 验证。
限制：该规范针对本仓库实现，缓存仅限只读接口，禁止缓存高频写或强一致接口；开发环境默认不注册 SW，需 MAGIC_MOCK=true 或 MAGIC_FORCE_ENABLE_SW_IN_DEV=true；具体价格、发布渠道等未提供。