feat: 重构为 Go Web 脚手架——在线图片识别 Web 服务 + vision-cli 独立工具

- Gin + config.yaml + SQLite 后端骨架，JWT 登录 + 管理员初始化 - web/ 原生单页：拖拽多图上传 → Agnes 免费识别 → 结果复制 - HTTP API：/api/v1/vision/analyze 免鉴权 + 令牌桶限流，支持程序直调 - cmd/vision-cli 独立 CLI 工具（复用 service 层，不依赖 Web 服务） - build.bat / build.sh 构建脚本，移除 mcp-server - 统一响应格式 {code, message, data}，CORS/JWT/限流中间件 Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-12 23:59:17 +08:00
parent 8bf77301bd
commit a3bbf33358
25 changed files with 1902 additions and 798 deletions
--- a/README.md
+++ b/README.md
@@ -1,21 +1,18 @@
-# vision-tool — 给 Claude Code 装上眼睛 👁️
+# vision-tool — 免费图片识别 👁️

-基于 Go 构建的图片视觉分析 CLI 工具，对接 **Agnes-2.0-Flash** 免费视觉模型（Sapiens AI）。让 Claude Code 在不消耗昂贵多模态 token 的前提下"看懂"图片——适用于 **UI 设计稿分析、布局结构解读、页面内容/文字提取** 等场景。
+基于 Go 的图片视觉分析工具，对接 **Agnes-2.0-Flash** 免费视觉模型（Sapiens AI）。提供 **Web 在线识别页面** 和 **CLI 工具** 两种形态，适用于 **UI 设计稿分析、布局结构解读、页面内容/文字提取** 等场景。

-```
-用户粘贴图片 → Claude Code 获取路径 → 调用 vision-tool.exe → 免费模型返回文本描述 → Claude Code 基于文本推理
-```
-
-**核心思路：推理模型专心推理，图片理解交给免费小模型。各取所长，成本为零。**
+**核心思路：推理模型专心推理，图片理解交给免费小模型。成本为零。**

 ## ✨ 特性

 - 🆓 完全免费（Agnes-2.0-Flash：Input $0 / Output $0）
- 🖼️ 支持多图对比、base64 直传（无需图床/公网 URL）
+- 🌐 Web 在线识别页：拖拽/多图上传 → 识别 → 复制结果
+- 🖥️ 独立 CLI 工具（`vision-cli`）：不依赖 Web 服务，适合脚本/Claude Code 调用
+- 🖼️ 多图对比、base64 直传（无需图床/公网 URL）
 - 🔁 指数退避自动重试（429/5xx：2s → 5s → 8s → 11s）
- ⚡ `--no-think` 关闭思考模式，响应更快
- 🔧 多源配置：命令行 > 环境变量 > 配置文件 > 内置默认
- 🧩 附带 MCP Server（`mcp-server/`），可接入 MCP 客户端直接调用
+- 🔧 配置：命令行 > 环境变量 > config.yaml > 内置默认
+- 🔒 JWT 登录 + 管理员初始化（脚手架模板能力）

 ## 🚀 快速开始

@@ -23,105 +20,131 @@

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

-### 基本用法
+### Web 使用

 ```bash
-# Claude Code 自动调用分析图片（推荐 -q 只输出结果）
-./vision-tool.exe -q <图片路径>
-
-# 自定义提问（UI 设计分析场景）
-./vision-tool.exe -q -prompt "请分析这张 UI 设计稿：布局结构、配色、组件层级、文字内容" design.png
-
-# 多图对比
-./vision-tool.exe -q screenshot1.png screenshot2.png
-
-# 安静模式 + 关闭思考（Claude Code 推荐组合）
-./vision-tool.exe -q --no-think screenshot.png
-
-# 指定 API Key（或设置环境变量 AGNES_API_KEY）
-./vision-tool.exe --apikey YOUR_KEY image.png
-
-# 持久化保存 Key 到 config.json
-./vision-tool.exe --save-config --apikey YOUR_KEY
+go run .                     # 或 ./vision-tool.exe
+# 打开 http://localhost:8080
 ```

-### 参数一览
+1. 首次访问：初始化管理员账号（右上角）
+2. 拖拽或点击选择图片（可多张）
+3. （可选）输入自定义提问
+4. 点击「开始识别」→ 得到识别结果，可一键复制

