congsh
5c028d7952
包含 FastAPI 后端、React 前端、队列/OCR/标签/待办等完整功能。 Co-authored-by: Cursor <cursoragent@cursor.com>
95 lines
3.6 KiB
Markdown
95 lines
3.6 KiB
Markdown
# 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()` 创建，无需额外迁移命令
|