## Context

StudyDeck 学习页（`StudyView` + `MediaPlayer`）当前用原生 `<video controls>`，AI 入口是右下角 `AiAssistPanel` FAB。配置侧已具备 `realtimeVoice` / `realtimeVision`、`features.realtimeVoiceCall` / `realtimeScreenShare`、`prompts.voiceCall` / `screenShare`，但学习 UX 未拆分。家长期望在 iPad/PC 视频舞台底部固定波形与工具条，支持「上一句剪辑提问 / 截图提问 / 语音通话 / 投屏通话」。

业界对照：

| 产品/方案 | 传输 | 视觉输入实质 | 成本特征 |
|-----------|------|--------------|----------|
| 豆包视频通话 | 火山 RTC + 多模态传输（MMT） | 云侧抽帧 + 实时语音；对开发者开放对话式 AI / RTC | 体验最好，集成重（AppId/Token/StartVoiceChat） |
| 通义 Qwen-Omni-Realtime | WebSocket 或 WebRTC | **建议 1 帧/秒** JPG；单帧体积受限；音频必需 | 文档清晰，成本可控（帧率即账单旋钮） |
| OpenAI Realtime | WebRTC/WS | 「视频」多为关键帧/快照作 image input，非 30fps 推理 | 按 token；少发帧显著降本 |

共识：**模型并不吃连续 30fps**；体验来自低延迟语音 + 稀疏关键帧 + VAD/打断。

## Goals / Non-Goals

**Goals:**

- iPad/PC 统一底部 chrome：Wave（~56–64px）+ Toolbar（~56–64px + safe-area）。
- 上一句：能量谷断句 → 音频片段提问。
- 消息聚焦：暂停 + 整帧截图缓冲。
- 铅笔：QQ 式遮罩圈选 → 缓冲 → vision 提问。
- 电话：纯语音 realtime。
- 视频：界面内投屏演示 + 语音；默认「抽帧伪投屏」路径。
- 模式互斥、feature/endpoint 门控。

**Non-Goals:**

- 系统桌面级 `getDisplayMedia` 真录屏（可后续）。
- 完整复制豆包 MMT / 亿级 RTC 基建。
- 强制字幕轴断句（可作后续增强，与能量断句并存）。
- 改造牛津树 `frontend/`/`backend/`。

## Decisions

### D1 — 舞台布局：固定底栏，视频区 `flex:1`

```
Stage (flex:1)     ← 视频/字幕/涂鸦遮罩
Wave strip         ← 波形 + 精简播放控件
AI Toolbar         ← ☎ 📹 ✏ 💬 + input + send
```

- 去掉原生 `controls`，自绘进度/播放，避免与底栏抢高度。
- `video_pdf`：底栏挂整页底部（视频侧内容上移），不把 Toolbar 塞进窄分栏。

**Alternatives:** 波形叠在视频内（草图现状）→ 放弃，因工具条需要稳定触控区且 iPad 拇指区在底。

### D2 — 上一句：分层能量谷（5s → 10s），输出音频 clip

算法（v1，可调参）：

1. 以当前 `t = media.currentTime` 为终点（须已暂停或按钮触发时先 pause）。
2. 预计算或按需解码得到能量序列 `E[i]`（窗长 ~20–40ms，hop ~10–20ms；RMS 或均值绝对值）。
3. 在 `[t-5s, t)` 找满足「局部谷」的时刻：
   - `E[i] < noiseFloor * k`（k≈1.2–1.5）
   - 连续静音 ≥ `minSilence`（建议 180–250ms）
   - 谷前需有一段可听语音（避免片头静音误判）
4. 若无命中，扩大到 `[t-10s, t)`；仍无则 `start = max(0, t-10s)`（硬回退）。
5. 产出 `AudioClip { start, end: t }`；波形上高亮该区间。
6. 发送：优先走 **chat + 音频附件/转写**；若 endpoint 仅支持文本，则先本地/云端 ASR 再附文本时间戳。v1 若暂无音频上传通道：用「时间范围 + 可选抽帧 1 张（区间中点）」+ 提示词说明「请结合画面与时间范围解释对白」作为降级；**任务中优先打通音频片段上传或 ASR**。

