docs(工程文档): 格式化文档表格

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

.github/CODING_STANDARDS.md

@@ -285,8 +285,7 @@ import { useThemeMode } from '@/providers/ThemeModeProvider';
 import { FeatureConfig, FEATURES } from '@/config/features';
 import { storageUtil } from '@/utils/chromeStorage';
 // 5. i18n
-import { useTranslation } from 'react-i18next';
+import { useI18n } from '@/utils/chromeI18n';
-import { normalizeLanguage, SUPPORTED_LANGUAGES } from '@/i18n';
 // 6. 本地组件
 import TextMode from './TextMode';
 import { ZONES } from './constants';
@@ -295,7 +294,7 @@ import SwitchButtonGroup from '@/components/SwitchButtonGroup';
 import { Button } from '@/components/ui/button';
 // 8. 工具函数 / Hook
 import { cn } from '@/lib/utils';
-import { useLazyTranslation } from '@/utils/useLazyTranslation';
+import { useStorageState } from '@/utils/useStorageState';
 // 9. 类型
 import type { PageType, StorageSchema } from '@/types/storage';
 ```
@@ -401,22 +400,22 @@ className={cn(
 
 ## 5. 错误处理
 
-### 5.1 工具函数：结果对象模式
+### 5.1 工具函数：可恢复错误返回可判断结果
 
-工具函数**不抛异常**，返回包含 `hasError` 和 `error` 字段的结果对象：
+可恢复的解析/校验错误应返回可判断的结果，避免工具层直接弹 Toast。确需保留底层异常的函数
+（如 `formatJson` / `minifyJson`）必须在页面 Hook 或 UI 层捕获并转换为用户提示：
 
 ```typescript
