# CLAUDE.md

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

**重要：使用中文进行交流和文档生成**

## 项目概述

CutThenThink Lite 是一个基于 Tauri 2.x 开发的轻量级截图和 AI 分类工具，目标是替代 Python 版本实现 < 10MB 的原生应用。

## 技术栈

- **框架**: Tauri 2.10.0 (Rust + WebView)
- **前端**: Vanilla HTML/CSS/JS (零框架)
- **后端**: Rust (Tokio 异步运行时)
- **数据库**: SQLite (rusqlite)
- **构建工具**: Vite 5.4.11

## 常用命令

### 开发命令
```bash
# 开发模式 (前端热重载 + 后端热重载)
npm run tauri:dev

# 仅前端开发 (端口 5173)
npm run dev
```

### 构建命令
```bash
# 前端生产构建
npm run build

# 完整应用构建 (生成安装包)
npm run tauri:build

# 构建分析 (查看打包体积)
npm run build:analyze

# 清理构建产物
npm run clean
```

### 系统依赖安装 (Linux)
```bash
sudo ./install-deps.sh
# 或手动安装:
# sudo apt-get install -y pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev librsvg2-dev
```

## 项目架构

### 后端架构 (Rust)

后端代码位于 `src-tauri/src/`，采用模块化架构：

**核心模块**:
- `lib.rs` - 主入口，注册 Tauri 命令和全局状态
- `main.rs` - 应用启动点
- `config.rs` - 配置管理器 (应用配置、路径管理)
- `database.rs` - SQLite 数据库封装
- `hotkey.rs` - 全局快捷键

**功能模块**:
- `screenshot.rs` - 截图管理器 (全屏/区域/窗口截图、剪贴板操作)
- `upload.rs` - 图片上传到图床
- `secure_storage.rs` - API 密钥安全存储

**OCR 模块** (`ocr/`):
- `mod.rs` - OCR 管理器
- `cloud.rs` - 云端 OCR (百度/腾讯)
- `local.rs` - 本地 OCR 插件系统
- `result.rs` - OCR 结果数据结构

**AI 模块** (`ai/`):
- `mod.rs` - AI 模块入口
- `client.rs` - AI 客户端 (Claude/OpenAI)
- `classify.rs` - AI 分类器
- `template.rs` - Prompt 模板管理器
- `prompt.rs` - Prompt 渲染引擎

**插件系统**:
- `plugin/mod.rs` - 插件管理器 (安装/卸载/状态查询)

### 前端架构

前端代码位于 `src/`，采用原生 JavaScript 模块化架构：

**目录结构**:
```
src/
├── index.html          # 主页面
├── main.js            # 应用入口
├── style.css          # 全局样式
├── api/               # Tauri API 封装
│   ├── index.js       # 通用 API 调用
│   └── ai.ts         # AI 相关 API
├── store/             # 简单状态管理
│   ├── index.js      # Store 入口
│   ├── records.ts    # 记录状态
│   ├── settings.ts   # 设置状态
│   ├── upload.ts     # 上传状态
│   └── ai.ts         # AI 状态
├── components/        # UI 组件
│   ├── shared/       # 共享组件
│   └── views/        # 页面视图
└── utils/            # 工具函数
```

### 全局状态管理

后端使用 `AppState` 结构体管理全局状态（`lib.rs:25-32`）:
- `screenshot_manager` - 截图管理器
- `config_manager` - 配置管理器
- `database` - 数据库实例
- `plugin_manager` - 插件管理器
- `classifier` - AI 分类器
- `template_manager` - 模板管理器

所有状态通过 `Mutex` 包装以保证线程安全。

## Tauri 命令系统

所有前端与后端通信通过 Tauri 命令实现（`lib.rs:89-137`），命令分组如下：

**截图命令** (`screenshot_*`): 全屏截图、区域截图、剪贴板操作、删除、列表、清理
**配置命令** (`config_*`): 获取/设置配置、获取路径
**上传命令** (`upload_image`): 上传到图床
**数据库命令** (`record_*`, `setting_*`): 记录 CRUD、设置管理
**OCR 命令** (`ocr_*`): 识别、保存/获取 API 密钥
**插件命令** (`plugin_*`): 列表、安装、卸载
**AI 命令** (`ai_*`): 分类（普通/流式）、API 密钥管理、提供商配置
**模板命令** (`template_*`): 模板 CRUD、测试
**分类命令** (`classification_*`): 获取/确认分类结果、历史记录、统计

## 数据库架构

SQLite 数据库文件位于配置目录的 `data/` 文件夹下，主要表结构：

- **records** - 截图记录表 (id, type, content, file_path, thumbnail, metadata, created_at)
- **settings** - 设置表 (key, value, updated_at)
- **classifications** - AI 分类结果表 (id, record_id, category, subcategory, tags, confidence, reasoning, template_id, confirmed, created_at)
- **classification_history** - 分类历史表

## 配置文件

- `.env.development` - 开发环境变量
- `src-tauri/tauri.conf.json` - Tauri 应用配置 (窗口、权限、打包)
- `src-tauri/Cargo.toml` - Rust 依赖管理
- `vite.config.js` - Vite 构建配置 (代码分割、压缩、优化)
- `package.json` - Node.js 依赖和脚本

## 关键设计模式

1. **异步处理**: 长时间运行的操作（OCR、AI 分类、上传）使用 `tokio::spawn` 在后台异步执行
2. **进度通知**: 通过 `window.emit()` 发送实时进度更新 (`ocr-progress`, `plugin-install-progress`, `ai-classify-chunk` 等)
3. **错误处理**: 统一返回 `Result<T, String>`，错误信息向前端展示
4. **插件系统**: 本地 OCR 插件为独立的可执行文件，通过 SHA256 校验确保安全性

## 安全注意事项

- API 密钥存储在数据库中，通过 `secure_storage.rs` 提供额外保护
- 插件安装前进行 SHA256 校验
- Tauri 权限配置位于 `src-tauri/capabilities/` 目录
- 敏感操作需要用户确认（如删除、卸载）

## 开发提示

1. 修改 Rust 代码后需重启 `tauri:dev`（前端可热重载，后端需要重新编译）
2. 新增 Tauri 命令需要在 `lib.rs` 的 `invoke_handler!` 宏中注册
3. 前端调用后端命令使用 `invoke()` 函数 (见 `src/api/index.js`)
4. 数据库迁移需要手动修改 `database.rs` 中的表创建逻辑
5. 窗口配置修改 `src-tauri/tauri.conf.json`

## 构建产物

- `dist/` - 前端构建产物 (JS/CSS/图片)
- `src-tauri/target/release/bundle/` - 完整应用安装包 (.deb, .app, .exe 等)

## 相关文档

- `docs/design-v3-complete.md` - 完整设计文档
- `docs/BUILD-GUIDE.md` - 构建指南
- `README.md` - 快速开始指南