雨霖铃
144 lines
4.5 KiB
Markdown
144 lines
4.5 KiB
Markdown
# AGENTS.md
|
||
|
||
This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
这是一个基于 WXT 框架的浏览器扩展项目，提供测试工具功能，包括时间戳转换等。
|
||
|
||
## 核心命令
|
||
|
||
### 开发相关
|
||
|
||
- `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 - 测试框架
|
||
- @testing-library/react - React 组件测试
|
||
- @testing-library/user-event v13 - 用户交互模拟（注意：v13 不支持 setup()，使用 fireEvent）
|
||
- jsdom - 浏览器环境模拟
|
||
|
||
### 依赖与准备
|
||
|
||
- `npm install` - 安装依赖
|
||
- `postinstall` 会自动运行 `wxt prepare` 准备开发环境
|
||
- `prepare` 钩子会初始化 Husky Git 钩子
|
||
|
||
## 项目架构
|
||
|
||
### 技术栈
|
||
|
||
- **框架**: WXT (Web Extension Toolkit) - 浏览器扩展开发框架
|
||
- **前端**: React 19 + TypeScript
|
||
- **UI 库**: Material UI (MUI)
|
||
- **状态管理**: React Hooks
|
||
- **路由**: React Router DOM
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
├── components/ # 可复用 UI 组件
|
||
│ ├── CopyButton.tsx # 复制按钮组件
|
||
│ ├── DatetimeToTimestamp.tsx # 日期转时间戳组件
|
||
│ ├── Navbar.tsx # 导航栏组件
|
||
│ ├── RoutePersistence.tsx # 路由持久化组件
|
||
│ ├── TimestampExecution.tsx # 时间戳执行组件
|
||
│ └── TimestampToDatetime.tsx # 时间戳转日期组件
|
||
├── entrypoints/ # 浏览器扩展入口点
|
||
│ ├── background.ts # 后台脚本（主进程）
|
||
│ ├── content.ts # 内容脚本（注入到页面）
|
||
│ └── popup/ # 扩展弹窗界面
|
||
│ ├── App.tsx # 弹窗主应用
|
||
│ ├── main.tsx # 弹窗入口
|
||
│ └── pages/ # 弹窗页面
|
||
│ ├── TestPage.tsx # 测试页面
|
||
│ └── TimestampPage.tsx # 时间戳工具页面
|
||
├── utils/ # 工具函数
|
||
│ ├── chromeStorage.ts # Chrome 存储工具
|
||
│ ├── dayjs.ts # 日期处理工具
|
||
│ └── messages.tsx # 消息通信工具
|
||
├── types/ # 类型定义
|
||
│ └── storage.d.ts # 存储相关类型
|
||
```
|
||
|
||
### 核心功能实现
|
||
|
||
#### 1. 时间戳转换工具
|
||
|
||
- 位置: `components/` 目录下的时间戳相关组件
|
||
- 依赖: dayjs 库进行日期处理
|
||
- 功能: 支持日期与时间戳的双向转换，支持多种格式
|
||
|
||
#### 2. 通信系统
|
||
|
||
- 位置: `utils/messages.tsx`
|
||
- 机制: 使用 `@webext-core/messaging` 库实现
|
||
- 通信通道: 后台脚本 ↔ 内容脚本 ↔ 弹窗
|
||
|
||
#### 3. 数据存储
|
||
|
||
- Chrome Storage API: `utils/chromeStorage.ts` (用于配置等小数据)
|
||
|
||
### 关键配置文件
|
||
|
||
#### wxt.config.ts
|
||
|
||
- 配置 WXT 框架参数
|
||
- 启用 React 模块
|
||
- 配置浏览器扩展权限
|
||
- Vite 构建配置（使用 Terser 压缩，强制 ASCII 编码）
|
||
|
||
#### manifest 权限
|
||
|
||
```typescript
|
||
permissions: [
|
||
'storage', // 存储权限
|
||
'unlimitedStorage', // 无限制存储
|
||
'clipboardWrite', // 剪贴板写入
|
||
'activeTab', // 当前标签页
|
||
'scripting', // 脚本注入
|
||
'tabs', // 标签页管理
|
||
'debugger', // 调试器
|
||
],
|
||
host_permissions: ['<all_urls>'] // 访问所有网站
|
||
```
|
||
|
||
## 开发注意事项
|
||
|
||
### 扩展入口点
|
||
|
||
- **后台脚本**: `entrypoints/background.ts` - 处理扩展生命周期和后台任务
|
||
- **内容脚本**: `entrypoints/content.ts` - 注入到网页中，处理 DOM 交互
|
||
- **弹窗**: `entrypoints/popup/main.tsx` - 用户点击扩展图标时显示
|
||
|
||
### 浏览器兼容性
|
||
|
||
- 支持 Chrome 和 Firefox 浏览器
|
||
- 使用 WXT 框架抽象浏览器差异
|
||
|
||
### 代码质量
|
||
|
||
- 使用 ESLint 进行代码检查
|
||
- Husky 用于 Git 钩子管理
|
||
- Lint-staged 确保暂存文件符合规范
|