feat(audio): 接入进程环回 Provider 与构建链路（Phase 2，flag 默认关）

ADR-001 Phase 2：原生进程环回接入编排器，特性开关默认关闭，行为与
Phase 0 一致；开启方式为环境变量 ENTROPY_PROCESS_LOOPBACK=1。

- processAudioNative：原生模块加载器。addon 视为可选依赖，未编译/非 Windows/
  版本过低均优雅降级为'能力不可用'，加载失败不冒泡到启动路径；能力探测与
  加载结果缓存到进程生命周期
- processLoopbackProvider：窗口源 ID 解析 HWND → 匹配原生枚举取进程树根 PID；
  采集在主进程完成故不实现 handleRendererChunk
- audioCapture：接入能力探测与 flag；新增运行时降级——采集开始后才发生的
  进程环回故障（如目标进程退出）无缝切回端点环回
- 构建链路：native:install / native:build 脚本（electron-rebuild 针对
  Electron ABI 编译）、electron-builder files 纳入 .node 产物（已有
  asarUnpack 解包）、CI 增加编译步骤（continue-on-error + 产物检查告警，
  编译失败不阻断发布）

验证：client 473 tests、lint 0 errors、渲染与主进程 tsc 均 0；
electron-rebuild 针对 Electron ABI 重建通过。

未纳入本阶段：useAudioRecovery 按源分支提示文案（flag 关闭时现有文案正确），
留待 Phase 3 灰度开启时一并处理。

Author: Aparencia

.github/workflows/release.yml

@@ -59,6 +59,24 @@ jobs:
           cache: 'npm'
           cache-dependency-path: client/package-lock.json
       - run: cd client && npm ci
+      # 进程环回原生模块（ADR-001）：windows-latest 自带 MSVC，针对 Electron ABI 编译。
+      # continue-on-error：它是可选增强（运行时未加载到则降级为端点环回），
+      # 不应因其编译失败而阻断整条发布流水线
+      - name: Build native process-audio module
+        continue-on-error: true
+        run: |
+          cd client
+          npm run native:install
+          npm run native:build
+      - name: Check native module artifact
+        shell: bash
+        run: |
+          cd client
+          if [ -f native/process-audio/build/Release/process_audio.node ]; then
+            echo "进程环回原生模块已就绪"
+          else
+            echo "::warning::进程环回原生模块未构建成功，本包仅支持端点环回采集"
+          fi
       # --publish never：发布由下方 release job 统一负责，避免 electron-builder
       # 因检测到 tag 而自行尝试发布（github provider 无 GH_TOKEN 会报错）
       #

client/electron-builder.yml

@@ -25,6 +25,10 @@ files:
   - dist/**/*
   - dist-electron/**/*
   - app-icon.png
