fix: 修复主题切换后首页状态重置 + 首页 UX 优化 + 文档同步

## 根因
  设置页 `navigate('/settings')` 导致 React Router `/*` 的 index
  路由不匹配，HomePage 被卸载重挂载，所有 useState 回到默认值。

  ## 修复（6 文件）
  - event-bus.ts: 新增 OPEN_SETTINGS 事件
  - nav-config.ts: 设置按钮 action: 'navigate' → 'button'，去路由化
  - NavBar.tsx: button case 中 emit(OPEN_SETTINGS)
  - SettingsPage.tsx: 去路由化，改为 Modal 居中叠加 + open/onClose props，
    使用 antd 6.x 正确 API destroyOnHidden（非废弃的 destroyOnClose），
    mask={{ closable: false }} + keyboard={false} 仅允许 X 按钮关闭
  - router/index.tsx: 移除 SettingsPage 渲染
  - App.tsx: 添加 SettingsPage Modal，事件驱动（与 LoginPage 模式一致）

  ## UX 优化（2 文件）
  - HomeContent.tsx: 右侧分隔条移除多余 marginLeft，左右视觉对称
  - BannerCarousel.tsx: 新增关闭按钮，session 级别 useState 隐藏，
    不做 localStorage 持久化，确保每次启动重新展示

  ## 架构原则
  确立 QT 多窗口模型 → Web 映射：叠加层走 Modal/Drawer + 事件总线，
  主页面不卸载；真正的视图切换才用 React Router。

  ## 文档同步
  - TODO.md: 移除已完成项详细记录，精简为未完成待办
  - WORKLOG.md: 追加 2026-06-07 完整工作日志
  - PROJECT.md: 更新路由/叠加层架构说明
  - CHANGELOG.md: 追加 v0.0.13 条目
  - ARCHITECTURE.md: 更新日期 + 新增叠加层模式章节

.codegraph/daemon.pid

@@ -1,6 +1,6 @@
 {
-  "pid": 145380,
+  "pid": 384720,
   "version": "0.9.9",
   "socketPath": "\\\\.\\pipe\\codegraph-aef859f0205bacea",
-  "startedAt": 1780622650728
+  "startedAt": 1780763058452
 }

ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # 船长 · HeiXiu — 前端架构文档
 
-> 最后更新：2026-06-03
+> 最后更新：2026-06-07
 
 ## 目录结构
 
@@ -156,7 +156,23 @@ NavBar / 设置页 → AppProvider.logout()
 
 - 纯发布-订阅，不依赖任何框架
 - 用于跨模块解耦通信（如 axios 拦截器无法直接用 React Context）
-- 预定义事件：`AUTH_REQUIRED` / `SHOW_LOGIN` / `LOGIN_SUCCESS` / `LOGOUT`
+- 预定义事件：`AUTH_REQUIRED` / `SHOW_LOGIN` / `LOGIN_SUCCESS` / `LOGOUT` / `TASK_SUBMITTED` / `OPEN_SETTINGS`
+
+### 页面叠加层模式（QT 多窗口模型映射）
+
+本项目是 Python QT 桌面应用的 Web 重构版。QT 应用以"新开窗口"为常态，原窗口不因新窗口打开而销毁。Web 端对应原则：
+
+| QT 原版 | Web 对应 | 实现方式 |
+|---------|---------|---------|
+| 新开窗口叠加在主窗口之上 | Modal / Drawer | 事件总线驱动，主页面不卸载 |
+| Tab 切换 / 视图替换 | React Router | 跨页状态放 Provider 或 localStorage |
+
+**当前叠加层**：
+- LoginPage — Modal，事件总线 `SHOW_LOGIN` / `AUTH_REQUIRED` 触发
+- SettingsPage — Modal，事件总线 `OPEN_SETTINGS` 触发
+- AnnouncementDrawer — Drawer，NavBar 内部 state 控制
+
+**反模式警告**：叠加层绝不应通过路由跳转实现。`navigate('/xxx')` + `useLocation` 判断显隐会导致原有页面卸载，丢失所有组件状态。
 
 ### API 模块规范
 

