feat: 主题切换性能优化 — View Transitions API + 0.15s 统一过渡 + 设置页增强

【问题】
  桌面端（Electron）切换主题时颜色变化速度不一致、明显卡顿。
  根因分析（4 轮迭代）：
    1. 过渡时长不统一（body 0.3s / 组件 0.15s）→ 统一到 0.2s
    2. antd CSS-in-JS 标签替换导致瞬间变色 → 尝试 cssVar（无效，仍走标签替换）
    3. applyHtmlTheme 在 updater 回调中执行，与 antd CSS 变更不同帧 → 移入 useLayoutEffect
    4. html * 全局过渡在 Electron 中为数千 DOM 节点同步插值 → 合成器掉帧
  终极方案：View Transitions API（GPU 合成器 1 次 cross-fade 替代 N 个 CSS 过渡）
   + 精准 CSS 过渡覆盖 ~80 个 antd 容器类（回退方案）

  【修改】

  ThemeProvider.tsx — 核心重构
    - applyHtmlTheme 从 setIsDark updater → useLayoutEffect([isDark])
      确保自定义 CSS 变量与 antd CSS-in-JS 在同一次 React 提交中生效
    - View Transitions API：document.startViewTransition + flushSync
      GPU 合成器截取旧/新两帧做单次 cross-fade，消除多元素插值卡顿
    - 浏览器不支持时自动回退到 CSS transition 方案

  globals.css — 过渡策略
    - body: 0.3s ease → 0.15s linear
    - View Transitions 动画：::view-transition-old/new(root) 0.15s linear
    - ~80 个 antd 容器类精准过渡（Layout/Card/Modal/Table/Input/
      Select/Picker/Menu/Tabs/Tag/Alert/Empty/Result/Skeleton 等）
      按功能分组：布局 → 表格 → 表单 → 导航 → 反馈
      不覆盖交互组件自有 transition（Button/Switch/Slider 等）
      linear 替代 ease — 匀速插值，桌面应用更利落

  Layout.tsx / HomeContent.tsx / LeftPanel.tsx / ModelSelector.tsx
    - 过渡参数对齐：全部 0.2s → 0.15s linear

  SettingsPage.tsx — 用户体验
    - Modal 取消 keyboard={false}，Esc 键可关闭
    - macOS：关闭按钮移至标题左侧（遵循 macOS HIG）
    - afterClose 中 blur 当前焦点元素，防止聚焦跳到导航栏

  【文档】
  CHANGELOG.md — 新增 0.0.15 版本记录
  CLAUDE.md — 新增主题系统架构章节（双轨颜色体系 / 时序 / 过渡策略）

.gitignore

@@ -36,3 +36,5 @@ dist-ssr
 *.py
 *.pyi
 WORKLOG.md
+*openapi*.json
+response_*.json

CHANGELOG.md

@@ -1,6 +1,28 @@
 # 更新日志
 
 > 每次发版前修改此文件，`npm run build:win` 打包后会自动读取生成 update-info.json。
+---
+
+## 0.0.15（2026-06-09）
+
+**主题切换性能优化 — 桌面端流畅度提升**
+
+- View Transitions API 驱动主题切换：GPU 合成器单次 cross-fade 替代 80+ 个独立 CSS 过渡，消除 Electron 卡顿
+- 主题更新时序统一：`applyHtmlTheme` 从 updater → `useLayoutEffect`，CSS 变量与 React 提交同帧
+- 过渡参数对齐：全部 `0.2s ease` → `0.15s linear`，桌面应用更利落
+- CSS 过渡精准覆盖：antd 容器组件（Layout/Card/Modal/Table/Input/Menu 等 ~80 个类）替代 `html *` 全局选择器
+- 设置页 Esc 键关闭 + macOS 关闭按钮适配 + 关闭后焦点防跳转
+
+---
+
+## 0.0.14 -- 🚀更新公告
+
+**模型选择器焕新**
+
+- 模型列表改为标签页分组展示，新增「全部模型」Tab
+- 列表项新增悬停高亮效果，维护中模型自动置灰并提示
+- 修复选择模型后参数表单重复 key 报错
+- 类型体系重构，支持后端分类 slug 自动映射
 
 ---
 

