rsgltzyd/testing-tool
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Reorganize CLAUDE.md for better clarity and flow

Browse Source 
- Restructured content into logical sections: Quick Start, Architecture Overview, Core Features, Development Workflow, Configuration & Implementation, CI/CD & Project Context
- Added command table for better readability of npm scripts
- Simplified directory structure while maintaining essential information
- Added missing technical context: path aliases (@/), TypeScript configuration highlights
- Preserved all original information while reducing redundancy
- Created design document documenting the reorganization approach

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
雨霖铃
2026-03-25 21:13:52 +08:00
parent f4c2f6d374
commit 71b9dcc35c
2 changed files with 237 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+140 -130
View File
@@ -2,170 +2,180 @@
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## 项目概述
## Project Overview
这是一个基于 WXT 框架的浏览器扩展项目，提供时间戳转换工具。项目已精简为核心功能，移除了录制回放等复杂功能。
A browser extension built with the WXT framework, providing timestamp conversion and storage cleaning tools. The project has been streamlined to focus on core functionality, removing complex features like recording and playback.
## 核心命令
## Core Commands
### 开发相关
### Development
- `npm run dev` - Start development mode for Chrome
- `npm run dev:firefox` - Start development mode for Firefox
- `npm run build` - Build production version for Chrome
- `npm run build:firefox` - Build production version for Firefox
- `npm run zip` - Package Chrome extension
- `npm run zip:firefox` - Package Firefox extension
- `npm run compile` - TypeScript type checking (no file generation)
- `npm run lint` - Run ESLint with zero warnings allowed
- `npm run dev` - 启动 Chrome 浏览器的开发模式
- `npm run dev:firefox` - 启动 Firefox 浏览器的开发模式
- `npm run build` - 构建 Chrome 浏览器的生产版本
- `npm run build:firefox` - 构建 Firefox 浏览器的生产版本
- `npm run zip` - 打包 Chrome 扩展
- `npm run zip:firefox` - 打包 Firefox 扩展
- `npm run compile` - TypeScript 类型检查（不生成文件）
- `npm run lint` - 运行 ESLint 检查
### 依赖与准备
- `npm install` - 安装依赖
- `postinstall` 会自动运行 `wxt prepare` 准备开发环境
- `prepare` 钩子会初始化 Husky Git 钩子
### Dependencies & Setup
- `npm install` - Install dependencies (automatically runs `wxt prepare` via postinstall hook)
- The `prepare` hook initializes Husky Git hooks
### CI/CD
- GitHub Actions workflow: `.github/workflows/node.js.yml`
- Triggers on push to main branch or pull requests
- Uses Node.js 20.x and 22.x for multi-version testing
- Runs ESLint, TypeScript compilation, and build steps
- Test commands are currently commented (project has no tests)
- GitHub Actions 配置: `.github/workflows/node.js.yml`
- 在 main 分支推送或 PR 时触发
- 使用 Node.js 22.x 运行 build
- 测试命令当前被注释（项目暂无测试）
## Project Architecture
## 项目架构
### 技术栈
- **框架**: WXT (Web Extension Toolkit) - 浏览器扩展开发框架
- **前端**: React 19 + TypeScript
- **UI 库**: Material UI (MUI)
- **日期处理**: dayjs (含 UTC 和时区插件)
- **通信**: @webext-core/messaging
### 目录结构
### Tech Stack
- **Framework**: WXT (Web Extension Toolkit) - browser extension development framework
- **Frontend**: React 19 + TypeScript
- **UI Library**: Material UI (MUI)
- **Date Handling**: dayjs (with UTC and timezone plugins)
- **Communication**: @webext-core/messaging
- **Storage**: Chrome Storage API with type-safe wrapper
### Directory Structure
```
├── entrypoints/ # 浏览器扩展入口点
│ ├── background.ts # 后台脚本（处理扩展安装/更新，注入内容脚本）
│ ├── content.ts # 内容内容脚本（注入到页面，当前为空占位）
│ ├── popup/ # 扩展弹窗界面
│ │ ├── App.tsx # 弹窗主应用
│ │ ├── main.tsx # 弹窗入口
│ │ ├── index.html # 弹窗 HTML
│ │ └── pages/ # 弹窗页面
│ │ └── TimestampPage.tsx # 时间戳转换页面（核心功能）
│ └── options/ # 选项页面（当前为静态 HTML）
│ └── index.html # 选项页 HTML
├── utils/ # 工具函数
│ ├── chromeStorage.ts # Chrome Storage 工具（类型安全封装）
│ ├── dayjs.ts # dayjs 配置（UTC + 时区插件）
│ └── messages.tsx # 扩展消息通信工具（@webext-core/messaging）
├── types/ # 类型定义
│ └── storage.d.ts # StorageSchema 类型定义
├── constants/ # 常量定义（当前为空）
└── public/ # 静态资源
├── entrypoints/ # Browser extension entry points
│ ├── background.ts # Background script (handles extension install/update, injects content scripts)
│ ├── content.ts # Content script (injected into pages, currently placeholder)
│ ├── popup/ # Extension popup interface
│ │ ├── App.tsx # Popup main application (handles page routing)
│ │ ├── main.tsx # Popup entry point
│ │ ├── index.html # Popup HTML
│ │ └── pages/ # Popup pages
│ │ ├── TimestampPage.tsx # Timestamp conversion page (core feature)
│ │ └── StorageCleanerPage.tsx # Storage cleaning page (added feature)
│ └── options/ # Options page (currently static HTML)
│ └── index.html # Options page HTML
├── utils/ # Utility functions
│ ├── chromeStorage.ts # Chrome Storage utility (type-safe wrapper)
│ ├── dayjs.ts # dayjs configuration (UTC + timezone plugins)
│ ├── messages.tsx # Extension messaging protocol (@webext-core/messaging)
│ └── storageCleaner.ts # Storage cleaning utilities (new feature)
├── types/ # TypeScript type definitions
│ └── storage.d.ts # StorageSchema type definitions
├── constants/ # Constants (currently empty)
└── public/ # Static assets
```
### 核心功能
### Core Features
#### 时间戳转换工具 (entrypoints/popup/pages/TimestampPage.tsx)
#### Timestamp Conversion Tool (`entrypoints/popup/pages/TimestampPage.tsx`)
- Real-time current timestamp display (milliseconds/seconds toggle)
- Timestamp ↔ date/time conversion
- Support for multiple timezones (Asia/Shanghai, America/New_York, Europe/London)
- One-click copy functionality
- Input validation and error handling
- 实时显示当前时间戳（毫秒/秒可切换）
- 时间戳 → 日期时间转换
- 日期时间 → 时间戳转换
- 支持多个时区（亚洲/上海、美洲/纽约、欧洲/伦敦）
- 一键复制功能
- 输入验证和错误提示
#### Storage Cleaning Tool (`entrypoints/popup/pages/StorageCleanerPage.tsx`)
- Automatically reads current domain
- Cleans multiple storage types: localStorage, sessionStorage, IndexedDB, Cookies, Cache Storage, Service Workers
- User-selectable storage types (all selected by default)
- Confirmation dialog to prevent accidental cleaning
- Cleaning result statistics display
- Auto-refresh page after cleaning option
- User preferences persistence
### 扩展入口点
### Extension Entry Points
- **后台脚本** (`entrypoints/background.ts`):
- 监听扩展安装/更新事件
- 自动向所有有效标签页注入内容脚本
- 过滤受限协议（chrome://, about:// 等）
#### Background Script (`entrypoints/background.ts`)
- Listens for extension installation/update events
- Automatically injects content scripts into all valid tabs
- Filters restricted protocols (chrome://, about://, etc.)
- **内容脚本** (`entrypoints/content.ts`):
- 匹配所有 URL (`<all_urls>`)
- 在文档开始时运行
- 当前为占位符，无实际逻辑
#### Content Script (`entrypoints/content.ts`)
- Matches all URLs (`<all_urls>`)
- Runs at document start
- Currently a placeholder with no actual logic
- **弹窗** (`entrypoints/popup/`):
- 主入口显示 TimestampPage
- 提供时间戳转换的完整功能
#### Popup (`entrypoints/popup/`)
- Main entry displays TimestampPage by default
- Tab-based navigation between timestamp conversion and storage cleaning
- Route persistence: remembers last visited page when popup is reopened
- **选项页** (`entrypoints/options/`):
- 当前为静态 HTML 页面
- 可扩展为设置界面
#### Options Page (`entrypoints/options/`)
- Currently a static HTML page
- Can be extended as a settings interface
### 数据存储
### Data Storage
使用 Chrome Storage API 进行持久化存储：
Uses Chrome Storage API for persistent storage:
- Type-safe wrapper (`utils/chromeStorage.ts`)
- Interface-based Schema (`types/storage.d.ts`)
- Current storage keys:
- `app/currentRoute`: Current active page route (default: 'timestamp')
- `app/visiblePages`: List of visible pages (default: ['timestamp', 'storageCleaner'])
- `app/lastRoute`: Last accessed route (legacy)
- `app/theme`: Theme settings
- `storageCleaner/preferences`: Storage cleaner preferences (autoRefresh, selectedTypes)
- 类型安全的封装 (`utils/chromeStorage.ts`)
- 基于接口定义的 Schema (`types/storage.d.ts`)
- 当前支持的存储键：
- `app/lastRoute`: 上次访问的路由
- `app/theme`: 主题设置
### Messaging
### 消息通信
Uses `@webext-core/messaging` library for type-safe extension communication:
- Defined in `utils/messages.tsx`
- Current ProtocolMap is empty (reserved for future use)
使用 `@webext-core/messaging` 库实现类型安全的扩展内通信：
### Key Configuration Files
- 定义在 `utils/messages.tsx`
- 当前 ProtocolMap 为空（预留接口）
### 关键配置文件
#### wxt.config.ts
- 启用 React 模块 (`@wxt-dev/module-react`)
- 配置 manifest 权限和 host_permissions
- 使用 Terser 压缩（强制 ASCII 编码）
- 配置图标和选项页
#### manifest 权限
#### `wxt.config.ts`
- Enables React module (`@wxt-dev/module-react`)
- Configures manifest permissions and host_permissions
- Uses Terser compression (forces ASCII encoding)
- Configures icons and options page
#### Manifest Permissions
```typescript
permissions: [
'storage', // Chrome Storage
'unlimitedStorage', // 无限制存储
'clipboardWrite', // 剪贴板写入（复制功能）
'activeTab', // 当前标签页访问
'scripting', // 脚本注入
'tabs', // 标签页管理
'debugger', // 调试器权限
'unlimitedStorage', // Unlimited storage
'clipboardWrite', // Clipboard write (copy functionality)
'activeTab', // Current tab access
'scripting', // Script injection
'tabs', // Tab management
'debugger', // Debugger permissions
'cookies', // Cookies access (added for storage cleaning)
],
host_permissions: ['<all_urls>'] // 访问所有网站
host_permissions: ['<all_urls>'] // Access all websites
```
## 开发注意事项
## Development Notes
### 浏览器兼容性
### Browser Compatibility
- Supports Chrome and Firefox browsers
- Uses WXT framework to abstract browser differences
- 支持 Chrome 和 Firefox 浏览器
- 使用 WXT 框架抽象浏览器差异
### Code Quality
- ESLint for code checking (zero warnings enforced)
- Husky for Git hook management
- Lint-staged ensures staged files comply (ESLint + TypeScript + Prettier)
- Prettier for code formatting (100 char line width, 2 space indent, single quotes, trailing comma)
### 代码质量
### TypeScript Configuration
- Strict mode enabled (`strict: true`)
- `noImplicitAny` set to `false` (allows implicit any)
- Unused variables/parameters cause errors (`noUnusedLocals`, `noUnusedParameters`)
- Module resolution mode: Bundler
- Excludes test files (`**/*.test.tsx`, `**/*.test.ts`) from type checking
- 使用 ESLint 进行代码检查（零警告）
- Husky 用于 Git 钩子管理
- Lint-staged 确保暂存文件符合规范（ESLint + TypeScript + Prettier）
- Prettier 用于代码格式化
- Prettier 配置: 100 字符行宽，2 空格缩进，单引号，trailing comma
### Storage Cleaning Implementation Details
- Cookies: Uses `chrome.cookies` API directly in extension context
- Other storage types: Uses `chrome.scripting.executeScript` to inject cleaning scripts into page context
- Restricted page filtering (chrome://, about://, edge://, view-source://, file://, data://)
- IndexedDB: Uses `indexedDB.databases()` to get database list, handles `onblocked` events
- Service Workers: Unregisters to prevent re-caching
- Cache Storage: Uses `caches` API to clear all caches
### TypeScript 配置
- 严格模式开启（`strict: true`）
- `noImplicitAny` 设置为 `false`（允许隐式 any）
- 未使用变量/参数会报错（`noUnusedLocals`, `noUnusedParameters`）
- 模块解析模式：Bundler
- 排除测试文件（`**/*.test.tsx`, `**/*.test.ts`）以避免类型检查
### 项目历史
近期重构（根据 git 历史）：
- 移除了录制回放功能
- 移除了测试页面
- 精简为单页面时间戳工具
- 将 storage 工具类重命名为 storageUtil
### Project History
Recent refactoring (based on git history):
- Removed recording and playback functionality
- Removed test pages
- Streamlined to single-page timestamp tool
- Renamed storage utility class to storageUtil
- Added storage cleaning functionality with persistent preferences
- Added route persistence for popup navigation