为了快乐摸鱼，我给Cursor、Claude Code开发了个小工具 （二）

前情提要：

昨天简单介绍了下agentwake的功能——在cursor、claude code、qoder任务完成、异常或等待授权时，将通知推送到桌面、手机端。

秉持着老摸鱼人的原则，就采取“渐进式披露”——一次性写不了太多。今天先介绍的是PWA这条线。

PWA

什么是PWA？

PWA（Progressive Web App）并不是“网页套壳 App”，而是用一组浏览器能力，把 Web 应用做成“接近原生体验”的工程实践。

它的核心目标是三件事： 可安装、可离线、可推送 ，同时保持 Web 的跨平台和低分发成本。

而我使用PWA，就是因为它可以在手机上接近APP的体验，从而触发系统推送，实现相比app更为轻量。

HTTPS

PWA 在手机上要稳定可安装、可通知，HTTPS 是硬门槛。
Service Worker 注册、安装体验、部分通知能力都依赖安全上下文（https://）。

但如果你的需求和我一样，主要是局域网内自用，就没必要走公网证书那套复杂流程（域名、CA 证书、续期等）。
这里非常推荐 mkcert：一个本地签发受信任开发证书的工具，适合本地和内网 HTTPS 场景。

1. 用 mkcert 生成本机/局域网可访问地址的证书
2. 在服务端启用 HTTPS（AgentWake 通过环境变量控制）
3. 把根证书安装并信任到手机设备
4. 用手机访问 https://<局域网IP>:端口，再申请通知权限

这样可以在不引入公网域名成本的前提下，满足 PWA 的安装与通知条件。

推送能力（VAPID）

当前项目里的方案是“实时优先，逐步增强”：

• 第一层：WebSocket 实时推送

  • 网关收到事件后立即推送到移动端页面
  • 页面调用通知 API 触发系统提醒

• 第二层：轮询补偿

  • 当 WebSocket 短暂断开时，通过 /api/events?since=... 拉取增量事件
  • 避免弱网环境下的消息遗漏

• 第三层：Web Push

  • 当页面关闭或不在前台时，仍可由 Service Worker 接收 Push 并展示通知

具体实现：在服务端使用工具生成一对公钥和私钥（Base64 字符串），前端 Service Worker 在调用 pushManager.subscribe 时，提供公钥。服务端在发送推送时，需要包含 VAPID 详情以验证身份。

---

在仓库中的实现分工

为了方便读代码，这里给一版“职责地图”：

• web/manifest.webmanifest：定义应用名、图标、显示模式（可安装能力）。
• web/sw.js：监听 push 与 notificationclick（后台通知能力）。
• web/app.js：注册 SW、申请权限、WS 连接、轮询补偿、Push 订阅上报。
• src/notifiers/mobile-ws-notifier.ts：WebSocket 通知通道。
• src/notifiers/pwa-push-notifier.ts：Web Push 通道与订阅管理。
• src/bootstrap.ts：把上述通道接入统一事件路由。
• src/config.ts：读取 PWA/HTTPS/VAPID 等开关与参数。

---

关键配置项

要跑通完整 PWA 推送链路，agentwake注入的环境变量：

• AGENTWAKE_PWA_ENABLED=1：开启移动端 PWA 通道。
• AGENTWAKE_HTTPS_ENABLED=1：建议开启 HTTPS（手机端强烈建议）。
• AGENTWAKE_HTTPS_CERT_PATH：证书路径。
• AGENTWAKE_HTTPS_KEY_PATH：私钥路径。
• AGENTWAKE_WS_PATH=/ws：WebSocket 路径。
• AGENTWAKE_VAPID_PUBLIC_KEY：Web Push 公钥。
• AGENTWAKE_VAPID_PRIVATE_KEY：Web Push 私钥。
• AGENTWAKE_VAPID_SUBJECT：VAPID 联系标识（如 mailto:xxx@xx.com）。

🔗 开源地址 ： github.com/tjdxwwj/age…

走过路过，大佬们 GitHub 顺手点个 Star ⭐️ 支持一下！（收到star的感觉比上班爽多了～）如果你正在用其他 AI 编程工具也想接入这个“监工”系统，欢迎随时提出来，我们会积极适配～