# snapsight

**Repository Path**: ulquiola/snapsight

## Basic Information

- **Project Name**: snapsight
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-15
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 Snapsight - 屏幕 OCR + AI 处理工具

<p align="center">
  <img src="https://img.shields.io/badge/版本-v1.0-blue" alt="版本">
  <img src="https://img.shields.io/badge/平台-macOS%20|%20Windows-green" alt="平台">
  <img src="https://img.shields.io/badge/Electron-最新版本-orange" alt="Electron">
  <img src="https://img.shields.io/badge/OCR-Tesseract--js-purple" alt="OCR">
  <img src="https://img.shields.io/badge/AI-支持Markdown渲染-red" alt="AI">
</p>

## ✨ 特性亮点

- 🖼️ **高精度截图 OCR** - 2x 超采样 + PNG 格式确保文字识别清晰度
- 🤖 **智能 AI 处理** - 集成 AI 模型，支持 Markdown 富文本渲染
- 🎯 **跨平台支持** - 原生支持 macOS 和 Windows
- ⚡ **快速启动** - 一键启动脚本，支持 GPU 崩溃修复
- 🔧 **零依赖配置** - 手动 .env 解析，无需额外依赖
- 📋 **悬浮窗界面** - 现代化的悬浮窗 UI，支持用户追问
- 🛡️ **权限自动处理** - macOS 屏幕录制权限自动请求

## 📁 项目结构

```
snapsight/
├── main.js                 # Electron 主进程
├── overlay-renderer.js     # 悬浮窗前端逻辑 + Markdown 渲染
├── src/components/MarkdownRenderer.js  # Markdown 解析器
├── ai-processor.js        # AI 处理器
├── ocr-processor.js       # OCR 处理器
├── screenshot.js          # 高清截图模块
├── settings-store.js      # 设置存储（零依赖 .env 解析）
├── start.sh              # macOS/Linux 启动脚本
├── start.bat             # Windows 启动脚本
├── build-windows.bat     # Windows 构建脚本
└── overlay.html          # 悬浮窗界面
```

## 🚀 快速开始

### 1️⃣ 安装依赖
```bash
npm install
```

### 2️⃣ 配置 API 密钥
复制 `.env.example` 到 `.env` 并设置您的 AI API：
```bash
cp .env.example .env
# 编辑 .env 文件设置您的 API 配置
```

### 3️⃣ 启动应用
- **macOS/Linux**: `./start.sh`
- **Windows**: 双击 `start.bat`

> 💡 启动脚本已包含 GPU 崩溃修复参数 `--disable-gpu --no-sandbox`

## 🎯 使用方法

### 基本操作流程
1. **热键激活** - 按 `F3` 键启动区域选择
2. **区域选择** - 拖动鼠标选择屏幕区域
3. **自动识别** - 释放鼠标自动执行 OCR
4. **AI 处理** - 文本发送到 AI 进行分析处理
5. **悬浮窗展示** - 结果在悬浮窗中显示（支持 Markdown）
6. **用户追问** - 在输入框中继续与 AI 对话

### 功能演示
```plaintext
📸 截图识别 → 🧠 OCR 提取文本 → 🤖 AI 分析处理 → 📋 Markdown 渲染展示
```

## ⚙️ 技术特色

### 🖼️ OCR 优化
- **2x 超采样**：确保小字体识别准确率
- **PNG 格式**：避免 JPEG 压缩导致的文字模糊
- **多语言支持**：内置中文（简体）和英文模型

### 🤖 AI 集成
- **零依赖 .env 解析**：无 `dotenv` 依赖，手动解析
- **流式响应**：支持实时 AI 响应显示
- **Markdown 渲染**：AI 回答以富文本形式展示

### 🛡️ 系统兼容
- **GPU 崩溃修复**：内置 `--disable-gpu` 参数
- **权限自动处理**：macOS 屏幕录制权限引导
- **跨平台启动**：统一的启动脚本

## 🔧 配置选项

### AI 提供商配置（.env）
```ini
# 支持的提供商：openai, azure, groq, custom
AI_PROVIDER=custom

# OpenAI 配置
OPENAI_API_KEY=sk-xxxxxxxxxxxx
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

# Azure OpenAI 配置
AZURE_OPENAI_API_KEY=xxxxxxxx
AZURE_OPENAI_ENDPOINT=https://xxx.openai.azure.com
AZURE_OPENAI_DEPLOYMENT=gpt-4

# Groq 配置
GROQ_API_KEY=gsk_xxxxxxxx
GROQ_MODEL=llama-3.1-8b-instant

# 自定义 API 配置
CUSTOM_API_URL=http://127.0.0.1:8081/v1/chat/completions
CUSTOM_API_MODEL=T2
```

### OCR 配置
- **语言**：中文简体 (chi_sim) + 英文 (eng)
- **分辨率**：2x 屏幕分辨率
- **格式**：PNG 无损格式

## 🐛 故障排除

### 常见问题

#### 1. GPU 进程崩溃
**症状**：应用启动后立即退出，日志显示 `exit_code=15`
**解决方案**：启动脚本已内置修复参数，如需手动修复：
```javascript
// 在 main.js 顶部添加
app.disableHardwareAcceleration();
```

#### 2. macOS 权限问题
**症状**：截图失败，无法选择区域
**解决方案**：
```bash
# 手动打开权限设置
open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"
# 勾选 Electron 或您的终端应用
```

#### 3. AI 响应无内容
**检查步骤**：
1. 确认 `.env` 配置正确
2. 检查 API 服务可访问性
3. 查看应用日志 `logs.txt`

### 日志查看
```bash
# 实时查看日志
tail -f logs.txt

# Windows 查看日志
type logs.txt
```

## 🏗️ 开发构建

### 打包为可执行文件
- **macOS 构建**：已预编译在 `release/snapsight-mac.zip`
- **Windows 构建**：运行 `build-windows.bat`

### 开发调试
```bash
# 开发模式启动
npm run dev

# 查看所有热键
node main.js --help
```

## 📋 文件说明

| 文件 | 说明 |
|------|------|
| `QUICKSTART.md` | 快速使用指南 |
| `USAGE.md` | 详细使用说明 |
| `TEST-REPORT.md` | 测试报告 |
| `FIX-REPORT.md` | 修复记录 |
| `PERMISSION-GUIDE.md` | 权限配置指南 |
| `LICENSE` | MIT 许可证 |

## 🔄 更新日志

### v1.0 (2026-05-15)
- ✅ 高清 OCR：2x 分辨率 + PNG 格式优化
- ✅ Markdown 渲染：AI 响应富文本展示
- ✅ GPU 崩溃修复：内置禁用硬件加速
- ✅ 零依赖配置：手动 .env 解析
- ✅ 跨平台启动脚本：macOS/Windows 统一启动
- ✅ 悬浮窗界面：现代化的对话 UI
- ✅ 权限自动处理：macOS 屏幕录制引导

## 🤝 贡献指南

1. Fork 项目仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

## 📄 许可证

本项目基于 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 支持与反馈

- **问题报告**：[创建 Issue](https://gitee.com/ulquiola/snapsight/issues)
- **功能请求**：欢迎提交 PR 或 Issue
- **使用交流**：查看 [QUICKSTART.md](QUICKSTART.md) 快速上手

---

<p align="center">
  <strong>💡 提示：首次使用请务必配置 .env 文件中的 API 密钥</strong>
</p>

**最后更新**: 2026-05-15