feat(live): 课堂助手三项优化——停止即时/播放暂停驱动/引擎预热

Author: Aparencia

CHANGELOG.md

@@ -31,6 +31,11 @@
   - 手动标记按钮"⭐ 标记此刻"：save_user_screenshot 补 live:image-saved 事件，"最近画面"条即时刷新（快捷键 Ctrl+Shift+S 同效）
   - 融合完成直达：停止后右侧显示"查看时间轴 →"卡片，一键跳会话页并自动打开对应会话详情
 - **开始前准备流（2026-08 用户需求，C 批）**：引擎就绪清单卡片（流式模型/SenseVoice/OCR 设备/结构模型/磁盘，聚合现有只读命令，零后端改动）——缺什么一目了然，全就绪显示"可开始"
+- **课堂助手三项优化（2026-08 用户需求）**：
+  - 停止即时生效：停止信号置位即停捕获线程（channel 断开后 drain 残留块），停止响应从 ~8s 降至 <1s；"会话线程 5s 内未退出，已 detach" 由常态日志降级为真卡死兜底；stop 命令改 spawn_blocking 不再阻塞异步运行时
+  - 视频播放状态自动暂停/恢复：REQ-125 暂停图标检测驱动 A1 硬暂停标志——视频暂停 → 整链路停采（WASAPI 端点 Stop / 不喂 ASR / 不写 WAV / 屏幕零分析），恢复播放自动继续；暂停边沿 flush 尾句 + 引擎 reset（替代 100ms 静音方案——真正断句，暂停前后语音不连句）
+  - 引擎预热（开始即录）：进课堂助手页即后台加载流式 ASR 引擎（预备线程 park 等待交接——引擎非 Send 不跨线程），点"开始"毫秒级启动；离开页面释放 + 15min TTL 兜底；预热失败/未就绪回退内联加载（零回归）
+  - 修复：A1 暂停标志/补偿时长跨会话残留（新会话起始即暂停、时间戳偏移）——start 时按会话复位
 
 - **课堂助手页面优化（2026-08 用户需求）**：
   - 窗口选择：自动过滤无法采集的窗口（最小化/零尺寸/cloaked/工具窗口）；B站/YouTube 等站点首页（无视频内容落地页）降权移出推荐并标注"站点首页"，仍可手动选择兜底

app/src-tauri/src/capture/audio_loopback.rs

@@ -66,6 +66,16 @@ pub struct SessionPause {
     pub total_paused_ms: Arc<std::sync::atomic::AtomicU64>,
 }
 
+impl SessionPause {
+    /// 按会话复位（P2 补漏：标志/补偿时长不得跨会话残留——上次会话若在
+    /// 暂停中停止，paused 残留会让新会话起始即暂停；补偿时长残留会让
+    /// 新会话时间戳整体偏移）。
+    pub fn reset(&self) {
+        self.paused.store(false, Ordering::SeqCst);
+        self.total_paused_ms.store(0, Ordering::SeqCst);
+    }
+}
+
 impl AudioLoopbackCapture {
     /// 启动捕获。on_chunk 在捕获线程内被调用（消费者需自行做轻量处理或转发）。
     ///
@@ -312,6 +322,25 @@ where
                                     t.elapsed().as_millis() as u64,
                                     Ordering::SeqCst,
                                 );