CLAUDE.md

@@ -2,3 +2,26 @@
 
 - 所有交互、解释、代码注释与生成内容均使用简体中文，专有技术名词可保留英文，但需附带中文说明
 - 进行任务时都需要考虑安全、性能、主题切换、业务自定义错误、事件总线驱动方式以及日志记录
+- 有需要请自己调用MCP服务
+
+# 主题系统架构
+
+## 双轨颜色体系
+
+1. **自定义 CSS 变量**（`globals.css`）：`data-theme="light|dark"` → `var(--color-bg-base)` 等，用于 body 和自定义组件
+2. **antd 令牌**（`antd-theme.ts`）：`ConfigProvider theme={algorithm}` → `useToken()` → inline style，用于 antd 组件
+
+## 主题切换时序（关键）
+
+```
+ThemeProvider.useLayoutEffect([isDark])
+  → applyHtmlTheme(isDark)         ← data-theme 属性变更
+  (与 ConfigProvider 的 useInsertionEffect 同帧执行)
+  → 浏览器绘制 ← 所有颜色变更在同一帧生效
+```
+
+## 过渡策略
+
+- **Electron/Chromium**：View Transitions API（`document.startViewTransition` + `flushSync`），GPU 合成器单次 cross-fade
+- **其他浏览器**：CSS `transition: color/bg/border/shadow 0.15s linear`，精准覆盖 ~80 个 antd 容器类（不覆盖交互组件自有 transition）
+- **不启用 antd cssVar**：经实测 cssVar 模式下 CSS-in-JS 仍走标签替换路径，过渡无效

electron/main.ts

@@ -1,4 +1,4 @@
-import { app, BrowserWindow, ipcMain, dialog } from 'electron';
+import {app, BrowserWindow, ipcMain, dialog, session} from 'electron';
 import {createRequire} from 'node:module';
 import {fileURLToPath} from 'node:url';
 import path from 'node:path';
