refactor: 更新 RouterProvider 以过滤非法页面并合并配置

refactor: 移除 Dashboard 页面及相关功能，更新路由和组件逻辑
- 移除 Dashboard 相关的组件、特性和测试代码，简化项目结构。 - 更新 PageSkeleton 组件，默认渲染工具页面骨架。 - 修改 RouterContainer 和 RouterProvider 以适应新的默认路由策略，确保用户直接访问 timestamp 页面。 - 更新测试用例，确保在新结构下的功能正常。
2026-07-05 22:20:04 +08:00 · 2026-07-05 22:02:25 +08:00 · 2026-07-05 21:55:22 +08:00 · 2026-07-05 21:47:35 +08:00 · 2026-07-05 21:34:41 +08:00 · 2026-06-30 23:15:35 +08:00
203 changed files with 6356 additions and 3491 deletions
@@ -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,
+  component: 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/`            | 静态资源（图标等）                                           |

 ---

@@ -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`
@@ -1,6 +1,6 @@
 # AGENTS.md

-WXT 浏览器扩展项目 (React 19 + TypeScript)。提供时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、Markdown、测试数据生成器等测试效率工具。
+WXT 浏览器扩展项目 (React 19 + TypeScript)。提供时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、测试数据生成器等测试效率工具。

 ## 核心命令

@@ -16,30 +16,64 @@ 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 全部通过）

 ## 项目结构

 ```
-src/                   # 源代码根目录
-  config/features.tsx    # 功能定义（路由 + 元数据的单一事实来源）
-  entrypoints/           # 扩展入口点 (popup/, sidepanel/, background.ts, content.ts)
-  pages/                 # 功能页面组件 (懒加载)
-  components/            # 可复用 UI 组件
-  components/ui/         # shadcn/ui 基础组件 (button, dialog, select 等)
-  providers/             # React Context (Router, Theme 等)
-  hooks/                 # 自定义 React Hooks
-  utils/                 # 工具函数与服务抽象
-  types/                 # TypeScript 类型声明
-  lib/                   # 通用工具函数（cn、utils）
-  workers/               # Web Worker（数据生成等耗时任务）
-public/                # 静态资源（图标、_locales 等）
+src/                     # 源代码根目录
+  config/features.tsx      # 功能定义（路由 + 元数据的单一事实来源）
+  entrypoints/             # 扩展入口点 (popup/, sidepanel/, background.ts, content.ts)
+  layout/                  # 应用壳层布局（TopBar 导航、搜索、主题切换）
+  pages/                   # 功能页面组件 (懒加载)
+  components/              # 可复用 UI 组件
+  components/ui/           # shadcn/ui 基础组件 (button, dialog, select 等)
+  providers/               # React Context (Router, Theme 等)
+  hooks/                   # 自定义 React Hooks
+  utils/                   # 工具函数与服务抽象
+  types/                   # TypeScript 类型声明
+  lib/                     # 通用工具函数（cn、utils）及数据生成器定义
+  workers/                 # Web Worker（数据生成等耗时任务）
+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 通知
@@ -1 +1 @@
-@AGENT.md
+@AGENTS.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`: 管理后台定时任务（如清理后自动刷新）.

 ## 浏览器支持

@@ -5,7 +5,7 @@
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
-    "css": "src/index.css",
+    "css": "src/styles/shell.css",
    "baseColor": "slate",
    "cssVariables": true,
    "prefix": ""
@@ -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>
  );
