# vision-tool — 给 Claude Code 装上眼睛 👁️

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

```
用户粘贴图片 → Claude Code 获取路径 → 调用 vision-tool.exe → 免费模型返回文本描述 → Claude Code 基于文本推理
```

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

## ✨ 特性

- 🆓 完全免费（Agnes-2.0-Flash：Input $0 / Output $0）
- 🖼️ 支持多图对比、base64 直传（无需图床/公网 URL）
- 🔁 指数退避自动重试（429/5xx：2s → 5s → 8s → 11s）
- ⚡ `--no-think` 关闭思考模式，响应更快
- 🔧 多源配置：命令行 > 环境变量 > 配置文件 > 内置默认
- 🧩 附带 MCP Server（`mcp-server/`），可接入 MCP 客户端直接调用

## 🚀 快速开始

### 构建

```bash
cd vision-tool
go build -o vision-tool.exe .        # Windows
# go build -o vision-tool .          # Linux / macOS
```

### 基本用法

```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
```

### 参数一览

| 参数 | 说明 |
|---|---|
| `-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 会执行：

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

3. Claude 拿到模型返回的文本描述后，即可基于此进行 UI 分析、代码生成或内容提取。

**权限提示**：可在 Claude Code 配置中允许该命令，或直接执行（首次会询问权限）。

## 🧩 MCP Server（可选）

`mcp-server/` 提供 MCP（Model Context Protocol）服务，可注册到支持 MCP 的客户端：

```bash
cd mcp-server
npm install
node server.js          # stdio 传输，由 MCP 客户端拉起
```

环境变量：`AGNES_API_KEY` / `VISION_MODEL` / `VISION_BASE_URL`。

## ⚙️ 配置优先级

`命令行参数 > 环境变量（AGNES_API_KEY）> 配置文件（config.json）> 内置默认`

config.json 结构：

```json
{
  "api_key": "sk-...",
  "model": "agnes-2.0-flash",
  "base_url": "https://apihub.agnes-ai.com/v1/chat/completions",
  "provider": "agnes"
}
```

## 🧱 项目结构

```
vision-tool/
├── main.go          # CLI 入口（参数解析/调用编排）
├── vision.go        # 视觉 API 客户端（请求构建/重试/多图）
├── config.go        # 配置加载（多源优先级/供应商预设）
├── mcp-server/      # MCP 服务（server.js + package.json）
└── go.mod           # Go 1.25 module
```

## ⚠️ 注意事项

- 支持图片格式：PNG / JPEG / GIF / WebP / BMP
- Windows Git Bash 下经 curl 传中文请用 `--data-binary @file.json`（避免编码损坏）
- 图片过大时建议先压缩（降低延迟与体积）
- API Key 为内置默认值，若需更换：`--apikey` 或 `--save-config`

---

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