Initial TrueGrowth source import

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

@@ -0,0 +1,126 @@
+# 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. 是否需要支持消息压缩？
+   - 当前任务数据量不大，暂不需要