feat(performance): 三档性能模式（静谧/从容/澎湃）与渲染开销优化

设置页新增三档性能模式（默认从容/medium）：tier 天花板模型（effectiveTier=min(自动tier,档位上限)，自动降档仍生效但不超用户档位）；模块态 3D 按档位降帧/暂停（静谧=暂停、从容=10fps、澎湃=30fps），避免 3D 被遮罩覆盖时仍全帧渲染（持续开销最大头）；静谧档经 MotionConfig 全局减弱 Framer Motion 动画；主进程 performance:set-mode IPC 持久化档位并按档位缩放屏幕采集间隔。含 performanceMode 纯函数层 14 个单测。

Author: Aparencia

client/electron/main.ts

@@ -37,6 +37,7 @@ import { registerDisplayMediaHandler } from './displayMediaHandler.js';
 import { registerDbIpcHandlers } from './db/dbIpcHandlers.js';
 import { registerStorageIpcHandlers } from './storageIpcHandlers.js';
 import { registerKeyframeScheme, registerKeyframeIpcHandlers } from './ipc/keyframeStorage.js';
+import { loadPerformanceMode, registerPerformanceHandlers } from './performanceMode.js';
 
 // ================================================================
 // 性能优化：启用 GPU 光栅化与零拷贝
@@ -151,6 +152,10 @@ if (!gotTheLock) {
     // 课堂关键帧图片持久化 IPC + keyframe:// 协议（详见 ipc/keyframeStorage.ts）
     registerKeyframeIpcHandlers();
 
+    // 性能模式：加载持久化档位 + 注册 IPC（详见 performanceMode.ts）
+    loadPerformanceMode();
+    registerPerformanceHandlers();
+
     // 隐藏默认 Electron 菜单栏
     Menu.setApplicationMenu(null);
 

client/electron/performanceMode.ts

@@ -0,0 +1,75 @@
+/**
+ * performanceMode（主进程）— 性能模式状态、持久化与采集频率缩放
+ *
+ * 渲染进程经 performance:set-mode 设置模式并持久化到 userData，
+ * 启动时加载，供屏幕采集间隔缩放等进程级策略使用。
+ *
+ * @ai-context: 主进程模块。backgroundThrottling 等需重建窗口的策略
+ * 因与番茄钟后台计时精度冲突，暂不启用（保持 backgroundThrottling:false），
+ * 待与番茄钟状态协同后再引入。
+ */
+import { app } from 'electron';
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { safeHandle } from './ipcUtils.js';
+import { logger } from './logger.js';
+
+export type PerformanceMode = 'low' | 'medium' | 'high';
+
+const DEFAULT_MODE: PerformanceMode = 'medium';
+
+/** 各模式采集频率倍率（作用于截屏间隔：interval / scale，scale<1 即降频） */
+const CAPTURE_RATE_SCALE: Record<PerformanceMode, number> = {
+  low: 0.5,
+  medium: 1,
+  high: 1,
+};
+
+let currentMode: PerformanceMode = DEFAULT_MODE;
+
+function configPath(): string {
+  return join(app.getPath('userData'), 'performance-mode.json');
+}
+
+function isMode(v: unknown): v is PerformanceMode {
+  return v === 'low' || v === 'medium' || v === 'high';
+}
+
+/** 启动时加载持久化模式（文件缺失/损坏时用默认值） */
+export function loadPerformanceMode(): void {
+  try {
+    const parsed = JSON.parse(readFileSync(configPath(), 'utf-8'));
+    if (isMode(parsed?.mode)) currentMode = parsed.mode;
+  } catch { /* 首次运行或文件损坏：使用默认 medium */ }
+  logger.info(`[PerformanceMode] 当前模式: ${currentMode}`);
+}
+
+/** 设置模式并持久化（由 IPC 调用） */
+export function setPerformanceMode(mode: unknown): void {
+  if (!isMode(mode)) return;
+  currentMode = mode;
+  try {
+    writeFileSync(configPath(), JSON.stringify({ mode }), 'utf-8');
+  } catch (err) {
+    logger.error('[PerformanceMode] 持久化失败:', err);
+  }
+  logger.info(`[PerformanceMode] 模式已设置: ${mode}`);
+}
+
+/** 当前模式 */
+export function getPerformanceMode(): PerformanceMode {
+  return currentMode;
+}
+
+/** 采集频率倍率（用于缩放截屏间隔） */
+export function getCaptureRateScale(): number {
+  return CAPTURE_RATE_SCALE[currentMode];
+}
+
+/** 注册性能模式 IPC handler */
+export function registerPerformanceHandlers(): void {
+  safeHandle('performance:set-mode', async (_event, mode: unknown) => {
+    setPerformanceMode(mode);
+    return { success: true, mode: getPerformanceMode() };
+  });
+}

client/electron/preload.ts

@@ -89,6 +89,8 @@ const ALLOWED_CHANNELS = [
   // 课堂关键帧图片持久化 IPC channel
   'keyframe_save',
   'keyframe_cleanup',
+  // 性能模式 IPC channel（三档：静谧/从容/澎湃）
+  'performance:set-mode',
 ] as const;
 
 /** 允许渲染进程监听的事件 channel 白名单（主进程 → 渲染进程推送） */

client/electron/screenCaptureHandlers.ts

@@ -14,6 +14,7 @@ import type { ScreenCaptureOptions, ScreenshotFrameData } from './screenCapture.
 import { safeHandle, getMainWindowId } from './ipcUtils.js';
 import { logger } from './logger.js';
 import { scoreAndFilterWindows } from './windowScorer.js';
+import { getCaptureRateScale } from './performanceMode.js';
 
 // ================================================================
 // 模块级状态
@@ -78,6 +79,12 @@ export function registerScreenCaptureHandlers(): void {
             safeOptions.interval = 5000;
           }
 
+          // 按性能模式缩放采集间隔（静谧档 scale=0.5 → 间隔翻倍、频率减半，降低开销）
+          const rateScale = getCaptureRateScale();
+          if (typeof safeOptions.interval === 'number' && rateScale !== 1) {
+            safeOptions.interval = Math.min(60000, Math.round(safeOptions.interval / rateScale));
+          }
+
           activeCapture = new ScreenCapture(safeOptions, (frame: ScreenshotFrameData) => {
             if (senderWin && !senderWin.isDestroyed()) {
               senderWin.webContents.send('screen_capture_frame', frame);

client/src/components/layout/AppLayout.tsx

@@ -3,7 +3,7 @@
  */
 import { useEffect, useState } from 'react';
 import { Outlet, useLocation, useNavigate } from 'react-router-dom';
-import { AnimatePresence, motion } from 'framer-motion';
+import { AnimatePresence, motion, MotionConfig } from 'framer-motion';
 import { Home } from 'lucide-react';
 import CommandPalette from '../ui/CommandPalette';
 import { CloseConfirmDialog } from '../ui/CloseConfirmDialog';
@@ -24,6 +24,8 @@ import { useOnboardingStore } from '@/components/onboarding/useOnboardingStore';
 import { useRuntimeEnv } from '@/lib/env/useRuntimeEnv';
 import { PWAInstallPrompt } from '@/components/PWAInstallPrompt';
 import { FirstDiveGate } from '@/features/onboarding/firstDive/FirstDiveGate';
+import { usePerformanceModeStore } from '@/lib/performance/usePerformanceMode';
+import { PERFORMANCE_MODE_CONFIG } from '@/lib/performance/performanceMode';
 
 export default function AppLayout() {
   const { pathname } = useLocation();
@@ -33,6 +35,9 @@ export default function AppLayout() {
   const [showCloseDialog, setShowCloseDialog] = useState(false);
   const { sync } = useSync();
   const { shouldDegrade3D } = useRuntimeEnv();
+  // 性能模式：静谧(low)档全局减弱 Framer Motion 动画（transform/layout 动画直接到位）
+  const perfMode = usePerformanceModeStore((s) => s.mode);
+  const reduceMotion = PERFORMANCE_MODE_CONFIG[perfMode].reduceMotion;
 
   // 监听 session 过期事件
   useSessionExpiry();
@@ -109,6 +114,7 @@ export default function AppLayout() {
   }, [isInModule, enterModule, exitModule, navigate, openHelp]);
 
   return (
+    <MotionConfig reducedMotion={reduceMotion ? 'always' : 'user'}>
     <div className="flex flex-col h-screen overflow-hidden">
       {/* Layer 2: 始终最顶层 — Electron标题栏 */}
       <CustomTitlebar />
@@ -173,5 +179,6 @@ export default function AppLayout() {
       <PWAInstallPrompt />
       <CloseConfirmDialog open={showCloseDialog} onClose={() => setShowCloseDialog(false)} />
     </div>
+    </MotionConfig>
   );
 }

client/src/lib/3d/core/QualityController.tsx

@@ -6,11 +6,12 @@
  */
 import { useThree } from '@react-three/fiber';
 import { useEffect } from 'react';
-import { usePerformanceStore } from './PerformanceMonitor';
+import { useEffectiveTier } from '@/lib/performance/usePerformanceMode';
 
 export function QualityController() {
   const { gl } = useThree();
-  const tier = usePerformanceStore((s) => s.tier);
+  // 有效 tier（自动 tier 受用户性能模式上限约束）
+  const tier = useEffectiveTier();
 
   useEffect(() => {
     switch (tier) {

client/src/lib/3d/core/SceneProvider.tsx

@@ -4,15 +4,26 @@
  * 但仍低于所有 UI 浮层（标题栏 z-50 / FunctionalOverlay z-10 / 引导 z-40+）。
  * 注意：不能用负 z-index，否则会落到根 div 之后被其透明盒拦截点击。
  *
+ * 帧循环策略（性能优化核心）：
+ * - 概览态（!isInModule）：frameloop=always 全帧渲染（可交互）；
+ * - 模块态（isInModule，3D 被遗罩覆盖）：按性能模式降帧/暂停——
+ *   静谧(low)=never 暂停、从容(medium)=demand 10fps、澎湃(high)=demand 30fps，
+ *   避免 3D 在不可见时仍全帧渲染（持续开销最大头）。
+ * - 模块态不渲染 PerformanceMonitor：降帧后的 FPS 是人为限制值，
+ *   若用于测量会被误判为性能恶化而降级 tier。
+ *
  * @ai-context: 3D 场景核心（R3F）：SceneProvider。
  */
-import { Canvas } from '@react-three/fiber';
-import { Suspense } from 'react';
+import { Canvas, useThree } from '@react-three/fiber';
+import { Suspense, useEffect } from 'react';
 import { Preload } from '@react-three/drei';
 import { PerformanceMonitor } from './PerformanceMonitor';
 import { QualityController } from './QualityController';
 import { MemoryManager } from './MemoryManager';
 import { ContextRecovery } from './ContextRecovery';
+import { useOrbitalStore } from '../navigation/OrbitalStore';
+import { usePerformanceModeStore } from '@/lib/performance/usePerformanceMode';
+import { PERFORMANCE_MODE_CONFIG } from '@/lib/performance/performanceMode';
 import * as THREE from 'three';
 
 interface SceneProviderProps {
@@ -21,10 +32,33 @@ interface SceneProviderProps {
   interactive?: boolean;
 }
 
+/** 模块态降帧 ticker：demand 模式下按目标帧率触发渲染（invalidate） */
+function ModuleFpsTicker({ fps }: { fps: number }) {
+  const invalidate = useThree((s) => s.invalidate);
+  useEffect(() => {
+    if (fps <= 0) return; // 暂停档：不触发渲染
+    const id = setInterval(() => invalidate(), 1000 / fps);
+    return () => clearInterval(id);
+  }, [fps, invalidate]);
+  return null;
+}
+
 export function SceneProvider({ children, interactive = false }: SceneProviderProps) {
+  const isInModule = useOrbitalStore((s) => s.isInModule);
+  const mode = usePerformanceModeStore((s) => s.mode);
+  const moduleFps = PERFORMANCE_MODE_CONFIG[mode].moduleFps;
+
+  // 帧循环策略：概览态全帧；模块态按档位降帧/暂停
+  const frameloop: 'always' | 'demand' | 'never' = !isInModule
+    ? 'always'
+    : moduleFps === 0
+      ? 'never'
+      : 'demand';
+
   return (
     <div className="fixed inset-0 z-0" style={{ pointerEvents: interactive ? 'auto' : 'none' }}>
       <Canvas
+        frameloop={frameloop}
         gl={{
           antialias: true,
           alpha: true,
@@ -49,7 +83,10 @@ export function SceneProvider({ children, interactive = false }: SceneProviderPr
           console.info('[3D] WebGL renderer:', rendererName);
         }}
       >
-        <PerformanceMonitor />
+        {/* 模块态降帧 ticker（仅 demand 模式） */}
+        {frameloop === 'demand' && <ModuleFpsTicker fps={moduleFps} />}
+        {/* FPS 自动降档仅在概览态测量（模块态帧率被人为限制，不可作为性能依据） */}
+        {!isInModule && <PerformanceMonitor />}
         <QualityController />
         <MemoryManager />
         <ContextRecovery />

client/src/lib/3d/objects/ParticleSystem.tsx

@@ -7,7 +7,7 @@
 import { useRef, useMemo } from 'react';
 import { useFrame } from '@react-three/fiber';
 import * as THREE from 'three';
-import { usePerformanceStore } from '../core/PerformanceMonitor';
+import { useEffectiveTier } from '@/lib/performance/usePerformanceMode';
 
 interface ParticleSystemProps {
   count?: number;
@@ -25,7 +25,8 @@ export function ParticleSystem({
   speed = 1,
 }: ParticleSystemProps) {
   const pointsRef = useRef<THREE.Points>(null);
-  const tier = usePerformanceStore((s) => s.tier);
+  // 有效 tier（自动 tier 受用户性能模式上限约束）
+  const tier = useEffectiveTier();
 
   const particleCount = tier === 'low' ? 500 : tier === 'medium' ? 1200 : count;
 

client/src/lib/3d/scenes/AuroraDomeWorld.tsx

@@ -10,7 +10,7 @@ import * as THREE from 'three';
 import { Bloom, Vignette, ChromaticAberration } from '@react-three/postprocessing';
 import { BlendFunction } from 'postprocessing';
 import { SafeEffectComposer } from '../core/SafeEffectComposer';
-import { usePerformanceStore } from '../core/PerformanceMonitor';
+import { useEffectiveTier } from '@/lib/performance/usePerformanceMode';
 
 // ─── 天空穹顶着色器 ───────────────────────────────────────
 const domeVertexShader = /* glsl */ `
@@ -269,7 +269,8 @@ function CloudLayer() {
 
 // ─── 主场景组件 ───────────────────────────────────────────
 export function AuroraDomeWorld() {
-  const tier = usePerformanceStore((s) => s.tier);
+  // 有效 tier（自动 tier 受用户性能模式上限约束）
+  const tier = useEffectiveTier();
 
   // 根据性能等级调整粒子数
   const particleCount = tier === 'low' ? 500 : tier === 'medium' ? 1000 : 1500;

client/src/lib/3d/scenes/DeepSeaWorld.tsx

@@ -6,10 +6,11 @@
  */
 import { Bloom, DepthOfField, Vignette } from '@react-three/postprocessing';
 import { SafeEffectComposer } from '../core/SafeEffectComposer';
-import { usePerformanceStore } from '../core/PerformanceMonitor';
+import { useEffectiveTier } from '@/lib/performance/usePerformanceMode';
 
 export function DeepSeaWorld() {
-  const tier = usePerformanceStore((s) => s.tier);
+  // 有效 tier（自动 tier 受用户性能模式上限约束）
+  const tier = useEffectiveTier();
 
   return (
     <group>