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