feat(electron): G7 全局快捷键框架 + E2 录音持久化 IPC 白名单

Author: Aparencia

client/electron/main.ts

@@ -44,6 +44,7 @@ import { registerStorageIpcHandlers } from './storageIpcHandlers.js';
 import { registerKeyframeScheme, registerKeyframeIpcHandlers } from './ipc/keyframeStorage.js';
 import { loadPerformanceMode, registerPerformanceHandlers } from './performanceMode.js';
 import { registerShortcuts, unregisterShortcuts } from './shortcutManager.js';
+import { registerRecordingIpcHandlers } from './recordingStorage.js';
 
 // ================================================================
 // 性能优化：启用 GPU 光栅化与零拷贝
@@ -295,6 +296,9 @@ if (!gotTheLock) {
     // （capture-clipboard 等），触发事件经 shortcut:triggered 推送给渲染层
     registerShortcuts(() => mainWindow);
 
+    // E2 费曼录音持久化 IPC（{userData}/recordings 读写）
+    registerRecordingIpcHandlers();
+
     initAutoUpdater(mainWindow);
 
     // ---- 窗口控制 IPC handlers ----

client/electron/preload.ts

@@ -140,6 +140,10 @@ const ALLOWED_CHANNELS = [
   'sovereignty:import-world',
   // 知识星座 IPC channel（阶段 B：只读图谱聚合）
   'knowledge:get-graph',
+  // E2 费曼录音持久化 IPC channel（{userData}/recordings 读写）
+  'recording:save',
+  'recording:load',
+  'recording:delete',
 ] as const;
 
 /** 允许渲染进程监听的事件 channel 白名单（主进程 → 渲染进程推送） */
@@ -315,6 +319,15 @@ contextBridge.exposeInMainWorld('electronAPI', {
     getActivePath: () =>
       ipcRenderer.invoke('storage:get-active-path'),
   },
+  // ---- E2: 费曼录音持久化 API ----
+  recording: {
+    save: (stem: string, base64: string) =>
+      ipcRenderer.invoke('recording:save', { stem, base64 }),
+    load: (stem: string) =>
+      ipcRenderer.invoke('recording:load', { stem }),
+    delete: (stem: string) =>
+      ipcRenderer.invoke('recording:delete', { stem }),
+  },
   // ---- Ollama 本地推理 API ----
   ollama: {
     getStatus: (forceRefresh?: boolean) =>

client/electron/recordingStorage.ts

@@ -0,0 +1,83 @@
+/**
+ * 费曼录音持久化 IPC — {userData}/recordings 目录读写
+ * Feynman recording persistence — IPC bridge for {userData}/recordings
+ *
+ * @ai-context: E2 跨会话回放——录音 WAV 本地落盘（本地优先，不上传）。
+ * fileName 强制安全字符 + .wav 后缀（防路径穿越）；保存前确保目录存在；
+ * 读取不存在时返回 not_found 供调用方静默回退（可选增强原则）。
+ * @ai-context: Local-first WAV persistence for cross-session playback.
+ * File names are strictly validated to prevent path traversal; missing
+ * files surface as not_found so the renderer can degrade silently.
+ */
+import { app } from 'electron';
+import * as path from 'path';
+import { mkdir, writeFile, readFile, rm } from 'fs/promises';
+import { safeHandle } from '../ipcUtils.js';
+import { logger } from '../logger.js';
+
+/** 安全文件名：字母数字/下划线/连字符，1-80 字符（防路径穿越） */
+const SAFE_NAME_RE = /^[A-Za-z0-9_-]{1,80}$/;
+
+/** 录音根目录：{userData}/recordings */
+function recordingsRoot(): string {
+  return path.join(app.getPath('userData'), 'recordings');
+}
+
+/** 校验 fileName（不含扩展名，主进程统一追加 .wav） */
+function isSafeStem(stem: unknown): stem is string {
+  return typeof stem === 'string' && SAFE_NAME_RE.test(stem);
+}
+
+/**
+ * 注册 recording:* IPC handlers（app ready 后调用一次）。
+ * - recording:save   { stem, base64 } → 写 {userData}/recordings/{stem}.wav
+ * - recording:load   { stem } → 读文件返回 base64（不存在 → not_found）
+ * - recording:delete { stem } → 删除文件（失败静默）
+ */
+export function registerRecordingIpcHandlers(): void {
+  // ---- 保存录音 WAV（base64 → 文件）----
+  safeHandle('recording:save', async (_event, args: { stem: string; base64: string }) => {
+    const stem = args?.stem;
+    if (!isSafeStem(stem)) {
+      throw new Error('非法的录音文件名（仅允许字母数字/下划线/连字符）');
+    }
+    if (typeof args?.base64 !== 'string' || args.base64.length === 0) {
+      throw new Error('录音数据不能为空');
+    }
+    const dir = recordingsRoot();
+    await mkdir(dir, { recursive: true });
+    await writeFile(path.join(dir, `${stem}.wav`), Buffer.from(args.base64, 'base64'));
+    return { success: true, fileName: `${stem}.wav` };
+  });
+
+  // ---- 读取录音 WAV（跨会话回放）----
+  safeHandle('recording:load', async (_event, args: { stem: string }) => {
+    const stem = args?.stem;
+    if (!isSafeStem(stem)) {
+      throw new Error('非法的录音文件名');
+    }
+    try {
+      const data = await readFile(path.join(recordingsRoot(), `${stem}.wav`));
+      return { success: true, base64: data.toString('base64') };
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException)?.code;
+      if (code === 'ENOENT') return { success: false, notFound: true };
+      logger.warn(`[Recording] load failed: ${String(err)}`);
+      return { success: false, error: 'read_failed' };
+    }
+  });
+
+  // ---- 删除录音（本地缓存清理，失败静默）----
+  safeHandle('recording:delete', async (_event, args: { stem: string }) => {
+    const stem = args?.stem;
+    if (!isSafeStem(stem)) {
+      throw new Error('非法的录音文件名');
+    }
+    try {
+      await rm(path.join(recordingsRoot(), `${stem}.wav`), { force: true });
+    } catch {
+      /* 删除失败静默——不阻塞 UI */
+    }
+    return { success: true };
+  });
+}

client/electron/shortcutDefs.ts

@@ -0,0 +1,43 @@
+/**
+ * 全局快捷键静态定义表
+ *
+ * 所有系统级快捷键的唯一登记处：未来新增全局快捷键只需在
+ * SHORTCUT_DEFS 中追加一行，注册/触发/释放逻辑由 shortcutManager.ts
+ * 统一驱动，无需再触碰 main.ts / preload.ts。
+ *
+ * @ai-context: 全局快捷键声明表（id / accelerator / description），
+ * shortcutManager 遍历本表执行 globalShortcut.register；id 同时作为
+ * 'shortcut:triggered' 事件 payload 的分发键，渲染侧
+ * shortcutDispatcher.ts 按 id 路由处理。
+ * @ai-context: Single source of truth for system-level shortcut
+ * declarations. Adding a new global shortcut = append one entry here;
+ * registration, dispatch and disposal are fully driven by
+ * shortcutManager.ts, so main.ts/preload.ts stay untouched.
+ */
+
+/** 单条全局快捷键定义 */
+export interface ShortcutDef {
+  /** 唯一标识，作为 'shortcut:triggered' payload.id 的分发键 */
+  id: string;
+  /** Electron Accelerator 字符串（如 'CommandOrControl+Shift+B'） */
+  accelerator: string;
+  /** 人类可读描述（供设置页/命令面板展示） */
+  description: string;
+  /** 触发时由主进程附带剪贴板文本（capture-clipboard 等收集类快捷键） */
+  withClipboardText?: boolean;
+}
+
+/**
+ * 首批快捷键清单
+ *
+ * capture-clipboard：收藏剪贴板文本到统一收件箱（inbox_items 表）。
+ * 主进程 clipboard.readText() 在窗口失焦时同样可用，故注册在系统级。
+ */
+export const SHORTCUT_DEFS: ShortcutDef[] = [
+  {
+    id: 'capture-clipboard',
+    accelerator: 'CommandOrControl+Shift+B',
+    description: '收藏剪贴板内容到收件箱',
+    withClipboardText: true,
+  },
+];

client/electron/shortcutManager.ts

@@ -0,0 +1,57 @@
+/**
+ * 全局快捷键管理器 — 注册/触发分发/释放
+ * Global shortcut manager — register, dispatch, dispose
+ *
+ * @ai-context: 遍历 SHORTCUT_DEFS 声明表注册 globalShortcut；触发时向主窗口
+ * 推送 'shortcut:triggered' 事件（payload.id 为分发键，withClipboardText 的
+ * 定义附带剪贴板文本）。注册失败仅告警不阻断启动；will-quit 前必须调用
+ * unregisterShortcuts 释放（globalShortcut 不随进程自动回收）。渲染侧由
+ * shortcutDispatcher 按 id 路由处理。
+ * @ai-context: Registers every entry in SHORTCUT_DEFS; on trigger pushes
+ * 'shortcut:triggered' to the main window (payload.id is the dispatch key).
+ * Registration failures are non-fatal; always dispose before quit.
+ */
+import { globalShortcut, clipboard, type BrowserWindow } from 'electron';
+import { SHORTCUT_DEFS } from './shortcutDefs.js';
+import { logger } from './logger.js';
+
+let registered = false;
+
+/**
+ * 注册全部全局快捷键（app ready 后、主窗口创建后调用一次）。
+ * @param getMainWindow 主窗口获取器——窗口可能重建（macOS activate），
+ * 每次触发时实时获取，避免持有失效引用
+ */
+export function registerShortcuts(getMainWindow: () => BrowserWindow | null): void {
+  if (registered) return;
+
+  let okCount = 0;
+  for (const def of SHORTCUT_DEFS) {
+    const ok = globalShortcut.register(def.accelerator, () => {
+      const win = getMainWindow();
+      if (!win || win.isDestroyed()) return;
+      const payload: Record<string, unknown> = { id: def.id };
+      // capture-clipboard：剪贴板读取在主进程完成——窗口失焦时同样可用
+      if (def.withClipboardText) {
+        payload.text = clipboard.readText();
+      }
+      win.webContents.send('shortcut:triggered', payload);
+    });
+    if (ok) {
+      okCount += 1;
+      logger.info(`[Shortcut] registered "${def.id}" (${def.accelerator})`);
+    } else {
+      logger.warn(`[Shortcut] failed to register "${def.id}" (${def.accelerator}) — accelerator may be taken`);
+    }
+  }
+  registered = true;
+  logger.info(`[Shortcut] ${okCount}/${SHORTCUT_DEFS.length} global shortcuts registered`);
+}
+
+/** 释放全部全局快捷键（window-all-closed / 退出路径调用，幂等） */
+export function unregisterShortcuts(): void {
+  if (!registered) return;
+  globalShortcut.unregisterAll();
+  registered = false;
+  logger.info('[Shortcut] all global shortcuts unregistered');
+}

client/src/App.tsx

@@ -22,6 +22,7 @@ import { soundPlayer } from '@/lib/audio/SoundPlayer';
 import { getAIConfig } from '@/lib/ai/config';
 import { OfflineAIQueueBootstrap } from '@/lib/ai/OfflineAIQueueBootstrap';
 import { AssistantRoot } from '@/features/assistant/AssistantRoot';
+import { ShortcutRoot } from '@/features/shortcut/ShortcutRoot';
 import { assistantEventBus } from '@/features/assistant/lib/eventBus';
 import { RETURN_THRESHOLD_MS } from '@/features/assistant/constants';
 // 留存机制：初始化 hook（store 加载）+ 深海发现弹窗（全局 portal）
@@ -157,6 +158,9 @@ function App() {
               <OfflineAIQueueBootstrap />
               {/* AI 学伴：全局浮层，路由之外、Provider 之内，偏好关闭时零开销 */}
               <AssistantRoot />
+              {/* 全局快捷键：订阅主进程 shortcut:triggered 并按 id 分发
+                  （capture-clipboard 收藏剪贴板到收件箱） */}
+              <ShortcutRoot />
               {/* 留存机制：深海发现揭示弹窗（createPortal 到 body，与 AchievementToast 同级）
                   仅当 discoveryStore 有待展示发现时才渲染实际 DOM */}
               <DiscoveryReveal />

client/src/env.d.ts

@@ -50,6 +50,8 @@ declare global {
       onMaximizedChanged: (callback: (isMaximized: boolean) => void) => () => void;
       onSyncBeforeQuit: (callback: () => void) => () => void;
       notifySyncComplete: () => void;
+      /** 监听全局快捷键触发（payload: { id, text? }，shortcutManager 驱动） */
+      onShortcutTriggered: (callback: (payload: { id: string; text?: string }) => void) => () => void;
       setAutoUpdate: (enabled: boolean) => Promise<unknown>;
       /** FRONT2-M5: safeStorage 系统级加密（密钥材料落盘保护） */
       safeStorageEncrypt: (plain: string) => Promise<string>;
@@ -73,6 +75,12 @@ declare global {
         changePath: (newPath: string) => Promise<{ success: boolean; previousPath?: string; newPath?: string; error?: string }>;
         getActivePath: () => Promise<unknown>;
       };
+      /** E2: 费曼录音持久化（{userData}/recordings） */
+      recording: {
+        save: (stem: string, base64: string) => Promise<{ success: boolean; fileName?: string }>;
+        load: (stem: string) => Promise<{ success: boolean; base64?: string; notFound?: boolean; error?: string }>;
+        delete: (stem: string) => Promise<{ success: boolean }>;
+      };
       /** Ollama 本地推理 API */
       ollama: {
         getStatus: (forceRefresh?: boolean) => Promise<{ status: OllamaStatus; config: OllamaConfig }>;

client/src/features/shortcut/ShortcutRoot.tsx

@@ -0,0 +1,49 @@
+/**
+ * 全局快捷键根组件 — 订阅主进程触发事件并接线各 handler
+ * Shortcut root — subscribes to main-process triggers and wires handlers
+ *
+ * @ai-context: 在 App.tsx 挂载一次（ToastProvider 内）。capture-clipboard
+ * 在此接线：剪贴板文本经 inboxRepository 入库（含去重），toast 反馈结果；
+ * 失败静默降级（剪贴板为空/非 Electron 环境直接忽略）。组件卸载时
+ * 注销订阅与 handler，避免重复监听。
+ * @ai-context: Mounted once inside ToastProvider. Wires capture-clipboard to
+ * the inbox repository with dedupe and toast feedback; degrades silently on
+ * empty clipboard or missing IPC. Cleans up subscription on unmount.
+ */
+import { useEffect } from 'react';
+import { useToast } from '@/components/ui';
+import { registerShortcutHandler, unregisterShortcutHandler, dispatchShortcut } from './shortcutDispatcher';
+import { captureClipboardText } from '@/features/inbox/lib/inboxRepository';
+
+export function ShortcutRoot() {
+  const { toast } = useToast();
+
+  useEffect(() => {
+    const api = window.electronAPI;
+
+    registerShortcutHandler('capture-clipboard', async (payload) => {
+      const text = payload.text?.trim();
+      if (!text) {
+        toast({ type: 'info', message: '剪贴板为空，未收藏任何内容' });
+        return;
+      }
+      const result = await captureClipboardText(text);
+      if (!result) {
+        toast({ type: 'error', message: '收藏失败，请重试' });
+        return;
+      }
+      toast({
+        type: result.duplicated ? 'info' : 'success',
+        message: result.duplicated ? '该内容 24h 内已收藏过' : '已收藏到收件箱',
+      });
+    });
+
+    const unsubscribe = api?.onShortcutTriggered(dispatchShortcut);
+    return () => {
+      unsubscribe?.();
+      unregisterShortcutHandler('capture-clipboard');
+    };
+  }, [toast]);
+
+  return null;
+}

client/src/features/shortcut/shortcutDispatcher.ts

@@ -0,0 +1,37 @@
+/**
+ * 全局快捷键分发器 — 按 id 路由到注册的 handler
+ * Shortcut dispatcher — routes shortcut:triggered by id
+ *
+ * @ai-context: 渲染侧订阅 preload 的 onShortcutTriggered 后统一交由此分发。
+ * handler 注册表模式：新快捷键只需 registerShortcutHandler(id, fn) 追加，
+ * 与主进程 SHORTCUT_DEFS 声明一一对应。dispatchShortcut 无匹配 handler
+ * 时静默忽略（主进程已登记但渲染层尚未接线的快捷键不报错）。
+ * @ai-context: Renderer subscribes via preload then funnels events here.
+ * Handlers register by id, mirroring SHORTCUT_DEFS; unknown ids are
+ * silently ignored while the renderer wiring catches up.
+ */
+
+/** 快捷键触发 payload（与 preload onShortcutTriggered 同构） */
+export interface ShortcutPayload {
+  id: string;
+  /** capture-clipboard 等收集类快捷键附带的主进程剪贴板文本 */
+  text?: string;
+}
+
+const handlers = new Map<string, (payload: ShortcutPayload) => void>();
+
+/** 注册快捷键 handler（按 id，重复注册覆盖） */
+export function registerShortcutHandler(id: string, fn: (payload: ShortcutPayload) => void): void {
+  handlers.set(id, fn);
+}
+
+/** 注销快捷键 handler */
+export function unregisterShortcutHandler(id: string): void {
+  handlers.delete(id);
+}
+
+/** 分发一次触发事件 */
+export function dispatchShortcut(payload: ShortcutPayload): void {
+  const fn = handlers.get(payload.id);
+  if (fn) fn(payload);
+}