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 客户端直接调用

🚀 快速开始

构建

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

基本用法

# 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 会执行：

/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 的客户端：

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 结构：

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