纯文本模型视觉工具箱 Anionex/agent-vision-toolkit

agent-vision-toolkit

它想到什么，就看到什么 —— 给任何纯文本编程智能体装上眼睛：图像问答、长截图 OCR、前端 UI 还原、GUI 自动化，打包成一套视觉工具集加一个技能，还能按需接入 Codex、Claude Code、Pi、Oh My Pi 和 OpenCode。

🎯 智能体的视觉能力不必长在模型里 —— 它可以长在 harness 里。

🌐 中文 ｜ English

如果你的智能体跑在 DeepSeek 这类纯文本模型上，却因为缺少多模态能力处处受限 —— 看不了图片，每次想调用图像工具都被系统拦下 —— 这个仓库提供的工具、技能和代理集成，能让纯文本模型处理视觉任务时表现持平甚至更好。目标是让用文本模型的智能体体验起来和用多模态模型一样顺滑，最终让一个配上工具的文本模型智能体，胜过不用这套工具集和方法的原生多模态智能体。

这个仓库提供两类组件：
1. 视觉工具命令行 —— 多个命令行工具，外加一个技能，教智能体什么时候该用哪一个。任何能调用 shell 的智能体都能用。
2. 无缝集成（可选升级）—— 透明本地代理加单文件原生插件，让你粘贴的图片和智能体内置的图片工具都能顺畅工作，不用额外装工具，也不用额外写提示词。

所有代码都在真实的 Codex + DeepSeek 会话里验证过，同一条流水线也在 Claude Code、Pi、Oh My Pi 和 OpenCode 里做过端到端实测。

如果这个项目帮到了你，或者给了你一些启发，欢迎 star🌟 & fork。

❤️ 赞助

想赞助这个项目？看 FUNDING.md，或发邮件到 davidyang042@gmail.com。

点击折叠

感谢 AIHubMix 赞助这个项目！AIHubMix 是稳定、高并发的 AI 模型 API 网关，用一个 API key 就能接上 Claude、GPT、Gemini、DeepSeek 等主流模型，兼容多种协议，还有免费模型可选。国内用户走国内入口，海外用户走全球入口。

感谢 E-API 赞助这个项目！E-API 把主流 AI 模型聚合在 OpenAI、Anthropic 和 Codex 兼容的 API 后面，精选 Claude 模型价格比官方便宜最多 98%，DeepSeek V4 模型比官方便宜约 25%。

最新更新

2026-08-18 — 技能改名： 内置的智能体技能现在叫 vision-skills（原名 vision-tools），这样名字描述的是能力，而不是底层工具。

2026-08-13 — 原生 DeepSeek Harness 支持现已可用。 新关联的包 dsh-vision-toolkit 把这套工具包作为原生 Profile Bundle 带进 DSH Web 和 Headless 配置档。它提供 10 个结构化视觉工具，覆盖意图感知的图片问答、定位、检测、描迹、裁剪、像素 diff、长截图 OCR、前景提取、主色分析和 HTML 截图，同时加入 DSH Credentials、托管隔离运行时、可预览 Artifacts、Web Settings，以及按智能体作用域渐进暴露工具。

这个包在这里以 Git submodule 的形式跟踪，并在 Anionex/dsh-vision-toolkit 独立维护。克隆本仓库时加上 --recurse-submodules，或者在已有检出里运行 git submodule update --init --recursive。

目录

- 最新更新
- 亮点
- 用例实战手册
- 实际效果
- 快速开始
- 工具一览
- 升级：无缝集成
- 工作原理
- 配置
- 常见问题
- 捐赠
- 社区
- 关于

亮点

- 不只是描述图片——它抓住 LLM 真正关心的内容：查看图片时，它会带上用户或模型最新的意图，产出当前这一轮需要的细节，而不是泛泛而谈、抓不住重点的描述。
- 粘贴的图片和内置图片工具都能用：智能体既能理解直接粘贴的图片，也能理解通过内置工具打开的图片。
- 一套久经考验的视觉任务方法论：随附的技能会教智能体该看什么、选哪个工具、按什么顺序走、怎么验证最终结果。
- 一句话安装：让你的智能体去装就行——它会从头到尾走完验证过的流程，工具包、技能、无缝集成全都包含在内。

用例实战手册

随附的 vision-skills 技能里有完整示例，智能体可以直接照着做。
什么时候用、按什么顺序调用工具、怎么验证结果，都写在对应的技能指南里：

