fix(client): 内测反馈五连修——导航竞态/剪贴板IPC/音频资源路径/番茄钟预设/ASR兼容

- 3D导航：OrbitalStore.syncWithRoute 飞行中不再丢弃路由同步，SceneProvider 增加 2.5s 强制停靠兜底，修复快速切换页面不渲染

- 剪贴板：新增 clipboard:write-text IPC（sender 校验 + 白名单）与 lib/utils/clipboard.ts 三级降级链，修复 Electron 失焦复制失败

- 音频资源：新增 publicAssetUrl（BASE_URL 拼接），修复 file:// 生产构建下音效/白噪音/BGM 绝对路径 404

- 番茄钟预设：标题去重清洗、删除与排序能力补全，设置页一屏适配

- 本地ASR：sherpa-onnx 新旧版 acceptWaveform/free 签名适配层，设置页新增流式识别启用开关

- 同步：SyncEngine/NetworkManager 幂等写入与退避加固（含测试）

- 沉淀 3 张知识卡片并更新知识索引

Author: Aparencia

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

@@ -10,6 +10,11 @@
  * 符合项目"可选增强"设计原则。
  * @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 真流式启动失败根因，离线路径同样受影响）。
  */
 
 import * as path from 'path';
@@ -26,9 +31,16 @@ import {
 // sherpa-onnx 动态加载（可选依赖，加载失败不崩溃）
 // ================================================================
 
+/** 识别器构造器签名（新版 API：类导出） */
+type RecognizerCtor<T> = new (config: Record<string, unknown>) => T;
+
 interface SherpaOnnx {
-  createOfflineRecognizer(config: Record<string, unknown>): OfflineRecognizer;
-  createOnlineRecognizer(config: Record<string, unknown>): OnlineRecognizer;
+  /** 旧版 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 {
@@ -38,9 +50,12 @@ interface OfflineRecognizer {
 }
 
 interface OfflineStream {
+  /** 旧版：(sampleRate, samples)；新版 1.13+：({ samples, sampleRate })，统一走 feedWaveform */
   acceptWaveform(sampleRate: number, samples: Float32Array): void;
+  acceptWaveform(waveform: { samples: Float32Array; sampleRate: number }): void;
   inputFinished(): void;
-  free(): void;
+  /** 新版 OnlineStream/OfflineStream 未提供 free（句柄由 GC 回收），故为可选 */
+  free?(): void;
 }
 
 export interface OnlineRecognizer {
@@ -53,14 +68,56 @@ export interface OnlineRecognizer {
 }
 
 export interface OnlineStream {
+  /** 旧版：(sampleRate, samples)；新版 1.13+：({ samples, sampleRate })，统一走 feedWaveform */
   acceptWaveform(sampleRate: number, samples: Float32Array): void;
+  acceptWaveform(waveform: { samples: Float32Array; sampleRate: number }): void;
   inputFinished(): void;
-  free(): void;
+  free?(): void;
+}
+
+/**
+ * 向流喂入音频：自动适配新旧 API 签名差异。
+ * 旧版（<=1.12）acceptWaveform(sampleRate, samples) 双参；
+ * 新版（1.13+）acceptWaveform({ samples, sampleRate }) 单对象。
+ * 按函数形参数（length）判别，调用方无需感知版本。
+ */
+export function feedWaveform(
+  stream: OnlineStream | OfflineStream,
+  sampleRate: number,
+  samples: Float32Array,
+): void {
+  if (stream.acceptWaveform.length <= 1) {
+    stream.acceptWaveform({ samples, sampleRate });
+  } else {
+    stream.acceptWaveform(sampleRate, samples);
+  }
 }
 
 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') {
+    return sherpa.createOnlineRecognizer(config);
+  }
+  if (typeof sherpa.OnlineRecognizer === 'function') {
+    return new sherpa.OnlineRecognizer(config);
+  }
+  throw new Error('sherpa-onnx-node 既无 createOnlineRecognizer 工厂也无 OnlineRecognizer 类，请核对依赖版本');
+}
+
 /** 尝试加载 sherpa-onnx-node（仅尝试一次） */
 function loadSherpa(): SherpaOnnx | null {
   if (_loadAttempted) return _sherpa;
@@ -97,7 +154,7 @@ function getOfflineRecognizer(): OfflineRecognizer | null {
   const threads = config.threads > 0 ? config.threads : Math.max(1, os.cpus().length - 1);
 
   try {
-    _offlineRecognizer = sherpa.createOfflineRecognizer({
+    _offlineRecognizer = instantiateOffline(sherpa, {
       featConfig: { sampleRate: 16000, featureDim: 80 },
       modelConfig: {
         senseVoice: {
@@ -131,7 +188,7 @@ export function getOnlineRecognizer(): OnlineRecognizer | null {
   const threads = config.threads > 0 ? config.threads : Math.max(1, os.cpus().length - 1);
 
   try {
-    _onlineRecognizer = sherpa.createOnlineRecognizer({
+    _onlineRecognizer = instantiateOnline(sherpa, {
       featConfig: { sampleRate: 16000, featureDim: 80 },
       modelConfig: {
         paraformer: {
@@ -219,7 +276,7 @@ export async function transcribeOffline(
 
   const stream = recognizer.createStream();
   try {
-    stream.acceptWaveform(16000, pcmData);
+    feedWaveform(stream, 16000, pcmData);
     stream.inputFinished();
     recognizer.decode(stream);
     const result = recognizer.getResult(stream);
@@ -229,7 +286,7 @@ export async function transcribeOffline(
     logger.debug(`[LocalASR] Offline transcribe: ${text.length} chars, ${durationMs}ms`);
     return { text, engine: 'offline', durationMs };
   } finally {
-    stream.free();
+    stream.free?.();
   }
 }
 
@@ -258,7 +315,7 @@ export async function transcribeStreaming(
     const chunkSize = 1600;
     for (let offset = 0; offset < pcmData.length; offset += chunkSize) {
       const chunk = pcmData.subarray(offset, Math.min(offset + chunkSize, pcmData.length));
-      stream.acceptWaveform(16000, chunk);
+      feedWaveform(stream, 16000, chunk);
       while (recognizer.isReady(stream)) {
         recognizer.decode(stream);
       }
@@ -277,7 +334,7 @@ export async function transcribeStreaming(
     logger.debug(`[LocalASR] Streaming transcribe: ${text.length} chars, ${durationMs}ms`);
     return { text, engine: 'streaming', durationMs };
   } finally {
-    stream.free();
+    stream.free?.();
   }
 }
 

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

@@ -12,7 +12,7 @@
 
 import type { BrowserWindow } from 'electron';
 import { logger } from '../../logger.js';
-import { getOnlineRecognizer, type OnlineStream } from './SherpaAsrService.js';
+import { getOnlineRecognizer, feedWaveform, type OnlineStream } from './SherpaAsrService.js';
 
 /** partial 推送节流：两次 partial 推送的最小间隔（ms） */
 const PARTIAL_EMIT_INTERVAL_MS = 150;
@@ -91,7 +91,8 @@ export function feedStreamingAsr(audioBuffer: ArrayBuffer, sampleRate?: number):
   const rate = sampleRate ?? _sampleRate;
 
   try {
-    _stream.acceptWaveform(rate, samples);
+    // 统一适配层：新旧版 sherpa-onnx-node 的 acceptWaveform 签名不同
+    feedWaveform(_stream, rate, samples);
     while (recognizer.isReady(_stream)) {
       recognizer.decode(_stream);
     }
@@ -129,7 +130,8 @@ export function feedStreamingAsr(audioBuffer: ArrayBuffer, sampleRate?: number):
 export function stopStreamingAsr(): void {
   if (_stream) {
     try {
-      _stream.free();
+      // 新版（1.13+）流对象无 free 方法（句柄由 GC 回收），可选调用
+      _stream.free?.();
     } catch (err) {
       logger.warn(`[StreamingASR] 释放流失败: ${err}`);
     }

client/electron/ipc/channels.ts

@@ -108,6 +108,7 @@ export const IPC_CHANNELS = {
 
   // 系统
   APP_GET_VERSION: 'get-app-version',
+  CLIPBOARD_WRITE_TEXT: 'clipboard:write-text',
   GET_DEFAULT_STORAGE_PATH: 'get-default-storage-path',
   DIALOG_SELECT_DIRECTORY: 'dialog:selectDirectory',
 

client/electron/main.ts

@@ -17,8 +17,8 @@
  * 应用无法启动，任何修改需完整回归启动/退出/托盘/更新流程。
  */
 
-import { app, BrowserWindow, Menu, session } from 'electron';
-import { safeHandle, setMainWindowId } from './ipcUtils.js';
+import { app, BrowserWindow, Menu, session, clipboard } from 'electron';
+import { safeHandle, setMainWindowId, requireText } from './ipcUtils.js';
 import { logger } from './logger.js';
 import { registerAIHandlers, initAIModule } from './ai/index.js';
 import { loadPersistedGatewayUrl, setRuntimeGatewayUrl, gatewayUrl, isDevMode } from './ai/utils.js';
@@ -231,6 +231,14 @@ if (!gotTheLock) {
       return app.getVersion();
     });
 
+    // 剪贴板写入：渲染进程 navigator.clipboard 在 Electron 非聚焦/受限上下文下
+    // 会抛 "Document is not focused" 而失败，改由主进程 clipboard 模块写入更可靠。
+    safeHandle('clipboard:write-text', async (_event, text: unknown) => {
+      const value = requireText(text, 'text');
+      clipboard.writeText(value);
+      return { success: true };
+    });
+
     // 创建主窗口（内部会创建托盘）
     mainWindow = createMainWindow(isQuittingRef, performQuit);
 

client/electron/mcpMemoryServer.ts

@@ -26,19 +26,32 @@ import * as fs from 'fs';
 // 路径解析（无 electron 依赖：独立进程内手动推导 userData）
 // ================================================================
 
-const APP_DIR_NAME = 'entropy-decrease';
+/**
+ * 应用实际 userData 目录名取自 Electron app.name：默认 productName
+ * （"Entropy decrease"），无 productName 时才回退 name（"entropy-decrease"）。
+ * 独立进程无法调用 app.getPath('userData')，只能按此顺序推导候选目录，
+ * 取第一个真实存在的目录——否则授权标记、keban.db、访问日志会全部错位。
+ */
+const APP_DIR_NAMES = ['Entropy decrease', 'entropy-decrease'];
 const CONSENT_MARKER = 'memory-server-consent';
 const ACCESS_LOG = 'memory-server-access.log';
 
 function resolveUserDataDir(): string {
+  let base: string;
   switch (process.platform) {
     case 'win32':
-      return path.join(process.env.APPDATA ?? path.join(os.homedir(), 'AppData', 'Roaming'), APP_DIR_NAME);
+      base = process.env.APPDATA ?? path.join(os.homedir(), 'AppData', 'Roaming');
+      break;
     case 'darwin':
-      return path.join(os.homedir(), 'Library', 'Application Support', APP_DIR_NAME);
+      base = path.join(os.homedir(), 'Library', 'Application Support');
+      break;
     default:
-      return path.join(process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), '.config'), APP_DIR_NAME);
+      base = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), '.config');
   }
+  return (
+    APP_DIR_NAMES.map((name) => path.join(base, name)).find((dir) => fs.existsSync(dir)) ??
+    path.join(base, APP_DIR_NAMES[0])
+  );
 }
 
 /** 与 storageConfig.resolveDbPath 同口径：优先自定义路径，回退 userData/keban.db */

client/electron/preload.ts

@@ -57,6 +57,8 @@ const ALLOWED_CHANNELS = [
   // A2 语音对话：启动前查询是否已有活跃采集（互斥保护，避免误伤课堂采集）
   'audio_capture_status',
   'get-app-version',
+  // 剪贴板写入（渲染进程 navigator.clipboard 在 Electron 受限上下文下不可靠）
+  'clipboard:write-text',
   'dialog:selectDirectory',
   'get-default-storage-path',
   'update:check',

client/src/components/layout/AppLayout.tsx

@@ -154,19 +154,26 @@ export default function AppLayout() {
             : undefined}
           maskClassName={currentModule === 'inspiration' ? '!bg-[var(--kb-bg-primary)] !backdrop-blur-none' : undefined}
         >
-          {/* 路由级 AnimatePresence：mode="wait" 确保旧页面完成退出动画后再挂载新页面，避免残帧 */}
-          <AnimatePresence mode="wait">
-            <motion.div
-              key={pathname}
-              /* 简单的 opacity 淡入淡出，不影响 3D 场景的相机飞行和停靠时序 */
-              initial={{ opacity: 0 }}
-              animate={{ opacity: 1 }}
-              exit={{ opacity: 0 }}
-              transition={{ duration: 0.2 }}
-            >
-              <Outlet />
-            </motion.div>
-          </AnimatePresence>
+          {/* 路由级过渡：grid 叠放 + 同期交叉淡入淡出。
+              历史方案 mode="wait" 要求旧页退出回调交接后才挂载新页；在
+              reduced-motion / StrictMode(dev) / HMR 等条件下交接会偶发丢失，
+              新页永不挂载——即内测反馈"回到主页时主页不显示"的根因。
+              交叉淡入淡出下新页立即挂载、旧页淡出后卸载，退出即使延迟也不阻塞内容展示 */}
+          <div className="grid">
+            <AnimatePresence>
+              <motion.div
+                key={pathname}
+                style={{ gridArea: '1 / 1' }}
+                /* 简单的 opacity 淡入淡出，不影响 3D 场景的相机飞行和停靠时序 */
+                initial={{ opacity: 0 }}
+                animate={{ opacity: 1 }}
+                exit={{ opacity: 0 }}
+                transition={{ duration: 0.2 }}
+              >
+                <Outlet />
+              </motion.div>
+            </AnimatePresence>
+          </div>
         </FunctionalOverlay>
       )}
 

client/src/features/assistant/hooks/useAssistantAudio.ts

@@ -8,11 +8,13 @@
 import { useEffect, useCallback } from 'react';
 import { useAssistantStore } from '../store/useAssistantStore';
 import { ttsController } from '../lib/ttsController';
+import { publicAssetUrl } from '@/lib/assets/publicAssetUrl';
 
+// publicAssetUrl 适配 Electron file:// 相对解析（绝对路径会 404）
 const SOUND_PATHS = {
-  bubble: '/sounds/assistant-bubble.mp3',
-  speakStart: '/sounds/assistant-speak-start.mp3',
-  ack: '/sounds/assistant-ack.mp3',
+  bubble: publicAssetUrl('/sounds/assistant-bubble.mp3'),
+  speakStart: publicAssetUrl('/sounds/assistant-speak-start.mp3'),
+  ack: publicAssetUrl('/sounds/assistant-ack.mp3'),
 } as const;
 
 export type SoundName = keyof typeof SOUND_PATHS;

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

@@ -24,11 +24,7 @@
  */
 import { useState, useEffect, useRef } from 'react';
 import type { AudioChunkData, CaptureMode, SessionStatus, CaptureManager } from '@/lib/capture';
-import {
-  isAudioWorkletSupported,
-  startAudioWorkletPipeline,
-  startScriptProcessorPipeline,
-} from '@/lib/audioPipeline';
+import { startAudioPipeline } from '@/lib/audioPipeline';
 
 /** 开始采集后多久仍无音频块则判定管道未启动 */
 const NEVER_RECEIVED_TIMEOUT_MS = 15000;
@@ -245,18 +241,11 @@ export function useClassroomAudio({ captureManager, status, mode, onNotify }: Us
             });
           };
 
-          // 优先使用 AudioWorklet，不可用时降级到 ScriptProcessor
-          if (isAudioWorkletSupported()) {
-            console.info('[useClassroomCapture] 使用 AudioWorklet 音频管道（推荐）');
-            audioCleanupRef.current = await startAudioWorkletPipeline(
-              audioCtx, stream, payload.options, onChunk,
-            );
-          } else {
-            console.warn('[useClassroomCapture] AudioWorklet 不可用，降级到 ScriptProcessor');
-            audioCleanupRef.current = startScriptProcessorPipeline(
-              audioCtx, stream, payload.options, onChunk,
-            );
-          }
+          // 统一入口：优先 AudioWorklet，模块加载失败自动降级 ScriptProcessor
+          // （生产 file:// 下 addModule 会因 opaque origin 失败，降级保底）
+          audioCleanupRef.current = await startAudioPipeline(
+            audioCtx, stream, payload.options, onChunk,
+          );
         } catch (err) {
           console.error('[useClassroomCapture] Audio pipeline start failed:', err);
           // 根据采集源类型给出不同的诊断提示

client/src/features/notes/components/ContentTierModal.tsx

@@ -11,6 +11,7 @@ import { useToast } from '@/components/ui';
 import { AIThinkingIndicator } from '@/components/ui/AIThinkingIndicator';
 import { Layers, ChevronDown, ChevronRight, Copy } from 'lucide-react';
 import { cn } from '@/lib/utils';
+import { copyText } from '@/lib/utils/clipboard';
 import { useAIContentTier } from '@/lib/ai/hooks/useAIContentTier';
 import type { ContentTierItem } from '@/lib/ai/types';
 
@@ -47,10 +48,11 @@ export function ContentTierModal({ open, onClose, noteText }: ContentTierModalPr
   const copyCore = async () => {
     if (!tier) return;
     const text = tier.core.map((item, i) => `${i + 1}. ${item.text}`).join('\n');
-    try {
-      await navigator.clipboard.writeText(text);
+    // copyText 三级降级（Electron 下 navigator.clipboard 非聚焦态会失败）
+    const ok = await copyText(text);
+    if (ok) {
       toast({ type: 'success', message: '核心概念已复制到剪贴板' });
-    } catch {
+    } else {
       toast({ type: 'error', message: '复制失败，请手动选择复制' });
     }
   };