# CLAUDE.md

> 本文件用于指导 Claude（及其他 AI 助手）在本仓库内进行高质量的代码协作。
> 请在每次重大改动后保持本文件与实际工程的同步。

## 1. 项目概览

- **名称**：AutoRecord（npm/cargo 包名：`auto-record`，crate lib 名：`auto_record_lib`）
- **定位**：桌面端 **录制内嵌 webview 内容** 工具
- **技术栈**：
  - 前端：React 19 + TypeScript 5.8 + Vite 7
  - UI 组件与风格：Ant Design 6.x（最新）+ Tailwind CSS v4（主题 token 已对齐 antd 6 设计规范，见 `src/App.css` 的 `@theme` 块）
  - 后端：Rust (Tauri 2.x stable)
  - 包管理：pnpm（推荐 ≥ 10，配合 Node.js ≥ 20.19）
  - 桌面壳：Tauri 2.x（官方稳定版）
- **应用标识**：`com.ewaga.autorecord`（`src-tauri/tauri.conf.json#identifier`）
- **目标平台**  Windows / macOS （windows优先）
                      |

## 2. 目录结构

```
AutoRecord/
├── CLAUDE.md                 # 本文件
├── README.md
├── package.json              # 前端依赖与脚本（pnpm）
├── pnpm-lock.yaml            # 首次 pnpm install 后生成
├── tsconfig.json
├── tsconfig.node.json
├── vite.config.ts
├── index.html
├── public/                   # 静态资源（不经构建处理）
│   ├── tauri.svg
│   └── vite.svg
├── src/                      # 前端源码（TypeScript + React）
│   ├── main.tsx              # 应用入口
│   ├── App.tsx               # 根组件
│   ├── App.css
│   ├── styles.css
│   ├── vite-env.d.ts
│   └── assets/
│       └── react.svg
└── src-tauri/                # Rust / Tauri 端
    ├── Cargo.toml
    ├── build.rs
    ├── tauri.conf.json       # Tauri 主配置
    ├── capabilities/
    │   └── default.json      # 权限能力声明（Tauri 2 权限系统）
    ├── icons/                # 平台图标（需运行 `pnpm tauri icon` 生成）
    └── src/
        ├── main.rs           # 桌面端入口
        └── lib.rs            # 可复用入口（含 #[tauri::command]）
```

## 3. 常用命令

所有命令在仓库根目录执行，使用 **pnpm**（请勿混用 npm/yarn）。

| 目的                     | 命令                       | 对应脚本（package.json） |
| ------------------------ | -------------------------- | ------------------------ |
| 安装依赖                 | `pnpm install`             | —                        |
| 启动开发（含 Tauri 壳）  | `pnpm tauri dev`           | `tauri`                  |
| 仅启动前端 Vite          | `pnpm dev`                 | `vite`                   |
| 构建前端                 | `pnpm build`               | `tsc && vite build`      |
| 预览构建产物             | `pnpm preview`             | `vite preview`           |
| 打包桌面端               | `pnpm tauri build`         | `tauri`                  |
| 生成多平台图标           | `pnpm tauri icon <path>`   | `tauri`                  |
| 查看 Tauri CLI 帮助      | `pnpm tauri --help`        | `tauri`                  |

## 4. 关键约定

### 4.1 前端

- **入口**：`src/main.tsx` → 渲染 `<App />` 到 `#root`
- **样式**：全局样式（含 Tailwind `@import` 与 `@theme` token）写在 `src/App.css`；组件样式优先写在同名 `.css` / 模块化样式中
- **Tailwind 用法**：直接使用 utility class（如 `text-primary`、`bg-gray-3`、`rounded-md`、`shadow-md`、`p-4`）；这些 token 与 antd 6 的 seed token 完全一致，后续接入 antd `ConfigProvider` 时请保持同步
- **路径别名**：暂未配置，按需在 `vite.config.ts` + `tsconfig.json` 中同步
- **与 Rust 通信**：使用 `@tauri-apps/api` 的 `invoke("command_name", args)`

### 4.2 Rust / Tauri

- 业务逻辑写在 `src-tauri/src/lib.rs` 中，`main.rs` 仅作为薄入口（移动端复用所需）
- 暴露给前端的命令使用 `#[tauri::command]` 标注，并注册到
  ```rust
  .invoke_handler(tauri::generate_handler![greet, /* ... */])
  ```
- Tauri 2 使用 **权限系统（capabilities）**：任何新插件 / 新 API 都需要在
  `src-tauri/capabilities/default.json` 中显式声明权限
- 新增 Rust 依赖：编辑 `src-tauri/Cargo.toml` 后由 cargo 自动解析

## 5. 代码风格

- **注释语言**：代码注释尽量使用 **中文**，专业术语（如 `WebView`、`MediaRecorder`、`invoke`、`StrictMode` 等）保留英文原词
- TypeScript：开启 `strict`，禁止 `any`（业务代码）；优先使用类型推断
- React：函数组件 + hooks；避免在组件内部进行重 IO
- Rust：`cargo fmt` + `cargo clippy --all-targets -- -D warnings`
- 提交信息建议遵循 Conventional Commits（`feat:` / `fix:` / `chore:` ...）
- 一般功能请尽量在前端也就是 typescript 实现

## 6. AI 助手协作守则

### 6.0 高优先级约束（每次响应前必读）

- **先分析，再动手**：拿到需求后，先口头确认/复述实际需求与改动范围，得到方向认可或显然无歧义时再开始改文件
- **最小改动**：只动与本次需求直接相关的代码与文档，不顺手「优化」或重排无关内容
- **不过度理解**：用户说什么改什么，不擅自扩大解释；如有歧义，先问一次，不要靠猜
- **使用中文沟通**：与用户交流（计划、解释、报告）全程使用中文；代码注释规则见 § 5

### 6.1 常规守则

在本仓库内开展工作时，请遵循：

1. **先看 CLAUDE.md 与 README.md**，了解项目当前状态再动手
2. **保持 pnpm 单一来源**：不要生成 `package-lock.json` / `yarn.lock`
3. **不要直接修改 `src-tauri/gen/`**（由 Tauri 在构建时生成）
4. **新增前端依赖**：使用 `pnpm add <pkg>`；运行时依赖与 devDeps 分清
5. **新增 Rust 依赖**：写入 `Cargo.toml`，必要时说明 feature flags
6. **跨进程通信**：前后端 API 同步更新（TS 类型 + Rust 命令）
7. **变更涉及权限**：同步修改 `capabilities/default.json` 与 `tauri.conf.json`
8. **不要提交大文件**：录屏样本、二进制 ffmpeg 等放入 `.gitignore`
9. **完成功能后更新本文件**：尤其是「目录结构」「常用命令」「路线图」三节