fix(ai-asr): 重构 ASR 引擎为 zipformer-transducer 单引擎

- 移除离线 SenseVoice 引擎，统一为 zipformer-transducer 中英双语流式模型
- 流式与按段转写共用同一引擎，简化维护
- 下载流程增加 Transform 流背压控制 + 10 分钟总超时保护
- 流式启动支持热词增强透传（createStream hotwords）
- 双版本 API 兼容（工厂函数 <=1.12 / 类导出 1.13+）

Author: Aparencia

client/electron/ai/local-asr/SherpaAsrService.ts

@@ -2,19 +2,20 @@
  * 本地 ASR — sherpa-onnx 语音识别服务
  *
  * @ai-context: 基于 sherpa-onnx-node 原生 addon 实现本地 ASR。
- * 双引擎架构：
- * - offline（SenseVoice）：非流式，50ms/段极速推理，中文准确率最高，课后精修
- * - streaming（Paraformer）：流式，边说边出 < 200ms 延迟，实时字幕
+ * 单一引擎：zipformer-transducer 中英双语流式模型，同时承担实时流式
+ * 转写（streamingAsr.ts 真流式路径）与按段转写（transcribeLocal 路径）。
+ * @ai-context: zipformer-transducer 支持 createStream(hotwords) 热词增强，
+ * 热词字符串由调用方经 IPC payload 透传（详见 local_asr_transcribe 与
+ * local_asr_stream_start 接口）。
  * @ai-context: sherpa-onnx-node 为可选依赖（optionalDependencies），
  * 加载失败时 isAvailable() 返回 false，上层自动降级到云端 ASR。
  * 符合项目"可选增强"设计原则。
  * @ai-context: 音频输入要求：16kHz 单声道 Float32 PCM。
  * 渲染进程发来的音频块已满足此格式（process-audio native addon 输出）。
  * @ai-context: sherpa-onnx-node API 兼容：旧版（<=1.12）导出工厂函数
- * createOfflineRecognizer/createOnlineRecognizer；新版（1.13+，如 1.13.4）
- * 改为导出类 OfflineRecognizer/OnlineRecognizer（new 构造，config 形状不变）。
- * 下方工厂包装双路径兼容，否则升级依赖后 TypeError: ... is not a function
- * （2026-08 真流式启动失败根因，离线路径同样受影响）。
+ * createOnlineRecognizer；新版（1.13+，如 1.13.4）改为导出类
+ * OnlineRecognizer（new 构造，config 形状不变）。
+ * 下方工厂包装双路径兼容，否则升级依赖后 TypeError: ... is not a function。
  */
 
 import * as path from 'path';
@@ -25,7 +26,7 @@ import {
   getLocalAsrConfig,
   getModelDir,
   isModelReady,
-  type AsrEngine,
+  MODEL_FILES,
 } from './config.js';
 
 // ================================================================
@@ -37,30 +38,13 @@ type RecognizerCtor<T> = new (config: Record<string, unknown>) => T;
 
 interface SherpaOnnx {
   /** 旧版 API（<=1.12）：工厂函数 */
-  createOfflineRecognizer?: (config: Record<string, unknown>) => OfflineRecognizer;
   createOnlineRecognizer?: (config: Record<string, unknown>) => OnlineRecognizer;
   /** 新版 API（1.13+）：类导出 */
-  OfflineRecognizer?: RecognizerCtor<OfflineRecognizer>;
   OnlineRecognizer?: RecognizerCtor<OnlineRecognizer>;
 }
 
