docs: 添加项目文档(copilot-instructions、编码规范、各目录 README)

- 新增 .github/copilot-instructions.md:Copilot 指令文件,涵盖构建命令、CI 流水线、项目架构、关键规范
- 新增 .github/CODING_STANDARDS.md:完整的代码编写规范文档(TypeScript、React、样式、错误处理、命名、测试、Hook、i18n、存储等 12 个章节)
- 新增 11 个目录的 README.md:components、components/ui、config、entrypoints、i18n、lib、pages、providers、public、src、types、utils
- 更新 AGENTS.md:补充页面组件模式说明和 components/ui 目录

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
雨霖铃
2026-05-27 11:54:21 +08:00
parent 0f3b6c4cd8
commit c61b599287
15 changed files with 1575 additions and 14 deletions
+31 -14
View File
@@ -47,6 +47,7 @@ config/features.tsx # 功能定义(路由 + 元数据的单一事实来源
entrypoints/ # 扩展入口点 (popup/, options/, sidepanel/, background.ts, content.ts)
pages/ # 功能页面组件 (懒加载)
components/ # 可复用 UI 组件
components/ui/ # shadcn/ui 基础组件 (button, dialog, select 等)
providers/ # React Context (Router, Theme 等)
hooks/ # 自定义 React Hooks
utils/ # 工具函数与服务抽象
@@ -54,11 +55,26 @@ types/ # TypeScript 类型声明
i18n/locales/{zh,en}/ # 国际化资源 (common.json, features.json 及各功能独立 JSON)
```
### 页面组件模式
典型功能页面遵循 **UI + Hook 分离** 模式:
```
pages/FeatureName/
├── index.tsx # 页面 UI(纯展示,使用 shadcn/ui 组件)
├── useFeatureName.ts # 业务逻辑 Hook(状态管理 + 转换逻辑)
└── constants.ts # 常量定义
```
- 页面组件调用 `useLazyTranslation('featureName')` 获取翻译函数
- Hook 负责所有状态管理和业务逻辑,通过返回值暴露给页面
- 子组件可进一步拆分(如 `LiveClock.tsx``ResultView.tsx`
## 关键架构决策
**路由**: 不使用 React Router。通过 `config/features.tsx``FEATURES` 数组管理,`RouterProvider` 根据 `PageType`
渲染对应组件。支持三种渲染模式:popup(弹窗)、sidepanel(侧边栏)和 browser-tab(浏览器新标签页,通过 `open_in_tab` 打开)。
每种模式有独立的路由和可见页面配置。
每种模式有独立的路由和可见页面配置`app/popupRoute``app/sidepanelRoute``app/tabRoute` 等)
**存储**: 所有 Chrome Storage 键必须在 `types/storage.d.ts``StorageSchema` 中定义,键名使用 kebab-case 格式(如 `app/currentRoute`)。
使用 `utils/chromeStorage.ts` 及其 Hook。Router 同时使用 `chrome.storage.local``localStorage` 做快照以消除首屏闪烁。
@@ -70,6 +86,8 @@ i18n/locales/{zh,en}/ # 国际化资源 (common.json, features.json 及各功
**浏览器兼容**: 优先使用 `wxt/browser` 导出的 `browser` 对象,而非原生 `chrome` API。
**代码分割**: `wxt.config.ts` 通过 `manualChunksForHtmlOnly()` 自动分组依赖(vendor-react、vendor-i18n、vendor-qr 等),无需手动配置。
## 测试环境
- 环境: jsdom
@@ -99,8 +117,11 @@ i18n/locales/{zh,en}/ # 国际化资源 (common.json, features.json 及各功
## 新功能开发清单
1.`types/storage.d.ts` 添加 `PageType` 联合类型
2.`config/features.tsx``FEATURES` 数组添加配置
3.`pages/` 创建页面组件 (懒加载)
2.`config/features.tsx``FEATURES` 数组添加配置(指定 key、翻译键、图标、三种渲染模式的组件)
3.`pages/` 创建页面组件 (懒加载)
- `index.tsx` — UI 组件,使用 `useLazyTranslation` 获取翻译
- `useFeatureName.ts` — 业务逻辑 Hook
- `constants.ts` — 常量(可选)
4.`i18n/locales/{zh,en}/features.json` 添加翻译(复杂功能可新建独立 JSON)
5. 如需新权限,更新 `wxt.config.ts``manifest.permissions`
6. 添加对应的单元测试
@@ -115,15 +136,11 @@ i18n/locales/{zh,en}/ # 国际化资源 (common.json, features.json 及各功
- 格式: Prettier (`.prettierrc`: 100 字符宽, 单引号, 尾逗号 all, LF 换行)
- ESLint 使用 `typescript-eslint``projectService: true`(无需手动维护 project 路径)
## 技术栈版本
## 关键外部库(非显而易见的)
- WXT: ^0.20.26
- React: ^19.2.6
- Tailwind CSS: ^3.4.19
- shadcn/ui (基于 Radix UI + class-variance-authority)
- TypeScript: ^5.9.3
- Vitest: ^4.1.7
- i18next: ^26.2.0
- @dnd-kit (拖拽排序)
- marked (Markdown 解析)
- qrious + qr-scanner (二维码生成与解析)
- `@webext-core/messaging` — 扩展消息通信
- `@dnd-kit` — 拖拽排序(用于页面顺序管理)
- `marked` — Markdown 解析
- `qrious` + `qr-scanner` — 二维码生成与解析
- `dayjs` — 日期处理(时间戳转换)
- `sonner` — Toast 通知(替代传统 snackbar