-// ✅ 结果对象模式
+// ✅ 可恢复校验返回错误消息，调用方据此展示 UI
-export function markdownToHtml(markdown: string): MarkdownToHtmlResult {
+export function validateJson(text: string): string | null {
+  if (!text.trim()) {
+    return null;
+  }
   try {
-    ...
+    JSON.parse(text.trim());
-    return { html, originalLength, htmlLength, hasError: false };
+    return null;
-  } catch (error) {
+  } catch (e) {
-    return {
+    return e instanceof SyntaxError ? e.message : 'Invalid JSON';
-      html: '', ...
-      hasError: true,
-      error: error instanceof Error ? error.message : 'Markdown 解析失败',
-    };
   }
 }
 ```
@@ -658,7 +657,7 @@ export function useTimestampConverter(): UseTimestampConverterReturn { ... }
 
 ```
 src/utils/useStorageState.ts          — Chrome Storage 状态持久化
-src/utils/useLazyTranslation.ts       — i18n 懒加载
+src/utils/chromeI18n.ts               — chrome.i18n wrapper 与 useI18n
 src/utils/useContextMenuData.ts       — 右键菜单数据
 src/utils/useDebounce.ts              — 防抖
 src/pages/Timestamp/useTimestampConverter.ts    — 页面级 Hook
@@ -671,43 +670,48 @@ src/pages/StorageCleaner/useStorageCleaner.ts  — 页面级 Hook
 
 ### 9.1 翻译键格式
 
-- 命名空间：`common`（默认）、`features`
+- 使用 Chrome 扩展标准的 `chrome.i18n`，通过 `src/utils/chromeI18n.ts` 暴露 `useI18n`
-- 翻译键格式：`namespace:key`（如 `features:timestamp.title`）
+- 翻译 key 存放在 `public/_locales/zh_CN/messages.json`
-- 语言：`zh`（默认）、`en`
+- 直接 key：`t('dashboard_title')` → 查找 `dashboard_title`
+- 命名空间兼容写法：`t('common:buttons.search')` → 查找 `common_buttons_search`
+- 命名空间参数：`useI18n(['common', 'features'])` 会尝试 `common_key`、`features_key`
 
 ### 9.2 翻译文件结构
 
 ```
-i18n/locales/{zh,en}/common.json           — 全局通用翻译
+public/_locales/zh_CN/messages.json        — Chrome 扩展默认语言包
-i18n/locales/{zh,en}/features.json         — 功能模块标题和描述
+wxt.config.ts                              — manifest.default_locale = 'zh_CN'
-i18n/locales/{zh,en}/{功能名}.json         — 各功能独立翻译
 ```
 
 ### 9.3 使用方式
 
 ```typescript
-// ✅ 页面组件 — 使用 useLazyTranslation
+// ✅ 页面组件 / 子组件 — 使用 useI18n
-import { useLazyTranslation } from '@/utils/useLazyTranslation';
+import { useI18n } from '@/utils/chromeI18n';
 
 export default function Index() {
-  const { t } = useLazyTranslation('timestamp');
+  const { t } = useI18n('timestamp');
-  return <h1>{t('timestamp:title')}</h1>;
+  return <h1>{t('timestamp_title')}</h1>;
 }
 
-// ✅ 全局组件 — 使用 useTranslation
+// ✅ 带占位符
-import { useTranslation } from 'react-i18next';
+export function NotFoundMessage() {
-
+  const { t } = useI18n('router');
-export function TopBar() {
+  return <p>{t('router_notFoundDescription', { entryPointType: 'popup' })}</p>;
-  const { t } = useTranslation(['common', 'features']);
-  return <span>{t('common:settings')}</span>;
 }
 ```
 
 ### 9.4 添加新翻译
 
-1. 在 `i18n/locales/{zh,en}/features.json` 添加功能标题和描述
+1. 在 `public/_locales/zh_CN/messages.json` 添加 Chrome 扩展格式的消息：
-2. 创建 `i18n/locales/{zh,en}/{功能名}.json` 添加功能专属翻译
+   ```json
-3. 在 `utils/useLazyTranslation.ts` 的 `localeModules` 中注册新命名空间
+   {
+     "feature_title": { "message": "功能标题" },
+     "feature_description": { "message": "功能描述" }
+   }
+   ```
+2. key 使用下划线分隔，避免点号；`useI18n` 会把 `namespace:key.path` 兼容转换为下划线
+3. `chrome.i18n` 不支持运行时动态切换语言，浏览器语言变化后需要刷新扩展页面
 
 ---
 
@@ -1083,7 +1087,7 @@ export default function Index() {
 4. ✅ 业务逻辑提取到 `useXxx.ts` Hook（index.tsx 不超过 150 行）
 5. ✅ 需要持久化的 UI 状态使用 `useStorageState`
 6. ✅ 常量 ≥3 个时提取到 `constants.ts`
-7. ✅ 在 `i18n/locales/{zh,en}/` 添加翻译
+7. ✅ 在 `public/_locales/zh_CN/messages.json` 添加翻译
 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）                                    |
+| `src/lib/`           | 通用工具函数与生成器库（cn、utils、generators）              |
-| `public/`            | 静态资源                                                     |
+| `public/`            | 静态资源与 Chrome `_locales` 语言包                          |
 
 ---
 

.github/copilot-instructions.md

@@ -1,6 +1,6 @@
 # Copilot 指令
 
-基于 WXT 框架的浏览器扩展项目（React 19 + TypeScript），为开发者和测试人员提供效率工具：时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、Markdown 等。
+基于 WXT 框架的浏览器扩展项目（React 19 + TypeScript），为开发者和测试人员提供效率工具：时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、测试数据生成器等。
 
 ## 核心命令
 
@@ -74,10 +74,10 @@ pages/FeatureName/
 1. 在 `types/storage.d.ts` 的 `PageType` 联合类型中添加新成员
 2. 在 `config/features.tsx` 的 `FEATURES` 数组中添加配置（key、翻译键、图标、三种渲染模式组件）
 3. 在 `pages/` 目录创建页面组件（懒加载）：
-   - `index.tsx` — 使用 `useLazyTranslation` 的 UI 组件
+   - `index.tsx` — 使用 `useI18n` 的 UI 组件
    - `useFeatureName.ts` — 业务逻辑 Hook
    - `constants.ts` — 常量（可选）
-4. 在 `i18n/locales/{zh,en}/features.json` 添加翻译（复杂功能可新建独立 JSON 文件）
+4. 在 `public/_locales/zh_CN/messages.json` 添加 Chrome i18n 翻译
 5. 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
 6. 添加对应的单元测试
 
@@ -102,7 +102,7 @@ pages/FeatureName/
 
 ### 代码分割
 
-`wxt.config.ts` 通过 `manualChunksForHtmlOnly()` 自动分组 vendor 依赖（vendor-react、vendor-i18n、vendor-qr、vendor-dnd），无需手动配置。
+`wxt.config.ts` 通过 `manualChunksForHtmlOnly()` 自动分组 vendor 依赖（vendor-react、vendor-qr、vendor-dnd），无需手动配置。
 
 ### 代码风格
 
@@ -118,8 +118,7 @@ pages/FeatureName/
 - 全局变量：`vitest/globals`（describe、it、expect 等无需导入）
 - Setup 文件：`vitest.setup.ts` 自动 mock 以下内容：
   - `chrome.*` / `browser.*` API（storage、tabs、runtime、cookies 等）
-  - `react-i18next`（返回 key 作为翻译）
+  - `@/utils/chromeI18n`（从 `public/_locales/zh_CN/messages.json` 加载真实翻译）
-  - `@/utils/useLazyTranslation`（返回 `ns:key` 格式）
   - `window.matchMedia`
 - 测试文件命名：`__tests__/*.test.{ts,tsx}` 或 `*.test.{ts,tsx}`
 - 使用 `vi.mock()` 进行模块级 mock；避免重复 mock `vitest.setup.ts` 中已有的内容
@@ -127,12 +126,12 @@ pages/FeatureName/
 
 ### 国际化（i18n）
 
-- 命名空间：`common`（默认）、`features`
+- 使用 Chrome 扩展标准 `chrome.i18n`
-- 翻译键格式：`namespace:key`（如 `features:timestamp.title`）
+- 默认语言目录：`public/_locales/zh_CN/messages.json`
-- 语言：`zh`（默认）、`en`
+- 使用方式：`import { useI18n } from '@/utils/chromeI18n'`
-- 翻译文件：`i18n/locales/{zh,en}/{common,features}.json` + 各功能独立 JSON 文件
+- 翻译键格式：直接 key（如 `timestamp_title`）；兼容 `namespace:key.path` 并转换为下划线
-- 使用 `useLazyTranslation` Hook 加载功能专属翻译
+- 回退策略：缺失翻译返回 key 本身，并在开发模式下记录 warning
-- 回退策略：缺失的翻译键回退到 `zh`，若仍缺失则返回占位格式 `namespace:key`
+- 限制：`chrome.i18n` 跟随浏览器语言，不能在运行时动态切换语言
 
 ### WXT 生成文件
 

AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-WXT 浏览器扩展项目 (React 19 + TypeScript)。提供时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、Markdown、测试数据生成器等测试效率工具。
+WXT 浏览器扩展项目 (React 19 + TypeScript)。提供时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、测试数据生成器等测试效率工具。
 
 ## 核心命令
 
@@ -98,8 +98,9 @@ src/pages/TestDataGenerator/
 
 src/utils/
 ├── ruleStorage.ts               # 规则持久化存储（localStorage）
-├── dataExporter.ts              # 数据导出工具（JSON/CSV 转换、下载、剪贴板）
+└── dataExporter.ts              # 数据导出工具（JSON/CSV 转换、下载、剪贴板）
-└── generators/                  # 内置生成器定义（个人信息、企业、技术、基础类型）
+
+src/lib/generators/              # 内置生成器定义（个人信息、企业、技术、基础类型）
 
 src/workers/
 └── generator.worker.ts          # 数据生成 Web Worker
@@ -132,7 +133,7 @@ src/types/
 - 全局变量: `vitest/globals` (describe, it, expect 等无需导入)
 - Setup 文件: `vitest.setup.ts` 自动 mock:
   - `chrome.*` / `browser.*` API (storage, tabs, runtime, cookies 等)
-  - `@/utils/chromeI18n` (从 `public/_locales/zh/messages.json` 加载真实翻译)
+  - `@/utils/chromeI18n` (从 `public/_locales/zh_CN/messages.json` 加载真实翻译)
   - `window.matchMedia`
 - 测试文件命名: `__tests__/*.test.{ts,tsx}` 或 `*.test.{ts,tsx}`
 - Mock 模式: 使用 `vi.mock()` 进行模块级 mock，避免在测试文件中重复 mock 代码
@@ -142,8 +143,8 @@ src/types/
 
 项目使用 Chrome 扩展标准的 `chrome.i18n` API 进行本地化，通过 `src/utils/chromeI18n.ts` 提供类型安全的 React Hook 包装。
 
-- **翻译文件**: `public/_locales/{zh,en}/messages.json`（Chrome 扩展标准格式）
+- **翻译文件**: `public/_locales/zh_CN/messages.json`（Chrome 扩展标准格式）
-- **默认语言**: `zh`（在 `wxt.config.ts` 的 `manifest.default_locale` 中配置）
+- **默认语言**: `zh_CN`（在 `wxt.config.ts` 的 `manifest.default_locale` 中配置）
 - **使用方式**: `import { useI18n } from '@/utils/chromeI18n'`
 - **翻译键格式**:
   - 直接 key: `t('dashboard_title')` → 查找 `dashboard_title`
@@ -162,7 +163,7 @@ src/types/
    - `index.tsx` — UI 组件，使用 `useI18n` 获取翻译
    - `useFeatureName.ts` — 业务逻辑 Hook
    - `constants.ts` — 常量（可选）
-4. 在 `public/_locales/zh/messages.json`（及 `en/messages.json`）添加翻译
+4. 在 `public/_locales/zh_CN/messages.json` 添加翻译
 5. 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
 6. 添加对应的单元测试
 

README.md

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

docs/test-data-generator/README.md

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

public/README.md

@@ -12,8 +12,24 @@
 | `icon/48.png`  | 48×48 图标（扩展管理页）         |
 | `icon/96.png`  | 96×96 图标                       |
 | `icon/128.png` | 128×128 图标（Chrome Web Store） |
+| `_locales/`    | Chrome 扩展本地化资源            |
+
+## 本地化资源
+
+项目使用 Chrome 扩展标准 `chrome.i18n`，默认语言在 `wxt.config.ts` 中配置为 `zh_CN`。
+
+| 文件/目录                      | 用途                                               |
+| ------------------------------ | -------------------------------------------------- |
+| `_locales/zh_CN/messages.json` | 默认中文语言包，包含功能名、描述、按钮、提示等翻译 |
+
+添加或修改文案时：
+
+- 使用 Chrome 扩展消息格式：`"key": { "message": "文本" }`
+- key 使用下划线分隔，例如 `testDataGenerator_title`
+- 代码中通过 `useI18n` 或 `getMessage` 读取，不要新增 `i18n/locales` 目录
 
 ## 注意事项
 
 - 修改图标后需同步更新 `wxt.config.ts` 中的 manifest 配置
 - 图标格式推荐使用 PNG，确保透明背景
+- 修改 `_locales` 后需确认 `manifest.default_locale` 与语言目录名一致

src/config/README.md

@@ -19,7 +19,7 @@
 - `defaultVisible`：默认是否可见
 - `components`：三种渲染模式的懒加载组件（`popup`、`sidepanel`、`tab`）
 
-## 已注册功能（11 个）
+## 已注册功能（10 个）
 
 | key                  | 图标              | 说明              |
 | -------------------- | ----------------- | ----------------- |
@@ -31,9 +31,8 @@
 | `jwt`                | Key               | JWT 解析工具      |
 | `jsonDiff`           | GitCompareArrows  | JSON 差异比较工具 |
 | `base64Converter`    | ArrowLeftRight    | Base64 转换器     |
-| `markdownToHtml`     | Code              | Markdown 转 HTML  |
-| `htmlToMarkdown`     | File              | HTML 转 Markdown  |
 | `rightClickRestorer` | MousePointerClick | 右键菜单恢复工具  |
+| `testDataGenerator`  | FileSpreadsheet   | 测试数据生成器    |
 
 ## 导出函数
 

src/lib/README.md

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

src/pages/README.md

@@ -113,14 +113,6 @@ Base64 编解码工具，支持文本/文件/图片三种模式。
 | `TextMode.tsx`               | 文本模式              |
 | `Base64ConverterSection.tsx` | 文件/图片通用转换区域 |
 
-### MarkdownToHtml/
-
-Markdown 转 HTML 工具，支持分栏/预览/源码三种视图模式。
-
-### HtmlToMarkdown/
-
-HTML 转 Markdown 工具，支持分栏/预览/Markdown 三种视图模式。
-
 ### RightClickRestorer/
 
 右键菜单恢复工具，解除网站对右键的限制。
@@ -130,11 +122,32 @@ HTML 转 Markdown 工具，支持分栏/预览/Markdown 三种视图模式。
 | `index.tsx`                | 页面 UI       |
 | `useRightClickRestorer.ts` | 业务逻辑 Hook |
 
+### TestDataGenerator/
+
+测试数据生成器，支持可视化字段配置、规则复用、Web Worker 批量生成和 JSON/CSV 导出。
+
+| 文件/目录                    | 用途                                              |
+| ---------------------------- | ------------------------------------------------- |
+| `index.tsx`                  | 主页面，管理字段配置、规则标签页和生成结果        |
+| `hooks/useGenerator.ts`      | Worker 生命周期与消息通信，暴露生成/取消/清理操作 |
+| `components/FieldList.tsx`   | 字段列表、拖拽排序、虚拟滚动和规则保存入口        |
+| `components/FieldEditor.tsx` | 字段名称、生成器、参数、必填/空值率/唯一性配置    |
+| `components/RuleManager.tsx` | 规则搜索、加载、编辑、复制、删除、导入和导出      |
+| `components/ExportPanel.tsx` | 生成结果复制和 JSON/CSV 下载                      |
+
+约束与注意事项：
+
+- 字段数量最多 40 个（`FieldList.MAX_FIELDS`）。
+- 生成数量为 1 ~ 100,000，预设值包含 50、100、1,000、5,000、10,000。
+- 大批量生成通过 `src/workers/generator.worker.ts` 执行，避免阻塞 UI；Worker 每 1,000 条或结束时回传进度。
+- 规则通过 `src/utils/ruleStorage.ts` 存入 `localStorage`，最多保存 20 条规则。
+- 内置生成器位于 `src/lib/generators/`，按个人信息、业务数据、技术数据、基础类型分类。
+
 ## 新增页面
 
 1. 在 `types/storage.d.ts` 添加 `PageType` 联合类型成员
 2. 在 `config/features.tsx` 的 `FEATURES` 数组添加配置
 3. 在 `pages/` 创建页面目录（遵循上述结构）
-4. 在 `i18n/locales/{zh,en}/features.json` 添加翻译
+4. 在 `public/_locales/zh_CN/messages.json` 添加 Chrome i18n 翻译
 5. 如需新权限，更新 `wxt.config.ts`
 6. 添加对应的单元测试

src/pages/TestDataGenerator/hooks/__tests__/useGenerator.test.ts

@@ -1,117 +0,0 @@
-import { act, renderHook, waitFor } from '@testing-library/react';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { useGenerator } from '@/pages/TestDataGenerator/hooks/useGenerator';
-import type { FieldConfig, WorkerResponseMessage } from '@/types/testDataGenerator';
-
-const mockField: FieldConfig = {
-  id: 'field-1',
-  name: 'username',
-  generatorId: 'string',
-  params: {},
-  required: true,
-  nullRate: 0,
-  unique: false,
-};
-
-type WorkerListener = (event: MessageEvent<WorkerResponseMessage>) => void;
-
-class MockWorker {
-  static instances: MockWorker[] = [];
-  onmessage: WorkerListener | null = null;
-  onerror: ((event: ErrorEvent) => void) | null = null;
-  postedMessages: unknown[] = [];
-
-  constructor(_url: URL, _options?: WorkerOptions) {
-    MockWorker.instances.push(this);
-  }
-
-  postMessage(message: unknown) {
-    this.postedMessages.push(message);
-  }
-
-  terminate() {
-    const index = MockWorker.instances.indexOf(this);
-    if (index >= 0) {
-      MockWorker.instances.splice(index, 1);
-    }
-  }
-
-  emit(message: WorkerResponseMessage) {
-    this.onmessage?.({ data: message } as MessageEvent<WorkerResponseMessage>);
-  }
-}
-
-describe('useGenerator', () => {
-  beforeEach(() => {
-    MockWorker.instances = [];
-    vi.stubGlobal('Worker', MockWorker);
-  });
-
-  it('应忽略过期 generationId 的 complete 消息', async () => {
-    const { result } = renderHook(() => useGenerator());
-
-    act(() => {
-      result.current.generate([mockField], 10);
-    });
-
-    const worker = MockWorker.instances[0];
-    expect(worker).toBeDefined();
-
-    act(() => {
-      result.current.cancel();
-    });
-
-    act(() => {
-      result.current.generate([mockField], 5);
-    });
-
-    act(() => {
-      worker.emit({
-        type: 'complete',
-        generationId: 1,
-        payload: {
-          success: true,
-          data: [{ username: 'stale' }],
-          stats: { total: 10, success: 10, failed: 0, duration: 1 },
-        },
-      });
-    });
-
-    expect(result.current.result).toBeNull();
-    expect(result.current.isGenerating).toBe(true);
-
-    act(() => {
-      worker.emit({
-        type: 'complete',
-        generationId: 3,
-        payload: {
-          success: true,
-          data: [{ username: 'fresh' }],
-          stats: { total: 5, success: 5, failed: 0, duration: 1 },
-        },
-      });
-    });
-
-    await waitFor(() => {
-      expect(result.current.isGenerating).toBe(false);
-    });
-    expect(result.current.result?.data?.[0]).toEqual({ username: 'fresh' });
-  });
-
-  it('cancel 后应发送 cancel 消息并使 generationId 失效', () => {
-    const { result } = renderHook(() => useGenerator());
-
-    act(() => {
-      result.current.generate([mockField], 100);
-    });
-
-    const worker = MockWorker.instances[0];
-
-    act(() => {
-      result.current.cancel();
-    });
-
-    expect(result.current.isGenerating).toBe(false);
-    expect(worker.postedMessages).toEqual(expect.arrayContaining([{ type: 'cancel' }]));
-  });
-});

src/pages/TestDataGenerator/hooks/useGenerator.ts

@@ -8,8 +8,7 @@ import type {
   FieldConfig,
   GenerateResult,
   GenerateProgress,
-  WorkerRequestMessage,
+  WorkerMessage,
-  WorkerResponseMessage,
 } from '@/types/testDataGenerator';
 
 export interface UseGeneratorReturn {
@@ -36,7 +35,6 @@ export function useGenerator(): UseGeneratorReturn {
   const [error, setError] = useState<string | null>(null);
 
   const workerRef = useRef<Worker | null>(null);
-  const generationIdRef = useRef(0);
 
   // 清理 Worker
   useEffect(() => {
@@ -60,30 +58,22 @@ export function useGenerator(): UseGeneratorReturn {
       type: 'module',
     });
 
-    worker.onmessage = (e: MessageEvent<WorkerResponseMessage>) => {
+    worker.onmessage = (e: MessageEvent<WorkerMessage>) => {
       const data = e.data;
       const { type } = data;
 
-      if (data.generationId !== generationIdRef.current) {
-        return;
-      }
-
       switch (type) {
         case 'progress':
-          setProgress(data.payload);
+          setProgress(data.payload as GenerateProgress);
           break;
         case 'complete':
           setIsGenerating(false);
-          if (data.payload.success) {
+          setResult(data.payload as GenerateResult);
-            setResult(data.payload);
-          } else if (data.payload.error && data.payload.error !== '生成已取消') {
-            setError(data.payload.error);
-          }
           setProgress(null);
           break;
         case 'error':
           setIsGenerating(false);
-          setError(data.payload.error);
+          setError((data.payload as { error: string }).error);
           setProgress(null);
           break;
       }
@@ -110,17 +100,15 @@ export function useGenerator(): UseGeneratorReturn {
     (fields: FieldConfig[], count: number, csvMode = false) => {
       if (isGenerating) return;
 
-      const generationId = ++generationIdRef.current;
-
       setIsGenerating(true);
       setProgress(null);
       setResult(null);
       setError(null);
 
       const worker = getWorker();
-      const message: WorkerRequestMessage = {
+      const message: WorkerMessage = {
         type: 'start',
-        payload: { generationId, fields, count, csvMode },
+        payload: { fields, count, csvMode },
       };
       worker.postMessage(message);
     },
@@ -132,8 +120,7 @@ export function useGenerator(): UseGeneratorReturn {
    */
   const cancel = useCallback(() => {
     if (workerRef.current && isGenerating) {
-      ++generationIdRef.current;
+      const message: WorkerMessage = { type: 'cancel' };
-      const message: WorkerRequestMessage = { type: 'cancel' };
       workerRef.current.postMessage(message);
       setIsGenerating(false);
       setProgress(null);

src/types/README.md

@@ -10,12 +10,10 @@
 
 **页面类型：**
 
-- `PageType` — 所有页面类型的联合类型（`dashboard` | `timestamp` | `storageCleaner` | ...）
+- `PageType` — 所有页面类型的联合类型（含 `dashboard`、`timestamp`、`storageCleaner`、`testDataGenerator` 等）
 - `JsonToolsPageMode` — JSON 工具子模式（`diff` | `format` | `yaml` | `toml` | `minify`）
 - `Base64ConverterPageMode` — Base64 子模式（`text` | `file` | `image`）
 - `Base64ConvertDirection` — 编解码方向（`encode` | `decode`）
-- `MarkdownToHtmlPreviewMode` — Markdown 预览模式（`split` | `preview` | `html`）
-- `HtmlToMarkdownPreviewMode` — HTML 预览模式（`split` | `preview` | `markdown`）
 
 **存储 Schema：**
 
@@ -34,6 +32,16 @@
 
 `qrious` 库的类型声明，定义 QR 码生成选项和 `QRious` 类。
 
+### testDataGenerator.ts
+
+测试数据生成器共享类型，包含：
+
+- `FieldConfig` — 字段配置（字段名、生成器、参数、必填、空值率、唯一性）
+- `DataRule` — 可保存/导入/导出的字段规则
+- `GeneratorDefinition` / `GeneratorParam` — 内置生成器定义和参数 Schema
+- `GenerateResult` / `GenerateProgress` / `WorkerMessage` — Worker 生成结果、进度和消息协议
+- `ExportFile` — JSON/CSV 导出文件描述
+
 ## 修改 StorageSchema 的注意事项
 
 修改 `StorageSchema` 时，必须：

src/types/testDataGenerator.ts

@@ -156,29 +156,19 @@ export interface GenerateProgress {
 }
 
 /**
- * Worker 请求消息类型
+ * Worker 消息类型
  */
-export type WorkerRequestMessage =
+export type WorkerMessage =
   | { type: 'start'; payload: WorkerStartPayload }
+  | { type: 'progress'; payload: GenerateProgress }
+  | { type: 'complete'; payload: GenerateResult }
+  | { type: 'error'; payload: { error: string } }
   | { type: 'cancel' };
 
-/**
- * Worker 响应消息类型
- */
-export type WorkerResponseMessage =
-  | { type: 'progress'; generationId: number; payload: GenerateProgress }
-  | { type: 'complete'; generationId: number; payload: GenerateResult }
-  | { type: 'error'; generationId: number; payload: { error: string } };
-
-/** @deprecated 使用 WorkerRequestMessage | WorkerResponseMessage */
-export type WorkerMessage = WorkerRequestMessage | WorkerResponseMessage;
-
 /**
  * Worker 启动参数
  */
 export interface WorkerStartPayload {
-  /** 生成任务 ID，用于忽略过期 Worker 响应 */
-  generationId: number;
   /** 字段配置列表 */
   fields: FieldConfig[];
   /** 生成数量 */

src/utils/README.md

@@ -5,7 +5,7 @@
 ## 工具函数
 
 | 文件                     | 用途                                                                                                |
-| -------------------- | --------------------------------------------------------------------------------------------------- |
+| ------------------------ | --------------------------------------------------------------------------------------------------- |
 | `chromeStorage.ts`       | Chrome Storage API 封装：类型安全的 `StorageUtils` 类，提供 `get/set/remove` 方法                   |
 | `chromeTabs.ts`          | Chrome Tabs API 封装：获取活动标签页、获取域名、在新标签页打开扩展页面                              |
 | `clipboard.ts`           | 剪贴板操作：`copyTextToClipboard`（文本）、`copyImageToClipboard`（图片）                           |
@@ -16,27 +16,28 @@
 | `jsonFormatter.ts`       | JSON 格式化/压缩：支持缩进、按键排序、minify                                                        |
 | `jsonToYaml.ts`          | JSON→YAML 转换                                                                                      |
 | `jsonToToml.ts`          | JSON→TOML 转换                                                                                      |
-| `markdownToHtml.ts`  | Markdown→HTML 转换：基于 `marked` 库，支持 GFM 和换行转换                                           |
-| `htmlToMarkdown.ts`  | HTML→Markdown 转换：基于 DOMParser 解析                                                             |
 | `qrCodeParser.ts`        | 二维码解析：基于 `qr-scanner` 库从文件中解析二维码                                                  |
 | `storageCleaner.ts`      | 存储清理：获取当前标签页、检测受限 URL、计算 Cookie/Storage 大小、清理操作                          |
 | `textStatistics.ts`      | 文本统计：使用 `Intl.Segmenter` 计算字符数/单词数/行数/字节大小                                     |
 | `format.ts`              | 通用格式化：`formatBytes` 将字节转为可读字符串（B/KB/MB/GB/TB）                                     |
 | `dayjs.ts`               | Day.js 初始化：扩展 UTC、Timezone、RelativeTime 插件，加载中文本地化                                |
+| `chromeI18n.ts`          | Chrome `chrome.i18n` 包装：提供 `getMessage` 和兼容 React 使用的 `useI18n` Hook                     |
+| `ruleStorage.ts`         | 测试数据生成器规则存储：基于 `localStorage` 的 CRUD、搜索、导入/导出和数量限制                      |
+| `dataExporter.ts`        | 测试数据导出：JSON/CSV 转换、文件下载和复制到剪贴板                                                 |
+| `rightClickInjection.ts` | 右键恢复注入脚本：在页面上下文恢复 contextmenu/copy/paste 等事件默认行为                            |
 
 ## 自定义 Hooks
 
 | 文件                    | 用途                                                                                                           |
 | ----------------------- | -------------------------------------------------------------------------------------------------------------- |
 | `useStorageState.ts`    | Chrome Storage 状态 Hook：类似 `useState`，值自动同步到 `chrome.storage`，使用 `localStorage` 快照消除首屏闪烁 |
-| `useLazyTranslation.ts` | 懒加载翻译 Hook：按需动态导入 i18n 命名空间，支持预加载和缓存                                                  |
 | `useContextMenuData.ts` | 右键菜单数据 Hook：从 storage 读取待处理数据，匹配 featureKey 后消费并触发回调                                 |
 | `useDebounce.ts`        | 防抖 Hook：对值进行延迟更新，避免频繁触发                                                                      |
 
 ## 使用约定
 
 - 工具函数使用**命名导出**（`export function xxx()`）
-- 工具函数**不抛异常**，返回包含 `hasError` 和 `error` 字段的结果对象
+- 工具层不直接展示 Toast；可恢复错误返回可判断结果，需要抛出的解析/转换错误由页面 Hook 或 UI 层捕获
 - Hook 使用 `use` 前缀命名，定义返回值接口类型
 - 存储操作使用 `chromeStorage.ts` 的 `storageUtil` 封装，不要直接调用 `chrome.storage`
 - 消息通信使用 `messages.ts` 的 `sendMessage`/`onMessage`，不要使用原生 `chrome.runtime.sendMessage`

src/utils/__tests__/ruleStorage.test.ts

@@ -1,65 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import * as ruleStorage from '../ruleStorage';
-
-const STORAGE_KEY = 'testDataGenerator_rules';
-
-const mockField = {
-  id: 'field-1',
-  name: 'username',
-  generatorId: 'string',
-  params: {},
-  required: true,
-  nullRate: 0,
-  unique: false,
-};
-
-describe('ruleStorage', () => {
-  beforeEach(() => {
-    localStorage.clear();
-    vi.restoreAllMocks();
-  });
-
-  it('save 在 localStorage 写入失败时应返回 null', () => {
-    vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
-      throw new DOMException('QuotaExceededError');
-    });
-
-    const result = ruleStorage.save({
-      name: 'Test Rule',
-      fields: [mockField],
-    });
-
-    expect(result).toBeNull();
-    expect(localStorage.getItem(STORAGE_KEY)).toBeNull();
-  });
-
-  it('update 在 localStorage 写入失败时应返回 null', () => {
-    const saved = ruleStorage.save({
-      name: 'Test Rule',
-      fields: [mockField],
-    });
-    expect(saved).not.toBeNull();
-
-    vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
-      throw new DOMException('QuotaExceededError');
-    });
-
-    const updated = ruleStorage.update(saved!.id, { name: 'Updated Rule' });
-    expect(updated).toBeNull();
-  });
-
-  it('deleteRule 在 localStorage 写入失败时应返回 false', () => {
-    const saved = ruleStorage.save({
-      name: 'Test Rule',
-      fields: [mockField],
-    });
-    expect(saved).not.toBeNull();
-
-    vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
-      throw new DOMException('QuotaExceededError');
-    });
-
-    expect(ruleStorage.deleteRule(saved!.id)).toBe(false);
-    expect(ruleStorage.getById(saved!.id)).toBeDefined();
-  });
-});

src/utils/ruleStorage.ts

@@ -78,9 +78,7 @@ export function save(
       useCount: 0,
     };
     rules.unshift(newRule);
-    if (!setAll(rules)) {
+    setAll(rules);
-      return null;
-    }
     return newRule;
   }
 
@@ -97,9 +95,7 @@ export function save(
     updatedAt: now,
   };
   rules[index] = updatedRule;
-  if (!setAll(rules)) {
+  setAll(rules);
-    return null;
-  }
   return updatedRule;
 }
 
@@ -121,9 +117,7 @@ export function update(id: string, updates: Partial<DataRule>): DataRule | null
     updatedAt: Date.now(),
   };
   rules[index] = updatedRule;
-  if (!setAll(rules)) {
+  setAll(rules);
-    return null;
-  }
   return updatedRule;
 }
 
@@ -138,7 +132,8 @@ export function deleteRule(id: string): boolean {
     return false;
   }
   rules.splice(index, 1);
-  return setAll(rules);
+  setAll(rules);
+  return true;
 }
 
 /**
@@ -170,9 +165,7 @@ export function duplicate(id: string, copySuffix = '（副本）'): DataRule | n
 
   const rules = getAll();
   rules.unshift(newRule);
-  if (!setAll(rules)) {
+  setAll(rules);
-    return null;
-  }
   return newRule;
 }
 
@@ -274,13 +267,11 @@ export function clear(): void {
 /**
  * 保存所有规则到存储
  */
-function setAll(rules: DataRule[]): boolean {
+function setAll(rules: DataRule[]): void {
   try {
     localStorage.setItem(STORAGE_KEY, JSON.stringify(rules));
-    return true;
   } catch (error) {
     console.error('[ruleStorage] 保存规则失败:', error);
-    return false;
   }
 }
 

src/workers/generator.worker.ts

@@ -6,14 +6,11 @@
 import { getGeneratorById } from '@/lib/generators';
 import type {
   FieldConfig,
-  WorkerRequestMessage,
+  WorkerMessage,
   GenerateResult,
   GenerateProgress,
 } from '@/types/testDataGenerator';
 
-/** 每生成 N 行让出一次事件循环，以便处理 cancel 消息 */
-const YIELD_EVERY = 100;
-
 // 生成结果缓存
 let generatedData: Record<string, unknown>[] = [];
 let isCancelled = false;
@@ -21,7 +18,7 @@ let isCancelled = false;
 /**
  * Worker 消息处理器
  */
-self.onmessage = async (e: MessageEvent<WorkerRequestMessage>) => {
+self.onmessage = async (e: MessageEvent<WorkerMessage>) => {
   const data = e.data;
   const { type } = data;
 
@@ -40,12 +37,11 @@ self.onmessage = async (e: MessageEvent<WorkerRequestMessage>) => {
  * 处理开始生成消息
  */
 async function handleStart(payload: {
-  generationId: number;
   fields: FieldConfig[];
   count: number;
   csvMode: boolean;
 }): Promise<void> {
-  const { generationId, fields, count } = payload;
+  const { fields, count } = payload;
   generatedData = [];
 
   try {
@@ -55,7 +51,6 @@ async function handleStart(payload: {
       if (!generator) {
         self.postMessage({
           type: 'error',
-          generationId,
           payload: { error: `生成器 "${field.generatorId}" 不存在` },
         });
         return;
@@ -70,7 +65,6 @@ async function handleStart(payload: {
       if (isCancelled) {
         self.postMessage({
           type: 'complete',
-          generationId,
           payload: {
             success: false,
             error: '生成已取消',
@@ -142,23 +136,7 @@ async function handleStart(payload: {
           total: count,
           estimatedTimeLeft: Math.round(((Date.now() - startTime) / (i + 1)) * (count - i - 1)),
         };
-        self.postMessage({ type: 'progress', generationId, payload: progress });
+        self.postMessage({ type: 'progress', payload: progress });
-      }
-
-      // 定期让出事件循环，使 cancel 消息能被处理
-      if ((i + 1) % YIELD_EVERY === 0) {
-        await new Promise<void>((resolve) => setTimeout(resolve, 0));
-        if (isCancelled) {
-          self.postMessage({
-            type: 'complete',
-            generationId,
-            payload: {
-              success: false,
-              error: '生成已取消',
-            },
-          });
-          return;
-        }
       }
     }
 
@@ -177,11 +155,10 @@ async function handleStart(payload: {
       },
     };
 
-    self.postMessage({ type: 'complete', generationId, payload: result });
+    self.postMessage({ type: 'complete', payload: result });
   } catch (error) {
     self.postMessage({
       type: 'error',
-      generationId,
       payload: { error: `生成失败: ${error}` },
     });
   }