5 分钟上手 agent-vision-toolkit:一句话让 Agent 具备图片问答能力
5 分钟上手 agent-vision-toolkit:一句话让 Agent 具备图片问答能力
agent-vision-toolkit 是一套为纯文本模型 Agent 设计的视觉工具箱与技能包,支持图片问答、长截图 OCR、前端 UI 还原和 GUI 自动化,并可无缝接入 Codex、Claude Code、Pi、OpenCode 等主流 Agent。只需一句话,就能让你的文本模型 Agent「长出眼睛」。
它能解决什么问题?
如果你的 Agent 接入的是 DeepSeek 这类纯文本模型,它会遇到一个尴尬的局面:
- 用户直接粘贴图片 → 模型看不见;
- 模型尝试调用看图工具 → 被系统拦下。
agent-vision-toolkit 的思路很直接:视觉能力不一定长在模型上,也可以长在 harness(工具层)上。它提供两类组件:
| 组件 | 说明 |
|---|---|
| 🧰 视觉工具 CLI | glance、ground、detect、trace、crop 等命令行工具,任何能调用 shell 的 Agent 都能用 |
| 🪄 无缝接入层(可选) | 透明本地代理 + 单文件原生插件,让「粘贴图片」和「内置看图工具」都直接可用 |
快速上手:5 分钟安装步骤
一句话安装(推荐)
最简单的方式,是把下面这句话直接发给你的 Agent,它会沿着已验证流程把工具箱、skill 和配置一次装好:
根据 https://gitcode.com/gh_mirrors/ag/agent-vision-toolkit 的仓库指引,在本地安装视觉工具箱和 skill。如果视觉 API 尚未配置,请按当前系统找到配置文件,并引导我填写
VISION_API_KEY、VISION_BASE_URL和VISION_MODEL。
你唯一需要准备的是:一个支持 OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages 的多模态 API,外加它的 base URL、API key 和模型名。Agent 会引导你把它们写入配置文件。
三步手动安装
如果想自己动手,总共三步:
1️⃣ 指向一个视觉 API — 在 ~/.config/agent-vision-toolkit/env 写入三个环境变量:
VISION_API_KEY=sk-...
VISION_BASE_URL=https://openrouter.ai/api/v1
VISION_MODEL=google/gemini-3.6-flash
2️⃣ 把 CLI 放进 PATH:
git clone https://gitcode.com/gh_mirrors/ag/agent-vision-toolkit.git
export PATH="$PWD/agent-vision-toolkit/bin:$PATH"
3️⃣ 安装 skill,让 Agent 知道这些工具存在、该什么时候用哪个:
npx skills add Anionex/agent-vision-toolkit --skill vision-skills -a codex -g --copy -y
💡
glance只需 Python 3.11+;ground/detect/crop和长截图 OCR 需要pillow。按需安装即可。
核心工具一览:Agent 会怎么选?
工具按「你在回答什么问题」来选,这也是随包 vision-skills skill 教给 Agent 的第一课:
| 你的问题 | 工具 |
|---|---|
| 「这张图是什么 / 写了什么?」 | glance(图片问答、OCR) |
| 「X 在哪?」 | ground(定位目标,返回像素坐标) |
| 「图里所有 X 都在哪?」 | detect(元素清单) |
| 「它的确切形状轨迹?」 | trace(本地恢复几何轨迹并生成 SVG) |
| 「把这个区域裁出来?」 | crop(按坐标导出子图文件) |
一个典型的两步组合:先用 ground 定位小目标,再用 glance --region 放大细看:
ground screenshot.png "发送按钮"
# x1: 1067, y1: 841, x2: 1108, y2: 881
glance screenshot.png --region 1067,841,1108,881 -q "它是可点击的还是灰色禁用?"
除了核心 CLI,skills/vision-skills/ 目录还内置了长截图 OCR、UI 还原、图形素材还原、GUI 自动化等可直接照做的用例手册,例如 references/long-screenshot-ocr.md 和 references/restore-ui.md。
实际效果:图片问答长什么样?
装上之后,直接对 Agent 说「这张界面是什么风格」即可。下面是真实会话中的效果:
- 🗣️ 多轮图片问答:对同一张截图连续追问,上下文由 Agent 自己维护;
- 🎯 定位 + 自动化:配合
ground,DeepSeek V4 能定位屏幕元素,甚至自主下国际象棋; - 🐛 看图排查 bug:直接贴报错界面截图,模型据图定位字段名不匹配的问题。
它是怎么工作的?focus hint 是关键
大多数「看图桥接」方案只是让多模态模型给一段泛泛的描述,再指望文本模型自己从中拼出信息——每多一层转述,信息就多丢一点。
agent-vision-toolkit 的做法是恢复「Agent 为什么想看这张图」:
- 从用户消息或模型的调用理由中提取看图意图(比如「将这个 UI 复刻成 HTML 页面」);
- 把意图作为 focus hint 传给视觉模型;
- 得到的描述因此聚焦当前这一步真正需要的细节(布局、间距、颜色、文字样式),而不是没有重点的「详细描述」。
结果:更低成本、更高准确率、更快响应。
可选升级:无缝接入,粘贴图片直接生效
如果不想依赖 Agent 主动调 CLI,可以再加一层「无缝接入」,装完重启后直接粘贴图片即可,内置看图工具也不再报错:
| Agent | 接入方式 | 状态 |
|---|---|---|
| Codex | 透明本地代理(Responses API) | ✅ 已验证 |
| Claude Code | 同一个代理,改指 ANTHROPIC_BASE_URL |
✅ 已验证 |
| Pi / Oh My Pi | 单文件原生扩展 extensions/pi/ | ✅ 已验证 |
| OpenCode | 单文件原生插件 extensions/opencode/ | ✅ 已验证 |
| 任何能开 shell 的 Agent | 上面的工具箱,无需接入层 | ✅ |
所有入口共用同一份配置,配一次、到处用。完整部署指引见 AGENT_INSTALL.md。
常见问题(FAQ)
Q:接上本地代理后,代理还需要上游模型的 API key 吗?
不需要。代理只负责把图片换成文字描述后原样转发,上游鉴权仍由你的 Agent 配置发送,代理环境里只需要 VISION_API_KEY、VISION_BASE_URL、VISION_MODEL 三个视觉配置。
Q:多一个多模态模型,成本会不会暴增?
不会。每次看图只发送「必要意图 + 图片」给视觉模型,且有截断机制防止上下文膨胀。预算有限时,还可以用本地部署的小型多模态模型(如 Gemma、Qwen 系列)充当视觉后端。
Q:有什么限制?
这是一层「图片转文字」桥接,不直接给文本模型喂视觉 token;最终视觉任务质量由主模型和视觉模型共同决定。详见 README.md 的 Limitations 章节。
🌟 总结:5 分钟、一句话,纯文本模型 Agent 就能获得图片问答、长图 OCR、UI 还原和 GUI 自动化能力。更多实跑示例可参考 examples/long-screenshot-ocr/(780×31186 的 Telegram 长截图,OCR 记录 180/180 全对)和 CHANGELOG.md 了解最新进展。


