Files
boss/docs/superpowers/specs/2026-04-21-master-agent-background-notification-design.md

2.6 KiB
Raw Permalink Blame History

主 Agent 后台通知设计

目标:当用户不在 Boss App 前台时,如果主 Agent 会话收到新回复Android 端必须像即时通讯工具一样给出系统通知;用户回到前台或正在查看该会话时,不重复通知。

方案对比:

  1. 仅用现有 SSE 实时链路补本地通知。优点是改动最小、上线最快、复用现在已验证的实时链路;缺点是应用被系统彻底杀死时无法像 FCM 那样绝对到达。推荐先做这个。
  2. 引入 FCM 补离线推送。优点是彻底后台/杀进程场景覆盖更强;缺点是需要服务端推送凭据、设备 token 管理、通知路由与去重,改动面明显更大。
  3. 做前台服务常驻保活。优点是可提升存活率;缺点是侵入性强、耗电、系统限制更多,不适合作为第一批方案。

本次设计:

  • 只针对 master-agent 会话里的“主 Agent -> 用户”回复发通知。
  • 触发源继续使用 /api/v1/events 的 SSE收到 project.messages.updatedprojectId == master-agent 时,从 projectMessagesPayload.project.messages 里取最后一条消息判断是否为主 Agent 回复。
  • 增加应用前后台跟踪器,判断 App 当前是否在前台、当前打开的会话是不是 master-agent。若正在前台看主 Agent 对话,则不通知;否则通知。
  • 增加通知去重:按最新消息 message.id 记忆,避免重连、补帧、重复事件导致连续弹多次。
  • 通知点击后直接打开 ProjectDetailActivity(master-agent)
  • 若 Android 13+ 未授予通知权限,则静默跳过,不打断主流程。

涉及文件:

  • 新增 android/app/src/main/java/com/hyzq/boss/BossAppVisibilityTracker.java
  • 新增 android/app/src/main/java/com/hyzq/boss/BossNotificationRouter.java
  • 修改 android/app/src/main/java/com/hyzq/boss/BossApplication.java
  • 修改 android/app/src/main/java/com/hyzq/boss/BossRealtimeClient.java
  • 修改 android/app/src/main/java/com/hyzq/boss/MainActivity.java
  • 修改 android/app/src/main/java/com/hyzq/boss/ProjectDetailActivity.java
  • 修改 android/app/src/main/AndroidManifest.xml
  • 新增测试 android/app/src/test/java/com/hyzq/boss/BossNotificationRouterTest.java
  • 修改测试 android/app/src/test/java/com/hyzq/boss/ProjectDetailActivityRealtimeTest.java
  • 修改测试 android/app/src/test/java/com/hyzq/boss/BossRealtimeClientTest.java

边界:

  • 这批不做普通线程通知,不做群聊通知,不做 FCM。
  • 这批不解决“应用被系统彻底杀死时的绝对送达”,后续若你要补到微信级彻底离线送达,再上 FCM 第二期。