Skip to content

Commit 17b44e5

Browse files
committed
docs: PWA 设计/计划 v4——音频源决策:录屏导入(含系统音频)为主力,麦克风为应急,真·系统音频监听列 Phase 2
1 parent db39188 commit 17b44e5

2 files changed

Lines changed: 21 additions & 16 deletions

File tree

‎docs/superpowers/plans/2026-08-16-pwa-mobile.md‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,9 @@
33
> **For agentic workers:** 按任务顺序逐 Task 实施,Step 使用 checkbox(`- [ ]`)跟踪。
44
> **Spec:** `docs/superpowers/specs/2026-08-16-pwa-mobile-design.md`(v2 已定稿)
55
6-
**Goal:** 在现有代码库上增加第二条运行时——PWA(iOS Safari / Android Chrome),首批交付:番茄钟、空白笔记、课堂助手(麦克风录音转写 + 视频转笔记)、桌面↔移动账号同步。移动端本轮只保证**布局可用 + 功能完整**,不含 UI 视觉美化(Spec §1.3)。
6+
**Goal:** 在现有代码库上增加第二条运行时——PWA(iOS Safari / Android Chrome),首批交付:番茄钟、空白笔记、课堂助手(**系统录屏导入转写为主力(含系统音频)** + 麦克风实时转写应急 + 视频/抖音视频转笔记)、桌面↔移动账号同步。移动端本轮只保证**布局可用 + 功能完整**,不含 UI 视觉美化(Spec §1.3)。
77

8-
**Architecture:** 复用现有双模式基座(`storageFactory` PWA/Dexie 分支、ASR 云端降级链、墙钟校准计时);新增 `WebCaptureAdapter`(getUserMedia + MediaRecorder + 云端分段 ASR)与视频导入链路(复用网关 `/api/v1/multimodal/analyze-video`);同步复用 sync-service + OfflineQueue + Automerge。
8+
**Architecture:** 复用现有双模式基座(`storageFactory` PWA/Dexie 分支、ASR 云端降级链、墙钟校准计时);新增 `WebCaptureAdapter`(麦克风应急通道,Spec §3.2 音频源决策)与视频导入链路(主力通道,复用网关 `/api/v1/multimodal/analyze-video`);同步复用 sync-service + OfflineQueue + Automerge。
99

1010
**Tech Stack:** React 18 + Vite(VitePWA 已配置)、TypeScript、Dexie/IndexedDB、TipTap、Zustand、Web Notification API、supabase-js、Go sync-service(浏览器 WebSocket 直连)。Phase 1.5 可选项:sherpa-onnx-web(WASM + onnxruntime-web)。
1111

@@ -106,16 +106,19 @@
106106

107107
## M3: 课堂助手(第 2–6 周,~3–4 周;与 M2 并行)
108108

109-
### Task 9: WebCaptureAdapter(1.5–2 周,核心件)
109+
### Task 9: WebCaptureAdapter(麦克风应急通道,1–1.5 周)
110110

111111
**Files:** 新增 `client/src/features/classroom/capture/WebCaptureAdapter.ts`、`client/src/lib/audio/`(浏览器侧)
112112

113+
> 音频源决策(Spec §3.2 v4):PWA 无法实时监听系统扬声器;**主力通道 = 系统录屏导入**(Task 10 链路,系统音频随录屏文件落盘),本任务只做麦克风应急通道。
114+
113115
- [ ] **Step 1:** getUserMedia 麦克风采集(16kHz 单声道:AudioWorklet/ScriptProcessor 降采样,复用 asrFilters 处理链)
114116
- [ ] **Step 2:** MediaRecorder 分段(5–15s)+ 每段转码为云端 ASR 所需格式
115117
- [ ] **Step 3:** `CaptureAdapter` 接口定义(含现有 Electron 路径能力枚举:captureType/windowless 模式),`useSessionControl`/`useClassroomEvents` 加环境分支
116118
- [ ] **Step 4:** 移动端隐藏窗口选择/屏幕采集/系统音频 UI(`WindowSelectCard`/Vision 入口等按环境条件渲染)
117-
- [ ] **Step 5:** 会话中断恢复:标签切后台录音停止→前台恢复续录(复用/对齐 useAudioRecovery 语义)
118-
- [ ] **验收**:手机麦克风录音→分段→云端转写(transcribeWithRetry 现成链路)文本回流;后台切换不崩溃、可恢复
119+
- [ ] **Step 5:** 课堂主界面音频源选择:麦克风(实时应急)/ 系统录屏导入(主力,引导至 Task 10 导入入口)
120+
- [ ] **Step 6:** 会话中断恢复:标签切后台录音停止→前台恢复续录(复用/对齐 useAudioRecovery 语义)
121+
- [ ] **验收**:手机麦克风录音→分段→云端转写(transcribeWithRetry 现成链路)文本回流;录屏导入入口可达;后台切换不崩溃、可恢复
119122

120123
### Task 10: 视频转笔记(含抖音链接引导,1–1.5 天)
121124

