LingandRX
7167a43763
核心功能新增 工具套件扩展 JSON 工具（差异比较、格式化、转 YAML/TOML、压缩） Base64 转换器（文本/文件/图像编解码） Markdown ↔ HTML 双向转换 JWT 解析器 文本统计工具 二维码生成/解析（替换库以减小体积） 表单工具（已移除） 表单映射、智能填充、高亮定位功能已移除 架构与工程改进 技术栈升级 引入 @webext-core/messaging 重构消息通信 添加 @dnd-kit 支持功能列表拖拽排序 引入 i18next 实现中英文国际化 使用 MUI 主题系统替代硬编码样式，支持暗色模式 代码质量 统一组件导出为默认导出 提取公共组件（TextInputArea、SwitchButtonGroup、PageHeader、DecodeResultPaper） 使用 useStorageState 钩子统一管理存储状态 添加 PageErrorBoundary 页面级错误边界 实现组件懒加载优化首屏性能 关键重构 路由系统重构 — 支持独立标签页模式，合并路由与功能配置 状态管理优化 — 存储状态增加快照机制、验证器和防抖处理 剪贴板与打印工具 — 统一为 async/await 形式，修复重复触发问题 存储清理器 — 使用 TextEncoder 准确计算 UTF-8 字节数，支持 TB 单位 测试与 CI 测试覆盖 — 为新增工具、公共组件、边界场景补充单元测试 CI 精简 — 移除 Firefox 测试，仅保留 Chrome；修正类型检查命令
123 lines
5.4 KiB
Markdown
123 lines
5.4 KiB
Markdown
# AGENTS.md
|
||
|
||
This file provides guidance to AI agents (such as Gemini, Codex, etc.) when working with the code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
**Testing Tools** 是一个基于 WXT (Web Extension Toolkit) 框架的现代化浏览器扩展项目. 它提供了一系列实用的开发和测试工具，包括时间戳转换、存储管理、文本统计、JWT 解析及二维码工具.
|
||
|
||
## 核心命令
|
||
|
||
### 开发与构建
|
||
|
||
- `npm run dev` - 启动 Chrome 浏览器的开发模式（支持 HMR）
|
||
- `npm run dev:firefox` - 启动 Firefox 浏览器的开发模式
|
||
- `npm run build` - 构建 Chrome 浏览器的生产版本
|
||
- `npm run build:firefox` - 构建 Firefox 浏览器的生产版本
|
||
- `npm run zip` - 打包 Chrome 扩展为 ZIP 文件
|
||
- `npm run zip:firefox` - 打包 Firefox 扩展为 ZIP 文件
|
||
- `npm run typecheck` - 执行 TypeScript 类型检查（`tsc --noEmit`）
|
||
- `npm run lint` - 运行 ESLint 静态代码检查
|
||
|
||
### 测试
|
||
|
||
- `npm run test` - 运行所有单元测试（单次执行）
|
||
- `npm run test:watch` - 启动 Vitest 交互式监视模式
|
||
- `npm run test:coverage` - 运行测试并生成代码覆盖率报告
|
||
|
||
**运行单个测试文件：**
|
||
|
||
```bash
|
||
npx vitest run path/to/your.test.ts
|
||
```
|
||
|
||
### 依赖管理
|
||
|
||
- `npm install` - 安装项目依赖
|
||
- `postinstall` 钩子会自动运行 `wxt prepare` 以生成必要的类型定义和入口点.
|
||
- `prepare` 钩子会自动初始化 Husky 以进行 Git 提交前检查.
|
||
|
||
## 项目架构与目录结构
|
||
|
||
### 技术栈
|
||
|
||
- **框架**: WXT v0.20.6 (Web Extension Toolkit)
|
||
- **前端**: React 19 + TypeScript 5
|
||
- **UI 库**: Material UI (MUI) @7.x + Emotion
|
||
- **日期处理**: dayjs (集成 UTC 和 Timezone 插件)
|
||
- **通信**: `@webext-core/messaging` (用于 Entrypoints 间通信)
|
||
- **测试**: Vitest + Testing Library (jsdom 环境)
|
||
- **代码规范**: ESLint v9 + Prettier + Husky + lint-staged
|
||
|
||
### 目录结构
|
||
|
||
```text
|
||
├── components/ # 原子级 UI 组件
|
||
│ ├── __tests__/ # 组件单元测试
|
||
│ ├── PageHeader.tsx # 标准页面头部
|
||
│ ├── ToolCard.tsx # 仪表盘卡片基础
|
||
│ └── ...
|
||
├── config/ # 核心配置与元数据
|
||
│ ├── features.tsx # 功能特性定义（路由与元数据的单一事实来源）
|
||
│ ├── pageTheme.ts # 页面级主题与样式常量
|
||
│ └── theme.ts # MUI 全局主题配置
|
||
├── entrypoints/ # 浏览器扩展入口点
|
||
│ ├── background.ts # 后台 Service Worker (消息中转与生命周期)
|
||
│ ├── content.ts # 注入页面的内容脚本
|
||
│ ├── popup/ # 弹窗界面主入口
|
||
│ ├── options/ # 选项页面主入口
|
||
│ └── sidepanel/ # 侧边栏界面主入口
|
||
├── pages/ # 功能模块页面组件
|
||
│ ├── DashboardPage.tsx # 仪表盘/首页
|
||
│ ├── Jwt/index.tsx # JWT 解析工具
|
||
│ ├── QrCode/index.tsx # 二维码工具
|
||
│ ├── StorageCleaner/index.tsx # 存储清理工具
|
||
│ ├── TextStatistics/index.tsx # 文本统计工具
|
||
│ └── Timestamp/index.tsx # 时间戳转换工具
|
||
├── providers/ # React Context Providers (Router, Theme 等)
|
||
├── utils/ # 业务逻辑与工具函数
|
||
│ ├── chromeStorage.ts # 类型安全的 Chrome Storage 封装
|
||
│ ├── jwt.ts # JWT 解析逻辑
|
||
│ ├── textStatistics.ts # 文本分析逻辑
|
||
│ └── ...
|
||
├── types/ # 全局 TypeScript 类型声明
|
||
└── public/ # 静态资源 (图标等)
|
||
```
|
||
|
||
## 核心功能说明
|
||
|
||
### 1. 路由与功能发现
|
||
|
||
项目不使用传统的 React Router，而是通过 `config/features.tsx` 中的 `FEATURES` 数组统一管理.
|
||
|
||
- 每个功能都有一个唯一的 `PageType` (如 `timestamp`, `jwt`).
|
||
- `RouterProvider` 负责维护当前的页面状态，并根据 `FEATURES` 配置渲染对应的组件.
|
||
|
||
### 2. 存储管理 (Chrome Storage)
|
||
|
||
- 统一使用 `utils/chromeStorage.ts` 及其对应的 Hook.
|
||
- 所有的存储键值必须在 `types/storage.d.ts` 的 `StorageSchema` 中定义，以确保存储的类型安全.
|
||
|
||
### 3. 消息通信 (Messaging)
|
||
|
||
- 使用 `@webext-core/messaging` 进行 Popup, Sidepanel, Background 和 Content Script 之间的通信.
|
||
- 消息协议定义在 `utils/messages.ts` 中.
|
||
|
||
### 4. 样式系统
|
||
|
||
- 基于 MUI v7 的 `Box`, `Stack`, `Paper` 等组件构建.
|
||
- 页面特定的复杂样式应在 `config/pageTheme.ts` 中统一定义，以保持视觉一致性.
|
||
|
||
## AI 代理开发准则
|
||
|
||
1. **类型安全**: 始终优先使用 TypeScript 接口和类型. 不要使用 `any`.
|
||
2. **组件化**: 新功能应拆分为 `pages/` 中的页面组件和 `components/` 中的通用组件.
|
||
3. **单元测试**: 每次修改逻辑或添加新功能后，必须在对应的 `__tests__` 目录下增加测试用例.
|
||
4. **单一事实来源**: 功能的添加、修改或删除应首先从 `config/features.tsx` 开始.
|
||
5. **跨浏览器兼容**: WXT 处理了大部分差异，但涉及原生 API (如 `chrome.cookies`) 时，请确保逻辑在 Firefox 和 Chrome 下均有效.
|
||
6. **i18n**: 目前主要使用中文 UI，但在开发时请注意提取硬编码字符串，以便未来国际化.
|
||
|
||
## 权限管理
|
||
|
||
所有新申请的浏览器权限必须同步更新至 `wxt.config.ts` 的 `manifest.permissions` 中.
|