fix(client): 客户端中危修复——IPC批处理返回值/流式超时与连接释放/代理路径校验/MCP最小环境/采集源校验/备份保护/watchdog上限

- CL-M1: ai:stream:start 的 API 路径白名单校验（仅 /api/v1/(ai|multimodal)/ 前缀，拒绝 ?/# 注入），堵住代理访问任意网关端点
- CL-M2: postJsonStream 读取阶段 30s 无数据超时（原仅覆盖建连）+ 所有退出路径 reader.cancel() 释放连接 + 外部 abort 信号检测
- CL-M3: safeHandleBatched 返回真实结果（最后一次调用结算 Promise），microtask 异常 reject 给调用方而非 unhandledRejection
- CL-M4: 屏幕采集缩略图 1920×1080 → 1280×720（extractFrame 目标分辨率），多窗口每帧位图分配降 56%
- CL-M5: db:batch 批量操作条数上限 1000，防止单事务长期持有写锁阻塞全部 db IPC
- CL-M6: columnCache 失效策略——initialize/close/checkpointAndClose 时 clear，运行期 schema 变更不再过滤新列
- CL-M7: MCP Bridge 子进程最小环境白名单（14 个基础变量），不再透传宿主全部环境变量（供应链凭据泄露面）
- CL-M8: displayMedia handler 校验请求 frame 来源（file:// 或 localhost），非应用来源拒绝授权（防静默录屏+系统音频）
- CL-M9: dbFileMigrator 复制前检查目标目录已存在 keban.db 则拒绝（防覆盖旧库）；备份名加时间戳并保留最近 5 份
- CL-M10: 帧超时 watchdog 连续重启上限 3 次（收到有效帧清零），耗尽后停止并 toast 提示，消除幽灵采集循环
- CL-M11: callWithLocalFallback 本地探测缓存过期时先刷新再决策，不再静默跳过本地推理

验证: npm run lint (0 errors) + npm run test (875 passed) + npm run build 全部通过

Author: Aparencia

client/electron/ai/gatewayHttp.ts

@@ -13,7 +13,7 @@ import { randomUUID } from 'crypto';
 import { logger } from '../logger.js';
 import { gatewayUrl } from './gatewayConfig.js';
 import { isLocalInferenceEnabled } from './ollama/config.js';
