refactor: update docs with new features, revised tech stack, and CI changes
This commit is contained in:
雨霖铃
@@ -1,6 +1,6 @@
|
||||
# AGENTS.md
|
||||
|
||||
WXT 浏览器扩展项目 (React 19 + TypeScript + MUI v7)。
|
||||
WXT 浏览器扩展项目 (React 19 + TypeScript)。
|
||||
|
||||
## 核心命令
|
||||
|
||||
@@ -9,6 +9,8 @@ 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 # tsc --noEmit
|
||||
npm run test # vitest run (单次执行)
|
||||
@@ -20,15 +22,23 @@ npm run test:coverage # 带覆盖率的测试
|
||||
|
||||
## 验证流程
|
||||
|
||||
CI 执行顺序: `lint → typecheck → test → build` (build 依赖前三者)。
|
||||
CI 执行顺序: `setup → lint/typecheck/test(并行) → build` (build 依赖前三者)。
|
||||
|
||||
Pre-commit hook (lint-staged) 顺序:
|
||||
Pre-commit hook (`.husky/pre-commit` 调用 `lint-staged`):
|
||||
|
||||
1. `prettier --write`
|
||||
2. `eslint --fix --max-warnings=0`
|
||||
3. `tsc --noEmit`
|
||||
- 代码文件 (`*.{ts,tsx,js,jsx,mjs}`): `eslint --fix --max-warnings=0 --no-warn-ignored` → `prettier --write`
|
||||
- 其他文件 (`*.{json,css,scss,md}`): `prettier --write`
|
||||
|
||||
提交前确保三者通过。
|
||||
提交前确保 `lint` 和 `typecheck` 通过。
|
||||
|
||||
> **注意**: Release 工作流 (`.github/workflows/release.yml`) 存在脚本名错误，typecheck 步骤使用了不存在的
|
||||
> `npm run compile`，正确命令应为 `npm run typecheck`。
|
||||
|
||||
## WXT 生成文件
|
||||
|
||||
- `.wxt/` 目录由 `postinstall` 自动执行 `wxt prepare` 生成，包含 TypeScript 类型声明和扩展的 tsconfig。
|
||||
- 生产构建输出到 `.output/` 目录。
|
||||
- `tsconfig.json` 继承自 `./.wxt/tsconfig.json`。
|
||||
|
||||
## 项目结构
|
||||
|
||||
@@ -40,28 +50,34 @@ entrypoints/ # 扩展入口点 (popup/, options/, sidepanel/, backgrou
|
||||
pages/ # 功能页面组件 (懒加载)
|
||||
components/ # 可复用 UI 组件
|
||||
providers/ # React Context (Router, Theme 等)
|
||||
hooks/ # 自定义 React Hooks
|
||||
utils/ # 工具函数与服务抽象
|
||||
types/ # TypeScript 类型声明
|
||||
i18n/locales/{zh,en}/ # 国际化资源 (common.json, features.json)
|
||||
i18n/locales/{zh,en}/ # 国际化资源 (common.json, features.json 及各功能独立 JSON)
|
||||
```
|
||||
|
||||
## 关键架构决策
|
||||
|
||||
**路由**: 不使用 React Router。通过 `config/features.tsx` 的 `FEATURES` 数组管理，`RouterProvider` 根据 `PageType` 渲染对应组件。
|
||||
**路由**: 不使用 React Router。通过 `config/features.tsx` 的 `FEATURES` 数组管理，`RouterProvider` 根据 `PageType`
|
||||
渲染对应组件。支持三种渲染模式: popup / sidepanel / tab。
|
||||
|
||||
**存储**: 所有 Chrome Storage 键必须在 `types/storage.d.ts` 的 `StorageSchema` 中定义。使用 `utils/chromeStorage.ts` 及其 Hook。
|
||||
**存储**: 所有 Chrome Storage 键必须在 `types/storage.d.ts` 的 `StorageSchema` 中定义。使用 `utils/chromeStorage.ts` 及其
|
||||
Hook。Router 同时使用 `chrome.storage.local` 和 `localStorage` 做快照以消除首屏闪烁。
|
||||
|
||||
**通信**: 使用 `@webext-core/messaging`，协议定义在 `utils/messages.ts`。
|
||||
|
||||
**路径别名**: `@/` 映射到项目根目录 (已在 tsconfig 和 vitest.config 中配置)。
|
||||
|
||||
**浏览器兼容**: 优先使用 `wxt/browser` 导出的 `browser` 对象，而非原生 `chrome` API。
|
||||
|
||||
## 测试环境
|
||||
|
||||
- 环境: jsdom
|
||||
- 全局变量: `vitest/globals` (describe, it, expect 等无需导入)
|
||||
- Setup 文件: `vitest.setup.ts` 自动 mock:
|
||||
- `chrome.*` API (storage, tabs, runtime, cookies 等)
|
||||
- `chrome.*` / `browser.*` API (storage, tabs, runtime, cookies 等)
|
||||
- `react-i18next` (返回 key 作为翻译)
|
||||
- `@/utils/useLazyTranslation` (返回 `ns:key` 格式翻译)
|
||||
- `window.matchMedia`
|
||||
- 测试文件命名: `__tests__/*.test.{ts,tsx}` 或 `*.test.{ts,tsx}`
|
||||
|
||||
@@ -70,14 +86,14 @@ i18n/locales/{zh,en}/ # 国际化资源 (common.json, features.json)
|
||||
- 命名空间: `common` (默认), `features`
|
||||
- 翻译键格式: `namespace:key` (如 `features:timestamp.title`)
|
||||
- 语言: `zh` (默认), `en`
|
||||
- 添加新翻译: 编辑 `i18n/locales/{zh,en}/{common,features}.json`
|
||||
- 添加新翻译: 编辑 `i18n/locales/{zh,en}/{common,features}.json` 及对应功能独立 JSON
|
||||
|
||||
## 新功能开发清单
|
||||
|
||||
1. 在 `types/storage.d.ts` 添加 `PageType` 联合类型
|
||||
2. 在 `config/features.tsx` 的 `FEATURES` 数组添加配置
|
||||
3. 在 `pages/` 创建页面组件 (懒加载)
|
||||
4. 在 `i18n/locales/{zh,en}/features.json` 添加翻译
|
||||
4. 在 `i18n/locales/{zh,en}/features.json` 添加翻译（复杂功能可新建独立 JSON）
|
||||
5. 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
|
||||
6. 添加对应的单元测试
|
||||
|
||||
@@ -86,7 +102,8 @@ i18n/locales/{zh,en}/ # 国际化资源 (common.json, features.json)
|
||||
- 禁止使用 `any` (测试文件除外)
|
||||
- 未使用变量/参数: 使用 `_` 前缀 (如 `_unused`)
|
||||
- 样式: 复杂页面样式放 `config/pageTheme.ts`，简单样式用 MUI `sx` prop
|
||||
- 格式: Prettier (100 字符宽, 单引号, 尾逗号)
|
||||
- 格式: Prettier (`.prettierrc`: 100 字符宽, 单引号, 尾逗号 all, LF 换行)
|
||||
- ESLint 使用 `typescript-eslint` 的 `projectService: true`（无需手动维护 project 路径）
|
||||
|
||||
## 技术栈版本
|
||||
|
||||
|
||||
@@ -46,13 +46,30 @@
|
||||
- **生成器**: 将当前 URL 或自定义文本快速转换为二维码，支持下载.
|
||||
- **解析器**: 支持通过上传图片或粘贴图片来解析二维码内容.
|
||||
|
||||
### 🔄 JSON 工具
|
||||
|
||||
- **差异比较**: 对比两段 JSON 数据，高亮展示差异.
|
||||
- **格式化**: 支持 JSON 美化、压缩、转 YAML / TOML.
|
||||
|
||||
### 🧰 Base64 转换器
|
||||
|
||||
- **文本编解码**: 支持文本内容的 Base64 编码与解码.
|
||||
- **文件转换**: 支持文件与 Base64 字符串互转.
|
||||
- **图像预览**: 支持图片 Base64 编码与实时预览.
|
||||
|
||||
### 📝 Markdown ↔ HTML 转换
|
||||
|
||||
- **Markdown 转 HTML**: 实时预览 Markdown 渲染结果，支持导出 HTML 源码.
|
||||
- **HTML 转 Markdown**: 将 HTML 内容转换为 Markdown 格式.
|
||||
|
||||
## 技术栈
|
||||
|
||||
- **框架**: [WXT (Web Extension Toolkit)](https://wxt.dev/)
|
||||
- **前端**: React 19 + TypeScript
|
||||
- **UI 组件**: Material UI (MUI) @7.x
|
||||
- **样式**: Emotion (Styled Components)
|
||||
- **UI 组件**: Radix UI (无头组件库)
|
||||
- **样式**: Tailwind CSS + class-variance-authority
|
||||
- **日期处理**: dayjs (集成 UTC 和 Timezone 插件)
|
||||
- **国际化**: i18next + react-i18next
|
||||
- **通信**: @webext-core/messaging
|
||||
- **存储**: Chrome Storage API (类型安全封装)
|
||||
- **解析引擎**: qr-scanner (二维码解析), qrious (二维码生成)
|
||||
@@ -72,10 +89,13 @@
|
||||
│ ├── background.ts # 后台 Service Worker
|
||||
│ └── content.ts # 网页注入脚本
|
||||
├── pages/ # 各功能模块的页面组件
|
||||
├── providers/ # 全局状态提供者 (Router, Snackbar 等)
|
||||
├── types/ # TypeScript 类型声明
|
||||
├── providers/ # 全局状态提供者 (Router, Theme 等)
|
||||
├── hooks/ # 自定义 React Hooks
|
||||
├── utils/ # 工具函数与服务抽象
|
||||
├── public/ # 静态资源 (图标、 manifest 资源等)
|
||||
├── types/ # TypeScript 类型声明
|
||||
├── lib/ # 通用工具函数
|
||||
├── i18n/ # 国际化资源
|
||||
├── public/ # 静态资源 (图标、manifest 资源等)
|
||||
├── wxt.config.ts # WXT 框架核心配置
|
||||
└── package.json # 项目元数据与依赖管理
|
||||
```
|
||||
@@ -89,15 +109,20 @@
|
||||
|
||||
### 常用命令
|
||||
|
||||
| 命令 | 说明 |
|
||||
| ----------------------- | -------------------------------- |
|
||||
| `npm run dev` | 启动 Chrome 开发模式（支持 HMR） |
|
||||
| `npm run dev:firefox` | 启动 Firefox 开发模式 |
|
||||
| `npm run build` | 构建 Chrome 生产版本 |
|
||||
| `npm run compile` | 执行 TypeScript 类型检查 |
|
||||
| `npm run lint` | 执行 ESLint 代码规范检查 |
|
||||
| `npm run test` | 运行单元测试 |
|
||||
| `npm run test:coverage` | 生成测试覆盖率报告 |
|
||||
| 命令 | 说明 |
|
||||
| ----------------------- | --------------------------------- |
|
||||
| `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 typecheck` | 执行 TypeScript 类型检查 |
|
||||
| `npm run lint` | 执行 ESLint 代码规范检查 |
|
||||
| `npm run test` | 运行单元测试 |
|
||||
| `npm run test:coverage` | 生成测试覆盖率报告 |
|
||||
|
||||
运行单个测试: `npx vitest run path/to/file.test.ts`
|
||||
|
||||
### 自动化流程
|
||||
|
||||
|
||||
Reference in New Issue
Block a user