LingandRX
689c3faf16
* feat: 添加 contextMenus 权限和消息类型定义 * feat: 实现右键菜单注册与点击分流逻辑 - 新增 utils/contextMenu.ts 封装菜单配置和解析函数 - 在 background.ts 监听 onInstalled 初始化菜单 - 实现 contextMenus.onClicked 点击事件处理 - 分流逻辑：优先发送到侧边栏，否则打开 options 页面 - 添加 contextMenu 单元测试（15个测试用例） - 更新 vitest.setup.ts 添加 contextMenus mock * feat: 实现 Content Script 原位轻量提示 UI - 新增 uiPopover.ts 实现原位弹窗组件（深色主题、自动定位、自动隐藏） - 新增 contextMenuHandler.ts 处理右键菜单消息 - 时间戳转换：在点击位置显示转换结果 - 文本统计：显示字符/单词/行数/字节统计 - 更新 messageHandler.ts 挂载右键菜单消息监听 * feat: 实现 React 页面层右键菜单数据联动 - 新增 useContextMenuData Hook 处理右键菜单数据传递 - 重构 Jwt/Base64Converter/TextStatistics/QrCode 页面接收右键数据 - RouterProvider 支持从 URL 参数解析右键菜单数据 - 添加 contextMenu/pendingData 存储键到 StorageSchema - 添加 useContextMenuData 单元测试（12个测试用例） * test: 添加 background 单元测试与边界情况处理 - 新增 entrypoints/__tests__/background.test.ts (12个测试用例) - 超长文本截断限制 (>10000字符) - Base64 内联图片拦截并返回错误提示 - 更新 parseContextMenuClick 返回 ParseResult 格式 - 更新测试匹配新的返回格式 - lint/typecheck/test 全部通过 (579个测试) * fix: 修复右键菜单跳转到错误页面的问题 - 将 options 页面路径从 '/entrypoints/options/index.html' 修正为 '/options.html' - WXT 构建后 entrypoints/options/index.html 会输出为根目录的 options.html * fix: 修复右键菜单跳转目标为 popup 页面 - 将 fallback 页面从 options.html 改为 popup.html - popup 页面使用 RouterProvider，可以正确处理 URL 参数并跳转到对应功能页面 - options 页面是独立设置页，不支持 URL 参数路由 * fix: 使用 openPopup() 替代 tabs.create() 打开弹窗 - background.ts: 使用 browser.action.openPopup() 打开 popup 弹窗 - 先保存数据到 storage，然后打开 popup - RouterProvider.tsx: 初始化时检查 storage 中的 pendingData 并跳转到对应页面 - 移除之前错误的 tabs.create() 方式 * fix: 修复右键菜单数据未传递到目标页面的问题 - RouterProvider 不再提前清除 pendingData - 让目标页面的 useContextMenuData 来消费和清除数据 - 这样确保 TextStatistics 等页面能正确接收选中的文本 * fix: 修复 popup 已打开时右键菜单不生效的问题 - 在 RouterProvider 中添加对 contextMenu/pendingData 的 storage 变化监听 - 当 pendingData 变化时，自动跳转到对应功能页面 - 解决了 openPopup() 只聚焦已有窗口而不触发重新挂载的问题 * feat: 支持右键菜单图片二维码识别 - 在 qrCodeParser.ts 中添加 parseQrCodeFromUrl 函数，支持从图片 URL 解析二维码 - 在 QrCodeToUrlSection 中使用 useContextMenuData 接收右键菜单传递的图片 URL - 自动下载图片并解析二维码，显示解析结果 * refactor: 暂时移除图片二维码识别功能 - 删除 qrCode-image 右键菜单配置 - 删除 parseQrCodeFromUrl 函数 - 删除 QrCodeToUrlSection 中的 useContextMenuData 相关代码 - 更新相关测试用例 * feat: 支持右键菜单时间戳转换 - 在 useTimestampConverter 中添加 useContextMenuData hook - 智能识别输入是时间戳还是日期时间字符串 - 自动切换到对应模式并执行转换 - 时间戳自动识别秒/毫秒单位 * fix: 修复右键菜单功能的多个逻辑漏洞 1. 修复时区硬编码问题 - 使用用户选择的时区而非固定 Asia/Shanghai 2. 修复 openPopup() 失败后数据残留 - 失败时清除 storage 中的待处理数据 3. 统一数据过期时间常量 - 导出 CONTEXT_MENU_DATA_EXPIRY_MS 并统一使用 4. 修复 featureKey 类型断言不安全 - 使用映射表处理非常规菜单 ID * refactor(qrcode): 提取独立组件并添加单元测试 - 创建 pages/QrCode/types.ts 定义状态类型接口 - 提取 QrCodePreview 组件用于二维码预览和操作 - 提取 ImageUploader 组件封装图片上传、拖拽、粘贴逻辑 - 重构 UrlToQrCodeSection 状态提升到父组件 - 重构 QrCodeToUrlSection 通过回调传递解析结果 - 更新主页面 index.tsx 集中管理所有状态 - 为 QrCodePreview 和 ImageUploader 添加单元测试 (23 个用例) * refactor(qrcode): 引入通用组件并重构双栏布局 - 引入 SwitchButtonGroup 用于模式切换 - 引入 TextInputArea 用于文本输入和结果展示 - 使用 MUI Grid 构建响应式双栏布局 - 实现 generate/parse 模式下的左右面板内容切换 - 修复 iconColor 颜色格式错误，使用 qrCodePageStyles.primaryColor * refactor(qrcode): 国际化补充、质量保障与错误处理优化 - 补充 i18n 翻译键（generateMode, parseMode, pasteHint 等） - 创建 useDebounce Hook 实现输入防抖 (200ms) - 使用 useRef 解决 useEffect 无限循环问题 - 编写 pages/QrCode 单元测试 (7 个用例) - 优化右键菜单错误处理，改进用户提示 - 运行 603 个测试全部通过 * refactor(qrcode): 组件化重构，采用 Context + Hook 模式 - 创建 QrCodeContext 和 QrCodeProvider 管理共享状态 - 提取 useQrCode Hook 封装所有状态和业务逻辑 - 创建 GeneratePanel 组件处理二维码生成模式 - 创建 ParsePanel 组件处理二维码解析模式 - 简化 index.tsx 为容器组件 (340行 → 47行) - 删除未使用的旧组件文件 (QrCodeToUrlSection, UrlToQrCodeSection) - 清理 types.ts 中未使用的类型定义 - 603 个测试全部通过 * fix(qrcode): 固定二维码预览图片尺寸，避免布局抖动 - 设置 QR_PREVIEW_IMAGE 固定尺寸 250x250 - 与 QRious 生成的二维码大小保持一致 - 解决输入内容变化时预览窗口大小跳动问题 * fix(qrcode): 修复切换 tab 后二维码图片失效问题 - 移除 ImageUploader 组件卸载时的预览 URL 释放逻辑 - 在 useQrCode hook 中统一管理预览 URL 生命周期 - 创建新预览 URL 前释放旧的，避免内存泄漏 * fix(qrcode): 固定图片上传区域高度，避免布局抖动 - 将 DROPZONE 的 minHeight: 200 改为 height: 250 - 与二维码预览图片高度保持一致 - 解决上传图片时 div 高度变化问题 * refactor(qrCode): 优化二维码解析功能 - 将'二维码转 URL'改为'二维码转文本' - 将解析结果的文本预览框的 placeholder 置为空 - 去除手动解析二维码功能，只保留自动解析 * fix(pageHeader): 使用 MUI 主题色替代硬编码颜色，支持暗色模式 * feat(pageHeader): popup 模式下隐藏 PageHeader 组件 * fix(i18n): 统一使用 useLazyTranslation 避免翻译 key 闪烁 * perf: 配置 manualChunks 拆分 vendor chunk，优化打包体积 - 使用 Vite 插件 manualChunksForHtmlOnly 仅对 HTML 多入口构建生效 - 跳过 background/content-script 的 IIFE 构建（不支持 manualChunks） - 拆分 vendor-react (193KB)、vendor-mui (326KB)、vendor-i18n (55KB) - 按需加载 vendor-qr (78KB)、vendor-dnd (45KB)、vendor-markdown (41KB) - PageErrorBoundary chunk 从 454KB 降至 36KB * chore: upgrade wxt to v0.20.26 and @wxt-dev/module-react to v1.2.2 * chore: upgrade low-risk dependencies - react: 19.2.3 → 19.2.6 - react-dom: 19.2.3 → 19.2.6 - dayjs: 1.11.19 → 1.11.20 - marked: 18.0.3 → 18.0.4 - prettier: 3.8.1 → 3.8.3 - terser: 5.46.0 → 5.47.1 - i18next: 26.0.8 → 26.2.0 - react-i18next: 17.0.6 → 17.0.8 - globals: 17.2.0 → 17.6.0 - eslint-plugin-react-hooks: 7.0.1 → 7.1.1 - @typescript-eslint/*: 8.54.0 → 8.59.4 - typescript-eslint: 8.54.0 → 8.59.4 - @testing-library/jest-dom: 6.6.0 → 6.9.1 - @testing-library/react: 16.0.0 → 16.3.2 - @testing-library/user-event: 14.5.2 → 14.6.1 - @testing-library/dom: added as peer dependency - @types/react: 19.2.7 → 19.2.15 - @types/chrome: 0.1.36 → 0.1.42 - @types/webextension-polyfill: 0.12.4 → 0.12.5 * chore: upgrade medium-risk dependencies - lint-staged: 16.2.7 → 17.0.5 - jsdom: 25.0.0 → 29.1.1 - @vitejs/plugin-react: 4.3.4 → 6.0.2 - vitest: 2.0.0 → 4.1.7 - @vitest/coverage-v8: upgraded to match vitest - @webext-core/messaging: 2.3.0 → 3.0.1 - eslint: 9.39.2 → 10.4.0 - @eslint/js: added as new dependency - @types/marked: removed (marked now provides its own types) Fixes: - Fix ref update during render in useQrCode.ts - Fix ref update during render in useStorageCleaner.ts - Add error cause in jwt.ts decode function - Add type assertion for mock functions in htmlToMarkdown.test.ts * chore(deps): 降级 eslint 版本并移除 @eslint/js * docs: 精简 AGENTS.md，聚焦高信号信息 * test: 修复测试中的 act() 警告和 clipboard mock 问题 - TextInputArea: 使用 userEvent 替代 fireEvent，用 vi.spyOn 替代 Object.assign mock clipboard - ImageMode/FileMode: 添加 waitForStorageReady() 等待 useStorageState 异步初始化
99 lines
3.2 KiB
Markdown
99 lines
3.2 KiB
Markdown
# AGENTS.md
|
|
|
|
WXT 浏览器扩展项目 (React 19 + TypeScript + MUI v7)。
|
|
|
|
## 核心命令
|
|
|
|
```bash
|
|
npm run dev # Chrome 开发模式 (HMR)
|
|
npm run dev:firefox # Firefox 开发模式
|
|
npm run build # Chrome 生产构建
|
|
npm run build:firefox # Firefox 生产构建
|
|
npm run lint # ESLint (--max-warnings=0)
|
|
npm run typecheck # tsc --noEmit
|
|
npm run test # vitest run (单次执行)
|
|
npm run test:watch # vitest 监视模式
|
|
npm run test:coverage # 带覆盖率的测试
|
|
```
|
|
|
|
运行单个测试: `npx vitest run path/to/file.test.ts`
|
|
|
|
## 验证流程
|
|
|
|
CI 执行顺序: `lint → typecheck → test → build` (build 依赖前三者)。
|
|
|
|
Pre-commit hook (lint-staged) 顺序:
|
|
|
|
1. `prettier --write`
|
|
2. `eslint --fix --max-warnings=0`
|
|
3. `tsc --noEmit`
|
|
|
|
提交前确保三者通过。
|
|
|
|
## 项目结构
|
|
|
|
```
|
|
config/features.tsx # 功能定义（路由 + 元数据的单一事实来源）
|
|
config/pageTheme.ts # 页面级主题常量
|
|
config/theme.ts # MUI 全局主题
|
|
entrypoints/ # 扩展入口点 (popup/, options/, sidepanel/, background.ts, content.ts)
|
|
pages/ # 功能页面组件 (懒加载)
|
|
components/ # 可复用 UI 组件
|
|
providers/ # React Context (Router, Theme 等)
|
|
utils/ # 工具函数与服务抽象
|
|
types/ # TypeScript 类型声明
|
|
i18n/locales/{zh,en}/ # 国际化资源 (common.json, features.json)
|
|
```
|
|
|
|
## 关键架构决策
|
|
|
|
**路由**: 不使用 React Router。通过 `config/features.tsx` 的 `FEATURES` 数组管理，`RouterProvider` 根据 `PageType` 渲染对应组件。
|
|
|
|
**存储**: 所有 Chrome Storage 键必须在 `types/storage.d.ts` 的 `StorageSchema` 中定义。使用 `utils/chromeStorage.ts` 及其 Hook。
|
|
|
|
**通信**: 使用 `@webext-core/messaging`，协议定义在 `utils/messages.ts`。
|
|
|
|
**路径别名**: `@/` 映射到项目根目录 (已在 tsconfig 和 vitest.config 中配置)。
|
|
|
|
## 测试环境
|
|
|
|
- 环境: jsdom
|
|
- 全局变量: `vitest/globals` (describe, it, expect 等无需导入)
|
|
- Setup 文件: `vitest.setup.ts` 自动 mock:
|
|
- `chrome.*` API (storage, tabs, runtime, cookies 等)
|
|
- `react-i18next` (返回 key 作为翻译)
|
|
- `window.matchMedia`
|
|
- 测试文件命名: `__tests__/*.test.{ts,tsx}` 或 `*.test.{ts,tsx}`
|
|
|
|
## i18n
|
|
|
|
- 命名空间: `common` (默认), `features`
|
|
- 翻译键格式: `namespace:key` (如 `features:timestamp.title`)
|
|
- 语言: `zh` (默认), `en`
|
|
- 添加新翻译: 编辑 `i18n/locales/{zh,en}/{common,features}.json`
|
|
|
|
## 新功能开发清单
|
|
|
|
1. 在 `types/storage.d.ts` 添加 `PageType` 联合类型
|
|
2. 在 `config/features.tsx` 的 `FEATURES` 数组添加配置
|
|
3. 在 `pages/` 创建页面组件 (懒加载)
|
|
4. 在 `i18n/locales/{zh,en}/features.json` 添加翻译
|
|
5. 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
|
|
6. 添加对应的单元测试
|
|
|
|
## 代码规范
|
|
|
|
- 禁止使用 `any` (测试文件除外)
|
|
- 未使用变量/参数: 使用 `_` 前缀 (如 `_unused`)
|
|
- 样式: 复杂页面样式放 `config/pageTheme.ts`，简单样式用 MUI `sx` prop
|
|
- 格式: Prettier (100 字符宽, 单引号, 尾逗号)
|
|
|
|
## 技术栈版本
|
|
|
|
- WXT: ^0.20.26
|
|
- React: ^19.2.6
|
|
- MUI: ^7.3.8
|
|
- TypeScript: ^5.9.3
|
|
- Vitest: ^4.1.7
|
|
- i18next: ^26.2.0
|