CHANGELOG.md

@@ -4,6 +4,15 @@
 
 ---
 
+## 0.0.13（2026-06-07）
+
+- 修复主题切换后首页状态重置问题：设置页去路由化，改为事件总线驱动的 Modal 叠加
+- 首页三栏分隔条视觉对齐：移除右侧多余 margin，左右完全对称
+- 轮播图新增关闭按钮：session 级别隐藏，每次启动重新展示
+- 确立 QT 多窗口模型 → Web 架构映射原则：叠加层走 Modal/Drawer + 事件总线，不走路由
+
+---
+
 ## 0.0.12（2026-06-04）
 
 - 重构更新检查流程：无更新不再抛异常，PreCheck → 直接 IPC 通知

PROJECT.md

@@ -46,10 +46,11 @@
 
    4. 窗口间通信统一通过主进程转发（或使用 MessagePort 等 Electron 支持的机制），保持窗口独立性。
 
-- 路由与导航：主窗口为 单页应用，使用 React Router v7+ 管理页面切换，支持嵌套路由。
+- 路由与导航：主窗口为单页应用，使用 React Router v7+ 管理页面切换。**遵循 QT 多窗口模型映射原则**：
+  - 叠加层（设置、公告、素材库等）→ Modal/Drawer + 事件总线驱动，主页面不卸载
+  - 页面跳转（真正的视图切换）→ React Router，需跨页保持的状态放 Provider 或 localStorage
 
-- 辅助窗口（设置、预览、导入导出等）为独立 BrowserWindow，加载独立的 HTML 入口（可根据路由参数或 windowId 决定内部路由），不与主窗口共享
+- 辅助窗口（设置、预览、导入导出等）以 Modal/Drawer 叠加在主窗口之上，不与主窗口共享 DOM，但保持在同一个 React 组件树中以确保状态一致性。
-  DOM。
 
 # 目录结构
 
@@ -175,6 +176,36 @@
 
 - 脱敏：shared/utils/sanitize.ts 在日志写入前自动处理 ID（哈希）、邮箱/手机/名称/Token 等字段。
 
+# 安全与认证
+
+## Token 加密存储
+
+- `access_token` 和 `refresh_token` 通过 Electron `safeStorage` API 加密存储，不落明文：
+  - macOS → Keychain
+  - Windows → DPAPI
+  - Linux → libsecret
+- 实现文件：
+  - `electron/main/safe-storage-ipc.ts` — 主进程加密/解密 IPC 处理（`BIDIRECTIONAL.SAFESTORAGE_ENCRYPT / DECRYPT`）
+  - `src/utils/safe-storage.ts` — 渲染进程桥接层（`initSafeStore / getSafeStore / setSafeStore / clearSafeStore`）
+  - `src/services/request.ts` — token 存取通过 `getSafeStore / setSafeStore`，无需感知加密细节
+  - `src/services/auth-token.ts` — refresh_token 同理通过 safeStorage 存取
+
+## 双 Token 机制
+
+- `access_token`（短效）+ `refresh_token`（长效），登录成功同时下发
+- 请求拦截器自动附加 `Authorization: Bearer <access_token>`
+- 401 响应 → 双重校验（HTTP `status` + 业务 `data.code`）→ 仅 `code === 401` 时触发刷新
+- 刷新期间并发请求排队（`failedQueue`），刷新完成后批量重试
+- refresh 接口自身 401 直接拒绝（防死循环），login 接口 401 穿透透传后端 `message`
+- 启动时 `refresh_token` 静默续期（自动登录），失败仅清除标记不影响用户名回填
+- 登录/退出通过事件总线解耦（`LOGIN_SUCCESS` / `LOGOUT` / `AUTH_REQUIRED`）
+
+## 日志脱敏
+
+- `shared/utils/sanitize.ts` 在日志写入前自动脱敏处理
+- 覆盖字段：用户 ID（SHA256 哈希）、邮箱（`***@domain`）、手机号（掩码）、用户名称、Token（截断）
+- 主进程 `electron/main/logger.ts` 和渲染进程 `src/utils/logger.ts` 均写入前调用 `sanitizeLogEntry()`
+
 # 样式与主题
 
 - 优先使用 Tailwind 工具类 完成布局与常规样式，自定义设计令牌应映射为 Tailwind 扩展（在 tailwind.config.ts 中配置
