TrueGrowth/openspec/changes/refactor-sw-duplex-comm/design.md

Design: postmessage-duplex 通信层重构

Context

当前系统使用原生 postMessage API 实现 SW 与应用层通信：

• 应用层 → SW：直接 controller.postMessage()
• SW → 应用层：broadcastToClients() 广播所有窗口

这种模式在多标签页场景下存在问题：

1. 多个页面同时提交相同任务，SW 的去重检查存在时间窗口
2. 广播消息所有页面都会收到，无法区分请求来源
3. 请求-响应模式需要手动用 RxJS 实现

Goals / Non-Goals

Goals

• 使用 postmessage-duplex 实现双工通信
• 解决多标签页任务重复问题
• 简化请求-响应模式的实现
• 保持向后兼容（渐进式迁移）

Non-Goals

• 不改变现有业务逻辑
• 不改变 IndexedDB 存储结构
• 不改变任务执行流程

Decisions

1. 通信架构

┌─────────────────┐        ┌──────────────────────┐        ┌─────────────────┐
│   Tab 1 (Page)  │        │    Service Worker    │        │   Tab 2 (Page)  │
├─────────────────┤        ├──────────────────────┤        ├─────────────────┤
│ ServiceWorker   │◄──────►│ Per-client channels  │◄──────►│ ServiceWorker   │
│ Channel         │  RPC   │ Map<clientId,Channel>│  RPC   │ Channel         │
└─────────────────┘        └──────────────────────┘        └─────────────────┘

• 每个页面创建独立的 ServiceWorkerChannel
• SW 端维护 Map<clientId, channel> 管理所有连接
• 请求-响应使用 call 方法，事件通知使用 subscribe

2. 消息类型划分

操作	当前方式	改造后方式
任务创建	postMessage + 监听	call('task:create', params) → {taskId, status}
任务取消	postMessage	call('task:cancel', {taskId}) → {success}
任务重试	postMessage	call('task:retry', {taskId}) → {success}
获取任务列表	postMessage + timeout	call('task:list') → {tasks}
任务状态变更	broadcast	subscribe('task:status')
任务完成	broadcast	subscribe('task:completed')
Chat 流式	broadcast	subscribe('chat:chunk')

3. 任务创建流程改造

当前流程：

1. 应用层生成 taskId
2. 本地创建任务（乐观更新）
3. postMessage 到 SW
4. SW 检查重复，可能拒绝
5. 广播 TASK_CREATED

改造后流程：

1. 应用层调用 channel.call('task:create', params)
2. SW 检查重复
   - 已存在：返回 {success: false, existingTaskId}
   - 新建：创建任务，返回 {success: true, task}
3. 应用层根据响应更新本地状态
4. SW 广播 task:created 给其他客户端（排除发起者）

4. 多页面同步

• SW 维护所有通道引用
• 当任务状态变更时，广播给所有订阅该事件的通道
• 每个通道独立订阅，避免重复处理

5. Service Worker 端集成

由于 SW 不支持直接 import npm 模块，有两种方案：

方案 A（推荐）：打包时内联

• 使用 Vite 的 ?inline 或自定义打包将库代码内联到 SW

方案 B：复制核心代码

• 将 postmessage-duplex 的 SW 相关代码复制到项目中

选择 方案 A，在 SW 构建配置中处理。

Risks / Trade-offs

Risk	Mitigation
SW 端集成复杂	使用打包工具处理，文档中有示例
迁移风险	渐进式迁移，保留旧消息类型兼容
库稳定性	库较新（v1.0.0），需关注 issues

Migration Plan

Phase 1：基础设施

1. 安装 postmessage-duplex 依赖
2. 配置 SW 打包支持
3. 创建新的通信服务（与现有并存）

Phase 2：核心功能迁移

1. 迁移任务创建为 call 模式
2. 迁移任务状态为 subscribe 模式
3. 迁移 Chat 流式为 subscribe 模式

Phase 3：清理

1. 移除旧的 RxJS 订阅逻辑
2. 移除兼容代码
3. 更新文档

Open Questions

1. SW 打包方式的具体实现细节？

   • 需要测试 Vite 对 SW 入口的打包行为

2. 是否需要支持消息压缩？

   • 当前任务数据量不大，暂不需要