+  # 进程环回原生模块（ADR-001）：仅打包编译产物，不带 src/node_modules。
+  # 经上方 asarUnpack 解到 app.asar.unpacked/，processAudioNative 按此路径加载；
+  # 未编译时此匹配为空，应用仍可正常启动（降级为端点环回）
+  - native/process-audio/build/Release/*.node
 # 图标说明：
 #   app-icon.png 为统一源文件（1024x1024 方形 PNG）。
 #   electron-builder 会自动将其转换为各平台所需格式：

client/electron/audio/processAudioNative.ts

@@ -0,0 +1,121 @@
+/**
+ * 进程环回原生模块加载器
+ *
+ * @ai-context: 原生 addon 是可选依赖——未编译、非 Windows、或 Windows 版本
+ * 过低时必须优雅降级为"能力不可用"，绝不能让加载失败冒泡到应用启动路径
+ * （AGENTS.md 高风险区约定）。故此处用 try/catch 包裹 require 并缓存结果。
+ * @ai-context: 能力探测（isProcessLoopbackSupported）会真实尝试激活一次
+ * WASAPI 接口，有几毫秒开销，因此结果缓存到进程生命周期。
+ */
+
+import * as path from 'path';
+import { app } from 'electron';
+import { logger } from '../logger.js';
+
+/** 原生模块导出的窗口信息 */
+export interface NativeWindowInfo {
+  hwnd: string;
+  pid: number;
+  rootPid: number;
+  title: string;
+  processName: string;
+  rootProcessName: string;
+}
+
+/** 原生模块流式回调的负载：音频块或错误 */
+export interface NativeStreamPayload {
+  audioBuffer?: ArrayBuffer;
+  sampleRate?: number;
+  channels?: number;
+  durationMs?: number;
+  error?: string;
+}
+
+/** 原生模块导出接口 */
+export interface ProcessAudioNative {
+  listAudioWindows(): NativeWindowInfo[];
+  resolveRootPid(pid: number): number;
+  isProcessLoopbackSupported(): boolean;
+  startCapture(
+    options: { pid: number; sampleRate: number; channels: number; chunkDurationMs: number },
+    callback: (payload: NativeStreamPayload) => void,
+  ): { ok: boolean; error: string };
+  stopCapture(): boolean;
+}
+
+/** 加载状态缓存（undefined 表示尚未尝试加载） */
+let cached: ProcessAudioNative | null | undefined;
+let supportedCache: boolean | undefined;
+
+/** 候选路径：开发态走源码目录构建产物，打包后走 asarUnpack 解出的目录 */
+function candidatePaths(): string[] {
+  const fileName = 'process_audio.node';
+  const appPath = app.getAppPath();
+  return [
+    // 打包后：asarUnpack 将 .node 解到 app.asar.unpacked 下
+    path.join(appPath.replace('app.asar', 'app.asar.unpacked'), 'native', 'process-audio', 'build', 'Release', fileName),
+    // 开发态：client/native/process-audio/build/Release
+    path.join(appPath, 'native', 'process-audio', 'build', 'Release', fileName),
+  ];
+}
+
+/**
+ * 加载原生模块；不可用时返回 null（不抛错）。
+ */
+export function loadProcessAudioNative(): ProcessAudioNative | null {
+  if (cached !== undefined) return cached;
+
+  if (process.platform !== 'win32') {
+    logger.info('[ProcessAudio] 非 Windows 平台，进程环回不可用');
+    cached = null;
+    return cached;
+  }
+
+  // 主进程编译目标为 CommonJS，直接用全局 require 动态加载 .node
+  for (const candidate of candidatePaths()) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const native = require(candidate) as ProcessAudioNative;
+      if (typeof native.startCapture === 'function') {
+        logger.info(`[ProcessAudio] 原生模块已加载: ${candidate}`);
+        cached = native;
+        return cached;
+      }
+    } catch {
+      // 继续尝试下一个候选路径
+    }
+  }
+
+  logger.info('[ProcessAudio] 原生模块未找到（未编译或未随包分发），进程环回不可用');
+  cached = null;
+  return cached;
+}
+
+/**
+ * 进程环回是否可用（模块已加载 + 系统 API 可用）。
+ * 结果缓存到进程生命周期。
+ */
+export function isProcessLoopbackAvailable(): boolean {
+  if (supportedCache !== undefined) return supportedCache;
+
+  const native = loadProcessAudioNative();
+  if (!native) {
+    supportedCache = false;
+    return supportedCache;
+  }
+  try {
+    supportedCache = native.isProcessLoopbackSupported();
+    logger.info(`[ProcessAudio] 系统能力探测: ${supportedCache ? '支持' : '不支持'}（需 Windows 10 2004+）`);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    logger.warn(`[ProcessAudio] 能力探测异常，视为不可用: ${message}`);
+    supportedCache = false;
+  }
+  return supportedCache;
+}
+
+/** 仅测试用：重置缓存 */
+export function resetProcessAudioCacheForTest(): void {
+  cached = undefined;
+  supportedCache = undefined;
+}

client/electron/audio/processLoopbackProvider.ts