@@ -240,6 +271,17 @@
 | `UpdateSetting` | `src/pages/settings/UpdateSetting.tsx` | 设置页更新区块（含"查看详情"弹窗） |
 | `server.py` | `test-server/server.py` | 本地测试服务器，扫描 release/ 目录，语义版本排序 |
 
+## 增量更新（差分下载）
+
+- `package.json` 配置 `"differentialPackage": true`，electron-builder 打包时自动生成 `.exe.blockmap` 文件
+- 自定义 Provider 模式：`HeiXiuNsisUpdater extends NsisUpdater` / `HeiXiuMacUpdater extends MacUpdater` / `HeiXiuAppImageUpdater extends AppImageUpdater`
+- 三平台 Updater 均覆盖 `getUpdateInfoAndProvider()` 注入 `HeiXiuProvider`（自定义 API 版本检查），差分下载由 electron-updater 父类原生处理
+- blockmap 文件流程：
+  - `scripts/generate-update-info.mjs` — 扫描 blockmap 文件，写 `blockmap.url` + `blockmap.size` 到 `update-info.json`
+  - `scripts/upload-oss.mjs` — 安装包 + blockmap 文件一并上传 OSS（支持 Node.js 直传和 ossutil 两种模式）
+  - `scripts/publish-release.mjs` — 通过 `--blockmap-url` 参数将 blockmap 信息发布到后端 API
+- 效果：日常更新仅下载变更区块，预计节省 60%~90% 流量
+
 ## 环境变量加载机制（主进程）
 
 加载顺序（后者覆盖前者，OS 环境变量始终优先）：

TODO.md

@@ -1,49 +1,6 @@
 # TODO — 船长·HeiXiu 待办与优化清单
 
-> 最后更新：2026-06-03
+> 最后更新：2026-06-07
-
----
-
-## 🔴 安全加固（优先级高）
-
-### 1. 敏感数据加密存储
-
-当前所有敏感数据存储在 `localStorage` 明文/Base64：
-
-| 数据               | 现状        | 目标方案                                   |
-|------------------|-----------|----------------------------------------|
-| `access_token`   | 明文        | Electron `safeStorage.encryptString()` |
-| `refresh_token`  | 明文        | Electron `safeStorage.encryptString()` |
-| `passwordBase64` | Base64 编码 | 移除密码存储，仅靠 refresh_token 自动登录           |
-
-**方案 A（推荐）**：使用 Electron `safeStorage` API
-
-- macOS → Keychain
-- Windows → DPAPI
-- Linux → libsecret
-
-```ts
-// preload.ts 暴露安全方法
-contextBridge.exposeInMainWorld('safeStorage', {
-    encrypt: (plain: string) => ipcRenderer.invoke('safe-storage:encrypt', plain),
-    decrypt: (encrypted: Buffer) => ipcRenderer.invoke('safe-storage:decrypt', encrypted),
-});
-
-// 替代现有 setToken / setStoredRefreshToken
-// 渲染进程不再直接操作 localStorage
-```
-
-**方案 B**：敏感操作下沉到主进程
-
-- `access_token` / `refresh_token` 由主进程管理
-- 渲染进程通过 IPC 发起请求时由主进程追加 Token
-- 渲染进程永不持有明文 Token
-
-### 2. 密码存储策略调整
-
-- [ ] "记住密码" → 仅回填用户名，不再存储密码（已完成）
-- [ ] 清理 `StoredAuth.passwordBase64` 字段
-- [ ] "自动登录" 完全依赖 `refresh_token` 静默续期
 
 ---
 