-interface OfflineRecognizer {
-  createStream(): OfflineStream;
-  decode(stream: OfflineStream): void;
-  getResult(stream: OfflineStream): { text: string };
-}
-
-interface OfflineStream {
-  /** 旧版：(sampleRate, samples)；新版 1.13+：({ samples, sampleRate })，统一走 feedWaveform */
-  acceptWaveform(sampleRate: number, samples: Float32Array): void;
-  acceptWaveform(waveform: { samples: Float32Array; sampleRate: number }): void;
-  inputFinished(): void;
-  /** 新版 OnlineStream/OfflineStream 未提供 free（句柄由 GC 回收），故为可选 */
-  free?(): void;
-}
-
 export interface OnlineRecognizer {
-  createStream(): OnlineStream;
+  createStream(hotwords?: string): OnlineStream;
   decode(stream: OnlineStream): void;
   isReady(stream: OnlineStream): boolean;
   getResult(stream: OnlineStream): { text: string };
@@ -73,6 +57,7 @@ export interface OnlineStream {
   acceptWaveform(sampleRate: number, samples: Float32Array): void;
   acceptWaveform(waveform: { samples: Float32Array; sampleRate: number }): void;
   inputFinished(): void;
+  /** 新版 OnlineStream 未提供 free（句柄由 GC 回收），故为可选 */
   free?(): void;
 }
 
@@ -83,7 +68,7 @@ export interface OnlineStream {
  * 按函数形参数（length）判别，调用方无需感知版本。
  */
 export function feedWaveform(
-  stream: OnlineStream | OfflineStream,
+  stream: OnlineStream,
   sampleRate: number,
   samples: Float32Array,
 ): void {
@@ -97,17 +82,6 @@ export function feedWaveform(
 let _sherpa: SherpaOnnx | null = null;
 let _loadAttempted = false;
 
-/** 创建离线识别器：优先旧版工厂函数，缺失时用新版类构造 */
-function instantiateOffline(sherpa: SherpaOnnx, config: Record<string, unknown>): OfflineRecognizer {
-  if (typeof sherpa.createOfflineRecognizer === 'function') {
-    return sherpa.createOfflineRecognizer(config);
-  }
-  if (typeof sherpa.OfflineRecognizer === 'function') {
-    return new sherpa.OfflineRecognizer(config);
-  }
-  throw new Error('sherpa-onnx-node 既无 createOfflineRecognizer 工厂也无 OfflineRecognizer 类，请核对依赖版本');
-}
-
 /** 创建在线识别器：优先旧版工厂函数，缺失时用新版类构造 */
 function instantiateOnline(sherpa: SherpaOnnx, config: Record<string, unknown>): OnlineRecognizer {
   if (typeof sherpa.createOnlineRecognizer === 'function') {
@@ -139,67 +113,42 @@ function loadSherpa(): SherpaOnnx | null {
 // Recognizer 单例缓存
 // ================================================================
 
-let _offlineRecognizer: OfflineRecognizer | null = null;
 let _onlineRecognizer: OnlineRecognizer | null = null;
 
-/** 获取/创建 SenseVoice 非流式识别器（单例） */
-function getOfflineRecognizer(): OfflineRecognizer | null {
-  if (_offlineRecognizer) return _offlineRecognizer;
-
-  const sherpa = loadSherpa();
-  if (!sherpa) return null;
-  if (!isModelReady('offline')) return null;
-
-  const modelDir = getModelDir('offline');
-  const config = getLocalAsrConfig();
-  const threads = config.threads > 0 ? config.threads : Math.max(1, os.cpus().length - 1);
-
-  try {
-    _offlineRecognizer = instantiateOffline(sherpa, {
-      featConfig: { sampleRate: 16000, featureDim: 80 },
-      modelConfig: {
-        senseVoice: {
-          model: path.join(modelDir, 'model.int8.onnx'),
-          language: config.language === 'auto' ? 'auto' : config.language,
-          useItn: true,
-        },
-        tokens: path.join(modelDir, 'tokens.txt'),
-        numThreads: threads,
-        provider: 'cpu',
-      },
-    });
-    logger.info(`[LocalASR] SenseVoice offline recognizer created (threads=${threads})`);
-    return _offlineRecognizer;
-  } catch (err) {
-    logger.error(`[LocalASR] Failed to create offline recognizer: ${err}`);
-    return null;
-  }
-}
-
-/** 获取/创建 Paraformer 流式识别器（单例） */
+/** 获取/创建 Zipformer 流式识别器（单例） */
 export function getOnlineRecognizer(): OnlineRecognizer | null {
   if (_onlineRecognizer) return _onlineRecognizer;
 
   const sherpa = loadSherpa();
   if (!sherpa) return null;
-  if (!isModelReady('streaming')) return null;
+  if (!isModelReady()) return null;
 
-  const modelDir = getModelDir('streaming');
+  const modelDir = getModelDir();
   const config = getLocalAsrConfig();
-  const threads = config.threads > 0 ? config.threads : Math.max(1, os.cpus().length - 1);
+  const cpuCount = Math.max(1, os.cpus().length);
+  const rawThreads = config.threads > 0 ? config.threads : Math.max(1, cpuCount - 1);
+  // 线程数上限：不超过 CPU 核心数（防止用户配置过大值导致 CPU 过载）
+  const threads = Math.min(rawThreads, cpuCount);
 
   try {
     _onlineRecognizer = instantiateOnline(sherpa, {
       featConfig: { sampleRate: 16000, featureDim: 80 },
       modelConfig: {
-        paraformer: {
-          encoder: path.join(modelDir, 'encoder.onnx'),
-          decoder: path.join(modelDir, 'decoder.onnx'),
+        // zipformer2 属于 transducer 类模型：sherpa-onnx-node 的 C API 字段为
+        // `transducer`（encoder/decoder/joiner 三件套），没有 `zipformer2` 字段；
+        // 曾误用 zipformer2 导致字段被忽略、encoder 为空而创建失败
+        transducer: {
+          encoder: path.join(modelDir, MODEL_FILES.encoder),
+          decoder: path.join(modelDir, MODEL_FILES.decoder),
+          joiner: path.join(modelDir, MODEL_FILES.joiner),
         },
-        tokens: path.join(modelDir, 'tokens.txt'),
+        tokens: path.join(modelDir, MODEL_FILES.tokens),
         numThreads: threads,
         provider: 'cpu',
       },
+      // enableEndpoint 显式开启：sherpa-onnx-node 1.13+ 官方 API 为扁平字段，
+      // 同时保留 endpointConfig 嵌套形状以兼容 rule2.minUtteranceLength=8
+      enableEndpoint: true,
       endpointConfig: {
         rule1: { minTrailingSilence: 2.4 },
         // rule2 必须配 minUtteranceLength：仅给 minTrailingSilence 时默认 0，
@@ -209,7 +158,7 @@ export function getOnlineRecognizer(): OnlineRecognizer | null {
         rule3: { minUtteranceLength: 20 },
       },
     });
-    logger.info(`[LocalASR] Paraformer streaming recognizer created (threads=${threads})`);
+    logger.info(`[LocalASR] Zipformer streaming recognizer created (threads=${threads})`);
     return _onlineRecognizer;
   } catch (err) {
     logger.error(`[LocalASR] Failed to create streaming recognizer: ${err}`);
@@ -221,100 +170,53 @@ export function getOnlineRecognizer(): OnlineRecognizer | null {
 // 公共 API
 // ================================================================
 
-/**
- * TODO(P1-3 热词增强): 经查 sherpa-onnx-node 类型声明，hotwords 仅 transducer
- * 系模型支持（OfflineStream createStream(hotwords)，见 non-streaming-asr.js 注释
- * "Hotwords are supported only by transducer models"）；本项目使用的
- * SenseVoice（offline）与 Paraformer（streaming）均不支持。故本期不透传热词，
- * 渲染进程词表 boost 词条已由 hotwordRuntime.getSessionBoostWords() 预留，
- * 未来若换用 zipformer-transducer 模型，可给 local_asr_transcribe /
- * local_asr_stream_start 的 IPC payload 增加可选 hotwords 字段（旧载荷须兼容）
- * 并在 createStream 时传入。云端网关热词透传同为遗留项（不改 transcribe.py）。
- */
-
 /**
  * 检测本地 ASR 是否可用（sherpa-onnx 已加载 + 模型已下载）
  */
 export async function checkLocalAsrAvailable(): Promise<boolean> {
   const sherpa = loadSherpa();
   if (!sherpa) return false;
-
-  const config = getLocalAsrConfig();
-  return isModelReady(config.engine);
+  return isModelReady();
 }
 
 /**
- * 真流式 ASR 是否可用（同步）：sherpa 已加载 + 本地 ASR 启用 + streaming（Paraformer）模型就绪。
+ * 真流式 ASR 是否可用（同步）：sherpa 已加载 + 本地 ASR 启用 + 模型就绪。
  * 供课堂智能采集决定是否走真流式链路（否则回退按段转写）。
  */
 export function isStreamingAsrAvailable(): boolean {
   const sherpa = loadSherpa();
   if (!sherpa) return false;
   if (!getLocalAsrConfig().enabled) return false;
-  return isModelReady('streaming');
+  return isModelReady();
 }
 
 /** 重置可用性缓存（模型下载完成后调用） */
 export function resetAvailabilityCache(): void {
-  _offlineRecognizer = null;
   _onlineRecognizer = null;
 }
 
 /**
- * 非流式转写（SenseVoice）— 适合课后全量分析
- *
- * @param pcmData - Float32 PCM 音频数据（16kHz 单声道）
- * @param options - 转写选项
- * @returns 转写结果
- */
-export async function transcribeOffline(
-  pcmData: Float32Array,
-  options?: { language?: string },
-): Promise<{ text: string; engine: 'offline'; durationMs: number }> {
-  const startTime = Date.now();
-
-  const recognizer = getOfflineRecognizer();
-  if (!recognizer) {
-    throw new Error('SenseVoice 识别器不可用（模型未下载或 sherpa-onnx 未安装）');
-  }
-
-  const stream = recognizer.createStream();
-  try {
-    feedWaveform(stream, 16000, pcmData);
-    stream.inputFinished();
-    recognizer.decode(stream);
-    const result = recognizer.getResult(stream);
-    // 输出后处理：相邻重复压缩 + 幻觉过滤（与流式路径一致，见 streamingAsr.ts）
-    const text = cleanAsrResult(result.text ?? '');
-    const durationMs = Date.now() - startTime;
-
-    logger.debug(`[LocalASR] Offline transcribe: ${text.length} chars, ${durationMs}ms`);
-    return { text, engine: 'offline', durationMs };
-  } finally {
-    stream.free?.();
-  }
-}
-
-/**
- * 流式转写（Paraformer）— 适合实时字幕
+ * 完整音频段转写（Zipformer 在线识别器，模拟流式喂入）
  *
  * 将完整音频段一次性喂入流式识别器，逐帧解码后返回最终文本。
- * 真正的"边录边出"需要渲染进程持续推送音频块（后续版本支持）。
+ * 用于按段转写路径（课堂非真流式 / 课后分析）。
  *
  * @param pcmData - Float32 PCM 音频数据（16kHz 单声道）
+ * @param hotwords - 可选热词增强字符串（zipformer-transducer 支持）
  * @returns 转写结果
  */
 export async function transcribeStreaming(
   pcmData: Float32Array,
-): Promise<{ text: string; engine: 'streaming'; durationMs: number }> {
+  hotwords?: string,
+): Promise<{ text: string; engine: 'zipformer'; durationMs: number }> {
   const startTime = Date.now();
 
   const recognizer = getOnlineRecognizer();
   if (!recognizer) {
-    throw new Error('Paraformer 识别器不可用（模型未下载或 sherpa-onnx 未安装）');
+    throw new Error('Zipformer 识别器不可用（模型未下载或 sherpa-onnx 未安装）');
   }
 
-  const stream = recognizer.createStream();
+  const stream = recognizer.createStream(hotwords);
   try {
     // 分块喂入（模拟流式，每块 1600 样本 = 100ms）
     const chunkSize = 1600;
@@ -333,41 +235,39 @@ export async function transcribeStreaming(
     }
 
     const result = recognizer.getResult(stream);
-    // 输出后处理：相邻重复压缩 + 幻觉过滤（与流式路径一致，见 streamingAsr.ts）
+    // 输出后处理：相邻重复压缩 + 幻觉过滤
     const text = cleanAsrResult(result.text ?? '');
     const durationMs = Date.now() - startTime;
 
-    logger.debug(`[LocalASR] Streaming transcribe: ${text.length} chars, ${durationMs}ms`);
-    return { text, engine: 'streaming', durationMs };
+    logger.debug(`[LocalASR] Zipformer transcribe: ${text.length} chars, ${durationMs}ms`);
+    return { text, engine: 'zipformer', durationMs };
   } finally {
     stream.free?.();
   }
 }
 
 /**
- * 统一转写入口（根据配置选择引擎）
+ * 统一转写入口
  *
  * @param audioBase64 - base64 编码的 Float32 PCM 音频（16kHz 单声道）
  * @param options - 转写选项
  */
 export async function transcribeLocal(
   audioBase64: string,
-  options?: { language?: string; sampleRate?: number; channels?: number; engine?: AsrEngine },
+  options?: { language?: string; sampleRate?: number; channels?: number; hotwords?: string },
 ): Promise<{ text: string; language: string; durationMs: number }> {
   const config = getLocalAsrConfig();
-  const engine = options?.engine ?? config.engine;
   const language = options?.language ?? config.language;
 
+  // 防御性校验：非 16kHz 采样率会严重降低识别质量
+  if (options?.sampleRate && options.sampleRate !== 16000) {
+    logger.warn(`[LocalASR] 非预期采样率: ${options.sampleRate}Hz，本地 ASR 要求 16kHz 单声道 Float32 PCM`);
+  }
+
   // base64 → Float32Array
   const rawBytes = Buffer.from(audioBase64, 'base64');
   const pcmData = new Float32Array(rawBytes.buffer, rawBytes.byteOffset, rawBytes.byteLength / 4);
 
-  if (engine === 'streaming' && isModelReady('streaming')) {
-    const result = await transcribeStreaming(pcmData);
-    return { text: result.text, language, durationMs: result.durationMs };
-  }
-
-  // 默认走 offline（SenseVoice）
-  const result = await transcribeOffline(pcmData, { language });
+  const result = await transcribeStreaming(pcmData, options?.hotwords);
   return { text: result.text, language, durationMs: result.durationMs };
-}
+}