# vision-tool — 免费图片识别 👁️

基于 Go 的图片视觉分析工具，对接 **Agnes-2.0-Flash** 免费视觉模型（Sapiens AI）。提供 **Web 在线识别页面** 和 **CLI 工具** 两种形态，适用于 **UI 设计稿分析、布局结构解读、页面内容/文字提取** 等场景。

**核心思路：推理模型专心推理，图片理解交给免费小模型。成本为零。**

## ✨ 特性

- 🆓 完全免费（Agnes-2.0-Flash：Input $0 / Output $0）
- 🌐 Web 在线识别页：拖拽/多图上传 → 识别 → 复制结果
- 🖥️ 独立 CLI 工具（`vision-cli`）：不依赖 Web 服务，适合脚本/Claude Code 调用
- 🖼️ 多图对比、base64 直传（无需图床/公网 URL）
- 🔁 指数退避自动重试（429/5xx：2s → 5s → 8s → 11s）
- 🔧 配置：命令行 > 环境变量 > config.yaml > 内置默认
- 🔑 固定进入密钥（默认 `19735500`），密钥初始化到数据库，页面解锁后使用

## 🚀 快速开始

### 构建

```bash
cd vision-tool
go build -o vision-tool.exe .                    # Web 服务（Windows）
go build -o vision-cli.exe ./cmd/vision-cli      # CLI 工具
# 或直接运行 build.bat / build.sh
```

### Web 使用

```bash
go run .                     # 或 ./vision-tool.exe
# 打开 http://localhost:8080
```

1. 输入进入密钥（默认 `19735500`，存于数据库，可改库更新）解锁页面
2. 拖拽或点击选择图片（可多张）
3. （可选）输入自定义提问
4. 点击「开始识别」→ 得到识别结果，可一键复制

### CLI 使用

```bash
./vision-cli.exe photo.jpg                                # 识别图片
./vision-cli.exe -q --no-think screenshot.png             # 安静模式 + 关闭思考（Claude Code 推荐）
./vision-cli.exe -prompt "提取图中所有文字" img.png
./vision-cli.exe -q img1.png img2.png                     # 多图对比
./vision-cli.exe --apikey YOUR_KEY image.png              # 指定 Key
```

Claude Code 在线调用方式：粘贴图片后执行

```bash
/path/to/vision-cli.exe -q --no-think "/path/to/image.png"
```

## 📡 HTTP API

统一响应格式：`{code, message, data}`（`code=0` 为成功）

### 在线图片识别（免鉴权或带密钥，限流防刷）

```bash
# 免鉴权调用
curl -F "images=@a.png" -F "images=@b.png" \
     -F "prompt=比较这两张图的异同" \
     http://localhost:8080/api/v1/vision/analyze

# 带密钥调用（可选，密钥错误返回 401）
curl -H "X-Access-Key: 19735500" -F "images=@photo.png" \
     http://localhost:8080/api/v1/vision/analyze
```

鉴权规则：请求头 `X-Access-Key`（或表单字段 `access_key`）提供密钥时强制校验，不提供则放行。

响应：

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "result": "……识别结果文本……",
    "images": ["/uploads/xxx.png"],
    "usage": {"prompt_tokens": 120, "completion_tokens": 80, "total_tokens": 200}
  }
}
```

### 完整接口清单

| 接口 | 方法 | 说明 |
|---|---|---|
| `/api/health` | GET | 健康检查 |
| `/api/v1/auth/verify` | POST | 校验进入密钥 `{key}` → `{ok}`（密钥存于数据库） |
| `/api/v1/vision/analyze` | POST | 图片识别（multipart：`images` × 1-N + 可选 `prompt`；可选 `X-Access-Key` 密钥鉴权） |
| `/uploads/*` | GET | 上传图片静态访问 |

## ⚙️ 配置（config.yaml）

```yaml
server:
  port: 8080
database:
  driver: sqlite              # 当前仅 sqlite（pure-go，无需 CGO）
  path: ./data/app.db
  auto_migrate: true
auth:
  access_key: "19735500"      # 进入密钥，首次启动初始化到数据库（可改库更新）
upload:
  path: uploads
  max_size: 10485760          # 10MB
ai:
  api_key: "sk-..."           # Agnes API Key（或环境变量 AGNES_API_KEY）
  base_url: "https://apihub.agnes-ai.com/v1/chat/completions"
  model: "agnes-2.0-flash"
```

配置优先级：`命令行参数 > 环境变量（AGNES_API_KEY）> config.yaml > 内置默认（内置免费 Key）`

## 🧱 项目结构

```
vision-tool/
├── main.go                    # Web 服务入口（Gin + //go:embed web）
├── config.yaml                # 统一配置
├── build.bat / build.sh       # 构建脚本
├── cmd/
│   └── vision-cli/            # 独立 CLI 工具（打包为单个二进制）
├── internal/
│   ├── config/                # 配置加载（yaml + 环境变量覆盖）
│   ├── database/              # GORM + SQLite 初始化 + AutoMigrate + 密钥种子数据
│   ├── model/                 # 数据模型 + 统一响应格式
│   ├── service/               # 业务逻辑（密钥校验 / vision 免费模型调用）
│   ├── handler/               # HTTP 处理器
│   ├── middleware/            # CORS / 令牌桶限流
│   └── router/                # 路由注册 + 前端内嵌 + SPA 回退
└── web/                       # 原生单页（在线图片识别，内嵌进二进制）
    ├── index.html
    ├── css/style.css
    └── js/app.js
```

## ⚠️ 注意事项

- 支持图片格式：PNG / JPG / GIF / WebP / BMP / TIFF
- 单张图片上限 10MB（config.yaml 可调）
- 识别接口免鉴权但有限流（10 req/s），如需生产部署请修改 JWT secret
- 生产环境建议 `auto_migrate: false`，手动管理数据库结构
- 图片过大时建议先压缩（降低延迟与体积）

---

Made with ❤️ — 推理模型专心推理，图片理解交给免费小模型。