更好断句（后续可选，不挡 v1）：

- 双门限迟滞（enter/exit 不同阈值）减少抖动。
- 谱通量 onset 检测句首。
- 若日后有字幕 cue，与能量谷取更近者。

**提问上下文**：`prompts` 新增或复用 `videoAsk`，场景文案覆盖「这段话含义 / 男声女声说了什么 / 与前文关系」；可附 `start–end` 与可选前 5s 摘要占位。

### D3 — 消息框：focus → pause + full-frame capture

- `onFocus` / 首次 tap：`pause()` → `captureVideoFrame()` → 写入单一 `CaptureBuffer`（新替旧）→ 输入区显示缩略 chip。
- 发送：有图 → `vision` + `videoAsk`；发送成功清缓冲。
- 与铅笔共用缓冲类型。

### D4 — 铅笔 Annotate：遮罩挖洞 + 确认裁切

状态：`Idle → Annotate → BufferReady`。

- 进入：pause、冻结帧（`drawImage(video)` 到 offscreen canvas）、全屏 `rgba(0,0,0,0.55)`、浮出工具条：取消 / 矩形 / 椭圆 / 确认。
- 选区：SVG mask 或 canvas `destination-out` 挖洞，圈内原色、圈外变暗；松手后可调大小。
- 确认：按形状 clip 裁切 JPEG（最长边 ≤1280）→ 缓冲 → 退回 Idle（保持暂停）。
- 复用并升级现有 `PdfRectCapture` 交互语言（确认流而非拖完即裁）。

### D5 — 实时通话：分层实现（成本 / 流畅度权衡）

```
                    ┌─────────────────────────────┐
                    │  产品：「电话 / 视频通话」    │
                    └──────────────┬──────────────┘
           ┌───────────────────────┼───────────────────────┐
           ▼                       ▼                       ▼
     VoiceCall               ScreenShareCall          (Future)
     realtimeVoice           Tier A (默认)            Tier B
     仅麦克风+扬声器          语音 + ~1fps 抽帧         厂商 RTC
                             事件驱动推帧              对话式AI
```

**Tier A（默认，对齐通义 Omni Realtime 文档）**

- 音频：Realtime WebSocket / 厂商 realtime voice（持续）。
- 画面：从学习 stage / video 抓 JPEG，**建议 1 fps 或更低**：
  - 基线：通话中每 1.0s 一帧；
  - 省流：用户 VAD 说话时才推帧，或用户点「看这里」/铅笔圈选后推 ROI；
  - 分辨率：480p–720p，单帧编码后控制体积（参考通义单帧限制量级）。
- UI：app 内全屏「投屏演示」层（镜像当前学习画面），非系统录屏权限。
- 成本旋钮：帧率、分辨率、是否仅在发言时推帧。

**Tier B（可选升级，对齐豆包/火山对话式 AI）**

- 当 `rtcAppId` + `rtcTokenUrl` 可用：走 RTC + StartVoiceChat 类一站式。
- 视觉由云侧抽帧/视频通道处理；客户端职责变为推流与 UI。
- 集成成本高，体验与弱网更好；作为配置开关，不阻塞 Tier A。

**明确不选（v1）**：本地 15–30fps 连续推给多模态模型（贵、热、收益低）。

### D6 — 状态机与互斥（含 Ask 浮窗）

```
Idle ──prevSentence──► AskModal(audio clip)
Idle ──message───────► pause+frame ──► AskModal(image)
Idle ──pencil ✓─────► AskModal(image crop)
Idle ──video icon───► AskModal(video) ──投屏──► ScreenShareCall
Idle ──phone────────► VoiceCall ──hangup──► Idle
AskModal ──send─────► Asking (in-modal) ──► AskModal
```

- Annotate / VoiceCall / ScreenShareCall 互斥。
- 底栏「视频」= 打开预览浮窗，不直接进投屏；投屏从浮窗动作进入。
- 通话中禁用铅笔（v1）。

### D7 — 组件拆分

