feat: complete testing-tool browser extension with timestamp converter and storage cleaner

2025-11-11 01:07:43 +08:00
commit f4c2f6d374
42 changed files with 13902 additions and 0 deletions
@@ -0,0 +1,72 @@
+# Testing Tools 项目指南
+
+本文件为 Gemini CLI 提供关于 **Testing Tools** 浏览器扩展项目的架构说明、开发规范和技术上下文。
+
+## 1. 项目概览
+
+- **名称**: Testing Tools
+- **核心框架**: [WXT (Web Extension Toolkit)](https://wxt.dev/)
+- **前端技术栈**: React 19 (Functional Components + Hooks) + TypeScript
+- **UI 组件库**: Material UI (MUI) 7.x (深度定制 `sx` 属性)
+- **日期处理**: dayjs (配合 timezone 和 utc 插件)
+- **主要功能**: 提供时间戳转换、日期格式化等开发辅助工具。
+
+## 2. 项目结构
+
+```text
+├── .github/              # CI/CD 工作流
+├── .husky/               # Git Hooks (pre-commit linting)
+├── assets/               # 静态资源 (SVG 等)
+├── components/           # 复用 UI 组件
+├── entrypoints/          # 浏览器扩展入口点
+│   ├── background.ts     # 后台 Service Worker 逻辑
+│   ├── content.ts        # 内容脚本注入逻辑
+│   ├── popup/            # 扩展弹出层 (主要功能区)
+│   └── options/          # 扩展选项页面
+├── types/                # 全局 TypeScript 类型声明
+├── utils/                # 工具类 (存储、消息通信、日期处理封装)
+├── wxt.config.ts         # WXT 框架与 Manifest 配置
+└── package.json          # 依赖管理与脚本
+```
+
+## 3. 开发规范与风格约定
+
+### 3.1 UI 设计语言
+
+- **极简主义 (Minimalist)**: 参考 Vercel 和 Apple 的设计语言。
+- **MUI 定制**:
+  - 严禁使用 MUI 默认的粗犷边框和深重阴影。
+  - 必须通过 `sx` 属性进行深度样式定制，去除 `notchedOutline`。
+  - 偏好使用 `grey.50` 背景区分层级，使用 `borderRadius: 4` (大圆角)。
+  - 交互反馈：禁用波纹效果 (`disableRipple`)，移除默认阴影 (`disableElevation`)。
+- **布局**: 优先使用 `Stack` 和 `Box` 进行布局，确保自上而下的操作流顺畅。
+
+### 3.2 技术选型惯例
+
+- **日期转换**: 必须通过 `utils/dayjs.ts` 导出的实例进行，确保时区处理一致。
+- **状态管理**: 优先使用 React 原生 `useState` 和 `useMemo`。
+- **存储**: 使用 `utils/chromeStorage.ts` 封装的类型安全接口。
+- **通信**: 使用 `@webext-core/messaging` 进行 background 和 popup 之间的消息传递。
+
+## 4. 关键指令
+
+### 4.1 开发与调试
+
+- `npm run dev`: 启动 Chrome 扩展开发模式。
+- `npm run dev:firefox`: 启动 Firefox 扩展开发模式。
+
+### 4.2 构建与检查
+
+- `npm run build`: 构建生产版本。
+- `npm run compile`: TypeScript 类型检查。
+- `npm run lint`: ESLint 代码风格检查。
+
+## 5. 权限与清单 (Manifest)
+
+- **核心权限**: `storage`, `unlimitedStorage`, `clipboardWrite`, `scripting`, `tabs`, `debugger`, `cookies`。
+- **宿主权限**: `<all_urls>` (用于在所有页面注入 content 脚本)。
+- **构建细节**: 生产环境构建使用 `terser` 压缩，并强制 `ascii_only` 以确保字符兼容性。
+
+## 6. 维护者提示
+
+在修改 `TimestampPage.tsx` 等核心页面时，应保持**逻辑层**（基于 dayjs 的转换算法）与**渲染层**（JSX/MUI 样式）的严格分离。