From 8bf77301bd610c72ec2a8c8f8d8e34993ef17601 Mon Sep 17 00:00:00 2001
From: Geliebte <1297754537@qq.com>
Date: Wed, 12 Aug 2026 23:38:21 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20README=E2=80=94?=
 =?UTF-8?q?=E2=80=94=E6=9E=84=E5=BB=BA/=E7=94=A8=E6=B3=95/Claude=20Code=20?=
 =?UTF-8?q?=E5=9C=A8=E7=BA=BF=E8=B0=83=E7=94=A8/MCP=20=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 128 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..de04f32
--- /dev/null
+++ b/README.md
@@ -0,0 +1,128 @@
+# 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 ❤️ — 推理模型专心推理，图片理解交给免费小模型。