| 模块 | 职责 |
|------|------|
| `StudyBottomChrome` | Wave + Toolbar 壳；入口分发 |
| `MediaWaveform` | 峰值渲染、区间高亮、seek |
| `EnergySentenceFinder` / `energySeries` | 5s/10s 谷点 |
| `AnnotateOverlay` | 遮罩、形状、确认裁切 |
| `StudyAskModal` | 左预览 + 右对话、TTS、语音气泡 |
| `lib/tts` | edgeTTS → speechSynthesis 回退 |
| `lib/voiceMessage` | 录音、播放、转写钩子 |
| `CallSession` | Voice / ScreenShare 生命周期 |

退役主路径 `ai-fab`。底栏内联「发送气泡」降级为入口；对话主场在 `StudyAskModal`。

### D8 — 图标与视觉语言

工具栏 / TTS / 语音输入使用 `Icons.tsx` 描边 SVG（`IconPhone`、`IconVideo`、`IconPencil`、`IconMessage`、`IconSpeaker` 等），禁止 emoji 作为主图标。电话可保留红色强调色（`currentColor` / 工具栏 class）。

### D9 — TTS 与语音消息

- **TTS**：助手消息喇叭 → `speakText`：edge-tts（Tauri）优先，失败提示后 `speechSynthesis`。
- **语音输入**：微信式单击开录/再击发送；绿气泡可点播；尽量 STT 后带上下文提问。
- 同模态内播放互斥：点播语音气泡或 TTS 时停止另一路。

## Risks / Trade-offs

- **[能量断句不准]** → 双窗回退 + 硬 10s；后续字幕 cue；可拖拽 clip。
- **[音频片段无法直传]** → v1：时间戳 + 中点帧；见 `notes-spike-audio-and-tier-b.md`。
- **[Realtime 厂商差异]** → `CallSession` adapter；Tier A 统一稀疏帧。
- **[edgeTTS 依赖]** → 本机未安装时静默回退 speechSynthesis，避免阻断提问。
- **[浮窗与底栏双入口]** → 状态易碎；以 modal 为对话唯一真相，底栏只做触发/chip。
- **[通话费用]** → 稀疏帧；设置档后续。
- **[麦权限]** → 通话/录音前显式错误文案。

## Migration Plan

1. Chrome + 自绘控件。
2. Ask 浮窗取代底栏内联主对话。
3. SVG 图标、TTS、语音气泡。
4. 按下方 UX backlog 收口破碎交互。
5. Tier B RTC 仍为 Phase 2。

回滚：关闭 chrome feature 时恢复原生 controls + FAB。

## Open Questions

- 音频片段：multimodal 直传 vs ASR→文本？（spike 结论：v1 时间范围+中点帧。）
- Tier B：仅预留配置（已定）。
- Clip 波形拖拽微调：v1.1。
- 底栏是否仍保留迷你 composer，还是图标-only？（实现已偏图标打开浮窗；需在 backlog 里钉死。）

## UX backlog（体验收口清单）

> 来源：并行对话 [AI 工具栏交互打磨](d3706a98-87e0-446e-b86a-2313578ee229) 及后续手测。  
> **用法**：每条先写成可验收的行为（可直接升格进 specs），再 `/opsx:apply` 改代码。  
> 本地未找到 UUID `f37b52ea-5eb5-41ce-9478-f30cd8647d8e`；若另有记录请继续往下追加。

### 已吸收进 specs（本轮）

1. 工具栏简约 SVG，不用 emoji。
2. 截图/音频/视频/消息 → 浮窗左预览 + 右对话。
3. AI 回复 TTS（edgeTTS → 本机朗读）。
4. 微信式语音输入气泡 + 可回放。
5. 视频图标先预览；投屏从浮窗进入；电话仍直达语音通话。

### 待用户补充 / 待收口（请往下追加）

<!-- 用户继续粘贴破碎问题；示例格式：
- [ ] 浮窗打开时底栏仍可点导致双模态
- [ ] 上一句预览播放越界未停在 end
- [ ] …
-->

- [ ] （等待补充）交互碎片与体验问题…