-| 参数 | 说明 |
-|---|---|
-| `-q` | 安静模式，只输出模型结果文本（Claude 调用推荐） |
-| `-prompt` | 自定义分析提问（默认：布局/元素/文字/要点结构化分析） |
-| `--no-think` | 关闭 thinking 模式（更快、更低负载） |
-| `--apikey` | API Key（优先于环境变量与配置文件） |
-| `-config` | 指定 config.json 路径 |
-| `--save-config` | 保存 API Key 后退出 |
-| `-provider` | 模型供应商（默认 `agnes`） |
-
-### 默认分析 Prompt（可被 -prompt 覆盖）
-
-> 请详细分析这张图片：1) 整体布局结构（区块划分/层级）2) UI 设计元素（颜色/字体/组件/间距）3) 所有文字内容（逐字提取）4) 交互与视觉要点。以结构化列表输出。
-
-## 🤖 在 Claude Code 中在线调用
-
-1. **构建 exe**：`go build -o vision-tool.exe .`
-2. **调用**：在 Claude Code 会话中，粘贴图片后告诉 Claude 图片的本地路径，Claude 会执行：
+### CLI 使用

 ```bash
-/path/to/vision-tool/vision-tool.exe -q --no-think "/path/to/your/image.png"
+./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
 ```

-3. Claude 拿到模型返回的文本描述后，即可基于此进行 UI 分析、代码生成或内容提取。
-
-**权限提示**：可在 Claude Code 配置中允许该命令，或直接执行（首次会询问权限）。
-
-## 🧩 MCP Server（可选）
-
-`mcp-server/` 提供 MCP（Model Context Protocol）服务，可注册到支持 MCP 的客户端：
+Claude Code 在线调用方式：粘贴图片后执行

 ```bash
-cd mcp-server
-npm install
-node server.js          # stdio 传输，由 MCP 客户端拉起
+/path/to/vision-cli.exe -q --no-think "/path/to/image.png"
 ```

-环境变量：`AGNES_API_KEY` / `VISION_MODEL` / `VISION_BASE_URL`。
+## 📡 HTTP API

-## ⚙️ 配置优先级
+统一响应格式：`{code, message, data}`（`code=0` 为成功）

-`命令行参数 > 环境变量（AGNES_API_KEY）> 配置文件（config.json）> 内置默认`
+### 在线图片识别（免鉴权 + 限流）

-config.json 结构：
+```bash
+curl -F "images=@a.png" -F "images=@b.png" \
+     -F "prompt=比较这两张图的异同" \
+     http://localhost:8080/api/v1/vision/analyze
+```
+
+响应：

 ```json
 {
-  "api_key": "sk-...",
-  "model": "agnes-2.0-flash",
-  "base_url": "https://apihub.agnes-ai.com/v1/chat/completions",
-  "provider": "agnes"
+  "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/admin/check` | GET | 管理员是否已初始化 |
+| `/api/v1/admin/init` | POST | 初始化管理员 `{username, password}` |
+| `/api/v1/auth/login` | POST | 登录 `{username, password}` → `{token}` |
+| `/api/v1/user/profile` | GET | 当前用户信息（需 `Authorization: Bearer <token>`） |
+| `/api/v1/vision/analyze` | POST | 图片识别（multipart：`images` × 1-N + 可选 `prompt`） |
+| `/uploads/*` | GET | 上传图片静态访问 |
+
+## ⚙️ 配置（config.yaml）
+
+```yaml
+server:
+  port: 8080
+database:
+  driver: sqlite              # 当前仅 sqlite（pure-go，无需 CGO）
+  path: ./data/app.db
+  auto_migrate: true
+jwt:
+  secret: "change-me-in-production"
+  expire_hours: 720
+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          # CLI 入口（参数解析/调用编排）
-├── vision.go        # 视觉 API 客户端（请求构建/重试/多图）
-├── config.go        # 配置加载（多源优先级/供应商预设）
-├── mcp-server/      # MCP 服务（server.js + package.json）
-└── go.mod           # Go 1.25 module
+├── 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/                 # 数据模型 + 统一响应格式
+│   ├── repository/            # 数据访问层
+│   ├── service/               # 业务逻辑（auth / vision 免费模型调用）
+│   ├── handler/               # HTTP 处理器
+│   ├── middleware/            # CORS / JWT / 令牌桶限流
+│   └── router/                # 路由注册 + 前端内嵌 + SPA 回退
+└── web/                       # 原生单页（在线图片识别，内嵌进二进制）
+    ├── index.html
+    ├── css/style.css
+    └── js/app.js
 ```

 ## ⚠️ 注意事项

- 支持图片格式：PNG / JPEG / GIF / WebP / BMP
- Windows Git Bash 下经 curl 传中文请用 `--data-binary @file.json`（避免编码损坏）
+- 支持图片格式：PNG / JPG / GIF / WebP / BMP / TIFF
+- 单张图片上限 10MB（config.yaml 可调）
+- 识别接口免鉴权但有限流（10 req/s），如需生产部署请修改 JWT secret
+- 生产环境建议 `auto_migrate: false`，手动管理数据库结构
 - 图片过大时建议先压缩（降低延迟与体积）
- API Key 为内置默认值，若需更换：`--apikey` 或 `--save-config`

 ---