# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

这是一个基于 WXT 框架的浏览器扩展项目，提供时间戳转换工具。项目已精简为核心功能，移除了录制回放等复杂功能。

## 核心命令

### 开发相关

- `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 钩子

### CI/CD

- GitHub Actions 配置: `.github/workflows/node.js.yml`
- 在 main 分支推送或 PR 时触发
- 使用 Node.js 22.x 运行 build
- 测试命令当前被注释（项目暂无测试）

## 项目架构

### 技术栈

- **框架**: WXT (Web Extension Toolkit) - 浏览器扩展开发框架
- **前端**: React 19 + TypeScript
- **UI 库**: Material UI (MUI)
- **日期处理**: dayjs (含 UTC 和时区插件)
- **通信**: @webext-core/messaging

### 目录结构

```
├── 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/popup/pages/TimestampPage.tsx)

- 实时显示当前时间戳（毫秒/秒可切换）
- 时间戳 → 日期时间转换
- 日期时间 → 时间戳转换
- 支持多个时区（亚洲/上海、美洲/纽约、欧洲/伦敦）
- 一键复制功能
- 输入验证和错误提示

### 扩展入口点

- **后台脚本** (`entrypoints/background.ts`):
  - 监听扩展安装/更新事件
  - 自动向所有有效标签页注入内容脚本
  - 过滤受限协议（chrome://, about:// 等）

- **内容脚本** (`entrypoints/content.ts`):
  - 匹配所有 URL (`<all_urls>`)
  - 在文档开始时运行
  - 当前为占位符，无实际逻辑

- **弹窗** (`entrypoints/popup/`):
  - 主入口显示 TimestampPage
  - 提供时间戳转换的完整功能

- **选项页** (`entrypoints/options/`):
  - 当前为静态 HTML 页面
  - 可扩展为设置界面

### 数据存储

使用 Chrome Storage API 进行持久化存储：

- 类型安全的封装 (`utils/chromeStorage.ts`)
- 基于接口定义的 Schema (`types/storage.d.ts`)
- 当前支持的存储键：
  - `app/lastRoute`: 上次访问的路由
  - `app/theme`: 主题设置

### 消息通信

使用 `@webext-core/messaging` 库实现类型安全的扩展内通信：

- 定义在 `utils/messages.tsx`
- 当前 ProtocolMap 为空（预留接口）

### 关键配置文件

#### wxt.config.ts

- 启用 React 模块 (`@wxt-dev/module-react`)
- 配置 manifest 权限和 host_permissions
- 使用 Terser 压缩（强制 ASCII 编码）
- 配置图标和选项页

#### manifest 权限

```typescript
permissions: [
  'storage',           // Chrome Storage
  'unlimitedStorage',  // 无限制存储
  'clipboardWrite',    // 剪贴板写入（复制功能）
  'activeTab',         // 当前标签页访问
  'scripting',         // 脚本注入
  'tabs',              // 标签页管理
  'debugger',          // 调试器权限
],
host_permissions: ['<all_urls>']  // 访问所有网站
```

## 开发注意事项

### 浏览器兼容性

- 支持 Chrome 和 Firefox 浏览器
- 使用 WXT 框架抽象浏览器差异

### 代码质量

- 使用 ESLint 进行代码检查（零警告）
- Husky 用于 Git 钩子管理
- Lint-staged 确保暂存文件符合规范（ESLint + TypeScript + Prettier）
- Prettier 用于代码格式化
- Prettier 配置: 100 字符行宽，2 空格缩进，单引号，trailing comma

### TypeScript 配置

- 严格模式开启（`strict: true`）
- `noImplicitAny` 设置为 `false`（允许隐式 any）
- 未使用变量/参数会报错（`noUnusedLocals`, `noUnusedParameters`）
- 模块解析模式：Bundler
- 排除测试文件（`**/*.test.tsx`, `**/*.test.ts`）以避免类型检查

### 项目历史

近期重构（根据 git 历史）：

- 移除了录制回放功能
- 移除了测试页面
- 精简为单页面时间戳工具
- 将 storage 工具类重命名为 storageUtil