# snapAna · 截图智能整理

让 AI 帮你认识每一张截图。本地运行的 Web 应用：自动监听截图文件夹，提取文字、识别内容、给出标题/摘要/标签/待办，按时间和分类整理成可筛选、可随机展示的卡片库。

## 特性

- 监听一个或多个文件夹，新截图自动入库（含 OneDrive/同步盘的轮询兜底）
- 哈希去重，文件重命名/移动只更新路径
- 可插拔 Provider：Tesseract / PaddleOCR / HTTP OCR / 视觉模型识文 + OpenAI 兼容视觉 AI（Ollama / GLM / MiniMax / OpenAI…）
- 文字识别方式可选：传统 OCR、视觉 AI、混合（OCR 失败自动视觉识文）
- 单张图同时拿到结构化结果：标题 + 摘要 + 分类 + 标签 + 待办 + 建议
- SQLite + FTS5 全文搜索（OCR 文本 / AI 摘要 / AI 标题）
- 分类色块、标签云、收藏、日期范围、状态筛选；卡片网格虚拟滚动
- 随机展示页 + 首页「每日回顾」
- 待办清单：AI 自动抽取「待看 / 待读 / 待办」，可逐条标记完成
- 敏感目录黑名单：勾选后该目录内的截图不会上传云端 VLM

## 目录结构

```
snapAna/
├── backend/         # FastAPI + SQLite + watchdog
│   ├── app/         # 应用代码
│   ├── run.py       # 开发入口
│   └── requirements.txt
├── frontend/        # Vite + React + Tailwind
│   └── src/
├── start-dev.ps1    # 一键启动脚本（Windows）
└── PROGRESS.md      # 进度文档
```

## 快速开始

### 一键启动（Windows PowerShell）

```powershell
# 在仓库根目录
.\start-dev.ps1                # 首次会自动建 venv + 安装依赖
# 或显式重新装依赖
.\start-dev.ps1 -InstallDeps
```

启动后访问：

- 前端：<http://127.0.0.1:5173>
- 后端 API：<http://127.0.0.1:8765/docs>

### 手动启动

```powershell
# 后端
cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python run.py
```

```powershell
# 前端（另开一个终端）
cd frontend
npm install
npm run dev
```

## 配置 AI Provider

进入「设置」页：

- **文字识别方式**：传统 OCR / 视觉 AI 识文 / 混合（推荐）
- **OCR 引擎**：`tesseract`（本地）、`paddleocr`（需 `pip install paddleocr`）、`http`（自定义 API）、`vision`（视觉模型纯识文）
- **视觉 AI 模型**：选 `openai_compat`，填入：
  | 模型 | Base URL | Model 示例 |
  | --- | --- | --- |
  | 本地 Ollama | `http://localhost:11434/v1` | `qwen2.5vl:7b` |
  | OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |
  | 智谱 GLM | `https://open.bigmodel.cn/api/paas/v4` | `glm-4v-flash` |
  | MiniMax | `https://api.minimaxi.com/v1` | `MiniMax-VL-01` |
  | OpenRouter | `https://openrouter.ai/api/v1` | `qwen/qwen2.5-vl-72b-instruct` |

保存后回到「设置」→「监听目录」，添加一个截图文件夹，系统会自动扫描并入库；右侧 worker 会按配置并发分析（默认并发数 2，可通过 `.env` 调整）。

## 数据与隐私

- 所有数据存在 `backend/.data/`：`snapana.db`（SQLite）+ `thumbs/`（缩略图缓存）
- 默认绑定 `127.0.0.1`，仅本机访问
- 标记为「敏感目录」的截图不会上传到云端 VLM；如果两个 Provider 都是本地，则永远离线
- 上传 VLM 之前会自动压缩到长边 1280 像素以节省成本/时延

## 开发提示

- 前端通过 Vite 反向代理 `/api/*` 到 `127.0.0.1:8765`
- 队列 / 监听器在 FastAPI lifespan 内启动，热重载会自动复用
- SQLAlchemy 模型与 FTS5 触发器在首次启动时由 `init_db()` 创建，无需额外迁移命令