@@ -87,54 +44,6 @@ contextBridge.exposeInMainWorld('safeStorage', {
 - [ ] 单元测试覆盖（Vitest）
 - [ ] Bundle 体积分析优化（rollup-plugin-visualizer 已有，定期检查）
 
-### 增量更新改造
-
-当前状态：
-
-- `electron-builder` 已配置 `"differential": true`，打包时已生成 `.exe.blockmap` 文件 ✅
-- `electron/main/updater.ts` 为**手写全量下载**（`net.request`），未使用 `electron-updater` npm 包 ❌
-- blockmap 文件生成了但从未被消费，每次更新都是完整下载
-
-目标方案 — 自定义 Provider + electron-updater：
-
-```ts
-// electron/main/updater-v2.ts
-import { autoUpdater } from 'electron-updater';
-import { Provider } from 'electron-updater/out/providers/Provider';
-
-class HeiXiuProvider extends Provider<UpdateInfo> {
-  // 版本检查 → 走自定义 API（保留灰度/强更控制）
-  async getLatestVersion(): Promise<UpdateInfo> {
-    const res = await fetch(`${API_BASE}/api/v1/update/check?...`);
-    const data = await res.json();
-    return {
-      version: data.latestVersion,
-      files: [{
-        url: data.downloadUrl,
-        sha512: data.sha512,
-        size: data.fileSize,
-        blockMapSize: data.blockMapSize,  // 后端新增字段
-      }],
-      path: data.downloadUrl,
-      sha512: data.sha512,
-      releaseDate: data.releaseDate,
-    };
-  }
-}
-```
-
-改造内容：
-
-- [ ] 安装 `electron-updater` npm 包
-- [ ] 重写 `electron/main/updater.ts` 为自定义 Provider 模式
-- [ ] 发布脚本 `upload-oss.mjs` 增加 blockmap 文件上传
-- [ ] `generate-update-info.mjs` 增加 blockmap 字段（`blockMapUrl`、`blockMapSize`）
-- [ ] 后端 API `/api/v1/update/check` 响应增加 `blockMapUrl`、`blockMapSize` 字段
-- [ ] 后端 `releases` 表增加 `blockmap_url`、`blockmap_size` 列
-- [ ] OSS 上传每次版本需同时上传 `.exe` + `.exe.blockmap` 两个文件
-
-增量效果预估：日常更新下载量从完整安装包 → 仅变化的块（预计节省 60%~90% 流量）。
-
 ### 代码质量
 
 - [ ] 移除未使用的 `shared/` 类型和常量
@@ -153,9 +62,10 @@ class HeiXiuProvider extends Provider<UpdateInfo> {
 ## ⚠️ 已知技术债务
 
 | 问题              | 说明                                    | 影响               |
-|-----------------|---------------------------------------|----------------|
+|-----------------|---------------------------------------|------------------|
 | localStorage 依赖 | 所有持久化数据依赖 localStorage                | 清理浏览器数据会丢失所有配置   |
 | IPC 监听器         | useUpdater 已改为单例，其他 IPC hook 可能也有类似问题 | 长期运行可能内存泄漏       |
+| ~~主题切换状态重置~~      | ✅ 已修复 — 根因：设置页 `navigate('/settings')` 导致路由 `/*` 仅匹配 index，HomePage 被卸载重挂载。修复：SettingsPage 改为事件总线驱动的 Modal 居中叠加，不走路由 | ~~用户体验差~~ |
 | `test.py`       | 仓库根目录残留测试文件                           | 无实际作用，应清理        |
 | `null` 文件       | 仓库根目录名为 null 的文件                      | 构建产物或误操作残留       |
 
@@ -163,6 +73,7 @@ class HeiXiuProvider extends Provider<UpdateInfo> {
 
 ## 📋 下次开发计划
 
-1. **safeStorage 加密改造**（安全加固 #1）
+1. **合规素材库页面**（功能待完善 — 按 QT 原版设计，以 Modal/Drawer 叠加而非路由跳转实现）
-2. **合规素材库页面**（功能待完善 Route 页面）
+2. **各页面 nav 导航补齐**（后续页面优先使用叠加模式，遵循 QT 多窗口模型 → 见 WORKLOG 2026-06-07）
-3. **各页面 nav 导航补齐**
+3. **leftWidth / rightWidth / taskPage 加 localStorage 持久化**（UX 优化：刷新页面后保持用户偏好）
+4. **轮播图关闭按钮状态优化**（当前为 session 级别 useState，可考虑加 localStorage 记录关闭时间戳，超过 N 天再显示）

src/App.tsx

@@ -3,6 +3,7 @@ import { HashRouter } from 'react-router-dom';
 
 import { useAppContext } from './contexts/app-context';
 import { LoginPage } from './pages/login';
+import { SettingsPage } from './pages/settings';
 import { on, off, EVENTS } from './utils/event-bus';
 import { AppRoutes } from './router';
 
@@ -12,7 +13,12 @@ import { AppRoutes } from './router';
  * 层级：
  *   HashRouter
  *     ├── LoginPage（Modal 弹层，事件总线驱动）
- *     ├── AppRoutes（页面路由 + SettingsPage Drawer 叠加）
+ *     ├── SettingsPage（Modal 居中叠加，事件总线驱动 — 对应 QT 原版设置窗口）
+ *     ├── AppRoutes（页面路由）
+ *
+ * 设计原则（对应 QT 原版多窗口模型）：
+ *   - 叠加层（设置、公告等）→ Modal/Drawer + 事件总线，主页面不卸载
+ *   - 页面跳转 → React Router，需要跨页保持的状态放 Provider 或 localStorage
  */
 function App() {
    const { isLoggedIn } = useAppContext();
@@ -42,12 +48,25 @@ function App() {
       setLoginOpen(false);
    }, []);
 
+   // 设置 Drawer 状态
+   const [settingsOpen, setSettingsOpen] = useState(false);
+
+   // 监听打开设置 Drawer
+   useEffect(() => {
+      const handler = () => setSettingsOpen(true);
+      on(EVENTS.OPEN_SETTINGS, handler);
+      return () => { off(EVENTS.OPEN_SETTINGS, handler); };
+   }, []);
+
    return (
       <HashRouter>
          {/* 登录 Modal — 可关闭，关闭后主页可操作 */}
          <LoginPage open={loginOpen && !isLoggedIn} onClose={handleLoginClose} />
 
-         {/* 页面路由 + SettingsPage Drawer 叠加 */}
+         {/* 设置 Modal — 事件驱动，居中叠加，主页面始终挂载（对应 QT 原版独立设置窗口） */}
+         <SettingsPage open={settingsOpen} onClose={() => setSettingsOpen(false)} />
+
+         {/* 页面路由 */}
          <AppRoutes />
       </HashRouter>
    );

src/components/navbar/NavBar.tsx

@@ -79,6 +79,8 @@ export function NavBar() {
             case 'button':
                if (item.key === 'logout') {
                    logout();
+               } else if (item.key === 'settings') {
+                   emit(EVENTS.OPEN_SETTINGS);
                }
                break;
 

src/components/navbar/nav-config.ts

@@ -99,8 +99,7 @@ const personalRight: NavItemConfig[] = [
       key: 'settings',
       label: '设置',
       iconSrc: settingsSvg,
-      action: 'navigate',
+      action: 'button',
-      target: '/settings',
       position: 'right',
    },
    {
@@ -168,8 +167,7 @@ const enterpriseRight: NavItemConfig[] = [
       key: 'settings',
       label: '设置',
       iconSrc: settingsSvg,
-      action: 'navigate',
+      action: 'button',
-      target: '/settings',
       position: 'right',
    },
    {

src/pages/home/HomeContent.tsx

@@ -239,10 +239,7 @@ export function HomeContent() {
             {/* 右分隔条 */}
             <div
                onMouseDown={handleDividerMouseDown('right')}
-               style={{
+               style={dividerStyle('right')}
-                  ...dividerStyle('right'),
-                  marginLeft: 12,
-               }}
                onMouseEnter={() => setHoveredDivider('right')}
                onMouseLeave={() => setHoveredDivider(null)}
             >
@@ -261,7 +258,7 @@ export function HomeContent() {
             </div>
 
             {/* 右列 */}
-            <div style={{ width: rightWidth, overflow: 'hidden', flexShrink: 0, marginLeft: 6 }}>
+            <div style={{ width: rightWidth, overflow: 'hidden', flexShrink: 0 }}>
                <RightPanel />
             </div>
          </div>

src/pages/home/components/BannerCarousel.tsx

@@ -1,10 +1,16 @@
 // ============================================================
 // BannerCarousel — 首页顶部轮播图
 // 使用 useBannerList() Hook 获取数据，组件仅负责渲染
+//
+// 关闭行为：
+//   - 关闭后当前会话不再显示（组件内 useState 驱动）
+//   - 刷新/重启应用 → state 重置 → 重新展示
+//   - 不做 localStorage 持久化，确保每次启动都可见
 // ============================================================
 
-import { useRef, useMemo } from 'react';
+import { useRef, useMemo, useState } from 'react';
-import { Carousel, Skeleton } from 'antd';
+import { Carousel, Skeleton, Button } from 'antd';
+import { CloseOutlined } from '@ant-design/icons';
 import type { CarouselRef } from 'antd/es/carousel';
 
 import { useBannerList } from '@/hooks/use-api';
@@ -22,6 +28,9 @@ export function BannerCarousel({ className }: BannerCarouselProps) {
    const carouselRef = useRef<CarouselRef>(null);
    const { data: rawBanners, loading } = useBannerList();
 
+   /** 当前会话是否已关闭轮播图（组件卸载即重置，下次启动重新展示） */
+   const [dismissed, setDismissed] = useState(false);
+
    // 过滤 + 排序（纯计算，无副作用）
    const banners = useMemo<Banner[]>(() => {
       if (!rawBanners) return [];
@@ -31,8 +40,8 @@ export function BannerCarousel({ className }: BannerCarouselProps) {
          .sort((a, b) => a.sort_order - b.sort_order);
    }, [rawBanners]);
 
-   // 无数据时不渲染
+   // 用户已关闭或加载完成但无数据 → 不渲染
-   if (!loading && banners.length === 0) {
+   if (dismissed || (!loading && banners.length === 0)) {
       return null;
    }
 
@@ -69,6 +78,35 @@ export function BannerCarousel({ className }: BannerCarouselProps) {
                </div>
             ))}
          </Carousel>
+
+         {/* 关闭按钮 — 右上角悬浮，半透明底色，hover 加深 */}
+         <Button
+            type="text"
+            size="small"
+            icon={<CloseOutlined />}
+            onClick={() => setDismissed(true)}
+            title="关闭轮播图"
+            style={{
+               position: 'absolute',
+               top: 8,
+               right: 8,
+               zIndex: 10,
+               color: '#fff',
+               background: 'rgba(0, 0, 0, 0.35)',
+               borderRadius: 4,
+               width: 24,
+               height: 24,
+               display: 'flex',
+               alignItems: 'center',
+               justifyContent: 'center',
+            }}
+            onMouseEnter={(e) => {
+               (e.currentTarget as HTMLButtonElement).style.background = 'rgba(0, 0, 0, 0.55)';
+            }}
+            onMouseLeave={(e) => {
+               (e.currentTarget as HTMLButtonElement).style.background = 'rgba(0, 0, 0, 0.35)';
+            }}
+         />
       </div>
    );
 }

src/pages/settings/SettingsPage.tsx

@@ -1,39 +1,38 @@
 // ============================================================
-// SettingsPage — 设置页面（路由命中 /settings 时以居中 Modal 叠加展示）
+// SettingsPage — 设置页面（Modal 居中叠加，事件驱动显隐）
 //
 // 核心设计：
-//   - 独立于 <Routes> 之外，通过 useLocation 判断是否渲染
+//   - 通过 open/onClose props 控制显隐，不使用路由（避免主页面被卸载）
-//   - 命中 /settings → Modal 居中弹出，首页内容保持在背景不动
+//   - Modal 居中弹出 + 遮罩层，首页内容始终保持挂载不动
-//   - 关闭 Modal → navigate(-1)，仅可通过 X 按钮关闭
+//   - destroyOnHidden → 关闭即销毁 DOM，不堆内存
-//   - destroyOnClose → 关闭即销毁 DOM，不堆内存
+//   - 仅可通过标题栏 X 按钮关闭（mask 不可关闭、ESC 禁用）
+//
+// 对应 QT 原版：设置窗口为独立窗口叠加在主窗口之上，主窗口不销毁
 // ============================================================
 
-import {Modal} from 'antd';
+import { Modal } from 'antd';
-import {SettingOutlined} from '@ant-design/icons';
+import { SettingOutlined } from '@ant-design/icons';
-import {useLocation, useNavigate} from 'react-router-dom';
+import { useAppContext } from '@/contexts/app-context';
-import {useAppContext} from '@/contexts/app-context';
+import { ThemeSetting } from './ThemeSetting';
-import {ThemeSetting} from './ThemeSetting';
+import { StoragePathSetting } from './StoragePathSetting';
-import {StoragePathSetting} from './StoragePathSetting';
+import { SystemInfoSetting } from './SystemInfoSetting';
-import {SystemInfoSetting} from './SystemInfoSetting';
+import { UpdateSetting } from './UpdateSetting';
-import {UpdateSetting} from './UpdateSetting';
 
-export function SettingsPage() {
+interface SettingsPageProps {
-    const location = useLocation();
+   open: boolean;
-    const navigate = useNavigate();
+   onClose: () => void;
-    const {edition} = useAppContext();
+}
-    const open = location.pathname === '/settings';
+
+export function SettingsPage({ open, onClose }: SettingsPageProps) {
+    const { edition } = useAppContext();
 
     return (
         <Modal
             open={open}
             width={480}
-            onCancel={() => navigate(-1)}
+            onCancel={onClose}
             destroyOnHidden={true}
-            mask={
+            mask={{ closable: false }}
-                {
-                    closable: false
-                }
-            }
             keyboard={false}
             footer={null}
             title={
@@ -42,7 +41,7 @@ export function SettingsPage() {
                     设置
                 </span>
             }
-            styles={{body: {padding: 0, maxHeight: '70vh', overflow: 'auto'}}}
+            styles={{ body: { padding: 0, maxHeight: '70vh', overflow: 'auto' } }}
         >
             <div className="flex flex-col gap-4 p-4">
                 <ThemeSetting />

src/router/index.tsx

@@ -2,25 +2,20 @@
 // AppRoutes — 应用路由配置（由 App.tsx 在 HashRouter 内使用）
 //
 // 核心设计：
-//   - SettingsPage 在 <Routes> 外部，路由命中时以 Drawer 叠加首页
+//   - Settings 等叠加层通过事件总线驱动 Drawer/Modal 展示，不走路由
 //   - 首页始终保持挂载，不会因导航而卸载
 // ============================================================
 
 import { Routes, Route } from 'react-router-dom';
 import { Layout } from '@/components/Layout';
 import { HomePage } from '@/pages/home/HomePage';
-import { SettingsPage } from '@/pages/settings';
 
 export function AppRoutes() {
    return (
-      <>
       <Routes>
          <Route path="/*" element={<Layout />}>
             <Route index element={<HomePage />} />
          </Route>
       </Routes>
-         {/* 独立于 Routes：根据 URL /settings 自动显隐 Drawer */}
-         <SettingsPage />
-      </>
    );
 }

src/utils/event-bus.ts

@@ -71,4 +71,6 @@ export const EVENTS = {
    LOGOUT: 'auth:logout',
    /** 任务提交成功（→ 刷新任务列表） */
    TASK_SUBMITTED: 'task:submitted',
+   /** 打开设置 Drawer（导航栏"设置"按钮点击） */
+   OPEN_SETTINGS: 'settings:open',
 } as const;

vite.config.ts

@@ -74,7 +74,7 @@ export default defineConfig(({mode}) => {
                 // usePolling: true,
                 // interval: 100,
                 // 忽略不需要监听的目录，减少 CPU 占用
-                ignored: ['**/node_modules/**', '**/dist/**', '**/dist-electron/**', '**/release/**', '**/test-server/**'],
+                ignored: ['**/node_modules/**', '**/dist/**', '**/dist-electron/**', '**/release/**', '**/test-server/**', "**/**/*.md"],
             },
             // HMR 配置
             hmr: {