-import { isOllamaAvailable } from './ollama/OllamaService.js';
+import { isOllamaAvailable, getOllamaStatus } from './ollama/OllamaService.js';
 
 /** 构建公共请求头（JSON 模式含 Content-Type，multipart 由 fetch 自动生成） */
 function buildHeaders(clientRequestId: string, json: boolean, authToken?: string): Record<string, string> {
@@ -156,8 +156,23 @@ export async function callWithLocalFallback<TReq, TRes>(
   authToken?: string,
   timeoutMs: number = 60000,
 ): Promise<{ data: TRes; source: 'local' | 'remote'; requestId?: string }> {
-  // 检查本地 Ollama 是否可用
-  if (isLocalInferenceEnabled() && isOllamaAvailable()) {
+  // CL-M11: 本地探测缓存过期时先刷新一次再决策——isOllamaAvailable 对过期
+  // 缓存直接返回 false，若仅因缓存过期而静默跳过本地推理，用户以为在用本地
+  // 模型实际全走云端（隐私与成本预期偏差，且不可观测）
+  let localAvailable = false;
+  if (isLocalInferenceEnabled()) {
+    localAvailable = isOllamaAvailable();
+    if (!localAvailable) {
+      try {
+        const fresh = await getOllamaStatus(true);
+        localAvailable = fresh.running;
+      } catch {
+        localAvailable = false; // 探测异常时安全降级远程
+      }
+    }
+  }
+
+  if (localAvailable) {
     try {
       const localResult = await localHandler();
       logger.info(`[AI] ← Local Ollama success for ${apiPath}`);

client/electron/ai/gatewayStream.ts

@@ -87,10 +87,18 @@ export async function* postJsonStream<TReq>(
   let buffer = '';
   /** SSE 缓冲最大字节数，防止恶意服务端无分隔符输出耗尽内存 */
   const MAX_BUFFER_SIZE = 1 * 1024 * 1024; // 1MB
+  /** CL-M2: 读取阶段无数据超时（ms）——原超时仅覆盖 fetch 建连阶段，
+   *  服务端建连后挂起不发数据会导致读取永久等待 */
+  const READ_TIMEOUT_MS = 30_000;
 
   try {
     while (true) {
-      const { done, value } = await reader.read();
+      // CL-M2: 外部取消信号检查——abort 后立即停止消费，避免继续拉取
+      if (externalSignal?.aborted) {
+        break;
+      }
+
+      let { done, value } = await readWithTimeout(reader, READ_TIMEOUT_MS);
       if (done) break;
 
       buffer += decoder.decode(value, { stream: true });
@@ -136,6 +144,37 @@ export async function* postJsonStream<TReq>(
       }
     }
   } finally {
+    // CL-M2: 所有退出路径（[DONE] 提前 return/异常/取消）必须 cancel 响应流，
+    // 否则底层 TCP 连接保持打开直到 GC（连接泄漏）；cancel 对已自然结束的流为 no-op
+    try {
+      await reader.cancel();
+    } catch {
+      // 流已关闭时 cancel 抛错可忽略
+    }
     reader.releaseLock();
   }
 }
+
+/**
+ * CL-M2: 带超时的流读取——读取阶段无数据超时（30s）时取消流并抛错，
+ * 防止服务端建连后挂起导致调用方永久等待；超时同时 cancel reader
+ * 释放底层 TCP 连接（否则挂起的 read() 永远不结束）。
+ */
+async function readWithTimeout(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  timeoutMs: number,
+): Promise<ReadableStreamReadResult<Uint8Array>> {
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutId = setTimeout(() => {
+      // 取消流：让挂起的 read() 立即结束，并释放底层连接
+      reader.cancel().catch(() => {});
+      reject(new Error(`Stream read timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([reader.read(), timeoutPromise]);
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+  }
+}

client/electron/ai/streamHandler.ts

@@ -56,6 +56,19 @@ export function registerStreamHandler(): void {
       const { requestId, method, payload, authToken } = args;
       const sender = event.sender;
 
+      // CL-M1: API 路径白名单校验——method 实为路径，直接拼入 URL 可访问
+      // 网关任意端点（含 ?/# 注入参数）；仅允许受信任的 AI 功能路径
+      const VALID_STREAM_PATH = /^\/api\/v1\/(ai|multimodal)\/[A-Za-z0-9_\/-]+$/;
+      if (
+        typeof method !== 'string' ||
+        method.includes('?') ||
+        method.includes('#') ||
+        !VALID_STREAM_PATH.test(method)
+      ) {
+        logger.warn(`[AI] [stream] 拒绝非法路径: ${method}`);
+        return { ok: false, error: 'Invalid stream path' };
+      }
+
       logger.info(`[AI] [stream] Start: requestId=${requestId}, method=${method}`);
 
       // 为该流式请求创建 AbortController

client/electron/db/dbFileMigrator.ts

@@ -131,6 +131,19 @@ export async function migrateDatabaseFiles(
     const sourceStats = await stat(sourceDb);
     let totalSize = sourceStats.size;
 
+    // CL-M9: 复制前检查目标目录是否已有数据库——copyFile 默认直接覆盖，
+    // 若用户选择已存在 keban.db 的目录（历史存储路径/手动复制残留），
+    // 旧库会被静默替换且无备份，造成不可逆数据丢失
+    const targetDb = path.join(targetDir, 'keban.db');
+    if (await fileExists(targetDb)) {
+      return {
+        success: false,
+        sourcePath: sourceDir,
+        targetPath: targetDir,
+        error: '目标目录已存在数据库文件（keban.db），为防止覆盖旧数据，请选择空目录或将旧库改名后重试',
+      };
+    }
+
     // 计算所有存在的文件大小
     for (const fileName of DB_FILES) {
       const filePath = path.join(sourceDir, fileName);
@@ -227,15 +240,38 @@ export function verifyDatabaseIntegrity(dbPath: string): boolean {
 
 /**
  * 为旧路径数据库创建备份
- * 将 keban.db / keban.db-wal / keban.db-shm 各复制为 .bak（同目录）
+ * 将 keban.db / keban.db-wal / keban.db-shm 各复制为带时间戳的 .bak（同目录）
+ * CL-M9: 备份名固定为 keban.db.bak 会被多次切换路径时互相覆盖，回滚点丢失；
+ * 改为时间戳后缀并仅保留最近 5 份。
  */
 export async function createBackup(dbDir: string): Promise<void> {
+  const timestamp = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14);
   for (const fileName of DB_FILES) {
     const sourcePath = path.join(dbDir, fileName);
-    const backupPath = path.join(dbDir, fileName + '.bak');
+    const backupPath = path.join(dbDir, `${fileName}.${timestamp}.bak`);
     if (await fileExists(sourcePath)) {
       await copyFile(sourcePath, backupPath);
-      logger.info(`[DBMigrator] Backup created: ${fileName}.bak`);
+      logger.info(`[DBMigrator] Backup created: ${path.basename(backupPath)}`);
     }
   }
+  // 清理超出保留份数的旧备份（按文件名时间戳排序，保留最近 5 份）
+  await pruneOldBackups(dbDir);
+}
+
+/** 仅保留最近 5 份 .bak 备份（按时间戳后缀排序） */
+async function pruneOldBackups(dbDir: string): Promise<void> {
+  try {
+    const { readdir } = await import('fs/promises');
+    const entries = await readdir(dbDir);
+    const backupFiles = entries
+      .filter((name) => name.endsWith('.bak'))
+      .sort()
+      .reverse();
+    for (const name of backupFiles.slice(5)) {
+      await rm(path.join(dbDir, name));
+      logger.info(`[DBMigrator] Pruned old backup: ${name}`);
+    }
+  } catch (err) {
+    logger.warn(`[DBMigrator] Failed to prune old backups: ${err instanceof Error ? err.message : String(err)}`);
+  }
 }

client/electron/db/dbIpcHandlers.ts

@@ -260,6 +260,16 @@ export function registerDbIpcHandlers(): void {
   safeHandle('db:batch', async (_event, params: { operations: Array<{ type: string; table: string; [key: string]: unknown }> }) => {
     const dbConn = getConnection();
 
+    // CL-M5: 批量操作条数上限——超大数组单事务同步执行会长期持有写锁
+    // （所有其他 db:* IPC 排队）并阻塞主进程事件循环
+    const MAX_BATCH_OPS = 1000;
+    if (!Array.isArray(params.operations) || params.operations.length === 0) {
+      throw new Error('[DB] Batch operations must be a non-empty array');
+    }
+    if (params.operations.length > MAX_BATCH_OPS) {
+      throw new Error(`[DB] Batch operations exceed limit (max ${MAX_BATCH_OPS}, got ${params.operations.length})`);
+    }
+
     const txn = dbConn.transaction(() => {
       for (const op of params.operations) {
         const tableName = resolveTable(op.table as string);

client/electron/db/sqliteRepository.ts

@@ -110,6 +110,15 @@ function q(col: string): string {
 /** 缓存每张表的列名白名单 */
 const columnCache = new Map<string, Set<string>>();
 
+/**
+ * CL-M6: 使列名白名单缓存失效——schema 变更（ALTER TABLE）或数据库
+ * 连接重开（reinitialize 到新路径）后必须调用，否则 filterAllowedColumns
+ * 会用旧列集合过滤掉新列，导致新列数据静默丢弃。
+ */
+export function clearColumnCache(): void {
+  columnCache.clear();
+}
+
 /**
  * 获取表的合法列名集合（从 PRAGMA table_info 查询并缓存）
  */

client/electron/db/sqliteService.ts

@@ -10,6 +10,7 @@
 
 import Database from 'better-sqlite3';
 import { logger } from '../logger.js';
+import { clearColumnCache } from './sqliteRepository.js';
 
 // ================================================================
 // 模块级状态
@@ -48,6 +49,10 @@ export function initialize(dbPath?: string): Database.Database {
   try {
     db = new Database(resolvedPath);
 
+    // CL-M6: 新连接建立时使列名白名单缓存失效——重新初始化到新库/新路径
+    // 后 schema 可能不同，旧缓存会把新列过滤掉导致数据静默丢弃
+    clearColumnCache();
+
     // 开启 WAL 模式：提升并发读写性能，减少锁竞争
     db.pragma('journal_mode = WAL');
     logger.info('[SQLite] WAL mode enabled');
@@ -102,6 +107,8 @@ export function close(): void {
   } finally {
     db = null;
     currentDbPath = null;
+    // CL-M6: 连接关闭后缓存同步失效（下次 initialize 会重建）
+    clearColumnCache();
   }
 }
 
@@ -138,6 +145,8 @@ export function checkpointAndClose(): void {
     } finally {
       db = null;
       currentDbPath = null;
+      // CL-M6: 连接关闭后缓存同步失效（下次 initialize 会重建）
+      clearColumnCache();
     }
   }
 }

client/electron/displayMediaHandler.ts

@@ -15,7 +15,7 @@
  * useClassroomAudio 的 openMicrophoneStream 实现，无需本模块参与。
  */
 
-import { session, desktopCapturer } from 'electron';
+import { session, desktopCapturer, type WebFrameMain } from 'electron';
 import { logger } from './logger';
 
 /**
@@ -29,6 +29,18 @@ export function setPreferredDisplaySource(sourceId: string | null): void {
   preferredSourceId = sourceId;
 }
 
+/**
+ * CL-M8: 校验 displayMedia 请求来源是否为应用自身 frame。
+ * 生产打包为 file:// 路径，开发为 http://localhost:端口。
+ * 未通过校验一律拒绝——防止渲染层注入代码静默获取整屏 + 系统音频混音。
+ */
+function isTrustedFrame(frame: WebFrameMain | null): boolean {
+  if (!frame) return false;
+  const url = frame.url || '';
+  if (url.startsWith('file://')) return true;
+  return /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?\//.test(url);
+}
+
 /**
  * 注册 displayMedia 请求处理器（须在 app.whenReady 后调用一次）
  *
@@ -37,7 +49,15 @@ export function setPreferredDisplaySource(sourceId: string | null): void {
  */
 export function registerDisplayMediaHandler(): void {
   session.defaultSession.setDisplayMediaRequestHandler(
-    (_request, callback) => {
+    (request, callback) => {
+      // CL-M8: 仅响应应用自身 frame 的请求——忽略 request 参数时
+      // 任何来源（含注入 iframe/脚本）都能无感获取整屏画面 + 系统音频混音
+      if (!isTrustedFrame(request.frame)) {
+        const url = request.frame?.url ?? 'unknown';
+        logger.warn(`[DisplayMedia] 拒绝非应用来源的捕获请求: ${url}`);
+        callback({});
+        return;
+      }
       void (async () => {
         try {
           const sources = await desktopCapturer.getSources({

client/electron/ipcUtils.ts

@@ -151,26 +151,39 @@ export function safeHandleBatched<T extends any[]>(
   channel: string,
   handler: TypedHandler<T>,
 ): void {
-  let pendingArgs: { event: Electron.IpcMainInvokeEvent; args: T } | null = null;
+  let pending: {
+    event: Electron.IpcMainInvokeEvent;
+    args: T;
+    resolve: (value: unknown) => void;
+    reject: (reason: unknown) => void;
+  } | null = null;
   let scheduled = false;
 
   const batchedHandler: TypedHandler<T> = (event, ...args) => {
-    pendingArgs = { event, args };
-
-    if (!scheduled) {
-      scheduled = true;
-      queueMicrotask(async () => {
-        scheduled = false;
-        if (pendingArgs) {
-          const { event: ev, args: a } = pendingArgs;
-          pendingArgs = null;
-          return handler(ev, ...a);
-        }
-      });
+    // 新调用覆盖旧 pending：旧调用立即结算（合并语义——只有最后一次返回真实结果）
+    if (pending) {
+      pending.resolve(undefined);
     }
 
-    // 返回一个 resolved promise（批量化场景调用方不依赖即时返回值）
-    return Promise.resolve(undefined);
+    return new Promise((resolve, reject) => {
+      pending = { event, args, resolve, reject };
+
+      if (!scheduled) {
+        scheduled = true;
+        queueMicrotask(() => {
+          scheduled = false;
+          const current = pending;
+          pending = null;
+          if (!current) return;
+          // CL-M3: microtask 中 try/catch 包裹——handler 抛错时 reject 给调用方
+          // （invoke 收到 rejection 而非 unhandledRejection 状态漂移）；
+          // 最后一次调用可拿到 handler 的真实返回值
+          Promise.resolve(handler(current.event, ...current.args))
+            .then(current.resolve)
+            .catch(current.reject);
+        });
+      }
+    });
   };
 
   safeHandle(channel, batchedHandler);

client/electron/mcpBridge.ts

@@ -126,6 +126,24 @@ async function handleInit(params: Record<string, unknown>): Promise<Record<strin
   return status;
 }
 
+// CL-M7: MCP server 子进程最小环境白名单（仅传运行必需的基础变量）
+const MINIMAL_ENV_KEYS = [
+  'PATH', 'SystemRoot', 'WINDIR', 'TEMP', 'TMP', 'HOME', 'USERPROFILE',
+  'APPDATA', 'LOCALAPPDATA', 'COMSPEC', 'PATHEXT', 'NODE_PATH', 'LANG', 'LC_ALL',
+];
+
+/** 构建传给 MCP server 子进程的最小环境（显式白名单，绝不透传宿主全部环境变量） */
+function buildMinimalEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const key of MINIMAL_ENV_KEYS) {
+    const val = process.env[key];
+    if (typeof val === 'string' && val) {
+      env[key] = val;
+    }
+  }
+  return env;
+}
+
 async function startServer(config: { name: string; command: string; args: string[] }): Promise<void> {
   if (!ClientCtor || !StdioTransportCtor) return;
 
@@ -143,7 +161,9 @@ async function startServer(config: { name: string; command: string; args: string
     const transport = new StdioTransportCtor({
       command: config.command,
       args: config.args,
-      env: process.env as Record<string, string>,
+      // CL-M7: 最小环境白名单——绝不把主进程全部环境变量传给第三方 MCP
+      // server 子进程（供应链污染可读取宿主凭据）；仅传运行必需的基础变量
+      env: buildMinimalEnv(),
       stderr: 'pipe',
     });