cutThink_lite/CLAUDE.md

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

常用命令

开发命令

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

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

构建命令

# 前端生产构建
npm run build

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

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

# 清理构建产物
npm run clean

系统依赖安装 (Linux)

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 - 快速开始指南