feat: v0.10.1 — AI 错误处理增强、主页导航修复与后端路由优化

AI 错误处理增强：
- 新增 errorClassifier 错误分类器
- 新增 errorMessages 统一错误消息
- 新增 useAIErrorHandler Hook
- 新增 useAIFeature Hook
- ElectronAIPlugin / RemoteAIPlugin 错误处理优化
- AI 配置与类型系统扩展

主页与导航修复：
- 主页导航动效修复
- 弹性翻页时序优化
- AppLayout / PageTransition 交互增强

设置页优化：
- AIProviderSettings / DataSettings / ModeSettings 改进
- useSettingsStore 状态管理优化

后端路由优化：
- 全部路由模块增强（evaluate/feynman/cards/inspiration/learning/recommend/socratic/summarize/tag/transcribe/vision）
- auth / rate_limit 中间件优化
- AI 网关配置更新

部署配置：
- docker-compose.prod.yml 调整
- Nginx 配置更新

README 更新至 v0.10.1

Author: Aparencia

README.md

@@ -3,7 +3,7 @@
   <p align="center"><strong>你的 AI 智能学习伙伴 — 让每一分钟学习都高效有价值</strong></p>
   <p align="center">
     <img src="https://img.shields.io/badge/status-beta-green.svg" alt="Status" />
-    <img src="https://img.shields.io/badge/version-v0.9.0-blue.svg" alt="Version" />
+    <img src="https://img.shields.io/badge/version-v0.10.1-blue.svg" alt="Version" />
     <img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License" />
   </p>
 </p>
@@ -216,6 +216,8 @@ KeBan/
 | **v0.7.0** | ✅ 已完成 | 自定义标题栏 + 用户体系 + 邮箱验证 + 灵感 AI 整理 + 会话管理 |
 | **v0.8.0** | ✅ 已完成 | UI 视觉升级（深海静谧） + Electron 安全加固 + 标题栏增强 + 音效分类控制 + BUG 清零 |
 | **v0.9.0** | ✅ 已完成 | 笔记搜索优化 + 标签筛选 + 闪卡堆叠组件 + 多项 BUG 修复 |
+| **v0.10.0** | ✅ 已完成 | 主页氛围化问候 + 深海认知景深层 + 弹性翻页交互 + 启动缓冲带 + 动效优化 |
+| **v0.10.1** | ✅ 已完成 | 主页导航动效修复 + 弹性翻页时序优化 |
 | **正式上线** | 🎯 规划中 | 生产就绪版 |
 
 ### 🔮 未来方向
@@ -234,8 +236,8 @@ KeBan/
 | 组成部分 | 含义 | 示例 |
 |----------|------|------|
 | `MAJOR` | 不兼容的 API 变更 | `1.0.0` |
-| `MINOR` | 向后兼容的功能新增 | `0.9.0` |
-| `PATCH` | 向后兼容的缺陷修复 | `0.9.1` |
+| `MINOR` | 向后兼容的功能新增 | `0.10.0` |
+| `PATCH` | 向后兼容的缺陷修复 | `0.10.1` |
 
 发布 Tag 前请确保：`npm run lint` / `npm run test` / `npm run build` 全部通过。
 

client/electron/ai/utils.ts

@@ -5,19 +5,64 @@
  * POST 请求辅助函数、网关地址管理和功能注册表接口定义。
  */
 
+import { app } from 'electron';
+import * as path from 'path';
+import { readFile, writeFile } from 'fs/promises';
 import { logger } from '../logger.js';
 
 // ================================================================
 // 常量
 // ================================================================
 
 const DEFAULT_GATEWAY_URL = '';
+const GATEWAY_CONFIG_FILE = 'ai-gateway-config.json';
 
-/** 获取 AI 网关地址，优先读取环境变量 VITE_AI_GATEWAY_URL */
+// ── 运行时网关地址（渲染进程通过 IPC 同步） ──
+let _runtimeGatewayUrl: string | null = null;
+
+/**
+ * 获取 AI 网关地址
+ * 优先级：运行时设置 > 持久化文件 > 环境变量 > 默认空值
+ */
 export function gatewayUrl(): string {
+  if (_runtimeGatewayUrl) return _runtimeGatewayUrl;
   return process.env.VITE_AI_GATEWAY_URL || DEFAULT_GATEWAY_URL;
 }
 