@@ -180,7 +183,7 @@ T0(阻塞前置)
180183
Phase 1.5:Task 14 依赖 Task 9(采集链路)与 M1
181184
```
182185

183-
关键路径:T0 → M1 → M2(Task 6 编辑器为最大单项)→ M4 ≈ **9–13 周(单人)**;M3 与 M2 并行后总窗口不变;2 人并行时 M2/M3 各归一人,**5–7 周**。
186+
关键路径:T0 → M1 → M2(Task 6 编辑器为最大单项)→ M4 ≈ **9–12 周(单人)**;M3 与 M2 并行后总窗口不变;2 人并行时 M2/M3 各归一人,**5–7 周**。
184187

185188
## 工作量汇总(与 Spec §4 对齐)
186189

@@ -189,6 +192,6 @@ Phase 1.5:Task 14 依赖 Task 9(采集链路)与 M1
189192
| T0 | 前置验证 | 0.5–1 天 |
190193
| M1 | Task 1–4(基建+番茄钟) | 1 周 |
191194
| M2 | Task 5–8(笔记+同步) | 3–4 周 |
192-
| M3 | Task 9–11(课堂助手) | 3–4 周(与 M2 并行) |
195+
| M3 | Task 9–11(课堂助手:录屏导入为主 + 麦克风应急) | 2.5–3.5 周(与 M2 并行) |
193196
| M4 | Task 12–13(联调发布) | 1–1.5 周 |
194-
| Phase 1.5 | Task 14(WASM 流式,可选) | +1.5–2.5 周 |
197+
| Phase 1.5 | Task 14(WASM 流式,可选) | +1.5–2.5 周 |

‎docs/superpowers/specs/2026-08-16-pwa-mobile-design.md‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# 熵减移动端 PWA 版设计(MVP:课堂助手 + 空白笔记 + 番茄钟)
22

3-
> 日期:2026-08-16 | 状态:待评审(v3:课堂助手增加抖音链接引导导入,确认移动端录制识别机制) | 分支:dev
3+
> 日期:2026-08-16 | 状态:待评审(v4:音频源决策——录屏导入含系统音频为主力,麦克风为应急;真·系统音频监听列 Phase 2 原生壳) | 分支:dev
44
> 背景:评估"把当前 Electron 桌面项目移植到 iOS/Android"的工作量后,确认走项目既定策略
55
> (PWA 优先,见 docs/product/requirements-pool.md EXP-006 与 docs/Foresight/innovation-features-catalog.md),
66
> 首批范围锁定三个功能 + 桌面↔移动数据同步。
@@ -14,8 +14,8 @@
1414
1. **番茄钟**:移动端可用,计时准确(后台节流不丢时间),到点通知
1515
2. **空白笔记**:移动端可读写,数据落 IndexedDB(Dexie),与桌面端同构
1616
3. **课堂助手**:三种形态——
17-
- 实时课堂:麦克风录音 → 转写 → AI 结构化笔记(近似桌面端"实时录制识别"机制;参考 OPPO AI 笔记能力)
18-
- 视频转笔记:导入视频文件(手机录屏/网课下载/**抖音保存的视频**)→ 复用网关 `analyze-video` → 生成笔记
17+
- 实时课堂:麦克风录音 → 转写 → AI 结构化笔记(**应急通道**;近似桌面端"实时录制识别"机制)
18+
- 视频转笔记(**主力通道**):导入视频文件(**手机系统录屏——含系统音频**/网课下载/抖音保存的视频)→ 复用网关 `analyze-video` → 生成笔记。系统录屏是移动端"监听系统扬声器"的离线等价物(PWA 无法实时监听系统输出音频,见 §3.5)
1919
- 抖音链接引导:粘贴抖音分享链接 → 引导保存到相册 → 一键导入(方案 A);服务端自动解析(方案 B)列为后续实验性评估项
2020
4. **桌面 ↔ 移动数据同步**:账号绑定 + sync-service 增量同步
2121

@@ -62,9 +62,11 @@ getRuntimeEnvironment(): 'pwa' | 'electron' // 已存在,window.electronAPI
6262
```
6363
CaptureAdapter 接口(新增,client/src/features/classroom/capture/)
6464
├── ElectronCaptureAdapter ← 现有桌面实现(屏幕/窗口/系统音频/本地 ASR),保持不动
65-
└── WebCaptureAdapter ← 新增:getUserMedia 麦克风 + MediaRecorder 分段 + 云端 ASR
65+
└── WebCaptureAdapter ← 新增:麦克风实时转写(应急通道)+ 系统录屏导入转写(主力通道)
6666
```
6767

68+
- **音频源决策(v4)**:PWA 无法实时监听系统扬声器(iOS 无 API;Android 网页无法捕获原生 App 音频)。主力通道 = 手机系统录屏(系统音频随录屏文件落盘)→ 导入 → analyze-video 提取转写;应急通道 = 麦克风实时转写(外放收音,音质受限)。真·系统音频实时监听(Android AudioPlaybackCapture / iOS ReplayKit)列为 Phase 2 原生壳。
69+
6870
- 会话编排(useSessionControl / useClassroomEvents)增加环境分支;移动端隐藏窗口选择/屏幕采集 UI
6971
- 转写:MVP 走云端分段(`transcribeWithRetry` 已现成);Phase 1.5 换 WASM 流式
7072
- 视频转笔记:`<input type="file" accept="video/*">` → `aiClient` multipart 上传 `/api/v1/multimodal/analyze-video` → 结构化笔记入库。输入源含手机系统录屏、网课下载、抖音保存的视频;抖音分享链接(`douyin.com` 域名检测)走**引导流程**(提示"在抖音保存到相册"后导入)。**不做服务端自动解析**(抖音无公开下载 API;非官方解析受 a_bogus 反爬影响不稳定且有合规风险;方案 B 实验性解析后续单独评估)
@@ -92,7 +94,7 @@ StreamingAsrProvider 接口(新增,client/src/lib/asr/)
9294
| 桌面能力 | 移动 PWA 处理 |
9395
|----------|--------------|
9496
| 屏幕/窗口采集 | 移除(移动浏览器无 getDisplayMedia);替代:视频文件导入 |
95-
| 系统音频环回 | 移除;替代:麦克风录音 |
97+
| 系统音频环回 | PWA 无 API 无法实时监听;替代:**系统录屏导入(含系统音频)为主力** + 麦克风应急;Phase 2 原生壳(Android AudioPlaybackCapture / iOS ReplayKit) |
9698
| 托盘/全局快捷键 | 移除;替代:通知栏/页面内快捷入口 |
9799
| 本地 Ollama | 移除;走云端 AI 网关(项目已有完整降级链) |
98100
| 后台运行 | 浏览器标签后台会被节流:录音停止并提示;番茄钟靠墙钟校准+通知 |
@@ -107,11 +109,11 @@ StreamingAsrProvider 接口(新增,client/src/lib/asr/)
107109
| 横切基建(PWA 构建/部署、移动端导航与响应式布局、iOS Safari 细节、音频手势解锁) | 1 周 | VitePWA 已配置;仅布局结构,无视觉打磨 |
108110
| 番茄钟(响应式布局 + 通知流程) | 0.5–1 周 | 计时引擎已就绪(F3),纯布局+功能验证 |
109111
| 空白笔记(编辑器布局适配、存储验证、剪藏/PDF 浏览器替代) | 2–3 周 | 编辑器触摸/虚拟键盘/溢出是功能性问题,必须处理;不做视觉 |
110-
| 课堂助手-录音转写(WebCaptureAdapter + 云端分段 ASR) | 3–4 周 | 60 处 IPC 中捕获链路需重写,功能为主 |
112+
| 课堂助手-录音转写(WebCaptureAdapter 麦克风应急通道 + 转写链路) | 2.5–3.5 周 | 主力为系统录屏导入(走视频导入链路),麦克风为应急 |
111113
| 课堂助手-视频转笔记(文件选择 + 抖音链接引导 + 复用 analyze-video) | 0.5–1 周 | 后端现成(F6);抖音引导含链接检测与保存指引 |
112114
| 桌面 ↔ 移动同步(账号绑定 + 浏览器端验证) | 1–2 周 | 底子已具备(F8) |
113115
| 联调 + 移动端测试 + 打磨 | 1 周 | 双端回归;打磨仅限功能/布局缺陷 |
114-
| **合计** | **约 9–13 周(≈2–3 人月)** | 2 人并行约 5–7 周 |
116+
| **合计** | **约 9–12 周(≈2–2.5 人月)** | 2 人并行约 5–7 周 |
115117

116118
可选项:
117119
- 端侧 WASM 流式转写(StreamingAsrProvider,§3.3):**+1.5–2.5 周**,体验追平 OPPO 实时感、可离线,桌面同时获得降级路径
@@ -132,7 +134,7 @@ StreamingAsrProvider 接口(新增,client/src/lib/asr/)
132134
2. **布局可用**:360–430px 宽度下三个模块无横向溢出、无遮挡、可滚动,触摸/虚拟键盘可用(§1.3 标准;不含视觉美化)
133135
3. 番茄钟:切后台/锁屏 5 分钟再回来,计时不漂移(墙钟校准),到点通知可达
134136
4. 空白笔记:新建/编辑/搜索/文件夹/链接在移动端可用;数据持久化于 IndexedDB
135-
5. 课堂助手:麦克风录音 → 分段转写 → AI 生成结构化笔记全链路通(桌面式录制识别机制的移动版);导入视频(含手机录屏/抖音保存的视频)→ analyze-video → 笔记入库;粘贴抖音链接出现引导流程并可完成导入
137+
5. 课堂助手:系统录屏导入(含系统音频)→ analyze-video → 结构化笔记全链路通(主力通道);麦克风实时转写可用(应急通道);粘贴抖音链接出现引导流程并可完成导入
136138
6. 桌面 ↔ 移动:同一账号登录后数据双向增量同步,离线操作入队,恢复网络后补齐
137139
7. 桌面端回归:Electron 现有功能不受影响(适配器模式,桌面路径不变)
138140
8. 仓库门禁:`npm run check` 通过(lint/typecheck×2/test)

0 commit comments

Comments
 (0)