cutThenThink/docs/quick_start_gui.md

# CutThenThink GUI 快速入门指南

## 概述

CutThenThink 是一个智能截图管理工具，提供截图、OCR识别、AI分析和云存储同步等功能。

## 快速开始

### 1. 安装依赖

```bash
# 安装所有依赖
pip install -r requirements.txt
```

主要依赖：
- PyQt6==6.6.1 (GUI框架)
- PyQt6-WebEngine==6.6.0 (Web引擎)
- SQLAlchemy==2.0.25 (数据库)
- paddleocr==2.7.0.3 (OCR识别)
- openai>=1.0.0 (AI服务)
- anthropic>=0.18.0 (AI服务)

### 2. 运行应用

```bash
# 方法1: 运行测试脚本
python3 test_main_window.py

# 方法2: 直接导入使用
python3 -c "
from PyQt6.QtWidgets import QApplication
from src.gui import get_main_window_class

app = QApplication([])
MainWindow = get_main_window_class()
window = MainWindow()
window.show()
app.exec()
"
```

### 3. 基本功能

#### 主界面布局
- **左侧**: 导航侧边栏
  - 📷 截图处理
  - 📁 分类浏览
  - ☁️ 批量上传
  - ⚙️ 设置

- **右侧**: 主内容区域
  - 根据侧边栏选择显示不同页面

#### 快捷键
- `Ctrl+Shift+A`: 新建截图
- `Ctrl+Shift+V`: 粘贴剪贴板图片
- `Ctrl+Shift+O`: 导入图片

### 4. 使用颜色和样式

如果您想在其他地方使用相同的配色方案：

```python
from src.gui.styles import COLORS

# 使用颜色
button_color = COLORS.accent_primary      # #8B6914
bg_color = COLORS.background_primary      # #400000
text_color = COLORS.text_primary           # #2C2C2C

# 应用样式
from src.gui.styles import ThemeStyles
from PyQt6.QtWidgets import QPushButton

button = QPushButton("按钮")
ThemeStyles.apply_style(button)  # 应用完整主题
```

## 项目结构

```
CutThenThink/
├── src/
│   ├── gui/                 # GUI模块
│   │   ├── main_window.py  # 主窗口
│   │   └── styles/         # 样式定义
│   ├── config/             # 配置管理
│   ├── core/               # 核心功能
│   │   ├── ocr.py         # OCR识别
│   │   └── ai.py          # AI分析
│   ├── models/             # 数据模型
│   └── utils/              # 工具函数
├── data/                   # 数据目录
├── docs/                   # 文档
└── test_main_window.py     # 测试脚本
```

## 主要模块

### 1. 主窗口 (`src.gui.main_window`)

```python
from src.gui import get_main_window_class

MainWindow = get_main_window_class()
window = MainWindow()
window.show()
```

### 2. 样式系统 (`src.gui.styles`)

```python
from src.gui.styles import (
    COLORS,              # 颜色方案
    ThemeStyles,         # 主题样式
    ColorScheme,         # 颜色方案类
    get_color,           # 获取颜色
)
```

### 3. 配置管理 (`src.config.settings`)

```python
from src.config.settings import get_settings

settings = get_settings()
print(settings.ai.provider)    # AI提供商
print(settings.ui.theme)       # 界面主题
```

### 4. OCR功能 (`src.core.ocr`)

```python
from src.core.ocr import OCRProcessor

processor = OCRProcessor()
text = processor.process_image("path/to/image.png")
```

### 5. AI分析 (`src.core.ai`)

```python
from src.core.ai import AIAnalyzer

analyzer = AIAnalyzer()
result = analyzer.analyze_text(text)
```

## 配置文件

配置文件位置: `~/.cutthenthink/config.yaml`

首次运行会自动创建默认配置：

```yaml
ai:
  provider: anthropic
  api_key: ""  # 需要填入您的 API key
  model: claude-3-5-sonnet-20241022

ocr:
  mode: local
  use_gpu: false

ui:
  theme: light
  window_width: 1200
  window_height: 800
```

## 常见问题

### 1. PyQt6 未安装

```bash
pip install PyQt6==6.6.1 PyQt6-WebEngine==6.6.0
```

### 2. 导入错误

确保在项目根目录运行：
```bash
cd /path/to/CutThenThink
python3 test_main_window.py
```

### 3. 样式不生效

确保应用了主题：
```python
from src.gui.styles import ThemeStyles
ThemeStyles.apply_style(your_widget)
```

### 4. 颜色显示不正确

检查颜色定义：
```python
from src.gui.styles import COLORS
print(COLORS.accent_primary)  # 应该输出: #8B6914
```

## 开发指南

### 修改颜色方案

编辑 `src/gui/styles/colors.py` 中的 `ColorScheme` 类：

```python
@dataclass
class ColorScheme:
    accent_primary: str = "#YOUR_COLOR"
    # ... 其他颜色
```

### 修改样式表

编辑 `src/gui/styles/theme.py` 中的 QSS 样式表。

### 添加新页面

1. 在 `main_window.py` 中添加页面创建方法
2. 在 `_create_pages()` 中注册
3. 在侧边栏添加导航按钮
4. 在 `_on_nav_clicked()` 中添加切换逻辑

### 测试修改

```bash
# 运行测试脚本
python3 test_main_window.py

# 或者使用 Python 直接导入
python3 -c "from src.gui import get_main_window_class; print('OK')"
```

## 下一步

- 阅读 `docs/gui_main_window.md` 了解主窗口详细设计
- 阅读 `docs/p0_6_summary.md` 了解 P0-6 任务实现
- 查看 `src/gui/styles/` 了解样式系统
- 查看 `src/config/settings.py` 了解配置管理

## 技术支持

如有问题，请查看相关文档或联系开发团队。