+/**
+ * 设置运行时网关地址（由渲染进程通过 IPC 调用）
+ * 同时持久化到 userData 目录，确保主进程重启后仍可用
+ */
+export async function setRuntimeGatewayUrl(url: string): Promise<void> {
+  _runtimeGatewayUrl = url;
+  logger.info(`[AI-Gateway] Runtime gateway URL set: ${url}`);
+  // 持久化到文件
+  try {
+    const configPath = path.join(app.getPath('userData'), GATEWAY_CONFIG_FILE);
+    await writeFile(configPath, JSON.stringify({ gatewayUrl: url }), 'utf-8');
+  } catch (err) {
+    logger.error('[AI-Gateway] Failed to persist gateway URL', err);
+  }
+}
+
+/**
+ * 应用启动时从持久化文件加载网关地址
+ * 在 registerAIHandlers 之前调用
+ */
+export async function loadPersistedGatewayUrl(): Promise<void> {
+  try {
+    const configPath = path.join(app.getPath('userData'), GATEWAY_CONFIG_FILE);
+    const raw = await readFile(configPath, 'utf-8');
+    const config = JSON.parse(raw);
+    if (config.gatewayUrl) {
+      _runtimeGatewayUrl = config.gatewayUrl;
+      logger.info(`[AI-Gateway] Loaded persisted gateway URL: ${config.gatewayUrl}`);
+    }
+  } catch {
+    // 文件不存在或解析失败，静默忽略
+  }
+}
+
 // ================================================================
 // AI 功能注册表接口定义
 // ================================================================

client/electron/main.ts

@@ -14,6 +14,7 @@ import { writeFile, readFile } from 'fs/promises';
 import { safeHandle, setMainWindowId } from './ipcUtils.js';
 import { logger } from './logger.js';
 import { registerAIHandlers } from './ai/index.js';
+import { loadPersistedGatewayUrl, setRuntimeGatewayUrl } from './ai/utils.js';
 import { initAutoUpdater, checkForUpdate, downloadUpdate, installUpdate, destroyAutoUpdater, setAutoCheckEnabled } from './updater.js';
 import { createMainWindow, saveCloseChoice } from './windowManager.js';
 import { destroyTray } from './trayManager.js';