| 用例 | 智能体学会做什么 |
| 提取长截图、聊天记录和滚动页面 | 找出内容稀少的切割带，按顺序对每一块做 OCR，保留聊天发言人/时间戳/引用，只合并重复的重叠部分，并把有风险的边界标出来供验证。查看 Telegram 参考运行 → |
| 根据截图或设计稿重建 UI | 优先复用项目组件和素材，再结合代码原生 UI、提取出的视觉元素、渲染截图和视觉比对，把页面或组件对齐。 |
| 还原图标、logo、插画或其他图形 | 从源图提取透明 PNG，需要时重建可编辑/可缩放的 SVG，再验证形状、颜色和 alpha 边缘。 |
| 把草图、示意图或白板变成结构化代码 | 把节点、标签、连线和方向还原成可编辑的 Mermaid、Graphviz 或其他结构化表示。 |
| 通过截图操作 GUI | 定位控件，执行一个动作，再次截屏，验证结果状态后再继续。 |
| 更多用例 | 其他一步步指导的视觉智能体实战手册正在陆续补充。 |

实际效果

信息图还原：一句话把截图变成 HTML

左：原始信息图截图。右：用 HTML/CSS 重建的可编辑版本。查看 HTML 源码 →

UI 还原：一句话把草图变成界面

左：手绘参考图。右：照着它还原出的 JupyterLab 工作区。工作流见 UI 还原手册。在 Codex 中用 deepseek-v4-flash 执行。

快速 UI 还原：先出一版近似稿

左：原始页面。右：快速重建版，保留主要布局、内容和视觉层级，颜色和图标库允许近似。快速模式的目标是约三分钟出第一张截图。

左：用 glance 做多轮图像问答。右：配合 ground，DeepSeek V4 定位屏幕元素，自主下棋。

左：DeepSeek V4 回答 UI 风格问题，并给出相似风格对比。右：DeepSeek V4 根据截图排查字段名不匹配的问题。

快速开始

最简单的安装方式，是把下面这段话发给你的智能体：

按照 https://github.com/Anionex/agent-vision-toolkit 里的说明，在本地安装 vision 工具包和技能。如果 vision API 还没配置，找到当前操作系统的配置文件，引导我设置 VISION_API_KEY、VISION_BASE_URL 和 VISION_MODEL。
如果你也想要可选的 seamless 集成层，发送这段：

完整阅读 https://github.com/Anionex/agent-vision-toolkit/blob/main/AGENT_INSTALL.md，然后为我们当前使用的智能体应用安装合适的视觉代理或原生扩展/插件。如果视觉 API 还没配置，找到当前操作系统的配置文件，引导我设置 VISION_API_KEY、VISION_BASE_URL 和 VISION_MODEL。

你只需要准备一个多模态 API，支持 OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages，再加上它的 base URL、API key 和模型名。智能体会引导你把这些写进对应的配置文件。

装好可选集成并重启智能体后，直接粘贴图片，或者让模型调用它内置的图片工具。Pi、Oh My Pi 和 OpenCode 用的是单文件原生扩展，不是代理；具体看各智能体的文档。

三步手动安装

1. 让它指向视觉 API —— 在 ~/.config/agent-vision-toolkit/env 里写三个环境变量（chmod 600）：

VISION_API_KEY=sk-...
VISION_BASE_URL=https://openrouter.ai/api/v1
VISION_MODEL=google/gemini-3.6-flash

任何兼容 OpenAI、支持 /chat/completions 带 image_url 的端点都能用（比如阿里云 DashScope：https://dashscope.aliyuncs.com/compatible-mode/v1 + qwen-vl-max-latest）。Python 客户端/代理也可以走 /responses 配 input_image，只要设置 VISION_API_PROTOCOL=responses；或者走 Anthropic Messages，设置 VISION_API_PROTOCOL=anthropic，base URL 以 /v1 结尾（不是 /messages）。加上 LANG=en 可以输出英文描述（默认是中文）。

2. 把命令行工具放进 PATH：

git clone https://github.com/Anionex/agent-vision-toolkit.git
export PATH="$PWD/agent-vision-toolkit/bin:$PATH" # add to your shell profile to persist

glance 除了 Python 3.11+ 什么都不需要；ground/detect/crop 和长截图 OCR playbook 需要 pillow；trace 需要 pillow + numpy（vtracer 只在显式使用 --outline 兜底时才需要）。可选依赖装进独立的 venv，只装你用到的工具。

3. 安装技能，让智能体知道这些工具存在、以及怎么组合使用：

npx skills add Anionex/agent-vision-toolkit --skill vision-skills -a codex -g --copy -y

或者把 skills/vision-skills/ 复制进智能体的技能目录（比如 ~/.codex/skills/），然后重启智能体。

工具

一组为智能体设计的视觉工具，让它们根据情况自由选择：

glance —— 「这张图长什么样？」

直接对图片提问，或者转写它的文字。

glance screenshot.png -q "What is the dominant color of this image?"
glance screenshot.png --ocr

这张图的主色调是白色和浅灰色，点缀浅蓝色。

Username
Password
Login