+                                // 清空残留缓冲（2026-08 审查修复）：Stop 前缓冲内
+                                // 的数据在恢复后已无意义——不清空会以补偿后时间戳
+                                // 混入暂停前的音频（内容错位）；循环读到空为止
+                                loop {
+                                    let pending = capture_client.GetNextPacketSize()?;
+                                    if pending == 0 {
+                                        break;
+                                    }
+                                    let mut _d: *mut u8 = std::ptr::null_mut();
+                                    let mut _f: u32 = 0;
+                                    let mut _fl: u32 = 0;
+                                    capture_client
+                                        .GetBuffer(&mut _d, &mut _f, &mut _fl, None, None)?;
+                                    capture_client.ReleaseBuffer(_f)?;
+                                }
+                                // TD-H 补漏（十五轮审查）：应用层切块累加器同样存在
+                                // 暂停前未凑满 200ms 的残留样本——不清空会以补偿后
+                                // 时间戳混入恢复后首个 chunk（内容错位）；重建清零
+                                accumulator = ChunkAccumulator::new(0);
                                 eprintln!("[AudioLoopback] 会话恢复（端点已重启，暂停 {}ms）", t.elapsed().as_millis());
                             }
                             Err(e) => {

app/src-tauri/src/commands_live.rs

@@ -23,6 +23,8 @@ use crate::live_session::LiveSessionParams;
 pub struct LiveSessionStatus {
     pub active: bool,
     pub session_id: Option<i64>,
+    /// P3：引擎预热是否已就绪（前端"开始即录"提示）
+    pub prepared: bool,
 }
 
 /// 启动实时捕获会话（REQ-007~012 汇总入口）。
@@ -83,20 +85,73 @@ pub async fn start_live_session(
 /// 停止实时捕获会话；返回被停止的会话 id（None=无活动会话）。
 #[tauri::command]
 pub async fn stop_live_session(state: State<'_, AppState>) -> Result<Option<i64>, String> {
-    let stopped = state.live_session.stop_active().map_err(|e| e.to_string())?;
+    // 停止含 5s 有界等待——异步 command 不得直接阻塞运行时线程（审查要求；
+    // LiveSessionManager 为 Clone+Send，可安全移入 spawn_blocking）
+    let manager = state.live_session.clone();
+    let stopped = tauri::async_runtime::spawn_blocking(move || manager.stop_active())
+        .await
+        .map_err(|e| format!("停止任务失败: {}", e))?
+        .map_err(|e| e.to_string())?;
     stop_clipboard_monitor(&state);
     Ok(stopped)
 }
 
-/// 查询实时会话状态（活动会话 id）。
+/// 查询实时会话状态（活动会话 id + 预热就绪标记）。
 #[tauri::command]
 pub fn live_session_status(state: State<'_, AppState>) -> LiveSessionStatus {
     LiveSessionStatus {
         active: state.live_session.active_session_id().is_some(),
         session_id: state.live_session.active_session_id(),
+        prepared: matches!(
+            state.live_session.prepare_status(),
+            crate::live_session_prepare::PrepareStatus::Ready
+        ),
     }
 }
 
+/// 预热流式 ASR 引擎（P3）：选窗口阶段后台加载，点"开始"即录。
+///
+/// @ai-context: 返回 PrepareStatus（loading/ready/failed/idle）供前端提示；
+///              幂等；模型文件缺失预检快速返回 Failed（不白起线程）；
+///              页面卸载时由 release_live_prepare 释放（15min TTL 兜底）。
+#[tauri::command]
+pub fn prepare_live_session(
+    state: State<'_, AppState>,
+) -> Result<crate::live_session_prepare::PrepareStatus, String> {
+    // 防御性预检：四件套任一缺失 → 预热必失败，快速返回不白起线程
+    let m = &state.streaming_models;
+    let missing: Vec<&str> = [
+        (&m.encoder, "encoder"),
+        (&m.decoder, "decoder"),
+        (&m.joiner, "joiner"),
+        (&m.tokens, "tokens"),
+    ]
+    .iter()
+    .filter(|(p, _)| !std::path::Path::new(p).exists())
+    .map(|(_, name)| *name)
+    .collect();
+    if !missing.is_empty() {
+        return Ok(crate::live_session_prepare::PrepareStatus::Failed(format!(
+            "模型缺失: {}",
+            missing.join(", ")
+        )));
+    }
+    let env = crate::live_session_prepare::PrepareEnv {
+        streaming_models: state.streaming_models.clone(),
+        engines: state.engines.clone(),
+        vocab: state.vocab.clone(),
+        // ADR-012 F4-2：标点恢复模型路径（与 start 同口径）
+        punctuation_model: crate::punctuation_model(&state.model_dir),
+    };
+    Ok(state.live_session.prepare(env))
+}
+
+/// 释放预热引擎（P3：离开课堂助手页时调用；有界 join ≤1s，超时 detach）。
+#[tauri::command]
+pub fn release_live_prepare(state: State<'_, AppState>) -> Result<(), String> {
+    state.live_session.release_prepare().map_err(|e| e.to_string())
+}
+
 /// 暂停实时会话（2026-08 A1 硬暂停：完全停采，时间轴冻结）。
 ///
 /// @ai-context: 只置共享标志——实际暂停由捕获线程边沿检测执行（WASAPI 端点

app/src-tauri/src/lib.rs

@@ -115,6 +115,9 @@ mod live_session_fusion;
 mod live_frame_process;
 #[cfg(target_os = "windows")]
 mod live_session_frame;
+// P3：引擎预热（预备线程——选窗口阶段后台加载，start 交接）
+#[cfg(target_os = "windows")]
+mod live_session_prepare;
 #[cfg(target_os = "windows")]
 mod live_keyframes;
 mod load_monitor;
@@ -505,6 +508,11 @@ pub fn run() {
             commands_live::pause_live_session,
             #[cfg(target_os = "windows")]
             commands_live::resume_live_session,
+            // P3：引擎预热（选窗口阶段后台加载，开始即录）/ 释放
+            #[cfg(target_os = "windows")]
+            commands_live::prepare_live_session,
+            #[cfg(target_os = "windows")]
+            commands_live::release_live_prepare,
             // 视频文件导入（REQ-015，ADR-008：字幕优先 + ASR fallback + 关键帧 OCR）
             commands_import::import_video,
             // OCR 设备状态（REQ-036，ADR-009：GPU 卸载决策/回退可观测）

app/src-tauri/src/live_frame_process.rs

@@ -107,6 +107,54 @@ impl TriggerState {
     }
 }
 
+/// 暂停模式仅取帧（P2 自动暂停：视频暂停 → 捕获自动暂停时，worker 保持
+/// 低频取帧刷新 latest_frame——播放器恢复检测的信号源，不刷新则无法发现
+/// 恢复播放；零分析：不做 diff/OCR/落库，成本与静默轮询同级）。
+///
+/// @ai-context: 事件转发保持（窗口关闭等信号不因暂停丢失）；失败节流日志
+///              5s（暂停期 1s 一拍，全量打印会刷屏）；取帧成功即覆盖共享
+///              缓存（时间戳用补偿后纪元——调用方注入）。
+pub fn capture_latest_only(
+    screen: Option<&mut ScreenCaptureSampler>,
+    app: &tauri::AppHandle,
+    epoch: Instant,
+    latest_frame: &std::sync::Arc<std::sync::Mutex<Option<LatestCapturedFrame>>>,
+    last_capture_error: &mut Option<Instant>,
+) {
+    let Some(sampler) = screen else { return };
+    // ADR-007：目标窗口关闭等捕获事件无论捕获结果如何都要转发（同 process_frame）
+    match sampler.take_event() {
+        Some(crate::capture::dxgi_capture::CaptureEvent::WindowLost) => {
+            let _ = app.emit("live:window-lost", ());
+        }
+        None => {}
+    }
+    match sampler.capture(None) {
+        Ok(Some(frame)) => {
+            if let Ok(mut guard) = latest_frame.lock() {
+                *guard = Some(LatestCapturedFrame {
+                    timestamp_ms: epoch.elapsed().as_millis() as u64,
+                    bgraw: frame.bgraw,
+                    width: frame.width,
+                    height: frame.height,
+                });
+            }
+        }
+        // DXGI 超时（桌面无变化）——暂停期常态，非错误
+        Ok(None) => {}
+        Err(e) => {
+            let now = Instant::now();
+            let should_log = last_capture_error
+                .map(|t| now.duration_since(t) >= Duration::from_secs(5))
+                .unwrap_or(true);
+            if should_log {
+                *last_capture_error = Some(now);
+                eprintln!("[ScreenWorker] 暂停期取帧失败（日志节流 5s）: {}", e);
+            }
+        }
+    }
+}
+
 /// 处理一帧屏幕采样（字幕区/全帧 OCR）。
 ///
 /// @ai-context: ADR-011 两级判变：①全帧网格差异（每 tick，与路径无关）——