@@ -0,0 +1,8 @@
+# Spec 目录
+
+功能规格、修复方案与验收标准文档。
+
+| 文档                                                                             | 状态              | 说明                                                 |
+| -------------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------- |
+| [storage-cleaner/indexeddb-fix-plan.md](./storage-cleaner/indexeddb-fix-plan.md) | ✅ Phase 3 已完成 | Storage Cleaner IndexedDB 清理逻辑修复方案与验收标准 |
+| [popup-layout/feature-nav-layout.md](./popup-layout/feature-nav-layout.md)       | 待实施            | Popup 右侧图标导航、移除 Dashboard、默认 timestamp   |
@@ -0,0 +1,356 @@
+# Popup 布局重构 — 功能导航与 Dashboard 移除
+
+> 创建时间: 2026-07-05
+> 状态: 待实施
+> 关联模块: `src/entrypoints/popup/`、`src/layout/FeatureNav/`、`src/providers/RouterProvider.tsx`
+> 影响范围: 仅 popup 入口（tab / sidepanel 不在本次布局范围）
+
+## 背景与目标
+
+当前 popup 采用 **Dashboard 首页 + TopBar 搜索跳转** 模式：用户打开扩展后先看到仪表盘卡片网格，再点击进入具体工具。布局为固定 400×600（见 `src/entrypoints/popup/App.tsx` 与 `src/entrypoints/popup/index.html`），TopBar 在非 dashboard 页面显示「返回首页」按钮。
+
+该模式增加了一步选工具操作。本次重构将 popup 改为 **工具直达 + 右侧常驻导航**，并移除 Dashboard 页面。
+
+| 维度       | 现状                          | 目标                                      |
+| ---------- | ----------------------------- | ----------------------------------------- |
+| 默认页     | `dashboard`                   | 新用户默认 `timestamp`                    |
+| 导航       | Dashboard 卡片网格 + 搜索跳转 | 右侧常驻纯图标导航栏                      |
+| 首页       | Dashboard 独立页              | 移除                                      |
+| Popup 宽度 | 400px                         | 450px（内容区 ~402px + 导航栏 48px）      |
+| 作用范围   | —                             | 仅 popup 改布局；tab / sidepanel 不加导航 |
+
+---
+
+## 布局设计
+
+### 结构示意
+
+```mermaid
+flowchart LR
+  subgraph popup ["Popup 450x600"]
+    subgraph mainCol ["主列 flex-1"]
+      TopBar["TopBar"]
+      Content["RouterContainer"]
+      TopBar --> Content
+    end
+    NavCol["FeatureNav 48px"]
+  end
+  mainCol --- NavCol
+```
+
+### 尺寸约束
+
+| 属性     | 值     | 说明                                           |
+| -------- | ------ | ---------------------------------------------- |
+| 总宽度   | 450px  | `App.tsx` 容器 + `index.html` 内联样式同步修改 |
+| 总高度   | 600px  | 不变                                           |
+| 主内容列 | flex-1 | 约 402px，需 `min-w-0` 防止 flex 子项溢出      |
+| 导航栏   | 48px   | Tailwind `w-12`，固定宽度，不参与 flex 收缩    |
+
+### 视觉规范
+
+- 导航栏：左侧 `border-l border-border`，垂直排列图标按钮
+- 图标按钮：`h-9 w-9` 或 `h-10 w-10`，纯图标
+- Tooltip：使用原生 `title` 属性 + `aria-label={feature.label}`，不引入 Tooltip 组件
+- Active 态：背景 `bg-muted` + 左侧 `border-l-2 border-primary`
+- 导航列表超出高度时：`overflow-y-auto`（600px 高度下 9 个工具通常无需滚动）
+
+---
+
+## FeatureNav 组件规格
+
+新建 `src/layout/FeatureNav/`，遵循 UI + Hook 分离模式（见 `.github/CODING_STANDARDS.md` §11）。
+
+### 文件结构
+
+```
+src/layout/FeatureNav/
+├── index.tsx              # 垂直图标按钮列表、active 高亮、无障碍属性
+├── useFeatureNav.ts       # 读路由状态，暴露 navItems / navigateTo / currentPage
+├── resolveNavFeatures.ts  # 从 Dashboard 迁出的功能列表解析逻辑
+└── __tests__/
+    ├── index.test.tsx
+    └── resolveNavFeatures.test.ts
+```
+
+### resolveNavFeatures.ts
+
+从 `src/pages/Dashboard/dashboardFeatures.ts` 迁出并重命名：
+
+```typescript
+export interface NavFeatureItem {
+  key: PageType;
+  feature: FeatureConfig & { icon: NonNullable<FeatureConfig['icon']> };
+}
+
+export function resolveNavFeatures(keys: PageType[], visiblePages: PageType[]): NavFeatureItem[];
+```
+
+逻辑与旧 `resolveDashboardFeatures` 一致：
+
+- 按 `keys`（即 `pageOrder`）顺序遍历
+- 跳过不在 `visiblePages` 中的项
+- 跳过无 `icon` 的 feature（dashboard 移除后不应出现）
+
+### useFeatureNav.ts
+
+```typescript
+export interface UseFeatureNavReturn {
+  navItems: NavFeatureItem[];
+  currentPage: PageType;
+  navigateTo: (page: PageType) => void;
+}
+```
+
+- 从 `useRouter()` 读取 `currentPage`、`pageOrder`、`visiblePages`、`navigateTo`
+- 用 `useMemo` 调用 `resolveNavFeatures(pageOrder, visiblePages)` 生成 `navItems`
+
+### index.tsx
+
+- 渲染 `<nav aria-label="功能导航">` 包裹垂直按钮列表
+- 每项为 `<button type="button">`，内含 Lucide 图标
+- 点击调用 `navigateTo(item.key)`
+- 当前项添加 active 样式与 `aria-current="page"`
+
+### 引用范围
+
+**仅** `src/entrypoints/popup/App.tsx` 引用 `FeatureNav`。sidepanel / tab 入口不引入该组件。
+
+---
+
+## popup/App.tsx 目标结构
+
+```tsx
+import RouterProvider from '@/providers/RouterProvider';
+import TopBar from '@/layout/TopBar';
+import FeatureNav from '@/layout/FeatureNav';
+import RouterContainer from '@/components/RouterContainer';
+import ErrorBoundary from '@/components/ErrorBoundary';
+
+export default function App() {
+  return (
+    <RouterProvider
+      defaultRoute="timestamp"
+      syncKey="app/popupRoute"
+      visiblePagesKey="app/popupVisiblePages"
+      pageOrderKey="app/popupPageOrder"
+    >
+      <div className="flex w-[450px] max-w-[450px] min-w-[450px] h-[600px] min-h-[600px] overflow-hidden bg-background">
+        <div className="flex flex-col flex-1 min-w-0">
+          <TopBar />
+          <ErrorBoundary>
+            <RouterContainer />
+          </ErrorBoundary>
+        </div>
+        <FeatureNav />
+      </div>
+    </RouterProvider>
+  );
+}
+```
+
+`src/entrypoints/popup/index.html` 内联样式中 `width: 400px` 改为 `width: 450px`。
+
+---
+
+## 移除 Dashboard（全局类型变更）
+
+布局仅改 popup，但 `dashboard` 从 `PageType` 移除会影响全项目类型与路由校验。
+
+### 删除文件
+
+| 路径                                  | 说明             |
+| ------------------------------------- | ---------------- |
+| `src/pages/Dashboard/`                | 整目录（含测试） |
+| `src/config/pageLoaders/dashboard.ts` | Dashboard 懒加载 |
+
+### 修改文件
+
+| 文件                                 | 改动                                                        |
+| ------------------------------------ | ----------------------------------------------------------- |
+| `src/types/storage.d.ts`             | 从 `PageType` 联合类型删除 `'dashboard'`                    |
+| `src/config/featureMeta.ts`          | 删除 dashboard 条目                                         |
+| `src/config/pageLoaders/index.ts`    | 删除 `case 'dashboard'`                                     |
+| `src/components/RouterContainer.tsx` | 去掉 dashboard 骨架屏分支；统一使用 `page-transition-enter` |
+| `src/components/PageSkeleton.tsx`    | 删除 `variant: 'dashboard'` 及对应 UI                       |
+| `src/styles/shell.css`               | 删除 `.page-transition-dashboard`                           |
+
+### TopBar 精简
+
+`src/layout/TopBar/index.tsx` 与 `useTopBar.ts`：
+
+- 删除「返回首页」按钮（`ArrowLeft` + `goHome`）
+- 删除 `isDashboard` 状态及相关导出
+- 搜索过滤中 `f.key === 'dashboard'` 的特殊排除逻辑可删除
+
+### RouterProvider 变更
+
+`src/providers/RouterProvider.tsx`：
+
+- 删除 `goHome()` 方法及 Context 中的 `goHome` 字段
+- 全局 `defaultRoute` 默认值由 `'dashboard'` 改为 `'timestamp'`
+- popup 显式传入 `defaultRoute="timestamp"`（与全局默认一致，便于阅读）
+
+### Sidepanel 最小修复
+
+`src/entrypoints/sidepanel/App.tsx` 若仍存在：
+
+- `defaultRoute="dashboard"` 改为 `defaultRoute="timestamp"`
+- 不添加 FeatureNav 布局
+
+---
+
+## 默认路由策略（仅新用户）
+
+利用现有 `RouterProvider` 机制，**无需额外迁移代码**。
+
+```typescript
+// 首屏（localStorage 快照，消除闪烁）
+const [currentPage] = useState(() => getSyncSnapshot(syncKey, defaultRoute, isValidPage));
+
+// 异步加载 chrome.storage
+const savedRoute = (stored[syncKey] ?? defaultRoute) as PageType;
+if (isValidPage(savedRoute) && syncRoute && !hasUserNavigatedRef.current) {
+  setCurrentPage(savedRoute);
+}
+```
+
+| 场景                                       | 行为                                                             |
+| ------------------------------------------ | ---------------------------------------------------------------- |
+| 新用户（无 `app/popupRoute`）              | 首屏 + 持久化均为 `timestamp`                                    |
+| 老用户（如 `app/popupRoute: 'jsonTools'`） | 恢复上次路由                                                     |
+| 老用户曾存 `dashboard`                     | `isValidPage('dashboard')` 为 false → 回退 `timestamp`（软迁移） |
+| 右键菜单 deep link                         | `?feature=&payload=` 优先级不变，高于默认路由                    |
+| 用户主动切换                               | `navigateTo` 后 `hasUserNavigatedRef` 阻止异步覆盖               |
+
+`visiblePages` / `pageOrder` 中残留的 `dashboard` 由 `mergeWithDefaults` 自动滤除（不在新默认列表中）。
+
+### 边界说明
+
+`recentlyUsedTools` 若含已移除的 `dashboard` 等非法项，当前 `isValidPageList` 校验要求数组**全部**合法，失败时整表回退为 `[]`。影响：TopBar 搜索历史中的「最近使用」可能被清空。此为已知低影响边界；实现时可选优化为「过滤非法项保留合法项」，**非必须**。
+
+---
+
+## 实施顺序
+
+```
+1. 迁出 resolveNavFeatures + 新建 FeatureNav 组件与测试
+2. 修改 popup/App.tsx 布局 + popup/index.html 宽度
+3. 全局移除 dashboard（PageType → FEATURES → pageLoader → 删页面目录）
+4. 精简 TopBar / RouterProvider / RouterContainer / PageSkeleton
+5. 批量更新测试 → npm run typecheck && npm run test && npm run lint
+```
+
+---
+
+## 验收标准
+
+### A. 布局与导航（手动）
+
+| 编号 | 步骤                                 | 期望                                           |
+| ---- | ------------------------------------ | ---------------------------------------------- |
+| A-1  | 首次安装（或清空 storage）打开 popup | 默认显示时间戳页，右侧导航 timestamp 项高亮    |
+| A-2  | 依次点击各导航图标                   | 切换到对应工具页，active 态跟随当前页          |
+| A-3  | hover 各导航图标                     | 显示中文功能名 tooltip（`title` 属性）         |
+| A-4  | 使用过某工具后关闭再打开 popup       | 恢复上次路由（非 dashboard）                   |
+| A-5  | 检查 popup 尺寸                      | 宽度 450px，高度 600px，内容区不被导航挤压溢出 |
+
+### B. Dashboard 移除
+
+| 编号 | 期望                                                                 |
+| ---- | -------------------------------------------------------------------- |
+| B-1  | TopBar 搜索下拉无 dashboard 项                                       |
+| B-2  | TopBar 无「返回首页」按钮                                            |
+| B-3  | `PageType`、`FEATURES`、`loadPage` 中无 dashboard                    |
+| B-4  | storage 中 `app/popupRoute: 'dashboard'` 时打开 popup 落到 timestamp |
+| B-5  | `visiblePages` 含 dashboard 时自动滤除，导航正常显示工具列表         |
+
+### C. 单元测试
+
+| 编号 | 覆盖                                                                       |
+| ---- | -------------------------------------------------------------------------- |
+| C-1  | `FeatureNav` 渲染全部可见工具图标                                          |
+| C-2  | `FeatureNav` 点击图标调用 `navigateTo`                                     |
+| C-3  | `FeatureNav` 当前页对应项有 active 样式 / `aria-current`                   |
+| C-4  | `resolveNavFeatures` 按 pageOrder 排序、respect visiblePages               |
+| C-5  | 更新 `RouterProvider` / `TopBar` / `RouterContainer` / `features` 相关测试 |
+| C-6  | 删除 `src/pages/Dashboard/__tests__/` 下全部测试                           |
+
+### D. CI
+
+| 编号 | 标准                     |
+| ---- | ------------------------ |
+| D-1  | `npm run typecheck` 通过 |
+| D-2  | `npm run test` 通过      |
+| D-3  | `npm run lint` 通过      |
+
+---
+
+## 不在范围
+
+- tab / sidepanel 布局改造（不加 FeatureNav）
+- `visiblePages` / `pageOrder` 可视化配置 UI
+- Popup 高度变更（保持 600px）
+- 修改 `AGENTS.md` 中 spec 目录引用（实际 spec 位于 `docs/spec/`）
+
+---
+
+## PR 检查清单
+
+```markdown
+## 功能
+
+- [ ] 新建 FeatureNav 组件（index / useFeatureNav / resolveNavFeatures）
+- [ ] popup 布局改为双列（主内容 + 右侧导航）
+- [ ] popup 宽度 450px（App.tsx + index.html）
+- [ ] popup defaultRoute="timestamp"
+- [ ] 全局移除 dashboard（PageType、FEATURES、pageLoader、页面目录）
+- [ ] TopBar 移除返回按钮与 goHome 相关逻辑
+- [ ] RouterProvider 移除 goHome，defaultRoute 改为 timestamp
+- [ ] sidepanel defaultRoute 最小修复（若文件存在）
+
+## 测试
+
+- [ ] FeatureNav / resolveNavFeatures 单元测试
+- [ ] 更新 RouterProvider / TopBar / RouterContainer / features 测试
+- [ ] 删除 Dashboard 相关测试
+
+## 验收
+
+- [ ] npm run typecheck / test / lint 通过
+- [ ] 手动 A-1 ~ A-5、B-1 ~ B-4 通过
+```
+
+---
+
+## 风险与边界说明
+
+1. **Dashboard 移除为全局变更**：虽 FeatureNav 仅 popup 使用，但 `PageType` 删除 `dashboard` 会影响所有入口的类型校验与路由合法性。
+2. **老用户 dashboard 路由软迁移**：依赖 `isValidPage` 回退到 `defaultRoute`，不会 crash，但用户会察觉「首页消失、默认变为时间戳」——符合预期。
+3. **450px 宽度**：Chrome popup 允许扩展较默认更宽；若未来 Firefox 有差异需在 Firefox 构建中手动验证。
+4. **recentlyUsedTools 整表校验**：见「默认路由策略 → 边界说明」，可选后续优化。
+
+---
+
+## 相关文件索引
+
+| 文件                                  | 说明                            |
+| ------------------------------------- | ------------------------------- |
+| `src/entrypoints/popup/App.tsx`       | popup 布局入口，引用 FeatureNav |
+| `src/entrypoints/popup/index.html`    | popup 初始尺寸 450px            |
+| `src/layout/FeatureNav/`              | 新建：右侧图标导航              |
+| `src/layout/TopBar/`                  | 精简：移除返回按钮              |
+| `src/providers/RouterProvider.tsx`    | 默认路由、移除 goHome           |
+| `src/config/featureMeta.ts`           | FEATURES 定义，删除 dashboard   |
+| `src/types/storage.d.ts`              | PageType 定义                   |
+| `src/config/pageLoaders/index.ts`     | 页面懒加载路由                  |
+| `src/components/RouterContainer.tsx`  | 页面渲染容器                    |
+| `src/components/PageSkeleton.tsx`     | 加载骨架屏                      |
+| `src/styles/shell.css`                | 页面过渡动画                    |
+| `src/pages/Dashboard/`                | **删除**                        |
+| `src/config/pageLoaders/dashboard.ts` | **删除**                        |
+| `src/entrypoints/sidepanel/App.tsx`   | 最小修复 defaultRoute           |
+
+---
+
+> **注**：项目 spec 文档实际目录为 `docs/spec/`。`AGENTS.md` 中引用的根目录 `spec/README.md` 尚未建立，以本目录 [`README.md`](../README.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                                  |
@@ -2,7 +2,7 @@

 > 版本: v1.0
 > 创建时间: 2024-01-20
-> 状态: 待 Review
+> 状态: 已实现（见 `src/pages/TestDataGenerator/`、`src/lib/generators/`、`src/workers/generator.worker.ts`）

 ## 产品定位

@@ -19,3 +19,30 @@
 - [规则管理](./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)。
+
+## 开发者注意事项（与源码同步）
+
+以下行为以 `src/` 源码为准；设计文档中的旧版 class API、`metadata`/`options` 嵌套结构已废弃。
+
+### Worker 任务 ID（`generationId`）
+
+`useGenerator` 每次调用 `generate()` 递增 `generationIdRef`，经 `start` 消息传入 Worker。Worker 所有响应（`progress` / `complete` / `error`）均携带同一 `generationId`。
+
+- **取消**：`cancel()` 先递增 ID 再发送 `cancel`，使进行中的 Worker 响应被主线程忽略；Worker 每生成 100 行让出事件循环以处理 cancel。
+- **快速重试**：新任务 ID 大于旧响应时，旧消息被丢弃，避免 UI 状态错乱。
+
+类型见 `WorkerRequestMessage` / `WorkerResponseMessage`（`src/types/testDataGenerator.ts`）。
+
+### 规则存储写入失败
+
+`ruleStorage.save()` / `update()` 在 `localStorage.setItem` 失败时返回 `null`（不部分提交）。页面层（如 `FieldList.tsx`）仅在返回值非空时 Toast 成功。详见 [rule-management.md § 存储机制](./rule-management.md#存储机制) 与 `src/utils/README.md`。
@@ -24,25 +24,20 @@

 ## 数据结构

+> **与源码对齐**：类型定义见 `src/types/testDataGenerator.ts`。规则**不**持久化生成数量与导出格式（由页面 `GenerateOptions` 状态管理）。
+
 ### 规则模板

 ```typescript
 interface DataRule {
-  id: string; // 唯一标识
-  name: string; // 规则名称
-  description?: string; // 规则描述
-  fields: FieldConfig[]; // 字段配置
-  options: {
-    total: number; // 生成数量
-    format: 'json' | 'csv';
-    defaultEmptyRate: number; // 默认空值率（0-100）
-  };
-  metadata: {
-    createdAt: number; // 创建时间
-    updatedAt: number; // 更新时间
-    lastUsedAt?: number; // 最后使用时间
-    useCount: number; // 使用次数
-  };
+  id: string;
+  name: string;
+  description?: string;
+  fields: FieldConfig[];
+  createdAt: number;
+  updatedAt: number;
+  lastUsedAt?: number;
+  useCount: number;
 }
 ```

@@ -50,13 +45,14 @@ interface DataRule {

 ```typescript
 interface FieldConfig {
-  id: string; // 字段唯一标识
-  name: string; // 字段名
-  generator: string; // 生成器名称
-  params: Record<string, any>; // 生成器参数
-  unique: boolean; // 唯一性约束
-  required: boolean; // 是否必填
-  emptyRate?: number; // 选填字段的空值概率（0-100）
+  id: string;
+  name: string;
+  description?: string;
+  generatorId: string; // 生成器 ID，对应 lib/generators 中的 id
+  params: Record<string, unknown>;
+  required: boolean;
+  nullRate: number; // 空值率 0-100，仅 required=false 时生效
+  unique: boolean;
 }
 ```

@@ -110,11 +106,9 @@ interface FieldConfig {

 1. 验证规则名称不为空
 2. 检查规则数量是否达到上限（20 条）
-3. 如果达到上限，显示提示"已达到最大规则数量"
-4. 生成唯一 ID
-5. 设置创建时间和更新时间
-6. 初始化使用次数为 0
-7. 保存到 localStorage
+3. 若达上限，`save()` 返回 `null`，UI 应阻止或提示
+4. 生成唯一 ID，写入 `createdAt`/`updatedAt`，`useCount` 初始为 0
+5. 调用 `ruleStorage.save()`；仅当返回值非 `null` 时视为成功（`localStorage` 写入失败同样返回 `null`）

 ---

@@ -167,17 +161,13 @@ interface FieldConfig {
 - 支持按规则描述搜索
 - 搜索为模糊匹配，不区分大小写

-**实现方式**:
+**实现方式**（`src/utils/ruleStorage.ts`）:

 ```typescript
-search(keyword: string): DataRule[] {
-  const rules = this.getAll();
-  const lowerKeyword = keyword.toLowerCase();
+import * as ruleStorage from '@/utils/ruleStorage';

-  return rules.filter(r =>
-    r.name.toLowerCase().includes(lowerKeyword) ||
-    r.description?.toLowerCase().includes(lowerKeyword)
-  );
+function searchRules(query: string): DataRule[] {
+  return ruleStorage.search(query);
 }
 ```

@@ -224,9 +214,7 @@ search(keyword: string): DataRule[] {

 1. 加载原规则配置到编辑器
 2. 用户修改配置
-3. 点击保存时更新规则
-4. 更新 metadata.updatedAt
-5. 保存到 localStorage
+3. 点击保存时调用 `ruleStorage.update()`；返回非 `null` 才更新 `updatedAt` 并提示成功

 ---

@@ -269,18 +257,12 @@ search(keyword: string): DataRule[] {
 **实现方式**:

 ```typescript
-loadRule(ruleId: string): void {
-  const rule = this.storage.getById(ruleId);
+function loadRule(ruleId: string): void {
+  const rule = ruleStorage.getById(ruleId);
+  if (!rule) return;

-  // 应用规则配置
-  this.setFields(rule.fields);
-  this.setOptions(rule.options);
-
-  // 记录使用
-  this.storage.recordUse(ruleId);
-
-  // 更新预览
-  this.updatePreview();
+  setFields(rule.fields);
+  ruleStorage.recordUse(ruleId);
 }
 ```

@@ -292,7 +274,7 @@ loadRule(ruleId: string): void {

 1. 点击"复制"按钮
 2. 创建规则的副本
-3. 名称添加"(副本)"后缀
+3. 名称添加「（副本）」后缀（默认 `duplicate(id, '（副本）')`）
 4. 生成新的 ID
 5. 保存为新规则

@@ -327,23 +309,20 @@ loadRule(ruleId: string): void {
 └─────────────────────────────────────────────────────────────────────┘
 ```

-**导出格式**:
+**导出格式**（`exportRules()` 返回 `DataRule[]` 的 JSON 字符串，无外层包装）:

 ```json
-{
-  "version": "1.0",
-  "exportedAt": "2024-01-20T10:15:45.000Z",
-  "rules": [
-    {
-      "id": "rule_123456",
-      "name": "电商用户数据 - 测试用",
-      "description": "用于测试用户注册功能",
-      "fields": [...],
-      "options": {...},
-      "metadata": {...}
-    }
-  ]
-}
+[
+  {
+    "id": "rule_123456",
+    "name": "电商用户数据 - 测试用",
+    "description": "用于测试用户注册功能",
+    "fields": [],
+    "createdAt": 1704067200000,
+    "updatedAt": 1704067200000,
+    "useCount": 0
+  }
+]
 ```

 ---
@@ -401,63 +380,25 @@ loadRule(ruleId: string): void {

 ### 本地存储

-使用 localStorage 存储规则数据:
+使用 `localStorage`，键名 `testDataGenerator_rules`。API 为**命名导出函数**（见 `src/utils/ruleStorage.ts`）：
+
+| 函数 | 说明 |
+| ---- | ---- |
+| `getAll()` / `getById()` / `getByName()` | 读取 |
+| `save()` / `update()` / `deleteRule()` / `duplicate()` | 写入；失败时返回 `null` 或 `false` |
+| `recordUse()` | 递增 `useCount`、更新 `lastUsedAt` |
+| `search()` / `getRecent()` | 搜索与最近使用 |
+| `exportRules()` / `importRules()` | 导入导出 JSON 数组 |
+| `clear()` | 清空全部规则 |
+
+写入失败（如 `QuotaExceededError`）时，内部 `setAll()` 返回 `false`，`save`/`update` 返回 `null`，`deleteRule` 返回 `false`，并在控制台输出 `[ruleStorage] 保存规则失败`。调用方须检查返回值，避免误报成功。

 ```typescript
-class RuleStorage {
-  private readonly STORAGE_KEY = 'testDataGenerator_rules';
+import * as ruleStorage from '@/utils/ruleStorage';

-  // 获取所有规则
-  getAll(): DataRule[] {
-    const data = localStorage.getItem(this.STORAGE_KEY);
-    return data ? JSON.parse(data) : [];
-  }
-
-  // 保存规则
-  save(rule: DataRule): { success: boolean; message?: string } {
-    const rules = this.getAll();
-
-    // 规则数量限制：最多 20 条
-    const MAX_RULES = 20;
-    if (rules.length >= MAX_RULES) {
-      return {
-        success: false,
-        message: `已达到最大规则数量（${MAX_RULES}条），请删除一些规则后再保存`,
-      };
-    }
-
-    rules.push(rule);
-    localStorage.setItem(this.STORAGE_KEY, JSON.stringify(rules));
-    return { success: true };
-  }
-
-  // 更新规则
-  update(id: string, updates: Partial<DataRule>): void {
-    const rules = this.getAll();
-    const index = rules.findIndex((r) => r.id === id);
-    if (index !== -1) {
-      rules[index] = { ...rules[index], ...updates };
-      localStorage.setItem(this.STORAGE_KEY, JSON.stringify(rules));
-    }
-  }
-
-  // 删除规则
-  delete(id: string): void {
-    const rules = this.getAll();
-    const filtered = rules.filter((r) => r.id !== id);
-    localStorage.setItem(this.STORAGE_KEY, JSON.stringify(filtered));
-  }
-
-  // 记录使用
-  recordUse(id: string): void {
-    const rules = this.getAll();
-    const rule = rules.find((r) => r.id === id);
-    if (rule) {
-      rule.metadata.lastUsedAt = Date.now();
-      rule.metadata.useCount++;
-      localStorage.setItem(this.STORAGE_KEY, JSON.stringify(rules));
-    }
-  }
+const saved = ruleStorage.save({ name: '示例', fields });
+if (!saved) {
+  // 达上限或 localStorage 不可用
 }
 ```

@@ -1,5 +1,7 @@
 # 技术实现

+> **文档同步说明**：本文档含早期设计稿代码示例，部分类型/API 已与实现偏离。开发时请以 `src/types/testDataGenerator.ts`、`src/workers/generator.worker.ts`、`src/pages/TestDataGenerator/hooks/useGenerator.ts`、`src/utils/ruleStorage.ts` 为准。近期变更摘要见 [README § 开发者注意事项](./README.md#开发者注意事项与源码同步)。
+
 ## 技术栈

 | 技术         | 用途     | 版本 |
@@ -1498,6 +1500,69 @@ export class DataExporter {

 ## Web Worker 使用

+### 消息协议
+
+```typescript
+// src/types/testDataGenerator.ts
+
+type WorkerRequestMessage =
+  | { type: 'start'; payload: WorkerStartPayload }
+  | { type: 'cancel' };
+
+type WorkerResponseMessage =
+  | { type: 'progress'; generationId: number; payload: GenerateProgress }
+  | { type: 'complete'; generationId: number; payload: GenerateResult }
+  | { type: 'error'; generationId: number; payload: { error: string } };
+
+interface WorkerStartPayload {
+  generationId: number; // 任务 ID，用于忽略过期响应
+  fields: FieldConfig[];
+  count: number;
+  csvMode: boolean;
+}
+```
+
+### useGenerator Hook
+
+`src/pages/TestDataGenerator/hooks/useGenerator.ts` 负责 Worker 生命周期与 `generationId` 管理：
+
+- Worker **复用**：同一 Hook 实例内只创建一次，出错后 `terminate` 并在下次重建
+- **开始生成**：`generate(fields, count, csvMode?)` 递增 `generationId` 并 post `start`
+- **取消**：`cancel()` 递增 ID（使旧响应失效）并 post `cancel`；取消完成的 `complete` 不写入 `error` 状态
+- **响应过滤**：`onmessage` 中若 `data.generationId !== generationIdRef.current` 则忽略
+
+```typescript
+const generate = (fields: FieldConfig[], count: number, csvMode = false) => {
+  if (isGenerating) return;
+  const generationId = ++generationIdRef.current;
+  worker.postMessage({ type: 'start', payload: { generationId, fields, count, csvMode } });
+};
+
+const cancel = () => {
+  if (workerRef.current && isGenerating) {
+    ++generationIdRef.current;
+    worker.postMessage({ type: 'cancel' });
+    setIsGenerating(false);
+  }
+};
+```
+
+### Worker 实现要点
+
+`src/workers/generator.worker.ts`：
+
+- 按 `field.generatorId` 查找生成器；选填字段按 `nullRate` 随机置 `null`
+- 唯一性：≤1000 条随机+重试；>1000 条优先 `generateAtIndex`
+- 每 `YIELD_EVERY`（100）行 `await setTimeout(0)`，以便处理 `cancel`
+- 进度：每 1000 条或最后一行 post `progress`
+
+---
+
+## Web Worker 使用（历史设计稿，仅供参考）
+
+<details>
+<summary>展开查看旧版设计示例（与当前实现不一致）</summary>
+
 ### 创建 Worker

 ```typescript
@@ -1593,7 +1658,7 @@ export function useGenerator() {
 }
 ```

-### 错误处理
+### 错误处理（设计稿，`useErrorHandler.ts` 未实现）

 ```typescript
 // src/pages/TestDataGenerator/hooks/useErrorHandler.ts
@@ -1636,8 +1701,12 @@ export function useErrorHandler(options: ErrorHandlerOptions = {}) {

 ---

+</details>
+
 ## 错误提示机制

+> 当前实现：`TestDataGenerator/index.tsx` 直接使用 `useGenerator` 的 `error`/`result` 与 `ResultPanel` 展示警告；下方示例引用未实现的 `useErrorHandler`，仅供对照。
+
 ### 错误类型分类

 | 错误类型        | 严重程度 | 触发场景                 | 提示方式      |
@@ -17,3 +17,4 @@

 - 修改图标后需同步更新 `wxt.config.ts` 中的 manifest 配置
 - 图标格式推荐使用 PNG，确保透明背景
+- UI 文案不在此目录维护，见 `src/config/features.tsx` 与各页面组件
@@ -1,8 +1,8 @@
 import React, { useEffect, useRef, useState } from 'react';
 import { Check, Copy } from 'lucide-react';
 import { copyTextToClipboard } from '@/utils/clipboard';
+import { Button, type ButtonProps } from '@/components/ui/button';
 import { cn } from '@/lib/utils';
-import { buttonVariants, type ButtonProps } from '@/components/ui/button';
 import { toast } from 'sonner';

 interface CopyButtonProps extends Omit<ButtonProps, 'children' | 'onClick'> {
@@ -47,25 +47,18 @@ 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={cn(className, copied && 'text-emerald-500')}
      {...props}
    >
-      {copied ? (
-        <Check className="h-[1.2em] w-[1.2em]" />
-      ) : (
-        <Copy className="h-[1.2em] w-[1.2em]" />
-      )}
-    </button>
+      {copied ? <Check className="h-4 w-4" /> : <Copy className="h-4 w-4" />}
+    </Button>
  );
 };

@@ -0,0 +1,194 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+// unmock the globally-mocked component so we test the real implementation
+vi.unmock('@/components/CopyButton');
+
+vi.mock('@/utils/clipboard', () => ({
+  copyTextToClipboard: vi.fn(),
+}));
+
+vi.mock('sonner', () => ({
+  toast: {
+    success: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+
+import { CopyButton } from '@/components/CopyButton';
+import { copyTextToClipboard } from '@/utils/clipboard';
+import { toast } from 'sonner';
+
+const mockedCopy = vi.mocked(copyTextToClipboard);
+const mockedToast = vi.mocked(toast);
+
+describe('CopyButton', () => {
+  beforeEach(() => {
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('复制成功时调用 copyTextToClipboard 并传入正确 text', async () => {
+    mockedCopy.mockResolvedValue(true);
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
+
+    render(<CopyButton text="hello world" />);
+
+    await user.click(screen.getByRole('button'));
+
+    expect(mockedCopy).toHaveBeenCalledWith('hello world');
+    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 });
+
+    render(<CopyButton text="" />);
+
+    await user.click(screen.getByRole('button'));
+
+    expect(mockedCopy).not.toHaveBeenCalled();
+    expect(mockedToast.error).toHaveBeenCalled();
+  });
+
+  it('复制失败时弹出 error toast', async () => {
+    mockedCopy.mockResolvedValue(false);
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
+
+    render(<CopyButton text="something" />);
+
+    await user.click(screen.getByRole('button'));
+
+    expect(mockedCopy).toHaveBeenCalledWith('something');
+    expect(mockedToast.error).toHaveBeenCalled();
+  });
+
+  // ==================== 新增测试 ====================
+
+  it('初始渲染时显示 Copy 图标且无 emerald 样式', () => {
+    render(<CopyButton text="initial" />);
+
+    const button = screen.getByRole('button');
+    expect(button.className).not.toContain('text-emerald');
+    // 通过 aria-label 确认按钮存在，图标由 lucide 渲染为 svg
+    expect(button).toHaveAttribute('aria-label');
+  });
+
+  it('自定义 tooltip 会覆盖默认 title 和 aria-label', () => {
+    render(<CopyButton text="tooltip-test" tooltip="自定义提示" />);
+
+    const button = screen.getByRole('button');
+    expect(button).toHaveAttribute('title', '自定义提示');
+    expect(button).toHaveAttribute('aria-label', '自定义提示');
+  });
+
+  it('className 被正确透传到按钮', () => {
+    render(<CopyButton text="class-test" className="my-custom-class" />);
+
+    const button = screen.getByRole('button');
+    expect(button.className).toContain('my-custom-class');
+  });
+
+  it('点击事件阻止冒泡', async () => {
+    mockedCopy.mockResolvedValue(true);
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
+    const parentClick = vi.fn();
+
+    render(
+      <div onClick={parentClick}>
+        <CopyButton text="stop-propagation" />
+      </div>,
+    );
+
+    await user.click(screen.getByRole('button'));
+
+    expect(mockedCopy).toHaveBeenCalled();
+    expect(parentClick).not.toHaveBeenCalled();
+  });
+
+  it('组件卸载时清除定时器，不触发状态更新警告', async () => {
+    mockedCopy.mockResolvedValue(true);
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
+
+    const { unmount } = render(<CopyButton text="unmount-test" />);
+
+    await user.click(screen.getByRole('button'));
+
+    // 在 1.5 秒超时到期前卸载组件
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+
+    // 卸载不应抛出 "Can't perform a React state update on an unmounted component" 警告
+    expect(() => unmount()).not.toThrow();
+
+    // 前进剩余时间，确认没有异常
+    act(() => {
+      vi.advanceTimersByTime(2000);
+    });
+  });
+
+  it('快速连续点击不会创建多个重叠定时器', async () => {
+    mockedCopy.mockResolvedValue(true);
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
+
+    render(<CopyButton text="rapid-click" />);
+
+    const button = screen.getByRole('button');
+
+    // 快速点击 3 次
+    await user.click(button);
+    await user.click(button);
+    await user.click(button);
+
+    // copyTextToClipboard 应该被调用 3 次（每次点击都执行）
+    expect(mockedCopy).toHaveBeenCalledTimes(3);
+
+    // 但 setTimeout 相关的 clearTimeout + setTimeout 组合应正常工作
+    //  advance 1.5 秒后，copied 状态应恢复为 false
+    act(() => {
+      vi.advanceTimersByTime(1500);
+    });
+
+    await waitFor(() => {
+      expect(button.className).not.toContain('text-emerald');
+    });
+  });
+
+  it('其他 button props 通过 ...props 透传', () => {
+    render(<CopyButton text="props-test" data-testid="copy-btn" disabled id="copy-button-id" />);
+
+    const button = screen.getByRole('button');
+    expect(button).toHaveAttribute('data-testid', 'copy-btn');
+    expect(button).toBeDisabled();
+    expect(button).toHaveAttribute('id', 'copy-button-id');
+  });
+});
@@ -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>
+  );
+}
@@ -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}
+        />
      );
    }

@@ -0,0 +1,96 @@
+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] fade-in-zoom-95',
+        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={
+            isApp ? 'text-sm text-muted-foreground mb-6' : 'text-xs text-muted-foreground 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={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>
+  );
+}
@@ -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
+        />
      );
    }

@@ -4,30 +4,6 @@
 * 用于 Suspense fallback 和初始加载状态，提供平滑的视觉过渡
 * 避免白屏闪烁，减少布局偏移
 */
-interface PageSkeletonProps {
-  /** 骨架屏类型 */
-  variant?: 'dashboard' | 'tool';
-}
-
-/**
- * 仪表盘卡片骨架屏
- */
-function DashboardCardSkeleton() {
-  return (
-    <div className="rounded-xl border border-border p-5 h-[100px]">
-      <div className="flex justify-between items-start">
-        <div className="flex gap-3 items-center">
-          <div className="w-10 h-10 rounded-lg bg-muted animate-pulse" />
-          <div>
-            <div className="w-24 h-5 bg-muted rounded animate-pulse" />
-            <div className="w-32 h-3.5 bg-muted rounded animate-pulse mt-1.5" />
-          </div>
-        </div>
-        <div className="w-3 h-3 rounded-full bg-muted animate-pulse" />
-      </div>
-    </div>
-  );
-}

 /**
 * 工具页面骨架屏
@@ -46,7 +22,7 @@ function ToolPageSkeleton() {
        <div className="w-24 h-9 bg-muted rounded-lg animate-pulse" />
        <div className="w-20 h-9 bg-muted rounded-lg animate-pulse" />
        <div className="flex-1" />
-        <div className="w-22 h-9 bg-muted rounded-lg animate-pulse" />
+        <div className="w-24 h-9 bg-muted rounded-lg animate-pulse" />
      </div>

      {/* 结果区域 */}
@@ -57,22 +33,9 @@ function ToolPageSkeleton() {

 /**
 * 页面加载骨架屏
- *
- * @param props - PageSkeletonProps
- * @returns 骨架屏 JSX 元素
 */
-export default function PageSkeleton({ variant = 'dashboard' }: PageSkeletonProps) {
-  if (variant === 'tool') {
-    return <ToolPageSkeleton />;
-  }
-
-  return (
-    <div className="grid grid-cols-1 sm:grid-cols-[repeat(auto-fill,minmax(300px,1fr))] auto-rows-fr gap-4 p-4">
-      {Array.from({ length: 6 }).map((_, index) => (
-        <DashboardCardSkeleton key={index} />
-      ))}
-    </div>
-  );
+export default function PageSkeleton() {
+  return <ToolPageSkeleton />;
 }

 PageSkeleton.displayName = 'PageSkeleton';
@@ -6,11 +6,11 @@

 | 组件                    | 用途                                                                           |
 | ----------------------- | ------------------------------------------------------------------------------ |
-| `TopBar.tsx`            | 顶部导航栏，集成搜索（含历史记录）、主题切换、语言切换、返回导航               |
 | `RouterContainer.tsx`   | 路由容器，根据当前路由动态渲染对应页面组件，集成错误边界和骨架屏               |
 | `SwitchButtonGroup.tsx` | 通用切换按钮组，支持 `small/medium/large` 三种尺寸，用于页面子模式切换         |
+| `EmptyPlaceholder.tsx`  | 虚线边框空状态占位，统一工具页「暂无结果」提示样式                             |
 | `TextInputArea.tsx`     | 增强文本输入区域，支持校验规则、工具栏操作、字符计数、清空                     |
-| `CopyButton.tsx`        | 一键复制按钮，支持复制成功状态动画，封装 `copyTextToClipboard` 和 `toast` 反馈 |
+| `CopyButton.tsx`        | 一键复制按钮：复制成功后 1.5s 内切换为 Check 图标并应用 `text-emerald-500`；空内容/失败时 `toast` 提示 |
 | `ImageUploader.tsx`     | 图片上传组件，支持拖拽上传、文件选择和预览                                     |
 | `QrCodePreview.tsx`     | 二维码预览组件，展示生成的二维码图片，提供复制和下载操作                       |
 | `DecodeResultPaper.tsx` | Base64 解码结果展示面板，显示 MIME 类型、文件大小、文件名输入和下载按钮        |
@@ -1,54 +1,69 @@
-import { FEATURES, getEntryPointType } from '@/config/features';
+import { getFeatureByKey } from '@/config/features';
+import { loadPage } from '@/config/pageLoaders/index';
 import { useRouter } from '@/providers/RouterProvider';
-import { Suspense } from 'react';
+import type { PageType } from '@/types/storage';
+import { type ComponentType, useEffect, useState } from 'react';
 import PageErrorBoundary from '@/components/PageErrorBoundary';
 import PageSkeleton from '@/components/PageSkeleton';
 import { cn } from '@/lib/utils';
 import { AlertTriangle } from 'lucide-react';

-const entryPointType = getEntryPointType();
+function LoadedPage({ pageKey }: { pageKey: PageType }) {
+  const [Page, setPage] = useState<ComponentType | null>(null);

-export default function RouterContainer() {
-  const { currentPage, isLoaded } = useRouter();
+  useEffect(() => {
+    let cancelled = false;

-  const animationClass =
-    currentPage === 'dashboard' ? 'page-transition-dashboard' : 'page-transition-enter';
+    loadPage(pageKey)
+      .then((mod) => {
+        if (!cancelled) {
+          setPage(() => mod.default);
+        }
+      })
+      .catch((err) => {
+        console.error('[Router Page Load Error]', err);
+      });

-  if (!isLoaded) {
-    return <PageSkeleton variant={currentPage === 'dashboard' ? 'dashboard' : 'tool'} />;
+    return () => {
+      cancelled = true;
+    };
+  }, [pageKey]);
+
+  if (!Page) {
+    return <PageSkeleton />;
  }

-  const currentFeature = FEATURES.find((f) => f.key === currentPage);
-  const MatchedComponent = currentFeature?.components?.[entryPointType];
+  return <Page />;
+}
+
+export default function RouterContainer() {
+  const { currentPage } = useRouter();
+
+  const currentFeature = getFeatureByKey(currentPage);

  return (
    <div
      key={currentPage}
      className={cn(
        'flex-1 flex flex-col overflow-x-hidden overflow-y-auto',
-        'scrollbar-gutter-stable motion-reduce:transition-none',
-        animationClass,
+        'motion-reduce:transition-none page-transition-enter',
      )}
    >
-      <Suspense
-        fallback={<PageSkeleton variant={currentPage === 'dashboard' ? 'dashboard' : 'tool'} />}
-      >
-        <PageErrorBoundary resetKey={currentPage}>
-          {MatchedComponent ? (
-            <MatchedComponent />
-          ) : (
-            <div className="flex-1 flex flex-col items-center justify-center p-8 text-center animate-in fade-in duration-300">
-              <div className="flex h-12 w-12 items-center justify-center rounded-xl bg-destructive/10 text-destructive mb-4">
-                <AlertTriangle className="h-6 w-6" />
-              </div>
-              <h3 className="text-sm font-semibold text-foreground">{'页面未找到'}</h3>
-              <p className="text-xs text-muted-foreground mt-1 max-w-[240px]">
-                {`该功能在当前运行环境（${entryPointType}）下不可用或已被移除。`}
-              </p>
+      <PageErrorBoundary resetKey={currentPage}>
+        {currentFeature ? (
+          <LoadedPage key={currentPage} pageKey={currentPage} />
+        ) : (
+          <div className="flex-1 flex flex-col items-center justify-center p-8 text-center fade-in-300">
+            <div className="flex h-12 w-12 items-center justify-center rounded-xl bg-destructive/10 text-destructive mb-4">
+              <AlertTriangle className="h-6 w-6" />
            </div>
-          )}
-        </PageErrorBoundary>
-      </Suspense>
+            <h3 className="text-sm font-semibold text-foreground">页面未找到</h3>
+            <p className="text-xs text-muted-foreground mt-1 max-w-[240px]">
+              该功能不存在或已被移除。
+            </p>
+          </div>
+        )}
+      </PageErrorBoundary>
    </div>
  );
 }
@@ -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> {
@@ -23,8 +24,7 @@ const SIZE_CLASSES = {
  large: 'text-base h-11 px-4 py-2 rounded-lg',
 } as const;

-const SELECTED_CLASSES =
-  'bg-background text-foreground shadow-sm font-semibold animate-in fade-in-50 zoom-in-95 duration-150';
+const SELECTED_CLASSES = 'bg-background text-foreground shadow-sm font-semibold fade-in-zoom-95';
 const UNSELECTED_CLASSES = 'hover:bg-background/50 hover:text-foreground/80';

 export default function SwitchButtonGroup<T extends string | number = string>({
@@ -45,21 +45,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>
  );
@@ -1,8 +1,9 @@
 import React, { forwardRef, useCallback, useImperativeHandle, useRef, useState } from 'react';
 import { X } from 'lucide-react';
 import { cn } from '@/lib/utils';
-import { toast } from 'sonner'; // 推荐使用 shadcn 的默认 Toast
+import { toast } from 'sonner';
 import { CopyButton } from '@/components/CopyButton';
+import { Button } from './ui/button';

 export type ValidateRule = {
  validator: (value: string) => boolean;
@@ -43,7 +44,6 @@ export interface TextInputAreaProps extends Omit<
  onClear?: () => void;
 }

-// 提炼基础的 ActionButton，全面向 shadcn 核心 Button 样式对齐
 function ActionButton({
  action,
  value,
@@ -125,7 +125,6 @@ const TextInputArea = forwardRef<HTMLTextAreaElement, TextInputAreaProps>((props
    const textArea = internalRef.current;
    if (!textArea) return;

-    // 重置高度计算
    textArea.style.height = 'auto';

    const computedMin = minRows * 24;
@@ -254,7 +253,6 @@ const TextInputArea = forwardRef<HTMLTextAreaElement, TextInputAreaProps>((props

        {hasBottomBar && (
          <div className="flex h-10 items-center justify-between px-4 bg-muted/30 border-t border-border/50">
-            {/* 左侧自定义动作 */}
            <div className="flex items-center gap-1.5 min-w-0">
              {bottomActions.map((action) => (
                <ActionButton
@@ -267,29 +265,35 @@ const TextInputArea = forwardRef<HTMLTextAreaElement, TextInputAreaProps>((props
              ))}
            </div>

-            {/* 右侧系统按钮组 */}
            <div className="flex items-center gap-1.5 ml-auto shrink-0">
              {allowCopy && value && (
-                <CopyButton text={value} tooltip={'复制内容'} size="sm" className="h-7 w-7 p-1" />
+                <CopyButton
+                  text={value}
+                  tooltip="复制内容"
+                  variant="ghost"
+                  size="iconSm"
+                  className="text-muted-foreground hover:text-foreground"
+                />
              )}
              {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"
+                  aria-label="清空"
+                  variant="ghost"
+                  size="iconSm"
+                  className="text-muted-foreground hover:text-destructive hover:bg-destructive/10"
                >
                  <X className="h-4 w-4" />
-                </button>
+                </Button>
              )}
            </div>
          </div>
        )}
      </div>

-      {/* 错误提示 */}
      {displayError && (
-        <p className="text-xs font-medium text-destructive px-0.5 animate-in fade-in slide-in-from-top-1 duration-150">
+        <p className="text-xs font-medium text-destructive px-0.5 fade-in-slide-top-1">
          {displayError}
        </p>
      )}
@@ -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>
-  );
-}
@@ -1,5 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { act, render, screen, waitFor } from '@testing-library/react';
+import { act, render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';

 // unmock the globally-mocked component so we test the real implementation
@@ -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 });

@@ -91,15 +68,10 @@ describe('CopyButton', () => {
    expect(mockedToast.error).toHaveBeenCalled();
  });

-  // ==================== 新增测试 ====================
-
-  it('初始渲染时显示 Copy 图标且无 emerald 样式', () => {
+  it('初始渲染时带有默认 aria-label', () => {
    render(<CopyButton text="initial" />);

-    const button = screen.getByRole('button');
-    expect(button.className).not.toContain('text-emerald');
-    // 通过 aria-label 确认按钮存在，图标由 lucide 渲染为 svg
-    expect(button).toHaveAttribute('aria-label');
+    expect(screen.getByRole('button')).toHaveAttribute('aria-label', '复制');
  });

  it('自定义 tooltip 会覆盖默认 title 和 aria-label', () => {
@@ -142,15 +114,12 @@ describe('CopyButton', () => {

    await user.click(screen.getByRole('button'));

-    // 在 1.5 秒超时到期前卸载组件
    act(() => {
      vi.advanceTimersByTime(500);
    });

-    // 卸载不应抛出 "Can't perform a React state update on an unmounted component" 警告
    expect(() => unmount()).not.toThrow();

-    // 前进剩余时间，确认没有异常
    act(() => {
      vi.advanceTimersByTime(2000);
    });
@@ -164,23 +133,15 @@ describe('CopyButton', () => {

    const button = screen.getByRole('button');

-    // 快速点击 3 次
    await user.click(button);
    await user.click(button);
    await user.click(button);

-    // copyTextToClipboard 应该被调用 3 次（每次点击都执行）
    expect(mockedCopy).toHaveBeenCalledTimes(3);

-    // 但 setTimeout 相关的 clearTimeout + setTimeout 组合应正常工作
-    //  advance 1.5 秒后，copied 状态应恢复为 false
    act(() => {
      vi.advanceTimersByTime(1500);
    });
-
-    await waitFor(() => {
-      expect(button.className).not.toContain('text-emerald');
-    });
  });

  it('其他 button props 通过 ...props 透传', () => {
@@ -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();
+  });
+});
@@ -4,41 +4,17 @@ import PageSkeleton from '@/components/PageSkeleton';

 describe('PageSkeleton 组件', () => {
  describe('渲染测试', () => {
-    it('默认应渲染 dashboard 骨架屏', () => {
+    it('应渲染工具页面骨架', () => {
      const { container } = render(<PageSkeleton />);

-      // dashboard 骨架屏包含 6 个卡片
-      const cards = container.querySelectorAll('.rounded-xl');
-      expect(cards.length).toBe(6);
-    });
-
-    it('variant 为 dashboard 时应渲染仪表盘卡片骨架', () => {
-      const { container } = render(<PageSkeleton variant="dashboard" />);
-
-      // 每个卡片有 2 个骨架元素（图标、文本），6 个卡片共 12 个
-      const cards = container.querySelectorAll('.rounded-xl');
-      expect(cards.length).toBe(6);
-    });
-
-    it('variant 为 tool 时应渲染工具页面骨架', () => {
-      const { container } = render(<PageSkeleton variant="tool" />);
-
-      // tool 骨架屏包含标题、输入区、控制栏 3 个按钮、结果区
      const skeletons = container.querySelectorAll('.animate-pulse');
      expect(skeletons.length).toBeGreaterThan(0);
    });
  });

  describe('布局结构测试', () => {
-    it('dashboard 骨架屏应使用 grid 布局', () => {
-      const { container } = render(<PageSkeleton variant="dashboard" />);
-      const gridContainer = container.firstChild as HTMLElement;
-
-      expect(gridContainer).toHaveClass('grid');
-    });
-
-    it('tool 骨架屏应有内边距', () => {
-      const { container } = render(<PageSkeleton variant="tool" />);
+    it('工具骨架屏应有内边距', () => {
+      const { container } = render(<PageSkeleton />);
      const toolContainer = container.firstChild as HTMLElement;

      expect(toolContainer).toHaveClass('p-5');
@@ -46,16 +22,8 @@ describe('PageSkeleton 组件', () => {
  });

  describe('骨架屏元素测试', () => {
-    it('dashboard 骨架屏应包含圆角和边框样式', () => {
-      const { container } = render(<PageSkeleton variant="dashboard" />);
-
-      // 获取第一个卡片容器
-      const card = container.querySelector('.rounded-xl.border');
-      expect(card).toBeInTheDocument();
-    });
-
-    it('tool 骨架屏应包含动画脉冲效果', () => {
-      const { container } = render(<PageSkeleton variant="tool" />);
+    it('工具骨架屏应包含动画脉冲效果', () => {
+      const { container } = render(<PageSkeleton />);

      const skeletons = container.querySelectorAll('.animate-pulse');
      expect(skeletons.length).toBeGreaterThan(0);
@@ -6,15 +6,14 @@ import type { PageType } from '@/types/storage';
 import React from 'react';

 const mockRouterValue = {
-  currentPage: 'dashboard' as PageType,
-  visiblePages: ['dashboard', 'timestamp'] as PageType[],
+  currentPage: 'timestamp' as PageType,
+  visiblePages: ['timestamp', 'jwt'] as PageType[],
  pageOrder: ['timestamp'] as PageType[],
-  isLoaded: true,
  navigateTo: vi.fn(),
-  syncNavigation: vi.fn(),
-  goBack: vi.fn(),
  setVisiblePages: vi.fn(),
  setPageOrder: vi.fn(),
+  recentlyUsedTools: [] as PageType[],
+  isLoaded: true,
 };

 vi.mock('@/providers/RouterProvider', () => ({
@@ -32,31 +31,15 @@ describe('RouterContainer 组件', () => {
  };

  describe('渲染测试', () => {
-    it('isLoaded 为 false 时应渲染骨架屏', () => {
-      mockRouterValue.isLoaded = false;
+    it('mount 后应直接渲染页面结构（不等待 storage 加载）', () => {
+      mockRouterValue.currentPage = 'timestamp';
      const { container } = renderWithProvider(<RouterContainer />);
-      // 骨架屏使用 animate-pulse 类
-      const skeletons = container.querySelectorAll('.animate-pulse');
-      expect(skeletons.length).toBeGreaterThan(0);
-    });
-
-    it('isLoaded 为 true 时应渲染页面内容', () => {
-      mockRouterValue.isLoaded = true;
-      mockRouterValue.currentPage = 'dashboard';
-      const { container } = renderWithProvider(<RouterContainer />);
-      expect(container.querySelector('.page-transition-dashboard')).toBeInTheDocument();
+      expect(container.querySelector('.page-transition-enter')).toBeInTheDocument();
    });
  });

  describe('动画类测试', () => {
-    it('在 dashboard 页面应应用 dashboard 动画类', () => {
-      mockRouterValue.currentPage = 'dashboard';
-      renderWithProvider(<RouterContainer />);
-      const box = document.querySelector('.page-transition-dashboard');
-      expect(box).toBeInTheDocument();
-    });
-
-    it('在非 dashboard 页面应应用 enter 动画类', () => {
+    it('应应用 enter 动画类', () => {
      mockRouterValue.currentPage = 'timestamp';
      renderWithProvider(<RouterContainer />);
      const box = document.querySelector('.page-transition-enter');
@@ -68,7 +51,7 @@ describe('RouterContainer 组件', () => {
    it('currentPage 变化时应更新', () => {
      const { rerender } = renderWithProvider(<RouterContainer />);

-      mockRouterValue.currentPage = 'timestamp';
+      mockRouterValue.currentPage = 'jwt';
      rerender(<RouterProvider>{<RouterContainer />}</RouterProvider>);

      const box = document.querySelector('.page-transition-enter');
@@ -77,13 +60,11 @@ describe('RouterContainer 组件', () => {
  });

  describe('页面级错误隔离', () => {
-    it('PageErrorBoundary 应包裹在 Suspense 内层', () => {
-      mockRouterValue.isLoaded = true;
-      mockRouterValue.currentPage = 'dashboard';
+    it('PageErrorBoundary 应包裹页面内容', () => {
+      mockRouterValue.currentPage = 'timestamp';
      const { container } = renderWithProvider(<RouterContainer />);

-      // 验证 RouterContainer 的 Box 结构存在
-      const routerBox = container.querySelector('.page-transition-dashboard');
+      const routerBox = container.querySelector('.page-transition-enter');
      expect(routerBox).toBeInTheDocument();
    });
  });
@@ -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();
    });
@@ -21,6 +21,7 @@ const buttonVariants = cva(
        sm: 'h-9 rounded-md px-3',
        lg: 'h-11 rounded-md px-8',
        icon: 'h-10 w-10',
+        iconSm: 'h-7 w-7',
      },
    },
    defaultVariants: {
@@ -16,7 +16,7 @@ const Checkbox = React.forwardRef<
    )}
    {...props}
  >
-    <CheckboxPrimitive.Indicator className={cn('grid place-content-center text-current')}>
+    <CheckboxPrimitive.Indicator className="grid place-content-center text-current">
      <Check className="h-4 w-4" />
    </CheckboxPrimitive.Indicator>
  </CheckboxPrimitive.Root>
@@ -18,7 +18,7 @@ const DialogOverlay = React.forwardRef<
  <DialogPrimitive.Overlay
    ref={ref}
    className={cn(
-      'fixed inset-0 z-50 bg-black/80 dark:bg-black/60 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
+      'fixed inset-0 z-50 bg-black/80 dark:bg-black/60 transition-opacity duration-200 data-[state=closed]:opacity-0 data-[state=open]:opacity-100',
      className,
    )}
    {...props}
@@ -41,7 +41,7 @@ const DialogContent = React.forwardRef<
    <DialogPrimitive.Content
      ref={ref}
      className={cn(
-        'fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-white dark:bg-gray-900 p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] sm:rounded-lg',
+        'fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-white dark:bg-gray-900 p-6 shadow-lg transition-all duration-200 data-[state=closed]:scale-95 data-[state=open]:scale-100 data-[state=closed]:opacity-0 data-[state=open]:opacity-100 sm:rounded-lg',
        className,
      )}
      {...props}
@@ -65,7 +65,7 @@ const SelectContent = React.forwardRef<
    <SelectPrimitive.Content
      ref={ref}
      className={cn(
-        'relative z-50 max-h-96 min-w-[8rem] overflow-hidden rounded-md border bg-popover text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+        'relative z-50 max-h-96 min-w-[8rem] overflow-hidden rounded-md border bg-popover text-popover-foreground shadow-md transition-all duration-200 data-[state=closed]:scale-95 data-[state=open]:scale-100 data-[state=closed]:opacity-0 data-[state=open]:opacity-100',
        position === 'popper' &&
          'data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1',
        className,
@@ -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）
@@ -0,0 +1,83 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const pageLoadTracker = vi.hoisted(() => ({
+  loaded: [] as string[],
+}));
+
+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(9);
+    expect(pageLoadTracker.loaded).toEqual([]);
+  });
+
+  it('loadPage 应仅加载对应页面模块', async () => {
+    const { loadPage } = await import('@/config/pageLoaders/index');
+
+    await loadPage('timestamp');
+
+    expect(pageLoadTracker.loaded).toEqual(['Timestamp']);
+  });
+
+  it('loadPage 切换页面时不应加载无关页面模块', async () => {
+    const { loadPage } = await import('@/config/pageLoaders/index');
+
+    await loadPage('jwt');
+
+    expect(pageLoadTracker.loaded).toEqual(['Jwt']);
+    expect(pageLoadTracker.loaded).not.toContain('QrCode');
+    expect(pageLoadTracker.loaded).not.toContain('TestDataGenerator');
+  });
+});
@@ -9,36 +9,28 @@ import {

 describe('features', () => {
  describe('FEATURES', () => {
-    it('should have 10 features defined', () => {
-      expect(FEATURES).toHaveLength(10);
+    it('应该有9个功能定义', () => {
+      expect(FEATURES).toHaveLength(9);
    });

-    it('should have all required properties for each feature', () => {
+    it('应该有每个功能的所有必需属性', () => {
      FEATURES.forEach((feature) => {
        expect(feature).toHaveProperty('key');
        expect(feature).toHaveProperty('label');
        expect(feature).toHaveProperty('description');
        expect(feature).toHaveProperty('defaultVisible');
-        expect(feature).toHaveProperty('components');
+        expect(feature).not.toHaveProperty('component');
        expect(typeof feature.key).toBe('string');
        expect(typeof feature.label).toBe('string');
        expect(typeof feature.description).toBe('string');
        expect(typeof feature.defaultVisible).toBe('boolean');
-        expect(typeof feature.components).toBe('object');
-        expect(feature.components).toHaveProperty('popup');
-        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');
-          expect(typeof feature.themeColorKey).toBe('string');
-        }
+        expect(feature).toHaveProperty('icon');
+        expect(feature).toHaveProperty('themeColorKey');
+        expect(typeof feature.themeColorKey).toBe('string');
      });
    });

-    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 +38,7 @@ describe('features', () => {
  });

  describe('getFeatureByKey', () => {
-    it('should return dashboard feature', () => {
-      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 +46,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,9 +68,8 @@ describe('features', () => {
      });
    });

-    it('should include dashboard, timestamp, storageCleaner, qrCode', () => {
+    it('应该包含时间戳、存储清理、二维码', () => {
      const visibleKeys = getDefaultVisibleFeatureKeys();
-      expect(visibleKeys).toContain('dashboard');
      expect(visibleKeys).toContain('timestamp');
      expect(visibleKeys).toContain('storageCleaner');
      expect(visibleKeys).toContain('qrCode');
@@ -93,16 +77,15 @@ describe('features', () => {
  });

  describe('getAllFeatureKeys', () => {
-    it('should return all feature keys', () => {
+    it('应该返回所有功能key', () => {
      const allKeys = getAllFeatureKeys();
-      expect(allKeys).toHaveLength(10);
-      expect(allKeys).toContain('dashboard');
+      expect(allKeys).toHaveLength(9);
      expect(allKeys).toContain('timestamp');
      expect(allKeys).toContain('storageCleaner');
      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,21 +93,16 @@ describe('features', () => {
  });

  describe('getDefaultPageOrder', () => {
-    it('should exclude dashboard from page order', () => {
+    it('应该包含所有工具页面', () => {
      const pageOrder = getDefaultPageOrder();
-      expect(pageOrder).not.toContain('dashboard');
+      expect(pageOrder).toHaveLength(9);
    });

-    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', () => {
-      const pageOrder = getDefaultPageOrder();
-      expect(pageOrder).toHaveLength(9);
-    });
  });
 });
@@ -1,4 +1,4 @@
-import { type ComponentType, lazy } from 'react';
+import type { ComponentType } from 'react';
 import type { LucideProps } from 'lucide-react';
 import type { PageType } from '@/types/storage';
 import {
@@ -15,18 +15,6 @@ import {

 export type PaletteColorKey = 'primary' | 'success' | 'warning' | 'error' | 'secondary' | 'info';

-// 懒加载页面组件
-const DashboardPage = lazy(() => import('@/pages/Dashboard'));
-const TimestampPage = lazy(() => import('@/pages/Timestamp'));
-const StorageCleanerPage = lazy(() => import('@/pages/StorageCleaner'));
-const QrCodePage = lazy(() => import('@/pages/QrCode'));
-const TextStatisticsPage = lazy(() => import('@/pages/TextStatistics'));
-const JwtPage = lazy(() => import('@/pages/Jwt'));
-const JsonToolsPage = lazy(() => import('@/pages/JsonTools'));
-const Base64ConverterPage = lazy(() => import('@/pages/Base64Converter'));
-const RightClickRestorerPage = lazy(() => import('@/pages/RightClickRestorer'));
-const TestDataGeneratorPage = lazy(() => import('@/pages/TestDataGenerator'));
-
 export interface FeatureConfig {
  key: PageType;
  label: string;
@@ -34,25 +22,9 @@ export interface FeatureConfig {
  themeColorKey?: PaletteColorKey;
  icon?: ComponentType<LucideProps>;
  defaultVisible: boolean;
-  components: {
-    popup: ComponentType;
-    sidepanel: ComponentType;
-    tab: ComponentType;
-  };
 }

 export const FEATURES: FeatureConfig[] = [
-  {
-    key: 'dashboard',
-    label: '仪表盘',
-    description: '',
-    defaultVisible: true,
-    components: {
-      popup: DashboardPage,
-      sidepanel: DashboardPage,
-      tab: DashboardPage,
-    },
-  },
  {
    key: 'timestamp',
    label: '时间戳',
@@ -60,11 +32,6 @@ export const FEATURES: FeatureConfig[] = [
    themeColorKey: 'primary',
    icon: Clock,
    defaultVisible: true,
-    components: {
-      popup: TimestampPage,
-      sidepanel: TimestampPage,
-      tab: TimestampPage,
-    },
  },
  {
    key: 'storageCleaner',
@@ -73,11 +40,6 @@ export const FEATURES: FeatureConfig[] = [
    themeColorKey: 'warning',
    icon: Database,
    defaultVisible: true,
-    components: {
-      popup: StorageCleanerPage,
-      sidepanel: StorageCleanerPage,
-      tab: StorageCleanerPage,
-    },
  },
  {
    key: 'qrCode',
@@ -86,11 +48,6 @@ export const FEATURES: FeatureConfig[] = [
    themeColorKey: 'success',
    icon: QrCode,
    defaultVisible: true,
-    components: {
-      popup: QrCodePage,
-      sidepanel: QrCodePage,
-      tab: QrCodePage,
-    },
  },
  {
    key: 'textStatistics',
@@ -99,11 +56,6 @@ export const FEATURES: FeatureConfig[] = [
    themeColorKey: 'secondary',
    icon: FileText,
    defaultVisible: true,
-    components: {
-      popup: TextStatisticsPage,
-      sidepanel: TextStatisticsPage,
-      tab: TextStatisticsPage,
-    },
  },
  {
    key: 'jwt',
@@ -112,24 +64,14 @@ export const FEATURES: FeatureConfig[] = [
    themeColorKey: 'info',
    icon: Key,
    defaultVisible: true,
-    components: {
-      popup: JwtPage,
-      sidepanel: JwtPage,
-      tab: JwtPage,
-    },
  },
  {
-    key: 'jsonDiff',
+    key: 'jsonTools',
    label: 'JSON 工具',
    description: '差异比较、格式化、YAML/TOML 转换及压缩',
    themeColorKey: 'primary',
    icon: GitCompareArrows,
    defaultVisible: true,
-    components: {
-      popup: JsonToolsPage,
-      sidepanel: JsonToolsPage,
-      tab: JsonToolsPage,
-    },
  },
  {
    key: 'base64Converter',
@@ -138,11 +80,6 @@ export const FEATURES: FeatureConfig[] = [
    themeColorKey: 'info',
    icon: ArrowLeftRight,
    defaultVisible: true,
-    components: {
-      popup: Base64ConverterPage,
-      sidepanel: Base64ConverterPage,
-      tab: Base64ConverterPage,
-    },
  },
  {
    key: 'rightClickRestorer',
@@ -151,11 +88,6 @@ export const FEATURES: FeatureConfig[] = [
    themeColorKey: 'success',
    icon: MousePointerClick,
    defaultVisible: true,
-    components: {
-      popup: RightClickRestorerPage,
-      sidepanel: RightClickRestorerPage,
-      tab: RightClickRestorerPage,
-    },
  },
  {
    key: 'testDataGenerator',
@@ -164,11 +96,6 @@ export const FEATURES: FeatureConfig[] = [
    themeColorKey: 'warning',
    icon: FileSpreadsheet,
    defaultVisible: true,
-    components: {
-      popup: TestDataGeneratorPage,
-      sidepanel: TestDataGeneratorPage,
-      tab: TestDataGeneratorPage,
-    },
  },
 ];

@@ -185,16 +112,5 @@ export function getAllFeatureKeys(): PageType[] {
 }

 export function getDefaultPageOrder(): PageType[] {
-  return FEATURES.filter((f) => f.key !== 'dashboard').map((f) => f.key);
-}
-
-export function getEntryPointType(): 'popup' | 'sidepanel' | 'tab' {
-  const pathname = window.location.pathname;
-  if (pathname.includes('sidepanel')) {
-    return 'sidepanel';
-  }
-  if (new URLSearchParams(window.location.search).get('mode') === 'tab') {
-    return 'tab';
-  }
-  return 'popup';
+  return FEATURES.map((f) => f.key);
 }
@@ -0,0 +1,8 @@
+export type { FeatureConfig, PaletteColorKey } from '@/config/featureMeta';
+export {
+  FEATURES,
+  getAllFeatureKeys,
+  getDefaultPageOrder,
+  getDefaultVisibleFeatureKeys,
+  getFeatureByKey,
+} from '@/config/featureMeta';
@@ -0,0 +1,5 @@
+import type { ComponentType } from 'react';
+
+export default function loadBase64Converter(): Promise<{ default: ComponentType }> {
+  return import('@/pages/Base64Converter');
+}
@@ -0,0 +1,43 @@
+import type { ComponentType } from 'react';
+import type { PageType } from '@/types/storage';
+
+type PageModule = { default: ComponentType };
+
+let pagesStylesLoaded = false;
+
+function ensurePagesStyles(): Promise<unknown> {
+  if (pagesStylesLoaded) {
+    return Promise.resolve();
+  }
+  pagesStylesLoaded = true;
+  return import('@/styles/pages.css');
+}
+
+export function loadPage(key: PageType): Promise<PageModule> {
+  return ensurePagesStyles().then(() => {
+    switch (key) {
+      case 'timestamp':
+        return import('@/config/pageLoaders/timestamp').then((m) => m.default());
+      case 'storageCleaner':
+        return import('@/config/pageLoaders/storageCleaner').then((m) => m.default());
+      case 'qrCode':
+        return import('@/config/pageLoaders/qrCode').then((m) => m.default());
+      case 'textStatistics':
+        return import('@/config/pageLoaders/textStatistics').then((m) => m.default());
+      case 'jwt':
+        return import('@/config/pageLoaders/jwt').then((m) => m.default());
+      case 'jsonTools':
+        return import('@/config/pageLoaders/jsonTools').then((m) => m.default());
+      case 'base64Converter':
+        return import('@/config/pageLoaders/base64Converter').then((m) => m.default());
+      case 'rightClickRestorer':
+        return import('@/config/pageLoaders/rightClickRestorer').then((m) => m.default());
+      case 'testDataGenerator':
+        return import('@/config/pageLoaders/testDataGenerator').then((m) => m.default());
+      default: {
+        const _exhaustive: never = key;
+        return Promise.reject(new Error(`Unknown page: ${String(_exhaustive)}`));
+      }
+    }
+  });
+}
@@ -0,0 +1,5 @@
+import type { ComponentType } from 'react';
+
+export default function loadJsonTools(): Promise<{ default: ComponentType }> {
+  return import('@/pages/JsonTools');
+}
@@ -0,0 +1,5 @@
+import type { ComponentType } from 'react';
+
+export default function loadJwt(): Promise<{ default: ComponentType }> {
+  return import('@/pages/Jwt');
+}
@@ -0,0 +1,5 @@
+import type { ComponentType } from 'react';
+
+export default function loadQrCode(): Promise<{ default: ComponentType }> {
+  return import('@/pages/QrCode');
+}
@@ -0,0 +1,5 @@
+import type { ComponentType } from 'react';
+
+export default function loadRightClickRestorer(): Promise<{ default: ComponentType }> {
+  return import('@/pages/RightClickRestorer');
+}
@@ -0,0 +1,5 @@
+import type { ComponentType } from 'react';
+
+export default function loadStorageCleaner(): Promise<{ default: ComponentType }> {
+  return import('@/pages/StorageCleaner');
+}
@@ -0,0 +1,5 @@
+import type { ComponentType } from 'react';
+
+export default function loadTestDataGenerator(): Promise<{ default: ComponentType }> {
+  return import('@/pages/TestDataGenerator');
+}
@@ -0,0 +1,5 @@
+import type { ComponentType } from 'react';
+
+export default function loadTextStatistics(): Promise<{ default: ComponentType }> {
+  return import('@/pages/TextStatistics');
+}
@@ -0,0 +1,5 @@
+import type { ComponentType } from 'react';
+
+export default function loadTimestamp(): Promise<{ default: ComponentType }> {
+  return import('@/pages/Timestamp');
+}
@@ -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` 的不同配置实现独立路由
@@ -1,6 +1,6 @@
 import '../../.wxt/types/imports.d.ts';
 import { browser } from 'wxt/browser';
-import { MessageAction, onMessage, sendMessage } from '@/utils/messages';
+import { MessageAction, onMessage } from '@/utils/messages';
 import { createAllContextMenus, parseContextMenuClick } from '@/utils/contextMenu';
 import { saveContextMenuData } from '@/utils/useContextMenuData';
 import { mainWorldInjectionScript } from '@/utils/rightClickInjection';
@@ -24,38 +24,12 @@ export default defineBackground(() => {

    const { featureKey, payload } = result.data;

-    try {
-      const sidePanelState = await browser.storage.local.get('sidePanelOpen');
-      const isSidePanelOpen = sidePanelState.sidePanelOpen === true;
-
-      if (isSidePanelOpen) {
-        await sendMessage(MessageAction.CONTEXT_MENU_CLICKED, { featureKey, payload });
-        return;
-      }
-    } catch (err) {
-      console.debug('[Context Menu] Side panel pipeline is not available:', err);
-    }
-
    await saveContextMenuData({ featureKey, payload });

    try {
      await browser.action.openPopup();
    } catch (err) {
-      console.warn(
-        '[Context Menu] 自动打开 popup 失败，请手动点击扩展图标，暂存数据已安全保留:',
-        err,
-      );
-    }
-  });
-
-  // 监听扩展图标点击事件，安全激活侧边栏
-  browser.action.onClicked.addListener(async (tab) => {
-    if (tab.id) {
-      try {
-        await browser.sidePanel.open({ tabId: tab.id });
-      } catch (err) {
-        console.error('Failed to open side panel via extension action clicked:', err);
-      }
+      console.warn('[Context Menu] 自动打开 popup 失败，请手动点击扩展图标，数据已暂存:', err);
    }
  });

@@ -65,8 +39,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 +53,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 };
    }
  });
@@ -4,18 +4,17 @@ import { getTextStats } from '@/utils/textStatistics';
 import { hidePopover, showTextStatsResult, showTimestampResult } from './uiPopover';

 function convertTimestamp(input: string): string {
-  const invalidText = '无效时间戳';
  const num = Number(input.trim());

  if (isNaN(num)) {
-    return invalidText;
+    return '无效时间戳';
  }

-  // 1e12 判定毫秒级/秒级时间戳兼容
+  // 1e12 区分毫秒/秒级时间戳
  const d = num > 1e12 ? new Date(num) : new Date(num * 1000);

  if (isNaN(d.getTime())) {
-    return invalidText;
+    return '无效时间戳';
  }

  const year = d.getFullYear();
@@ -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, '统计结果');
 }
@@ -1,35 +1,25 @@
 import RouterProvider from '@/providers/RouterProvider';
-import TopBar from '@/components/TopBar';
+import TopBar from '@/layout/TopBar';
+import FeatureNav from '@/layout/FeatureNav';
 import RouterContainer from '@/components/RouterContainer';
 import ErrorBoundary from '@/components/ErrorBoundary';
-import { getEntryPointType } from '@/config/features';
+
 export default function App() {
-  const entryType = getEntryPointType();
-
-  const routerConfig =
-    entryType === 'tab'
-      ? {
-          syncKey: 'app/tabRoute' as const,
-          visiblePagesKey: 'app/tabVisiblePages' as const,
-          pageOrderKey: 'app/tabPageOrder' as const,
-        }
-      : {
-          syncKey: 'app/popupRoute' as const,
-          visiblePagesKey: 'app/popupVisiblePages' as const,
-          pageOrderKey: 'app/popupPageOrder' as const,
-        };
-
  return (
    <RouterProvider
-      syncKey={routerConfig.syncKey}
-      visiblePagesKey={routerConfig.visiblePagesKey}
-      pageOrderKey={routerConfig.pageOrderKey}
+      defaultRoute="timestamp"
+      syncKey="app/popupRoute"
+      visiblePagesKey="app/popupVisiblePages"
+      pageOrderKey="app/popupPageOrder"
    >
-      <div className="app flex flex-col w-[400px] max-w-[400px] min-w-[400px] h-[600px] min-h-[600px] overflow-hidden bg-background sm:w-screen sm:max-w-none sm:min-w-0 sm:h-screen sm:min-h-0">
-        <TopBar />
-        <ErrorBoundary>
-          <RouterContainer />
-        </ErrorBoundary>
+      <div className="flex w-[450px] max-w-[450px] min-w-[450px] h-[600px] min-h-[600px] overflow-hidden bg-background">
+        <div className="flex flex-col flex-1 min-w-0">
+          <TopBar />
+          <ErrorBoundary>
+            <RouterContainer />
+          </ErrorBoundary>
+        </div>
+        <FeatureNav />
      </div>
    </RouterProvider>
  );
@@ -3,12 +3,25 @@
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Testing Tools - 标签页</title>
+    <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 {
-        width: 400px;
+        width: 450px;
        height: 600px;
        margin: 0;
        padding: 0;
@@ -20,13 +33,6 @@
        width: 100%;
        height: 100%;
      }
-      /* If opened in a tab (mode=tab), reset the fixed size */
-      @media screen and (min-width: 600px) {
-        html, body {
-          width: 100%;
-          height: 100%;
-        }
-      }
    </style>
  </head>
  <body>
@@ -1,6 +1,6 @@
 import ReactDOM from 'react-dom/client';
 import AppRoot from '@/providers/AppRoot';
-import '@/index.css';
+import '@/styles/shell.css';
 import App from './App.tsx';

 ReactDOM.createRoot(document.getElementById('root')!).render(
@@ -1,26 +0,0 @@
-import { useEffect } from 'react';
-import RouterProvider from '@/providers/RouterProvider';
-import TopBar from '@/components/TopBar';
-import RouterContainer from '@/components/RouterContainer';
-import ErrorBoundary from '@/components/ErrorBoundary';
-import { MessageAction, sendMessage } from '@/utils/messages';
-
-export default function App() {
-  useEffect(() => {
-    sendMessage(MessageAction.SIDE_PANEL_STATE_CHANGED, { isOpen: true });
-    return () => {
-      sendMessage(MessageAction.SIDE_PANEL_STATE_CHANGED, { isOpen: false });
-    };
-  }, []);
-
-  return (
-    <RouterProvider defaultRoute="dashboard" syncKey="app/sidepanelRoute">
-      <div className="app flex flex-col h-screen w-full overflow-hidden">
-        <TopBar />
-        <ErrorBoundary>
-          <RouterContainer />
-        </ErrorBoundary>
-      </div>
-    </RouterProvider>
-  );
-}
@@ -1,12 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Testing Tools - Side Panel</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="./main.tsx"></script>
-  </body>
-</html>
@@ -1,10 +0,0 @@
-import ReactDOM from 'react-dom/client';
-import AppRoot from '@/providers/AppRoot';
-import '@/index.css';
-import App from './App.tsx';
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <AppRoot>
-    <App />
-  </AppRoot>,
-);
@@ -0,0 +1,54 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import type { PageType } from '@/types/storage';
+import FeatureNav from '@/layout/FeatureNav';
+
+const mockNavigateTo = vi.fn();
+
+const mockRouterValue = {
+  currentPage: 'timestamp' as PageType,
+  visiblePages: ['timestamp', 'jwt', 'storageCleaner'] as PageType[],
+  pageOrder: ['jwt', 'timestamp', 'storageCleaner'] as PageType[],
+  recentlyUsedTools: [] as PageType[],
+  isLoaded: true,
+  navigateTo: mockNavigateTo,
+  setVisiblePages: vi.fn(),
+  setPageOrder: vi.fn(),
+};
+
+vi.mock('@/providers/RouterProvider', () => ({
+  useRouter: () => mockRouterValue,
+}));
+
+describe('FeatureNav 组件', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockRouterValue.currentPage = 'timestamp';
+    mockRouterValue.pageOrder = ['jwt', 'timestamp', 'storageCleaner'];
+    mockRouterValue.visiblePages = ['timestamp', 'jwt', 'storageCleaner'];
+  });
+
+  it('应渲染全部可见工具图标', () => {
+    render(<FeatureNav />);
+
+    expect(screen.getByLabelText('JWT 解析')).toBeInTheDocument();
+    expect(screen.getByLabelText('时间戳')).toBeInTheDocument();
+    expect(screen.getByLabelText('存储清理')).toBeInTheDocument();
+  });
+
+  it('点击图标应调用 navigateTo', () => {
+    render(<FeatureNav />);
+
+    fireEvent.click(screen.getByLabelText('JWT 解析'));
+    expect(mockNavigateTo).toHaveBeenCalledWith('jwt');
+  });
+
+  it('当前页对应项应有 active 样式与 aria-current', () => {
+    render(<FeatureNav />);
+
+    const activeButton = screen.getByLabelText('时间戳');
+    expect(activeButton).toHaveAttribute('aria-current', 'page');
+    expect(activeButton).toHaveClass('bg-muted');
+    expect(activeButton).toHaveClass('border-primary');
+  });
+});
@@ -0,0 +1,58 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import * as featureConfig from '@/config/features';
+import { resolveNavFeatures } from '../resolveNavFeatures';
+
+describe('resolveNavFeatures', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('应按 keys 顺序返回可见工具', () => {
+    const items = resolveNavFeatures(['jwt', 'timestamp'], ['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 = resolveNavFeatures(['timestamp'], ['timestamp']);
+
+    expect(items.map((item) => item.key)).toEqual(['timestamp']);
+  });
+
+  it('应过滤不在 visiblePages 中的工具', () => {
+    const items = resolveNavFeatures(['jwt', 'timestamp'], ['timestamp']);
+
+    expect(items.map((item) => item.key)).toEqual(['timestamp']);
+  });
+
+  it('visiblePages 无匹配工具时应返回空列表', () => {
+    const items = resolveNavFeatures(['jwt', 'timestamp'], []);
+
+    expect(items).toEqual([]);
+  });
+
+  it('应过滤缺少 icon 的工具', () => {
+    const originalGetFeatureByKey = featureConfig.getFeatureByKey;
+    vi.spyOn(featureConfig, 'getFeatureByKey').mockImplementation((key) => {
+      const feature = originalGetFeatureByKey(key);
+      if (key === 'jwt' && feature) {
+        return { ...feature, icon: undefined };
+      }
+      return feature;
+    });
+
+    const items = resolveNavFeatures(['jwt', 'timestamp'], ['jwt', 'timestamp']);
+
+    expect(items.map((item) => item.key)).toEqual(['timestamp']);
+  });
+});
@@ -0,0 +1,35 @@
+import { cn } from '@/lib/utils';
+import { useFeatureNav } from './useFeatureNav';
+
+export default function FeatureNav() {
+  const { navItems, currentPage, navigateTo } = useFeatureNav();
+
+  return (
+    <nav
+      aria-label="功能导航"
+      className="flex w-12 shrink-0 flex-col items-center gap-1 overflow-y-auto border-l border-border py-2"
+    >
+      {navItems.map(({ key, feature }) => {
+        const Icon = feature.icon;
+        const isActive = currentPage === key;
+
+        return (
+          <button
+            key={key}
+            type="button"
+            title={feature.label}
+            aria-label={feature.label}
+            aria-current={isActive ? 'page' : undefined}
+            onClick={() => navigateTo(key)}
+            className={cn(
+              'flex h-9 w-9 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-muted hover:text-foreground',
+              isActive && 'border-l-2 border-primary bg-muted text-foreground',
+            )}
+          >
+            <Icon className="h-4 w-4" aria-hidden="true" />
+          </button>
+        );
+      })}
+    </nav>
+  );
+}
@@ -0,0 +1,27 @@
+import { getFeatureByKey, type FeatureConfig } from '@/config/features';
+import type { PageType } from '@/types/storage';
+
+export interface NavFeatureItem {
+  key: PageType;
+  feature: FeatureConfig & { icon: NonNullable<FeatureConfig['icon']> };
+}
+
+function isNavFeature(feature: FeatureConfig): feature is NavFeatureItem['feature'] {
+  return feature.icon != null;
+}
+
+export function resolveNavFeatures(keys: PageType[], visiblePages: PageType[]): NavFeatureItem[] {
+  const visibleSet = new Set(visiblePages);
+  const items: NavFeatureItem[] = [];
+
+  for (const key of keys) {
+    if (!visibleSet.has(key)) continue;
+
+    const feature = getFeatureByKey(key);
+    if (!feature || !isNavFeature(feature)) continue;
+
+    items.push({ key, feature });
+  }
+
+  return items;
+}
@@ -0,0 +1,21 @@
+import { useMemo } from 'react';
+import { useRouter } from '@/providers/RouterProvider';
+import type { PageType } from '@/types/storage';
+import { resolveNavFeatures, type NavFeatureItem } from './resolveNavFeatures';
+
+export interface UseFeatureNavReturn {
+  navItems: NavFeatureItem[];
+  currentPage: PageType;
+  navigateTo: (page: PageType) => void;
+}
+
+export function useFeatureNav(): UseFeatureNavReturn {
+  const { currentPage, pageOrder, visiblePages, navigateTo } = useRouter();
+
+  const navItems = useMemo(
+    () => resolveNavFeatures(pageOrder, visiblePages),
+    [pageOrder, visiblePages],
+  );
+
+  return { navItems, currentPage, navigateTo };
+}
@@ -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
+```
@@ -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();
+  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 fade-in-slide-top-2">
+      <ul role="listbox" className="p-1.5">
+        {!isSearching && items.length > 0 && (
+          <li className="px-3 py-1.5 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground/60">
+            最近搜索
+          </li>
+        )}
+        {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>
+  );
+}
@@ -0,0 +1,55 @@
+import { type KeyboardEvent, 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: 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}
+        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 ? (
+        <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>
+      ) : (
+        <kbd className="pointer-events-none absolute right-3 top-1/2 hidden h-5 -translate-y-1/2 items-center 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>
+      )}
+    </div>
+  );
+}
@@ -0,0 +1,30 @@
+import { type FeatureConfig } from '@/config/features';
+import { cn } from '@/lib/utils';
+
+interface SearchResultItemProps {
+  feature: FeatureConfig;
+  selected: boolean;
+  onSelect: (feature: FeatureConfig) => void;
+}
+
+export default function SearchResultItem({ 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>
+  );
+}
@@ -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>
+  );
+}
@@ -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');
+  });
+});
@@ -1,8 +1,8 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { fireEvent, render, screen } from '@testing-library/react';
+import { 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';

@@ -21,13 +21,12 @@ Object.defineProperty(window, 'matchMedia', {
 });

 const mockRouterValue = {
-  currentPage: 'dashboard' as PageType,
-  visiblePages: ['dashboard', 'timestamp'] as PageType[],
+  currentPage: 'timestamp' as PageType,
+  visiblePages: ['timestamp', 'jwt'] as PageType[],
  pageOrder: ['timestamp'] as PageType[],
+  recentlyUsedTools: [] as PageType[],
  isLoaded: true,
  navigateTo: vi.fn(),
-  syncNavigation: vi.fn(),
-  goBack: vi.fn(),
  setVisiblePages: vi.fn(),
  setPageOrder: vi.fn(),
 };
@@ -51,26 +50,14 @@ describe('TopBar 组件', () => {
  };

  describe('渲染测试', () => {
-    it('不在 dashboard 时应渲染返回按钮', () => {
-      mockRouterValue.currentPage = 'timestamp';
+    it('不应渲染返回首页按钮', () => {
      renderWithProvider(<TopBar />);
-      expect(screen.getByLabelText('返回')).toBeInTheDocument();
+      expect(screen.queryByLabelText('返回首页')).not.toBeInTheDocument();
    });

-    it('在 dashboard 上不应渲染返回按钮', () => {
-      mockRouterValue.currentPage = 'dashboard';
+    it('应渲染搜索输入框', () => {
      renderWithProvider(<TopBar />);
-      expect(screen.queryByLabelText('返回')).not.toBeInTheDocument();
-    });
-  });
-
-  describe('交互测试', () => {
-    it('点击返回按钮时应调用 goBack', () => {
-      mockRouterValue.currentPage = 'timestamp';
-      renderWithProvider(<TopBar />);
-
-      fireEvent.click(screen.getByLabelText('返回'));
-      expect(mockRouterValue.goBack).toHaveBeenCalledTimes(1);
+      expect(screen.getByRole('textbox')).toBeInTheDocument();
    });
  });
 });
@@ -0,0 +1,9 @@
+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 {
+  return /Mac|iPhone|iPad|iPod/i.test(navigator.userAgent) ? '⌘K' : 'Ctrl+K';
+}
@@ -0,0 +1,52 @@
+import SearchDropdown from './SearchDropdown';
+import SearchInput from './SearchInput';
+import TopBarActions from './TopBarActions';
+import { useTopBar } from './useTopBar';
+
+export default function TopBar() {
+  const {
+    searchQuery,
+    searchResults,
+    recentFeatures,
+    selectedIndex,
+    ThemeIcon,
+    themeTitle,
+    showDropdown,
+    containerRef,
+    inputRef,
+    handleSearchQueryChange,
+    handleSearchFocus,
+    handleSelectFeature,
+    handleKeyDown,
+    cycleThemeMode,
+    clearSearch,
+  } = useTopBar();
+
+  const actions = [{ id: 'theme', icon: ThemeIcon, title: themeTitle, onClick: cycleThemeMode }];
+
+  return (
+    <header className="relative z-50 flex h-14 items-center justify-between border-b border-border bg-background px-4">
+      <div ref={containerRef} className="relative mx-4 max-w-md flex-1">
+        <SearchInput
+          inputRef={inputRef}
+          searchQuery={searchQuery}
+          onSearchQueryChange={handleSearchQueryChange}
+          onFocus={handleSearchFocus}
+          onKeyDown={handleKeyDown}
+          onClear={clearSearch}
+        />
+        {showDropdown && (
+          <SearchDropdown
+            searchQuery={searchQuery}
+            searchResults={searchResults}
+            recentFeatures={recentFeatures}
+            selectedIndex={selectedIndex}
+            onSelect={handleSelectFeature}
+          />
+        )}
+      </div>
+
+      <TopBarActions actions={actions} />
+    </header>
+  );
+}
@@ -0,0 +1,169 @@
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type KeyboardEvent as ReactKeyboardEvent,
+  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 { isSearchHistory, SEARCH_HISTORY_DISPLAY, SEARCH_HISTORY_LIMIT } from './constants';
+
+export interface UseTopBarReturn {
+  searchQuery: string;
+  searchResults: FeatureConfig[];
+  recentFeatures: FeatureConfig[];
+  selectedIndex: number;
+  ThemeIcon: typeof Sun;
+  themeTitle: string;
+  showDropdown: boolean;
+  containerRef: RefObject<HTMLDivElement | null>;
+  inputRef: RefObject<HTMLInputElement | null>;
+  handleSearchQueryChange: (value: string) => void;
+  handleSearchFocus: () => void;
+  handleSelectFeature: (feature: FeatureConfig) => void;
+  handleKeyDown: (e: ReactKeyboardEvent) => void;
+  cycleThemeMode: () => void;
+  clearSearch: () => void;
+}
+
+export function useTopBar(): UseTopBarReturn {
+  const { 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);
+
+  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) => {
+      return f.label.toLowerCase().includes(query) || f.description.toLowerCase().includes(query);
+    });
+  }, [searchQuery]);
+
+  const recentFeatures = 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);
+  }, [searchHistory, searchQuery]);
+
+  const saveToHistory = (featureKey: string) => {
+    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: ReactKeyboardEvent) => {
+    const isSearching = !!searchQuery.trim();
+    const items = isSearching ? searchResults : recentFeatures;
+    const totalItems = items.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();
+      let feature: FeatureConfig | undefined;
+      if (selectedIndex >= 0 && selectedIndex < totalItems) {
+        feature = items[selectedIndex];
+      } else if (isSearching && searchResults.length > 0) {
+        feature = searchResults[0];
+      }
+      if (feature) handleSelectFeature(feature);
+    } else if (e.key === 'Escape') {
+      setShowResults(false);
+      inputRef.current?.blur();
+    }
+  };
+
+  const clearSearch = () => {
+    setSearchQuery('');
+    setSelectedIndex(-1);
+  };
+
+  const handleSearchQueryChange = (value: string) => {
+    setSearchQuery(value);
+    setShowResults(true);
+    setSelectedIndex(-1);
+  };
+
+  const handleSearchFocus = () => setShowResults(true);
+
+  const showDropdown = showResults && (!!searchQuery.trim() || recentFeatures.length > 0);
+
+  return {
+    searchQuery,
+    searchResults,
+    recentFeatures,
+    selectedIndex,
+    showDropdown,
+    ThemeIcon,
+    themeTitle,
+    containerRef,
+    inputRef,
+    handleSearchQueryChange,
+    handleSearchFocus,
+    handleSelectFeature,
+    handleKeyDown,
+    cycleThemeMode,
+    clearSearch,
+  };
+}
@@ -4,9 +4,10 @@

 ## 文件说明

-| 文件       | 用途                                 |
-| ---------- | ------------------------------------ |
-| `utils.ts` | `cn()` 函数 — shadcn/ui 标准工具函数 |
+| 文件/目录     | 用途                                   |
+| ------------- | -------------------------------------- |
+| `utils.ts`    | `cn()` 函数 — shadcn/ui 标准工具函数   |
+| `generators/` | 测试数据生成器内置生成器库和分类注册表 |

 ## cn()

@@ -24,3 +25,31 @@ 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`     | 基础类型生成器（整数、浮点数、布尔值、字符串） |
+
+使用示例：
+
+```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` 能展示该分类。
@@ -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');
+  });
+});
@@ -1,27 +1,6 @@
-/**
- * 基础类型生成器
- * 包含：随机整数、随机浮点数、随机字符串、从列表选择
- */
-
 import type { GeneratorDefinition } from '@/types/testDataGenerator';
+import { randomInt, randomPick } from './random';

-/**
- * 生成随机整数
- */
-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)];
-}
-
-/**
- * 随机整数生成器
- */
 export const randomIntGenerator: GeneratorDefinition = {
  id: 'randomInt',
  name: '随机整数',
@@ -56,9 +35,6 @@ export const randomIntGenerator: GeneratorDefinition = {
  },
 };

-/**
- * 随机浮点数生成器
- */
 export const randomFloat: GeneratorDefinition = {
  id: 'randomFloat',
  name: '随机浮点数',
@@ -98,9 +74,6 @@ export const randomFloat: GeneratorDefinition = {
  },
 };

-/**
- * 随机字符串生成器
- */
 export const randomString: GeneratorDefinition = {
  id: 'randomString',
  name: '随机字符串',
@@ -179,9 +152,6 @@ export const randomString: GeneratorDefinition = {
  },
 };

-/**
- * 从列表选择生成器
- */
 export const fromList: GeneratorDefinition = {
  id: 'fromList',
  name: '从列表选择',
@@ -1,27 +1,6 @@
-/**
- * 业务数据生成器
- * 包含：订单号、价格、日期、状态、数量、评分、折扣、库存
- */
-
 import type { GeneratorDefinition } from '@/types/testDataGenerator';
+import { randomInt, randomPick } from './random';

-/**
- * 生成随机整数
- */
-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)];
-}
-
-/**
- * 格式化日期
- */
 function formatDate(date: Date, format: string): string {
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, '0');
@@ -39,9 +18,6 @@ function formatDate(date: Date, format: string): string {
    .replace('ss', seconds);
 }

-/**
- * 订单号生成器
- */
 export const orderId: GeneratorDefinition = {
  id: 'orderId',
  name: '订单号',
@@ -81,9 +57,6 @@ export const orderId: GeneratorDefinition = {
  },
 };

-/**
- * 价格生成器
- */
 export const price: GeneratorDefinition = {
  id: 'price',
  name: '价格',
@@ -155,9 +128,6 @@ export const price: GeneratorDefinition = {
  },
 };

-/**
- * 生成心理定价（如 9.99, 19.9, 99）
- */
 function generatePsychologicalPrice(min: number, max: number): number {
  const patterns = [
    () => {
@@ -180,9 +150,6 @@ function generatePsychologicalPrice(min: number, max: number): number {
  return price;
 }

-/**
- * 生成真实分布价格（对数正态分布）
- */
 function generateRealisticPrice(min: number, max: number): number {
  const mean = (Math.log(min) + Math.log(max)) / 2;
  const stdDev = (Math.log(max) - Math.log(min)) / 4;
@@ -195,9 +162,6 @@ function generateRealisticPrice(min: number, max: number): number {
  return Math.max(min, Math.min(max, value));
 }

-/**
- * 日期生成器
- */
 export const date: GeneratorDefinition = {
  id: 'date',
  name: '日期',
@@ -248,9 +212,6 @@ export const date: GeneratorDefinition = {
  },
 };

-/**
- * 状态生成器
- */
 export const status: GeneratorDefinition = {
  id: 'status',
  name: '状态',
@@ -303,9 +264,6 @@ export const status: GeneratorDefinition = {
  },
 };

-/**
- * 数量生成器
- */
 export const quantity: GeneratorDefinition = {
  id: 'quantity',
  name: '数量',
@@ -352,9 +310,6 @@ export const quantity: GeneratorDefinition = {
  },
 };

-/**
- * 泊松分布随机数
- */
 function poissonRandom(lambda: number): number {
  const L = Math.exp(-lambda);
  let k = 0;
@@ -366,9 +321,6 @@ function poissonRandom(lambda: number): number {
  return k - 1;
 }

-/**
- * 评分生成器
- */
 export const rating: GeneratorDefinition = {
  id: 'rating',
  name: '评分',
@@ -423,9 +375,6 @@ export const rating: GeneratorDefinition = {
  },
 };

-/**
- * 偏向高分的随机数（模拟真实评分分布）
- */
 function skewedRandom(min: number, max: number): number {
  // 使用 Beta 分布模拟评分偏向
  const alpha = 3;
@@ -434,13 +383,10 @@ 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);
 }

-/**
- * 折扣生成器
- */
 export const discount: GeneratorDefinition = {
  id: 'discount',
  name: '折扣',
@@ -492,9 +438,6 @@ export const discount: GeneratorDefinition = {
  },
 };

-/**
- * 生成心理折扣（如 5%, 10%, 20%, 30%）
- */
 function generatePsychologicalDiscount(min: number, max: number): number {
  const psychologicalDiscounts = [5, 10, 15, 20, 25, 30, 40, 50, 60, 70, 80];
  const validDiscounts = psychologicalDiscounts.filter((d) => d >= min && d <= max);
@@ -504,9 +447,6 @@ function generatePsychologicalDiscount(min: number, max: number): number {
  return randomInt(min, max);
 }

-/**
- * 库存生成器
- */
 export const stock: GeneratorDefinition = {
  id: 'stock',
  name: '库存',
@@ -1,17 +1,9 @@
-/**
- * 生成器库索引
- * 导出所有生成器和分类配置
- */
-
 import type { GeneratorDefinition, GeneratorCategory } from '@/types/testDataGenerator';
 import { personalGenerators } from './personal';
 import { businessGenerators } from './business';
 import { technicalGenerators } from './technical';
 import { basicGenerators } from './basic';

-/**
- * 生成器分类配置
- */
 export const generatorCategories: GeneratorCategory[] = [
  { id: 'personal', name: '个人信息', icon: 'User' },
  { id: 'business', name: '业务数据', icon: 'Briefcase' },
@@ -19,9 +11,6 @@ export const generatorCategories: GeneratorCategory[] = [
  { id: 'basic', name: '基础类型', icon: 'Hash' },
 ];

-/**
- * 所有生成器列表
- */
 export const allGenerators: GeneratorDefinition[] = [
  ...personalGenerators,
  ...businessGenerators,
@@ -29,23 +18,14 @@ export const allGenerators: GeneratorDefinition[] = [
  ...basicGenerators,
 ];

-/**
- * 根据 ID 获取生成器
- */
 export function getGeneratorById(id: string): GeneratorDefinition | undefined {
  return allGenerators.find((g) => g.id === id);
 }

-/**
- * 根据分类 ID 获取生成器列表
- */
 export function getGeneratorsByCategory(categoryId: string): GeneratorDefinition[] {
  return allGenerators.filter((g) => g.categoryId === categoryId);
 }

-/**
- * 搜索生成器
- */
 export function searchGenerators(query: string): GeneratorDefinition[] {
  const lowerQuery = query.toLowerCase();
  return allGenerators.filter(
@@ -1,11 +1,6 @@
-/**
- * 个人信息生成器
- * 包含：中文姓名、邮箱、手机号、身份证号、中文地址、年龄
- */
-
 import type { GeneratorDefinition } from '@/types/testDataGenerator';
+import { randomInt, randomPick } from './random';

-// 中文姓氏
 const SURNAMES = [
  '王',
  '李',
@@ -59,7 +54,6 @@ const SURNAMES = [
  '阎',
 ];

-// 中文名字常用字
 const NAME_CHARS = [
  '伟',
  '芳',
@@ -113,10 +107,8 @@ const NAME_CHARS = [
  '慧',
 ];

-// 邮箱域名
 const EMAIL_DOMAINS = ['qq.com', '163.com', '126.com', 'gmail.com', 'outlook.com', 'hotmail.com'];

-// 省份
 const PROVINCES = [
  '北京市',
  '天津市',
@@ -152,7 +144,6 @@ const PROVINCES = [
  '新疆维吾尔自治区',
 ];

-// 城市
 const CITIES: Record<string, string[]> = {
  北京市: ['东城区', '西城区', '朝阳区', '海淀区'],
  上海市: ['黄浦区', '徐汇区', '长宁区', '静安区'],
@@ -162,23 +153,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)];
-}
-
-/**
- * 中文姓名生成器
- */
 export const chineseName: GeneratorDefinition = {
  id: 'chineseName',
  name: '中文姓名',
@@ -192,9 +166,6 @@ export const chineseName: GeneratorDefinition = {
  },
 };

-/**
- * 邮箱生成器
- */
 export const email: GeneratorDefinition = {
  id: 'email',
  name: '邮箱',
@@ -221,9 +192,6 @@ export const email: GeneratorDefinition = {
  },
 };

-/**
- * 手机号生成器
- */
 export const chinesePhone: GeneratorDefinition = {
  id: 'chinesePhone',
  name: '手机号',
@@ -254,9 +222,6 @@ export const chinesePhone: GeneratorDefinition = {
  },
 };

-/**
- * 身份证号生成器
- */
 export const idCard: GeneratorDefinition = {
  id: 'idCard',
  name: '身份证号',
@@ -281,20 +246,12 @@ export const idCard: GeneratorDefinition = {
  generate: (params) => {
    const regions = ['110101', '310101', '440103', '440305', '510104', '330102'];
    const region = params.region === 'random' ? randomPick(regions) : (params.region as string);
-
-    // 出生日期 1960-2005年
    const year = randomInt(1960, 2005);
    const month = String(randomInt(1, 12)).padStart(2, '0');
    const day = String(randomInt(1, 28)).padStart(2, '0');
    const birthday = `${year}${month}${day}`;
-
-    // 顺序码
    const sequence = String(randomInt(1, 999)).padStart(3, '0');
-
-    // 前17位
    const prefix17 = region + birthday + sequence;
-
-    // 校验码
    const weights = [7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2];
    const checkCodes = ['1', '0', 'X', '9', '8', '7', '6', '5', '4', '3', '2'];
    let sum = 0;
@@ -330,9 +287,6 @@ export const idCard: GeneratorDefinition = {
  },
 };

-/**
- * 中文地址生成器
- */
 export const chineseAddress: GeneratorDefinition = {
  id: 'chineseAddress',
  name: '中文地址',
@@ -361,9 +315,6 @@ export const chineseAddress: GeneratorDefinition = {
  },
 };

-/**
- * 年龄生成器
- */
 export const age: GeneratorDefinition = {
  id: 'age',
  name: '年龄',
@@ -415,9 +366,6 @@ export const age: GeneratorDefinition = {
  },
 };

-/**
- * 正态分布随机数
- */
 function normalRandom(min: number, max: number): number {
  const mean = (min + max) / 2;
  const stdDev = (max - min) / 6;
@@ -430,9 +378,6 @@ function normalRandom(min: number, max: number): number {
  return Math.max(min, Math.min(max, value));
 }

-/**
- * 人口统计分布随机数（模拟真实年龄分布）
- */
 function demographicRandom(): number {
  const ageGroups = [
    { min: 0, max: 14, weight: 0.18 },
@@ -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)];
+}
@@ -1,27 +1,6 @@
-/**
- * 技术数据生成器
- * 包含：UUID、IPv4、URL
- */
-
 import type { GeneratorDefinition } from '@/types/testDataGenerator';
+import { randomInt, randomPick } from './random';

-/**
- * 生成随机整数
- */
-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)];
-}
-
-/**
- * UUID 生成器
- */
 export const uuid: GeneratorDefinition = {
  id: 'uuid',
  name: 'UUID',
@@ -78,9 +57,6 @@ export const uuid: GeneratorDefinition = {
  },
 };

-/**
- * 生成 UUID v4
- */
 function generateUUIDv4(): string {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
    const r = (Math.random() * 16) | 0;
@@ -89,9 +65,6 @@ function generateUUIDv4(): string {
  });
 }

-/**
- * 生成 UUID v1（简化版本，模拟时间戳）
- */
 function generateUUIDv1(): string {
  const now = Date.now();
  const timeLow = (now & 0xffffffff).toString(16).padStart(8, '0');
@@ -105,9 +78,6 @@ function generateUUIDv1(): string {
  return `${timeLow}-${timeMid}-${timeHi.toString(16)}-${clockSeq.toString(16)}-${node}`;
 }

-/**
- * IPv4 生成器
- */
 export const ipv4: GeneratorDefinition = {
  id: 'ipv4',
  name: 'IPv4',
@@ -142,16 +112,10 @@ export const ipv4: GeneratorDefinition = {
  },
 };

-/**
- * 生成完全随机 IPv4
- */
 function generateRandomIPv4(): string {
  return Array.from({ length: 4 }, () => randomInt(0, 255)).join('.');
 }

-/**
- * 生成内网 IPv4
- */
 function generatePrivateIPv4(): string {
  const ranges = [
    { prefix: '10', second: () => randomInt(0, 255) },
@@ -166,9 +130,6 @@ function generatePrivateIPv4(): string {
  return `${range.prefix}.${range.second()}.${randomInt(1, 254)}.${randomInt(1, 254)}`;
 }

-/**
- * 生成公网 IPv4
- */
 function generatePublicIPv4(): string {
  let first: number;
  do {
@@ -178,9 +139,6 @@ function generatePublicIPv4(): string {
  return `${first}.${randomInt(0, 255)}.${randomInt(0, 255)}.${randomInt(1, 254)}`;
 }

-/**
- * URL 生成器
- */
 export const url: GeneratorDefinition = {
  id: 'url',
  name: 'URL',
@@ -250,8 +208,6 @@ export const url: GeneratorDefinition = {
        path = `/${randomPick(['about', 'contact', 'products', 'services', 'blog'])}`;
      }
    }
-
-    // 添加查询参数
    let query = '';
    if (Math.random() > 0.5) {
      const params = new URLSearchParams();
@@ -1,6 +1,5 @@
 import { type ClassValue, clsx } from 'clsx';
-import { twMerge } from 'tailwind-merge';

 export function cn(...inputs: ClassValue[]) {
-  return twMerge(clsx(inputs));
+  return clsx(inputs);
 }
@@ -2,15 +2,6 @@ import { describe, expect, it, vi } from 'vitest';
 import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
 import Base64ConverterPage from '../index';

-// Mock getEntryPointType
-vi.mock('@/config/features', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('@/config/features')>();
-  return {
-    ...actual,
-    getEntryPointType: () => 'sidepanel',
-  };
-});
-
 // Mock 子组件
 vi.mock('../components/TextMode', () => ({
  default: ({ onSwitchToImageMode }: { onSwitchToImageMode?: () => void }) => (
@@ -22,7 +13,9 @@ vi.mock('../components/TextMode', () => ({
 }));

 vi.mock('../components/Base64ConverterSection', () => ({
-  default: ({ mode }: { mode: string }) => <div data-testid={`${mode}-mode`}>{mode}</div>,
+  default: ({ mode }: { mode: 'file' | 'image' }) => (
+    <div data-testid={`${mode}-mode`}>{mode.toUpperCase()} Mode</div>
+  ),
 }));

 const waitForStorageInit = () =>
@@ -40,19 +40,16 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
    decodedFileName,
    setCustomFileName,
    resetAll,
-    safeFileSelect,
+    handleFileSelect,
+    maxFileSizeStr,
  } = useBase64Converter({ mode });

  const handleDirectionChange = (next: Base64ConvertDirection) => {
-    if (!next || next === direction) return;
+    if (next === direction) return;
    resetAll();
    setDirection(next);
  };

-  const handleDownload = () => {
-    if (decoded) downloadBlob(decoded.blob, decodedFileName);
-  };
-
  return (
    <div className="w-full flex flex-col space-y-4 px-2">
      <div className="flex h-11 items-center px-1.5 bg-secondary/40 rounded-xl border border-border/60 w-fit">
@@ -79,7 +76,7 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
              e.preventDefault();
              setIsDragging(false);
              const file = e.dataTransfer.files[0];
-              if (file) safeFileSelect(file);
+              if (file) void handleFileSelect(file);
            }}
            onClick={() => fileInputRef.current?.click()}
            className={cn(
@@ -98,7 +95,7 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
              hidden
              onChange={(e) => {
                const file = e.target.files?.[0];
-                if (file) safeFileSelect(file);
+                if (file) void handleFileSelect(file);
              }}
            />
            {isLoading ? (
@@ -114,7 +111,7 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
                    />
                  </div>
                )}
-                <Upload className={cn('w-8 h-8 text-primary')} />
+                <Upload className="w-8 h-8 text-primary" />
                <span className="text-sm font-bold text-foreground/90 max-w-[280px] truncate">
                  {info.name}
                </span>
@@ -122,7 +119,7 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
                  {formatBytes(info.size)} · {info.type}
                </span>
                <span className="text-[11px] font-medium text-primary/80 mt-1">
-                  {'点击或拖拽以替换文件'}
+                  点击或拖拽以替换文件
                </span>
              </div>
            ) : (
@@ -136,11 +133,11 @@ 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">
-                    {'支持 PNG、JPG、WEBP、GIF、BMP、SVG 等格式'}
+                    支持 PNG、JPG、WEBP、GIF、BMP、SVG 等格式
                  </span>
                )}
              </div>
@@ -157,17 +154,17 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
            <div className="p-4 rounded-2xl bg-card border border-border shadow-sm flex flex-col space-y-3">
              <div className="flex justify-between items-center select-none">
                <span className="text-[10px] font-bold uppercase tracking-wider text-muted-foreground/90">
-                  {'Base64 编码结果'}
+                  Base64 编码结果
                </span>
                <div className="flex gap-2">
                  <CopyButton
                    text={result.rawBase64}
-                    tooltip={'复制纯 Base64'}
+                    tooltip="复制纯 Base64"
                    className="h-6 px-2 rounded-md border text-[10px] font-bold"
                  />
                  <CopyButton
                    text={result.output}
-                    tooltip={'复制 Data URI'}
+                    tooltip="复制 Data URI"
                    className="h-6 px-2 rounded-md border text-[10px] font-bold"
                  />
                </div>
@@ -185,14 +182,14 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
              <div className="flex items-center justify-between font-mono text-[10px] text-muted-foreground/70 select-none pt-1">
                <div className="flex gap-4 items-center 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>
@@ -205,7 +202,7 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
                  className="h-7 rounded-md text-muted-foreground hover:text-destructive text-[11px] gap-1 px-2"
                >
                  <Trash2 className="w-3.5 h-3.5" />
-                  {'清空'}
+                  清空
                </Button>
              </div>
            </div>
@@ -214,7 +211,7 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
      ) : (
        <div className="flex flex-col space-y-4">
          <TextInputArea
-            placeholder={'输入需要解码的 Base64 或 data URI...'}
+            placeholder="输入需要解码的 Base64 或 data URI..."
            value={decodeInput}
            onChange={setDecodeInput}
            externalError={decodeError || undefined}
@@ -230,7 +227,7 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
              blobSize={decoded.blob.size}
              fileName={decodedFileName}
              onFileNameChange={setCustomFileName}
-              onDownload={handleDownload}
+              onDownload={() => downloadBlob(decoded.blob, decodedFileName)}
            >
              {mode === 'image' && (
                <div className="relative p-1.5 border border-border bg-background dark:bg-muted/10 rounded-xl max-w-[220px] mb-3 overflow-hidden shadow-sm">
@@ -1,12 +1,3 @@
-/**
- * DecodeResultPaper
- *
- * FileMode 与 ImageMode 通用的 decode 结果展示组件。
- * 提取了二者 decode 输出区完全一致的结构：
- *   标题 → 可选预览（children）→ 文件信息 → 文件名输入 → 下载按钮
- *
- * FileMode 直接使用，ImageMode 通过 children 传入图片预览。
- */
 import { Download } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
@@ -14,19 +5,12 @@ import { Label } from '@/components/ui/label';
 import { formatBytes } from '@/utils/format';

 interface DecodeResultPaperProps {
-  /** 标题文案，由调用方传入 i18n key 对应的值（如 decodedFileOutput / decodedImageOutput） */
  title: string;
-  /** 解码后推断的 MIME 类型 */
  mimeType: string;
-  /** 解码后 Blob 的大小（字节） */
  blobSize: number;
-  /** 当前文件名 */
  fileName: string;
-  /** 文件名变更回调 */
  onFileNameChange: (name: string) => void;
-  /** 下载按钮点击回调 */
  onDownload: () => void;
-  /** 可选的预览内容，ImageMode 用于渲染图片预览 */
  children?: React.ReactNode;
 }

@@ -41,31 +25,20 @@ export default function DecodeResultPaper({
 }: DecodeResultPaperProps) {
  return (
    <div className="p-4 rounded-xl bg-primary/10 border border-primary/30">
-      {/* 标题 */}
      <span className="block mb-2 text-xs font-bold text-muted-foreground">{title}</span>

-      {/* 可选预览内容（ImageMode 的图片） */}
      {children}

-      {/* 文件信息 */}
      <div className="flex gap-4 mb-3">
-        <span className="text-xs text-muted-foreground">
-          {'推断的 MIME 类型'}: {mimeType}
-        </span>
-        <span className="text-xs text-muted-foreground">
-          {'解码大小'}: {formatBytes(blobSize)}
-        </span>
+        <span className="text-xs text-muted-foreground">推断的 MIME 类型: {mimeType}</span>
+        <span className="text-xs text-muted-foreground">解码大小: {formatBytes(blobSize)}</span>
      </div>

-      {/* 文件名输入 */}
      <div className="mb-3">
-        <Label className="block text-xs font-medium text-muted-foreground mb-1">
-          {'解码后文件名'}
-        </Label>
+        <Label className="block text-xs font-medium text-muted-foreground mb-1">解码后文件名</Label>
        <Input value={fileName} onChange={(e) => onFileNameChange(e.target.value)} />
      </div>

-      {/* 下载按钮 */}
      <Button
        variant="default"
        onClick={onDownload}
@@ -73,7 +46,7 @@ export default function DecodeResultPaper({
        className="w-full rounded-lg font-bold"
      >
        <Download className="mr-2 h-4 w-4" />
-        {'下载'}
+        下载
      </Button>
    </div>
  );
@@ -8,7 +8,7 @@ interface TextModeProps {
  onSwitchToImageMode?: () => void;
 }

-export default function TextMode({ onSwitchToImageMode }: TextModeProps = {}) {
+export default function TextMode({ onSwitchToImageMode }: TextModeProps) {
  const {
    input,
    setInput,
@@ -93,16 +93,7 @@ export function useBase64Converter({ mode }: UseBase64ConverterProps) {
    [mode],
  );

-  const safeFileSelect = useCallback(
-    (file: File) => {
-      handleFileSelect(file).catch((err) => {
-        console.error(`Base64 [${mode}] pipeline crash:`, err);
-      });
-    },
-    [handleFileSelect, mode],
-  );
-
-  const decodePipeline = useMemo(() => {
+  const decodeResult = useMemo(() => {
    const cleanedInput = debouncedDecodeInput.replace(/^data:image\/[a-z+]+;base64,/i, '').trim();
    if (!cleanedInput) return { decoded: null, error: null };

@@ -118,8 +109,8 @@ export function useBase64Converter({ mode }: UseBase64ConverterProps) {
    }
  }, [debouncedDecodeInput]);

-  const decoded = decodePipeline.decoded;
-  const decodeError = decodePipeline.error;
+  const decoded = decodeResult.decoded;
+  const decodeError = decodeResult.error;

  const decodedFileName = useMemo(() => {
    if (customFileName) return customFileName;
@@ -144,7 +135,7 @@ export function useBase64Converter({ mode }: UseBase64ConverterProps) {
    decodedFileName,
    setCustomFileName,
    resetAll,
-    safeFileSelect,
+    handleFileSelect,
    maxFileSizeStr,
  };
 }
@@ -4,7 +4,7 @@ import { useContextMenuData } from '@/utils/useContextMenuData';

 const IMAGE_DATA_URI_PATTERN = /^\s*data:image\//i;

-const ERROR_MESSAGE_TO_I18N: Record<string, string> = {
+const ERROR_MESSAGES: Record<string, string> = {
  'Invalid Base64 string': '无效的 Base64 字符串',
  'Input appears to be binary data (e.g. an image). Please use the Image tab instead.':
    '检测到二进制数据（如图像），请使用图像选项卡',
@@ -30,7 +30,7 @@ export function useTextMode() {

  useContextMenuData({ featureKey: 'base64Converter', onData: handleContextMenuData });

-  const conversionPipeline = useMemo(() => {
+  const conversion = useMemo(() => {
    const trimmed = debouncedInput.trim();
    if (!trimmed) return { output: '', error: null };

@@ -38,31 +38,26 @@ export function useTextMode() {
      if (direction === 'encode') {
        const result = textToBase64(debouncedInput);
        return { output: result.output, error: null };
-      } else {
-        const decoded = base64ToText(trimmed);
-        return { output: decoded, error: null };
      }
+      const decoded = base64ToText(trimmed);
+      return { output: decoded, error: null };
    } catch (e) {
      const message = e instanceof Error ? e.message : '';
-      const i18nKey = ERROR_MESSAGE_TO_I18N[message];
      return {
        output: '',
-        error: i18nKey || message || '转换失败',
+        error: ERROR_MESSAGES[message] || message || '转换失败',
      };
    }
  }, [debouncedInput, direction]);

-  const output = conversionPipeline.output;
-  const error = conversionPipeline.error;
+  const output = conversion.output;
+  const error = conversion.error;

  const placeholder =
    direction === 'encode' ? '输入需要编码为 Base64 的文本...' : '输入需要解码的 Base64 字符串...';
  const outputLabel = direction === 'encode' ? 'Base64 编码结果' : '解码文本结果';

-  const showImageHint = useMemo(
-    () => direction === 'decode' && IMAGE_DATA_URI_PATTERN.test(input),
-    [direction, input],
-  );
+  const showImageHint = direction === 'decode' && IMAGE_DATA_URI_PATTERN.test(input);

  const handleDirectionChange = (value: 'encode' | 'decode') => {
    if (value === direction) return;
@@ -1,92 +0,0 @@
-import { useRouter } from '@/providers/RouterProvider';
-import { getFeatureByKey } from '@/config/features';
-import type { PageType } from '@/types/storage';
-import { cn } from '@/lib/utils';
-
-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;
-
-  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">
-            {'最近使用'}
-          </h3>
-          <div className="flex flex-wrap gap-2">
-            {recentFeatures.map(({ key, feature }) => {
-              const IconComponent = feature!.icon!;
-              return (
-                <button
-                  key={key}
-                  type="button"
-                  onClick={() => navigateTo(key as PageType)}
-                  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',
-                    'hover:bg-muted/40 hover:border-primary/30',
-                    'transition-colors cursor-pointer',
-                  )}
-                >
-                  <IconComponent className="h-3.5 w-3.5 text-muted-foreground/70" />
-                  {feature!.label}
-                </button>
-              );
-            })}
-          </div>
-        </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.map(({ key, feature }) => {
-            const IconComponent = feature!.icon!;
-            return (
-              <button
-                key={key}
-                type="button"
-                onClick={() => navigateTo(key as PageType)}
-                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',
-                  'hover:bg-muted/40 hover:border-primary/30',
-                  'transition-colors cursor-pointer',
-                )}
-              >
-                <IconComponent
-                  className={cn(
-                    'h-5 w-5 text-muted-foreground/70',
-                    'group-hover:text-foreground',
-                    'transition-colors',
-                  )}
-                />
-                <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}
-                </span>
-              </button>
-            );
-          })}
-        </div>
-      </div>
-    </div>
-  );
-}
@@ -5,7 +5,6 @@ import Index from '../index';
 describe('JsonTools 页面', () => {
  it('应该渲染模式切换按钮', () => {
    render(<Index />);
-    // 基本渲染测试：页面含多个模式切换按钮，应至少渲染一个
    expect(screen.getAllByRole('button').length).toBeGreaterThan(0);
  });
 });
@@ -30,7 +30,7 @@ export default function DiffNavigator({
        )}
        {...props}
      >
-        <span className="text-xs font-semibold text-muted-foreground/90">{'无差异'}</span>
+        <span className="text-xs font-semibold text-muted-foreground/90">无差异</span>
      </div>
    );
  }
@@ -43,11 +43,10 @@ export default function DiffNavigator({
      )}
      {...props}
    >
-      {/* 上一处差异按钮 */}
      <button
        type="button"
        disabled={isFirst}
-        aria-label={'上一个'}
+        aria-label="上一个"
        onClick={onPrev}
        className={cn(
          'p-1 rounded-md text-muted-foreground hover:bg-accent hover:text-foreground',
@@ -63,11 +62,10 @@ export default function DiffNavigator({
        {total}
      </span>

-      {/* 下一处差异按钮 */}
      <button
        type="button"
        disabled={isLast}
-        aria-label={'下一个'}
+        aria-label="下一个"
        onClick={onNext}
        className={cn(
          'p-1 rounded-md text-muted-foreground hover:bg-accent hover:text-foreground',
@@ -23,11 +23,11 @@ export default function DiffResult({
        {...props}
      >
        <div className="flex-1 min-w-0">
-          <SectionLabel text={'原始 JSON'} />
+          <SectionLabel text="原始 JSON" />
          <JsonTree node={result.root} side="left" activePath={activePath} />
        </div>
        <div className="flex-1 min-w-0">
-          <SectionLabel text={'目标 JSON'} />
+          <SectionLabel text="目标 JSON" />
          <JsonTree node={result.root} side="right" activePath={activePath} />
        </div>
      </div>
@@ -133,7 +133,6 @@ const UnifiedView = ({ node, depth, activePath }: UnifiedViewProps) => {
    );
  }

-  // 容器节点整块渲染处理
  if (node.type === 'added') {
    return (
      <UnifiedRow
@@ -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';
@@ -28,12 +28,12 @@ const CONVERT_LABELS: Record<
 };

 interface JsonConvertSectionProps extends React.HTMLAttributes<HTMLDivElement> {
-  translationPrefix: string;
+  mode: string;
  convertFunction: ConvertFunction;
 }

 export default function JsonConvertSection({
-  translationPrefix,
+  mode,
  convertFunction,
  className,
  ...props
@@ -41,10 +41,8 @@ export default function JsonConvertSection({
  const [input, setInput] = useState('');
  const [debouncedInput, setDebouncedInput] = useState('');

-  const pk = translationPrefix;
-  const labels = CONVERT_LABELS[pk] || CONVERT_LABELS.yaml;
+  const labels = CONVERT_LABELS[mode] ?? CONVERT_LABELS.yaml;

-  // Debounce input
  useEffect(() => {
    const handle = setTimeout(() => {
      setDebouncedInput(input);
@@ -56,33 +54,25 @@ export default function JsonConvertSection({
    return validateJson(debouncedInput);
  }, [debouncedInput]);

-  const conversionPipeline = useMemo(() => {
+  const { result, runtimeError } = useMemo((): {
+    result: ConvertResult | null;
+    runtimeError: string | null;
+  } => {
    const trimmed = debouncedInput.trim();
-    if (!trimmed || error) return null;
+    if (!trimmed || error) return { result: null, runtimeError: null };

    try {
-      return convertFunction(debouncedInput);
+      return { result: convertFunction(debouncedInput), runtimeError: null };
    } catch (e) {
-      // 捕获可能从外部转换器（如 YAML.stringify）中抛出的底层异常
      return {
-        isRuntimeError: true,
-        errorMessage: e instanceof Error ? e.message : String(e),
+        result: null,
+        runtimeError: e instanceof Error ? e.message : String(e),
      };
    }
  }, [debouncedInput, error, convertFunction]);

-  const runtimeError =
-    conversionPipeline && 'isRuntimeError' in conversionPipeline
-      ? conversionPipeline.errorMessage
-      : null;
-  const result =
-    conversionPipeline && !('isRuntimeError' in conversionPipeline)
-      ? (conversionPipeline as ConvertResult)
-      : null;
-
  return (
    <div className={cn('w-full flex flex-col gap-4', className)} {...props}>
-      {/* 输入区 */}
      <TextInputArea
        placeholder={labels.inputPlaceholder}
        value={input}
@@ -95,48 +85,18 @@ export default function JsonConvertSection({
        onClear={() => setInput('')}
      />

-      {/* 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"
-            />
-          </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>
+      {result?.output ? (
+        <JsonResultPanel
+          title={labels.outputLabel}
+          content={result.output}
+          originalBytes={result.originalBytes}
+          outputBytes={result.outputBytes}
+          maxHeight="380px"
+        />
      ) : (
-        <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">
-            {error ? '请修正上方 JSON 的语法错误以开启实时流式格式化' : labels.emptyHint}
-          </p>
-        </div>
+        <EmptyPlaceholder>
+          {error ? '请修正上方 JSON 的语法错误以开启实时流式格式化' : labels.emptyHint}
+        </EmptyPlaceholder>
      )}
    </div>
  );
@@ -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';

@@ -18,7 +18,6 @@ export default function JsonFormatSection() {
  const [indentSize, setIndentSize] = useState<number>(2);
  const [sortKeys, setSortKeys] = useState(false);

-  // Debounce input
  useEffect(() => {
    const handle = setTimeout(() => {
      setDebouncedInput(input);
@@ -30,40 +29,31 @@ export default function JsonFormatSection() {
    return validateJson(debouncedInput);
  }, [debouncedInput]);

-  // Real-time formatting pipeline
-  const formattedPipeline = useMemo(() => {
+  const { result, runtimeError } = useMemo((): {
+    result: JsonFormatResult | null;
+    runtimeError: string | null;
+  } => {
    const trimmed = debouncedInput.trim();
-    if (!trimmed || error) return null;
+    if (!trimmed || error) return { result: null, runtimeError: null };

    try {
      const options: JsonFormatOptions = { indentSize, sortKeys };
-      return formatJson(debouncedInput, options);
+      return { result: formatJson(debouncedInput, options), runtimeError: null };
    } catch (e) {
      return {
-        isRuntimeError: true,
-        errorMessage: e instanceof SyntaxError ? e.message : String(e),
+        result: null,
+        runtimeError: e instanceof SyntaxError ? e.message : String(e),
      };
    }
  }, [debouncedInput, error, indentSize, sortKeys]);

-  const runtimeError =
-    formattedPipeline && 'isRuntimeError' in formattedPipeline
-      ? formattedPipeline.errorMessage
-      : null;
-  const result =
-    formattedPipeline && !('isRuntimeError' in formattedPipeline)
-      ? (formattedPipeline as JsonFormatResult)
-      : null;
-
  return (
    <div className="w-full flex flex-col gap-4">
-      {/* 工具控制栏 */}
      <div className="flex h-10 items-center justify-between px-1.5 bg-secondary/40 rounded-xl border border-border/60">
        <div className="flex gap-4 items-center w-full">
-          {/* 缩进配置区 */}
          <div className="flex gap-2 items-center shrink-0 select-none">
            <span className="text-[10px] font-bold text-muted-foreground/90 uppercase tracking-wider">
-              {'缩进'}
+              缩进
            </span>
            <SwitchButtonGroup
              value={indentSize}
@@ -75,7 +65,6 @@ export default function JsonFormatSection() {

          <div className="h-4 w-px bg-border/60" />

-          {/* 键名排序区 */}
          <div
            onClick={() => setSortKeys(!sortKeys)}
            className="flex items-center gap-2 cursor-pointer select-none group py-1"
@@ -91,15 +80,14 @@ export default function JsonFormatSection() {
              htmlFor="sort-keys-checkbox"
              className="text-xs font-bold text-foreground/80 cursor-pointer tracking-tight group-hover:text-foreground"
            >
-              {'键名排序'}
+              键名排序
            </Label>
          </div>
        </div>
      </div>

-      {/* 满血版输入终端 */}
      <TextInputArea
-        placeholder={'输入需要格式化的 JSON...'}
+        placeholder="输入需要格式化的 JSON..."
        value={input}
        onChange={setInput}
        externalError={error || runtimeError || undefined}
@@ -110,50 +98,17 @@ export default function JsonFormatSection() {
        onClear={() => setInput('')}
      />

-      {/* 格式化结果流面板展示 */}
-      {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"
-            />
-          </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>
+      {result?.formatted ? (
+        <JsonResultPanel
+          title="格式化结果"
+          content={result.formatted}
+          originalBytes={result.originalBytes}
+          outputBytes={result.formattedBytes}
+        />
      ) : (
-        /* 空状态指示引导区 */
-        <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">
-            {error ? '请修正上方 JSON 的语法错误以开启实时流式格式化' : '输入 JSON 后点击格式化'}
-          </p>
-        </div>
+        <EmptyPlaceholder>
+          {error ? '请修正上方 JSON 的语法错误以开启实时流式格式化' : '输入 JSON 后点击格式化'}
+        </EmptyPlaceholder>
      )}
    </div>
  );
@@ -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>
+  );
+}
@@ -1,5 +1,5 @@
 import React, { useEffect, useMemo, useRef, useState } from 'react';
-import { ChevronDown, ChevronRight } from 'lucide-react'; // 用正统的矢量箭头平替原生的字符 '▾' '▸'
+import { ChevronDown, ChevronRight } from 'lucide-react';
 import type { DiffNode, DiffType } from '../types';
 import { cn } from '@/lib/utils';

@@ -82,14 +82,12 @@ const NodeRow = React.memo(
          ? false
          : onActivePath || depth < defaultExpandDepth;

-    // 当激活路径精准定位到本行时，平滑滚动至容器中心
    useEffect(() => {
      if (activePath === node.path) {
        rowRef.current?.scrollIntoView({ behavior: 'smooth', block: 'center' });
      }
    }, [activePath, node.path]);

-    // 占位空行分支：必须加 h-[22px] 锁定绝对等高，防止两侧文本高度塌陷发生高低错位
    if (!shouldRenderOnSide(node.type, side)) {
      return (
        <div
@@ -124,7 +122,6 @@ const NodeRow = React.memo(

      return (
        <div ref={rowRef} className="w-full flex flex-col">
-          {/* 大容器开端行 */}
          <div
            onClick={() => setOverride(expanded ? 'closed' : 'open')}
            className={cn(
@@ -135,7 +132,6 @@ const NodeRow = React.memo(
            )}
            style={indentStyle}
          >
-            {/* 折叠小箭头：升级为精巧的 Lucide SVG 矢量微动效 */}
            <span className="w-3.5 h-3.5 flex items-center justify-center text-muted-foreground/80 shrink-0">
              {expanded ? (
                <ChevronDown className="h-3 w-3" />
@@ -164,7 +160,6 @@ const NodeRow = React.memo(
            )}
          </div>

-          {/* 容器子节点递归区 */}
          {expanded && (
            <div className={indentClass}>
              {node.children.map((child, idx) => (
@@ -181,7 +176,6 @@ const NodeRow = React.memo(
            </div>
          )}

-          {/* 大容器收尾行 */}
          {expanded && (
            <div
              className="text-muted-foreground/80 font-mono text-xs py-0.5 h-[22px] leading-relaxed"
@@ -195,7 +189,6 @@ const NodeRow = React.memo(
      );
    }

-    // 叶子数据行分支
    return (
      <div
        ref={rowRef}
@@ -207,7 +200,7 @@ const NodeRow = React.memo(
        )}
        style={indentStyle}
      >
-        <span className="w-3.5 shrink-0" /> {/* 与上方的折叠键轴线严格对齐 */}
+        <span className="w-3.5 shrink-0" />
        {!isRoot && (
          <span className="text-foreground/90 font-bold tracking-tight">{node.key}:</span>
        )}
@@ -231,7 +224,6 @@ export default function JsonTree({
  ...props
 }: JsonTreeProps) {
  return (
-    /* 最外层承载器：统一收拢至标准的 bg-card 与等宽 tabular-nums 控制轴 */
    <div
      className={cn(
        'rounded-xl border border-border bg-card text-card-foreground font-mono text-xs shadow-sm overflow-x-auto min-h-[200px] max-h-[520px] overflow-y-auto p-2.5 tabular-nums select-text',
@@ -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';
@@ -65,16 +66,16 @@ export default function Index() {

          <div className="flex flex-col md:flex-row gap-4 w-full items-stretch">
            <JsonDiffInput
-              label={'原始 JSON'}
-              placeholder={'输入原始 JSON...'}
+              label="原始 JSON"
+              placeholder="输入原始 JSON..."
              value={leftInput}
              onChange={setLeftInput}
              error={leftError}
              minRows={9}
            />
            <JsonDiffInput
-              label={'目标 JSON'}
-              placeholder={'输入目标 JSON...'}
+              label="目标 JSON"
+              placeholder="输入目标 JSON..."
              value={rightInput}
              onChange={setRightInput}
              error={rightError}
@@ -95,23 +96,21 @@ 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">
-                {leftError || rightError
-                  ? '请修正上方 JSON 的语法错误以开启实时流式比对'
-                  : '输入两侧 JSON 后点击比较'}
-              </p>
-            </div>
+            <EmptyPlaceholder className="min-h-[140px]" messageClassName="max-w-[260px]">
+              {leftError || rightError
+                ? '请修正上方 JSON 的语法错误以开启实时流式比对'
+                : '输入两侧 JSON 后点击比较'}
+            </EmptyPlaceholder>
          )}
        </div>
      ) : pageMode === 'format' ? (
        <JsonFormatSection />
      ) : pageMode === 'yaml' ? (
-        <JsonConvertSection translationPrefix="yaml" convertFunction={yamlConvert} />
+        <JsonConvertSection mode="yaml" convertFunction={yamlConvert} />
      ) : pageMode === 'toml' ? (
-        <JsonConvertSection translationPrefix="toml" convertFunction={tomlConvert} />
+        <JsonConvertSection mode="toml" convertFunction={tomlConvert} />
      ) : (
-        <JsonConvertSection translationPrefix="minify" convertFunction={minifyConvert} />
+        <JsonConvertSection mode="minify" convertFunction={minifyConvert} />
      )}
    </div>
  );
@@ -11,7 +11,6 @@ import type { ConvertFunction, ViewMode } from './types';
 export interface UseJsonToolsReturn {
  pageMode: JsonToolsPageMode;
  setPageMode: (mode: JsonToolsPageMode) => void;
-  // Diff mode state
  leftInput: string;
  rightInput: string;
  setLeftInput: (val: string) => void;
@@ -26,7 +25,6 @@ export interface UseJsonToolsReturn {
  handlePrev: () => void;
  handleNext: () => void;
  activePath: string | undefined;
-  // Convert functions
  yamlConvert: ConvertFunction;
  tomlConvert: ConvertFunction;
  minifyConvert: ConvertFunction;
@@ -35,13 +33,11 @@ export interface UseJsonToolsReturn {
 export function useJsonTools(): UseJsonToolsReturn {
  const [pageMode, setPageMode] = useStorageState('jsonTools/pageMode', 'diff', isValidPageMode);

-  // Diff inputs
  const [leftInput, setLeftInput] = useState('');
  const [rightInput, setRightInput] = useState('');
  const [debouncedLeft, setDebouncedLeft] = useState('');
  const [debouncedRight, setDebouncedRight] = useState('');

-  // Debounce
  useEffect(() => {
    const handle = setTimeout(() => {
      setDebouncedLeft(leftInput);
@@ -50,7 +46,6 @@ export function useJsonTools(): UseJsonToolsReturn {
    return () => clearTimeout(handle);
  }, [leftInput, rightInput]);

-  // Parse debounced inputs
  const parseState = useMemo(() => {
    const invalidMsg = '无效的 JSON 格式';
    return {
@@ -65,7 +60,6 @@ export function useJsonTools(): UseJsonToolsReturn {
  const [viewMode, setViewMode] = useState<ViewMode>('sideBySide');
  const [currentDiffIndex, setCurrentDiffIndex] = useState(0);

-  // Real-time diff computation
  const diffResult = useMemo(() => {
    const { left, right } = parseState;
    if (left.error || right.error || debouncedLeft.trim() === '' || debouncedRight.trim() === '') {
@@ -88,7 +82,6 @@ export function useJsonTools(): UseJsonToolsReturn {

  const activePath = diffResult && total > 0 ? diffResult.diffPaths[currentDiffIndex] : undefined;

-  // Convert functions
  const yamlConvert: ConvertFunction = useCallback((text: string) => {
    const r = jsonToYaml(text);
    return { output: r.output, originalBytes: r.originalBytes, outputBytes: r.outputBytes };
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
rsgltzyd	43038c5edb	refactor: 更新 RouterProvider 以过滤非法页面并合并配置	2026-07-05 22:20:04 +08:00
rsgltzyd	9aa7a51f0b	refactor: 移除 Dashboard 页面及相关功能，更新路由和组件逻辑 - 移除 Dashboard 相关的组件、特性和测试代码，简化项目结构。 - 更新 PageSkeleton 组件，默认渲染工具页面骨架。 - 修改 RouterContainer 和 RouterProvider 以适应新的默认路由策略，确保用户直接访问 timestamp 页面。 - 更新测试用例，确保在新结构下的功能正常。	2026-07-05 22:02:25 +08:00
rsgltzyd	d21e970f56	feat: 重构 Popup 布局，移除 Dashboard 页面并引入功能导航 - 更新 README.md，添加 Popup 功能导航文档链接。 - 新建 feature-nav-layout.md，详细描述 Popup 布局重构的背景、目标及设计。 - 移除 Dashboard 相关代码，更新 RouterProvider 和 TopBar 以适应新布局。 - 修改默认路由策略，确保新用户直接访问 timestamp 页面。	2026-07-05 21:55:22 +08:00
rsgltzyd	6589ea3858	refactor: 移除侧边栏相关功能和代码	2026-07-05 21:47:35 +08:00
rsgltzyd	6be9b31ca2	docs: 将spec目录移动到docs目录中	2026-07-05 21:34:41 +08:00
rsgltzyd	6975e38f79	refactor: 重构 Tailwind 配置以支持模块化和共享主题 - 更新 components.json，修改 CSS 文件路径为 src/styles/shell.css。 - 移除 tailwind.config.js 中的冗余配置，改为导入 tailwind.shell.config.js。 - 新增 tailwind.pages.config.js 和 tailwind.shared.js，集中管理主题和样式配置。 - 更新多个组件以使用新的样式类和配置，提升代码一致性和可维护性。	2026-06-30 23:15:35 +08:00
rsgltzyd	17a4dbd8a7	refactor: 优化 RouterProvider 组件的数据加载逻辑 - 使用批量获取方法 `getMany` 替代多个单独的 `get` 调用，简化数据加载过程。 - 更新 `loadInitialData` 函数，确保从存储中获取的默认值更为一致。 - 修改测试用例以验证批量获取的功能，确保组件在不同情况下的正确性。	2026-06-30 22:56:31 +08:00
rsgltzyd	27e03ae038	refactor: 移除 RouterContainer 组件中的 isLoaded 状态检查 - 简化 RouterContainer 组件逻辑，直接渲染页面内容，无需等待加载状态。 - 更新测试用例，确保在组件挂载后直接渲染页面结构。	2026-06-30 22:51:38 +08:00
rsgltzyd	c7f4305fc3	refactor: 重构 RouterContainer 组件以支持懒加载页面模块 - 移除不必要的 Suspense 组件，改为使用 LoadedPage 组件进行懒加载。 - 更新特性获取逻辑，使用 getFeatureByKey 函数替代直接查找。 - 新增 featureMeta.ts 文件，集中管理功能配置和相关方法。 - 实现 pageLoaders 以支持按需加载页面模块，提升性能和用户体验。	2026-06-30 22:45:32 +08:00
rsgltzyd	d18ae5d41c	refactor: 移除 twMerge 以简化 cn() 函数实现	2026-06-30 22:00:08 +08:00
rsgltzyd	47e08f80b3	refactor: 统一功能组件结构，简化特性配置	2026-06-30 21:18:28 +08:00
rsgltzyd	ece5c6135e	fix: 更新中文提示信息格式以提升可读性在多个组件中移除模板字符串，直接使用普通字符串格式化中文提示信息，增强了代码的可读性和一致性。	2026-06-30 21:06:39 +08:00
rsgltzyd	d0825c5ec0	refactor: 移除无意义的 cn() 包装对仅含静态类名或单一三元表达式的 className 改用普通字符串，保留有条件合并或 prop 覆盖场景下的 cn() 用法。 Co-authored-by: Cursor <cursoragent@cursor.com>	2026-06-30 21:05:10 +08:00
Cursor Agent	149883565d	docs: 同步测试数据生成器 Worker 任务 ID 与 ruleStorage 写入失败说明 Co-authored-by: LingandRX <LingandRX@users.noreply.github.com>	2026-06-30 20:43:38 +08:00
Cursor Agent	ff3c66531c	fix(测试数据生成器): 修复规则覆盖保存误创建重复规则覆盖同名规则时 handleSave(true) 未传入已有规则 id，save() 走新建分支导致旧规则保留且产生同名重复项，getByName 仍返回旧数据。	2026-06-30 20:43:33 +08:00
Cursor Agent	4084dafc29	fix(测试数据生成器): 修复 Worker 并发生成导致的数据污染 Co-authored-by: LingandRX <LingandRX@users.noreply.github.com>	2026-06-30 20:43:26 +08:00
Cursor Agent	647e3dd308	fix(StorageCleaner): 同一标签页 URL 变更时阻止误清理 handleClean 原先仅校验 tab id，未校验 url。用户在页面内导航后、存储信息刷新完成前确认清理，会按旧页面展示的数据清理新页面存储。	2026-06-30 20:40:57 +08:00
雨霖铃	2967a6f79f	fix: 修复 ruleStorage 写入失败处理与 CopyButton 成功态样式	2026-06-27 17:53:08 +08:00
雨霖铃	92bca1c728	refactor: 更新 Worker 消息类型以支持生成任务 ID	2026-06-27 17:47:58 +08:00
雨霖铃	ce0af7dff3	Merge branch 'main' into develop	2026-06-27 17:42:43 +08:00
雨霖铃	d38bafe237	refactor: 统一中文文案并简化组件结构，提升代码可读性移除 chrome.i18n 后，将各功能页面、布局与工具模块的 UI 文案改为内联中文；删除冗余注释与过度抽象（如 ToolCard、StatCard），精简 props 与状态管理；同步优化 JsonTools、StorageCleaner、Timestamp、TestDataGenerator、Dashboard、 Base64Converter、RightClickRestorer、TextStatistics、TopBar、RouterProvider、 ThemeModeProvider 及生成器库与 utils 工具文件。	2026-06-27 17:26:19 +08:00
cursor[bot]	f3a9838017	docs: 同步 i18n 移除与存储初始化防覆盖说明 (#73 ) - 移除已废弃的 chrome.i18n / _locales 文档引用 - 补充 UI 文案规范（features.tsx + 组件内中文） - 记录 RouterProvider / useStorageState 初始化防覆盖机制 - 更新 syncSnapshot、themeSnapshot、restrictedUrls 工具说明	2026-06-27 10:36:18 +08:00
Cursor Agent	0545910b16	fix: 修复路由初始化竞态、存储状态静默覆盖与存储清理误删	2026-06-26 17:17:17 +08:00
cursor[bot]	1948ba67a7	docs: 同步工程文档与当前架构 (#70 ) * docs(工程文档): 同步当前架构说明 * docs(工程文档): 格式化文档表格	2026-06-26 17:16:10 +08:00
cursor[bot]	4b38133cf8	fix(测试数据生成器): 修复 Worker 取消失效与规则存储静默失败 (#69 ) - 为生成任务引入 generationId，忽略过期 Worker 响应，避免取消后展示错误数据 - Worker 每 100 行让出事件循环，使 cancel 消息能被及时处理 - ruleStorage.setAll 返回写入结果，save/update/delete 在 QuotaExceeded 时返回失败 - 补充 useGenerator 与 ruleStorage 单元测试	2026-06-26 17:07:35 +08:00
cursor[bot]	5ae9cf065f	docs: 同步工程文档与当前架构 (#70 ) * docs(工程文档): 同步当前架构说明 * docs(工程文档): 格式化文档表格	2026-06-26 16:59:53 +08:00
rsgltzyd	1041b3ece1	docs: 更新AGENTS.md文档并清理废弃文件 1. 重构AGENTS.md内容，补充功能列表、项目结构说明 2. 删除CLAUDE.md、src/entrypoints/README.md、src/pages/README.md、.github/copilot-instructions.md等废弃文档	2026-06-26 13:54:14 +08:00
rsgltzyd	edd4cf266c	fix(StorageCleaner): 修复 IndexedDB 清理竞态、部分成功计数与刷新后状态同步	2026-06-25 23:31:44 +08:00
雨霖铃	ebf9f7a153	refactor(StorageCleaner): 移动 isRestrictedUrl 函数到独立模块并更新相关引用 - 将 isRestrictedUrl 函数从 storageCleaner 移动到 restrictedUrls 模块，优化代码结构。 - 更新相关文件以引用新的位置，移除冗余的测试用例。	2026-06-19 21:09:22 +08:00
雨霖铃	c98d09d14c	feat(TopBar): 添加搜索框快捷键提示功能及相关测试 - 新增 getSearchShortcutLabel 函数，根据平台返回搜索框的快捷键提示文案。 - 更新 SearchInput 组件，使用 getSearchShortcutLabel 显示正确的快捷键。 - 新增 constants.test.ts 测试文件，验证 getSearchShortcutLabel 函数在不同操作系统下的行为。 - 新增 features.lazy.test.ts 文件，测试懒加载功能，确保页面模块按需加载。	2026-06-19 21:06:51 +08:00
雨霖铃	bf06b61f10	fix(RouterProvider): 修复初始加载状态逻辑，确保在加载前不覆盖 chrome.storage - 将 isLoaded 的初始状态设置为 false，避免在加载初始数据前错误地覆盖存储。 - 新增测试用例，验证在 localStorage 快照过期时，loadInitialData 完成前不应覆盖 chrome.storage 的行为。	2026-06-19 21:00:27 +08:00
雨霖铃	0f3060dcf3	refactor(代码重复): 抽取共享工具函数与 UI 组件，消除多处重复实现 Co-authored-by: Cursor <cursoragent@cursor.com>	2026-06-19 20:55:39 +08:00
雨霖铃	47d74f999e	refactor(RouterProvider, chromeStorage, useContextMenuData): 更新存储获取逻辑以移除默认值参数 - 在 RouterProvider 和 useContextMenuData 中更新对 storageUtil.get 的调用，移除默认值参数，简化逻辑。 - 修改 chromeStorage 中的 get 方法签名，确保在没有默认值时返回可选类型，并添加相应的单元测试以验证类型推断。	2026-06-19 20:47:43 +08:00
雨霖铃	ed383dd319	refactor(CopyButton.test): 移除冗余测试用例	2026-06-19 20:34:38 +08:00
雨霖铃	e1b3a26a2c	feat(TestDataGenerator): 更新规则编辑提示和警告显示逻辑 - 修改规则编辑时的 toast 提示，确保显示正确的规则名称。 - 更新 ResultPanel 组件，优化警告数量的显示逻辑，确保超过 5 条警告时正确显示剩余警告数量。 - 新增 TestDataGeneratorPage 和 ResultPanel 组件的单元测试，验证功能的正确性。	2026-06-19 20:31:59 +08:00
雨霖铃	e372fc6855	refactor(ImageUploader): 移除预览 URL 相关逻辑并简化粘贴事件处理 - 删除 ImageUploader 组件中的 onPreviewUrlChange 属性及相关逻辑，简化文件处理流程。 - 更新测试用例，确保只调用 onFileChange 方法，移除对预览 URL 的依赖。 - 新增 ParsePanel 组件的测试，确保粘贴功能的正确性和唯一性。	2026-06-19 20:29:19 +08:00
雨霖铃	9d6213e75e	fix(business): 修复 skewedRandom 函数中的数学计算错误 - 更新 skewedRandom 函数中的公式，确保正确计算随机值，提升函数的准确性和可靠性。	2026-06-19 20:27:30 +08:00
雨霖铃	228cadf526	refactor(RightClickRestorer): 用状态配置表简化页面 UI 结构 Co-authored-by: Cursor <cursoragent@cursor.com>	2026-06-19 10:41:22 +08:00
雨霖铃	06b9d29270	feat(Jwt): 重构 JWT 组件，新增常量和结果视图 - 新增 constants.ts 文件，定义 JWT 输入占位符和配置常量，提升代码可读性。 - 删除 JwtSection 组件，重构为 JwtResultView 组件，简化结果展示逻辑。 - 更新 index.tsx，使用 JwtResultView 组件替代原有的 JWT 结果展示方式，优化页面结构。	2026-06-19 10:31:40 +08:00
雨霖铃	0906d1f425	feat(Timestamp): 重构时间戳转换功能，新增 ConverterForm 组件 - 在 Timestamp 页面中引入 ConverterForm 组件，简化输入和转换逻辑。 - 新增常量定义，包括模式选项、单位选项和输入占位符，提升代码可读性。 - 更新 useTimestampConverter 钩子，添加输入占位符支持。 - 引入 ToolCard 组件以统一样式和结构，优化页面布局。	2026-06-19 10:27:01 +08:00
雨霖铃	9c993b6cea	feat(TextStatistics): 引入 StatCard 组件以优化统计信息展示 - 新增 StatCard 组件，简化统计信息的展示逻辑。 - 更新 TextStatistics 页面，使用 StatCard 组件替代原有的统计项渲染方式，提升代码可读性和维护性。	2026-06-19 10:22:49 +08:00
雨霖铃	ca0143f3bd	feat: 添加 EmptyPlaceholder 组件并更新相关页面 - 新增 EmptyPlaceholder 组件，用于统一处理空状态提示，提升用户体验。 - 更新多个页面（JsonTools、Jwt、QrCode、Timestamp）以使用 EmptyPlaceholder 组件，简化空状态的实现。 - 更新 README.md，添加 EmptyPlaceholder 组件的说明。	2026-06-19 10:16:59 +08:00
雨霖铃	3ab7194501	refactor: 统一使用 Button 组件替换原有 button 元素 - 在 CopyButton、SwitchButtonGroup 和 TextInputArea 组件中，将原有的 button 元素替换为统一的 Button 组件，提升代码一致性和可维护性。 - 更新相关样式和属性以适应新组件，确保功能正常。	2026-06-19 10:08:27 +08:00
雨霖铃	d401744739	feat(TopBar): 添加搜索功能组件并优化结构 - 新增 SearchInput、SearchDropdown、SearchResultItem 和 TopBarActions 组件，增强 TopBar 的搜索功能。 - 更新 useTopBar 钩子以支持最近搜索功能，并优化搜索历史管理。 - 修改 TopBar 组件以整合新组件，提升可读性和可维护性。 - 更新 README.md，反映新增组件和功能。	2026-06-19 09:59:15 +08:00
雨霖铃	2c901ab4fd	refactor: 重构 TopBar 组件并更新项目结构 - 删除原有的 TopBar 组件，重构为布局组件并移动至 layout/ 目录。 - 更新相关文档，反映 TopBar 组件的新位置。 - 引入新的 useTopBar 钩子以管理 TopBar 的状态和逻辑。 - 添加 TopBar 组件的单元测试，确保功能正常。	2026-06-19 09:53:29 +08:00
雨霖铃	a8a1e89f8a	refactor: 更新功能键名称并移除 README 文件 - 将功能键 'jsonDiff' 更新为 'jsonTools'，以更准确地反映其功能。 - 删除不再使用的 README.md 文件，清理项目结构。 - 更新相关测试用例以反映功能键名称的变化。	2026-06-19 09:47:08 +08:00
雨霖铃	9097c48b1f	feat(Dashboard): 重构仪表板功能组件和逻辑 - 新增 dashboardFeatures.ts 和 useDashboard.ts 文件，封装仪表板功能的解析和状态管理逻辑。 - 更新 Dashboard 组件，使用 useDashboard 钩子简化可见工具和最近使用工具的处理。 - 添加仪表板功能的单元测试，确保功能正确性。 - 更新 README.md，移除不再使用的 ToolCard 组件说明。	2026-06-19 09:26:30 +08:00
雨霖铃	c69a26b469	refactor: 清理代码注释并优化组件结构 - 在 useQrCode.ts 中移除多余的注释，简化代码逻辑。 - 在 DataPreview.tsx 和 FieldEditor.tsx 中删除不必要的注释，提升可读性。 - 在 format.ts 和 jsonToToml.ts 中更新注释内容，确保准确性。	2026-06-19 01:04:15 +08:00
雨霖铃	cd21d11fa1	refactor: 将 UI 文案改为中文并优化相关逻辑 - 在 background.ts 中将错误信息翻译为中文。 - 在 uiPopover.ts 中移除注释并更新弹出框标题。 - 在 Base64ConverterSection.tsx 中动态显示最大文件大小。 - 在 DecodeResultPaper.tsx 中简化标题文案注释。 - 在 GenerateButton.tsx 中动态显示生成进度和预计剩余时间。 - 在 base64Converter.ts 中将错误信息翻译为中文。	2026-06-19 00:53:56 +08:00
雨霖铃	f0292acbb7	fix(ThemeModeProvider): 修复主题快照同步与首屏闪烁问题抽取 themeSnapshot 工具模块，异步恢复与跨窗同步时写回 snapshot；HTML 内联脚本与 useLayoutEffect 消除 dark 类首帧闪烁；避免 storage 恢复覆盖用户操作及 setState 嵌套更新。 Co-authored-by: Cursor <cursoragent@cursor.com>	2026-06-19 00:45:52 +08:00
雨霖铃	8f9ff27034	fix(RouterProvider): 将 goBack 重命名为 goHome，修复跨窗同步 merge 不一致 API 命名与实际行为（返回 dashboard）对齐；storage.onChanged 同步 visiblePages/pageOrder 时应用 mergeWithDefaults，与初始化逻辑保持一致。 Co-authored-by: Cursor <cursoragent@cursor.com>	2026-06-19 00:38:01 +08:00
雨霖铃	aa63723b80	refactor(AppRoot): 移除 RouterProvider 组件，直接渲染子组件 - 在 AppRoot 组件中移除 RouterProvider，直接将 children 作为子元素渲染，简化组件结构。	2026-06-19 00:36:40 +08:00
LingandRX	a163297de4	develop (#68 ) * docs(AGENTS.md): 添加 Git Commit 必须使用中文描述的规范 * docs: 更新测试数据生成器功能设计文档 * refactor: 删除死代码 * docs: 统一测试数据生成器文档，移除 SQL/TypeScript 导出，修复接口命名不一致 * feat: 实现测试数据生成器功能 * docs: 更新 README 和 AGENTS 文档，补充测试数据生成器模块说明	2026-06-07 00:04:53 +08:00
LingandRX	a5d86a92c2	develop (#67 ) feat: 升级项目 Logo、完善 toast 提示及优化工程化配置 ### Features - logo: 替换全套项目图标，更新 wxt.config.ts 浏览器扩展图标配置。 ### Bug Fixes - ui/toast: 引入 <Toaster> 组件修复 toast 无法显示问题，并调整位置为正下方。 - i18n: 统一将 t() 函数中的 `.` 和 `:` 转换为 `_`，修复国际化文案读取失败问题。 - context-menu: 限制 srcUrl 检查仅在二维码图片菜单项生效，避免误判。 - hooks: 修复 pre-push 钩子，仅对变更文件进行 eslint 检查，并支持无 upstream 时的回退对比。 - components: 修复 CopyButton 动画与组件导入方式，并补齐无障碍属性与测试。 - async: 延迟生成二维码以正确渲染 loading 状态，并适配相关异步测试。 ### Refactor & Cleans - clean: 清理未使用的组件（ToolCard）、Hook（useDebounce）及多个未使用的工具函数导出。 - structure: 统一移动测试文件至 __tests__ 目录，移除不必要的类型导出。 ### Documentation - docs: 在 AGENTS.md 中明确规范 Git Commit 必须使用中文描述。	2026-06-06 01:07:27 +08:00
LingandRX	c992986789	fix(CopyButton): 修复 review 反馈并补充测试 (#66 ) * fix: remove non-functional animation classes from CopyButton * test(CopyButton): 补充单元测试覆盖边界场景 * fix: unify CopyButton imports to named export across all consumers * fix(CopyButton): add aria-label for screen reader accessibility	2026-06-05 21:15:48 +08:00
LingandRX	70b799aa2d	fix: add missing Toaster component to enable toast display (#65 ) The project was calling toast.success/error/warning from sonner in 7 files, but the <Toaster> component was never rendered in the React tree. This meant sonner stored toast data internally but no UI was ever displayed to users. Changes: - Create src/components/ui/sonner.tsx with shadcn/ui-style Toaster wrapper that integrates with ThemeModeProvider for light/dark theme support - Add <Toaster /> to AppRoot.tsx so it works across all entry points (popup, sidepanel, browser-tab) fix: always convert dots to underscores in i18n t() key lookup The t() function only converted dots to underscores when the key contained a colon (namespace:key format). Keys using dot notation like 'messages.copySuccess' were passed directly to chrome.i18n.getMessage() without dot-to-underscore conversion, causing lookups to fail silently and return empty strings - resulting in toast notifications with no text. Now all separators (both ':' and '.') are consistently converted to '_' regardless of format, matching the messages.json key convention. fix: position toast at bottom-center instead of bottom-right	2026-06-05 19:29:21 +08:00
LingandRX	58af2af37b	fix: 右键菜单 srcUrl 误判、pre-push 变更文件检测、generating 状态不可见 (#64 ) * fix: 修复右键菜单 srcUrl 误判、pre-push 全量扫描、generating 状态不可见问题 - contextMenu: srcUrl 检查限定为 qrCode-image 菜单项，避免其他菜单误返回图片 URL - pre-push: eslint 改为只检查变更文件（git diff 过滤），tsc 保留全项目检查 - useQrCode: confirmGenerate 用 setTimeout 延迟生成，让 loading 状态先被 React 渲染 - tests: 生成相关测试改为 async + waitFor 适配异步 confirmGenerate * fix(hooks): pre-push 无 upstream 时回退到 origin/main 对比 * fix(hooks): 用 merge-base 替代 rev-parse 修复 pre-push 变更文件检测	2026-06-05 13:10:44 +08:00