@@ -151,6 +151,16 @@ app.whenReady().then(() => {
     setupAppMenu();
     app.setName(WINDOW_TITLE);
     registerUpdateIpcHandlers();
+    const fakeUserAgent = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36';
+    session.defaultSession.webRequest.onBeforeSendHeaders((details, callback) => {
+        const url = details.url;
+        if (url.includes("rh-images-1252422369.cos.ap-beijing.myqcloud.com")) {
+            details.requestHeaders['User-Agent'] = fakeUserAgent;
+        }
+        callback({
+            requestHeaders: details.requestHeaders
+        });
+    });
 
     // 文件对话框 IPC 处理（供渲染进程选择文件夹）
     ipcMain.handle(BIDIRECTIONAL.FILE_DIALOG, async (_event, options: Electron.OpenDialogOptions) => {

package.json

@@ -1,7 +1,7 @@
 {
    "name": "ele-heixiu",
    "private": true,
-   "version": "0.0.13",
+   "version": "0.0.14",
    "description": "船长·HeiXiu — 桌面效率工作台",
    "author": "HeiXiu 杨烨",
    "type": "module",

src/components/Layout.tsx

@@ -13,7 +13,7 @@ export function Layout({ children }: { children: ReactNode }) {
 
    return (
       <div
-         className="h-screen flex flex-col transition-colors duration-300"
+         className="h-screen flex flex-col transition-colors duration-150"
          style={{ background: token.colorBgLayout }}
       >
          <BannerCarousel />

src/components/ThemeProvider.tsx

@@ -1,8 +1,14 @@
 // ============================================================
 // ThemeProvider — 主题 Provider 组件
+//
+// 桌面端（Electron）使用 View Transitions API 驱动主题切换：
+// GPU 合成器截取旧/新两帧做一次 cross-fade，替代 80+ 个
+// 独立 CSS 过渡，消除 Electron Chromium 的合成器卡顿。
+// 浏览器不支持时回退到 CSS transition 方案。
 // ============================================================
 
-import { useState, useEffect, useCallback, type ReactNode } from 'react';
+import { useState, useEffect, useLayoutEffect, useCallback, type ReactNode } from 'react';
+import { flushSync } from 'react-dom';
 import { ConfigProvider } from 'antd';
 import zhCN from 'antd/locale/zh_CN';
 
@@ -20,33 +26,66 @@ interface ThemeProviderProps {
    children: ReactNode;
 }
 
+/** 检测 View Transitions API 是否可用（Chromium 111+，Electron 28+） */
+function supportsViewTransition(): boolean {
+   return typeof document !== 'undefined' && 'startViewTransition' in document;
+}
+
 export function ThemeProvider({ children }: ThemeProviderProps) {
    const [isDark, setIsDark] = useState<boolean>(readStoredTheme);
 
-   // 挂载时同步
+   useLayoutEffect(() => {
-   useEffect(() => {
       applyHtmlTheme(isDark);
-   }, []); // eslint-disable-line react-hooks/exhaustive-deps
+   }, [isDark]);
 
    const toggleTheme = useCallback(() => {
+      if (supportsViewTransition()) {
+         // View Transitions API：GPU 合成器 cross-fade，1 个动画替代 N 个 CSS 过渡
+         document.startViewTransition(() => {
+            flushSync(() => {
                setIsDark((prev) => {
                   const next = !prev;
                   writeStoredTheme(next);
-         applyHtmlTheme(next);
                   return next;
                });
+            });
+         });
+      } else {
+         // 回退：普通 React 状态更新 + CSS transition
+         setIsDark((prev) => {
+            const next = !prev;
+            writeStoredTheme(next);
+            return next;
+         });
+      }
    }, []);
 
    const setLight = useCallback(() => {
+      if (supportsViewTransition()) {
+         document.startViewTransition(() => {
+            flushSync(() => {
                setIsDark(false);
                writeStoredTheme(false);
-      applyHtmlTheme(false);
+            });
+         });
+      } else {
+         setIsDark(false);
+         writeStoredTheme(false);
+      }
    }, []);
 
    const setDark = useCallback(() => {
+      if (supportsViewTransition()) {
+         document.startViewTransition(() => {
+            flushSync(() => {
                setIsDark(true);
                writeStoredTheme(true);
-      applyHtmlTheme(true);
+            });
+         });
+      } else {
+         setIsDark(true);
+         writeStoredTheme(true);
+      }
    }, []);
 
    // 监听系统主题变化（仅用户从未手动切换时跟随）
@@ -56,7 +95,6 @@ export function ThemeProvider({ children }: ThemeProviderProps) {
          const stored = localStorage.getItem(STORAGE_KEY);
          if (stored === null) {
             setIsDark(e.matches);
-            applyHtmlTheme(e.matches);
          }
       };
       mq.addEventListener('change', handleChange);

src/pages/home/HomeContent.tsx

@@ -211,7 +211,7 @@ export function HomeContent() {
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
-         transition: 'background 0.2s ease',
+         transition: 'background 0.15s linear',
       };
    };
 
@@ -283,7 +283,7 @@ export function HomeContent() {
                               : hoveredDivider === 'left'
                                   ? token.colorPrimary
                                   : token.colorBorder,
-                          transition: 'background 0.2s ease',
+                          transition: 'background 0.15s linear',
                        }} />
                     </div>
                  </>
@@ -311,7 +311,7 @@ export function HomeContent() {
                        : hoveredDivider === 'right'
                            ? token.colorPrimary
                            : token.colorBorder,
-                   transition: 'background 0.2s ease',
+                   transition: 'background 0.15s linear',
                 }} />
              </div>
 

src/pages/home/components/LeftPanel.tsx

@@ -150,7 +150,7 @@ export function LeftPanel() {
                display: 'flex',
                alignItems: 'center',
                justifyContent: 'center',
-               transition: 'background 0.2s ease',
+               transition: 'background 0.15s linear',
                zIndex: 10,
             }}
             onMouseEnter={() => setHovered(true)}
@@ -166,7 +166,7 @@ export function LeftPanel() {
                   : isHovered
                      ? token.colorPrimary
                      : token.colorBorder,
-               transition: 'background 0.2s ease',
+               transition: 'background 0.15s linear',
             }} />
          </div>
 

src/pages/home/components/ModelSelector.tsx

@@ -68,7 +68,7 @@ function ModelItem({ model, isSelected, onSelect }: ModelItemProps) {
                 alignItems: 'center',
                 justifyContent: 'space-between',
                 gap: 8,
-                transition: 'background 0.15s ease, border-color 0.15s ease, opacity 0.15s ease',
+                transition: 'background 0.15s linear, border-color 0.15s linear, opacity 0.15s linear',
             }}
         >
             <Text

src/pages/settings/SettingsPage.tsx

@@ -5,14 +5,17 @@
 //   - 通过 open/onClose props 控制显隐，不使用路由（避免主页面被卸载）
 //   - Modal 居中弹出 + 遮罩层，首页内容始终保持挂载不动
 //   - destroyOnHidden → 关闭即销毁 DOM，不堆内存
-//   - 仅可通过标题栏 X 按钮关闭（mask 不可关闭、ESC 禁用）
+//   - Esc 键可关闭（跨平台统一）
+//   - macOS：关闭按钮移至标题左侧（遵循 macOS HIG）
 //
 // 对应 QT 原版：设置窗口为独立窗口叠加在主窗口之上，主窗口不销毁
 // ============================================================
 
+import { useCallback } from 'react';
 import { Modal } from 'antd';
-import { SettingOutlined } from '@ant-design/icons';
+import { SettingOutlined, CloseOutlined } from '@ant-design/icons';
 import { useAppContext } from '@/contexts/app-context';
+import { isMacOS } from '@/utils/platform';
 import { ThemeSetting } from './blocks/ThemeSetting';
 import { StoragePathSetting } from './blocks/StoragePathSetting';
 import { SystemInfoSetting } from './blocks/SystemInfoSetting';
@@ -26,18 +29,31 @@ interface SettingsPageProps {
 
 export function SettingsPage({ open, onClose }: SettingsPageProps) {
    const { edition } = useAppContext();
+   const isMac = isMacOS();
+
+   // 关闭后移除焦点，避免跑到导航栏设置按钮上
+   const handleAfterClose = useCallback(() => {
+      (document.activeElement as HTMLElement)?.blur();
+   }, []);
 
    return (
       <Modal
          open={open}
          width={480}
          onCancel={onClose}
+         afterClose={handleAfterClose}
          destroyOnHidden={true}
          mask={{ closable: false }}
-         keyboard={false}
+         closable={!isMac}
          footer={null}
          title={
             <span className="flex items-center gap-2">
+               {isMac && (
+                  <CloseOutlined
+                     onClick={onClose}
+                     className="cursor-pointer text-gray-400 hover:text-gray-600 dark:hover:text-gray-300 transition-colors"
+                  />
+               )}
                <SettingOutlined />
                设置
             </span>

src/theme/globals.css

@@ -168,8 +168,125 @@ body {
    background-color: var(--color-bg-base);
    min-height: 100vh;
    transition:
-      background-color 0.3s ease,
+      background-color 0.15s linear,
-      color 0.3s ease;
+      color 0.15s linear;
+}
+
+/* ============================================================
+ * View Transitions API — GPU 合成器驱动的主题切换动画
+ * 替代 80+ 个独立 CSS 过渡，单次 cross-fade 消除 Electron 卡顿。
+ * 仅在 Chromium 111+（Electron 28+）生效，其他浏览器回退 CSS 过渡。
+ * ============================================================ */
+
+::view-transition-old(root),
+::view-transition-new(root) {
+   animation-duration: 0.15s;
+   animation-timing-function: linear;
+}
+
+/* ============================================================
+ * 主题切换过渡 — 精准覆盖大面积视觉容器，避免 * 全局选择器
+ * 在 Electron 中为数千个 DOM 节点同时启动过渡造成卡顿。
+ *
+ * 策略：
+ *   1. 容器/布局组件（Card / Modal / Layout / Drawer 等）
+ *   2. 表格 & 列表（Table / List / Timeline）
+ *   3. 表单控件（Input / Select / Picker）
+ *   4. 导航 & 标签（Menu / Tabs / Tag / Breadcrumb）
+ *   5. 反馈 & 展示（Alert / Empty / Result / Statistic / Skeleton）
+ *
+ * 不覆盖交互组件自有 transition（Button / Switch / Slider 等
+ * 均使用 transition: all，特异性更高不受影响）。
+ * ============================================================ */
+
+/* —— 布局 & 容器 —— */
+body,
+.ant-layout,
+.ant-layout-header,
+.ant-layout-sider,
+.ant-layout-content,
+.ant-card,
+.ant-card-head,
+.ant-card-body,
+.ant-card-actions,
+.ant-modal-content,
+.ant-modal-header,
+.ant-modal-body,
+.ant-modal-footer,
+.ant-drawer-content,
+.ant-drawer-header,
+.ant-drawer-body,
+.ant-drawer-footer,
+
+/* —— 表格 & 列表 —— */
+.ant-table,
+.ant-table-thead > tr > th,
+.ant-table-tbody > tr > td,
+.ant-table-tbody > tr:hover > td,
+.ant-list,
+.ant-list-item,
+.ant-timeline-item,
+.ant-transfer-list,
+.ant-tree-node-content-wrapper,
+
+/* —— 表单控件 —— */
+.ant-input,
+.ant-input-affix-wrapper,
+.ant-select-selector,
+.ant-select-dropdown,
+.ant-picker,
+.ant-picker-input,
+.ant-picker-dropdown,
+.ant-picker-panel-container,
+.ant-input-number,
+.ant-input-number-input,
+.ant-radio-button-wrapper,
+.ant-radio-group,
+.ant-checkbox-wrapper,
+.ant-segmented,
+.ant-segmented-item,
+.ant-upload-drag,
+.ant-upload-list-item,
+
+/* —— 导航 & 标签 —— */
+.ant-menu,
+.ant-menu-item,
+.ant-menu-submenu-title,
+.ant-tabs-nav,
+.ant-tabs-nav-list,
+.ant-tabs-tab,
+.ant-tabs-content,
+.ant-tag,
+.ant-breadcrumb,
+.ant-pagination-item,
+.ant-dropdown-menu,
+
+/* —— 反馈 & 展示 —— */
+.ant-alert,
+.ant-empty,
+.ant-result,
+.ant-statistic,
+.ant-statistic-content,
+.ant-badge,
+.ant-avatar,
+.ant-divider,
+.ant-skeleton,
+.ant-skeleton-input,
+.ant-skeleton-button,
+.ant-notification-notice,
+.ant-message-notice-content,
+.ant-popover-inner,
+.ant-tooltip-inner,
+.ant-collapse,
+.ant-collapse-item,
+.ant-collapse-header,
+.ant-collapse-content-box,
+.ant-descriptions-item-container {
+   transition:
+      color 0.15s linear,
+      background-color 0.15s linear,
+      border-color 0.15s linear,
+      box-shadow 0.15s linear;
 }
 
 #root {