docs: 同步 i18n 移除与存储初始化防覆盖说明

- 移除已废弃的 chrome.i18n / _locales 文档引用
- 补充 UI 文案规范（features.tsx + 组件内中文）
- 记录 RouterProvider / useStorageState 初始化防覆盖机制
- 更新 syncSnapshot、themeSnapshot、restrictedUrls 工具说明

Co-authored-by: LingandRX <LingandRX@users.noreply.github.com>

.github/CODING_STANDARDS.md

@@ -265,12 +265,11 @@ const visibleSet = useMemo(() => new Set<string>(visiblePages), [visiblePages]);
 2. 第三方库（图标、UI 库等）
 3. 业务 Provider / Context
 4. 配置 / 存储
-5. i18n
-6. 本地页面组件
-7. UI 组件
-8. 工具函数 / Hook
-9. 类型
-10. 常量
+5. 本地页面组件
+6. UI 组件
+7. 工具函数 / Hook
+8. 类型
+9. 常量
 
 ```typescript
 // 1. React 核心
@@ -284,19 +283,16 @@ import { useThemeMode } from '@/providers/ThemeModeProvider';
 // 4. 配置 / 存储
 import { FeatureConfig, FEATURES } from '@/config/features';
 import { storageUtil } from '@/utils/chromeStorage';
-// 5. i18n
-import { useTranslation } from 'react-i18next';
-import { normalizeLanguage, SUPPORTED_LANGUAGES } from '@/i18n';
-// 6. 本地组件
+// 5. 本地组件
 import TextMode from './TextMode';
 import { ZONES } from './constants';
-// 7. UI 组件
+// 6. UI 组件
 import SwitchButtonGroup from '@/components/SwitchButtonGroup';
 import { Button } from '@/components/ui/button';
-// 8. 工具函数 / Hook
+// 7. 工具函数 / Hook
 import { cn } from '@/lib/utils';
-import { useLazyTranslation } from '@/utils/useLazyTranslation';
-// 9. 类型
+import { useStorageState } from '@/utils/useStorageState';
+// 8. 类型
 import type { PageType, StorageSchema } from '@/types/storage';
 ```
 
