LingandRX
8d36f21f1b
* docs: 添加组件文档注释和类型导入 refactor: 统一使用 SnackbarOptions 类型 style: 优化导入语句顺序和格式 * refactor: 简化假数据生成器中的faker导入和使用 Co-authored-by: Copilot <copilot@github.com> * feat(form-recognizer): 增强表单识别功能并优化UI交互 - 新增字段类型偏好设置功能，支持按域名保存字段类型 - 重构FieldList组件，改进字段选择和类型修改体验 - 添加字段定位闪烁功能，便于在页面上快速找到对应字段 - 优化表单填充逻辑，支持单个字段覆盖默认填充模式 - 移除独立的侧边栏页面，统一使用主页面组件 - 改进useStorageState钩子，增加加载状态管理和防抖处理 * refactor: 移除未使用的组件文件 * refactor(页面头部): 提取通用 PageHeader 组件并替换各页面头部实现 重构各页面头部为统一的 PageHeader 组件，提高代码复用性和维护性 * style(组件): 调整自动刷新开关和存储选项网格的样式 优化自动刷新开关的文本内边距，重构存储选项网格的布局结构，调整间距和边框样式 * style(ui): 调整时间戳页面和结果视图的样式 - 为时区选择器添加圆角 - 优化结果视图的布局和对齐方式 - 调整结果项的内边距和文本样式 * ci(workflow): 移除Firefox测试以简化CI流程 仅保留Chrome浏览器的构建步骤，减少CI运行时间和资源消耗 * refactor(qrcode): 重构二维码解析功能并提取为独立模块 * style(页面样式): 统一页面头部图标颜色并优化表单样式 更新各页面头部组件的图标颜色配置，移除冗余的表单标签属性，优化输入框样式和按钮悬停效果 * feat(formMapping): 添加表单映射功能 - 创建 FormMappingPage 页面组件 - 实现表单扫描器 scanner.ts - 实现高亮器 highlighter.ts - 更新路由配置 routes.ts - 更新内容脚本 content.ts - 更新类型定义 storage.d.ts - 添加 formMappingPageStyles 样式配置 * feat(表单映射): 添加配置导出功能及状态提示 添加配置导出为JSON文件的功能，包含导出按钮和错误处理。新增Snackbar组件用于显示导出成功和错误状态。优化页面布局结构，将状态提示移至全局容器外。 * feat(表单填充): 新增智能表单填充功能 添加智能表单填充功能，包括： 1. 新增表单填充页面和路由配置 2. 实现模糊匹配引擎和智能注入引擎 3. 添加Mock数据生成器和视觉反馈渲染器 4. 扩展消息接口支持填充操作 * ci: 精简触发CI的工作流分支 移除对develop分支及其变体的触发，仅保留main分支的触发 * test: 更新路由测试以匹配新增的路由数量 * test: 将测试文件中的描述和断言翻译为中文 * test(PageHeader): 添加组件测试用例验证渲染逻辑和样式 * refactor(theme): 重构主题样式并优化仪表盘卡片组件 将页面样式配置集中管理，移除各页面中硬编码的背景色 新增 DashboardCard 组件封装通用卡片逻辑 添加 dashboardCards 配置文件统一管理卡片数据 * refactor(Button): 统一按钮样式并移除重复样式定义 将按钮样式统一封装到 Button 组件中，移除各页面重复的样式定义 更新组件文档说明，提供更清晰的用法示例 * docs: 更新 README 文件中的目录结构说明 添加新组件和配置文件的说明，保持文档与代码同步 * refactor: 优化代码类型声明和UI布局 修复类型声明从any改为never以提高类型安全性 调整TimestampPage页面布局间距 移除DashboardPage中不必要的实时时钟状态 更新ESLint配置以使用推荐配置 添加选项页面打开的错误处理 * refactor(消息通信): 使用 @webext-core/messaging 重构消息处理逻辑 将原有的 chrome.runtime.onMessage 和 chrome.tabs.sendMessage 替换为类型安全的 @webext-core/messaging 实现 添加 ProtocolMap 类型定义确保消息类型安全 更新相关页面和后台脚本使用新的消息通信方式 * fix: 修复依赖项缺失导致的潜在问题 修复 useStorageState 中缺少 defaultValue 依赖的问题 重构 RouterProvider 的初始化逻辑，使用 useCallback 优化性能 * refactor: 重构表单识别和消息处理逻辑 将表单映射UI逻辑提取到独立文件 将消息处理器提取到独立文件 将表单识别页面逻辑提取到自定义hook 优化代码结构和可维护性 * feat(侧边栏): 添加侧边栏状态变化通知功能 - 在消息类型中新增侧边栏状态变化枚举和字段 - 侧边栏打开和关闭时发送状态通知 - 替换轮询检查方式为消息监听机制 * refactor: 优化高亮组件渲染逻辑并添加防抖处理 重构高亮组件渲染逻辑，使用 requestAnimationFrame 进行节流优化 在 useStorageCleaner 中添加防抖处理以避免频繁加载 * refactor: 统一组件导出方式为默认导出 * refactor: 重构样式系统并迁移至 MUI 主题 删除冗余的 CSS 文件，统一使用 MUI 主题管理样式 新增 useActiveTabDomain 和 useSidePanelState 自定义 Hook 优化各入口点的主题集成和布局处理 * docs: 更新项目文档以反映新增功能和技术栈细节 更新 AGENTS.md 文档，详细描述新增的功能模块（存储管理、URL 管理、二维码生成、表单工具套件等）和更新的技术栈信息 * feat: 添加错误边界组件以捕获子组件错误 在 popup、sidepanel 和 options 入口点添加 ErrorBoundary 组件，用于捕获并处理子组件中的 JavaScript 错误。当错误发生时，显示友好的错误界面并提供刷新功能。 * refactor(ui): 使用全局 snackbar 替换本地通知组件 重构表单页面中的通知系统，移除本地 Snackbar 和 Alert 组件，改用全局 GlobalSnackbar 组件统一管理通知 标准化主题配置中的 CSS 属性命名，移除带前缀的样式属性 * refactor(snackbar): 重构全局消息提示为 SnackbarProvider 组件 将原本分散在各页面的 GlobalSnackbar 组件重构为集中管理的 SnackbarProvider，通过 Context 提供统一的消息提示功能。主要变更包括： 1. 创建新的 SnackbarProvider 组件作为全局消息提示容器 2. 提供 useSnackbar hook 供子组件调用 3. 移除各页面中独立的 GlobalSnackbar 实例 4. 在 App 根组件中统一集成 SnackbarProvider 5. 优化消息提示样式和交互行为 * refactor(Snackbar): 重构消息提示组件并优化样式 重构 Snackbar 组件，将状态管理逻辑提取到 GlobalSnackbar 中复用 优化消息提示样式，调整阴影效果和最小尺寸 统一各页面使用 Snackbar 的方式，移除冗余配置 * refactor: 重构路由和功能配置系统 - 将路由配置和仪表盘卡片配置合并为统一的 features 配置 - 重构 RouterProvider 增加数据校验和本地快照功能 - 优化表单字段识别和填充逻辑，提取公共方法 - 更新相关组件和文档以适配新的配置系统 - 删除废弃的 dashboardCards 和 routes 配置文件
316 lines
13 KiB
Markdown
316 lines
13 KiB
Markdown
# AGENTS.md
|
||
|
||
This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
这是一个基于 WXT 框架的浏览器扩展项目，提供多种测试工具功能，包括时间戳转换、存储管理、URL 管理、二维码生成、表单识别与填充等。
|
||
|
||
## 核心命令
|
||
|
||
### 开发相关
|
||
|
||
- `npm run dev` - 启动 Chrome 浏览器的开发模式
|
||
- `npm run dev:firefox` - 启动 Firefox 浏览器的开发模式
|
||
- `npm run build` - 构建 Chrome 浏览器的生产版本
|
||
- `npm run build:firefox` - 构建 Firefox 浏览器的生产版本
|
||
- `npm run zip` - 打包 Chrome 扩展
|
||
- `npm run zip:firefox` - 打包 Firefox 扩展
|
||
- `npm run compile` - TypeScript 类型检查（不生成文件）
|
||
- `npm run lint` - 运行 ESLint 检查
|
||
|
||
### 测试相关
|
||
|
||
- `npm run test` - 运行所有测试（单次执行）
|
||
- `npm run test:watch` - 运行测试并监听文件变化
|
||
- `npm run test:coverage` - 运行测试并生成覆盖率报告
|
||
|
||
**运行单个测试文件：**
|
||
|
||
```bash
|
||
npx vitest run components/__tests__/CopyButton.test.tsx
|
||
```
|
||
|
||
**测试技术栈：**
|
||
|
||
- Vitest v2 - 测试框架
|
||
- @testing-library/react v16 - React 组件测试
|
||
- @testing-library/user-event v14 - 用户交互模拟
|
||
- jsdom v25 - 浏览器环境模拟
|
||
|
||
### 依赖与准备
|
||
|
||
- `npm install` - 安装依赖
|
||
- `postinstall` 会自动运行 `wxt prepare` 准备开发环境
|
||
- `prepare` 钩子会初始化 Husky Git 钩子
|
||
|
||
## 项目架构
|
||
|
||
### 技术栈
|
||
|
||
- **框架**: WXT v0.20.6 (Web Extension Toolkit) - 浏览器扩展开发框架
|
||
- **前端**: React 19 + TypeScript 5
|
||
- **UI 库**: Material UI (MUI) v7 + Emotion
|
||
- **状态管理**: React Hooks + 自定义 Hooks
|
||
- **路由**: 自定义路由系统（支持 popup/sidepanel/detached 三种模式）
|
||
- **测试**: Vitest + Testing Library
|
||
- **代码质量**: ESLint v9 + Prettier + Husky + lint-staged
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
├── components/ # 可复用 UI 组件
|
||
│ ├── __tests__/ # 组件测试文件
|
||
│ ├── Button.tsx # 按钮组件
|
||
│ ├── CopyButton.tsx # 复制按钮组件
|
||
│ ├── DashboardCard.tsx # 仪表盘卡片组件
|
||
│ ├── FieldList.tsx # 字段列表组件
|
||
│ ├── GlobalSnackbar.tsx # 全局提示消息组件
|
||
│ ├── PageHeader.tsx # 页面头部组件
|
||
│ ├── QrCodeToUrlSection.tsx # 二维码解析为 URL 组件
|
||
│ ├── QrCodeUploader.tsx # 二维码上传组件
|
||
│ ├── RouterContainer.tsx # 路由容器组件
|
||
│ ├── StorageCleanerConfirm.tsx # 存储清理确认组件
|
||
│ ├── ToolCard.tsx # 工具卡片组件
|
||
│ ├── TopBar.tsx # 顶部导航栏组件
|
||
│ ├── UrlEntryForm.tsx # URL 录入表单组件
|
||
│ ├── UrlEntryItem.tsx # URL 条目组件
|
||
│ ├── UrlEntryList.tsx # URL 列表组件
|
||
│ └── UrlToQrCodeSection.tsx # URL 转二维码组件
|
||
├── config/ # 配置文件
|
||
│ ├── __tests__/ # 配置测试文件
|
||
│ ├── dashboardCards.tsx # 仪表盘卡片配置
|
||
│ ├── pageTheme.ts # 页面主题配置
|
||
│ ├── routes.ts # 路由配置
|
||
│ └── theme.ts # 全局主题配置
|
||
├── entrypoints/ # 浏览器扩展入口点
|
||
│ ├── background.ts # 后台脚本（主进程）
|
||
│ ├── content.ts # 内容脚本（注入到页面）
|
||
│ ├── content/
|
||
│ │ └── messageHandler.ts # 消息处理器
|
||
│ ├── options/ # 选项页面
|
||
│ │ ├── App.tsx # 选项应用
|
||
│ │ ├── index.html # 选项页面 HTML
|
||
│ │ └── main.tsx # 选项页面入口
|
||
│ ├── popup/ # 扩展弹窗界面
|
||
│ │ ├── App.tsx # 弹窗主应用
|
||
│ │ ├── main.tsx # 弹窗入口
|
||
│ │ ├── index.html # 弹窗 HTML
|
||
│ │ ├── pages/ # 弹窗页面
|
||
│ │ │ ├── components/ # 页面级组件
|
||
│ │ │ │ ├── AutoRefreshToggle.tsx # 自动刷新开关
|
||
│ │ │ │ ├── CleaningResult.tsx # 清理结果展示
|
||
│ │ │ │ ├── DomainHeader.tsx # 域名头部
|
||
│ │ │ │ ├── ErrorDisplay.tsx # 错误显示
|
||
│ │ │ │ ├── LiveClock.tsx # 实时时钟
|
||
│ │ │ │ ├── OptionItem.tsx # 选项条目
|
||
│ │ │ │ ├── ResultView.tsx # 结果视图
|
||
│ │ │ │ └── StorageOptionsGrid.tsx # 存储选项网格
|
||
│ │ │ ├── hooks/ # 自定义 Hooks
|
||
│ │ │ │ ├── useActiveTabDomain.ts # 当前标签页域名
|
||
│ │ │ │ ├── useFormRecognizer.ts # 表单识别
|
||
│ │ │ │ ├── useSidePanelState.ts # 侧边栏状态
|
||
│ │ │ │ └── useTimestampConverter.ts # 时间戳转换
|
||
│ │ │ ├── DashboardPage.tsx # 仪表盘页面
|
||
│ │ │ ├── FormFillPage.tsx # 表单填充页面
|
||
│ │ │ ├── FormMappingPage.tsx # 表单映射页面
|
||
│ │ │ ├── FormRecognizerPage.tsx # 表单识别页面
|
||
│ │ │ ├── OpenUrlPage.tsx # 打开 URL 页面
|
||
│ │ │ ├── OpenUrlViewerPage.tsx # URL 查看页面
|
||
│ │ │ ├── QrCodePage.tsx # 二维码页面
|
||
│ │ │ ├── StorageCleanerPage.tsx # 存储清理页面
|
||
│ │ │ ├── TimestampPage.tsx # 时间戳页面
|
||
│ │ │ └── useStorageCleaner.ts # 存储清理 Hook
|
||
│ └── sidepanel/ # 侧边栏界面
|
||
│ ├── App.tsx # 侧边栏应用
|
||
│ ├── index.html # 侧边栏 HTML
|
||
│ └── main.tsx # 侧边栏入口
|
||
├── providers/ # React Providers
|
||
│ └── RouterProvider.tsx # 路由 Provider
|
||
├── utils/ # 工具函数
|
||
│ ├── __tests__/ # 工具测试文件
|
||
│ ├── formMapping/ # 表单映射工具
|
||
│ │ ├── highlighter.ts # 表单高亮器
|
||
│ │ ├── scanner.ts # 表单扫描器
|
||
│ │ ├── smartInjector.ts # 智能注入器
|
||
│ │ └── ui.ts # UI 工具
|
||
│ ├── chromeStorage.ts # Chrome 存储工具
|
||
│ ├── chromeTabs.ts # Chrome 标签页工具
|
||
│ ├── clipboard.ts # 剪贴板工具
|
||
│ ├── dataTemplate.ts # 数据模板
|
||
│ ├── dataValidator.ts # 数据验证器
|
||
│ ├── dayjs.ts # 日期处理工具
|
||
│ ├── dummyDataGenerator.ts # 虚拟数据生成器（基于 Faker）
|
||
│ ├── messages.ts # 消息通信工具
|
||
│ ├── qrCodeParser.ts # 二维码解析器
|
||
│ ├── storageCleaner.ts # 存储清理工具
|
||
│ ├── useStorageState.ts # 存储状态 Hook
|
||
│ └── useUrlPreferences.ts # URL 偏好设置 Hook
|
||
├── types/ # 类型定义
|
||
│ └── storage.d.ts # 存储相关类型
|
||
├── docs/ # 文档
|
||
│ └── plans/ # 计划文档
|
||
├── public/ # 静态资源
|
||
│ └── icon/ # 扩展图标
|
||
└── .github/ # GitHub 配置
|
||
└── workflows/ # CI/CD 工作流
|
||
├── ci.yml # 持续集成
|
||
└── release.yml # 发布流程
|
||
```
|
||
|
||
### 核心功能模块
|
||
|
||
#### 1. 时间戳转换工具
|
||
|
||
- 位置: `entrypoints/popup/pages/TimestampPage.tsx`
|
||
- Hook: `entrypoints/popup/pages/hooks/useTimestampConverter.ts`
|
||
- 依赖: dayjs 库进行日期处理
|
||
- 功能: 支持日期与时间戳的双向转换，支持多种格式，实时时钟显示
|
||
|
||
#### 2. 存储清理工具
|
||
|
||
- 位置: `entrypoints/popup/pages/StorageCleanerPage.tsx`
|
||
- Hook: `entrypoints/popup/pages/useStorageCleaner.ts`
|
||
- 工具: `utils/storageCleaner.ts`
|
||
- 功能: 清理缓存、Cookies、本地存储，支持按域名筛选，自动刷新功能
|
||
|
||
#### 3. URL 管理工具
|
||
|
||
- 打开 URL: `entrypoints/popup/pages/OpenUrlPage.tsx`
|
||
- 查看 URL: `entrypoints/popup/pages/OpenUrlViewerPage.tsx`
|
||
- 组件: `components/UrlEntryForm.tsx`, `components/UrlEntryList.tsx`
|
||
- 功能: 批量打开多个 URL，URL 列表管理
|
||
|
||
#### 4. 二维码工具
|
||
|
||
- 位置: `entrypoints/popup/pages/QrCodePage.tsx`
|
||
- 组件: `components/QrCodeUploader.tsx`, `components/QrCodeToUrlSection.tsx`, `components/UrlToQrCodeSection.tsx`
|
||
- 工具: `utils/qrCodeParser.ts`
|
||
- 依赖: qrcode, jsqr 库
|
||
- 功能: URL 转二维码生成，二维码图片解析为 URL
|
||
|
||
#### 5. 表单工具套件
|
||
|
||
**表单识别 (Form Recognizer)**
|
||
|
||
- 位置: `entrypoints/popup/pages/FormRecognizerPage.tsx`
|
||
- Hook: `entrypoints/popup/pages/hooks/useFormRecognizer.ts`
|
||
- 功能: 智能识别页面表单指纹
|
||
|
||
**表单映射 (Form Mapping)**
|
||
|
||
- 位置: `entrypoints/popup/pages/FormMappingPage.tsx`
|
||
- 工具: `utils/formMapping/` 目录
|
||
- `scanner.ts` - 表单扫描器
|
||
- `highlighter.ts` - 表单高亮器
|
||
- `smartInjector.ts` - 智能注入器
|
||
- `ui.ts` - UI 工具
|
||
- 功能: 表单指纹识别与自定义映射规则配置
|
||
|
||
**表单填充 (Form Fill)**
|
||
|
||
- 位置: `entrypoints/popup/pages/FormFillPage.tsx`
|
||
- 工具: `utils/dummyDataGenerator.ts` (基于 @faker-js/faker)
|
||
- 功能: 根据表单指纹智能填充表单数据
|
||
|
||
#### 6. 仪表盘系统
|
||
|
||
- 位置: `entrypoints/popup/pages/DashboardPage.tsx`
|
||
- 配置: `config/features.tsx`
|
||
- 组件: `components/DashboardCard.tsx`, `components/ToolCard.tsx`
|
||
- 功能: 统一工具入口，可自定义显示的工具卡片
|
||
|
||
#### 7. 多模式显示系统
|
||
|
||
- 支持三种显示模式:
|
||
- **popup** - 扩展弹窗（点击图标显示）
|
||
- **sidepanel** - 浏览器侧边栏
|
||
- **detached** - 独立窗口模式
|
||
- 路由配置: `config/features.tsx`
|
||
- 路由容器: `components/RouterContainer.tsx`
|
||
- Provider: `providers/RouterProvider.tsx`
|
||
|
||
#### 8. 通信系统
|
||
|
||
- 位置: `utils/messages.ts`
|
||
- 机制: 使用 `@webext-core/messaging` 库实现
|
||
- 内容脚本消息处理: `entrypoints/content/messageHandler.ts`
|
||
- 通信通道: 后台脚本 ↔ 内容脚本 ↔ 弹窗/侧边栏
|
||
|
||
#### 9. 数据存储
|
||
|
||
- Chrome Storage API: `utils/chromeStorage.ts`
|
||
- 存储状态 Hook: `utils/useStorageState.ts`
|
||
- URL 偏好设置: `utils/useUrlPreferences.ts`
|
||
- 类型定义: `types/storage.d.ts`
|
||
|
||
### 关键配置文件
|
||
|
||
#### wxt.config.ts
|
||
|
||
- 配置 WXT 框架参数
|
||
- 启用 React 模块
|
||
- 配置浏览器扩展权限（storage, unlimitedStorage, clipboardWrite, activeTab, scripting, tabs, cookies, sidePanel）
|
||
- Vite 构建配置（使用 Terser 压缩，强制 ASCII 编码）
|
||
- 配置侧边栏和选项页面
|
||
|
||
#### manifest 权限
|
||
|
||
```typescript
|
||
permissions: [
|
||
'storage', // 存储权限
|
||
'unlimitedStorage', // 无限制存储
|
||
'clipboardWrite', // 剪贴板写入
|
||
'activeTab', // 当前标签页
|
||
'scripting', // 脚本注入
|
||
'tabs', // 标签页管理
|
||
'cookies', // Cookies 管理
|
||
'sidePanel', // 侧边栏
|
||
],
|
||
host_permissions:['<all_urls>'] // 访问所有网站
|
||
```
|
||
|
||
#### CI/CD 配置
|
||
|
||
- `.github/workflows/ci.yml` - 持续集成工作流
|
||
- `.github/workflows/release.yml` - 发布工作流
|
||
|
||
## 开发注意事项
|
||
|
||
### 扩展入口点
|
||
|
||
- **后台脚本**: `entrypoints/background.ts` - 处理扩展生命周期和后台任务
|
||
- **内容脚本**: `entrypoints/content.ts` - 注入到网页中，处理 DOM 交互
|
||
- **弹窗**: `entrypoints/popup/main.tsx` - 用户点击扩展图标时显示
|
||
- **侧边栏**: `entrypoints/sidepanel/main.tsx` - 浏览器侧边栏界面
|
||
- **选项页面**: `entrypoints/options/main.tsx` - 扩展设置页面
|
||
|
||
### 路由系统
|
||
|
||
- 使用自定义路由系统，支持多种显示模式
|
||
- 路由配置在 `config/features.tsx`
|
||
- 通过 `getEntryPointType()` 判断当前入口点类型
|
||
- 支持页面可见性配置（`defaultVisible`）
|
||
|
||
### 浏览器兼容性
|
||
|
||
- 支持 Chrome 和 Firefox 浏览器
|
||
- 使用 WXT 框架抽象浏览器差异
|
||
- 使用 `@types/chrome` 和 `@types/webextension-polyfill` 提供类型支持
|
||
|
||
### 代码质量
|
||
|
||
- 使用 ESLint v9 进行代码检查（基于 typescript-eslint）
|
||
- Prettier 进行代码格式化
|
||
- Husky v9 用于 Git 钩子管理
|
||
- Lint-staged 确保暂存文件符合规范
|
||
- GitHub Actions CI/CD 自动化测试和构建
|
||
|
||
### 测试策略
|
||
|
||
- 组件测试: `components/__tests__/` 目录
|
||
- 工具函数测试: `utils/__tests__/` 目录
|
||
- 配置测试: `config/__tests__/` 目录
|
||
- 使用 Vitest 作为测试框架
|
||
- 使用 Testing Library 进行 React 组件测试
|