vision-tool/README.md

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），密钥初始化到数据库，页面解锁后使用

🚀 快速开始

构建

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 使用

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

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

CLI 使用

./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 在线调用方式：粘贴图片后执行

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

📡 HTTP API

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

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

# 免鉴权调用
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）提供密钥时强制校验，不提供则放行。

响应：

{
  "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）

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 ❤️ — 推理模型专心推理，图片理解交给免费小模型。