如果是滚动截图或聊天记录，技能里包含一套工作流：找出安全的切割带，用 glance 对分块做 OCR，合并重叠部分，并写出边界审计：

python3 skills/vision-skills/scripts/long_screenshot_ocr.py long-chat.png --mode chat -o long-chat.ocr.md

ground — 「我想要的对象在哪里？」

定位对象或区域，拿到原始像素坐标下的边界框：

ground screenshot.png "Send button"

x1: 1067, y1: 841, x2: 1108, y2: 881

每次调用分析一整张图。加上 --region X1,Y1,X2,Y2 后只搜索该框，但报告的仍是原图坐标——这是针对小目标的放大路径。

detect — 「图里有什么，在哪里？」

默认清点截图（或某个区域）里的 UI 元素——一份带编号的列表，包含精确的可见文本和像素框。对于照片或视频帧，指定类别如 "objects" 或 "text"，避开默认的 UI 框架：

detect page.png
detect page.png "buttons"
detect page.png --region 238,600,953,671
detect frame.png "text" --fail-on-empty

1. bottom-left Do anything x1: 253, y1: 601, x2: 328, y2: 609
2. bottom-left + x1: 254, y1: 650, x2: 268, y2: 665
3. bottom-right stop button x1: 924, y1: 645, x2: 952, y2: 670

默认情况下，空清单会向 stdout 打印 no elements detected 并以 0 退出，以保持兼容。加上 --fail-on-empty 后，改为向 stderr 打印 detect: no elements detected 并以 1 退出，stdout 无输出，这样脚本就能检测到空结果。这表示结果为空；它不能证明图中没有匹配的元素，也不能验证模型的标签。

全屏扫描是快速的初稿；要在密集屏幕上做到完整，就逐区域清点。

trace — 「它干净的几何轨迹是什么？」

trace 在局部、确定性地恢复扁平高对比度图形的中心线，然后拟合可编辑的 SVG 图元，如 <circle>、<line>、<polyline>、<polygon>。它还会把紧凑的实心圆形标记保留为填充圆，并让闭合曲线环保持完整。放大镜变成一个圆加一条线；闪电笔画变成它实际的直线段，而不是沿着栅格墨迹两侧的噪杂路径。内部放大能改善小图标，同时 SVG 仍留在源图像的坐标网格里。LLM 不参与这次拟合：DeepSeek 这样的智能体只负责编排周边的定位、裁剪、渲染和验证步骤。只有当你明确需要填充的外轮廓时才用 --outline（该回退方案需要 vtracer）。

trace icon.png -o icon.svgbash
trace screenshot.png --region 1563,514,1668,621 -o icon.svg
trace filled-artwork.png --outline -o silhouette.svg

crop —「裁出这块图像区域，方便复用」

crop 把图像里的一块像素区域裁成单独文件——用的就是 ground/detect 打印的那套 X1,Y1,X2,Y2 坐标，并限制在图像边界内。同一块区域马上要喂给多个检查（pixel_diff、dominant_colors、trace）时，裁一次、复用文件，别每次调用都在内存里重新裁。需要可选的 pillow。
bash
crop screenshot.png --region 1563,514,1668,621 -o send-button.png

升级：无缝集成

这一层让粘贴进智能体的截图直接可用，同时避免智能体调用内置图像工具时报错。

| 智能体 | 方式 | 状态 |
| Codex | 透明的本地代理（Responses API） | ✅ 已验证 |
| Claude Code | 同一个代理——把 ANTHROPIC_BASE_URL 指向它 | ✅ 已验证 |
| Pi / Oh My Pi | 单文件原生扩展（extensions/pi/） | ✅ 已验证 |
| OpenCode | 单文件原生插件（extensions/opencode/） | ✅ 已验证 |
| 任何带 shell 的智能体 | 用上面的工具集——无需集成 | ✅ |

所有入口共用一份配置。配置一次，处处可用。

工作原理

让描述始终盯住任务

面向纯文本模型的视觉桥接，大多只是让多模态模型把图像转成一段泛泛的描述，再把这段描述交给文本模型，指望它自己还原出需要的信息。这多了一层语义转换，信息难免丢失——于是就有了那种常见的说法：东拼西凑的视觉方案必然要吃很大的性能亏。

为此，agent-vision-toolkit 试着还原智能体为什么要看这张图。它从用户消息里、或从模型调用内置图像工具时给出的理由里，提取出看图意图，再把这份意图作为焦点提示传给视觉模型。得到的是一段任务感知的描述，突出当前步骤真正要紧的内容，而不是泛泛的「详细描述」——成本更低、准确率更高、响应更快。

请求流程与协议细节 text Codex -> 127.0.0.1:19100 -> your existing text-only upstream

