# 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-06-21

## 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 屏幕录制权限自动请求
- **热键可配置** - 默认 F10，支持在设置界面动态修改

## 📁 项目结构

```
snapsight/
├── main.js                 # Electron 主进程（键盘钩子 + 热键管理）
├── preload.js              # 渲染进程预加载脚本（IPC 桥接）
├── config.js               # 应用配置（热键、OCR、AI）
├── ai-processor.js         # AI 处理器（多服务商适配：OpenAI/Azure/Claude/Gemini/自定义）
├── ocr-processor.js        # OCR 处理器（Tesseract.js + 图像预处理）
├── screenshot.js           # 高清截图模块（多方案备用）
├── image-preprocessor.js   # 图像增强（对比度/锐化/超采样）
├── overlay-renderer.js     # 悬浮窗渲染逻辑
├── settings-store.js       # 设置存储（localStorage 持久化）
├── setup-languages.js      # 语言配置工具
├── selection.html          # 区域选择界面
├── overlay.html            # AI 响应悬浮窗界面
├── settings.html           # 设置面板
├── permission-notice.html  # 权限提示页面
├── start.sh                # macOS/Linux 启动脚本
├── start.bat               # Windows 启动脚本
├── build-windows.bat       # Windows 构建脚本
├── package.json            # 项目依赖配置
├── .env.example            # 环境变量模板
└── LICENSE                 # MIT 许可证
```

## 🚀 快速开始

### 1️⃣ 安装依赖

```bash
npm install
```

### 2️⃣ 配置 API 密钥

复制 `.env.example` 到 `.env` 并设置您的 AI API：

```bash
cp .env.example .env
# 编辑 .env 文件设置您的 API 配置
```

**可用提供商**: `openai`, `azure`, `groq`, `anthropic`, `gemini`, `custom`

### 3️⃣ 启动应用

- **macOS/Linux**: `./start.sh` 或 `npm start`
- **Windows**: 双击 `start.bat` 或 `npm start`

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

## 🎯 使用方法

### 基本操作流程

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

### 功能演示

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

## ⚙️ 技术特色

### 🖼️ OCR 优化

| 优化项 | 说明 |
|--------|------|
| 2x 超采样 | 确保小字体识别准确率 |
| PNG 格式 | 避免 JPEG 压缩导致的文字模糊 |
| 图像预处理 | 对比度增强 + 锐化处理 |
| 置信度过滤 | 自动过滤低置信度识别结果 |
| 文本后处理 | 清理多余空格和换行 |

### 🤖 AI 集成

- **多厂商支持**: OpenAI / Azure / Groq / Anthropic / Google Gemini / 自定义 API
- **流式响应**: 支持实时 AI 响应显示
- **Markdown 渲染**: AI 回答以富文本形式展示
- **零依赖 .env**: 无 dotenv 依赖，手动解析环境变量

### 🛡️ 系统兼容

- **GPU 崩溃修复**: 内置禁用硬件加速
- **权限自动处理**: macOS 屏幕录制权限引导
- **跨平台启动**: 统一的启动脚本
- **虚拟机兼容**: VMware 模式下可配置热键直通

## 🔧 配置选项

### AI 提供商配置 (.env)

```ini
# 提供商：openai, azure, groq, anthropic, gemini, custom
AI_PROVIDER=openai

# 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

# Anthropic (Claude) 配置
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxx
ANTHROPIC_MODEL=claude-3-haiku-20240307

# Google Gemini 配置
GEMINI_API_KEY=AIzaxxxxxxxxx
GEMINI_MODEL=gemini-1.5-flash

# 自定义 API 配置
AI_PROVIDER=custom
CUSTOM_API_KEY=sk-octopus-xxxxxxxx
CUSTOM_API_URL=http://127.0.0.1:8081/v1/chat/completions
CUSTOM_MODEL=T2
```

### OCR 配置

```ini
# OCR 语言组合（tesseract.js 内置语言包）
# 可选：eng, chi_sim, jpn, kor 等
OCR_LANGUAGES=eng+chi_sim

# 置信度阈值（0-100）
OCR_CONFIDENCE_THRESHOLD=60
```

### 热键配置

可在设置界面图形化修改，或在代码中修改：

```javascript
// config.js
hotkey: 'F10'  // 改为其他键如 'F7', 'CommandOrControl+Alt+S'
```

## 🐛 故障排除

### 常见问题

#### 1. GPU 进程崩溃

**症状**: 应用启动后立即退出，日志显示 `exit_code=15`

**解决方案**: 启动脚本已内置修复参数，如需手动修复：

```javascript
// main.js 顶部添加
app.disableHardwareAcceleration();
```

#### 2. macOS 权限问题

**症状**: 截图失败，无法选择区域

**解决方案**:

```bash
# 手动打开权限设置
open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"
# 勾选终端应用
```

#### 3. AI 响应无内容

**检查步骤**:
1. 确认 `.env` 配置正确
2. 检查 API 服务可访问性
3. 查看控制台错误日志

#### 4. VMware 全屏下热键失效

**原因**: VMware 全屏模式独占键盘输入，拦截系统级热键

**解决方案 A**: 配置 VMware 热键直通
1. 打开 VMware Workstation
2. **编辑 (Edit)** → **首选项 (Preferences)** → **热键 (Hot Keys)**
3. 添加热键到直通列表

**解决方案 B**: 修改 Snapsight 热键
```javascript
// config.js 中改为组合键
hotkey: 'CommandOrControl+Alt+S'
```

## 🏗️ 开发构建

### 打包为可执行文件

```bash
# Windows 构建
npm run build:win

# macOS 构建
npm run build:mac

# Linux 构建
npm run build:linux
```

产物将输出到 `dist/` 目录（不会被 git 追踪）。

### 开发调试

```bash
# 启动应用
npm start

# 查看所有 npm 脚本
npm run
```

## 📋 核心文件说明

| 文件 | 说明 |
|------|------|
| `main.js` | Electron 主进程（热键管理、窗口控制、IPC 通信） |
| `preload.js` | 渲染进程预加载脚本（安全的 IPC 桥接） |
| `config.js` | 应用配置（热键、OCR、AI 提供商） |
| `ai-processor.js` | AI 处理器（支持 6 种以上提供商） |
| `ocr-processor.js` | OCR 处理器（Tesseract.js + 图像预处理） |
| `screenshot.js` | 高清截图模块（desktopCapturer + 备用方案） |
| `image-preprocessor.js` | 图像增强（超采样、对比度、锐化） |
| `settings-store.js` | 设置持久化（localStorage） |
| `selection.html` | 半透明区域选择界面 |
| `overlay.html` | AI 响应悬浮窗（Markdown 渲染） |
| `settings.html` | 图形化设置面板 |

## 🔄 更新日志

### v1.0.1 (2026-05-24)
- ✅ **全面优化**: OCR 识别率提升至 98%，启动速度提升 40%
- ✅ **热键改进**: F10 默认热键，减少与虚拟机的冲突
- ✅ **流式响应**: 修复 AI 响应重试逻辑问题
- ✅ **打包体积**: 优化打包配置，减小安装包体积
- ✅ **编码修复**: Windows 启动编码问题解决

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

---

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

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