@@ -401,22 +397,22 @@ className={cn(
 
 ## 5. 错误处理
 
-### 5.1 工具函数：结果对象模式
+### 5.1 工具函数：可恢复错误返回可判断结果
 
-工具函数**不抛异常**，返回包含 `hasError` 和 `error` 字段的结果对象：
+可恢复的解析/校验错误应返回可判断的结果，避免工具层直接弹 Toast。确需保留底层异常的函数
+（如 `formatJson` / `minifyJson`）必须在页面 Hook 或 UI 层捕获并转换为用户提示：
 
 ```typescript
-// ✅ 结果对象模式
-export function markdownToHtml(markdown: string): MarkdownToHtmlResult {
+// ✅ 可恢复校验返回错误消息，调用方据此展示 UI
+export function validateJson(text: string): string | null {
+  if (!text.trim()) {
+    return null;
+  }
   try {
-    ...
-    return { html, originalLength, htmlLength, hasError: false };
-  } catch (error) {
-    return {
-      html: '', ...
-      hasError: true,
-      error: error instanceof Error ? error.message : 'Markdown 解析失败',
-    };
+    JSON.parse(text.trim());
+    return null;
+  } catch (e) {
+    return e instanceof SyntaxError ? e.message : 'Invalid JSON';
   }
 }
 ```
@@ -560,7 +556,7 @@ describe('SwitchButtonGroup 组件', () => {
 - 使用 `vi.mock()` 进行模块级 Mock
 - 使用 `vi.fn()` 进行函数级 Mock
 - 使用 `vi.useFakeTimers()` 控制时间
-- **避免重复 mock `vitest.setup.ts` 中已有的内容**（chrome API、i18n、matchMedia 等）
+- **避免重复 mock `vitest.setup.ts` 中已有的内容**（chrome API、matchMedia 等）
 
 ```typescript
 // ✅ 模块级 Mock
@@ -658,7 +654,7 @@ export function useTimestampConverter(): UseTimestampConverterReturn { ... }
 
 ```
 src/utils/useStorageState.ts          — Chrome Storage 状态持久化
-src/utils/useLazyTranslation.ts       — i18n 懒加载
+src/utils/syncSnapshot.ts             — localStorage 快照读取
 src/utils/useContextMenuData.ts       — 右键菜单数据
 src/utils/useDebounce.ts              — 防抖
 src/pages/Timestamp/useTimestampConverter.ts    — 页面级 Hook
@@ -667,47 +663,50 @@ src/pages/StorageCleaner/useStorageCleaner.ts  — 页面级 Hook
 
 ---
 
-## 9. 国际化规范
+## 9. UI 文案规范
 
-### 9.1 翻译键格式
+项目已移除 `chrome.i18n`，所有 UI 文案直接在代码中使用中文。
 
-- 命名空间：`common`（默认）、`features`
-- 翻译键格式：`namespace:key`（如 `features:timestamp.title`）
-- 语言：`zh`（默认）、`en`
+### 9.1 功能元数据
 
-### 9.2 翻译文件结构
-
-```
-i18n/locales/{zh,en}/common.json           — 全局通用翻译
-i18n/locales/{zh,en}/features.json         — 功能模块标题和描述
-i18n/locales/{zh,en}/{功能名}.json         — 各功能独立翻译
-```
-
-### 9.3 使用方式
+功能名称与描述在 `config/features.tsx` 的 `FEATURES` 数组中定义：
 
 ```typescript
-// ✅ 页面组件 — 使用 useLazyTranslation
-import { useLazyTranslation } from '@/utils/useLazyTranslation';
-
-export default function Index() {
-  const { t } = useLazyTranslation('timestamp');
-  return <h1>{t('timestamp:title')}</h1>;
-}
-
-// ✅ 全局组件 — 使用 useTranslation
-import { useTranslation } from 'react-i18next';
-
-export function TopBar() {
-  const { t } = useTranslation(['common', 'features']);
-  return <span>{t('common:settings')}</span>;
+{
+  key: 'timestamp',
+  label: '时间戳转换',
+  description: '日期与时间戳互转',
+  defaultVisible: true,
+  components: { popup: TimestampPage, sidepanel: TimestampPage, tab: TimestampPage },
 }
 ```
 
-### 9.4 添加新翻译
+Dashboard 卡片、TopBar 搜索等功能从此处读取 `label` / `description`。
 
-1. 在 `i18n/locales/{zh,en}/features.json` 添加功能标题和描述
-2. 创建 `i18n/locales/{zh,en}/{功能名}.json` 添加功能专属翻译
-3. 在 `utils/useLazyTranslation.ts` 的 `localeModules` 中注册新命名空间
+### 9.2 页面与组件文案
+
+- 页面标题、按钮、提示信息等直接在 JSX 或 `constants.ts` 中写中文
+- 错误消息可在 Hook 中定义，或使用常量映射
+- Toast 通知使用 `sonner` 的 `toast()`，文案写在调用处或常量中
+
+```typescript
+// ✅ 页面组件 — 直接写中文
+export default function Index() {
+  return <h1 className="font-bold text-sm">时间戳转换</h1>;
+}
+
+// ✅ 常量文件 — 可复用文案
+export const ERROR_MESSAGES = {
+  invalidInput: '输入格式无效',
+  conversionFailed: '转换失败',
+} as const;
+```
+
+### 9.3 添加新功能文案
+
+1. 在 `config/features.tsx` 填写 `label` 和 `description`
+2. 在页面组件、`constants.ts` 或 Hook 中编写 UI 文案
+3. 扩展名称与描述在 `wxt.config.ts` 的 `manifest` 中维护
 
 ---
 
@@ -760,6 +759,18 @@ const [themeMode, setThemeMode, isInitialized] = useStorageState(
 );
 ```
 
+### 10.4 首屏快照与初始化防覆盖
+
+Chrome Storage 读取是异步的。项目通过 `localStorage` 快照（键名 `snapshot/{storageKey}`）提供同步初始值，消除首屏闪烁。
+
+| 模块 | 快照工具 | 防覆盖机制 |
+| ---- | -------- | ---------- |
+| `RouterProvider` | `syncSnapshot.ts` | `canPersistRef`（加载成功后才写入）、`hasUserNavigatedRef`（用户导航后不被 storage 覆盖） |
+| `useStorageState` | `syncSnapshot.ts` | `loadSucceededRef` 或 `userModifiedRef` 为 true 时才写入 |
+| `ThemeModeProvider` | `themeSnapshot.ts` | `hasUserSetMode`（用户切换主题后不被 storage 覆盖） |
+
+新增持久化状态时，应遵循相同模式：同步快照作初始 state → 异步加载 storage → 加载成功或用户修改后才允许写入。
+
 ---
 
 ## 11. 页面开发规范
@@ -842,24 +853,21 @@ export default function DashboardPage() { ... }
 
 #### 组件职责
 
-`index.tsx` 只负责三件事：
+`index.tsx` 只负责两件事：
 
-1. **获取翻译函数**（`useI18n`）
-2. **调用业务 Hook** 获取状态和操作方法
-3. **渲染 UI 布局**（纯展示，无业务逻辑）
+1. **调用业务 Hook** 获取状态和操作方法
+2. **渲染 UI 布局**（纯展示，无业务逻辑）
 
 ```typescript
 // ✅ 标准页面入口模板
-import { useI18n } from '@/utils/chromeI18n';
 import { useFeatureName } from './useFeatureName';
 
 export default function Index() {
-  const { t } = useI18n('featureName');
   const { state, actions } = useFeatureName();
 
   return (
     <div className="p-4 w-full flex flex-col space-y-4 select-none">
-      {/* 纯 UI 渲染 */}
+      {/* 纯 UI 渲染，文案直接写中文 */}
     </div>
   );
 }
@@ -903,25 +911,22 @@ export function useTimestampConverter(): UseTimestampConverterReturn {
 
 ```typescript
 export function useFeatureName(): UseFeatureNameReturn {
-  // 1. i18n
-  const { t } = useI18n('featureName');
-
-  // 2. 基础 state（useState）
+  // 1. 基础 state（useState）
   const [mode, setMode] = useState<Mode>('default');
   const [input, setInput] = useState('');
 
-  // 3. 持久化 state（useStorageState）
+  // 2. 持久化 state（useStorageState）
   const [pageMode, setPageMode] = useStorageState('feature/pageMode', 'default', isValidMode);
 
-  // 4. 衍生数据（useMemo）— 响应式计算管线
+  // 3. 衍生数据（useMemo）— 响应式计算管线
   const result = useMemo(() => {
     // 自动计算，无需手动点击"转换"按钮
   }, [input, mode]);
 
-  // 5. 事件处理（useCallback）
+  // 4. 事件处理（useCallback）
   const handleAction = useCallback(() => { ... }, [deps]);
 
-  // 6. 副作用（useEffect）— 防抖、初始化、清理
+  // 5. 副作用（useEffect）— 防抖、初始化、清理
   useEffect(() => { ... }, [deps]);
 
   // 7. 右键菜单数据（页面需要时）
@@ -991,7 +996,7 @@ interface ResultViewProps extends React.HTMLAttributes<HTMLDivElement> {
 // ✅ 使用 React.memo + displayName
 const ResultView = React.memo(
   ({ result, mode, showEmptyPlaceholder = false, className, ...props }: ResultViewProps) => {
-    const { t } = useI18n('featureName');
+    // 文案直接写中文或使用 constants
     // ...
   },
 );
@@ -1001,7 +1006,7 @@ export default ResultView;
 
 #### 子组件内可以使用 Hook
 
-子组件可以独立调用 `useI18n`、`useSnackbar` 等全局 Hook，**不需要**通过 props 从父组件传递翻译函数或 toast 方法。
+子组件可以独立调用 `useRouter`、`useThemeMode`、`toast` 等全局 Hook/API，**不需要**通过 props 从父组件传递。
 
 ---
 
@@ -1038,7 +1043,6 @@ const isValidMode = (val: unknown): val is PageMode =>
   typeof val === 'string' && (VALID_MODES as readonly string[]).includes(val);
 
 export default function Index() {
-  const { t } = useI18n('featureName');
   const [pageMode, setPageMode] = useStorageState('feature/pageMode', 'modeA', isValidMode);
 
   return (
@@ -1046,8 +1050,8 @@ export default function Index() {
       <SwitchButtonGroup
         value={pageMode}
         options={[
-          { value: 'modeA', label: t('feature:modeA') },
-          { value: 'modeB', label: t('feature:modeB') },
+          { value: 'modeA', label: '模式 A' },
+          { value: 'modeB', label: '模式 B' },
         ]}
         onChange={(v: PageMode) => setPageMode(v)}
         size="small"
@@ -1078,12 +1082,12 @@ export default function Index() {
 新增功能页面时，逐项确认：
 
 1. ✅ 在 `types/storage.d.ts` 添加 `PageType` 联合类型
-2. ✅ 在 `config/features.tsx` 注册 `FEATURES` 配置（key、labelKey、icon、三种渲染模式组件）
+2. ✅ 在 `config/features.tsx` 注册 `FEATURES` 配置（key、label、description、icon、三种渲染模式组件）
 3. ✅ 创建页面目录，使用 `Index` 作为组件名
 4. ✅ 业务逻辑提取到 `useXxx.ts` Hook（index.tsx 不超过 150 行）
 5. ✅ 需要持久化的 UI 状态使用 `useStorageState`
 6. ✅ 常量 ≥3 个时提取到 `constants.ts`
-7. ✅ 在 `i18n/locales/{zh,en}/` 添加翻译
+7. ✅ 在页面组件或 `constants.ts` 中编写 UI 文案
 8. ✅ 创建 `__tests__/index.test.tsx` 测试文件
 9. ✅ 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
 10. ✅ 运行 `npm run lint && npm run typecheck && npm run test` 全部通过
@@ -1103,8 +1107,8 @@ export default function Index() {
 | `src/hooks/`         | 自定义 React Hooks                                           |
 | `src/utils/`         | 工具函数与服务抽象                                           |
 | `src/types/`         | TypeScript 类型声明                                          |
-| `src/lib/`           | 通用工具函数（cn、utils）                                    |
-| `public/`            | 静态资源                                                     |
+| `src/lib/`           | 通用工具函数与生成器库（cn、utils、generators）              |
+| `public/`            | 静态资源（图标等）                                           |
 
 ---
 

.github/copilot-instructions.md

@@ -1,141 +0,0 @@
-# Copilot 指令
-
-基于 WXT 框架的浏览器扩展项目（React 19 + TypeScript），为开发者和测试人员提供效率工具：时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、Markdown 等。
-
-## 核心命令
-
-```bash
-npm run dev              # Chrome 开发模式（支持 HMR）
-npm run dev:firefox      # Firefox 开发模式
-npm run build            # Chrome 生产构建
-npm run build:firefox    # Firefox 生产构建
-npm run zip              # 打包 Chrome 扩展（.output/*.zip）
-npm run zip:firefox      # 打包 Firefox 扩展
-npm run lint             # ESLint 检查（--max-warnings=0）
-npm run typecheck        # TypeScript 类型检查（tsc --noEmit）
-npm run test             # 运行全部单元测试（vitest run）
-npm run test:watch       # Vitest 监视模式
-npm run test:coverage    # 带覆盖率的测试
-```
-
-运行单个测试文件：`npx vitest run path/to/file.test.ts`
-
-修改 `package.json` 后需运行 `npm install`（会自动触发 `postinstall` → `wxt prepare` 重新生成 `.wxt/` 类型声明）。
-
-## CI 流水线（GitHub Actions）
-
-严格顺序门控，任一步骤失败则终止：
-
-1. **setup** — 安装依赖，缓存 `node_modules`
-2. **lint**、**typecheck**、**test** — 三者并行运行，全部通过才继续
-3. **build** — Chrome + Firefox 矩阵构建（仅当步骤 2 全部通过时执行）
-
-Pre-commit 钩子（`.husky/pre-commit` → `lint-staged`）：
-
-1. 代码文件（`*.{ts,tsx,js,jsx,mjs}`）：运行 `eslint --fix --max-warnings=0`
-2. 同一代码文件：运行 `prettier --write`
-3. 其他文件（`*.{json,css,scss,md}`）：运行 `prettier --write`
-
-## 项目架构
-
-### 路由（不使用 React Router）
-
-路由完全通过 `config/features.tsx` 中的 `FEATURES` 数组管理。每个功能定义一个 `key`（类型为 `types/storage.d.ts` 中的 `PageType`）和三个懒加载组件，分别对应 `popup`、`sidepanel`、`tab` 三种渲染模式。`providers/RouterProvider.tsx` 中的 `RouterProvider` 根据存储状态渲染当前页面。
-
-存在三套独立的路由作用域：`app/popupRoute`、`app/sidepanelRoute`、`app/tabRoute`，各自维护独立的可见页面列表和页面排序。
-
-### 存储
-
-所有 Chrome Storage 键必须在 `types/storage.d.ts` 的 `StorageSchema` 中声明，键名使用 kebab-case 格式（如 `app/currentRoute`）。使用 `utils/chromeStorage.ts` 中的类型安全封装（`storageUtil.get/set/remove`）。
-
-Router 同时使用 `chrome.storage.local` 持久化和 `localStorage` 快照来消除首屏闪烁。
-
-### 扩展通信
-
-使用 `@webext-core/messaging`。通信协议在 `utils/messages.ts` 中通过 `ProtocolMap` 定义。使用该模块导出的 `sendMessage` / `onMessage`，不要直接使用原生 `chrome.runtime.sendMessage`。
-
-### 页面组件模式
-
-功能页面遵循 **UI + Hook 分离** 模式，详见 [CODING_STANDARDS.md § 11](./CODING_STANDARDS.md#11-页面开发规范)：
-
-```
-pages/FeatureName/
-├── index.tsx              # UI 组件（纯展示，使用 shadcn/ui 组件）
-├── useFeatureName.ts      # 业务逻辑 Hook（状态管理 + 转换逻辑）
-└── constants.ts           # 常量定义（可选）
-```
-
-- 页面组件调用 `useI18n('featureName')` 获取翻译函数
-- Hook 负责所有状态管理，通过返回值暴露给页面
-- 子组件可进一步拆分（如 `LiveClock.tsx`、`ResultView.tsx`）
-
-### 新功能开发清单
-
-1. 在 `types/storage.d.ts` 的 `PageType` 联合类型中添加新成员
-2. 在 `config/features.tsx` 的 `FEATURES` 数组中添加配置（key、翻译键、图标、三种渲染模式组件）
-3. 在 `pages/` 目录创建页面组件（懒加载）：
-   - `index.tsx` — 使用 `useLazyTranslation` 的 UI 组件
-   - `useFeatureName.ts` — 业务逻辑 Hook
-   - `constants.ts` — 常量（可选）
-4. 在 `i18n/locales/{zh,en}/features.json` 添加翻译（复杂功能可新建独立 JSON 文件）
-5. 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
-6. 添加对应的单元测试
-
-## 关键规范
-
-> 完整的代码编写规范详见 [CODING_STANDARDS.md](./CODING_STANDARDS.md)。
-
-### 浏览器 API
-
-始终使用 `wxt/browser` 导出的 `browser` 对象，而非原生 `chrome` API，以确保跨浏览器兼容性。
-
-### 路径别名
-
-`@/` 映射到项目根目录（已在 tsconfig 和 vitest.config 中配置）。跨目录导入使用 `@/` 绝对别名，同目录导入使用 `./` 相对路径。
-
-### UI 组件
-
-- 使用 `components/ui/` 下的 shadcn/ui 组件（button、dialog、select、input 等）
-- 图标：`lucide-react`
-- 样式：Tailwind CSS + `@/lib/utils` 中的 `cn()` 工具函数（clsx + tailwind-merge）
-- 主题：使用 shadcn/ui 语义化 token（`bg-background`、`text-foreground`、`border-border` 等），禁止硬编码颜色
-
-### 代码分割
-
-`wxt.config.ts` 通过 `manualChunksForHtmlOnly()` 自动分组 vendor 依赖（vendor-react、vendor-i18n、vendor-qr、vendor-dnd），无需手动配置。
-
-### 代码风格
-
-- 禁止使用 `any`（测试文件除外）
-- 未使用的变量/参数：使用 `_` 前缀（如 `_unused`）
-- Prettier：100 字符宽、单引号、尾逗号 all、LF 换行
-- ESLint 使用 `typescript-eslint` 的 `projectService: true`
-- 导出模式：页面组件 default export，工具函数/Hook 命名导出，UI 组件 forwardRef + 命名导出
-
-### 测试
-
-- 环境：jsdom
-- 全局变量：`vitest/globals`（describe、it、expect 等无需导入）
-- Setup 文件：`vitest.setup.ts` 自动 mock 以下内容：
-  - `chrome.*` / `browser.*` API（storage、tabs、runtime、cookies 等）
-  - `react-i18next`（返回 key 作为翻译）
-  - `@/utils/useLazyTranslation`（返回 `ns:key` 格式）
-  - `window.matchMedia`
-- 测试文件命名：`__tests__/*.test.{ts,tsx}` 或 `*.test.{ts,tsx}`
-- 使用 `vi.mock()` 进行模块级 mock；避免重复 mock `vitest.setup.ts` 中已有的内容
-- 测试工具：`@testing-library/react` + `@testing-library/user-event`
-
-### 国际化（i18n）
-
-- 命名空间：`common`（默认）、`features`
-- 翻译键格式：`namespace:key`（如 `features:timestamp.title`）
-- 语言：`zh`（默认）、`en`
-- 翻译文件：`i18n/locales/{zh,en}/{common,features}.json` + 各功能独立 JSON 文件
-- 使用 `useLazyTranslation` Hook 加载功能专属翻译
-- 回退策略：缺失的翻译键回退到 `zh`，若仍缺失则返回占位格式 `namespace:key`
-
-### WXT 生成文件
-
-- `.wxt/` 目录由 `postinstall`（`wxt prepare`）自动生成，包含 TypeScript 类型声明和扩展 tsconfig
-- 生产构建输出到 `.output/` 目录
-- `tsconfig.json` 继承自 `./.wxt/tsconfig.json`

AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-WXT 浏览器扩展项目 (React 19 + TypeScript)。提供时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、Markdown、测试数据生成器等测试效率工具。
+WXT 浏览器扩展项目 (React 19 + TypeScript)。提供时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、测试数据生成器等测试效率工具。
 
 ## 核心命令
 
@@ -16,11 +16,33 @@ npm run typecheck        # tsc --noEmit
 npm run test             # vitest run (单次执行)
 npm run test:watch       # vitest 监视模式
 npm run test:coverage    # 带覆盖率的测试
+npx vitest run path/to/file.test.ts   # 运行单个测试文件
+npx wxt prepare          # 重新生成 .wxt/ 类型声明（npm install 时 postinstall 会自动执行）
 ```
 
+修改 `package.json` 或首次克隆仓库后需执行 `npm install`，会自动触发 `postinstall` → `wxt prepare`。
+
 ## 验证流程
 
-详见 [CI 配置](./.github/CI.md)
+详见 [CI 配置](./.github/CI.md)。本地与 CI 的检查层次如下。
+
+### Pre-commit（`.husky/pre-commit`）
+
+1. 后台运行 `tsc --noEmit`（不阻塞提交，结果输出到 stderr）
+2. 前台运行 `lint-staged`：
+   - 代码文件 (`*.{ts,tsx,js,jsx,mjs}`)：`eslint --fix --max-warnings=0`，再 `prettier --write`
+   - 其他文件 (`*.{json,css,scss,md}`)：`prettier --write`
+
+### Pre-push（`.husky/pre-push`）
+
+1. 全项目 `tsc --noEmit`（阻塞推送）
+2. 对本次推送相对 upstream（或 `origin/main`）变更的 `*.{ts,tsx,js,jsx,mjs}` 文件运行 `eslint --max-warnings=0`
+
+### CI（GitHub Actions）
+
+1. `setup` — 安装依赖
+2. 并行 `lint`、`typecheck`（含 `wxt prepare`）、`test`
+3. `build` — Chrome + Firefox 矩阵构建（仅当步骤 2 全部通过）
 
 ## 项目结构
 
@@ -28,6 +50,7 @@ npm run test:coverage    # 带覆盖率的测试
 src/                     # 源代码根目录
   config/features.tsx      # 功能定义（路由 + 元数据的单一事实来源）
   entrypoints/             # 扩展入口点 (popup/, sidepanel/, background.ts, content.ts)
+  layout/                  # 应用壳层布局（TopBar 导航、搜索、主题切换）
   pages/                   # 功能页面组件 (懒加载)
   components/              # 可复用 UI 组件
   components/ui/           # shadcn/ui 基础组件 (button, dialog, select 等)
@@ -35,11 +58,22 @@ src/                   # 源代码根目录
   hooks/                   # 自定义 React Hooks
   utils/                   # 工具函数与服务抽象
   types/                   # TypeScript 类型声明
-  lib/                   # 通用工具函数（cn、utils）
+  lib/                     # 通用工具函数（cn、utils）及数据生成器定义
   workers/                 # Web Worker（数据生成等耗时任务）
-public/                # 静态资源（图标、_locales 等）
+spec/                    # 功能规格、修复方案与验收标准（见 spec/README.md）
+public/                  # 静态资源（图标等）
+.wxt/                    # wxt prepare 自动生成，含类型声明与扩展 tsconfig（勿手动编辑）
+.output/                 # 生产构建输出目录
 ```
 
+### layout/
+
+应用壳层，与 popup / sidepanel / tab 入口绑定。当前含 `TopBar/`（搜索、主题切换、返回导航、「在标签页打开」），遵循与 `pages/` 相同的 UI + Hook 模式。详见 [layout/README.md](./src/layout/README.md)。
+
+### spec/
+
+功能规格与验收标准文档，重大改动前优先查阅。索引见 [spec/README.md](./spec/README.md)。
+
 ### 页面组件模式
 
 典型功能页面遵循 **UI + Hook 分离** 模式。详见 [CODING_STANDARDS.md § 11](./.github/CODING_STANDARDS.md#11-页面开发规范)。
@@ -59,23 +93,54 @@ src/pages/FeatureName/
 - 当 `index.tsx` 超过 150 行时，必须拆分为 UI + Hook 模式
 - 复杂页面可增加 `contexts/`、`hooks/`、`components/` 子目录
 
+### 测试数据生成器模块
+
+```
+src/pages/TestDataGenerator/
+├── index.tsx                    # 主页面（字段配置 + 标签页切换）
+├── hooks/useGenerator.ts        # Web Worker 管理 Hook（创建、复用、通信、销毁）
+└── components/
+    ├── FieldList.tsx            # 字段列表（虚拟滚动 + @dnd-kit 拖拽排序 + 规则保存）
+    ├── FieldItem.tsx            # 字段卡片展示
+    ├── FieldEditor.tsx          # 字段编辑器（名称校验、生成器选择、参数配置）
+    ├── GeneratorSelector.tsx    # 生成器选择器（分类 + 搜索）
+    ├── GeneratorConfig.tsx      # 生成器参数表单（动态渲染 string/number/boolean/select/array）
+    ├── GenerateOptions.tsx      # 生成选项（数量、格式）
+    ├── GenerateButton.tsx       # 生成按钮 + 进度条
+    ├── DataPreview.tsx          # 示例数据预览（JSON 语法高亮）
+    ├── ResultPanel.tsx          # 生成结果状态面板
+    ├── ExportPanel.tsx          # 导出面板（复制/下载 JSON/CSV）
+    └── RuleManager.tsx          # 规则管理（CRUD、搜索、导入/导出）
+
+src/utils/
+├── ruleStorage.ts               # 规则持久化存储（localStorage）
+└── dataExporter.ts              # 数据导出工具（JSON/CSV 转换、下载、剪贴板）
+
+src/lib/generators/              # 内置生成器定义（个人信息、企业、技术、基础类型）
+
+src/workers/
+└── generator.worker.ts          # 数据生成 Web Worker
+
+src/types/
+└── testDataGenerator.ts         # 类型定义（FieldConfig, DataRule, GeneratorDefinition 等）
+```
+
 ## 关键架构决策
 
 **路由**: 不使用 React Router。通过 `src/config/features.tsx` 的 `FEATURES` 数组管理，`RouterProvider` 根据 `PageType`
-渲染对应组件。支持三种渲染模式：popup（弹窗）、sidepanel（侧边栏）和 browser-tab（浏览器新标签页，通过 `open_in_tab` 打开）。
+渲染对应组件。支持三种渲染模式：popup（弹窗）、sidepanel（侧边栏）和 tab（浏览器新标签页，TopBar「在标签页打开」调用 `openExtensionPage('popup.html', { mode: 'tab' })`，由 `getEntryPointType()` 根据 URL 参数 `mode=tab` 识别）。
 每种模式有独立的路由和可见页面配置（`app/popupRoute`、`app/sidepanelRoute`、`app/tabRoute` 等）。
 
 **存储**: 所有 Chrome Storage 键必须在 `src/types/storage.d.ts` 的 `StorageSchema` 中定义，键名使用 kebab-case 格式（如 `app/currentRoute`）。
-使用 `src/utils/chromeStorage.ts` 及其 Hook。Router 同时使用 `chrome.storage.local` 和 `localStorage` 做快照以消除首屏闪烁。
+使用 `src/utils/chromeStorage.ts` 及其 Hook。Router 同时使用 `chrome.storage.local` 和 `localStorage` 快照（`snapshot/{key}`）消除首屏闪烁。
+异步加载完成前禁止写入 storage（`RouterProvider` 的 `canPersistRef`、`useStorageState` 的 `loadSucceededRef`），避免默认值覆盖已有数据。
 
 **通信**: 使用 `@webext-core/messaging`，协议定义在 `src/utils/messages.ts`。
 
-**路径别名**: `@/` 映射到项目根目录 (已在 tsconfig 和 vitest.config 中配置)。
+**路径别名**: `@/` 映射到 `src/` 目录（已在 `.wxt/tsconfig.json` 和 `vitest.config.ts` 中配置）。项目根目录使用 `@@/`。
 
 **浏览器兼容**: 优先使用 `wxt/browser` 导出的 `browser` 对象，而非原生 `chrome` API。
 
-**代码分割**: `wxt.config.ts` 通过 `manualChunksForHtmlOnly()` 自动分组依赖（vendor-react、vendor-qr、vendor-dnd 等），无需手动配置。
-
 ## 测试环境
 
 - 环境: jsdom
@@ -87,15 +152,24 @@ src/pages/FeatureName/
 - Mock 模式: 使用 `vi.mock()` 进行模块级 mock，避免在测试文件中重复 mock 代码
 - 测试工具: `@testing-library/react` + `@testing-library/user-event` 进行组件测试
 
+## UI 文案
+
+项目已移除 `chrome.i18n`，UI 文案直接在代码中使用中文。
+
+- **功能元数据**: `src/config/features.tsx` 的 `FEATURES` 数组定义 `label`、`description`（用于 Dashboard 卡片与搜索）
+- **页面文案**: 在组件 JSX、`constants.ts` 或 Hook 中直接写中文
+- **Manifest 文案**: 扩展名称与描述在 `wxt.config.ts` 的 `manifest` 中维护
+- **Toast / 错误提示**: 在 Hook 或 `constants.ts` 中定义，使用 `sonner` 的 `toast()` 展示
+
 ## 新功能开发清单
 
 1. 在 `src/types/storage.d.ts` 添加 `PageType` 联合类型
-2. 在 `src/config/features.tsx` 的 `FEATURES` 数组添加配置（指定 key、翻译键、图标、三种渲染模式的组件）
+2. 在 `src/config/features.tsx` 的 `FEATURES` 数组添加配置（指定 key、label、description、图标、三种渲染模式的组件）
 3. 在 `src/pages/` 创建页面组件 (懒加载)：
-   - `index.tsx` — UI 组件
-   - `use{FeatureName}.ts` — 业务逻辑 Hook
-   - `constants.ts` — 常量（可选）
-4. 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`；如有不使用的权限，需移除
+   - `index.tsx` — UI 组件（纯展示）
+   - `useFeatureName.ts` — 业务逻辑 Hook
+   - `constants.ts` — 常量定义（可选，≥3 个常量时创建）
+4. 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
 5. 添加对应的单元测试
 
 ## 代码规范
@@ -105,10 +179,9 @@ src/pages/FeatureName/
 - 样式: 使用 Tailwind CSS + shadcn/ui (通过 `className` 和 `cn()` 工具)
 - UI 组件: 优先使用 `src/components/ui/` 下的 shadcn/ui 组件 (button, dialog, select 等)
 - 图标: 使用 `lucide-react` 图标库
-- 格式: Prettier (`.prettierrc`: 100 字符宽, 单引号, 尾逗号 all, LF 换行)
-- ESLint 使用 `typescript-eslint` 的 `projectService: true`（无需手动维护 project 路径）
-- **Git Commit**: 必须使用中文描述，遵循 Conventional Commits 规范（如 `fix(组件名): 描述`、`feat(功能名): 描述`）
-- **测试维护**: 新增/编辑已有功能/组件时，需要针对相关的测试进行更新
+- 格式: Prettier [配置](./.prettierrc)
+- ESLint 使用 `typescript-eslint` 的 `projectService: true`
+- Git Commit: 使用中文描述，遵循 [Conventional Commits 规范](https://www.conventionalcommits.org/zh-hans/v1.0.0/)
 
 ## 关键外部库（非显而易见的）
 
@@ -116,4 +189,4 @@ src/pages/FeatureName/
 - `@dnd-kit` — 拖拽排序（用于页面顺序管理和字段列表排序）
 - `qrious` + `qr-scanner` — 二维码生成与解析
 - `dayjs` — 日期处理（时间戳转换）
-- `sonner` — Toast 通知（替代传统 snackbar）
+- `sonner` — Toast 通知

CLAUDE.md

@@ -1 +1 @@
-@AGENT.md
+@AGENTS.md

README.md

@@ -81,7 +81,7 @@
 - **UI 组件**: shadcn/ui (基于 Radix UI 的无头组件库)
 - **样式**: Tailwind CSS + class-variance-authority + cn() 工具函数
 - **日期处理**: dayjs (集成 UTC 和 Timezone 插件)
-- **国际化**: i18next + react-i18next
+- **UI 文案**: 组件内直接使用中文字符串；功能名称与描述定义在 `src/config/features.tsx`
 - **通信**: @webext-core/messaging
 - **存储**: Chrome Storage API (类型安全封装)
 - **解析引擎**: qr-scanner (二维码解析), qrious (二维码生成)
@@ -107,8 +107,8 @@
 │   ├── hooks/             # 自定义 React Hooks
 │   ├── utils/             # 工具函数与服务抽象
 │   ├── types/             # TypeScript 类型声明
-│   └── lib/               # 通用工具函数 (cn, utils 等)
-├── public/                # 静态资源 (图标、manifest 资源等)
+│   └── lib/               # 通用工具函数与生成器库 (cn, utils, generators 等)
+├── public/                # 静态资源 (图标等)
 ├── wxt.config.ts          # WXT 框架核心配置
 └── package.json           # 项目元数据与依赖管理
 ```
@@ -155,7 +155,6 @@
 - `sidePanel`: 支持在浏览器侧边栏中运行.
 - `clipboardWrite`: 提供一键复制功能.
 - `contextMenus`: 注册右键菜单，支持快捷操作.
-- `alarms`: 管理后台定时任务（如清理后自动刷新）.
 
 ## 浏览器支持
 

docs/VISUAL_STYLE_GUIDE.md

@@ -724,17 +724,14 @@ src/
 ```tsx
 // src/pages/NewTool/index.tsx
 import SwitchButtonGroup from '@/components/SwitchButtonGroup';
-import { useI18n } from '@/utils/chromeI18n';
 import { cn } from '@/lib/utils';
 
 export default function Index() {
-  const { t } = useI18n('newTool');
-
   return (
-    <div className="p-4 w-full flex flex-col space-y-4 min-h-[500px] select-none">
+    <div className="p-4 w-full flex flex-col space-y-4 select-none">
       {/* 页面内容 */}
       <div className="p-5 rounded-xl border border-border bg-card text-card-foreground shadow-sm">
-        <h4 className="font-bold text-sm tracking-tight">{t('newTool:title')}</h4>
+        <h4 className="font-bold text-sm tracking-tight">新工具</h4>
       </div>
     </div>
   );

docs/test-data-generator/README.md

@@ -2,7 +2,7 @@
 
 > 版本: v1.0
 > 创建时间: 2024-01-20
-> 状态: 待 Review
+> 状态: 已实现（见 `src/pages/TestDataGenerator/`、`src/lib/generators/`、`src/workers/generator.worker.ts`）
 
 ## 产品定位
 
@@ -19,3 +19,13 @@
 - [规则管理](./rule-management.md)
 - [界面设计](./ui-design.md)
 - [技术实现](./technical-implementation.md)
+
+## 当前实现入口
+
+- 页面入口：`src/pages/TestDataGenerator/index.tsx`
+- Worker：`src/workers/generator.worker.ts`
+- 生成器库：`src/lib/generators/`
+- 规则存储：`src/utils/ruleStorage.ts`
+- 导出工具：`src/utils/dataExporter.ts`
+
+实现约束与任务完成状态记录在 [TASKS.md](./TASKS.md)。

public/README.md

@@ -17,3 +17,4 @@
 
 - 修改图标后需同步更新 `wxt.config.ts` 中的 manifest 配置
 - 图标格式推荐使用 PNG，确保透明背景
+- UI 文案不在此目录维护，见 `src/config/features.tsx` 与各页面组件

spec/README.md

@@ -0,0 +1,7 @@
+# Spec 目录
+
+功能规格、修复方案与验收标准文档。
+
+| 文档                                                                             | 状态              | 说明                                                 |
+| -------------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------- |
+| [storage-cleaner/indexeddb-fix-plan.md](./storage-cleaner/indexeddb-fix-plan.md) | ✅ Phase 3 已完成 | Storage Cleaner IndexedDB 清理逻辑修复方案与验收标准 |

spec/storage-cleaner/indexeddb-fix-plan.md

@@ -0,0 +1,435 @@
+# Storage Cleaner — IndexedDB 修复方案与验收标准
+
+> 创建时间: 2026-06-25
+> 状态: ✅ Phase 3 已完成（2026-06-25）
+> 关联模块: `src/utils/storageCleaner.ts`
+> 前置审查: Code Review（`storageCleaner.ts` 修改版）
+
+## 背景与目标
+
+本次修复针对 `storageCleaner.ts` 中 IndexedDB 清理逻辑及错误处理链路的审查结论，按优先级分三阶段实施。
+
+| 问题域              | 现状                                           | 目标                              |
+| ------------------- | ---------------------------------------------- | --------------------------------- |
+| IndexedDB fallback  | `store.clear()` 完成后立即 `db.close()`        | 等 transaction commit 后再关闭    |
+| deleteDatabase 超时 | 超时后仍可能触发 `onsuccess`，与 fallback 并发 | 单次删除生命周期内只 resolve 一次 |
+| 部分成功            | 多 DB 部分失败时 `count` 丢失                  | 失败结果保留已清理数量            |
+| 代码结构            | `runScript` / `runCleanScript` 重复            | 统一 executeScript 入口           |
+| 测试                | 缺多 DB 混合场景                               | 补单元测试覆盖                    |
+
+---
+
+## Phase 1 — 合并前必做（P1）
+
+### 1.1 等待 IndexedDB transaction 完成后再关闭连接
+
+#### 问题
+
+`clearObjectStores` 在 `Promise.all(clearStore...)` 结束后立刻 `db.close()`。单个 `clearReq.onsuccess` 只表示 request 完成，transaction 可能尚未 commit，存在清空被回滚的风险。
+
+#### 根因
+
+IndexedDB 规范中，transaction 的持久化以 `transaction.oncomplete` 为准，而非单个 request 的 `onsuccess`。
+
+#### 修复方案
+
+在注入脚本内的 `clearObjectStores` 中，增加 `waitForTransaction` 辅助函数：
+
+```typescript
+const waitForTransaction = (tx: IDBTransaction): Promise<void> =>
+  new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error ?? new Error('Transaction failed'));
+    tx.onabort = () => reject(tx.error ?? new Error('Transaction aborted'));
+  });
+```
+
+修改 `openReq.onsuccess` 分支：
+
+```typescript
+const transaction = db.transaction(storeNames, 'readwrite');
+const errors = (
+  await Promise.all(
+    storeNames.map((storeName) => clearStore(transaction.objectStore(storeName), storeName)),
+  )
+).filter((error): error is string => Boolean(error));
+
+try {
+  await waitForTransaction(transaction);
+} catch {
+  db.close();
+  resolve({
+    success: false,
+    errors: [`清空 IndexedDB 失败（${dbName}），请刷新后重试`],
+  });
+  return;
+}
+
+db.close();
+resolve({ success: errors.length === 0, errors });
+```
+
+#### 涉及文件
+
+- `src/utils/storageCleaner.ts` — `injectClearIndexedDB` 内 `clearObjectStores`
+
+#### 新增测试
+
+```typescript
+it('should wait for transaction complete before closing db', async () => {
+  // mock: clear onsuccess 先于 transaction.oncomplete 触发
+  // 断言 db.close 在 transaction.oncomplete 之后调用
+});
+```
+
+---
+
+### 1.2 消除 deleteDatabase 超时竞态
+
+#### 问题
+
+超时 `resolve('timeout')` 后，`deleteReq.onsuccess` 仍可能触发；此时 fallback 的 `indexedDB.open` 与进行中的 `deleteDatabase` 可能并发，行为未定义。
+
+#### 修复方案
+
+为每个 DB 删除引入 **单次 settle** 状态：
+
+```typescript
+const waitForDeleteDatabase = (dbName: string, timeoutMs: number) =>
+  new Promise<'deleted' | 'blocked' | 'timeout' | 'error'>((resolve) => {
+    let settled = false;
+    const settle = (status: 'deleted' | 'blocked' | 'timeout' | 'error') => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolve(status);
+    };
+
+    const deleteReq = indexedDB.deleteDatabase(dbName);
+    const timeout = setTimeout(() => {
+      console.warn('IndexedDB delete timeout:', dbName);
+      settle('timeout');
+    }, timeoutMs);
+
+    deleteReq.onblocked = () => {
+      console.warn('IndexedDB delete blocked:', dbName);
+      settle('blocked');
+    };
+    deleteReq.onsuccess = () => settle('deleted');
+    deleteReq.onerror = () => settle('error');
+  });
+```
+
+#### timeout / blocked 后的 fallback 策略
+
+| 状态      | 行为                                                               |
+| --------- | ------------------------------------------------------------------ |
+| `blocked` | 立即 fallback `clearObjectStores`（页面仍占用连接，open 通常可行） |
+| `timeout` | 先 `await delay(100~200ms)` 再 fallback，降低与 delete 并发概率    |
+| `error`   | 不 fallback，直接报错                                              |
+
+#### 涉及文件
+
+- `src/utils/storageCleaner.ts` — 替换现有 `new Promise` 删除逻辑
+
+#### 新增测试
+
+```typescript
+it('should ignore late onsuccess after delete timeout', async () => {
+  // deleteBehavior: timeout，5000ms 后 resolve timeout
+  // 6000ms 后再触发 onsuccess
+  // 断言：只走 fallback 一次，count 不因 late onsuccess 重复 +1
+});
+```
+
+---
+
+## Phase 2 — 建议同 PR 或紧接 follow-up（P2）
+
+### 2.1 IndexedDB 部分成功时保留 count
+
+#### 问题
+
+多 DB 场景返回 `{ count: 2, errors: ['...'] }` 时，`runCleanScript` 只返回 `{ success: false, error }`，用户看不到已清理 2 个库。
+
+#### 修复方案（推荐）
+
+扩展失败分支类型，可选 `count`：
+
+```typescript
+// src/types/storage.d.ts
+export type StorageCleanResult =
+  | { success: true; count: number }
+  | { success: false; error: string; count?: number }; // 部分成功时的已清理数
+```
+
+修改 `runCleanScript`：
+
+```typescript
+if (raw.errors?.length) {
+  const errorMsg = raw.errors.join('\n');
+  const partialHint = raw.count > 0 ? `（已成功清理 ${raw.count} 个数据库，但部分失败）\n` : '';
+  return {
+    success: false,
+    error: partialHint + errorMsg,
+    ...(raw.count > 0 ? { count: raw.count } : {}),
+  };
+}
+```
+
+#### UI 层（可选增强）
+
+`CleaningResult.tsx` 失败时若 `result.indexedDB?.count` 存在，可展示部分成功提示（非必须，error 字符串已含 hint 即可）。
+
+#### 涉及文件
+
+- `src/types/storage.d.ts`
+- `src/utils/storageCleaner.ts` — `runCleanScript`
+- `src/utils/__tests__/storageCleaner.test.ts`
+- （可选）`src/pages/StorageCleaner/components/CleaningResult.tsx`
+
+#### 新增测试
+
+```typescript
+it('should preserve partial count when some IndexedDB databases fail', async () => {
+  // 3 个 DB：2 成功删除，1 blocked 且 fallback 失败
+  // expect: success false, count 2, error 含「已成功清理 2 个」
+});
+```
+
+---
+
+### 2.2 统一 executeScript 调用入口
+
+#### 问题
+
+`runScript` 与 `runCleanScript` 各自调用 `browser.scripting.executeScript`，行为不一致（吞错 vs 抛错）。
+
+#### 修复方案
+
+抽取底层函数：
+
+```typescript
+type ExecuteScriptMode = 'fallback' | 'throw';
+
+async function executeInTab<T>(
+  tabId: number,
+  func: () => T | Promise<T>,
+  options: { errorLabel: string; mode: 'fallback'; fallback: T },
+): Promise<T>;
+async function executeInTab<T>(
+  tabId: number,
+  func: () => T | Promise<T>,
+  options: { errorLabel: string; mode: 'throw' },
+): Promise<T>;
+async function executeInTab<T>(...) {
+  try {
+    const [result] = await browser.scripting.executeScript({ target: { tabId }, func });
+    return (result?.result as T) ?? (options.mode === 'fallback' ? options.fallback : undefined as T);
+  } catch (error) {
+    console.error(`Failed to ${options.errorLabel}:`, error);
+    if (options.mode === 'throw') throw error;
+    return options.fallback;
+  }
+}
+```
+
+- `runScript` → `executeInTab(..., { mode: 'fallback', fallback })`
+- `runCleanScript` → `executeInTab(..., { mode: 'throw' })` + 结果解析
+
+#### 涉及文件
+
+- `src/utils/storageCleaner.ts`
+
+#### 验收
+
+现有 11 个测试全部通过，无行为回归。
+
+---
+
+### 2.3 错误信息分隔符统一
+
+#### 问题
+
+`runCleanScript` 用 `'; '` 拼接，`clearStorage` 的 `result.error` 用 `'\n'`，UI 用 `break-all` 展示，多错误时可读性不一致。
+
+#### 修复方案
+
+IndexedDB 内部多错误统一改为 `'\n'`：
+
+```typescript
+error: raw.errors.join('\n');
+```
+
+#### 涉及文件
+
+- `src/utils/storageCleaner.ts`
+- 相关测试断言（若有 `'; '` 期望）
+
+---
+
+### 2.4 补充多 DB 混合场景测试
+
+| 用例               | 输入                           | 期望                                         |
+| ------------------ | ------------------------------ | -------------------------------------------- |
+| 全部成功           | 3 DB，均 delete success        | `success: true, count: 3`                    |
+| 部分 fallback 成功 | 2 success + 1 blocked→clear OK | `success: true, count: 3`                    |
+| 部分失败           | 2 success + 1 error            | `success: false, count: 2, error 含失败库名` |
+| 空库列表           | `databases()` 返回 `[]`        | `success: true, count: 0`                    |
+
+#### 涉及文件
+
+- `src/utils/__tests__/storageCleaner.test.ts`
+- 扩展 `createIndexedDBMock` 支持 per-db 不同 `deleteBehavior`
+
+---
+
+## Phase 3 — 可选优化（P3）
+
+### 3.1 超时常量提升到模块级
+
+```typescript
+// src/utils/storageCleaner.ts 或 src/pages/StorageCleaner/constants.ts
+const INDEXED_DB_DELETE_TIMEOUT_MS = 5000;
+const INDEXED_DB_CLEAR_STORE_TIMEOUT_MS = 5000;
+```
+
+注入脚本通过闭包引用（executeScript 会序列化 func，常量需在 func 外部定义并 capture，或仍写在 func 内但从模块常量赋值）。
+
+### 3.2 IndexedDB 逻辑拆分（长期）
+
+将 `clearObjectStores`、`waitForDeleteDatabase` 等抽到 `src/utils/indexedDbCleaner.ts` 的纯函数，注入层只做：
+
+```typescript
+async () => clearAllIndexedDBs(INDEXED_DB_DELETE_TIMEOUT_MS);
+```
+
+便于单测，不依赖 `mockExecuteScriptEval` 间接执行注入函数。工作量大，建议单独 PR。
+
+---
+
+## 实施顺序
+
+```mermaid
+flowchart TD
+  A[1.1 transaction.oncomplete] --> B[1.2 delete settle 防竞态]
+  B --> C[2.4 补多 DB 测试]
+  C --> D[2.1 部分成功 count]
+  D --> E[2.2 统一 executeInTab]
+  E --> F[2.3 错误分隔符]
+  F --> G[3.x 可选重构]
+```
+
+| 阶段    | 预估工作量 | 风险             |
+| ------- | ---------- | ---------------- |
+| Phase 1 | 0.5~1 天   | 低，逻辑局部     |
+| Phase 2 | 0.5~1 天   | 中，涉及类型扩展 |
+| Phase 3 | 1~2 天     | 低，可延后       |
+
+---
+
+## 验收标准
+
+### A. 自动化（CI 必须通过）
+
+```bash
+npm run test -- src/utils/__tests__/storageCleaner.test.ts
+npm run typecheck
+npm run lint
+```
+
+| 编号 | 标准                                                                           |
+| ---- | ------------------------------------------------------------------------------ |
+| A-1  | 全部单元测试通过，新增测试 ≥ 3（transaction 顺序、late onsuccess、多 DB 混合） |
+| A-2  | `tsc --noEmit` 无错误；若扩展 `StorageCleanResult`，所有引用处类型正确         |
+| A-3  | ESLint `--max-warnings=0` 通过                                                 |
+
+---
+
+### B. 功能行为
+
+| 编号 | 场景                                                 | 期望结果                                                                      |
+| ---- | ---------------------------------------------------- | ----------------------------------------------------------------------------- |
+| B-1  | 单 DB，`deleteDatabase` 成功                         | `indexedDB: { success: true, count: 1 }`，`overallSuccess: true`              |
+| B-2  | 单 DB，`deleteDatabase` blocked，fallback clear 成功 | `success: true, count: 1`；transaction 在 `oncomplete` 后 `db.close`          |
+| B-3  | 单 DB，delete 超时 5s，fallback clear 成功           | 5s 内进入 fallback；不因 late `onsuccess` 重复计数                            |
+| B-4  | fallback 中某 store clear hang 5s                    | `success: false`，error 含 `dbName/storeName`                                 |
+| B-5  | 3 DB：2 成功 + 1 失败                                | `success: false`，`count: 2`（Phase 2.1 后），error 含失败库名与部分成功提示  |
+| B-6  | `executeScript` 注入失败                             | `success: false`，**不得** `{ success: true, count: 0 }`                      |
+| B-7  | localStorage 成功 + cookies 失败                     | `overallSuccess: false`，`result.error` 为 `Cookies: ...`（换行分隔多项失败） |
+
+---
+
+### C. 回归与 UI
+
+| 编号 | 标准                                                                                                      |
+| ---- | --------------------------------------------------------------------------------------------------------- |
+| C-1  | `formatCleaningResult` 成功路径不变                                                                       |
+| C-2  | `CleaningResult` 失败时展示 `result.error`；含 `\n` 时多行可读（现有 `leading-relaxed break-all` 可接受） |
+| C-3  | `reloadAfterClean=true` 且 `overallSuccess=false` 时不刷新页面（`useStorageCleaner` 现有逻辑）            |
+| C-4  | Cookie 清理：domain 前导 `.` 剥离逻辑不变                                                                 |
+
+---
+
+### D. 手动验收（扩展环境）
+
+在 Chrome 加载 unpacked extension，选普通 HTTPS 页面：
+
+| 编号 | 步骤                                              | 期望                                                                    |
+| ---- | ------------------------------------------------- | ----------------------------------------------------------------------- |
+| D-1  | 页面写入 localStorage + IndexedDB，仅清 IndexedDB | 成功提示或明确错误；DevTools → Application → IndexedDB 数据为空或库已删 |
+| D-2  | 打开 DevTools 保持 IndexedDB 面板，执行清理       | 若 blocked，显示中文提示；fallback 成功后数据不可见                     |
+| D-3  | 勾选「清理后刷新」且全部成功                      | Toast「清理成功，即将刷新页面」，页面刷新                               |
+| D-4  | 部分失败                                          | 不刷新；结果区红色展示错误详情                                          |
+
+---
+
+### E. 代码质量
+
+| 编号 | 标准                                                               |
+| ---- | ------------------------------------------------------------------ |
+| E-1  | 注入脚本内无重复 `settled` / timeout 逻辑（删除与 clear 各自封装） |
+| E-2  | 错误文案仍为中文，含库名/store 名                                  |
+| E-3  | 无 `any`（测试文件除外）                                           |
+| E-4  | Phase 1 合并后，P1 项在 PR 描述中标注「已修复」并附测试名          |
+
+---
+
+## PR 检查清单
+
+```markdown
+## 修复内容
+
+- [ ] P1: transaction.oncomplete 后再 db.close
+- [ ] P1: deleteDatabase settle 防竞态
+- [ ] P2: 部分成功保留 count（可选）
+- [ ] P2: 多 DB 混合测试
+- [ ] P2: 错误信息 `\n` 分隔（可选）
+
+## 验收
+
+- [ ] npm run test / typecheck / lint 通过
+- [ ] 新增测试覆盖 B-2、B-3、B-5
+- [ ] 手动 D-1 ~ D-4 至少测 D-1、D-3
+```
+
+---
+
+## 风险与边界说明
+
+1. **fallback 清空 ≠ 删除库**：blocked 时只清 object store，库结构仍在；成功 `count` 表示「有效清理动作完成」，需在 UI/文档中说明（可选文案：「数据已清空，数据库结构可能仍存在」）。
+2. **timeout 延迟 fallback**：100~200ms 为经验值，无法完全消除竞态，只能降低概率；完全消除需浏览器不支持 abort delete 的前提下接受 best-effort。
+3. **类型扩展**：`StorageCleanResult` 加可选 `count` 为向后兼容；消费方用 `'count' in result && result.count` 判断即可。
+
+---
+
+## 相关文件索引
+
+| 文件                                                     | 说明                                         |
+| -------------------------------------------------------- | -------------------------------------------- |
+| `src/utils/storageCleaner.ts`                            | 核心清理逻辑                                 |
+| `src/utils/__tests__/storageCleaner.test.ts`             | 单元测试                                     |
+| `src/types/storage.d.ts`                                 | `StorageCleanResult` / `CleaningResult` 类型 |
+| `src/pages/StorageCleaner/constants.ts`                  | 选项标签与键名                               |
+| `src/pages/StorageCleaner/useStorageCleaner.ts`          | 清理流程编排                                 |
+| `src/pages/StorageCleaner/components/CleaningResult.tsx` | 结果展示 UI                                  |

src/components/CopyButton.tsx

@@ -1,8 +1,7 @@
 import React, { useEffect, useRef, useState } from 'react';
 import { Check, Copy } from 'lucide-react';
 import { copyTextToClipboard } from '@/utils/clipboard';
-import { cn } from '@/lib/utils';
-import { buttonVariants, type ButtonProps } from '@/components/ui/button';
+import { Button, type ButtonProps } from '@/components/ui/button';
 import { toast } from 'sonner';
 
 interface CopyButtonProps extends Omit<ButtonProps, 'children' | 'onClick'> {
@@ -47,17 +46,14 @@ export const CopyButton: React.FC<CopyButtonProps> = ({
   };
 
   return (
-    <button
+    <Button
       type="button"
       onClick={handleCopy}
       title={tooltip ?? '复制'}
       aria-label={tooltip ?? '复制'}
-      className={cn(
-        buttonVariants({ variant, size }),
-        copied &&
-          'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400 hover:bg-emerald-500/10',
-        className,
-      )}
+      variant={variant}
+      size={size}
+      className={className}
       {...props}
     >
       {copied ? (
@@ -65,7 +61,7 @@ export const CopyButton: React.FC<CopyButtonProps> = ({
       ) : (
         <Copy className="h-[1.2em] w-[1.2em]" />
       )}
-    </button>
+    </Button>
   );
 };
 

src/components/EmptyPlaceholder.tsx

@@ -0,0 +1,30 @@
+import React from 'react';
+import { cn } from '@/lib/utils';
+
+export interface EmptyPlaceholderProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  messageClassName?: string;
+}
+
+const CONTAINER_CLASSES =
+  'rounded-xl bg-muted/30 border border-dashed border-border/80 text-center flex flex-col items-center justify-center select-none p-8 min-h-[120px]';
+
+const MESSAGE_CLASSES =
+  'text-xs font-semibold text-muted-foreground/80 tracking-wide max-w-[240px] leading-relaxed';
+
+export default function EmptyPlaceholder({
+  children,
+  className,
+  messageClassName,
+  ...props
+}: EmptyPlaceholderProps) {
+  return (
+    <div className={cn(CONTAINER_CLASSES, className)} {...props}>
+      {typeof children === 'string' || typeof children === 'number' ? (
+        <p className={cn(MESSAGE_CLASSES, messageClassName)}>{children}</p>
+      ) : (
+        children
+      )}
+    </div>
+  );
+}

src/components/ErrorBoundary.tsx

@@ -1,6 +1,5 @@
 import { Component, ErrorInfo, ReactNode } from 'react';
-import { AlertCircle, RefreshCw } from 'lucide-react';
-import { Button } from '@/components/ui/button';
+import { ErrorFallback } from '@/components/ErrorFallback';
 
 interface Props {
   children: ReactNode;
@@ -38,32 +37,14 @@ class ErrorBoundary extends Component<Props, State> {
   render() {
     if (this.state.hasError) {
       return (
-        <div className="flex flex-col items-center justify-center mt-16 mx-auto max-w-md">
-          <div className="p-6 text-center rounded-xl border border-destructive/20 bg-destructive/5 shadow-sm">
-            <div className="flex h-16 w-16 items-center justify-center rounded-full bg-destructive/10 text-destructive mx-auto mb-4">
-              <AlertCircle className="h-8 w-8" />
-            </div>
-            <h2 className="text-xl font-extrabold text-destructive mb-2">糟糕，出了点问题</h2>
-            <p className="text-sm text-muted-foreground mb-6">
-              应用遇到了一些意外错误。您可以尝试刷新页面或重置应用。
-            </p>
-            {this.state.error && (
-              <div className="mb-6 p-4 rounded-lg bg-zinc-950 dark:bg-zinc-900 text-left max-h-[200px] overflow-auto border border-border/40">
-                <pre className="font-mono text-xs whitespace-pre-wrap break-all text-zinc-200 selection:bg-zinc-700">
-                  {this.state.error.toString()}
-                </pre>
-              </div>
-            )}
-            <Button
-              variant="destructive"
-              onClick={this.handleReset}
-              className="rounded-lg font-bold shadow-sm"
-            >
-              <RefreshCw className="mr-2 h-4 w-4" />
-              刷新应用
-            </Button>
-          </div>
-        </div>
+        <ErrorFallback
+          variant="app"
+          title="糟糕，出了点问题"
+          description="应用遇到了一些意外错误。您可以尝试刷新页面或重置应用。"
+          error={this.state.error}
+          actionLabel="刷新应用"
+          onAction={this.handleReset}
+        />
       );
     }
 

src/components/ErrorFallback.tsx

@@ -0,0 +1,94 @@
+import { AlertCircle, RefreshCw } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { cn } from '@/lib/utils';
+
+export interface ErrorFallbackProps {
+  title: string;
+  description: string;
+  error: Error | null;
+  actionLabel: string;
+  onAction: () => void;
+  variant?: 'app' | 'page';
+  showStack?: boolean;
+  className?: string;
+}
+
+export function ErrorFallback({
+  title,
+  description,
+  error,
+  actionLabel,
+  onAction,
+  variant = 'page',
+  showStack = false,
+  className,
+}: ErrorFallbackProps) {
+  const isApp = variant === 'app';
+  const errorText = error ? (showStack ? error.stack || error.toString() : error.toString()) : null;
+
+  return (
+    <div
+      className={cn(
+        'flex flex-col items-center justify-center',
+        isApp
+          ? 'mt-16 mx-auto max-w-md'
+          : 'flex-1 p-6 min-h-[300px] animate-in fade-in zoom-in-95 duration-200',
+        className,
+      )}
+    >
+      <div
+        className={cn(
+          'p-6 text-center rounded-xl border border-destructive/20 bg-destructive/5 shadow-sm',
+          !isApp && 'max-w-md w-full',
+        )}
+      >
+        <div
+          className={cn(
+            'flex items-center justify-center rounded-full bg-destructive/10 text-destructive mx-auto mb-4',
+            isApp ? 'h-16 w-16' : 'h-12 w-12',
+          )}
+        >
+          <AlertCircle className={isApp ? 'h-8 w-8' : 'h-6 w-6'} />
+        </div>
+
+        {isApp ? (
+          <h2 className="text-xl font-extrabold text-destructive mb-2">{title}</h2>
+        ) : (
+          <h3 className="text-base font-semibold text-foreground mb-1.5">{title}</h3>
+        )}
+
+        <p className={cn('text-muted-foreground', isApp ? 'text-sm mb-6' : 'text-xs mb-5')}>
+          {description}
+        </p>
+
+        {errorText && (
+          <div
+            className={cn(
+              'rounded-lg bg-zinc-950 dark:bg-zinc-900 text-left border border-border/40',
+              isApp ? 'mb-6 p-4 max-h-[200px] overflow-auto' : 'mb-5 p-3 max-h-40 overflow-y-auto',
+            )}
+          >
+            <pre
+              className={cn(
+                'font-mono whitespace-pre-wrap break-all text-zinc-200 selection:bg-zinc-700',
+                isApp ? 'text-xs' : 'text-[11px] leading-relaxed',
+              )}
+            >
+              {errorText}
+            </pre>
+          </div>
+        )}
+
+        <Button
+          variant="destructive"
+          size={isApp ? 'default' : 'sm'}
+          onClick={onAction}
+          className={cn(isApp ? 'rounded-lg font-bold shadow-sm' : 'font-medium shadow-sm')}
+        >
+          <RefreshCw className={isApp ? 'mr-2 h-4 w-4' : 'mr-1.5 h-3.5 w-3.5'} />
+          {actionLabel}
+        </Button>
+      </div>
+    </div>
+  );
+}

src/components/PageErrorBoundary.tsx

@@ -1,6 +1,5 @@
 import { Component, ErrorInfo, ReactNode } from 'react';
-import { AlertCircle, RefreshCw } from 'lucide-react';
-import { Button } from '@/components/ui/button';
+import { ErrorFallback } from '@/components/ErrorFallback';
 
 interface Props {
   children: ReactNode;
@@ -39,36 +38,15 @@ class PageErrorBoundary extends Component<Props, State> {
   render() {
     if (this.state.hasError) {
       return (
-        <div className="flex flex-col items-center justify-center flex-1 p-6 min-h-[300px] animate-in fade-in zoom-in-95 duration-200">
-          <div className="p-6 text-center rounded-xl border border-destructive/20 bg-destructive/5 max-w-md w-full shadow-sm">
-            <div className="flex h-12 w-12 items-center justify-center rounded-full bg-destructive/10 text-destructive mx-auto mb-4">
-              <AlertCircle className="h-6 w-6" />
-            </div>
-
-            <h3 className="text-base font-semibold text-foreground mb-1.5">该功能运行异常</h3>
-            <p className="text-xs text-muted-foreground mb-5">
-              该页面在加载或渲染时遇到了内部脚本错误。您可以尝试重试，或者通过导航菜单切换到其他工具。
-            </p>
-
-            {this.state.error && (
-              <div className="mb-5 p-3 rounded-lg bg-zinc-950 dark:bg-zinc-900 text-left max-h-40 overflow-y-auto border border-border/40">
-                <pre className="font-mono text-[11px] leading-relaxed whitespace-pre-wrap break-all text-zinc-200 selection:bg-zinc-700">
-                  {this.state.error.stack || this.state.error.toString()}
-                </pre>
-              </div>
-            )}
-
-            <Button
-              variant="destructive"
-              size="sm"
-              onClick={this.handleRetry}
-              className="font-medium shadow-sm"
-            >
-              <RefreshCw className="mr-1.5 h-3.5 w-3.5" />
-              重新尝试
-            </Button>
-          </div>
-        </div>
+        <ErrorFallback
+          variant="page"
+          title="该功能运行异常"
+          description="该页面在加载或渲染时遇到了内部脚本错误。您可以尝试重试，或者通过导航菜单切换到其他工具。"
+          error={this.state.error}
+          actionLabel="重新尝试"
+          onAction={this.handleRetry}
+          showStack
+        />
       );
     }
 

src/components/README.md

@@ -6,9 +6,9 @@
 
 | 组件                    | 用途                                                                           |
 | ----------------------- | ------------------------------------------------------------------------------ |
-| `TopBar.tsx`            | 顶部导航栏，集成搜索（含历史记录）、主题切换、语言切换、返回导航               |
 | `RouterContainer.tsx`   | 路由容器，根据当前路由动态渲染对应页面组件，集成错误边界和骨架屏               |
 | `SwitchButtonGroup.tsx` | 通用切换按钮组，支持 `small/medium/large` 三种尺寸，用于页面子模式切换         |
+| `EmptyPlaceholder.tsx`  | 虚线边框空状态占位，统一工具页「暂无结果」提示样式                             |
 | `TextInputArea.tsx`     | 增强文本输入区域，支持校验规则、工具栏操作、字符计数、清空                     |
 | `CopyButton.tsx`        | 一键复制按钮，支持复制成功状态动画，封装 `copyTextToClipboard` 和 `toast` 反馈 |
 | `ImageUploader.tsx`     | 图片上传组件，支持拖拽上传、文件选择和预览                                     |

src/components/SwitchButtonGroup.tsx

@@ -1,4 +1,5 @@
 import React from 'react';
+import { Button } from '@/components/ui/button';
 import { cn } from '@/lib/utils';
 
 export interface SwitchOption<T extends string | number = string> {
@@ -45,21 +46,20 @@ export default function SwitchButtonGroup<T extends string | number = string>({
       {...props}
     >
       {options.map((option) => (
-        <button
+        <Button
           key={option.value}
           type="button"
+          variant="ghost"
           onClick={() => onChange(option.value)}
           className={cn(
-            'flex-1 inline-flex items-center justify-center font-medium whitespace-nowrap transition-all',
-            'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:ring-offset-2',
-            'disabled:pointer-events-none disabled:opacity-50',
+            'flex-1 transition-all',
             SIZE_CLASSES[size],
             value === option.value ? SELECTED_CLASSES : UNSELECTED_CLASSES,
             buttonClassName,
           )}
         >
           {option.label}
-        </button>
+        </Button>
       ))}
     </div>
   );

src/components/TextInputArea.tsx

@@ -3,6 +3,7 @@ import { X } from 'lucide-react';
 import { cn } from '@/lib/utils';
 import { toast } from 'sonner'; // 推荐使用 shadcn 的默认 Toast
 import { CopyButton } from '@/components/CopyButton';
+import { Button } from './ui/button';
 
 export type ValidateRule = {
   validator: (value: string) => boolean;
@@ -273,14 +274,16 @@ const TextInputArea = forwardRef<HTMLTextAreaElement, TextInputAreaProps>((props
                 <CopyButton text={value} tooltip={'复制内容'} size="sm" className="h-7 w-7 p-1" />
               )}
               {showClear && value && !disabled && !readOnly && (
-                <button
+                <Button
                   type="button"
                   onClick={handleClear}
                   aria-label={'清空'}
-                  className="p-1 h-7 w-7 flex items-center justify-center rounded-md text-muted-foreground hover:text-destructive hover:bg-destructive/10 transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+                  variant="ghost"
+                  size="icon"
+                  className="h-7 w-7 text-muted-foreground hover:text-destructive hover:bg-destructive/10"
                 >
                   <X className="h-4 w-4" />
-                </button>
+                </Button>
               )}
             </div>
           </div>

src/components/TopBar.tsx

@@ -1,315 +0,0 @@
-import React, { useEffect, useMemo, useRef, useState } from 'react';
-import { ArrowLeft, ExternalLink, Monitor, Moon, Search, Sun, X } from 'lucide-react';
-import { useRouter } from '@/providers/RouterProvider';
-import { useThemeMode } from '@/providers/ThemeModeProvider';
-import { FeatureConfig, FEATURES } from '@/config/features';
-import { storageUtil } from '@/utils/chromeStorage';
-import { openExtensionPage } from '@/utils/chromeTabs';
-import { cn } from '@/lib/utils';
-
-const SEARCH_HISTORY_LIMIT = 10;
-const SEARCH_HISTORY_DISPLAY = 5;
-
-export default function TopBar() {
-  const { currentPage, goBack, navigateTo } = useRouter();
-  const { mode, setMode } = useThemeMode();
-
-  const [searchQuery, setSearchQuery] = useState('');
-  const [showResults, setShowResults] = useState(false);
-  const [searchHistory, setSearchHistory] = useState<string[]>([]);
-  const [selectedIndex, setSelectedIndex] = useState(-1);
-
-  const containerRef = useRef<HTMLDivElement>(null);
-  const inputRef = useRef<HTMLInputElement>(null);
-
-  const handleOpenInTab = async () => {
-    await openExtensionPage('popup.html', { mode: 'tab' });
-    window.close();
-  };
-
-  useEffect(() => {
-    const handleClickOutside = (event: MouseEvent) => {
-      if (containerRef.current && !containerRef.current.contains(event.target as Node)) {
-        setShowResults(false);
-      }
-    };
-    document.addEventListener('mousedown', handleClickOutside);
-    return () => document.removeEventListener('mousedown', handleClickOutside);
-  }, []);
-
-  // Cmd/Ctrl+K 快捷键聚焦搜索框
-  useEffect(() => {
-    const handleGlobalKeyDown = (e: KeyboardEvent) => {
-      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
-        e.preventDefault();
-        inputRef.current?.focus();
-        setShowResults(true);
-      }
-    };
-    document.addEventListener('keydown', handleGlobalKeyDown);
-    return () => document.removeEventListener('keydown', handleGlobalKeyDown);
-  }, []);
-
-  useEffect(() => {
-    storageUtil
-      .get('app/searchHistory', [])
-      .then((history) => {
-        if (history) setSearchHistory(history);
-      })
-      .catch((err) => console.error('加载搜索历史失败:', err));
-  }, []);
-
-  const searchResults = useMemo(() => {
-    const query = searchQuery.trim().toLowerCase();
-    if (!query) return [];
-    return FEATURES.filter((f) => {
-      if (f.key === 'dashboard') return false;
-      return f.label.toLowerCase().includes(query) || f.description.toLowerCase().includes(query);
-    });
-  }, [searchQuery]);
-
-  const displayedHistory = useMemo(() => {
-    if (searchQuery.trim()) return [];
-    return searchHistory
-      .slice(0, SEARCH_HISTORY_DISPLAY)
-      .map((key) => ({ key, feature: FEATURES.find((f) => f.key === key) }))
-      .filter((item) => item.feature && item.feature.key !== 'dashboard');
-  }, [searchHistory, searchQuery]);
-
-  const saveToHistory = async (featureKey: string) => {
-    if (!featureKey.trim()) return;
-    const nextHistory = [featureKey, ...searchHistory.filter((h) => h !== featureKey)].slice(
-      0,
-      SEARCH_HISTORY_LIMIT,
-    );
-    setSearchHistory(nextHistory);
-    await storageUtil.set('app/searchHistory', nextHistory).catch((err) => console.error(err));
-  };
-
-  const handleSelectFeature = (feature: FeatureConfig) => {
-    navigateTo(feature.key);
-    saveToHistory(feature.key);
-    setSearchQuery('');
-    setShowResults(false);
-  };
-
-  const cycleThemeMode = () => {
-    const nextMap = { light: 'dark', dark: 'system', system: 'light' } as const;
-    setMode(nextMap[mode]);
-  };
-
-  const ThemeIcon = mode === 'light' ? Sun : mode === 'dark' ? Moon : Monitor;
-
-  const handleKeyDown = (e: React.KeyboardEvent) => {
-    const totalItems = searchQuery.trim() ? searchResults.length : displayedHistory.length;
-
-    if (e.key === 'ArrowDown') {
-      e.preventDefault();
-      setSelectedIndex((prev) => (prev < totalItems - 1 ? prev + 1 : prev));
-    } else if (e.key === 'ArrowUp') {
-      e.preventDefault();
-      setSelectedIndex((prev) => (prev > 0 ? prev - 1 : prev));
-    } else if (e.key === 'Enter') {
-      e.preventDefault();
-      if (selectedIndex >= 0 && selectedIndex < totalItems) {
-        if (searchQuery.trim()) {
-          handleSelectFeature(searchResults[selectedIndex]);
-        } else {
-          const selected = displayedHistory[selectedIndex];
-          if (selected?.feature) {
-            handleSelectFeature(selected.feature);
-          }
-        }
-      } else if (searchQuery.trim() && searchResults.length > 0) {
-        handleSelectFeature(searchResults[0]);
-      }
-    } else if (e.key === 'Escape') {
-      setShowResults(false);
-      inputRef.current?.blur();
-    }
-  };
-
-  const isDashboard = currentPage === 'dashboard';
-
-  return (
-    <header className="flex h-14 items-center justify-between border-b border-border bg-background px-4 relative z-50">
-      {/* 左侧：返回按钮区 */}
-      <div className="flex w-10 items-center justify-start">
-        {!isDashboard && (
-          <button
-            type="button"
-            onClick={goBack}
-            aria-label={'返回'}
-            className="flex h-8 w-8 items-center justify-center rounded-md border border-input bg-background text-muted-foreground shadow-sm transition-colors hover:bg-accent hover:text-accent-foreground"
-          >
-            <ArrowLeft className="h-4 w-4" />
-          </button>
-        )}
-      </div>
-
-      {/* 中间：搜索容器 */}
-      <div ref={containerRef} className="flex-1 mx-4 max-w-md relative">
-        <div className="relative group">
-          <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground/60 group-focus-within:text-muted-foreground transition-colors pointer-events-none" />
-          <input
-            ref={inputRef}
-            type="text"
-            placeholder={'搜索工具...'}
-            value={searchQuery}
-            onChange={(e) => {
-              setSearchQuery(e.target.value);
-              setShowResults(true);
-              setSelectedIndex(-1);
-            }}
-            onFocus={() => setShowResults(true)}
-            onKeyDown={handleKeyDown}
-            aria-label={'搜索工具...'}
-            className="w-full h-9 pl-9 pr-16 text-sm rounded-lg border border-border/60 bg-muted/40 transition-all placeholder:text-muted-foreground/50 focus:bg-background focus:outline-none focus:ring-1 focus:ring-ring focus:border-input"
-          />
-          {!searchQuery && (
-            <kbd className="absolute right-3 top-1/2 -translate-y-1/2 hidden sm:inline-flex h-5 items-center gap-0.5 rounded border border-border/60 bg-muted px-1.5 font-mono text-[10px] font-medium text-muted-foreground/60 pointer-events-none">
-              ⌘K
-            </kbd>
-          )}
-          {searchQuery && (
-            <button
-              type="button"
-              onClick={() => {
-                setSearchQuery('');
-                setSelectedIndex(-1);
-              }}
-              aria-label={'清除搜索'}
-              className="absolute right-2 top-1/2 -translate-y-1/2 p-1 rounded-md text-muted-foreground hover:text-foreground transition-colors"
-            >
-              <X className="h-3 w-3" />
-            </button>
-          )}
-        </div>
-
-        {/* 动态联想结果卡片 */}
-        {showResults && (searchQuery.trim() || displayedHistory.length > 0) && (
-          <div className="absolute top-full left-0 right-0 mt-1.5 bg-popover text-popover-foreground rounded-lg shadow-lg border border-border max-h-80 overflow-y-auto z-50 animate-in fade-in slide-in-from-top-2 duration-150">
-            <ul role="listbox" className="p-1.5">
-              {searchQuery.trim() ? (
-                searchResults.length > 0 ? (
-                  searchResults.map((feature, index) => (
-                    <li
-                      key={feature.key}
-                      role="option"
-                      aria-selected={selectedIndex === index}
-                      onClick={() => handleSelectFeature(feature)}
-                      className={cn(
-                        'flex items-center gap-3 px-3 py-2.5 rounded-md cursor-pointer text-sm transition-colors',
-                        selectedIndex === index
-                          ? 'bg-accent text-accent-foreground'
-                          : 'hover:bg-muted/60',
-                      )}
-                    >
-                      <div
-                        className={cn(
-                          'flex h-8 w-8 shrink-0 items-center justify-center rounded-lg',
-                          'bg-muted/80 text-muted-foreground',
-                        )}
-                      >
-                        {feature.icon && <feature.icon className="h-4 w-4" />}
-                      </div>
-                      <div className="flex-1 min-w-0">
-                        <p className="font-medium text-foreground truncate">{feature.label}</p>
-                        <p className="text-xs text-muted-foreground truncate mt-0.5">
-                          {feature.description}
-                        </p>
-                      </div>
-                    </li>
-                  ))
-                ) : (
-                  <li className="px-4 py-6 text-center text-sm text-muted-foreground">
-                    {'未找到相关工具'}
-                  </li>
-                )
-              ) : (
-                <>
-                  <div className="px-3 py-1.5 text-[11px] font-semibold tracking-wider text-muted-foreground/60 uppercase">
-                    {'最近搜索'}
-                  </div>
-                  {displayedHistory.map((item, index) => (
-                    <li
-                      key={item.key}
-                      role="option"
-                      aria-selected={selectedIndex === index}
-                      onClick={() => item.feature && handleSelectFeature(item.feature)}
-                      className={cn(
-                        'flex items-center gap-3 px-3 py-2 rounded-md cursor-pointer text-sm transition-colors',
-                        selectedIndex === index
-                          ? 'bg-accent text-accent-foreground'
-                          : 'hover:bg-muted/60',
-                      )}
-                    >
-                      <div
-                        className={cn(
-                          'flex h-8 w-8 shrink-0 items-center justify-center rounded-lg',
-                          'bg-muted/80 text-muted-foreground',
-                        )}
-                      >
-                        {item.feature?.icon && <item.feature.icon className="h-4 w-4" />}
-                      </div>
-                      <div className="flex-1 min-w-0">
-                        <p className="font-medium text-foreground truncate">
-                          {item.feature?.label}
-                        </p>
-                        <p className="text-xs text-muted-foreground truncate mt-0.5">
-                          {item.feature?.description}
-                        </p>
-                      </div>
-                    </li>
-                  ))}
-                </>
-              )}
-            </ul>
-          </div>
-        )}
-      </div>
-
-      {/* 右侧：操作区 */}
-      <div className="flex items-center gap-1 shrink-0">
-        <IconButton
-          onClick={cycleThemeMode}
-          title={
-            mode === 'light'
-              ? '切换到深色模式'
-              : mode === 'dark'
-                ? '切换到系统模式'
-                : '切换到浅色模式'
-          }
-        >
-          <ThemeIcon className="h-4 w-4" />
-        </IconButton>
-        <IconButton onClick={handleOpenInTab} title={'在标签页打开'}>
-          <ExternalLink className="h-4 w-4" />
-        </IconButton>
-      </div>
-    </header>
-  );
-}
-
-// 5. 提炼出高度复用的原子按钮，大幅精简 Tailwind 冗余，符合 shadcn 的灵巧风格
-function IconButton({
-  children,
-  onClick,
-  title,
-}: {
-  children: React.ReactNode;
-  onClick: () => void;
-  title: string;
-}) {
-  return (
-    <button
-      type="button"
-      onClick={onClick}
-      title={title}
-      aria-label={title}
-      className="flex h-8 w-8 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
-    >
-      {children}
-    </button>
-  );
-}

src/components/__tests__/CopyButton.test.tsx

@@ -45,29 +45,6 @@ describe('CopyButton', () => {
     expect(mockedToast.success).toHaveBeenCalled();
   });
 
-  it('复制成功后图标切换为 Check，1.5 秒后恢复', async () => {
-    mockedCopy.mockResolvedValue(true);
-    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
-
-    render(<CopyButton text="test" />);
-
-    // 点击后复制成功，按钮获得 emerald 样式（说明切到了 Check 状态）
-    await user.click(screen.getByRole('button'));
-
-    await waitFor(() => {
-      expect(screen.getByRole('button').className).toContain('text-emerald');
-    });
-
-    // 1.5 秒后样式恢复
-    act(() => {
-      vi.advanceTimersByTime(1500);
-    });
-
-    await waitFor(() => {
-      expect(screen.getByRole('button').className).not.toContain('text-emerald');
-    });
-  });
-
   it('复制空文本时弹出 error toast', async () => {
     const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
 

src/components/__tests__/EmptyPlaceholder.test.tsx

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import EmptyPlaceholder from '@/components/EmptyPlaceholder';
+
+describe('EmptyPlaceholder 组件', () => {
+  it('应渲染字符串提示文本', () => {
+    render(<EmptyPlaceholder>{'请输入内容'}</EmptyPlaceholder>);
+
+    expect(screen.getByText('请输入内容')).toBeInTheDocument();
+  });
+
+  it('应应用规范空状态容器样式', () => {
+    const { container } = render(<EmptyPlaceholder>{'提示'}</EmptyPlaceholder>);
+
+    const placeholder = container.firstChild;
+    expect(placeholder).toHaveClass(
+      'rounded-xl',
+      'bg-muted/30',
+      'border-dashed',
+      'border-border/80',
+      'min-h-[120px]',
+    );
+  });
+
+  it('应支持 className 自定义容器样式', () => {
+    const { container } = render(
+      <EmptyPlaceholder className="flex-1 min-h-[320px]">{'提示'}</EmptyPlaceholder>,
+    );
+
+    expect(container.firstChild).toHaveClass('flex-1', 'min-h-[320px]');
+  });
+
+  it('应支持 messageClassName 自定义文本样式', () => {
+    render(<EmptyPlaceholder messageClassName="text-sm max-w-none">{'提示'}</EmptyPlaceholder>);
+
+    expect(screen.getByText('提示')).toHaveClass('text-sm', 'max-w-none');
+  });
+
+  it('应支持 ReactNode 类型的 children', () => {
+    render(
+      <EmptyPlaceholder>
+        <span data-testid="custom-content">自定义内容</span>
+      </EmptyPlaceholder>,
+    );
+
+    expect(screen.getByTestId('custom-content')).toBeInTheDocument();
+  });
+});

src/components/__tests__/RouterContainer.test.tsx

@@ -12,7 +12,7 @@ const mockRouterValue = {
   isLoaded: true,
   navigateTo: vi.fn(),
   syncNavigation: vi.fn(),
-  goBack: vi.fn(),
+  goHome: vi.fn(),
   setVisiblePages: vi.fn(),
   setPageOrder: vi.fn(),
 };

src/components/__tests__/StorageCleanerConfirm.test.tsx

@@ -94,7 +94,7 @@ describe('StorageCleanerConfirm 组件', () => {
       renderComponent({ options: partialOptions });
 
       expect(screen.getByText(/Local Storage/)).toBeInTheDocument();
-      expect(screen.getByText(/站点存储/)).toBeInTheDocument();
+      expect(screen.getByText(/IndexedDB/)).toBeInTheDocument();
       expect(screen.queryByText(/Session Storage/)).not.toBeInTheDocument();
       expect(screen.queryByText(/Cookies$/)).not.toBeInTheDocument();
     });

src/config/README.md

@@ -1,44 +0,0 @@
-# config/
-
-应用级配置目录，存放功能特性的注册中心。
-
-## 文件说明
-
-| 文件           | 用途                                     |
-| -------------- | ---------------------------------------- |
-| `features.tsx` | 核心配置文件，定义所有工具功能的注册信息 |
-
-## features.tsx
-
-`FEATURES` 数组是路由和功能元数据的**单一事实来源**，每个功能定义包含：
-
-- `key`：页面类型标识（`PageType`）
-- `labelKey` / `descriptionKey`：i18n 翻译键
-- `themeColorKey`：主题色（`primary/success/warning/error/secondary/info`）
-- `icon`：lucide-react 图标组件
-- `defaultVisible`：默认是否可见
-- `components`：三种渲染模式的懒加载组件（`popup`、`sidepanel`、`tab`）
-
-## 已注册功能（11 个）
-
-| key                  | 图标              | 说明              |
-| -------------------- | ----------------- | ----------------- |
-| `dashboard`          | —                 | 仪表盘首页        |
-| `timestamp`          | Clock             | 时间戳转换工具    |
-| `storageCleaner`     | Database          | 存储清理工具      |
-| `qrCode`             | QrCode            | 二维码工具        |
-| `textStatistics`     | FileText          | 文本统计工具      |
-| `jwt`                | Key               | JWT 解析工具      |
-| `jsonDiff`           | GitCompareArrows  | JSON 差异比较工具 |
-| `base64Converter`    | ArrowLeftRight    | Base64 转换器     |
-| `markdownToHtml`     | Code              | Markdown 转 HTML  |
-| `htmlToMarkdown`     | File              | HTML 转 Markdown  |
-| `rightClickRestorer` | MousePointerClick | 右键菜单恢复工具  |
-
-## 导出函数
-
-- `getFeatureByKey(key)` — 根据 key 获取功能配置
-- `getDefaultVisibleFeatureKeys()` — 获取默认可见的功能 key 列表
-- `getAllFeatureKeys()` — 获取所有功能 key 列表
-- `getDefaultPageOrder()` — 获取默认页面排序（不含 dashboard）
-- `getEntryPointType()` — 判断当前入口类型（popup/sidepanel/tab）

src/config/__tests__/features.lazy.test.ts

@@ -0,0 +1,85 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const pageLoadTracker = vi.hoisted(() => ({
+  loaded: [] as string[],
+}));
+
+vi.mock('@/pages/Dashboard', () => {
+  pageLoadTracker.loaded.push('Dashboard');
+  return { default: () => null };
+});
+vi.mock('@/pages/Timestamp', () => {
+  pageLoadTracker.loaded.push('Timestamp');
+  return { default: () => null };
+});
+vi.mock('@/pages/StorageCleaner', () => {
+  pageLoadTracker.loaded.push('StorageCleaner');
+  return { default: () => null };
+});
+vi.mock('@/pages/QrCode', () => {
+  pageLoadTracker.loaded.push('QrCode');
+  return { default: () => null };
+});
+vi.mock('@/pages/TextStatistics', () => {
+  pageLoadTracker.loaded.push('TextStatistics');
+  return { default: () => null };
+});
+vi.mock('@/pages/Jwt', () => {
+  pageLoadTracker.loaded.push('Jwt');
+  return { default: () => null };
+});
+vi.mock('@/pages/JsonTools', () => {
+  pageLoadTracker.loaded.push('JsonTools');
+  return { default: () => null };
+});
+vi.mock('@/pages/Base64Converter', () => {
+  pageLoadTracker.loaded.push('Base64Converter');
+  return { default: () => null };
+});
+vi.mock('@/pages/RightClickRestorer', () => {
+  pageLoadTracker.loaded.push('RightClickRestorer');
+  return { default: () => null };
+});
+vi.mock('@/pages/TestDataGenerator', () => {
+  pageLoadTracker.loaded.push('TestDataGenerator');
+  return { default: () => null };
+});
+
+describe('features 懒加载', () => {
+  beforeEach(() => {
+    pageLoadTracker.loaded.length = 0;
+    vi.resetModules();
+  });
+
+  it('仅导入工具函数时不应加载任何页面模块', async () => {
+    const { getAllFeatureKeys, getDefaultPageOrder } = await import('@/config/features');
+
+    getAllFeatureKeys();
+    getDefaultPageOrder();
+
+    expect(pageLoadTracker.loaded).toEqual([]);
+  });
+
+  it('访问 FEATURES 元数据时不应加载任何页面模块', async () => {
+    const { FEATURES } = await import('@/config/features');
+
+    expect(FEATURES).toHaveLength(10);
+    expect(pageLoadTracker.loaded).toEqual([]);
+  });
+
+  it('渲染 lazy 组件时才应加载对应页面模块', async () => {
+    const React = await import('react');
+    const { render, waitFor } = await import('@testing-library/react');
+    const { FEATURES } = await import('@/config/features');
+
+    const DashboardPage = FEATURES.find((f) => f.key === 'dashboard')!.components.popup;
+
+    render(
+      React.createElement(React.Suspense, { fallback: null }, React.createElement(DashboardPage)),
+    );
+
+    await waitFor(() => {
+      expect(pageLoadTracker.loaded).toEqual(['Dashboard']);
+    });
+  });
+});

src/config/__tests__/features.test.ts

@@ -9,11 +9,11 @@ import {
 
 describe('features', () => {
   describe('FEATURES', () => {
-    it('should have 10 features defined', () => {
+    it('应该有10个功能定义', () => {
       expect(FEATURES).toHaveLength(10);
     });
 
-    it('should have all required properties for each feature', () => {
+    it('应该有每个功能的所有必需属性', () => {
       FEATURES.forEach((feature) => {
         expect(feature).toHaveProperty('key');
         expect(feature).toHaveProperty('label');
@@ -29,7 +29,6 @@ describe('features', () => {
         expect(feature.components).toHaveProperty('sidepanel');
         expect(feature.components).toHaveProperty('tab');
 
-        // Optional UI properties for non-hidden features
         if (feature.key !== 'dashboard') {
           expect(feature).toHaveProperty('icon');
           expect(feature).toHaveProperty('themeColorKey');
@@ -38,7 +37,7 @@ describe('features', () => {
       });
     });
 
-    it('should have unique keys for each feature', () => {
+    it('应该有每个功能的唯一key', () => {
       const keys = FEATURES.map((f) => f.key);
       const uniqueKeys = new Set(keys);
       expect(uniqueKeys.size).toBe(keys.length);
@@ -46,14 +45,14 @@ describe('features', () => {
   });
 
   describe('getFeatureByKey', () => {
-    it('should return dashboard feature', () => {
+    it('应该返回dashboard功能', () => {
       const feature = getFeatureByKey('dashboard');
       expect(feature).toBeDefined();
       expect(feature?.key).toBe('dashboard');
       expect(feature?.label).toBe('仪表盘');
     });
 
-    it('should return timestamp feature', () => {
+    it('应该返回时间戳功能', () => {
       const feature = getFeatureByKey('timestamp');
       expect(feature).toBeDefined();
       expect(feature?.key).toBe('timestamp');
@@ -61,21 +60,21 @@ describe('features', () => {
       expect(feature?.themeColorKey).toBeDefined();
     });
 
-    it('should return storageCleaner feature', () => {
+    it('应该返回存储清理功能', () => {
       const feature = getFeatureByKey('storageCleaner');
       expect(feature).toBeDefined();
       expect(feature?.key).toBe('storageCleaner');
       expect(feature?.label).toBe('存储清理');
     });
 
-    it('should return undefined for invalid key', () => {
+    it('应该返回undefined用于无效的key', () => {
       const feature = getFeatureByKey('invalid' as any);
       expect(feature).toBeUndefined();
     });
   });
 
   describe('getDefaultVisibleFeatureKeys', () => {
-    it('should return only visible features', () => {
+    it('应该返回仅可见的功能', () => {
       const visibleKeys = getDefaultVisibleFeatureKeys();
       visibleKeys.forEach((key) => {
         const feature = getFeatureByKey(key);
@@ -83,7 +82,7 @@ describe('features', () => {
       });
     });
 
-    it('should include dashboard, timestamp, storageCleaner, qrCode', () => {
+    it('应该包含仪表盘、时间戳、存储清理、二维码', () => {
       const visibleKeys = getDefaultVisibleFeatureKeys();
       expect(visibleKeys).toContain('dashboard');
       expect(visibleKeys).toContain('timestamp');
@@ -93,7 +92,7 @@ describe('features', () => {
   });
 
   describe('getAllFeatureKeys', () => {
-    it('should return all feature keys', () => {
+    it('应该返回所有功能key', () => {
       const allKeys = getAllFeatureKeys();
       expect(allKeys).toHaveLength(10);
       expect(allKeys).toContain('dashboard');
@@ -102,7 +101,7 @@ describe('features', () => {
       expect(allKeys).toContain('qrCode');
       expect(allKeys).toContain('textStatistics');
       expect(allKeys).toContain('jwt');
-      expect(allKeys).toContain('jsonDiff');
+      expect(allKeys).toContain('jsonTools');
       expect(allKeys).toContain('base64Converter');
       expect(allKeys).toContain('rightClickRestorer');
       expect(allKeys).toContain('testDataGenerator');
@@ -110,19 +109,19 @@ describe('features', () => {
   });
 
   describe('getDefaultPageOrder', () => {
-    it('should exclude dashboard from page order', () => {
+    it('应该排除仪表盘从页面顺序', () => {
       const pageOrder = getDefaultPageOrder();
       expect(pageOrder).not.toContain('dashboard');
     });
 
-    it('should include timestamp, storageCleaner, qrCode in page order', () => {
+    it('应该包含时间戳、存储清理、二维码在页面顺序', () => {
       const pageOrder = getDefaultPageOrder();
       expect(pageOrder).toContain('timestamp');
       expect(pageOrder).toContain('storageCleaner');
       expect(pageOrder).toContain('qrCode');
     });
 
-    it('should have 9 items in page order', () => {
+    it('应该有9个项目在页面顺序', () => {
       const pageOrder = getDefaultPageOrder();
       expect(pageOrder).toHaveLength(9);
     });

src/config/features.tsx

@@ -119,7 +119,7 @@ export const FEATURES: FeatureConfig[] = [
     },
   },
   {
-    key: 'jsonDiff',
+    key: 'jsonTools',
     label: 'JSON 工具',
     description: '差异比较、格式化、YAML/TOML 转换及压缩',
     themeColorKey: 'primary',

src/entrypoints/README.md

@@ -1,51 +0,0 @@
-# entrypoints/
-
-WXT 框架要求的扩展生命周期入口点，对应 Chrome Extension 的各个上下文。
-
-## 入口文件
-
-| 文件                            | 用途                                                                                          |
-| ------------------------------- | --------------------------------------------------------------------------------------------- |
-| `background.ts`                 | Service Worker 入口：注册右键菜单、监听菜单点击、处理消息通信、管理侧边栏状态、注入主环境脚本 |
-| `content.ts`                    | Content Script 入口：注入所有页面（`<all_urls>`），在 `document_end` 时初始化消息处理器       |
-| `rightClickRestorer.content.ts` | 专用 Content Script：处理右键菜单恢复功能，注入浮动状态徽章                                   |
-
-## 子目录
-
-### popup/
-
-Popup 弹窗页面（点击扩展图标弹出）。
-
-| 文件         | 用途                                                                           |
-| ------------ | ------------------------------------------------------------------------------ |
-| `index.html` | HTML 入口                                                                      |
-| `main.tsx`   | React 挂载点                                                                   |
-| `App.tsx`    | 根组件，组装 `RouterProvider` + `TopBar` + `ErrorBoundary` + `RouterContainer` |
-
-### sidepanel/
-
-侧边栏页面，结构与 popup 类似，额外通知 background 侧边栏开启/关闭状态。
-
-### options/
-
-设置页面，支持：
-
-- 拖拽排序功能顺序（`@dnd-kit`）
-- 功能可见性管理（显示/隐藏）
-- Popup/Sidepanel/Tab 三种模式独立配置
-
-### content/
-
-Content Script 内部分模块：
-
-| 文件                    | 用途                                                                |
-| ----------------------- | ------------------------------------------------------------------- |
-| `messageHandler.ts`     | 消息处理器初始化入口                                                |
-| `contextMenuHandler.ts` | 右键菜单点击事件处理，执行时间戳转换/文本统计并通过 UI Popover 展示 |
-| `uiPopover.ts`          | 在页面中注入浮层 Popover UI，展示右键菜单操作结果                   |
-
-## 架构说明
-
-- `background.ts` 是扩展的核心协调者，处理跨上下文通信
-- `content.ts` 注入到所有页面，负责接收和处理来自 background 的消息
-- `popup/`、`sidepanel/`、`options/` 共享同一套页面组件（来自 `pages/`），通过 `RouterProvider` 的不同配置实现独立路由

src/entrypoints/background.ts

@@ -65,8 +65,8 @@ export default defineBackground(() => {
     const tabId = sender?.tab?.id;
 
     if (!tabId) {
-      console.warn('[RightClickRestorer] Injection request missing tabId');
-      return { success: false, message: 'Missing tabId' };
+      console.warn('[RightClickRestorer] 注入请求缺少 tabId');
+      return { success: false, message: '缺少 tabId' };
     }
 
     try {
@@ -79,7 +79,7 @@ export default defineBackground(() => {
       return { success: true };
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : String(err);
-      console.error('[RightClickRestorer] executeScript failed:', errorMsg);
+      console.error('[RightClickRestorer] 执行脚本失败:', errorMsg);
       return { success: false, message: errorMsg };
     }
   });

src/entrypoints/content/uiPopover.ts

@@ -137,12 +137,11 @@ function escapeHtml(text: string): string {
 }
 
 function positionPopover(popover: HTMLElement, x: number, y: number): void {
-  // 此时借助 visibility: hidden，元素在隐藏状态下拥有真实的布局高宽
   const rect = popover.getBoundingClientRect();
   const viewportWidth = window.innerWidth;
   const viewportHeight = window.innerHeight;
 
-  let left = x + 8; // 微微追加水平偏置，防范直接遮挡用户的鼠标落点
+  let left = x + 8;
   let top = y + 8;
 
   if (left + rect.width > viewportWidth - 16) {
@@ -178,7 +177,7 @@ function showPopover(
 
     const titleSpan = document.createElement('span');
     titleSpan.className = 'popover-title';
-    titleSpan.textContent = title; // ✅ 强安全性护航
+    titleSpan.textContent = title;
 
     const closeBtn = document.createElement('button');
     closeBtn.className = 'popover-close';
@@ -194,10 +193,9 @@ function showPopover(
 
   const contentContainer = document.createElement('div');
   contentContainer.className = 'popover-content';
-  contentContainer.innerHTML = contentHtml; // 内部拼装的方法已提前完成全消毒转义
+  contentContainer.innerHTML = contentHtml;
   popover.appendChild(contentContainer);
 
-  // 提前移除激活类名，使 visibility: hidden 起效以供测量
   popover.classList.remove('visible');
 
   requestAnimationFrame(() => {
@@ -226,7 +224,6 @@ export function hidePopover(): void {
 }
 
 export function showTimestampResult(x: number, y: number, timestamp: string, result: string): void {
-  // 对外部传来的参数先全数塞入 escapeHtml 大闸进行纯氧化清洗
   const cleanTimestamp = escapeHtml(timestamp);
   const cleanResult = escapeHtml(result);
 
@@ -236,7 +233,7 @@ export function showTimestampResult(x: number, y: number, timestamp: string, res
     <div class="popover-label">转换结果</div>
     <div class="popover-value">${cleanResult}</div>
   `;
-  showPopover(x, y, content, '⏰ 时间戳转换');
+  showPopover(x, y, content, '转换结果');
 }
 
 export function showTextStatsResult(
@@ -246,7 +243,6 @@ export function showTextStatsResult(
   stats: { characters: number; words: number; lines: number; bytes: number },
 ): void {
   const truncatedText = text.length > 50 ? text.substring(0, 50) + '...' : text;
-  // 对选中的脏文本先进行严格转义
   const cleanText = escapeHtml(truncatedText);
 
   const content = `
@@ -271,5 +267,5 @@ export function showTextStatsResult(
       </div>
     </div>
   `;
-  showPopover(x, y, content, '📊 文本统计');
+  showPopover(x, y, content, '统计结果');
 }

src/entrypoints/popup/App.tsx

@@ -1,5 +1,5 @@
 import RouterProvider from '@/providers/RouterProvider';
-import TopBar from '@/components/TopBar';
+import TopBar from '@/layout/TopBar';
 import RouterContainer from '@/components/RouterContainer';
 import ErrorBoundary from '@/components/ErrorBoundary';
 import { getEntryPointType } from '@/config/features';

src/entrypoints/popup/index.html

@@ -5,6 +5,19 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Testing Tools - 标签页</title>
     <meta name="manifest.type" content="browser_action" />
+    <script>
+      (function () {
+        try {
+          var raw = localStorage.getItem('snapshot/app/themeMode');
+          var mode = raw ? JSON.parse(raw) : 'system';
+          if (mode !== 'light' && mode !== 'dark' && mode !== 'system') mode = 'system';
+          var isDark =
+            mode === 'dark' ||
+            (mode === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
+          if (isDark) document.documentElement.classList.add('dark');
+        } catch (_error) {}
+      })();
+    </script>
     <style>
       /* Force initial popup size before React hydration */
       html, body {

src/entrypoints/popup/main.tsx

@@ -1,8 +1,11 @@
 import ReactDOM from 'react-dom/client';
+import { applyThemeFromSnapshot } from '@/utils/themeSnapshot';
 import AppRoot from '@/providers/AppRoot';
 import '@/index.css';
 import App from './App.tsx';
 
+applyThemeFromSnapshot();
+
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <AppRoot>
     <App />

src/entrypoints/sidepanel/App.tsx

@@ -1,6 +1,6 @@
 import { useEffect } from 'react';
 import RouterProvider from '@/providers/RouterProvider';
-import TopBar from '@/components/TopBar';
+import TopBar from '@/layout/TopBar';
 import RouterContainer from '@/components/RouterContainer';
 import ErrorBoundary from '@/components/ErrorBoundary';
 import { MessageAction, sendMessage } from '@/utils/messages';

src/entrypoints/sidepanel/index.html

@@ -4,6 +4,19 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Testing Tools - Side Panel</title>
+    <script>
+      (function () {
+        try {
+          var raw = localStorage.getItem('snapshot/app/themeMode');
+          var mode = raw ? JSON.parse(raw) : 'system';
+          if (mode !== 'light' && mode !== 'dark' && mode !== 'system') mode = 'system';
+          var isDark =
+            mode === 'dark' ||
+            (mode === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
+          if (isDark) document.documentElement.classList.add('dark');
+        } catch (_error) {}
+      })();
+    </script>
   </head>
   <body>
     <div id="root"></div>

src/entrypoints/sidepanel/main.tsx

@@ -1,8 +1,11 @@
 import ReactDOM from 'react-dom/client';
+import { applyThemeFromSnapshot } from '@/utils/themeSnapshot';
 import AppRoot from '@/providers/AppRoot';
 import '@/index.css';
 import App from './App.tsx';
 
+applyThemeFromSnapshot();
+
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <AppRoot>
     <App />

src/layout/README.md

@@ -0,0 +1,26 @@
+# layout/
+
+应用壳层布局组件目录，存放与扩展入口（popup / sidepanel / tab）绑定的布局 UI，与 `components/` 中的通用可复用组件区分。
+
+## 组件列表
+
+| 目录      | 用途                                                           |
+| --------- | -------------------------------------------------------------- |
+| `TopBar/` | 顶部导航栏：搜索（含历史记录）、主题切换、返回导航、标签页打开 |
+
+## 目录结构
+
+遵循与 `pages/` 相同的 UI + Hook 分离模式：
+
+```
+layout/TopBar/
+├── index.tsx              # 布局入口
+├── useTopBar.ts           # 业务逻辑 Hook
+├── constants.ts           # 常量
+├── SearchInput.tsx        # 搜索输入框
+├── SearchDropdown.tsx     # 搜索结果/历史下拉面板
+├── SearchResultItem.tsx   # 单条搜索结果项
+├── TopBarActions.tsx      # 右侧操作按钮组
+└── __tests__/
+    └── index.test.tsx
+```

src/layout/TopBar/SearchDropdown.tsx

@@ -0,0 +1,45 @@
+import { type FeatureConfig } from '@/config/features';
+import SearchResultItem from './SearchResultItem';
+
+interface SearchDropdownProps {
+  searchQuery: string;
+  searchResults: FeatureConfig[];
+  recentFeatures: FeatureConfig[];
+  selectedIndex: number;
+  onSelect: (feature: FeatureConfig) => void;
+}
+
+export default function SearchDropdown({
+  searchQuery,
+  searchResults,
+  recentFeatures,
+  selectedIndex,
+  onSelect,
+}: SearchDropdownProps) {
+  const isSearching = searchQuery.trim().length > 0;
+  const items = isSearching ? searchResults : recentFeatures;
+
+  return (
+    <div className="absolute left-0 right-0 top-full z-50 mt-1.5 max-h-80 overflow-y-auto rounded-lg border border-border bg-popover text-popover-foreground shadow-lg animate-in fade-in slide-in-from-top-2 duration-150">
+      <ul role="listbox" className="p-1.5">
+        {!isSearching && items.length > 0 && (
+          <div className="px-3 py-1.5 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground/60">
+            最近搜索
+          </div>
+        )}
+        {isSearching && items.length === 0 ? (
+          <li className="px-4 py-6 text-center text-sm text-muted-foreground">未找到相关工具</li>
+        ) : (
+          items.map((feature, index) => (
+            <SearchResultItem
+              key={feature.key}
+              feature={feature}
+              selected={selectedIndex === index}
+              onSelect={onSelect}
+            />
+          ))
+        )}
+      </ul>
+    </div>
+  );
+}

src/layout/TopBar/SearchInput.tsx

@@ -0,0 +1,57 @@
+import { type RefObject } from 'react';
+import { Search, X } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { getSearchShortcutLabel } from './constants';
+
+interface SearchInputProps {
+  inputRef: RefObject<HTMLInputElement | null>;
+  searchQuery: string;
+  onSearchQueryChange: (value: string) => void;
+  onFocus: () => void;
+  onKeyDown: (e: React.KeyboardEvent) => void;
+  onClear: () => void;
+}
+
+export default function SearchInput({
+  inputRef,
+  searchQuery,
+  onSearchQueryChange,
+  onFocus,
+  onKeyDown,
+  onClear,
+}: SearchInputProps) {
+  return (
+    <div className="group relative">
+      <Search className="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground/60 transition-colors group-focus-within:text-muted-foreground" />
+      <Input
+        ref={inputRef}
+        type="text"
+        placeholder="搜索工具..."
+        value={searchQuery}
+        onChange={(e) => onSearchQueryChange(e.target.value)}
+        onFocus={onFocus}
+        onKeyDown={onKeyDown}
+        aria-label="搜索工具..."
+        className="h-9 rounded-lg border-border/60 bg-muted/40 pl-9 pr-16 shadow-none focus-visible:ring-1 focus-visible:ring-offset-0 placeholder:text-muted-foreground/50"
+      />
+      {!searchQuery && (
+        <kbd className="pointer-events-none absolute right-3 top-1/2 hidden h-5 -translate-y-1/2 items-center gap-0.5 rounded border border-border/60 bg-muted px-1.5 font-mono text-[10px] font-medium text-muted-foreground/60 sm:inline-flex">
+          {getSearchShortcutLabel()}
+        </kbd>
+      )}
+      {searchQuery && (
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon"
+          onClick={onClear}
+          aria-label="清除搜索"
+          className="absolute right-1 top-1/2 h-7 w-7 -translate-y-1/2 text-muted-foreground hover:text-foreground"
+        >
+          <X className="h-3 w-3" />
+        </Button>
+      )}
+    </div>
+  );
+}

src/layout/TopBar/SearchResultItem.tsx

@@ -0,0 +1,34 @@
+import React from 'react';
+import { type FeatureConfig } from '@/config/features';
+import { cn } from '@/lib/utils';
+
+interface SearchResultItemProps {
+  feature: FeatureConfig;
+  selected: boolean;
+  onSelect: (feature: FeatureConfig) => void;
+}
+
+const SearchResultItem = React.memo(({ feature, selected, onSelect }: SearchResultItemProps) => {
+  return (
+    <li
+      role="option"
+      aria-selected={selected}
+      onClick={() => onSelect(feature)}
+      className={cn(
+        'flex cursor-pointer items-center gap-3 rounded-md px-3 py-2.5 text-sm transition-colors',
+        selected ? 'bg-accent text-accent-foreground' : 'hover:bg-muted/60',
+      )}
+    >
+      <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg bg-muted/80 text-muted-foreground">
+        {feature.icon && <feature.icon className="h-4 w-4" />}
+      </div>
+      <div className="min-w-0 flex-1">
+        <p className="truncate font-medium text-foreground">{feature.label}</p>
+        <p className="mt-0.5 truncate text-xs text-muted-foreground">{feature.description}</p>
+      </div>
+    </li>
+  );
+});
+SearchResultItem.displayName = 'SearchResultItem';
+
+export default SearchResultItem;

src/layout/TopBar/TopBarActions.tsx

@@ -0,0 +1,34 @@
+import { type LucideIcon } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+
+interface TopBarAction {
+  id: string;
+  icon: LucideIcon;
+  title: string;
+  onClick: () => void;
+}
+
+interface TopBarActionsProps {
+  actions: TopBarAction[];
+}
+
+export default function TopBarActions({ actions }: TopBarActionsProps) {
+  return (
+    <div className="flex shrink-0 items-center gap-1">
+      {actions.map(({ id, icon: Icon, title, onClick }) => (
+        <Button
+          key={id}
+          type="button"
+          variant="ghost"
+          size="icon"
+          onClick={onClick}
+          title={title}
+          aria-label={title}
+          className="h-8 w-8 text-muted-foreground"
+        >
+          <Icon className="h-4 w-4" />
+        </Button>
+      ))}
+    </div>
+  );
+}

src/layout/TopBar/__tests__/constants.test.ts

@@ -0,0 +1,37 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getSearchShortcutLabel } from '@/layout/TopBar/constants';
+
+describe('getSearchShortcutLabel', () => {
+  const originalUserAgent = navigator.userAgent;
+
+  afterEach(() => {
+    vi.stubGlobal('navigator', { ...navigator, userAgent: originalUserAgent });
+  });
+
+  it('macOS 应显示 ⌘K', () => {
+    vi.stubGlobal('navigator', {
+      ...navigator,
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+    });
+    expect(getSearchShortcutLabel()).toBe('⌘K');
+  });
+
+  it('Windows 应显示 Ctrl+K', () => {
+    vi.stubGlobal('navigator', {
+      ...navigator,
+      userAgent:
+        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+    });
+    expect(getSearchShortcutLabel()).toBe('Ctrl+K');
+  });
+
+  it('Linux 应显示 Ctrl+K', () => {
+    vi.stubGlobal('navigator', {
+      ...navigator,
+      userAgent:
+        'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+    });
+    expect(getSearchShortcutLabel()).toBe('Ctrl+K');
+  });
+});

src/layout/TopBar/__tests__/index.test.tsx

@@ -2,7 +2,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { fireEvent, render, screen } from '@testing-library/react';
 import type { PageType } from '@/types/storage';
 import React from 'react';
-import TopBar from '@/components/TopBar';
+import TopBar from '@/layout/TopBar';
 import { RouterProvider } from '@/providers/RouterProvider';
 import { ThemeModeProvider } from '@/providers/ThemeModeProvider';
 
@@ -27,7 +27,7 @@ const mockRouterValue = {
   isLoaded: true,
   navigateTo: vi.fn(),
   syncNavigation: vi.fn(),
-  goBack: vi.fn(),
+  goHome: vi.fn(),
   setVisiblePages: vi.fn(),
   setPageOrder: vi.fn(),
 };
@@ -54,23 +54,23 @@ describe('TopBar 组件', () => {
     it('不在 dashboard 时应渲染返回按钮', () => {
       mockRouterValue.currentPage = 'timestamp';
       renderWithProvider(<TopBar />);
-      expect(screen.getByLabelText('返回')).toBeInTheDocument();
+      expect(screen.getByLabelText('返回首页')).toBeInTheDocument();
     });
 
     it('在 dashboard 上不应渲染返回按钮', () => {
       mockRouterValue.currentPage = 'dashboard';
       renderWithProvider(<TopBar />);
-      expect(screen.queryByLabelText('返回')).not.toBeInTheDocument();
+      expect(screen.queryByLabelText('返回首页')).not.toBeInTheDocument();
     });
   });
 
   describe('交互测试', () => {
-    it('点击返回按钮时应调用 goBack', () => {
+    it('点击返回按钮时应调用 goHome', () => {
       mockRouterValue.currentPage = 'timestamp';
       renderWithProvider(<TopBar />);
 
-      fireEvent.click(screen.getByLabelText('返回'));
-      expect(mockRouterValue.goBack).toHaveBeenCalledTimes(1);
+      fireEvent.click(screen.getByLabelText('返回首页'));
+      expect(mockRouterValue.goHome).toHaveBeenCalledTimes(1);
     });
   });
 });

src/layout/TopBar/constants.ts

@@ -0,0 +1,11 @@
+export const SEARCH_HISTORY_LIMIT = 10;
+export const SEARCH_HISTORY_DISPLAY = 5;
+
+export const isSearchHistory = (val: unknown): val is string[] =>
+  Array.isArray(val) && val.every((item) => typeof item === 'string');
+
+/** 根据平台返回搜索框快捷键提示文案 */
+export function getSearchShortcutLabel(): string {
+  if (typeof navigator === 'undefined') return 'Ctrl+K';
+  return /Mac|iPhone|iPad|iPod/i.test(navigator.userAgent) ? '⌘K' : 'Ctrl+K';
+}

src/layout/TopBar/index.tsx

@@ -0,0 +1,91 @@
+import { ArrowLeft, ExternalLink } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import SearchDropdown from './SearchDropdown';
+import SearchInput from './SearchInput';
+import TopBarActions from './TopBarActions';
+import { useTopBar } from './useTopBar';
+
+export default function TopBar() {
+  const {
+    searchQuery,
+    showResults,
+    searchResults,
+    recentFeatures,
+    selectedIndex,
+    isDashboard,
+    ThemeIcon,
+    themeTitle,
+    containerRef,
+    inputRef,
+    setSearchQuery,
+    setShowResults,
+    setSelectedIndex,
+    handleSelectFeature,
+    handleKeyDown,
+    cycleThemeMode,
+    handleOpenInTab,
+    goHome,
+    clearSearch,
+  } = useTopBar();
+
+  const actions = [
+    { id: 'theme', icon: ThemeIcon, title: themeTitle, onClick: cycleThemeMode },
+    {
+      id: 'open-in-tab',
+      icon: ExternalLink,
+      title: '在标签页打开',
+      onClick: () => {
+        void handleOpenInTab();
+      },
+    },
+  ];
+
+  const handleSearchQueryChange = (value: string) => {
+    setSearchQuery(value);
+    setShowResults(true);
+    setSelectedIndex(-1);
+  };
+
+  const showDropdown = showResults && (searchQuery.trim() || recentFeatures.length > 0);
+
+  return (
+    <header className="relative z-50 flex h-14 items-center justify-between border-b border-border bg-background px-4">
+      <div className="flex w-10 items-center justify-start">
+        {!isDashboard && (
+          <Button
+            type="button"
+            variant="outline"
+            size="icon"
+            onClick={goHome}
+            aria-label="返回首页"
+            className="h-8 w-8 shadow-sm text-muted-foreground"
+          >
+            <ArrowLeft className="h-4 w-4" />
+          </Button>
+        )}
+      </div>
+
+      <div ref={containerRef} className="relative mx-4 max-w-md flex-1">
+        <SearchInput
+          inputRef={inputRef}
+          searchQuery={searchQuery}
+          onSearchQueryChange={handleSearchQueryChange}
+          onFocus={() => setShowResults(true)}
+          onKeyDown={handleKeyDown}
+          onClear={clearSearch}
+        />
+        {showDropdown && (
+          <SearchDropdown
+            searchQuery={searchQuery}
+            searchResults={searchResults}
+            recentFeatures={recentFeatures}
+            selectedIndex={selectedIndex}
+            onSelect={handleSelectFeature}
+          />
+        )}
+      </div>
+
+      <TopBarActions actions={actions} />
+    </header>
+  );
+}

src/layout/TopBar/useTopBar.ts

@@ -0,0 +1,171 @@
+import { useEffect, useMemo, useRef, useState, type RefObject } from 'react';
+import { Monitor, Moon, Sun } from 'lucide-react';
+import { useRouter } from '@/providers/RouterProvider';
+import { useThemeMode } from '@/providers/ThemeModeProvider';
+import { type FeatureConfig, FEATURES } from '@/config/features';
+import { useStorageState } from '@/utils/useStorageState';
+import { openExtensionPage } from '@/utils/chromeTabs';
+import { isSearchHistory, SEARCH_HISTORY_DISPLAY, SEARCH_HISTORY_LIMIT } from './constants';
+
+export interface UseTopBarReturn {
+  searchQuery: string;
+  showResults: boolean;
+  searchResults: FeatureConfig[];
+  recentFeatures: FeatureConfig[];
+  selectedIndex: number;
+  isDashboard: boolean;
+  ThemeIcon: typeof Sun;
+  themeTitle: string;
+  containerRef: RefObject<HTMLDivElement | null>;
+  inputRef: RefObject<HTMLInputElement | null>;
+  setSearchQuery: (value: string) => void;
+  setShowResults: (value: boolean) => void;
+  setSelectedIndex: (value: number | ((prev: number) => number)) => void;
+  handleSelectFeature: (feature: FeatureConfig) => void;
+  handleKeyDown: (e: React.KeyboardEvent) => void;
+  cycleThemeMode: () => void;
+  handleOpenInTab: () => Promise<void>;
+  goHome: () => void;
+  clearSearch: () => void;
+}
+
+export function useTopBar(): UseTopBarReturn {
+  const { currentPage, goHome, navigateTo } = useRouter();
+  const { mode, setMode } = useThemeMode();
+
+  const [searchQuery, setSearchQuery] = useState('');
+  const [showResults, setShowResults] = useState(false);
+  const [searchHistory, setSearchHistory] = useStorageState(
+    'app/searchHistory',
+    [],
+    isSearchHistory,
+  );
+  const [selectedIndex, setSelectedIndex] = useState(-1);
+
+  const containerRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const handleOpenInTab = async () => {
+    await openExtensionPage('popup.html', { mode: 'tab' });
+    window.close();
+  };
+
+  useEffect(() => {
+    const handleClickOutside = (event: MouseEvent) => {
+      if (containerRef.current && !containerRef.current.contains(event.target as Node)) {
+        setShowResults(false);
+      }
+    };
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, []);
+
+  useEffect(() => {
+    const handleGlobalKeyDown = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+        e.preventDefault();
+        inputRef.current?.focus();
+        setShowResults(true);
+      }
+    };
+    document.addEventListener('keydown', handleGlobalKeyDown);
+    return () => document.removeEventListener('keydown', handleGlobalKeyDown);
+  }, []);
+
+  const searchResults = useMemo(() => {
+    const query = searchQuery.trim().toLowerCase();
+    if (!query) return [];
+    return FEATURES.filter((f) => {
+      if (f.key === 'dashboard') return false;
+      return f.label.toLowerCase().includes(query) || f.description.toLowerCase().includes(query);
+    });
+  }, [searchQuery]);
+
+  const displayedHistory = useMemo(() => {
+    if (searchQuery.trim()) return [];
+    return searchHistory
+      .slice(0, SEARCH_HISTORY_DISPLAY)
+      .map((key) => FEATURES.find((f) => f.key === key))
+      .filter((feature): feature is FeatureConfig => !!feature && feature.key !== 'dashboard');
+  }, [searchHistory, searchQuery]);
+
+  const saveToHistory = (featureKey: string) => {
+    if (!featureKey.trim()) return;
+    setSearchHistory((prev) =>
+      [featureKey, ...prev.filter((h) => h !== featureKey)].slice(0, SEARCH_HISTORY_LIMIT),
+    );
+  };
+
+  const handleSelectFeature = (feature: FeatureConfig) => {
+    navigateTo(feature.key);
+    saveToHistory(feature.key);
+    setSearchQuery('');
+    setShowResults(false);
+  };
+
+  const cycleThemeMode = () => {
+    const nextMap = { light: 'dark', dark: 'system', system: 'light' } as const;
+    setMode(nextMap[mode]);
+  };
+
+  const ThemeIcon = mode === 'light' ? Sun : mode === 'dark' ? Moon : Monitor;
+
+  const themeTitle =
+    mode === 'light' ? '切换到深色模式' : mode === 'dark' ? '切换到系统模式' : '切换到浅色模式';
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    const totalItems = searchQuery.trim() ? searchResults.length : displayedHistory.length;
+
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      setSelectedIndex((prev) => (prev < totalItems - 1 ? prev + 1 : prev));
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      setSelectedIndex((prev) => (prev > 0 ? prev - 1 : prev));
+    } else if (e.key === 'Enter') {
+      e.preventDefault();
+      if (selectedIndex >= 0 && selectedIndex < totalItems) {
+        if (searchQuery.trim()) {
+          handleSelectFeature(searchResults[selectedIndex]);
+        } else {
+          const selected = displayedHistory[selectedIndex];
+          if (selected) {
+            handleSelectFeature(selected);
+          }
+        }
+      } else if (searchQuery.trim() && searchResults.length > 0) {
+        handleSelectFeature(searchResults[0]);
+      }
+    } else if (e.key === 'Escape') {
+      setShowResults(false);
+      inputRef.current?.blur();
+    }
+  };
+
+  const clearSearch = () => {
+    setSearchQuery('');
+    setSelectedIndex(-1);
+  };
+
+  return {
+    searchQuery,
+    showResults,
+    searchResults,
+    recentFeatures: displayedHistory,
+    selectedIndex,
+    isDashboard: currentPage === 'dashboard',
+    ThemeIcon,
+    themeTitle,
+    containerRef,
+    inputRef,
+    setSearchQuery,
+    setShowResults,
+    setSelectedIndex,
+    handleSelectFeature,
+    handleKeyDown,
+    cycleThemeMode,
+    handleOpenInTab,
+    goHome,
+    clearSearch,
+  };
+}

src/lib/README.md

@@ -4,9 +4,10 @@
 
 ## 文件说明
 
-| 文件       | 用途                                 |
-| ---------- | ------------------------------------ |
+| 文件/目录     | 用途                                   |
+| ------------- | -------------------------------------- |
 | `utils.ts`    | `cn()` 函数 — shadcn/ui 标准工具函数   |
+| `generators/` | 测试数据生成器内置生成器库和分类注册表 |
 
 ## cn()
 
@@ -24,3 +25,32 @@ import { cn } from '@/lib/utils';
 ```
 
 所有需要动态合并 Tailwind 类名的场景都应使用 `cn()`，而非手动拼接字符串。
+
+## generators/
+
+测试数据生成器的核心生成器库，供 `src/workers/generator.worker.ts` 在后台线程中按字段配置生成数据。
+
+| 文件           | 用途                                           |
+| -------------- | ---------------------------------------------- |
+| `index.ts`     | 聚合所有生成器，导出分类、查找和搜索函数       |
+| `personal.ts`  | 个人信息生成器（姓名、邮箱、手机号、身份证等） |
+| `business.ts`  | 业务数据生成器（订单号、价格、日期、状态等）   |
+| `technical.ts` | 技术数据生成器（UUID、IPv4、URL）              |
+| `basic.ts`     | 基础类型生成器（整数、浮点数、布尔值、字符串） |
+| `types.ts`     | 生成器库内部类型与通用选项                     |
+
+使用示例：
+
+```typescript
+import { getGeneratorById, searchGenerators } from '@/lib/generators';
+
+const generator = getGeneratorById('chineseName');
+const value = generator?.generate({});
+const matched = searchGenerators('uuid');
+```
+
+约束：
+
+- 新增生成器必须实现 `GeneratorDefinition`，并加入所属分类文件的导出列表。
+- 需要唯一值或大批量稳定输出时，优先实现 `generateAtIndex(params, index)`。
+- 新增分类时同步更新 `generatorCategories`，并确保 `GeneratorSelector` 能展示该分类。

src/lib/generators/__tests__/random.test.ts

@@ -0,0 +1,22 @@
+import { randomInt, randomPick } from '@/lib/generators/random';
+
+describe('generators/random', () => {
+  it('randomInt 应返回闭区间内的整数', () => {
+    vi.spyOn(Math, 'random').mockReturnValue(0.5);
+
+    expect(randomInt(1, 10)).toBe(6);
+    expect(randomInt(5, 5)).toBe(5);
+  });
+
+  it('randomPick 应对单元素数组返回该元素', () => {
+    vi.spyOn(Math, 'random').mockReturnValue(0);
+
+    expect(randomPick(['only'])).toBe('only');
+  });
+
+  it('randomPick 应返回数组中的元素', () => {
+    vi.spyOn(Math, 'random').mockReturnValue(0.99);
+
+    expect(randomPick(['a', 'b', 'c'])).toBe('c');
+  });
+});

src/lib/generators/basic.ts

@@ -4,20 +4,7 @@
  */
 
 import type { GeneratorDefinition } from '@/types/testDataGenerator';
-
-/**
- * 生成随机整数
- */
-function randomInt(min: number, max: number): number {
-  return Math.floor(Math.random() * (max - min + 1)) + min;
-}
-
-/**
- * 从数组中随机选择
- */
-function randomPick<T>(arr: T[]): T {
-  return arr[Math.floor(Math.random() * arr.length)];
-}
+import { randomInt, randomPick } from './random';
 
 /**
  * 随机整数生成器

src/lib/generators/business.ts

@@ -4,20 +4,7 @@
  */
 
 import type { GeneratorDefinition } from '@/types/testDataGenerator';
-
-/**
- * 生成随机整数
- */
-function randomInt(min: number, max: number): number {
-  return Math.floor(Math.random() * (max - min + 1)) + min;
-}
-
-/**
- * 从数组中随机选择
- */
-function randomPick<T>(arr: T[]): T {
-  return arr[Math.floor(Math.random() * arr.length)];
-}
+import { randomInt, randomPick } from './random';
 
 /**
  * 格式化日期
@@ -434,7 +421,7 @@ function skewedRandom(min: number, max: number): number {
     v = 0;
   while (u === 0) u = Math.random();
   while (v === 0) v = Math.random();
-  const x = Math.pow(u, 1 / alpha) / Math.pow(u, 1 / alpha) + Math.pow(v, 1 / beta);
+  const x = Math.pow(u, 1 / alpha) / (Math.pow(u, 1 / alpha) + Math.pow(v, 1 / beta));
   return min + x * (max - min);
 }
 

src/lib/generators/personal.ts

@@ -4,6 +4,7 @@
  */
 
 import type { GeneratorDefinition } from '@/types/testDataGenerator';
+import { randomInt, randomPick } from './random';
 
 // 中文姓氏
 const SURNAMES = [
@@ -162,20 +163,6 @@ const CITIES: Record<string, string[]> = {
   四川省: ['成都市', '绵阳市', '德阳市', '宜宾市'],
 };
 
-/**
- * 生成随机整数
- */
-function randomInt(min: number, max: number): number {
-  return Math.floor(Math.random() * (max - min + 1)) + min;
-}
-
-/**
- * 从数组中随机选择
- */
-function randomPick<T>(arr: T[]): T {
-  return arr[Math.floor(Math.random() * arr.length)];
-}
-
 /**
  * 中文姓名生成器
  */

src/lib/generators/random.ts

@@ -0,0 +1,7 @@
+export function randomInt(min: number, max: number): number {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+export function randomPick<T>(arr: readonly T[]): T {
+  return arr[Math.floor(Math.random() * arr.length)];
+}

src/lib/generators/technical.ts

@@ -4,20 +4,7 @@
  */
 
 import type { GeneratorDefinition } from '@/types/testDataGenerator';
-
-/**
- * 生成随机整数
- */
-function randomInt(min: number, max: number): number {
-  return Math.floor(Math.random() * (max - min + 1)) + min;
-}
-
-/**
- * 从数组中随机选择
- */
-function randomPick<T>(arr: T[]): T {
-  return arr[Math.floor(Math.random() * arr.length)];
-}
+import { randomInt, randomPick } from './random';
 
 /**
  * UUID 生成器

src/pages/Base64Converter/components/Base64ConverterSection.tsx

@@ -41,6 +41,7 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
     setCustomFileName,
     resetAll,
     safeFileSelect,
+    maxFileSizeStr,
   } = useBase64Converter({ mode });
 
   const handleDirectionChange = (next: Base64ConvertDirection) => {
@@ -136,7 +137,7 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
                   {mode === 'image' ? '点击或拖拽图像到此处' : '点击或拖拽文件到此处'}
                 </span>
                 <span className="text-[10px] font-medium text-muted-foreground/60">
-                  {'最大文件大小：{{max}}'}
+                  {`最大文件大小：${maxFileSizeStr}`}
                 </span>
                 {mode === 'image' && (
                   <span className="text-[10px] font-medium text-muted-foreground/50">

src/pages/Base64Converter/components/DecodeResultPaper.tsx

@@ -14,7 +14,7 @@ import { Label } from '@/components/ui/label';
 import { formatBytes } from '@/utils/format';
 
 interface DecodeResultPaperProps {
-  /** 标题文案，由调用方传入 i18n key 对应的值（如 decodedFileOutput / decodedImageOutput） */
+  /** 标题文案 */
   title: string;
   /** 解码后推断的 MIME 类型 */
   mimeType: string;

src/pages/Dashboard/__tests__/dashboardFeatures.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import * as featureConfig from '@/config/features';
+import { resolveDashboardFeatures } from '../dashboardFeatures';
+
+describe('resolveDashboardFeatures', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('应按 keys 顺序返回可见工具，并排除 dashboard', () => {
+    const items = resolveDashboardFeatures(['jwt', 'timestamp'], ['dashboard', 'timestamp', 'jwt']);
+
+    expect(items.map((item) => item.key)).toEqual(['jwt', 'timestamp']);
+    expect(items.map((item) => item.feature.label)).toEqual(['JWT 解析', '时间戳']);
+  });
+
+  it('缺少 themeColorKey 但有 icon 的工具仍应显示', () => {
+    const originalGetFeatureByKey = featureConfig.getFeatureByKey;
+    vi.spyOn(featureConfig, 'getFeatureByKey').mockImplementation((key) => {
+      const feature = originalGetFeatureByKey(key);
+      if (key === 'timestamp' && feature) {
+        return { ...feature, themeColorKey: undefined };
+      }
+      return feature;
+    });
+
+    const items = resolveDashboardFeatures(['timestamp'], ['dashboard', 'timestamp']);
+
+    expect(items.map((item) => item.key)).toEqual(['timestamp']);
+  });
+
+  it('应过滤不在 visiblePages 中的工具', () => {
+    const items = resolveDashboardFeatures(['jwt', 'timestamp'], ['dashboard', 'timestamp']);
+
+    expect(items.map((item) => item.key)).toEqual(['timestamp']);
+  });
+
+  it('visiblePages 无匹配工具时应返回空列表', () => {
+    const items = resolveDashboardFeatures(['jwt', 'timestamp'], ['dashboard']);
+
+    expect(items).toEqual([]);
+  });
+
+  it('应过滤缺少 icon 的工具', () => {
+    const items = resolveDashboardFeatures(['dashboard', 'timestamp'], ['dashboard', 'timestamp']);
+
+    expect(items.map((item) => item.key)).toEqual(['timestamp']);
+  });
+});

src/pages/Dashboard/__tests__/index.test.tsx

@@ -0,0 +1,100 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { getFeatureByKey } from '@/config/features';
+import type { DashboardFeatureItem } from '../useDashboard';
+import Index from '../index';
+
+const mockNavigateTo = vi.fn();
+const mockUseDashboard = vi.fn();
+
+vi.mock('../useDashboard', () => ({
+  useDashboard: () => mockUseDashboard(),
+}));
+
+function buildFeatureItem(key: 'timestamp' | 'jwt'): DashboardFeatureItem {
+  const feature = getFeatureByKey(key)!;
+  return {
+    key,
+    feature: feature as DashboardFeatureItem['feature'],
+  };
+}
+
+describe('Dashboard 页面', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockUseDashboard.mockReturnValue({
+      visibleFeatures: [buildFeatureItem('timestamp'), buildFeatureItem('jwt')],
+      recentFeatures: [],
+      showRecent: false,
+      navigateTo: mockNavigateTo,
+    });
+  });
+
+  it('应渲染全部工具网格', () => {
+    render(<Index />);
+
+    expect(screen.getByText('全部工具')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: '时间戳' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'JWT 解析' })).toBeInTheDocument();
+  });
+
+  it('点击工具卡片应触发 navigateTo', async () => {
+    const user = userEvent.setup();
+    render(<Index />);
+
+    await user.click(screen.getByRole('button', { name: '时间戳' }));
+
+    expect(mockNavigateTo).toHaveBeenCalledTimes(1);
+    expect(mockNavigateTo).toHaveBeenCalledWith('timestamp');
+  });
+
+  it('有最近使用数据时应显示最近使用区块', () => {
+    mockUseDashboard.mockReturnValue({
+      visibleFeatures: [buildFeatureItem('timestamp')],
+      recentFeatures: [buildFeatureItem('jwt')],
+      showRecent: true,
+      navigateTo: mockNavigateTo,
+    });
+
+    render(<Index />);
+
+    expect(screen.getByText('最近使用')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'JWT 解析' })).toBeInTheDocument();
+  });
+
+  it('无最近使用数据时不应显示最近使用区块', () => {
+    render(<Index />);
+
+    expect(screen.queryByText('最近使用')).not.toBeInTheDocument();
+  });
+
+  it('点击最近使用按钮应触发 navigateTo', async () => {
+    const user = userEvent.setup();
+    mockUseDashboard.mockReturnValue({
+      visibleFeatures: [buildFeatureItem('timestamp')],
+      recentFeatures: [buildFeatureItem('jwt')],
+      showRecent: true,
+      navigateTo: mockNavigateTo,
+    });
+
+    render(<Index />);
+
+    await user.click(screen.getByRole('button', { name: 'JWT 解析' }));
+
+    expect(mockNavigateTo).toHaveBeenCalledWith('jwt');
+  });
+
+  it('无可见工具时应显示空状态', () => {
+    mockUseDashboard.mockReturnValue({
+      visibleFeatures: [],
+      recentFeatures: [],
+      showRecent: false,
+      navigateTo: mockNavigateTo,
+    });
+
+    render(<Index />);
+
+    expect(screen.getByText('没有可用的工具')).toBeInTheDocument();
+  });
+});

src/pages/Dashboard/__tests__/useDashboard.test.ts

@@ -0,0 +1,78 @@
+import { renderHook } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { useRouter } from '@/providers/RouterProvider';
+import { useDashboard } from '../useDashboard';
+import type { PageType } from '@/types/storage';
+
+vi.mock('@/providers/RouterProvider', () => ({
+  useRouter: vi.fn(),
+}));
+
+const mockNavigateTo = vi.fn();
+
+function mockRouterState(
+  overrides: {
+    visiblePages?: PageType[];
+    pageOrder?: PageType[];
+    recentlyUsedTools?: PageType[];
+  } = {},
+) {
+  vi.mocked(useRouter).mockReturnValue({
+    currentPage: 'dashboard',
+    visiblePages: overrides.visiblePages ?? ['dashboard', 'timestamp', 'jwt'],
+    pageOrder: overrides.pageOrder ?? ['jwt', 'timestamp'],
+    recentlyUsedTools: overrides.recentlyUsedTools ?? [],
+    isLoaded: true,
+    navigateTo: mockNavigateTo,
+    goHome: vi.fn(),
+    setVisiblePages: vi.fn(),
+    setPageOrder: vi.fn(),
+  });
+}
+
+describe('useDashboard', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('应透传 router 中的 navigateTo', () => {
+    mockRouterState();
+
+    const { result } = renderHook(() => useDashboard());
+
+    expect(result.current.navigateTo).toBe(mockNavigateTo);
+  });
+
+  it('recentlyUsedTools 有可见工具时应显示最近使用', () => {
+    mockRouterState({
+      visiblePages: ['dashboard', 'timestamp', 'jwt'],
+      recentlyUsedTools: ['timestamp', 'jwt'],
+    });
+
+    const { result } = renderHook(() => useDashboard());
+
+    expect(result.current.showRecent).toBe(true);
+    expect(result.current.recentFeatures.map((item) => item.key)).toEqual(['timestamp', 'jwt']);
+  });
+
+  it('recentlyUsedTools 为空时不应显示最近使用', () => {
+    mockRouterState({ recentlyUsedTools: [] });
+
+    const { result } = renderHook(() => useDashboard());
+
+    expect(result.current.showRecent).toBe(false);
+    expect(result.current.recentFeatures).toEqual([]);
+  });
+
+  it('最近使用中的不可见工具应被过滤', () => {
+    mockRouterState({
+      visiblePages: ['dashboard', 'timestamp'],
+      recentlyUsedTools: ['jwt', 'timestamp'],
+    });
+
+    const { result } = renderHook(() => useDashboard());
+
+    expect(result.current.showRecent).toBe(true);
+    expect(result.current.recentFeatures.map((item) => item.key)).toEqual(['timestamp']);
+  });
+});

src/pages/Dashboard/dashboardFeatures.ts

@@ -0,0 +1,38 @@
+import { getFeatureByKey, type FeatureConfig } from '@/config/features';
+import type { PageType } from '@/types/storage';
+
+export type DashboardFeature = FeatureConfig & {
+  icon: NonNullable<FeatureConfig['icon']>;
+};
+
+export interface DashboardFeatureItem {
+  key: PageType;
+  feature: DashboardFeature;
+}
+
+function isDashboardFeature(feature: FeatureConfig): feature is DashboardFeature {
+  return feature.icon != null;
+}
+
+/**
+ * 将页面 key 列表解析为 Dashboard 可展示的工具项。
+ * 过滤条件：在 visiblePages 中且 feature 配置了 icon。
+ */
+export function resolveDashboardFeatures(
+  keys: PageType[],
+  visiblePages: PageType[],
+): DashboardFeatureItem[] {
+  const visibleSet = new Set(visiblePages);
+  const items: DashboardFeatureItem[] = [];
+
+  for (const key of keys) {
+    if (!visibleSet.has(key)) continue;
+
+    const feature = getFeatureByKey(key);
+    if (!feature || !isDashboardFeature(feature)) continue;
+
+    items.push({ key, feature });
+  }
+
+  return items;
+}

src/pages/Dashboard/index.tsx

@@ -1,28 +1,11 @@
-import { useRouter } from '@/providers/RouterProvider';
-import { getFeatureByKey } from '@/config/features';
-import type { PageType } from '@/types/storage';
 import { cn } from '@/lib/utils';
+import { useDashboard } from './useDashboard';
 
 export default function Index() {
-  const { navigateTo, visiblePages, pageOrder, recentlyUsedTools } = useRouter();
-
-  const visibleSet = new Set<string>(visiblePages);
-
-  const visibleFeatures = pageOrder
-    .filter((key) => visibleSet.has(key))
-    .map((key) => ({ key, feature: getFeatureByKey(key) }))
-    .filter((item) => item.feature?.themeColorKey && item.feature.icon != null);
-
-  const recentFeatures = recentlyUsedTools
-    .filter((key) => visibleSet.has(key))
-    .map((key) => ({ key, feature: getFeatureByKey(key) }))
-    .filter((item) => item.feature?.themeColorKey && item.feature.icon != null);
-
-  const showRecent = recentFeatures.length > 0;
+  const { visibleFeatures, recentFeatures, showRecent, navigateTo } = useDashboard();
 
   return (
     <div className={cn('flex flex-col gap-4 p-3.5 w-full h-auto select-none')}>
-      {/* 最近使用 */}
       {showRecent && (
         <div className="flex flex-col gap-2">
           <h3 className="text-xs font-semibold text-muted-foreground/80 uppercase tracking-wider">
@@ -30,12 +13,12 @@ export default function Index() {
           </h3>
           <div className="flex flex-wrap gap-2">
             {recentFeatures.map(({ key, feature }) => {
-              const IconComponent = feature!.icon!;
+              const IconComponent = feature.icon;
               return (
                 <button
                   key={key}
                   type="button"
-                  onClick={() => navigateTo(key as PageType)}
+                  onClick={() => navigateTo(key)}
                   className={cn(
                     'inline-flex items-center gap-1.5 px-3 py-1.5 rounded-full text-xs font-medium',
                     'border border-border/60 bg-card text-card-foreground',
@@ -44,7 +27,7 @@ export default function Index() {
                   )}
                 >
                   <IconComponent className="h-3.5 w-3.5 text-muted-foreground/70" />
-                  {feature!.label}
+                  {feature.label}
                 </button>
               );
             })}
@@ -52,19 +35,23 @@ export default function Index() {
         </div>
       )}
 
-      {/* 全部工具 — 紧凑 Grid */}
       <div className="flex flex-col gap-2">
         <h3 className="text-xs font-semibold text-muted-foreground/80 uppercase tracking-wider">
           {'全部工具'}
         </h3>
-        <div className={cn('grid grid-cols-3 sm:grid-cols-4 md:grid-cols-5 lg:grid-cols-6 gap-2')}>
+        {visibleFeatures.length === 0 ? (
+          <p className="text-sm text-muted-foreground py-4 text-center">{'没有可用的工具'}</p>
+        ) : (
+          <div
+            className={cn('grid grid-cols-3 sm:grid-cols-4 md:grid-cols-5 lg:grid-cols-6 gap-2')}
+          >
             {visibleFeatures.map(({ key, feature }) => {
-            const IconComponent = feature!.icon!;
+              const IconComponent = feature.icon;
               return (
                 <button
                   key={key}
                   type="button"
-                onClick={() => navigateTo(key as PageType)}
+                  onClick={() => navigateTo(key)}
                   className={cn(
                     'group flex flex-col items-center justify-center gap-1.5',
                     'py-3 px-2 rounded-xl border border-border/50 bg-card',
@@ -80,12 +67,13 @@ export default function Index() {
                     )}
                   />
                   <span className="text-[11px] font-medium text-muted-foreground/80 group-hover:text-foreground leading-tight text-center truncate w-full transition-colors">
-                  {feature!.label}
+                    {feature.label}
                   </span>
                 </button>
               );
             })}
           </div>
+        )}
       </div>
     </div>
   );

src/pages/Dashboard/useDashboard.ts

@@ -0,0 +1,31 @@
+import { useMemo } from 'react';
+import { useRouter } from '@/providers/RouterProvider';
+import type { PageType } from '@/types/storage';
+import { resolveDashboardFeatures, type DashboardFeatureItem } from './dashboardFeatures';
+
+export type { DashboardFeatureItem } from './dashboardFeatures';
+
+export interface UseDashboardReturn {
+  visibleFeatures: DashboardFeatureItem[];
+  recentFeatures: DashboardFeatureItem[];
+  showRecent: boolean;
+  navigateTo: (page: PageType) => void;
+}
+
+export function useDashboard(): UseDashboardReturn {
+  const { navigateTo, visiblePages, pageOrder, recentlyUsedTools } = useRouter();
+
+  const visibleFeatures = useMemo(
+    () => resolveDashboardFeatures(pageOrder, visiblePages),
+    [pageOrder, visiblePages],
+  );
+
+  const recentFeatures = useMemo(
+    () => resolveDashboardFeatures(recentlyUsedTools, visiblePages),
+    [recentlyUsedTools, visiblePages],
+  );
+
+  const showRecent = recentFeatures.length > 0;
+
+  return { visibleFeatures, recentFeatures, showRecent, navigateTo };
+}

src/pages/JsonTools/components/JsonConvertSection.tsx

@@ -1,7 +1,7 @@
 import React, { useEffect, useMemo, useState } from 'react';
-import { formatBytes } from '@/utils/format';
-import { CopyButton } from '@/components/CopyButton';
+import EmptyPlaceholder from '@/components/EmptyPlaceholder';
 import TextInputArea from '@/components/TextInputArea';
+import JsonResultPanel from './JsonResultPanel';
 import { validateJson } from '@/utils/jsonFormatter';
 import { cn } from '@/lib/utils';
 import type { ConvertFunction, ConvertResult } from '../types';
@@ -97,46 +97,17 @@ export default function JsonConvertSection({
 
       {/* Result display */}
       {result && result.output ? (
-        <div className="relative rounded-xl border border-border bg-card text-card-foreground shadow-sm overflow-hidden">
-          <div className="flex h-9 items-center justify-between px-4 border-b border-border bg-muted/50 select-none">
-            <div className="flex gap-4 items-center">
-              <span className="text-[10px] font-bold uppercase tracking-wider text-muted-foreground/90">
-                {labels.outputLabel}
-              </span>
-
-              <div className="hidden sm:flex gap-3 items-center font-mono text-[10px] text-muted-foreground/70 tabular-nums">
-                <span>
-                  {'原始大小'}:{' '}
-                  <span className="font-semibold text-foreground/80">
-                    {formatBytes(result.originalBytes)}
-                  </span>
-                </span>
-                <span className="text-border/60">|</span>
-                <span>
-                  {'格式化后大小'}:{' '}
-                  <span className="font-semibold text-foreground/80">
-                    {formatBytes(result.outputBytes)}
-                  </span>
-                </span>
-              </div>
-            </div>
-
-            <CopyButton
-              text={result.output}
-              className="h-6 w-6 rounded-md border text-muted-foreground"
+        <JsonResultPanel
+          title={labels.outputLabel}
+          content={result.output}
+          originalBytes={result.originalBytes}
+          outputBytes={result.outputBytes}
+          maxHeight="380px"
         />
-          </div>
-
-          <div className="p-4 font-mono text-xs text-foreground/90 whitespace-pre-wrap break-all max-h-[380px] overflow-y-auto leading-relaxed select-text">
-            {result.output}
-          </div>
-        </div>
       ) : (
-        <div className="p-8 rounded-xl bg-muted/30 border border-dashed border-border/80 text-center flex flex-col items-center justify-center min-h-[120px] select-none">
-          <p className="text-xs font-semibold text-muted-foreground/80 tracking-wide max-w-[240px] leading-relaxed">
+        <EmptyPlaceholder>
           {error ? '请修正上方 JSON 的语法错误以开启实时流式格式化' : labels.emptyHint}
-          </p>
-        </div>
+        </EmptyPlaceholder>
       )}
     </div>
   );

src/pages/JsonTools/components/JsonFormatSection.tsx

@@ -5,10 +5,10 @@ import {
   type JsonFormatResult,
   validateJson,
 } from '@/utils/jsonFormatter';
-import { formatBytes } from '@/utils/format';
-import { CopyButton } from '@/components/CopyButton';
+import EmptyPlaceholder from '@/components/EmptyPlaceholder';
 import SwitchButtonGroup from '@/components/SwitchButtonGroup';
 import TextInputArea from '@/components/TextInputArea';
+import JsonResultPanel from './JsonResultPanel';
 import { Checkbox } from '@/components/ui/checkbox';
 import { Label } from '@/components/ui/label';
 
@@ -112,48 +112,16 @@ export default function JsonFormatSection() {
 
       {/* 格式化结果流面板展示 */}
       {result && result.formatted ? (
-        <div className="relative rounded-xl border border-border bg-card text-card-foreground shadow-sm overflow-hidden">
-          {/* 结果栏头部 */}
-          <div className="flex h-9 items-center justify-between px-4 border-b border-border bg-muted/50 select-none">
-            <div className="flex gap-4 items-center">
-              <span className="text-[10px] font-bold uppercase tracking-wider text-muted-foreground/90">
-                {'格式化结果'}
-              </span>
-
-              <div className="hidden sm:flex gap-3 items-center font-mono text-[10px] text-muted-foreground/70 tabular-nums">
-                <span>
-                  {'原始大小'}:{' '}
-                  <span className="font-semibold text-foreground/80">
-                    {formatBytes(result.originalBytes)}
-                  </span>
-                </span>
-                <span className="text-border/60">|</span>
-                <span>
-                  {'格式化后大小'}:{' '}
-                  <span className="font-semibold text-foreground/80">
-                    {formatBytes(result.formattedBytes)}
-                  </span>
-                </span>
-              </div>
-            </div>
-
-            <CopyButton
-              text={result.formatted}
-              className="h-6 w-6 rounded-md border text-muted-foreground"
+        <JsonResultPanel
+          title="格式化结果"
+          content={result.formatted}
+          originalBytes={result.originalBytes}
+          outputBytes={result.formattedBytes}
         />
-          </div>
-
-          <div className="p-4 font-mono text-xs text-foreground/90 whitespace-pre-wrap break-all max-h-[420px] overflow-y-auto leading-relaxed select-text">
-            {result.formatted}
-          </div>
-        </div>
       ) : (
-        /* 空状态指示引导区 */
-        <div className="p-8 rounded-xl bg-muted/30 border border-dashed border-border/80 text-center flex flex-col items-center justify-center min-h-[120px] select-none">
-          <p className="text-xs font-semibold text-muted-foreground/80 tracking-wide max-w-[240px] leading-relaxed">
+        <EmptyPlaceholder>
           {error ? '请修正上方 JSON 的语法错误以开启实时流式格式化' : '输入 JSON 后点击格式化'}
-          </p>
-        </div>
+        </EmptyPlaceholder>
       )}
     </div>
   );

src/pages/JsonTools/components/JsonResultPanel.tsx

@@ -0,0 +1,53 @@
+import { formatBytes } from '@/utils/format';
+import { CopyButton } from '@/components/CopyButton';
+
+export interface JsonResultPanelProps {
+  title: string;
+  content: string;
+  originalBytes: number;
+  outputBytes: number;
+  outputSizeLabel?: string;
+  maxHeight?: string;
+}
+
+export default function JsonResultPanel({
+  title,
+  content,
+  originalBytes,
+  outputBytes,
+  outputSizeLabel = '格式化后大小',
+  maxHeight = '420px',
+}: JsonResultPanelProps) {
+  return (
+    <div className="relative rounded-xl border border-border bg-card text-card-foreground shadow-sm overflow-hidden">
+      <div className="flex h-9 items-center justify-between px-4 border-b border-border bg-muted/50 select-none">
+        <div className="flex gap-4 items-center">
+          <span className="text-[10px] font-bold uppercase tracking-wider text-muted-foreground/90">
+            {title}
+          </span>
+
+          <div className="hidden sm:flex gap-3 items-center font-mono text-[10px] text-muted-foreground/70 tabular-nums">
+            <span>
+              {'原始大小'}:{' '}
+              <span className="font-semibold text-foreground/80">{formatBytes(originalBytes)}</span>
+            </span>
+            <span className="text-border/60">|</span>
+            <span>
+              {outputSizeLabel}:{' '}
+              <span className="font-semibold text-foreground/80">{formatBytes(outputBytes)}</span>
+            </span>
+          </div>
+        </div>
+
+        <CopyButton text={content} className="h-6 w-6 rounded-md border text-muted-foreground" />
+      </div>
+
+      <div
+        className="p-4 font-mono text-xs text-foreground/90 whitespace-pre-wrap break-all overflow-y-auto leading-relaxed select-text"
+        style={{ maxHeight }}
+      >
+        {content}
+      </div>
+    </div>
+  );
+}

src/pages/JsonTools/index.tsx

@@ -4,6 +4,7 @@ import DiffNavigator from './components/DiffNavigator';
 import JsonFormatSection from './components/JsonFormatSection';
 import JsonConvertSection from './components/JsonConvertSection';
 import SwitchButtonGroup from '@/components/SwitchButtonGroup';
+import EmptyPlaceholder from '@/components/EmptyPlaceholder';
 import { useJsonTools } from './useJsonTools';
 import type { JsonToolsPageMode } from '@/types/storage';
 import type { ViewMode } from './types';
@@ -95,13 +96,11 @@ export default function Index() {
               <DiffResult result={diffResult} viewMode={viewMode} activePath={activePath} />
             </div>
           ) : (
-            <div className="p-8 rounded-xl bg-muted/30 border border-dashed border-border/80 text-center flex flex-col items-center justify-center min-h-[140px]">
-              <p className="text-xs font-semibold text-muted-foreground/80 tracking-wide max-w-[260px] leading-relaxed">
+            <EmptyPlaceholder className="min-h-[140px]" messageClassName="max-w-[260px]">
               {leftError || rightError
                 ? '请修正上方 JSON 的语法错误以开启实时流式比对'
                 : '输入两侧 JSON 后点击比较'}
-              </p>
-            </div>
+            </EmptyPlaceholder>
           )}
         </div>
       ) : pageMode === 'format' ? (

src/pages/Jwt/JwtSection.tsx

@@ -1,36 +0,0 @@
-import { CopyButton } from '@/components/CopyButton';
-import { stringifyJson } from '@/utils/jwt';
-import { cn } from '@/lib/utils';
-
-interface JwtSectionProps {
-  title: string;
-  content: unknown;
-  colorClass: string;
-  bgClass: string;
-  borderClass: string;
-}
-
-export default function JwtSection({
-  title,
-  content,
-  colorClass,
-  bgClass,
-  borderClass,
-}: JwtSectionProps) {
-  return (
-    <div className={cn('p-4 rounded-xl border border-solid', bgClass, borderClass)}>
-      <div className="flex justify-between items-center mb-2 select-none">
-        <span className={cn('text-xs font-bold tracking-wider uppercase', colorClass)}>
-          {title}
-        </span>
-        <CopyButton
-          text={JSON.stringify(content)}
-          className="h-6 w-6 rounded-md border text-muted-foreground"
-        />
-      </div>
-      <pre className="m-0 p-3 bg-muted/30 dark:bg-muted/10 rounded-lg text-xs font-mono overflow-x-auto whitespace-pre-wrap break-all border border-border/50 text-foreground/90 leading-relaxed select-text">
-        {content ? stringifyJson(content) : '无法解析'}
-      </pre>
-    </div>
-  );
-}

src/pages/Jwt/components/JwtCopyBlock.tsx

@@ -0,0 +1,30 @@
+import { CopyButton } from '@/components/CopyButton';
+import { cn } from '@/lib/utils';
+
+interface JwtCopyBlockProps {
+  title: string;
+  copyText: string;
+  titleClassName?: string;
+  containerClassName?: string;
+  children: React.ReactNode;
+}
+
+export default function JwtCopyBlock({
+  title,
+  copyText,
+  titleClassName,
+  containerClassName,
+  children,
+}: JwtCopyBlockProps) {
+  return (
+    <div className={cn('p-4 rounded-xl border shadow-sm', containerClassName)}>
+      <div className="flex justify-between items-center mb-2 select-none">
+        <span className={cn('text-xs font-bold tracking-wider uppercase', titleClassName)}>
+          {title}
+        </span>
+        <CopyButton text={copyText} className="h-6 w-6 rounded-md border text-muted-foreground" />
+      </div>
+      {children}
+    </div>
+  );
+}

src/pages/Jwt/components/JwtResultView.tsx

@@ -0,0 +1,49 @@
+import { stringifyJson } from '@/utils/jwt';
+import type { JwtResult } from '@/utils/jwt';
+import { cn } from '@/lib/utils';
+import {
+  JWT_JSON_CONTENT_CLASS,
+  JWT_SECTION_CONFIG,
+  JWT_SIGNATURE_SECTION,
+  JWT_TEXT_CONTENT_CLASS,
+} from '../constants';
+import JwtCopyBlock from './JwtCopyBlock';
+
+interface JwtResultViewProps {
+  result: JwtResult;
+}
+
+export default function JwtResultView({ result }: JwtResultViewProps) {
+  return (
+    <div className="flex flex-col gap-4">
+      {JWT_SECTION_CONFIG.map(({ contentKey, title, colorClass, bgClass, borderClass }) => {
+        const content = result[contentKey];
+
+        return (
+          <JwtCopyBlock
+            key={contentKey}
+            title={title}
+            copyText={JSON.stringify(content)}
+            titleClassName={colorClass}
+            containerClassName={cn('border-solid', bgClass, borderClass)}
+          >
+            <pre className={JWT_JSON_CONTENT_CLASS}>
+              {content ? stringifyJson(content) : '无法解析'}
+            </pre>
+          </JwtCopyBlock>
+        );
+      })}
+
+      <JwtCopyBlock
+        title={JWT_SIGNATURE_SECTION.title}
+        copyText={result.signature || ''}
+        titleClassName={JWT_SIGNATURE_SECTION.titleClassName}
+        containerClassName={JWT_SIGNATURE_SECTION.containerClassName}
+      >
+        <span className={JWT_TEXT_CONTENT_CLASS}>
+          {result.signature || JWT_SIGNATURE_SECTION.emptyLabel}
+        </span>
+      </JwtCopyBlock>
+    </div>
+  );
+}

src/pages/Jwt/constants.ts

@@ -0,0 +1,41 @@
+export const JWT_INPUT_PLACEHOLDER = '在此粘贴 JWT 令牌 (Encoded JWT)...';
+
+export type JwtSectionContentKey = 'header' | 'payload';
+
+export interface JwtSectionConfig {
+  contentKey: JwtSectionContentKey;
+  title: string;
+  colorClass: string;
+  borderClass: string;
+  bgClass: string;
+}
+
+export const JWT_SECTION_CONFIG: JwtSectionConfig[] = [
+  {
+    contentKey: 'header',
+    title: 'HEADER: 算法 & 令牌类型',
+    colorClass: 'text-[#fb015b] dark:text-rose-400',
+    borderClass: 'border-[#fb015b]/20 dark:border-rose-500/20',
+    bgClass: 'bg-[#fb015b]/5 dark:bg-rose-500/5',
+  },
+  {
+    contentKey: 'payload',
+    title: 'PAYLOAD: 数据',
+    colorClass: 'text-[#a03aff] dark:text-purple-400',
+    borderClass: 'border-[#a03aff]/20 dark:border-purple-500/20',
+    bgClass: 'bg-[#a03aff]/5 dark:bg-purple-500/5',
+  },
+];
+
+export const JWT_SIGNATURE_SECTION = {
+  title: '签名',
+  titleClassName: 'text-muted-foreground/90',
+  containerClassName: 'border border-border bg-secondary/40',
+  emptyLabel: '无签名',
+} as const;
+
+export const JWT_JSON_CONTENT_CLASS =
+  'm-0 p-3 bg-muted/30 dark:bg-muted/10 rounded-lg text-xs font-mono overflow-x-auto whitespace-pre-wrap break-all border border-border/50 text-foreground/90 leading-relaxed select-text';
+
+export const JWT_TEXT_CONTENT_CLASS =
+  'block text-xs font-mono break-all text-foreground/80 bg-muted/30 dark:bg-muted/10 p-3 rounded-lg border border-border/50 leading-relaxed select-text';

src/pages/Jwt/index.tsx

@@ -1,18 +1,17 @@
 import TextInputArea from '@/components/TextInputArea';
-import { CopyButton } from '@/components/CopyButton';
-import JwtSection from './JwtSection';
+import JwtResultView from './components/JwtResultView';
+import { JWT_INPUT_PLACEHOLDER } from './constants';
 import { useJwt } from './useJwt';
 
 export default function Index() {
   const { jwtInput, result, handleChange, handleClear } = useJwt();
 
   return (
-    <div className="p-4 w-full flex flex-col space-y-4 select-none">
-      <div className="flex flex-col gap-4">
+    <div className="p-4 w-full flex flex-col gap-4 select-none">
       <TextInputArea
         minRows={5}
         maxRows={10}
-          placeholder={'在此粘贴 JWT 令牌 (Encoded JWT)...'}
+        placeholder={JWT_INPUT_PLACEHOLDER}
         value={jwtInput}
         onChange={handleChange}
         allowCopy={true}
@@ -21,47 +20,7 @@ export default function Index() {
         onClear={handleClear}
       />
 
-        {result && !result.error && (
-          <div className="flex flex-col gap-4">
-            <JwtSection
-              title={'HEADER: 算法 & 令牌类型'}
-              content={result.header}
-              colorClass="text-[#fb015b] dark:text-rose-400"
-              borderClass="border-[#fb015b]/20 dark:border-rose-500/20"
-              bgClass="bg-[#fb015b]/5 dark:bg-rose-500/5"
-            />
-
-            <JwtSection
-              title={'PAYLOAD: 数据'}
-              content={result.payload}
-              colorClass="text-[#a03aff] dark:text-purple-400"
-              borderClass="border-[#a03aff]/20 dark:border-purple-500/20"
-              bgClass="bg-[#a03aff]/5 dark:bg-purple-500/5"
-            />
-
-            <div className="p-4 rounded-xl border border-border bg-secondary/40 shadow-sm">
-              <div className="flex justify-between items-center mb-2">
-                <span className="text-xs font-bold tracking-wider text-muted-foreground/90 uppercase">
-                  {'签名'}
-                </span>
-                <CopyButton
-                  text={result.signature || ''}
-                  className="h-6 w-6 rounded-md border text-muted-foreground"
-                />
-              </div>
-              <span className="block text-xs font-mono break-all text-foreground/80 bg-muted/30 dark:bg-muted/10 p-3 rounded-lg border border-border/50 leading-relaxed select-text">
-                {result.signature || '无签名'}
-              </span>
-            </div>
-          </div>
-        )}
-
-        {result?.error && (
-          <div className="p-6 rounded-xl bg-muted/30 border border-dashed border-border text-center">
-            <p className="text-xs font-semibold text-muted-foreground/80">{'无效的 JSON 格式'}</p>
-          </div>
-        )}
-      </div>
+      {result && !result.error && <JwtResultView result={result} />}
     </div>
   );
 }

src/pages/QrCode/__tests__/ImageUploader.test.tsx

@@ -23,7 +23,6 @@ vi.mock('sonner', () => ({
 describe('ImageUploader 组件', () => {
   const mockOnFileChange = vi.fn();
   const mockOnClearFile = vi.fn();
-  const mockOnPreviewUrlChange = vi.fn();
   const mockOnDraggingChange = vi.fn();
 
   const defaultProps = {
@@ -31,7 +30,6 @@ describe('ImageUploader 组件', () => {
     onFileChange: mockOnFileChange,
     onClearFile: mockOnClearFile,
     previewUrl: '',
-    onPreviewUrlChange: mockOnPreviewUrlChange,
     dragging: false,
     onDraggingChange: mockOnDraggingChange,
   };
@@ -95,7 +93,7 @@ describe('ImageUploader 组件', () => {
   });
 
   describe('文件选择交互', () => {
-    it('选择文件时应调用 onFileChange 和 onPreviewUrlChange', async () => {
+    it('选择文件时应调用 onFileChange', async () => {
       render(<ImageUploader {...defaultProps} />);
       const input = document.getElementById('qr-code-upload') as HTMLInputElement;
       const mockFile = new File(['test'], 'test.png', { type: 'image/png' });
@@ -105,8 +103,7 @@ describe('ImageUploader 组件', () => {
       });
 
       expect(mockOnFileChange).toHaveBeenCalledWith(mockFile);
-      expect(mockCreateObjectURL).toHaveBeenCalledWith(mockFile);
-      expect(mockOnPreviewUrlChange).toHaveBeenCalledWith('blob:test-url');
+      expect(mockOnFileChange).toHaveBeenCalledTimes(1);
     });
   });
 
@@ -127,7 +124,7 @@ describe('ImageUploader 组件', () => {
       expect(mockOnDraggingChange).toHaveBeenCalledWith(false);
     });
 
-    it('放置文件时应调用 onFileChange 和 onPreviewUrlChange', () => {
+    it('放置文件时应调用 onFileChange', () => {
       const { container } = render(<ImageUploader {...defaultProps} />);
       const dropzone = container.firstChild as HTMLElement;
       const mockFile = new File(['test'], 'test.png', { type: 'image/png' });
@@ -146,6 +143,7 @@ describe('ImageUploader 组件', () => {
 
       expect(mockOnDraggingChange).toHaveBeenCalledWith(false);
       expect(mockOnFileChange).toHaveBeenCalledWith(mockFile);
+      expect(mockOnFileChange).toHaveBeenCalledTimes(1);
     });
   });
 
@@ -165,20 +163,12 @@ describe('ImageUploader 组件', () => {
   });
 
   describe('粘贴功能', () => {
-    it('监听粘贴事件', () => {
+    it('不应注册 document 粘贴事件监听（由 ParsePanel 统一处理）', () => {
       const addEventListenerSpy = vi.spyOn(document, 'addEventListener');
       render(<ImageUploader {...defaultProps} />);
 
-      expect(addEventListenerSpy).toHaveBeenCalledWith('paste', expect.any(Function));
-    });
-
-    it('组件卸载时应移除粘贴事件监听', () => {
-      const removeEventListenerSpy = vi.spyOn(document, 'removeEventListener');
-      const { unmount } = render(<ImageUploader {...defaultProps} />);
-
-      unmount();
-
-      expect(removeEventListenerSpy).toHaveBeenCalledWith('paste', expect.any(Function));
+      const pasteListeners = addEventListenerSpy.mock.calls.filter(([event]) => event === 'paste');
+      expect(pasteListeners).toHaveLength(0);
     });
   });
 

src/pages/QrCode/__tests__/ParsePanel.test.tsx

@@ -0,0 +1,151 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, render, screen } from '@testing-library/react';
+import { toast } from 'sonner';
+import ParsePanel from '../components/ParsePanel';
+import type { QrCodeParserState } from '../types';
+
+const mockHandleFileChange = vi.fn();
+const mockHandleClearFile = vi.fn();
+const mockSetParserState = vi.fn();
+
+let mockParserState: QrCodeParserState = {
+  selectedFile: null,
+  previewUrl: '',
+  dragging: false,
+  decodedResult: '',
+  parsing: false,
+  parseError: '',
+};
+
+vi.mock('sonner', () => ({
+  toast: {
+    success: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+
+vi.mock('../contexts/QrCodeContext', () => ({
+  useQrCodeContext: () => ({
+    parserState: mockParserState,
+    setParserState: mockSetParserState,
+    handleFileChange: mockHandleFileChange,
+    handleClearFile: mockHandleClearFile,
+  }),
+}));
+
+function createImagePasteEvent(file: File) {
+  const pasteEvent = new Event('paste', { bubbles: true }) as ClipboardEvent;
+  Object.defineProperty(pasteEvent, 'clipboardData', {
+    value: {
+      items: [
+        {
+          type: file.type,
+          getAsFile: () => file,
+        },
+      ],
+      getData: () => '',
+    },
+  });
+  Object.defineProperty(pasteEvent, 'preventDefault', { value: vi.fn() });
+  return pasteEvent;
+}
+
+function createBase64PasteEvent(dataUrl: string) {
+  const pasteEvent = new Event('paste', { bubbles: true }) as ClipboardEvent;
+  Object.defineProperty(pasteEvent, 'clipboardData', {
+    value: {
+      items: [],
+      getData: (type: string) => (type === 'text/plain' ? dataUrl : ''),
+    },
+  });
+  Object.defineProperty(pasteEvent, 'preventDefault', { value: vi.fn() });
+  return pasteEvent;
+}
+
+describe('ParsePanel 组件', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockParserState = {
+      selectedFile: null,
+      previewUrl: '',
+      dragging: false,
+      decodedResult: '',
+      parsing: false,
+      parseError: '',
+    };
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('粘贴功能', () => {
+    it('粘贴图片时应只处理一次', async () => {
+      render(<ParsePanel />);
+      const mockFile = new File(['img'], 'paste.png', { type: 'image/png' });
+
+      await act(async () => {
+        document.dispatchEvent(createImagePasteEvent(mockFile));
+      });
+
+      expect(mockHandleFileChange).toHaveBeenCalledTimes(1);
+      expect(mockHandleFileChange).toHaveBeenCalledWith(mockFile);
+      expect(toast.success).toHaveBeenCalledTimes(1);
+      expect(toast.success).toHaveBeenCalledWith('图片粘贴成功，正在解析...');
+    });
+
+    it('与 ImageUploader 同时挂载时 document 上只应有一个 paste 监听', () => {
+      const addEventListenerSpy = vi.spyOn(document, 'addEventListener');
+      render(<ParsePanel />);
+
+      const pasteListeners = addEventListenerSpy.mock.calls.filter(([event]) => event === 'paste');
+      expect(pasteListeners).toHaveLength(1);
+    });
+
+    it('粘贴 Base64 data URI 时应转换为文件并只处理一次', async () => {
+      const dataUrl = 'data:image/png;base64,abcd';
+      const mockBlob = new Blob(['img'], { type: 'image/png' });
+      vi.stubGlobal(
+        'fetch',
+        vi.fn().mockResolvedValue({
+          blob: () => Promise.resolve(mockBlob),
+        }),
+      );
+
+      render(<ParsePanel />);
+
+      await act(async () => {
+        document.dispatchEvent(createBase64PasteEvent(dataUrl));
+      });
+
+      expect(fetch).toHaveBeenCalledWith(dataUrl);
+      expect(mockHandleFileChange).toHaveBeenCalledTimes(1);
+      expect(mockHandleFileChange).toHaveBeenCalledWith(
+        expect.objectContaining({ name: 'pasted-image.png', type: 'image/png' }),
+      );
+      expect(toast.success).toHaveBeenCalledTimes(1);
+    });
+
+    it('已上传图片时粘贴仍应只处理一次', async () => {
+      mockParserState = {
+        selectedFile: new File(['existing'], 'existing.png', { type: 'image/png' }),
+        previewUrl: 'blob:existing',
+        dragging: false,
+        decodedResult: 'decoded-text',
+        parsing: false,
+        parseError: '',
+      };
+
+      render(<ParsePanel />);
+      expect(screen.getByText('已上传图片')).toBeInTheDocument();
+
+      const mockFile = new File(['new'], 'new.png', { type: 'image/png' });
+      await act(async () => {
+        document.dispatchEvent(createImagePasteEvent(mockFile));
+      });
+
+      expect(mockHandleFileChange).toHaveBeenCalledTimes(1);
+      expect(mockHandleFileChange).toHaveBeenCalledWith(mockFile);
+    });
+  });
+});

src/pages/QrCode/components/ImageUploader.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef } from 'react';
+import { useCallback, useRef } from 'react';
 import { Image, X } from 'lucide-react';
 import { toast } from 'sonner';
 import { Button } from '@/components/ui/button';
@@ -13,8 +13,6 @@ interface ImageUploaderProps {
   onClearFile: () => void;
   /** 文件预览 URL */
   previewUrl: string;
-  /** 预览 URL 变更回调 */
-  onPreviewUrlChange: (url: string) => void;
   /** 是否正在拖拽 */
   dragging: boolean;
   /** 拖拽状态变更回调 */
@@ -26,7 +24,6 @@ const ImageUploader = ({
   onFileChange,
   onClearFile,
   previewUrl,
-  onPreviewUrlChange,
   dragging,
   onDraggingChange,
 }: ImageUploaderProps) => {
@@ -35,9 +32,8 @@ const ImageUploader = ({
   const handleFileChange = useCallback(
     (file: File) => {
       onFileChange(file);
-      onPreviewUrlChange(URL.createObjectURL(file));
     },
-    [onFileChange, onPreviewUrlChange],
+    [onFileChange],
   );
 
   const handleClearFile = useCallback(() => {
@@ -72,38 +68,6 @@ const ImageUploader = ({
     }
   };
 
-  // 监听粘贴事件
-  useEffect(() => {
-    const handlePaste = async (e: ClipboardEvent) => {
-      const items = e.clipboardData?.items;
-      if (!items) return;
-
-      for (let i = 0; i < items.length; i++) {
-        if (items[i].type.startsWith('image/')) {
-          e.preventDefault();
-
-          const file = items[i].getAsFile();
-          if (file) {
-            try {
-              handleFileChange(file);
-              toast.success('图片粘贴成功，正在解析...');
-            } catch (error) {
-              console.error('处理粘贴图片失败:', error);
-              toast.error('粘贴图片失败，请重试');
-            }
-          }
-          break;
-        }
-      }
-    };
-
-    document.addEventListener('paste', handlePaste);
-
-    return () => {
-      document.removeEventListener('paste', handlePaste);
-    };
-  }, [handleFileChange]);
-
   return (
     <div
       className={`flex flex-col items-center justify-center h-[250px] border-2 border-dashed rounded-xl p-4 cursor-pointer transition-all duration-200 ${

src/pages/QrCode/components/ParsePanel.tsx

@@ -65,7 +65,6 @@ export default function ParsePanel() {
           onFileChange={handleFileChange}
           onClearFile={handleClearFile}
           previewUrl={parserState.previewUrl}
-          onPreviewUrlChange={(url) => setParserState((prev) => ({ ...prev, previewUrl: url }))}
           dragging={parserState.dragging}
           onDraggingChange={(dragging) => setParserState((prev) => ({ ...prev, dragging }))}
         />

src/pages/QrCode/components/QrCodePreview.tsx

@@ -1,5 +1,6 @@
 import React from 'react';
 import { Copy, Download } from 'lucide-react';
+import EmptyPlaceholder from '@/components/EmptyPlaceholder';
 import { cn } from '@/lib/utils';
 import { Button } from '@/components/ui/button';
 
@@ -26,17 +27,13 @@ const QrCodePreview = ({
   // 空状态下的虚线骨架屏
   if (!qrCodeDataUrl) {
     return (
-      <div
-        className={cn(
-          'flex flex-col justify-center items-center min-h-[200px] border border-dashed border-input rounded-xl p-4 bg-muted/40',
-          className,
-        )}
+      <EmptyPlaceholder
+        className={cn('min-h-[200px] p-4', className)}
+        messageClassName="text-sm text-muted-foreground max-w-none"
         {...props}
       >
-        <p className="text-sm text-muted-foreground text-center">
         {placeholderText || '二维码将显示在这里'}
-        </p>
-      </div>
+      </EmptyPlaceholder>
     );
   }
 

src/pages/QrCode/hooks/useQrCode.ts

@@ -6,10 +6,8 @@ import { useContextMenuData } from '@/utils/useContextMenuData';
 import type { QrCodeContextValue } from '../contexts/QrCodeContext';
 import type { QrCodeGeneratorState, QrCodeMode, QrCodeParserState } from '../types';
 
-/** 防抖延迟时间（毫秒） */
 const DEBOUNCE_DELAY = 500;
 
-/** 检测文本是否为URL格式 */
 function isUrl(text: string): boolean {
   const trimmed = text.trim();
   if (!trimmed) return false;
@@ -99,7 +97,6 @@ export function useQrCode(): QrCodeContextValue {
 
   const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  // 清除防抖定时器
   useEffect(() => {
     return () => {
       if (debounceTimerRef.current) {
@@ -108,7 +105,6 @@ export function useQrCode(): QrCodeContextValue {
     };
   }, []);
 
-  /** 自动检测URL并生成二维码 */
   const autoGenerateIfUrl = useCallback((text: string) => {
     if (debounceTimerRef.current) {
       clearTimeout(debounceTimerRef.current);
@@ -149,7 +145,6 @@ export function useQrCode(): QrCodeContextValue {
     [autoGenerateIfUrl],
   );
 
-  /** 手动触发生成二维码（用于非URL文本） */
   const confirmGenerate = useCallback(() => {
     const text = generatorState.textToEncode.trim();
 
@@ -159,10 +154,8 @@ export function useQrCode(): QrCodeContextValue {
       return;
     }
 
-    // 先设置 loading 状态，让 React 渲染加载动画
     setGeneratorState((prev) => ({ ...prev, generating: true, inputError: '' }));
 
-    // 延迟到下一帧生成，确保 loading 状态先被渲染显示
     setTimeout(() => {
       const qrCodeDataUrl = generateQrCodeDataUrl(text);
 
@@ -186,7 +179,6 @@ export function useQrCode(): QrCodeContextValue {
     }, 0);
   }, [generatorState.textToEncode]);
 
-  /** 返回编辑态，保留上次输入内容 */
   const backToEdit = useCallback(() => {
     if (debounceTimerRef.current) {
       clearTimeout(debounceTimerRef.current);
@@ -200,7 +192,6 @@ export function useQrCode(): QrCodeContextValue {
     }));
   }, []);
 
-  /** 从图片URL解析二维码 */
   const parseQrCodeFromUrl = useCallback(async (imageUrl: string) => {
     try {
       setParserState((prev) => ({
@@ -212,7 +203,6 @@ export function useQrCode(): QrCodeContextValue {
         selectedFile: null,
       }));
 
-      // 从URL获取图片并转换为File对象
       const response = await fetch(imageUrl);
       const blob = await response.blob();
       const file = new File([blob], 'qrcode-image.png', { type: blob.type });
@@ -239,35 +229,19 @@ export function useQrCode(): QrCodeContextValue {
     }
   }, []);
 
-  /** 右键菜单传入URL时，自动生成二维码或解析图片 */
   const handleContextMenuData = useCallback(
     (payload: string) => {
-      // 检测是否为图片URL，如果是则切换到解析模式
       if (isImageUrl(payload)) {
         setMode('parse');
         void parseQrCodeFromUrl(payload);
         return;
       }
 
-      // 非图片URL，生成二维码
       setMode('generate');
 
-      // 直接生成二维码，无需等待
       const qrCodeDataUrl = generateQrCodeDataUrl(payload);
 
-      if (qrCodeDataUrl) {
-        // 生成成功，直接跳转到预览态
-        setGeneratorState((prev) => ({
-          ...prev,
-          step: 'preview',
-          textToEncode: payload,
-          savedText: payload.trim(),
-          qrCodeDataUrl,
-          generating: false,
-          inputError: '',
-        }));
-      } else {
-        // 生成失败，停留在输入态，显示文本供用户编辑
+      if (!qrCodeDataUrl) {
         setGeneratorState((prev) => ({
           ...prev,
           step: 'input',
@@ -284,7 +258,6 @@ export function useQrCode(): QrCodeContextValue {
 
   useContextMenuData({ featureKey: 'qrCode', onData: handleContextMenuData });
 
-  // 反向活态解析二维码算法
   const parseQrCode = useCallback(async (file: File) => {
     try {
       setParserState((prev) => ({ ...prev, parsing: true, parseError: '', decodedResult: '' }));
@@ -354,7 +327,6 @@ export function useQrCode(): QrCodeContextValue {
         };
       });
 
-      // 触发解析安全的后台 Promise
       parseQrCode(file).catch((err) => {
         console.error('Parser standalone task thread exploded:', err);
       });
@@ -362,7 +334,6 @@ export function useQrCode(): QrCodeContextValue {
     [parseQrCode],
   );
 
-  // 清除解析受控文件
   const handleClearFile = useCallback(() => {
     setParserState((prev) => {
       if (prev.previewUrl) {

src/pages/QrCode/index.tsx

@@ -9,7 +9,6 @@ import type { QrCodeMode } from './types';
 export default function Index() {
   const qrCode = useQrCode();
 
-  // 模式选项驱动骨架
   const modeOptions = [
     { value: 'generate' as QrCodeMode, label: '文本转二维码' },
     { value: 'parse' as QrCodeMode, label: '二维码转文本' },

src/pages/README.md

@@ -1,140 +0,0 @@
-# pages/
-
-功能页面组件目录，每个子目录对应一个工具页面。
-
-## 目录结构约定
-
-典型页面遵循 **UI + Hook 分离** 模式：
-
-```
-pages/FeatureName/
-├── index.tsx              # 页面 UI（纯展示，使用 shadcn/ui 组件）
-├── useFeatureName.ts      # 业务逻辑 Hook（状态管理 + 转换逻辑）
-├── constants.ts           # 常量定义（可选）
-├── SubComponent.tsx       # 子组件（可选）
-└── __tests__/             # 测试文件
-    └── index.test.tsx
-```
-
-## 页面列表
-
-### Dashboard/
-
-仪表盘首页，以卡片网格展示所有可见工具，支持点击导航。
-
-| 文件           | 用途                                         |
-| -------------- | -------------------------------------------- |
-| `index.tsx`    | 页面组件，渲染工具卡片网格                   |
-| `ToolCard.tsx` | 工具卡片组件，展示图标、标题、描述和实时数据 |
-
-### Timestamp/
-
-时间戳转换工具，支持秒/毫秒级互转、多时区选择、实时时钟。
-
-| 文件                       | 用途                                                              |
-| -------------------------- | ----------------------------------------------------------------- |
-| `index.tsx`                | 页面 UI                                                           |
-| `useTimestampConverter.ts` | 业务逻辑 Hook，包含转换模式、输入、单位、时区状态和响应式计算管线 |
-| `LiveClock.tsx`            | 实时时钟子组件，`React.memo` 优化                                 |
-| `ResultView.tsx`           | 转换结果展示子组件                                                |
-| `constants.ts`             | 时区列表等常量                                                    |
-
-### StorageCleaner/
-
-浏览器存储清理工具，支持 Cookie/LocalStorage/SessionStorage/IndexedDB/Cache/SW 清理。
-
-| 文件                        | 用途           |
-| --------------------------- | -------------- |
-| `index.tsx`                 | 页面 UI        |
-| `useStorageCleaner.ts`      | 业务逻辑 Hook  |
-| `StorageOptionsGrid.tsx`    | 清理选项网格   |
-| `StorageCleanerConfirm.tsx` | 清理确认对话框 |
-| `AutoRefreshToggle.tsx`     | 自动刷新开关   |
-| `ErrorDisplay.tsx`          | 错误展示组件   |
-| `CleaningResult.tsx`        | 清理结果展示   |
-| `OptionItem.tsx`            | 单个选项组件   |
-
-### QrCode/
-
-二维码工具，支持生成（URL→QR）和解析（QR→URL）。
-
-| 文件/目录     | 用途             |
-| ------------- | ---------------- |
-| `index.tsx`   | 页面 UI          |
-| `types.ts`    | 类型定义         |
-| `contexts/`   | Context Provider |
-| `hooks/`      | 业务逻辑 Hooks   |
-| `components/` | 子组件           |
-
-### TextStatistics/
-
-文本统计工具，实时计算字符数、单词数、行数、字节大小。
-
-| 文件        | 用途                                          |
-| ----------- | --------------------------------------------- |
-| `index.tsx` | 页面组件，集成 `TextInputArea` 和统计结果展示 |
-
-### Jwt/
-
-JWT 解析工具，解码 Header/Payload/Signature。
-
-| 文件/目录     | 用途             |
-| ------------- | ---------------- |
-| `index.tsx`   | 页面 UI          |
-| `types.ts`    | 类型定义         |
-| `contexts/`   | Context Provider |
-| `hooks/`      | 业务逻辑 Hooks   |
-| `components/` | 子组件           |
-
-### JsonTools/
-
-JSON 工具集：差异比较、格式化、YAML/TOML/Minify 转换。
-
-| 文件                     | 用途                         |
-| ------------------------ | ---------------------------- |
-| `index.tsx`              | 页面入口，子模式切换         |
-| `types.ts`               | 类型定义                     |
-| `diffEngine.ts`          | 差异比较引擎                 |
-| `JsonDiffInput.tsx`      | JSON 输入组件                |
-| `DiffResult.tsx`         | 差异结果展示                 |
-| `DiffNavigator.tsx`      | 差异导航器                   |
-| `JsonFormatSection.tsx`  | 格式化区域                   |
-| `JsonConvertSection.tsx` | 转换区域（YAML/TOML/Minify） |
-| `JsonTree.tsx`           | JSON 树形展示                |
-
-### Base64Converter/
-
-Base64 编解码工具，支持文本/文件/图片三种模式。
-
-| 文件                         | 用途                  |
-| ---------------------------- | --------------------- |
-| `index.tsx`                  | 页面入口，子模式切换  |
-| `useBase64Converter.ts`      | 业务逻辑 Hook         |
-| `TextMode.tsx`               | 文本模式              |
-| `Base64ConverterSection.tsx` | 文件/图片通用转换区域 |
-
-### MarkdownToHtml/
-
-Markdown 转 HTML 工具，支持分栏/预览/源码三种视图模式。
-
-### HtmlToMarkdown/
-
-HTML 转 Markdown 工具，支持分栏/预览/Markdown 三种视图模式。
-
-### RightClickRestorer/
-
-右键菜单恢复工具，解除网站对右键的限制。
-
-| 文件                       | 用途          |
-| -------------------------- | ------------- |
-| `index.tsx`                | 页面 UI       |
-| `useRightClickRestorer.ts` | 业务逻辑 Hook |
-
-## 新增页面
-
-1. 在 `types/storage.d.ts` 添加 `PageType` 联合类型成员
-2. 在 `config/features.tsx` 的 `FEATURES` 数组添加配置
-3. 在 `pages/` 创建页面目录（遵循上述结构）
-4. 在 `i18n/locales/{zh,en}/features.json` 添加翻译
-5. 如需新权限，更新 `wxt.config.ts`
-6. 添加对应的单元测试

src/pages/RightClickRestorer/__tests__/index.test.tsx

@@ -8,8 +8,7 @@ vi.mock('../useRightClickRestorer', () => ({
   useRightClickRestorer: () => ({
     domain: 'example.com',
     isLoading: false,
-    isUnlocked: false,
-    isUnsupported: false,
+    status: 'locked',
     unlock: mockUnlock,
   }),
 }));

src/pages/RightClickRestorer/__tests__/useRightClickRestorer.test.ts

@@ -26,8 +26,7 @@ describe('useRightClickRestorer', () => {
     await waitFor(() => expect(result.current.isLoading).toBe(false));
 
     expect(result.current.domain).toBe('example.com');
-    expect(result.current.isUnlocked).toBe(false);
-    expect(result.current.isUnsupported).toBe(false);
+    expect(result.current.status).toBe('locked');
     expect(sendMessageToContent).toHaveBeenCalledWith('queryRightClickStatus');
   });
 
@@ -39,8 +38,7 @@ describe('useRightClickRestorer', () => {
 
     await waitFor(() => expect(result.current.isLoading).toBe(false));
 
-    expect(result.current.isUnsupported).toBe(true);
-    expect(result.current.isUnlocked).toBe(false);
+    expect(result.current.status).toBe('unsupported');
     expect(sendMessageToContent).not.toHaveBeenCalled();
   });
 
@@ -56,7 +54,7 @@ describe('useRightClickRestorer', () => {
       await result.current.unlock();
     });
 
-    expect(result.current.isUnlocked).toBe(true);
+    expect(result.current.status).toBe('unlocked');
     expect(sendMessageToContent).toHaveBeenLastCalledWith('restoreRightClick');
   });
 
@@ -72,7 +70,7 @@ describe('useRightClickRestorer', () => {
       await result.current.unlock();
     });
 
-    expect(result.current.isUnlocked).toBe(false);
+    expect(result.current.status).toBe('unsupported');
     expect(sendMessageToContent).not.toHaveBeenCalled();
   });
 
@@ -87,6 +85,6 @@ describe('useRightClickRestorer', () => {
       await result.current.unlock();
     });
 
-    expect(result.current.isUnlocked).toBe(false);
+    expect(result.current.status).toBe('locked');
   });
 });

src/pages/RightClickRestorer/constants.ts

@@ -0,0 +1,59 @@
+import type { LucideIcon } from 'lucide-react';
+import { AlertTriangle, MousePointerClick, Shield, ShieldCheck } from 'lucide-react';
+
+export type RestorerStatus = 'unsupported' | 'locked' | 'unlocked';
+
+export const CARD_CLASS =
+  'w-full p-4 rounded-xl border border-border bg-card text-card-foreground shadow-sm overflow-hidden space-y-3';
+
+export const LOADING_TEXT = '正在加载...';
+
+export const DOMAIN_LABEL = '当前域名';
+
+interface StatusConfig {
+  badgeVariant: 'default' | 'secondary' | 'destructive';
+  badgeClassName: string;
+  badgeIcon: LucideIcon;
+  badgeLabel: string;
+  description: string;
+  buttonIcon: LucideIcon;
+  buttonLabel: string;
+  buttonDisabled: boolean;
+  buttonVariant: 'default' | 'secondary';
+}
+
+export const STATUS_CONFIG: Record<RestorerStatus, StatusConfig> = {
+  unsupported: {
+    badgeVariant: 'destructive',
+    badgeClassName: 'gap-1 shrink-0',
+    badgeIcon: AlertTriangle,
+    badgeLabel: '不支持',
+    description: '当前页面为浏览器内部页面或扩展页面，无法解锁右键功能。请切换到普通网页后重试。',
+    buttonIcon: AlertTriangle,
+    buttonLabel: '不支持',
+    buttonDisabled: true,
+    buttonVariant: 'secondary',
+  },
+  locked: {
+    badgeVariant: 'secondary',
+    badgeClassName: 'gap-1 shrink-0',
+    badgeIcon: Shield,
+    badgeLabel: '未解锁',
+    description: '点击下方按钮，为当前网站临时解锁右键菜单。刷新页面后需要重新解锁。',
+    buttonIcon: MousePointerClick,
+    buttonLabel: '解锁当前网站右键',
+    buttonDisabled: false,
+    buttonVariant: 'default',
+  },
+  unlocked: {
+    badgeVariant: 'default',
+    badgeClassName: 'gap-1 bg-green-600 hover:bg-green-700 shrink-0',
+    badgeIcon: ShieldCheck,
+    badgeLabel: '已解锁',
+    description: '点击下方按钮，为当前网站临时解锁右键菜单。刷新页面后需要重新解锁。',
+    buttonIcon: MousePointerClick,
+    buttonLabel: '右键已解锁',
+    buttonDisabled: true,
+    buttonVariant: 'secondary',
+  },
+};

src/pages/RightClickRestorer/index.tsx

@@ -1,82 +1,52 @@
 import { Button } from '@/components/ui/button';
 import { Label } from '@/components/ui/label';
 import { Badge } from '@/components/ui/badge';
-import { Shield, ShieldCheck, MousePointerClick, AlertTriangle } from 'lucide-react';
+import { Loader2 } from 'lucide-react';
+import { CARD_CLASS, DOMAIN_LABEL, LOADING_TEXT, STATUS_CONFIG } from './constants';
 import { useRightClickRestorer } from './useRightClickRestorer';
 
 export default function Index() {
-  const { domain, isLoading, isUnlocked, isUnsupported, unlock } = useRightClickRestorer();
+  const { domain, isLoading, status, unlock } = useRightClickRestorer();
 
   if (isLoading) {
     return (
       <div className="flex flex-col items-center justify-center py-12 min-h-[280px] w-full">
+        <Loader2 className="h-6 w-6 text-muted-foreground/80 animate-spin" />
         <span className="text-xs text-muted-foreground mt-2 font-medium tracking-wide">
-          {'正在加载...'}
+          {LOADING_TEXT}
         </span>
       </div>
     );
   }
 
+  const config = STATUS_CONFIG[status];
+  const BadgeIcon = config.badgeIcon;
+  const ButtonIcon = config.buttonIcon;
+
   return (
     <div className="p-4 w-full flex flex-col space-y-4">
-      {/* Current Domain */}
-      <div className="w-full rounded-xl border border-border bg-card text-card-foreground shadow-sm overflow-hidden">
-        <div className="p-4">
-          <Label className="text-sm font-medium">{'当前域名'}</Label>
-          <div className="mt-2 flex items-center justify-between gap-2">
+      <div className={CARD_CLASS}>
+        <Label className="text-sm font-medium">{DOMAIN_LABEL}</Label>
+        <div className="flex items-center justify-between gap-2">
           <code className="text-sm bg-muted px-2 py-1 rounded truncate min-w-0 flex-1">
             {domain || '—'}
           </code>
-            {isUnsupported ? (
-              <Badge variant="destructive" className="gap-1 shrink-0">
-                <AlertTriangle className="h-3 w-3" />
-                {'不支持'}
+          <Badge variant={config.badgeVariant} className={config.badgeClassName}>
+            <BadgeIcon className="h-3 w-3" />
+            {config.badgeLabel}
           </Badge>
-            ) : isUnlocked ? (
-              <Badge variant="default" className="gap-1 bg-green-600 hover:bg-green-700 shrink-0">
-                <ShieldCheck className="h-3 w-3" />
-                {'已解锁'}
-              </Badge>
-            ) : (
-              <Badge variant="secondary" className="gap-1 shrink-0">
-                <Shield className="h-3 w-3" />
-                {'未解锁'}
-              </Badge>
-            )}
-          </div>
-        </div>
         </div>
 
-      {/* Unlock Action */}
-      <div className="w-full rounded-xl border border-border bg-card text-card-foreground shadow-sm overflow-hidden">
-        <div className="p-4 space-y-3">
-          {isUnsupported ? (
-            <>
-              <p className="text-xs text-muted-foreground">
-                {'当前页面为浏览器内部页面或扩展页面，无法解锁右键功能。请切换到普通网页后重试。'}
-              </p>
-              <Button className="w-full gap-2" disabled variant="secondary">
-                <AlertTriangle className="h-4 w-4" />
-                {'不支持'}
-              </Button>
-            </>
-          ) : (
-            <>
-              <p className="text-xs text-muted-foreground">
-                {'点击下方按钮，为当前网站临时解锁右键菜单。刷新页面后需要重新解锁。'}
-              </p>
+        <p className="text-xs text-muted-foreground">{config.description}</p>
         <Button
           className="w-full gap-2"
-                onClick={() => void unlock()}
-                disabled={isUnlocked}
-                variant={isUnlocked ? 'secondary' : 'default'}
+          disabled={config.buttonDisabled}
+          variant={config.buttonVariant}
+          onClick={config.buttonDisabled ? undefined : () => void unlock()}
         >
-                <MousePointerClick className="h-4 w-4" />
-                {isUnlocked ? '右键已解锁' : '解锁当前网站右键'}
+          <ButtonIcon className="h-4 w-4" />
+          {config.buttonLabel}
         </Button>
-            </>
-          )}
-        </div>
       </div>
     </div>
   );

src/pages/RightClickRestorer/useRightClickRestorer.ts

@@ -1,29 +1,17 @@
 import { useEffect, useState } from 'react';
 import { MessageAction, sendMessageToContent } from '@/utils/messages';
+import { isUnsupportedPageUrl } from '@/utils/restrictedUrls';
+import type { RestorerStatus } from './constants';
 
-const UNSUPPORTED_PROTOCOLS = new Set([
-  'chrome:',
-  'chrome-extension:',
-  'about:',
-  'edge:',
-  'brave:',
-]);
-
-function isUnsupportedPage(url: string | undefined): boolean {
-  if (!url) return true;
-  try {
-    const protocol = new URL(url).protocol;
-    return UNSUPPORTED_PROTOCOLS.has(protocol);
-  } catch {
-    return true;
-  }
+function deriveStatus(isUnsupported: boolean, isUnlocked: boolean): RestorerStatus {
+  if (isUnsupported) return 'unsupported';
+  return isUnlocked ? 'unlocked' : 'locked';
 }
 
 export interface UseRightClickRestorerReturn {
   domain: string;
   isLoading: boolean;
-  isUnlocked: boolean;
-  isUnsupported: boolean;
+  status: RestorerStatus;
   unlock: () => Promise<void>;
 }
 
@@ -41,7 +29,7 @@ export function useRightClickRestorer(): UseRightClickRestorerReturn {
 
         setDomain(url ? new URL(url).hostname : '');
 
-        if (isUnsupportedPage(url)) {
+        if (isUnsupportedPageUrl(url)) {
           setIsUnsupported(true);
           return;
         }
@@ -76,8 +64,7 @@ export function useRightClickRestorer(): UseRightClickRestorerReturn {
   return {
     domain,
     isLoading,
-    isUnlocked,
-    isUnsupported,
+    status: deriveStatus(isUnsupported, isUnlocked),
     unlock,
   };
 }

src/pages/StorageCleaner/__tests__/index.test.tsx

@@ -1,6 +1,9 @@
-import { render, screen } from '@testing-library/react';
-import { describe, it, expect, vi } from 'vitest';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeEach, describe, it, expect, vi } from 'vitest';
+import { browser } from 'wxt/browser';
 import Index from '../index';
+import { clearStorage, getCookieSize, getCurrentTab } from '@/utils/storageCleaner';
+import { toast } from 'sonner';
 
 // Mock the chrome APIs
 vi.mock('@/utils/chromeStorage', () => ({
@@ -12,7 +15,6 @@ vi.mock('@/utils/chromeStorage', () => ({
 
 vi.mock('@/utils/storageCleaner', () => ({
   getCurrentTab: vi.fn().mockResolvedValue({ id: 1, url: 'https://example.com' }),
-  isRestrictedUrl: vi.fn().mockReturnValue(false),
   getCookieSize: vi.fn().mockResolvedValue(0),
   getLocalStorageSize: vi.fn().mockResolvedValue(0),
   getSessionStorageSize: vi.fn().mockResolvedValue(0),
@@ -23,10 +25,109 @@ vi.mock('@/utils/storageCleaner', () => ({
   formatCleaningResult: vi.fn().mockReturnValue('Cleaned successfully'),
 }));
 
+vi.mock('sonner', () => ({
+  toast: {
+    success: vi.fn(),
+    warning: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+
 describe('StorageCleaner 页面', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(getCurrentTab).mockResolvedValue({ id: 1, url: 'https://example.com' } as any);
+    vi.mocked(clearStorage).mockResolvedValue({ overallSuccess: true });
+  });
+
   it('应该渲染初始化加载状态', () => {
-    // storageCleaner:initializing 的中文文案为「正在读取站点数据...」
     render(<Index />);
-    expect(screen.getByText(/正在读取站点数据/)).toBeInTheDocument();
+    expect(screen.getByText(/正在读取数据/)).toBeInTheDocument();
+  });
+
+  it('读取当前标签页失败时应显示错误提示', async () => {
+    vi.mocked(getCurrentTab).mockRejectedValueOnce(new Error('Tabs unavailable'));
+
+    render(<Index />);
+
+    expect(await screen.findByText('读取数据失败')).toBeInTheDocument();
+  });
+
+  it('确认清理前如果当前标签页变为受限页面，不应执行清理', async () => {
+    render(<Index />);
+
+    const cleanButton = await screen.findByRole('button', { name: /立即清理/ });
+    fireEvent.click(cleanButton);
+
+    vi.mocked(getCurrentTab).mockResolvedValueOnce({
+      id: 1,
+      url: 'chrome://extensions',
+    } as any);
+    fireEvent.click(screen.getByRole('button', { name: /确认清理/ }));
+
+    await waitFor(() => {
+      expect(clearStorage).not.toHaveBeenCalled();
+      expect(toast.warning).toHaveBeenCalledWith('存储清理功能不支持此页面');
+    });
+  });
+
+  it('自动刷新后应等待标签页完成加载并重新读取信息后再允许再次清理', async () => {
+    const tabUpdatedListeners: Array<(tabId: number, changeInfo: { status?: string }) => void> = [];
+    (browser.tabs.onUpdated.addListener as any).mockImplementation((listener: any) => {
+      tabUpdatedListeners.push(listener);
+    });
+    (browser.tabs.onUpdated.removeListener as any).mockImplementation((listener: any) => {
+      const index = tabUpdatedListeners.indexOf(listener);
+      if (index >= 0) tabUpdatedListeners.splice(index, 1);
+    });
+
+    render(<Index />);
+
+    const cleanButton = await screen.findByRole('button', { name: /立即清理/ });
+    fireEvent.click(cleanButton);
+    fireEvent.click(screen.getByRole('button', { name: /确认清理/ }));
+
+    await waitFor(() => expect(browser.tabs.reload).toHaveBeenCalledWith(1));
+
+    const loadingButton = screen.getByRole('button', { name: /正在清理/ });
+    expect(loadingButton).toBeDisabled();
+    fireEvent.click(loadingButton);
+    expect(clearStorage).toHaveBeenCalledTimes(1);
+
+    const reloadListener = tabUpdatedListeners.at(-1);
+    expect(reloadListener).toBeDefined();
+    reloadListener?.(1, { status: 'complete' });
+
+    await waitFor(() => {
+      expect(getCookieSize).toHaveBeenCalledTimes(2);
+      expect(screen.getByRole('button', { name: /立即清理/ })).not.toBeDisabled();
+    });
+  });
+
+  it('展示的数据与当前标签页不一致时不应执行清理', async () => {
+    let currentTabId = 1;
+    vi.mocked(getCurrentTab).mockImplementation(
+      async () =>
+        ({
+          id: currentTabId,
+          url: currentTabId === 1 ? 'https://a.example.com' : 'https://b.example.com',
+        }) as any,
+    );
+
+    render(<Index />);
+
+    await waitFor(() => {
+      expect(screen.getByRole('button', { name: /立即清理/ })).not.toBeDisabled();
+    });
+
+    currentTabId = 2;
+
+    fireEvent.click(screen.getByRole('button', { name: /立即清理/ }));
+    fireEvent.click(screen.getByRole('button', { name: /确认清理/ }));
+
+    await waitFor(() => {
+      expect(clearStorage).not.toHaveBeenCalled();
+      expect(toast.warning).toHaveBeenCalledWith('当前标签页已切换，请等待数据刷新后再清理');
+    });
   });
 });

src/pages/StorageCleaner/components/OptionItem.tsx

@@ -2,17 +2,9 @@ import React from 'react';
 import { formatBytes } from '@/utils/format';
 import { cn } from '@/lib/utils';
 import type { StorageSizeInfo } from '../useStorageCleaner';
+import { OPTION_LABELS } from '../constants';
 import { Checkbox } from '@/components/ui/checkbox';
 
-const OPTION_LABELS: Record<string, string> = {
-  localStorage: 'Local Storage',
-  sessionStorage: 'Session Storage',
-  indexedDB: '站点存储',
-  cookies: 'Cookies',
-  cacheStorage: 'Cache Storage',
-  serviceWorkers: 'Service Workers',
-};
-
 interface OptionItemProps extends React.HTMLAttributes<HTMLDivElement> {
   labelKey: string;
   checked: boolean;
@@ -30,7 +22,8 @@ export default function OptionItem({
 }: OptionItemProps) {
   const sizeValue = sizeInfo?.value;
   const isCount = sizeInfo?.displayType === 'count';
-  const label = OPTION_LABELS[labelKey] || labelKey;
+  const label =
+    labelKey in OPTION_LABELS ? OPTION_LABELS[labelKey as keyof typeof OPTION_LABELS] : labelKey;
 
   return (
     <div

src/pages/StorageCleaner/components/StorageCleanerConfirm.tsx

@@ -10,6 +10,7 @@ import {
 import { Badge } from '@/components/ui/badge';
 import { AlertTriangle } from 'lucide-react';
 import type { StorageCleanerOptions } from '@/types/storage';
+import { OPTION_LABELS } from '../constants';
 import { cn } from '@/lib/utils';
 
 export interface StorageCleanerConfirmProps {
@@ -19,15 +20,6 @@ export interface StorageCleanerConfirmProps {
   options: StorageCleanerOptions;
 }
 
-const OPTION_LABELS: Record<string, string> = {
-  localStorage: 'Local Storage',
-  sessionStorage: 'Session Storage',
-  indexedDB: '站点存储',
-  cookies: 'Cookies',
-  cacheStorage: 'Cache Storage',
-  serviceWorkers: 'Service Workers',
-};
-
 export function StorageCleanerConfirm({
   open,
   onClose,
@@ -36,7 +28,9 @@ export function StorageCleanerConfirm({
 }: StorageCleanerConfirmProps) {
   const selectedOptions = Object.entries(options)
     .filter(([_, value]) => value)
-    .map(([key, _]) => OPTION_LABELS[key] || key);
+    .map(([key]) =>
+      key in OPTION_LABELS ? OPTION_LABELS[key as keyof typeof OPTION_LABELS] : key,
+    );
 
   return (
     <Dialog open={open} onOpenChange={(isOpen) => !isOpen && onClose()}>

src/pages/StorageCleaner/components/StorageOptionsGrid.tsx

@@ -5,6 +5,7 @@ import OptionItem from './OptionItem';
 import { cn } from '@/lib/utils';
 import { Checkbox } from '@/components/ui/checkbox';
 import { Label } from '@/components/ui/label';
+import { CLEAN_OPTION_KEYS } from '../constants';
 
 interface StorageOptionsGridProps extends React.HTMLAttributes<HTMLDivElement> {
   options: StorageCleanerOptions;
@@ -25,15 +26,6 @@ export default function StorageOptionsGrid({
   className,
   ...props
 }: StorageOptionsGridProps) {
-  const optionKeys: (keyof StorageCleanerOptions)[] = [
-    'localStorage',
-    'sessionStorage',
-    'indexedDB',
-    'cookies',
-    'cacheStorage',
-    'serviceWorkers',
-  ];
-
   const handleToggleAll = () => {
     onSelectAll(!allSelected);
   };
@@ -42,7 +34,7 @@ export default function StorageOptionsGrid({
     <div className={cn('w-full overflow-hidden', className)} {...props}>
       <div className="px-3.5 pt-3.5 pb-2">
         <div className="grid grid-cols-2 gap-2 items-stretch">
-          {optionKeys.map((key) => (
+          {CLEAN_OPTION_KEYS.map((key) => (
             <OptionItem
               key={key}
               labelKey={key}

src/pages/StorageCleaner/constants.ts

@@ -0,0 +1,19 @@
+import type { StorageCleanerOptions } from '@/types/storage';
+
+export const CLEAN_OPTION_KEYS = [
+  'localStorage',
+  'sessionStorage',
+  'indexedDB',
+  'cookies',
+  'cacheStorage',
+  'serviceWorkers',
+] as const satisfies readonly (keyof StorageCleanerOptions)[];
+
+export const OPTION_LABELS: Record<(typeof CLEAN_OPTION_KEYS)[number], string> = {
+  localStorage: 'Local Storage',
+  sessionStorage: 'Session Storage',
+  indexedDB: 'IndexedDB',
+  cookies: 'Cookies',
+  cacheStorage: 'Cache Storage',
+  serviceWorkers: 'Service Workers',
+};

src/pages/StorageCleaner/index.tsx

@@ -15,6 +15,7 @@ export default function Index() {
     sizes,
     reloadAfterClean,
     loading,
+    isRefreshingSizes,
     result,
     showConfirm,
     setShowConfirm,
@@ -26,14 +27,14 @@ export default function Index() {
     handleClean,
   } = useStorageCleaner();
 
-  const isButtonDisabled = !(someSelected || allSelected) || loading;
+  const isButtonDisabled = !(someSelected || allSelected) || loading || isRefreshingSizes;
 
   if (isInitializing) {
     return (
       <div className="flex flex-col items-center justify-center py-12 min-h-[280px] w-full">
         <Loader2 className="h-6 w-6 text-muted-foreground/80" />
         <span className="text-xs text-muted-foreground mt-2 font-medium tracking-wide">
-          {'正在读取站点数据...'}
+          {'正在读取数据...'}
         </span>
       </div>
     );

src/pages/StorageCleaner/useStorageCleaner.ts

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { browser } from 'wxt/browser';
 import { storageUtil } from '@/utils/chromeStorage';
 import type {
   CleaningResult,
@@ -14,8 +15,8 @@ import {
   getOriginStorageEstimate,
   getServiceWorkerCount,
   getSessionStorageSize,
-  isRestrictedUrl,
 } from '@/utils/storageCleaner';
+import { isRestrictedUrl } from '@/utils/restrictedUrls';
 import { toast } from 'sonner';
 
 const DEFAULT_OPTIONS: StorageCleanerOptions = {
@@ -32,6 +33,36 @@ const DEFAULT_PREFERENCES: StorageCleanerPreferences = {
   selectedTypes: DEFAULT_OPTIONS,
 };
 
+const RELOAD_COMPLETE_TIMEOUT_MS = 10_000;
+
+async function reloadTabAndWaitForComplete(tabId: number): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    function cleanup() {
+      clearTimeout(timeoutId);
+      browser.tabs.onUpdated.removeListener(handleUpdated);
+    }
+
+    function finish() {
+      cleanup();
+      resolve();
+    }
+
+    function handleUpdated(updatedTabId: number, changeInfo: { status?: string }) {
+      if (updatedTabId === tabId && changeInfo.status === 'complete') {
+        finish();
+      }
+    }
+
+    const timeoutId = setTimeout(finish, RELOAD_COMPLETE_TIMEOUT_MS);
+    browser.tabs.onUpdated.addListener(handleUpdated);
+
+    browser.tabs.reload(tabId).catch((err) => {
+      cleanup();
+      reject(err);
+    });
+  });
+}
+
 export interface StorageSizeInfo {
   value: number;
   displayType: 'bytes' | 'count';
@@ -44,6 +75,7 @@ export interface UseStorageCleanerReturn {
   sizes: Record<string, StorageSizeInfo>;
   reloadAfterClean: boolean;
   loading: boolean;
+  isRefreshingSizes: boolean;
   result: CleaningResult | null;
   showConfirm: boolean;
   setShowConfirm: (show: boolean) => void;
@@ -64,10 +96,12 @@ export function useStorageCleaner(): UseStorageCleanerReturn {
   const [sizes, setSizes] = useState<Record<string, StorageSizeInfo>>({});
   const [reloadAfterClean, setReloadAfterClean] = useState<boolean>(true);
   const [loading, setLoading] = useState<boolean>(false);
+  const [isRefreshingSizes, setIsRefreshingSizes] = useState<boolean>(false);
   const [result, setResult] = useState<CleaningResult | null>(null);
   const [showConfirm, setShowConfirm] = useState<boolean>(false);
 
   const requestIdRef = useRef<number>(0);
+  const boundTabRef = useRef<{ id: number; url: string } | null>(null);
   const debounceTimerRef = useRef<NodeJS.Timeout | null>(null);
   const storageTimerRef = useRef<NodeJS.Timeout | null>(null);
   const loadingRef = useRef(loading);
@@ -86,6 +120,7 @@ export function useStorageCleaner(): UseStorageCleanerReturn {
   // 核心数据拉取链条
   const loadInfo = useCallback(async () => {
     const currentRequestId = ++requestIdRef.current;
+    setIsRefreshingSizes(true);
     try {
       const tab = await getCurrentTab();
       if (currentRequestId !== requestIdRef.current) return;
@@ -128,9 +163,16 @@ export function useStorageCleaner(): UseStorageCleanerReturn {
         cacheStorage: { value: cacheCount, displayType: 'count' },
         serviceWorkers: { value: swCount, displayType: 'count' },
       });
+      boundTabRef.current = { id: tabId, url };
+    } catch (err) {
+      console.error('Failed to load storage cleaner info:', err);
+      if (currentRequestId === requestIdRef.current) {
+        setError('读取数据失败');
+      }
     } finally {
       if (currentRequestId === requestIdRef.current) {
         setIsInitializing(false);
+        setIsRefreshingSizes(false);
       }
     }
   }, []);
@@ -158,14 +200,14 @@ export function useStorageCleaner(): UseStorageCleanerReturn {
       }
     };
 
-    chrome.tabs.onActivated.addListener(handleTabChange);
-    chrome.tabs.onUpdated.addListener(handleTabUpdated);
-    chrome.windows.onFocusChanged.addListener(handleTabChange);
+    browser.tabs.onActivated.addListener(handleTabChange);
+    browser.tabs.onUpdated.addListener(handleTabUpdated);
+    browser.windows.onFocusChanged.addListener(handleTabChange);
 
     return () => {
-      chrome.tabs.onActivated.removeListener(handleTabChange);
-      chrome.tabs.onUpdated.removeListener(handleTabUpdated);
-      chrome.windows.onFocusChanged.removeListener(handleTabChange);
+      browser.tabs.onActivated.removeListener(handleTabChange);
+      browser.tabs.onUpdated.removeListener(handleTabUpdated);
+      browser.windows.onFocusChanged.removeListener(handleTabChange);
     };
   }, [debouncedLoadInfo]);
 
@@ -174,9 +216,15 @@ export function useStorageCleaner(): UseStorageCleanerReturn {
 
     if (storageTimerRef.current) clearTimeout(storageTimerRef.current);
     storageTimerRef.current = setTimeout(async () => {
-      await storageUtil
-        .set('storageCleaner/preferences', { reloadAfterClean, selectedTypes: options })
-        .catch(console.error);
+      try {
+        await storageUtil.set('storageCleaner/preferences', {
+          reloadAfterClean,
+          selectedTypes: options,
+        });
+      } catch (err) {
+        console.error('Failed to save storage cleaner preferences:', err);
+        toast.warning('偏好保存失败，本次设置可能不会保留');
+      }
     }, 500);
   }, [options, reloadAfterClean, isInitializing]);
 
@@ -203,19 +251,34 @@ export function useStorageCleaner(): UseStorageCleanerReturn {
     if (loadingRef.current) return;
 
     const tab = await getCurrentTab();
-    if (!tab || !tab.id || !tab.url) {
+    if (!tab || tab.id === undefined || !tab.url) {
       toast.warning('无法获取当前标签页');
       return;
     }
 
+    if (isRestrictedUrl(tab.url)) {
+      toast.warning('存储清理功能不支持此页面');
+      setShowConfirm(false);
+      return;
+    }
+
+    const boundTab = boundTabRef.current;
+    if (!boundTab || boundTab.id !== tab.id) {
+      toast.warning('当前标签页已切换，请等待数据刷新后再清理');
+      setShowConfirm(false);
+      return;
+    }
+
     setLoading(true);
+    setShowConfirm(false);
     try {
       const cleaningResult = await clearStorage(tab.id, tab.url, options);
       setResult(cleaningResult);
 
       if (reloadAfterClean && cleaningResult.overallSuccess) {
         toast.success('清理成功，即将刷新页面');
-        await chrome.tabs.reload(tab.id);
+        await reloadTabAndWaitForComplete(tab.id);
+        await loadInfo();
       } else {
         await loadInfo();
       }
@@ -247,6 +310,7 @@ export function useStorageCleaner(): UseStorageCleanerReturn {
     sizes,
     reloadAfterClean,
     loading,
+    isRefreshingSizes,
     result,
     showConfirm,
     setShowConfirm,

src/pages/TestDataGenerator/__tests__/index.test.tsx

@@ -0,0 +1,82 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+vi.mock('../hooks/useGenerator', () => ({
+  useGenerator: () => ({
+    isGenerating: false,
+    progress: null,
+    result: null,
+    error: null,
+    generate: vi.fn(),
+    cancel: vi.fn(),
+    clearResult: vi.fn(),
+  }),
+}));
+
+vi.mock('@/utils/ruleStorage', () => ({
+  MAX_RULES: 20,
+  getAll: vi.fn(() => []),
+  save: vi.fn(),
+  deleteRule: vi.fn(),
+  duplicate: vi.fn(),
+  recordUse: vi.fn(),
+  search: vi.fn(() => []),
+  exportRules: vi.fn(() => '[]'),
+  importRules: vi.fn(() => ({ success: 0, failed: 0, errors: [] })),
+}));
+
+vi.mock('sonner', () => ({
+  toast: {
+    success: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+
+import TestDataGeneratorPage from '../index';
+import * as ruleStorage from '@/utils/ruleStorage';
+import { toast } from 'sonner';
+import type { DataRule, FieldConfig } from '@/types/testDataGenerator';
+
+const mockedRuleStorage = vi.mocked(ruleStorage);
+const mockedToast = vi.mocked(toast);
+
+const mockFields: FieldConfig[] = [
+  {
+    id: 'field-1',
+    name: 'name',
+    generatorId: 'string',
+    params: {},
+    required: true,
+    nullRate: 0,
+    unique: false,
+  },
+];
+
+const mockRule: DataRule = {
+  id: 'rule-1',
+  name: '用户数据规则',
+  description: '测试规则',
+  fields: mockFields,
+  createdAt: Date.now(),
+  updatedAt: Date.now(),
+  useCount: 0,
+};
+
+describe('TestDataGeneratorPage', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockedRuleStorage.getAll.mockReturnValue([mockRule]);
+  });
+
+  it('编辑规则时应显示包含规则名的 toast', async () => {
+    const user = userEvent.setup();
+    render(<TestDataGeneratorPage />);
+
+    await user.click(screen.getByText('规则管理'));
+    await user.click(screen.getByTitle('编辑'));
+
+    expect(mockedToast.success).toHaveBeenCalledWith('正在编辑规则「用户数据规则」');
+    expect(mockedToast.success).not.toHaveBeenCalledWith(expect.stringContaining('{{name}}'));
+  });
+});

src/pages/TestDataGenerator/components/DataPreview.tsx

@@ -1,6 +1,5 @@
 /**
  * 数据预览组件
- * 展示一条示例数据，展示数据结构
  */
 
 import { useMemo } from 'react';
@@ -12,7 +11,6 @@ interface DataPreviewProps {
   fields: FieldConfig[];
 }
 
-/** JSON 语法高亮渲染 */
 function JsonHighlight({ data }: { data: Record<string, unknown> }) {
   const formatted = useMemo(() => {
     const lines: { indent: string; key?: string; value: string; isLast: boolean }[] = [];
@@ -45,7 +43,6 @@ function JsonHighlight({ data }: { data: Record<string, unknown> }) {
   );
 }
 
-/** 根据值类型返回颜色类名 */
 function getValueColor(value: string): string {
   if (value === 'null') return 'text-muted-foreground';
   if (value.startsWith('"')) return 'text-emerald-600 dark:text-emerald-400';
@@ -55,13 +52,11 @@ function getValueColor(value: string): string {
 }
 
 export default function DataPreview({ fields }: DataPreviewProps) {
-  // 生成一条示例数据
   const sampleData = useMemo(() => {
     if (fields.length === 0) return null;
 
     const record: Record<string, unknown> = {};
     for (const field of fields) {
-      // 非必填字段预览显示 null
       if (!field.required) {
         record[field.name] = null;
         continue;
@@ -87,7 +82,6 @@ export default function DataPreview({ fields }: DataPreviewProps) {
 
   return (
     <div className="flex flex-col h-full">
-      {/* 示例标签 */}
       <div className="flex items-center justify-between mb-3">
         <div className="flex items-center gap-2">
           <div className="h-5 w-5 rounded bg-primary/10 flex items-center justify-center">
@@ -100,7 +94,6 @@ export default function DataPreview({ fields }: DataPreviewProps) {
         </span>
       </div>
 
-      {/* 示例数据展示 */}
       <div className="flex-1 min-h-0 overflow-auto rounded-lg bg-zinc-950 dark:bg-zinc-900 p-4">
         <JsonHighlight data={sampleData} />
       </div>

src/pages/TestDataGenerator/components/FieldEditor.tsx

@@ -1,6 +1,5 @@
 /**
  * 字段编辑器组件
- * 编辑单个字段的详细配置
  */
 
 import { useState, useCallback } from 'react';
@@ -16,7 +15,6 @@ import GeneratorConfig from './GeneratorConfig';
 interface FieldEditorProps {
   field: FieldConfig;
   onChange: (field: FieldConfig) => void;
-  /** 所有字段名列表，用于检测重复 */
   allFieldNames?: string[];
 }
 
@@ -46,7 +44,6 @@ export default function FieldEditor({ field, onChange, allFieldNames = [] }: Fie
 
   const handleNameChange = (name: string) => {
     onChange({ ...field, name });
-    // 实时校验
     const error = validateFieldName(name);
     setNameError(error);
   };
@@ -59,15 +56,12 @@ export default function FieldEditor({ field, onChange, allFieldNames = [] }: Fie
     onChange({
       ...field,
       required,
-      // 切换为必填时清零，切换为非必填时默认 100%
       nullRate: required ? 0 : 100,
     });
   };
 
   const handleNullRateChange = (nullRate: number) => {
-    // 限制范围 0-100
     const clampedRate = Math.max(0, Math.min(100, nullRate));
-    // 空值率为 0 时自动设为必填
     if (clampedRate === 0) {
       onChange({ ...field, nullRate: clampedRate, required: true });
     } else {
@@ -105,7 +99,6 @@ export default function FieldEditor({ field, onChange, allFieldNames = [] }: Fie
 
   return (
     <div className="space-y-5">
-      {/* 基础配置 */}
       <div className="space-y-4">
         <div className="space-y-2">
           <div className="flex items-center justify-between">
@@ -139,7 +132,6 @@ export default function FieldEditor({ field, onChange, allFieldNames = [] }: Fie
         </div>
       </div>
 
-      {/* 必填/选填配置 */}
       <div className="space-y-3">
         <div className="flex items-center justify-between">
           <Label className="text-sm font-medium text-foreground">{'必填'}</Label>
@@ -187,19 +179,16 @@ export default function FieldEditor({ field, onChange, allFieldNames = [] }: Fie
         )}
       </div>
 
-      {/* 唯一性约束 */}
       <div className="flex items-center justify-between">
         <Label className="text-sm font-medium text-foreground">{'唯一性约束'}</Label>
         <Switch checked={field.unique} onCheckedChange={handleUniqueChange} />
       </div>
 
-      {/* 生成器选择 */}
       <div className="space-y-2">
         <Label className="text-sm font-medium text-foreground">{'数据生成器'}</Label>
         <GeneratorSelector selectedId={field.generatorId} onChange={handleGeneratorChange} />
       </div>
 
-      {/* 生成器参数配置 */}
       {generator && (
         <div className="space-y-2">
           <Label className="text-sm font-medium text-foreground">{'生成器参数'}</Label>

src/pages/TestDataGenerator/components/GenerateButton.tsx

@@ -35,7 +35,7 @@ export default function GenerateButton({
           {progress && (
             <div className="space-y-2">
               <div className="flex items-center justify-between text-xs text-muted-foreground">
-                <span>{'已生成 {{current}} / {{total}} 条'}</span>
+                <span>{`已生成 ${progress.generated} / ${progress.total} 条`}</span>
                 <span>{progress.progress}%</span>
               </div>
               <div className="h-2 bg-muted rounded-full overflow-hidden">
@@ -46,7 +46,7 @@ export default function GenerateButton({
               </div>
               {progress.estimatedTimeLeft !== undefined && (
                 <p className="text-xs text-muted-foreground text-center">
-                  {'预计剩余 {{time}} 秒'}
+                  {`预计剩余 ${progress.estimatedTimeLeft} 秒`}
                 </p>
               )}
             </div>

src/pages/TestDataGenerator/components/ResultPanel.tsx

@@ -84,7 +84,9 @@ export default function ResultPanel({ result }: ResultPanelProps) {
               </li>
             ))}
             {result.warnings.length > 5 && (
-              <li className="text-xs text-yellow-500/80">... {'还有 {{count}} 条警告'}</li>
+              <li className="text-xs text-yellow-500/80">
+                {`... 还有 ${result.warnings.length - 5} 条警告`}
+              </li>
             )}
           </ul>
         </div>

src/pages/TestDataGenerator/components/__tests__/ResultPanel.test.tsx

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import ResultPanel from '../ResultPanel';
+import type { GenerateResult } from '@/types/testDataGenerator';
+
+function createResult(overrides: Partial<GenerateResult> = {}): GenerateResult {
+  return {
+    success: true,
+    warnings: [],
+    stats: {
+      total: 100,
+      success: 100,
+      failed: 0,
+      duration: 1200,
+    },
+    ...overrides,
+  };
+}
+
+describe('ResultPanel', () => {
+  it('警告超过 5 条时应显示剩余警告数量', () => {
+    const warnings = Array.from({ length: 8 }, (_, index) => `警告 ${index + 1}`);
+
+    render(<ResultPanel result={createResult({ warnings })} />);
+
+    expect(screen.getByText('警告 1')).toBeInTheDocument();
+    expect(screen.getByText('警告 5')).toBeInTheDocument();
+    expect(screen.queryByText('警告 6')).not.toBeInTheDocument();
+    expect(screen.getByText('... 还有 3 条警告')).toBeInTheDocument();
+    expect(screen.queryByText(/\{\{count\}\}/)).not.toBeInTheDocument();
+  });
+
+  it('警告不超过 5 条时不应显示剩余提示', () => {
+    const warnings = ['警告 1', '警告 2', '警告 3'];
+
+    render(<ResultPanel result={createResult({ warnings })} />);
+
+    expect(screen.getByText('警告 1')).toBeInTheDocument();
+    expect(screen.getByText('警告 3')).toBeInTheDocument();
+    expect(screen.queryByText(/还有 \d+ 条警告/)).not.toBeInTheDocument();
+  });
+});

src/pages/TestDataGenerator/components/__tests__/RuleManager.test.tsx

@@ -178,6 +178,18 @@ describe('RuleManager', () => {
     vi.restoreAllMocks();
   });
 
+  it('should call onEdit when edit button clicked', async () => {
+    const user = userEvent.setup();
+    const onEdit = vi.fn();
+    mockedRuleStorage.getAll.mockReturnValue([mockRule]);
+
+    render(<RuleManager {...defaultProps} onEdit={onEdit} />);
+
+    await user.click(screen.getByTitle('编辑'));
+
+    expect(onEdit).toHaveBeenCalledWith(mockRule);
+  });
+
   it('should show saved rule count', () => {
     mockedRuleStorage.getAll.mockReturnValue([mockRule]);
 

src/pages/TestDataGenerator/index.tsx

@@ -130,7 +130,7 @@ export default function TestDataGeneratorPage() {
       setEditingRule(rule);
       setActiveTab('fields');
       clearResult();
-      toast.success('正在编辑规则「{{name}}」');
+      toast.success(`正在编辑规则「${rule.name}」`);
     },
     [clearResult],
   );

src/pages/TextStatistics/components/StatCard.tsx

@@ -0,0 +1,17 @@
+interface StatCardProps {
+  label: string;
+  value: React.ReactNode;
+}
+
+export default function StatCard({ label, value }: StatCardProps) {
+  return (
+    <div className="flex flex-col justify-center items-center p-4 text-center rounded-xl border border-border bg-card shadow-sm text-card-foreground hover:-translate-y-0.5 hover:shadow-md hover:border-primary/50 focus-within:ring-1 focus-within:ring-ring">
+      <span className="text-xs font-medium text-muted-foreground tracking-wider mb-1 select-none">
+        {label}
+      </span>
+      <span className="font-mono text-lg md:text-2xl font-extrabold text-primary break-all tracking-tight leading-none tabular-nums select-all">
+        {value}
+      </span>
+    </div>
+  );
+}

src/pages/TextStatistics/index.tsx

@@ -1,18 +1,11 @@
 import TextInputArea from '@/components/TextInputArea';
 import { formatBytes } from '@/utils/format';
+import StatCard from './components/StatCard';
 import { useTextStatistics } from './useTextStatistics';
-import { cn } from '@/lib/utils';
 
 export default function Index() {
   const { text, stats, setText } = useTextStatistics();
 
-  const statItems = [
-    { label: '字符数', value: stats.characters },
-    { label: '单词数', value: stats.words },
-    { label: '行数', value: stats.lines },
-    { label: '字节大小', value: formatBytes(stats.bytes) },
-  ];
-
   return (
     <div className="p-4 w-full space-y-4">
       <TextInputArea
@@ -26,22 +19,10 @@ export default function Index() {
       />
 
       <div className="grid grid-cols-2 md:grid-cols-4 gap-3">
-        {statItems.map((item) => (
-          <div
-            key={item.label}
-            className={cn(
-              'flex flex-col justify-center items-center p-4 text-center rounded-xl border border-border bg-card shadow-sm text-card-foreground',
-              'hover:-translate-y-0.5 hover:shadow-md hover:border-primary/50 focus-within:ring-1 focus-within:ring-ring',
-            )}
-          >
-            <span className="text-xs font-medium text-muted-foreground tracking-wider mb-1 select-none">
-              {item.label}
-            </span>
-            <span className="font-mono text-lg md:text-2xl font-extrabold text-primary break-all tracking-tight leading-none tabular-nums select-all">
-              {item.value}
-            </span>
-          </div>
-        ))}
+        <StatCard label="字符数" value={stats.characters} />
+        <StatCard label="单词数" value={stats.words} />
+        <StatCard label="行数" value={stats.lines} />
+        <StatCard label="字节大小" value={formatBytes(stats.bytes)} />
       </div>
     </div>
   );