+-- when the request contains images:
focus hint (the user's request, or the assistant's
调用 view_image 的声明原因） -> 视觉提示词 -> 文本描述 -> 图片被替换

配置

环境变量

独立命令行工具和 Python 代理使用这些环境变量；只有三个是必填的。原生 Pi 和 OpenCode 扩展使用各自的设置，目前只调用 /chat/completions。

| 变量 | 必填 | 说明 |
| VISION_API_KEY | 是 | 多模态模型的 API key |
| VISION_BASE_URL | 是 | 服务商 API 基础 URL；要包含 /v1，但不要包含 /messages 这类协议端点 |
| VISION_MODEL | 是 | 多模态模型名称 |
| LANG | 否 | 视觉模型输出语言：zh（中文）或 en（英文）；默认 zh |
| VISION_API_PROTOCOL | 否 | Python 客户端/代理协议：chat_completions（默认）、responses 或 anthropic；Anthropic 模式使用 x-api-key 和 anthropic-version |
| VISION_REASONING_EFFORT | 否 | 可选，服务商支持的推理强度，用于 Python 客户端/代理使用 responses 时 |
| VISION_ANTHROPIC_THINKING | 否 | Anthropic 思考模式。omit（默认）不发送 thinking 字段，兼容性最广。只有当所选模型明确支持该模式时，才用 disabled 或 adaptive；如果服务商返回 HTTP 400，先恢复 omit。不开放手动 enabled 加 budget_tokens。 |
| VISION_USER_AGENT | 否 | Python 客户端/代理的出站 User-Agent；默认使用兼容浏览器的值，可按服务商要求覆盖 |

上游出口

代理默认直接连接你的模型主机（TCP + TLS），从不读取 Windows 系统代理，所以 Clash 这类本地代理挂掉不会拖垮整条链路。显式代理是可选的：

- --upstream-proxy http://127.0.0.1:7890（或环境变量 VISION_UPSTREAM_PROXY）通过 CONNECT 隧道把上游流量走该代理。
- --proxy-first（或环境变量 VISION_PROXY_FIRST=1）先试显式代理再直连；默认顺序是先直连。

连接（TCP/TLS 握手）成功的路由会留在内存里复用；只有建立连接失败（拒绝 / DNS / TLS / 5s socket 超时）才切换路由，模型返回的 HTTP 状态错误原样透传。如果所有路由都失败，代理返回 502，并列出每条路由及原因。HTTP 代理 URL 不带显式端口时使用标准端口 80；不支持代理认证。

前置条件

- 一个已经能配合模型工作的编码智能体，包括 DeepSeek V4 这类纯文本模型
- 一个支持 OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages 的视觉 API；后两者用 VISION_API_PROTOCOL=responses 或 VISION_API_PROTOCOL=anthropic 选择
- 不需要其他配置

常见问题

把 base_url 指向本地代理后，代理还需要上游模型的 API key 吗？

不需要。虽然发往上游的网络请求由 127.0.0.1:19100 上的代理进程发出，但上游 API key 仍由 Codex 按你现有的配置放进 Authorization 头，代理原样转发这个头： text Codex（携带原始 Authorization） -> 127.0.0.1:19100 -> 纯文本上游（收到未改动的 Authorization）

所以别改 Codex 现有的认证配置，也别在代理环境里再存一遍上游 API key。代理环境只需要 VISION_API_KEY、VISION_BASE_URL 和 VISION_MODEL。

再加一个多模态模型会大幅增加成本吗？

不会。主模型每次需要查看图片时，vision 工具只把必要的意图和图片送进多模态模型的上下文。另外还有截断机制，不会出现上下文过长或不断累积的情况，成本能压得很低。

想进一步降成本，可以用本地部署的小型多模态旁路模型来提供视觉能力。推荐 Gemma 4 和 Qwen 3.5/3.6 系列。

限制

- 这是一层图生文，不会把视觉 token 直接交给文本模型。
- 视觉任务的整体质量由主 LLM 和多模态 LLM 共同决定。
- 代理的缓存只存在于进程内，重启即清空。

捐赠

如果这个项目对你有价值，欢迎请开发者喝杯咖啡 ☕️

社区

- 安装与使用帮助：支持指南 和仓库的 issue 表单
- Bug 反馈与功能请求：Issues
- 贡献代码：贡献指南
- 安全报告：安全政策
- 社区规范：行为准则
- 面向用户的变更：更新日志

关于

如果 agent-vision-toolkit 帮你省下了时间，欢迎给它点个 star、分享、贡献代码，或者赞助这个项目。

我是 anionex，一名 AI 原生开发者，曾在 GitHub 全球开发者趋势榜上排到第 4，我的项目累计收获 16k 以上 star。想跟进我后续的作品，可以在 X 上关注我或关注我的 GitHub。

加入社区群

欢迎加入 agent-vision-toolkit 社区群，交流使用技巧、反馈问题、提出改进建议。扫描下方二维码加入。