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

agent-vision-toolkit

X (Twitter)
GitHub stars
GitHub forks
License: MIT

Agent Skills
Extensions
Shell

它所想即所见——为任何纯文本编码智能体赋予眼睛：图像问答、长截图 OCR、前端 UI 还原以及 GUI 自动化，以视觉工具包加技能的形式提供，并可选地即插即用地集成到 Codex、Claude Code、Pi、Oh My Pi 和 OpenCode 中。

🎯 智能体的视觉能力不必存在于模型之中——它可以存在于运行框架之中。

🌐 中文 ｜ English

如果你的智能体已经运行在诸如 DeepSeek 这样的纯文本模型上，却因缺乏多模态能力而受限——无法查看图像，每次尝试使用图像工具都被系统阻止——本仓库提供的工具、技能和代理集成能让纯文本模型在视觉任务上拥有同等甚至更出色的表现。目标是让使用文本模型智能体的体验与使用多模态智能体一样顺畅，并最终让配备工具的文本模型智能体超越未使用本工具包及其方法的原生多模态智能体。

本仓库提供两类组件：
1. 视觉工具 CLI —— 多个 CLI，外加一个教导智能体何时使用哪一个的技能。任何能够调用 shell 的智能体都可以使用它们。
2. 无缝集成 (可选升级) — 一个透明的本地代理和单文件原生插件，因此我们粘贴的图片和智能体内置的图像工具都能无缝工作，无需额外安装工具或额外提示。

所有代码均已在真实的 Codex + DeepSeek 会话中验证，同一流水线也已在 Claude Code、Pi、Oh My Pi 和 OpenCode 中完成端到端实机验证。

如果这个项目对你有帮助，或者给了你一些启发，欢迎 star🌟 和 fork。

❤️ 赞助

想要赞助这个项目？请查看 FUNDING.md 或发送邮件至 davidyang042@gmail.com。

点击折叠

感谢 AIHubMix 赞助本项目！AIHubMix 是一个稳定、高并发的 AI 模型 API 网关，通过单个 API 密钥即可连接 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 个结构化视觉工具，用于意图感知图像问答、定位、检测、描摹、裁剪、像素差异、长截图 OCR、前景提取、主色分析和 HTML 截图，同时新增 DSH Credentials、托管隔离运行时、可预览 Artifacts、Web 设置以及智能体作用域的渐进式工具暴露。

该包在此处作为 Git 子模块进行跟踪，并在 Anionex/dsh-vision-toolkit 独立维护。使用 --recurse-submodules 克隆此仓库，或在现有检出中运行 git submodule update --init --recursive。

目录

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

亮点

- 不止于图像描述——它捕捉的是 LLM 真正关心的内容：在查看图像时，它会一并传递用户或模型的最新意图，从而生成当前轮次所需的细节，而不是宽泛、无重点的描述。
- 粘贴的图像和内置图像工具都能用：智能体既能理解直接粘贴的图像，也能理解通过其内置工具打开的图像。
- 一套经过实战检验的视觉任务方法论：随附的技能会教智能体该检查什么、该选择哪个工具、该遵循什么顺序，以及如何验证最终结果。
- 一句话安装：让你的智能体来安装它——它会端到端地遵循经过验证的流程，包括工具包、技能和无缝集成。

用例操作手册

随附的 vision-skills 技能包含智能体可以直接遵循的完整示例。
何时使用它们、按什么顺序调用工具，以及如何验证结果，都记录在相应的技能指南中：

| 用例 | 智能体将学会做什么 |
|---|---|
| 提取长截图、聊天记录和滚动页面 | 找到低内容切割带，按顺序对每个分块进行 OCR，保留聊天发言人/时间戳/引用，仅合并重复的重叠部分，并标出有风险的边界以供验证。查看 Telegram 参考运行 → |
| 根据截图或设计稿重建 UI | 优先复用项目组件和资源，然后结合代码原生 UI、提取的视觉元素、渲染截图和视觉对比来对齐页面或组件。 |
| 还原图标、徽标、插画或其他图形 | 从源图像中提取透明 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 根据截图调试字段名不匹配问题。

快速开始

最简单的安装方式是将以下内容发送给你的 agent：

按照 https://github.com/Anionex/agent-vision-toolkit 中的说明在本地安装视觉工具包和技能。如果视觉 API 尚未配置，请找到当前操作系统的配置文件，并引导我设置 VISION_API_KEY、VISION_BASE_URL 和 VISION_MODEL。
如果你还想要可选的无缝集成层，请发送以下内容：

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

你需要准备的只是一个支持 OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages 的多模态 API，以及它的 base URL、API key 和模型名称。agent 会引导你将它们写入合适的配置文件。

安装可选集成并重启 agent 后，直接粘贴一张图片，或让模型调用其内置的图像工具。Pi、Oh My Pi 和 OpenCode 使用单文件原生扩展，而不是代理；请参阅各个 agent 的文档。

三步手动安装

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

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

2. 将 CLI 添加到你的 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 操作手册需要 pillow；trace 需要 pillow + numpy（仅在其显式 --outline 回退时需要 vtracer）。请仅为你使用的工具将可选依赖安装到隔离的 venv 中。

