From dec43f89da52ed4f666ff6fa964e37e2b9662c59 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=9B=A8=E9=9C=96=E9=93=83?= Date: Mon, 25 May 2026 19:21:22 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20AGENTS.md=EF=BC=8C?= =?UTF-8?q?=E5=AE=8C=E5=96=84=20CI=20=E6=AD=A5=E9=AA=A4=E5=92=8C=E5=AD=98?= =?UTF-8?q?=E5=82=A8=E9=94=AE=E5=90=8D=E6=A0=BC=E5=BC=8F=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 289a697..f28e8bd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -WXT 浏览器扩展项目 (React 19 + TypeScript)。 +WXT 浏览器扩展项目 (React 19 + TypeScript)。提供时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、Markdown 等测试效率工具。 ## 核心命令 @@ -22,14 +22,17 @@ npm run test:coverage # 带覆盖率的测试 ## 验证流程 -CI 执行顺序: `setup → lint/typecheck/test(并行) → build` (build 依赖前三者)。 +CI 步骤（严格顺序，任一步骤失败则停止并标记 CI 失败）： -Pre-commit hook (`.husky/pre-commit` 调用 `lint-staged`): +1. `setup`（安装依赖、`wxt prepare`） +2. 并行运行 `lint`、`typecheck`、`test`（三者全部通过才继续） +3. `build`（仅当步骤 2 全部成功时执行） -- 代码文件 (`*.{ts,tsx,js,jsx,mjs}`): `eslint --fix --max-warnings=0 --no-warn-ignored` → `prettier --write` -- 其他文件 (`*.{json,css,scss,md}`): `prettier --write` +Pre-commit hook（`.husky/pre-commit` 调用 `lint-staged`，任一步骤返回非零则终止提交）： -提交前确保 `lint` 和 `typecheck` 通过。 +1. 代码文件 (`*.{ts,tsx,js,jsx,mjs}`)：运行 `eslint --fix --max-warnings=0 --no-warn-ignored`；若失败则终止并报告错误 +2. 同一代码文件：运行 `prettier --write` +3. 其他文件 (`*.{json,css,scss,md}`)：运行 `prettier --write` ## WXT 生成文件 @@ -54,10 +57,12 @@ i18n/locales/{zh,en}/ # 国际化资源 (common.json, features.json 及各功 ## 关键架构决策 **路由**: 不使用 React Router。通过 `config/features.tsx` 的 `FEATURES` 数组管理，`RouterProvider` 根据 `PageType` -渲染对应组件。支持三种渲染模式: popup / sidepanel / tab。每种模式有独立的路由和可见页面配置。 +渲染对应组件。支持三种渲染模式：popup（弹窗）、sidepanel（侧边栏）和 browser-tab（浏览器新标签页，通过 `open_in_tab` 打开）。 +每种模式有独立的路由和可见页面配置。 -**存储**: 所有 Chrome Storage 键必须在 `types/storage.d.ts` 的 `StorageSchema` 中定义。使用 `utils/chromeStorage.ts` 及其 -Hook。Router 同时使用 `chrome.storage.local` 和 `localStorage` 做快照以消除首屏闪烁。 +**存储**: 所有 Chrome Storage 键必须在 `types/storage.d.ts` 的 `StorageSchema` 中定义，键名使用 kebab-case 格式（如 `app/currentRoute`）。 +使用 `utils/chromeStorage.ts` 及其 Hook。Router 同时使用 `chrome.storage.local` 和 `localStorage` 做快照以消除首屏闪烁。 +修改 StorageSchema 时，必须在 `utils/chromeStorage.ts` 添加版本迁移函数，并在测试中覆盖迁移场景。 **通信**: 使用 `@webext-core/messaging`，协议定义在 `utils/messages.ts`。 @@ -89,6 +94,7 @@ Hook。Router 同时使用 `chrome.storage.local` 和 `localStorage` 做快照 - `i18n/locales/{zh,en}/{功能名}.json` - 各功能独立翻译（如 timestamp.json, storageCleaner.json 等） - 添加新翻译: 编辑 `i18n/locales/{zh,en}/{common,features}.json` 及对应功能独立 JSON - 使用 `useLazyTranslation` hook 加载功能独立翻译，返回 `ns:key` 格式 +- 回退策略: 当翻译 key 在目标语言缺失时，回退到默认语言 `zh`；若默认语言也缺失，返回占位格式 `namespace:key` 并在开发模式下记录 warning ## 新功能开发清单