186 lines
6.1 KiB
Markdown
186 lines
6.1 KiB
Markdown
|
# 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` - 快速开始指南
|