feat(audio): 进程环回默认启用 + 设置页音频源选择（Phase 3）

ADR-001 Phase 3：进程环回从灰度转默认启用，并补齐用户可控与可归因链路。

- flag 反转为默认开启，ENTROPY_PROCESS_LOOPBACK=0 保留为应急总闸
  （现场排障可不重新发版即关闭）
- audioSourcePreference：偏好持久化（localStorage），读写全程静默降级，
  绝不因偏好读取失败阻断采集启动；6 例单测覆盖非法值与存储异常
- 设置页新增「课堂音频采集」区块：自动 / 仅目标窗口声音 / 系统全部声音，
  各选项标注取舍（干净但可能漏采 vs 不漏采但含杂音）
- audio_capture_start 双向打通：入参接收 preference（主进程读不到
  localStorage），返回值回传 sourceKind + sourceReason
- useAudioRecovery 按源分支：对进程环回不再提示'检查系统默认输出设备'
  （该源不受输出设备与系统音量影响，属误导），改为提示确认目标窗口在播放；
  devicechange 自动重启仅端点环回保留
- 生效源经 useClassroomCapture 暴露，供 UI 展示与内测归因

验证：client 479 tests、lint 0 errors、渲染与主进程 tsc 均 0。

Author: Aparencia

client/electron/audioCapture.ts

@@ -32,13 +32,13 @@ import {
 } from '../src/lib/capture/audioSourceStrategy.js';
 
 /**
- * 进程环回特性开关（Phase 2：默认关）。
+ * 进程环回特性开关（Phase 3：默认开）。
  *
- * 开启方式：环境变量 ENTROPY_PROCESS_LOOPBACK=1。
- * Phase 3 经内测灰度后改为默认开并改由设置页控制。
+ * 默认开启后用户仍可在设置页选“系统全部声音”强制用端点环回；
+ * ENTROPY_PROCESS_LOOPBACK=0 作为应急总闸（现场排障时无需重新发版即可关闭）。
  */
 function isProcessLoopbackEnabled(): boolean {
-  return process.env.ENTROPY_PROCESS_LOOPBACK === '1';
+  return process.env.ENTROPY_PROCESS_LOOPBACK !== '0';
 }
 
 // 保持既有导出路径不变（mediaCaptureHandlers 等调用方无需改动）
