5 分钟上手 agent-vision-toolkit:一句话让 Agent 具备图片问答能力

原创2026-10-14 17:07:211,958 阅读

5 分钟上手 agent-vision-toolkit:一句话让 Agent 具备图片问答能力

agent-vision-toolkit 是一套为纯文本模型 Agent 设计的视觉工具箱与技能包,支持图片问答、长截图 OCR、前端 UI 还原和 GUI 自动化,并可无缝接入 Codex、Claude Code、Pi、OpenCode 等主流 Agent。只需一句话,就能让你的文本模型 Agent「长出眼睛」。

agent-vision-toolkit 图片问答:DeepSeek 查看 UI 截图并回答风格问题

它能解决什么问题?

如果你的 Agent 接入的是 DeepSeek 这类纯文本模型,它会遇到一个尴尬的局面:

  • 用户直接粘贴图片 → 模型看不见;
  • 模型尝试调用看图工具 → 被系统拦下。

agent-vision-toolkit 的思路很直接:视觉能力不一定长在模型上,也可以长在 harness(工具层)上。它提供两类组件:

组件 说明
🧰 视觉工具 CLI glance、ground、detect、trace、crop 等命令行工具,任何能调用 shell 的 Agent 都能用
🪄 无缝接入层(可选) 透明本地代理 + 单文件原生插件,让「粘贴图片」和「内置看图工具」都直接可用

agent-vision-toolkit 多轮图片问答:用 glance 对同一张图连续提问

快速上手: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:直接贴报错界面截图,模型据图定位字段名不匹配的问题。

agent-vision-toolkit focus hint 对比:通用图片描述 vs 任务感知的聚焦描述

它是怎么工作的?focus hint 是关键

大多数「看图桥接」方案只是让多模态模型给一段泛泛的描述,再指望文本模型自己从中拼出信息——每多一层转述,信息就多丢一点。

agent-vision-toolkit 的做法是恢复「Agent 为什么想看这张图」:

  1. 从用户消息或模型的调用理由中提取看图意图(比如「将这个 UI 复刻成 HTML 页面」);
  2. 把意图作为 focus hint 传给视觉模型;
  3. 得到的描述因此聚焦当前这一步真正需要的细节(布局、间距、颜色、文字样式),而不是没有重点的「详细描述」。

结果:更低成本、更高准确率、更快响应。

可选升级:无缝接入,粘贴图片直接生效

如果不想依赖 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 了解最新进展。

登录后查看全文
agent-vision-toolkit