@@ -0,0 +1,125 @@
+/**
+ * 进程环回 Provider（Windows 原生 WASAPI 路径）
+ *
+ * @ai-context: 见 ADR-001。与端点环回的关键差异：采集完全在主进程完成
+ * （原生采集线程 → ThreadSafeFunction → 主进程 JS），不经渲染进程，
+ * 故不实现 handleRendererChunk；产出的块直接交 sink。
+ * @ai-context: 目标 PID 解析——desktopCapturer 的 window id 形如
+ * `window:<HWND>:0`，取 HWND 匹配原生枚举结果得到进程树根。Chromium 顶层
+ * 窗口本身即归属 browser process，故 rootPid 通常等于 pid；仍走 rootPid
+ * 以覆盖窗口归属子进程的应用。
+ * @ai-context: 启动期失败（目标不可采/激活失败）经 onFatal 异步上报，
+ * 由编排器触发降级到端点环回。
+ */
+
+import { logger } from '../logger.js';
+import { loadProcessAudioNative, type NativeWindowInfo } from './processAudioNative.js';
+import type {
+  AudioChunkSink,
+  AudioProviderStartContext,
+  AudioSourceProvider,
+} from './audioSourceProvider.js';
+import type { AudioSourceKind } from '../../src/lib/capture/audioSourceStrategy.js';
+
+/** 从 desktopCapturer 的 window id 中解析 HWND；失败返回 null */
+export function parseHwndFromSourceId(sourceId: string | null): string | null {
+  if (!sourceId || !sourceId.startsWith('window:')) return null;
+  const parts = sourceId.split(':');
+  if (parts.length < 2 || !parts[1]) return null;
+  // id 形如 window:395794:0，中间段为十进制 HWND
+  return parts[1];
+}
+
+export class ProcessLoopbackProvider implements AudioSourceProvider {
+  readonly kind: AudioSourceKind = 'process_loopback';
+
+  private readonly sink: AudioChunkSink;
+  /** 致命错误上报（编排器据此降级） */
+  private readonly onFatal: (message: string) => void;
+  private capturing = false;
+  private disposed = false;
+
+  constructor(sink: AudioChunkSink, onFatal: (message: string) => void) {
+    this.sink = sink;
+    this.onFatal = onFatal;
+  }
+
+  async start(ctx: AudioProviderStartContext): Promise<void> {
+    if (this.capturing || this.disposed) return;
+
+    const native = loadProcessAudioNative();
+    if (!native) throw new Error('进程环回原生模块不可用');
+
+    const targetPid = this.resolveTargetPid(native.listAudioWindows(), ctx.sourceId);
+    if (targetPid === null) {
+      throw new Error('无法解析目标窗口所属进程，请改用系统音频采集');
+    }
+
+    const result = native.startCapture(
+      {
+        pid: targetPid,
+        sampleRate: ctx.options.sampleRate,
+        channels: ctx.options.channels,
+        chunkDurationMs: ctx.options.chunkDurationMs,
+      },
+      (payload) => {
+        if (this.disposed) return;
+        if (payload.error) {
+          logger.warn(`[ProcessLoopback] 采集错误: ${payload.error}`);
+          this.onFatal(payload.error);
+          return;
+        }
+        if (!payload.audioBuffer) return;
+        this.sink({
+          audioBuffer: payload.audioBuffer,
+          sampleRate: payload.sampleRate ?? ctx.options.sampleRate,
+          channels: payload.channels ?? ctx.options.channels,
+          durationMs: payload.durationMs ?? ctx.options.chunkDurationMs,
+        });
+      },
+    );
+
+    if (!result.ok) throw new Error(result.error || '进程环回启动失败');
+
+    this.capturing = true;
+    logger.info(
+      `[ProcessLoopback] 开始捕获, targetPid=${targetPid}, ` +
+      `chunkDurationMs=${ctx.options.chunkDurationMs}, ` +
+      `sampleRate=${ctx.options.sampleRate}, channels=${ctx.options.channels}`,
+    );
+  }
+
+  /** 由窗口源 ID 定位进程树根 PID */
+  private resolveTargetPid(windows: NativeWindowInfo[], sourceId: string | null): number | null {
+    const hwnd = parseHwndFromSourceId(sourceId);
+    if (!hwnd) return null;
+    const matched = windows.find((w) => w.hwnd === hwnd);
+    if (!matched) {
+      logger.warn(`[ProcessLoopback] 未在窗口列表中找到 HWND=${hwnd}`);
+      return null;
+    }
+    logger.info(
+      `[ProcessLoopback] 目标窗口="${matched.title}" pid=${matched.pid} ` +
+      `rootPid=${matched.rootPid} (${matched.rootProcessName})`,
+    );
+    return matched.rootPid;
+  }
+
+  stop(): void {
+    if (!this.capturing) return;
+    this.capturing = false;
+    const native = loadProcessAudioNative();
+    try {
+      native?.stopCapture();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.warn(`[ProcessLoopback] stopCapture 异常: ${message}`);
+    }
+    logger.info('[ProcessLoopback] 停止捕获');
+  }
+
+  dispose(): void {
+    this.stop();
+    this.disposed = true;
+  }
+}

client/electron/audioCapture.ts

@@ -16,6 +16,8 @@
 import type { BrowserWindow } from 'electron';
 import { logger } from './logger.js';
 import { EndpointLoopbackProvider, listAudioSources } from './audio/endpointLoopbackProvider.js';