@@ -132,7 +132,7 @@ export class AudioCapture {
     if (this.capturing || this.disposed) return;
 
     const resolvedSourceId = sourceId ?? null;
-    // 特性开关关闭时能力恒为不可用，选源必为端点环回（行为与 Phase 0 一致）
+    // 应急总闸关闭时能力恒为不可用，选源退回端点环回
     const processAvailable = isProcessLoopbackEnabled() && isProcessLoopbackAvailable();
     this.decision = selectAudioSource({
       capabilities: { processLoopbackAvailable: processAvailable },

client/electron/mediaCaptureHandlers.ts

@@ -10,6 +10,7 @@
 import { BrowserWindow, ipcMain } from 'electron';
 import { AudioCapture, listAudioSources } from './audioCapture.js';
 import type { AudioCaptureOptions, AudioChunk } from './audioCapture.js';
+import type { AudioSourcePreference } from '../src/lib/capture/audioSourceStrategy.js';
 import { VideoRecorder } from './videoRecorder.js';
 import type { VideoRecordOptions } from './videoRecorder.js';
 import { safeHandle, getMainWindowId } from './ipcUtils.js';
@@ -55,7 +56,14 @@ export function registerMediaCaptureHandlers(): void {
 
   safeHandle(
     'audio_capture_start',
-    async (event, options?: Partial<AudioCaptureOptions> & { sourceId?: string }) => {
+    async (
+      event,
+      options?: Partial<AudioCaptureOptions> & {
+        sourceId?: string;
+        /** 用户在设置页选择的音频源偏好（主进程读不到 localStorage，由渲染进程传入） */
+        preference?: AudioSourcePreference;
+      },
+    ) => {
       if (activeAudioCapture) {
         activeAudioCapture.dispose();
         activeAudioCapture = null;
@@ -79,9 +87,17 @@ export function registerMediaCaptureHandlers(): void {
       });
 
       try {
-        await activeAudioCapture.start(senderWin, options?.sourceId);
+        await activeAudioCapture.start(senderWin, options?.sourceId, {
+          preference: options?.preference,
+        });
+        const decision = activeAudioCapture.sourceDecision;
         logger.info('[IPC] audio_capture_start 已启动');
-        return { success: true };
+        // 回传生效源：渲染进程据此分支诊断文案并写入会话元数据（内测归因）
+        return {
+          success: true,
+          sourceKind: activeAudioCapture.activeSourceKind,
+          sourceReason: decision?.reason,
+        };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         logger.error('[IPC] audio_capture_start failed:', message);

client/src/features/classroom/hooks/useAudioRecovery.ts

@@ -2,14 +2,18 @@
  * 课堂音频自动恢复 hook（静音诊断 / 设备变更重启）
  *
  * @ai-context: 从 useClassroomAudio 拆出的独立恢复层。两条恢复路径：
- * ①输出设备不匹配诊断——系统环回只录默认输出设备，视频声音若输出到其他
- * 设备（HDMI/蓝牙）会表现为"音频块正常但持续静音"，检出后提示用户核对；
- * ②设备变更重启——默认输出设备切换后环回仍绑定旧设备，devicechange 时
- * 自动 stop→start 重新绑定。
+ * ①静音诊断——音频块正常但持续静音，成因随音频源不同（见下）；
+ * ②设备变更重启——仅端点环回需要（它绑定系统默认输出设备），进程环回
+ * 与输出设备无关，切设备时不必重启。
+ * @ai-context: 诊断文案必须按 sourceKind 分支（ADR-001）——对进程环回说
+ * "请检查默认输出设备"是误导，它根本不受输出设备与系统音量影响，此时
+ * 真实成因是目标窗口没在发声或声音来自别的应用。
  * @ai-context: 仅依赖 refs 的稳定回调，重启经 restartingRef 互斥防并发。
  */
 import { useEffect, useRef, useCallback } from 'react';
 import type { CaptureMode, SessionStatus } from '@/lib/capture';
+import type { AudioSourceKind } from '@/lib/capture/audioSourceStrategy';
+import { getAudioSourcePreference } from '@/lib/capture/audioSourcePreference';
 import {
   computeChunkRms, SilenceTracker,
   getDefaultOutputDeviceLabel, subscribeDeviceChange,
@@ -25,17 +29,25 @@ interface UseAudioRecoveryOptions {
   mode: CaptureMode;
   /** 会话选中窗口的源 ID，重启时沿用同一源 */
   audioSourceId?: string | null;
+  /** 本次会话实际生效的音频源（由 audio_capture_start 回传） */
+  sourceKind?: AudioSourceKind | null;
   onNotify: (type: 'warning' | 'error', message: string) => void;
 }
 
-export function useAudioRecovery({ status, mode, audioSourceId, onNotify }: UseAudioRecoveryOptions) {
+export function useAudioRecovery({
+  status, mode, audioSourceId, sourceKind, onNotify,
+}: UseAudioRecoveryOptions) {
   const notifyRef = useRef(onNotify);
   notifyRef.current = onNotify;
   const effectiveSourceRef = useRef<string | undefined>(audioSourceId ?? undefined);
   const silenceTrackerRef = useRef(new SilenceTracker());
   const restartingRef = useRef(false);
+  // 生效源用 ref 桥接：静音诊断的监听器依赖数组不含它，避免重订阅丢失计数
+  const sourceKindRef = useRef<AudioSourceKind | null>(sourceKind ?? null);
+  sourceKindRef.current = sourceKind ?? null;
 
   const audioEnabled = status === 'capturing' && (mode === 'audio' || mode === 'mixed');
+  const isProcessSource = sourceKind === 'process_loopback';
 
   // 会话开始时重置恢复状态（audioSourceId 取会话启动瞬间的快照）
   useEffect(() => {
@@ -53,7 +65,7 @@ export function useAudioRecovery({ status, mode, audioSourceId, onNotify }: UseA
       await window.electronAPI.invoke('audio_capture_stop');
       await new Promise((r) => setTimeout(r, RESTART_CLEANUP_DELAY_MS));
       const result = await window.electronAPI.invoke('audio_capture_start', {
-        ...AUDIO_START_OPTIONS, sourceId,
+        ...AUDIO_START_OPTIONS, sourceId, preference: getAudioSourcePreference(),
       }) as { success: boolean; error?: string };
       if (result.success) silenceTrackerRef.current.reset();
       else console.warn('[useAudioRecovery] 音频捕获重启失败:', result.error);
@@ -66,12 +78,20 @@ export function useAudioRecovery({ status, mode, audioSourceId, onNotify }: UseA
     }
   }, []);
 
-  // 静音诊断：音频块正常但持续无声 → 提示核对系统默认输出设备
+  // 静音诊断：音频块正常但持续无声 → 按生效源给出对应成因
   useEffect(() => {
     if (!audioEnabled || !window.electronAPI) return;
     const off = window.electronAPI.on('audio_capture_chunk', (...args: unknown[]) => {
       const chunk = args[0] as { audioBuffer: ArrayBuffer };
       if (!silenceTrackerRef.current.push(computeChunkRms(chunk.audioBuffer))) return;
+
+      if (sourceKindRef.current === 'process_loopback') {
+        // 进程环回不受系统音量/输出设备影响，成因只能是目标窗口没在发声
+        notifyRef.current('warning',
+          '持续收到静音音频：当前只采集目标窗口的声音，请确认该窗口正在播放，' +
+          '或在设置中改为采集「系统全部声音」');
+        return;
+      }
       void getDefaultOutputDeviceLabel().then((label) => {
         notifyRef.current('warning',
           `持续收到静音音频：请确认视频声音正在播放，且输出到系统默认设备${label ? `「${label}」` : ''}（系统音频捕获只能录到默认输出设备的声音）`);
@@ -80,9 +100,9 @@ export function useAudioRecovery({ status, mode, audioSourceId, onNotify }: UseA
     return off;
   }, [audioEnabled]);
 
-  // 设备变更自动重启：重新绑定新的默认输出设备
+  // 设备变更自动重启：仅端点环回需要（它绑定系统默认输出设备）
   useEffect(() => {
-    if (!audioEnabled || !window.electronAPI) return;
+    if (!audioEnabled || !window.electronAPI || isProcessSource) return;
     const unsubscribe = subscribeDeviceChange(() => {
       console.info('[useAudioRecovery] 检测到音频设备变更，自动重启音频捕获');
       void restartCapture(effectiveSourceRef.current).then((ok) => {
@@ -91,5 +111,5 @@ export function useAudioRecovery({ status, mode, audioSourceId, onNotify }: UseA
       });
     });
     return unsubscribe;
-  }, [audioEnabled, restartCapture]);
+  }, [audioEnabled, isProcessSource, restartCapture]);
 }

client/src/features/classroom/hooks/useClassroomCapture.ts

@@ -12,6 +12,7 @@
 import { useState, useCallback, useEffect, useRef, useMemo } from 'react';
 import { useToast } from '@/components/ui/Toast';
 import { CaptureManager } from '@/lib/capture';
+import type { AudioSourceKind } from '@/lib/capture/audioSourceStrategy';
 import type {
   CaptureMode,
   CaptureSidebarConfig,
@@ -50,6 +51,10 @@ export function useClassroomCapture() {
   // ── 课中重点标记 ──
   const [bookmarks, setBookmarks] = useState<{ timestamp: number; label?: string }[]>([]);
 
+  // 本次会话实际生效的音频源（ADR-001）：由主进程选源后回传，
+  // 用于诊断文案分支与 UI 展示，避免对进程环回给出“检查输出设备”类误导提示
+  const [audioSourceKind, setAudioSourceKind] = useState<AudioSourceKind | null>(null);
+
   const notify = useCallback((type: 'success' | 'warning' | 'error' | 'info', message: string) => {
     toast({ type, message });
   }, [toast]);
@@ -107,9 +112,9 @@ export function useClassroomCapture() {
     captureManager, status, mode, onNotify: notify,
   });
 
-  // 音频自动恢复：静音诊断 / 窗口源回退环回 / 设备变更重启
+  // 音频自动恢复：静音诊断（文案按生效源分支）/ 设备变更重启
   useAudioRecovery({
-    status, mode, audioSourceId: selectedWindow?.id, onNotify: notify,
+    status, mode, audioSourceId: selectedWindow?.id, sourceKind: audioSourceKind, onNotify: notify,
   });
 
   const analysis = useClassroomAnalysis({
@@ -150,6 +155,7 @@ export function useClassroomCapture() {
     onAnalyzeFull: analysis.handleAnalyze,
     onMergePartials: analysis.mergePartialNotes,
     onNotify: (type, message) => notify(type, message),
+    onAudioSourceResolved: setAudioSourceKind,
   });
 
   const handleModeChange = useCallback((newMode: CaptureMode) => {
@@ -214,6 +220,8 @@ export function useClassroomCapture() {
     liveTranscripts: events.liveTranscripts,
     // 音频健康 + VAD
     audioHealth, vadStats: events.vadStats,
+    // 本次会话生效的音频源（UI 可见，供内测归因）
+    audioSourceKind,
     // 课程上下文
     courseMeta, setCourseMeta, aiDetectEnabled, setAiDetectEnabled,
     // 录制

client/src/features/classroom/hooks/useSessionControl.ts

@@ -12,6 +12,8 @@ import { useCallback } from 'react';
 import { requireGatewayUrl } from '@/lib/ai/config';
 import { soundPlayer } from '@/lib/audio/SoundPlayer';
 import { analyzePartial } from '@/lib/ai/sessionAnalyzer';
+import { getAudioSourcePreference } from '@/lib/capture/audioSourcePreference';
+import type { AudioSourceKind } from '@/lib/capture/audioSourceStrategy';
 import type {
   CaptureManager,
   CaptureMode,
@@ -28,6 +30,10 @@ import type {
 interface IPCAudioStartResult {
   success: boolean;
   error?: string;
+  /** 实际生效的音频源（ADR-001 双源选择结果） */
+  sourceKind?: AudioSourceKind;
+  /** 选源理由（含降级说明），供内测问题归因 */
+  sourceReason?: string;
 }
 
 interface UseSessionControlOptions {
@@ -56,12 +62,14 @@ interface UseSessionControlOptions {
   onAnalyzeFull: () => void;
   onMergePartials: (partials: string[], durationMs: number, keyframeCount: number) => Promise<void>;
   onNotify: (type: 'warning', message: string) => void;
+  /** 音频源定下后回报（供诊断文案分支与 UI 展示） */
+  onAudioSourceResolved?: (kind: AudioSourceKind | null) => void;
 }
 
 export function useSessionControl({
   captureManager, selectedWindow, status, setStatus, mode, capturePath, config, courseMeta,
   frameRestartRef, audioCleanupRef, session,
-  onAnalyzeVideo, onAnalyzeFull, onMergePartials, onNotify,
+  onAnalyzeVideo, onAnalyzeFull, onMergePartials, onNotify, onAudioSourceResolved,
 }: UseSessionControlOptions) {
   /** 预检 AI 网关连通性（不可用仅提示，不阻断采集） */
   const probeGateway = useCallback(async () => {
@@ -130,14 +138,22 @@ export function useSessionControl({
 
       if (audioEnabled) {
         try {
-          // 方案A：优先以选中窗口为音频源（直采 B站客户端/浏览器等目标应用声音），
-          // 窗口级捕获不受支持时主进程会下发环回降级候选，由渲染端自动回退
+          // 选源由主进程的 selectAudioSource 决定（ADR-001）：锁定具体窗口时
+          // 优先进程环回（隔离其他应用杂音），否则用端点环回（不漏采）；
+          // 主进程读不到 localStorage，故偏好由渲染进程传入
           const audioResult = await window.electronAPI.invoke('audio_capture_start', {
             chunkDurationMs: 5000, sampleRate: 16000, channels: 1,
             sourceId: selectedWindow.id,
+            preference: getAudioSourcePreference(),
           }) as IPCAudioStartResult;
           if (!audioResult.success) {
             console.warn('[useClassroomCapture] Audio start failed:', audioResult.error);
+          } else {
+            console.info(
+              `[useClassroomCapture] 音频源=${audioResult.sourceKind ?? 'unknown'}` +
+              `（${audioResult.sourceReason ?? '-'}）`,
+            );
+            onAudioSourceResolved?.(audioResult.sourceKind ?? null);
           }
         } catch (audioErr) {
           console.warn('[useClassroomCapture] Audio unavailable:', audioErr);
@@ -147,7 +163,7 @@ export function useSessionControl({
       setStatus('error');
       console.error('[useClassroomCapture] Start failed:', err);
     }
-  }, [selectedWindow, setStatus, session, probeGateway, capturePath, captureManager, config, mode, courseMeta]);
+  }, [selectedWindow, setStatus, session, probeGateway, capturePath, captureManager, config, mode, courseMeta, onAudioSourceResolved]);
 
   const handlePause = useCallback(() => {
     if (status === 'capturing') {

client/src/lib/capture/audioSourcePreference.test.ts

@@ -0,0 +1,60 @@
+/**
+ * @ai-context: 音频源偏好持久化单测。重点覆盖"读取失败/非法值必须回落
+ * 到 auto"——偏好读取绝不能阻断采集启动（见 audioSourcePreference 头注）。
+ */
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import {
+  getAudioSourcePreference,
+  setAudioSourcePreference,
+  AUDIO_SOURCE_PREFERENCE_KEY,
+  AUDIO_SOURCE_PREFERENCE_LABELS,
+} from './audioSourcePreference';
+
+describe('audioSourcePreference', () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('未设置时默认 auto', () => {
+    expect(getAudioSourcePreference()).toBe('auto');
+  });
+
+  it('可写入并读回三种合法值', () => {
+    for (const value of ['auto', 'force_process', 'force_endpoint'] as const) {
+      setAudioSourcePreference(value);
+      expect(getAudioSourcePreference()).toBe(value);
+    }
+  });
+
+  it('存储中的非法值回落到 auto', () => {
+    localStorage.setItem(AUDIO_SOURCE_PREFERENCE_KEY, 'force_microphone');
+    expect(getAudioSourcePreference()).toBe('auto');
+  });
+
+  it('localStorage 读取抛错时回落到 auto 而非抛出', () => {
+    vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+      throw new Error('storage unavailable');
+    });
+    expect(() => getAudioSourcePreference()).not.toThrow();
+    expect(getAudioSourcePreference()).toBe('auto');
+  });
+
+  it('localStorage 写入抛错时静默降级而非抛出', () => {
+    vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+      throw new Error('quota exceeded');
+    });
+    expect(() => setAudioSourcePreference('force_process')).not.toThrow();
+  });
+
+  it('每种偏好都有非空的标签与说明（设置页依赖）', () => {
+    for (const value of ['auto', 'force_process', 'force_endpoint'] as const) {
+      const { label, hint } = AUDIO_SOURCE_PREFERENCE_LABELS[value];
+      expect(label.length).toBeGreaterThan(0);
+      expect(hint.length).toBeGreaterThan(0);
+    }
+  });
+});