@@ -99,8 +100,8 @@ if (!gotTheLock) {
         // 开发环境：允许 unsafe-inline/unsafe-eval（Vite HMR 需要）
         // 生产环境：禁止 unsafe-eval，保留 unsafe-inline（Tailwind 运行时需要）
         const csp = isDev
-          ? "default-src 'self' 'unsafe-inline' 'unsafe-eval' http://localhost:* ws://localhost:*; connect-src 'self' http://localhost:* ws://localhost:* https://*.supabase.co wss://*.supabase.co; img-src 'self' data: blob: https://*.supabase.co; font-src 'self' data:;"
-          : "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https://*.supabase.co; font-src 'self' data:; connect-src 'self' https://*.supabase.co wss://*.supabase.co; frame-ancestors 'none';";
+          ? "default-src 'self' 'unsafe-inline' 'unsafe-eval' http://localhost:* ws://localhost:*; connect-src 'self' http://localhost:* ws://localhost:* https://*.supabase.co wss://*.supabase.co https://entropydecrease.com wss://entropydecrease.com; img-src 'self' data: blob: https://*.supabase.co; font-src 'self' data:;"
+          : "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https://*.supabase.co; font-src 'self' data:; connect-src 'self' https://*.supabase.co wss://*.supabase.co https://entropydecrease.com wss://entropydecrease.com; frame-ancestors 'none';";
 
         callback({
           responseHeaders: {
@@ -115,6 +116,8 @@ if (!gotTheLock) {
       logger.error('[SEC] Failed to inject CSP policy', err);
     }
 
+    // 加载持久化的 AI 网关地址（在注册 handler 之前，确保 handler 可用正确的 URL）
+    await loadPersistedGatewayUrl();
     registerAIHandlers();
     registerCaptureHandlers();
 
@@ -130,6 +133,12 @@ if (!gotTheLock) {
     // 隐藏默认 Electron 菜单栏
     Menu.setApplicationMenu(null);
 
+    // AI 网关地址同步（渲染进程 → 主进程）
+    safeHandle('ai:set-gateway-url', async (_event, url: string) => {
+      await setRuntimeGatewayUrl(url);
+      return { success: true };
+    });
+
     // 通用 IPC handlers
     safeHandle('get-app-version', async () => {
       return app.getVersion();

client/electron/preload.ts

@@ -15,6 +15,7 @@ const ALLOWED_CHANNELS = [
   'ai_recommend_duration',
   'ai_feynman_question',
   'ai_feynman_evaluate_answers',
+  'ai:set-gateway-url',
   'screen_list_windows',
   'screen_capture_start',
   'screen_capture_stop',

client/electron/windowManager.ts

@@ -105,7 +105,7 @@ export function createMainWindow(
   if (isDev) {
     // 开发模式：连接 Vite 开发服务器
     win.loadURL('http://localhost:5173');
-    win.webContents.openDevTools();
+    win.webContents.openDevTools({ mode: 'detach' });
   } else {
     // 生产模式：加载打包后的 index.html
     win.loadFile(path.join(app.getAppPath(), 'dist', 'index.html'));

client/package-lock.json

@@ -2,7 +2,7 @@
   "name": "entropy-decrease",
   "productName": "Entropy decrease",
   "private": true,
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "熵减 - 跨端学习平台",
   "author": "Entropy Decrease Team",
   "main": "dist-electron/electron/main.js",
@@ -11,7 +11,7 @@
     "build": "tsc -b && vite build",
     "lint": "oxlint",
     "preview": "vite preview",
-    "electron:dev": "concurrently -k -n vite,electron \"cross-env ELECTRON_BUILD=1 vite\" \"wait-on http://localhost:5173 && tsc -p electron/tsconfig.json && cross-env ELECTRON_BUILD=1 electron .\"",
+    "electron:dev": "concurrently -k -n vite,electron \"cross-env ELECTRON_BUILD=1 vite\" \"wait-on http://localhost:5173 && tsc -p electron/tsconfig.json && cross-env ELECTRON_BUILD=1 NODE_ENV=development electron .\"",
     "electron:build": "cross-env ELECTRON_BUILD=1 vite build && tsc -p electron/tsconfig.json && electron-builder",
     "test": "vitest run",
     "test:watch": "vitest",

client/package.json

@@ -12,6 +12,7 @@ import { router } from '@/routes';
 import { useTheme } from '@/hooks/useTheme';
 import { db } from '@/lib/storage/database';
 import { soundPlayer } from '@/lib/audio/SoundPlayer';
+import { getAIConfig } from '@/lib/ai/config';
 import '@/stores/useSettingsStore'; // 导入以触发音效设置初始化
 
 // 启动时预加载所有音效（不阻塞渲染）
@@ -57,6 +58,11 @@ function App() {
     // 应用空闲时预检测 AI 网关健康状态（不阻塞首屏）
     const idle = window.requestIdleCallback ?? ((cb: () => void) => setTimeout(cb, 1500));
     idle(() => {
+      // 同步网关地址到主进程（主进程无法访问 localStorage，需显式传递）
+      const aiConfig = getAIConfig();
+      if (aiConfig.gatewayUrl && window.electronAPI) {
+        window.electronAPI.invoke('ai:set-gateway-url', aiConfig.gatewayUrl).catch(() => {});
+      }
       import('./hooks/useAIGatewayHealth').then(({ precheckGatewayHealth }) => {
         precheckGatewayHealth();
       });

client/src/App.tsx

@@ -1,4 +1,5 @@
 import { useState, useCallback, useEffect } from 'react';
+import { useNavigate } from 'react-router-dom';
 import { motion, AnimatePresence } from 'framer-motion';
 import {
   X, HelpCircle, Lightbulb, Layers, BookOpen,
@@ -38,7 +39,8 @@ const SUGGESTIONS = [
 export function RescuePanel({ isOpen, onClose, context, onSuggestion }: RescuePanelProps) {
   const [activeLevel, setActiveLevel] = useState<RescueLevel>(1);
   const [showIncubation, setShowIncubation] = useState(false);
-  const { loading, data, error, rescue } = useAIRescue();
+  const { loading, data, error, needsConfig, rescue } = useAIRescue();
+  const navigate = useNavigate();
 
   // 面板打开时触发救援请求
   useEffect(() => {
@@ -149,6 +151,14 @@ export function RescuePanel({ isOpen, onClose, context, onSuggestion }: RescuePa
               {error && !loading && (
                 <div className="p-3 rounded-kb-md bg-semantic-error/10 border border-semantic-error/20 text-b2 text-semantic-error">
                   {error}
+                  {needsConfig && (
+                    <button
+                      onClick={() => navigate('/settings')}
+                      className="mt-2 block text-b3 underline hover:no-underline"
+                    >
+                      前往设置页配置 API Key
+                    </button>
+                  )}
                 </div>
               )}
 

client/src/components/RescuePanel.tsx

@@ -83,7 +83,7 @@ export default function AppLayout() {
           {/* Page content */}
           <main className="flex-1 overflow-y-auto overflow-x-hidden pb-16 md:pb-0 relative">
             <AnimatePresence mode="wait" initial={false}>
-              <PageTransition key={pathname}>
+              <PageTransition key={pathname} variant={pathname === '/' ? 'none' : 'default'}>
                 <Outlet />
               </PageTransition>
             </AnimatePresence>