3. 安装该 skill，让你的 agent 知道这些工具的存在以及如何组合使用它们：

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

或者将 skills/vision-skills/ 复制到你的 agent 的 skills 目录（例如 ~/.codex/skills/）并重启 agent。

工具

一组为 agent 设计的视觉工具，让它们可以根据情况自由选择：

glance —— “这张图片看起来是什么样的？”

直接对图片提问，或转录其中的文本。

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

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

用户名
密码
登录

对于滚动截图或聊天记录，该技能包含一个工作流，
用于查找安全的切割带，使用 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 — “图像中有什么，在哪里？”

清点图像（或区域）中的元素——一个带有精确可见文本和像素框的编号列表：

detect page.png
detect page.png "buttons"
detect page.png --region 238,600,953,671

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

全屏扫描是快速的初稿；对于密集屏幕要保证完整性，请逐区域清点。

trace — “它干净的几何轨迹是什么？”

trace 以局部且确定性的方式恢复扁平、高对比度图形的中心线，然后拟合可编辑的 SVG 图元，例如 、、 和 。它还会将紧凑的实心圆形标记保留为填充圆，并保持闭合曲线环完整。放大镜会变成一个圆加一条线；闪电笔画会变成其实际的直线段，而不是围绕栅格墨迹两侧的噪声路径。内部放大可改善小图标，同时 SVG 仍保持在源图像的坐标网格中。LLM 不参与此拟合：像 DeepSeek 这样的代理只编排周围的定位、裁剪、渲染和验证步骤。仅当你明确需要填充的外轮廓时才使用 --outline（该回退方案需要 vtracer）。

trace icon.png -o icon.svg
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。

crop screenshot.png --region 1563,514,1668,621 -o send-button.png

升级：无缝集成

这一层让粘贴到 agent 中的截图可以直接使用，同时还能在 agent 调用其内置图像工具时防止出错。

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

所有入口点共享同一份配置。配置一次，即可处处使用。

工作原理

让任务始终在视野中的描述

大多数面向纯文本模型的视觉桥接方案，只是让多模态模型把图像转成一段通用描述，然后把这段描述交给文本模型，并期望它重建出所需的信息。这会额外增加一层语义，其中不可避免地会丢失一些信息——这正是人们普遍认为拼凑而成的视觉方案必然要承受巨大性能损失的原因。

为了解决这个问题，agent-vision-toolkit 尝试还原 agent 为什么要查看这张图像。它从用户消息中，或从模型调用内置图像工具时所述的理由中提取查看意图，然后将该意图作为 焦点提示 传给视觉模型。其结果是得到一段任务感知的描述，强调当前步骤真正重要的内容，而不是生成一段通用的“详细描述”——成本更低、准确率更高、响应更快。

请求流程与协议细节

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
stated reason for calling view_image)
-> vision prompt -> text description -> image replaced

配置

环境变量

独立的 CLI 和 Python 代理使用这些环境变量；其中只有三个是必需的。原生 Pi 和 OpenCode 扩展使用它们自己的设置，目前仅调用 /chat/completions。

| 变量 | 必需 | 描述 |
|---|---:|---|
| VISION_API_KEY | 是 | 多模态模型的 API 密钥 |
| 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 | 否 | 使用 responses 时，Python 客户端/代理可选的提供商支持的推理强度 |
| 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 / 5 秒套接字超时）才会切换路由，来自模型的 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 密钥？

不需要。尽管发往上游的网络请求由 127.0.0.1:19100 上的代理进程发出，但上游 API 密钥仍由 Codex 按你现有配置放入 Authorization 头中，代理会原样转发该头：

Codex（携带原始 Authorization）
-> 127.0.0.1:19100
-> 纯文本上游（原样接收 Authorization）
所以不要修改 Codex 现有的认证配置，也不要在代理环境中再次存储上游 API 密钥。代理环境只需要 VISION_API_KEY、VISION_BASE_URL 和 VISION_MODEL。

添加另一个多模态模型会显著增加成本吗？

不会。每次主模型需要检查图像时，视觉工具只将必要的意图和图像发送到多模态模型的上下文中。同时还设有截断机制，因此不会出现过长或不断累积的上下文，从而保持低成本。

要进一步降低成本，你可以使用本地部署的小型多模态辅助模型来提供视觉能力。推荐选项包括 Gemma 4 和 Qwen 3.5/3.6 系列。

限制

- 这是一个图像转文本层；它不会将视觉 token 直接交给文本模型。
- 整体视觉任务质量由主 LLM 和多模态 LLM 共同决定。
- 代理的缓存仅存在于其进程内部，重启后会被清除。

捐赠

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

社区

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

关于

如果 agent-vision-toolkit 为你节省了时间，欢迎给它点星、分享、贡献，或赞助该项目。

我是 anionex，一名 AI 原生开发者，曾在 GitHub 全球开发者趋势榜上排名第 4，我的项目累计获得超过 16k stars。如果你想关注我未来的工作，在 X 上关注我 或 GitHub。

加入社区群

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