+import { ProcessLoopbackProvider } from './audio/processLoopbackProvider.js';
+import { isProcessLoopbackAvailable } from './audio/processAudioNative.js';
 import type {
   AudioCaptureOptions,
   AudioChunk,
@@ -29,6 +31,16 @@ import {
   type AudioSourcePreference,
 } from '../src/lib/capture/audioSourceStrategy.js';
 
+/**
+ * 进程环回特性开关（Phase 2：默认关）。
+ *
+ * 开启方式：环境变量 ENTROPY_PROCESS_LOOPBACK=1。
+ * Phase 3 经内测灰度后改为默认开并改由设置页控制。
+ */
+function isProcessLoopbackEnabled(): boolean {
+  return process.env.ENTROPY_PROCESS_LOOPBACK === '1';
+}
+
 // 保持既有导出路径不变（mediaCaptureHandlers 等调用方无需改动）
 export { listAudioSources };
 export type { AudioCaptureOptions, AudioChunk } from './audio/audioSourceProvider.js';
@@ -74,6 +86,9 @@ export class AudioCapture {
   private provider: AudioSourceProvider | null = null;
   /** 本次采集的选源决策（供日志/会话元数据归因） */
   private decision: AudioSourceDecision | null = null;
+  /** 绑定的窗口与源 ID（运行时降级需重建 Provider） */
+  private boundWindow: BrowserWindow | null = null;
+  private boundSourceId: string | null = null;
 
   constructor(
     options: Partial<AudioCaptureOptions>,
@@ -117,9 +132,10 @@ export class AudioCapture {
     if (this.capturing || this.disposed) return;
 
     const resolvedSourceId = sourceId ?? null;
+    // 特性开关关闭时能力恒为不可用，选源必为端点环回（行为与 Phase 0 一致）
+    const processAvailable = isProcessLoopbackEnabled() && isProcessLoopbackAvailable();
     this.decision = selectAudioSource({
-      // Phase 0：进程环回尚未接入，能力探测恒为不可用（行为与重构前一致）
-      capabilities: { processLoopbackAvailable: false },
+      capabilities: { processLoopbackAvailable: processAvailable },
       sourceId: resolvedSourceId,
       preference: extras?.preference,
       microphone: extras?.microphone,
@@ -155,6 +171,8 @@ export class AudioCapture {
     win: BrowserWindow,
     sourceId: string | null,
   ): Promise<void> {
+    this.boundWindow = win;
+    this.boundSourceId = sourceId;
     this.provider?.dispose();
     this.provider = this.createProvider(kind);
     await this.provider.start({ window: win, sourceId, options: this.options });
@@ -167,14 +185,39 @@ export class AudioCapture {
       case 'endpoint_loopback':
         return new EndpointLoopbackProvider(sink);
       case 'process_loopback':
-        // Phase 2 接入；Phase 0 阶段选源不会产生该分支
-        throw new Error('进程环回 Provider 尚未接入');
+        // 采集中发生的致命错误（如目标进程退出）触发运行时降级
+        return new ProcessLoopbackProvider(sink, (message) => {
+          void this.degradeToEndpoint(message);
+        });
       case 'microphone':
         // TODO(现场课程): MicrophoneProvider 待实现
         throw new Error('麦克风 Provider 尚未实现');
     }
   }
 
+  /**
+   * 运行时降级：采集已开始后才发生的进程环回故障，无缝切到端点环回。
+   * 失败时仅记日志：此时已脱离 start 调用栈，抛错无人接收，
+   * 且上层 watchdog（useClassroomAudio）会在 15s 内提示用户。
+   */
+  private async degradeToEndpoint(reason: string): Promise<void> {
+    if (this.disposed || !this.capturing) return;
+    if (this.provider?.kind !== 'process_loopback') return;
+    if (!this.boundWindow || this.boundWindow.isDestroyed()) return;
+
+    logger.warn(`[AudioCapture] 进程环回运行中故障（${reason}），切换到端点环回`);
+    this.decision = {
+      kind: 'endpoint_loopback',
+      reason: `进程环回运行中故障后降级：${reason}`,
+      fallback: null,
+    };
+    try {
+      await this.startWithKind('endpoint_loopback', this.boundWindow, this.boundSourceId);
+    } catch (err) {
+      logger.error('[AudioCapture] 降级到端点环回失败', err);
+    }
+  }
+
   /** 统一补时间戳后向消费者分发 */
   private emitChunk(data: RendererAudioChunk): void {
     if (this.disposed) return;
@@ -208,6 +251,8 @@ export class AudioCapture {
     this.stop();
     this.provider?.dispose();
     this.provider = null;
+    this.boundWindow = null;
+    this.boundSourceId = null;
     this.disposed = true;
     logger.info('[AudioCapture] 已销毁');
   }