• 最新动态
• 亮点
• 用例技能
• 实际效果
• 快速开始
• 工具
• 升级：无缝接入
• 工作原理
• 配置
• 常见问题
• 赞赏
• 社区
• 关于

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

任何支持 /chat/completions 与 image_url 的 OpenAI-compatible 端点都可以（如阿里云百炼：https://dashscope.aliyuncs.com/compatible-mode/v1 + qwen-vl-max-latest）。Python 客户端/代理也可设置 VISION_API_PROTOCOL=responses 使用 /responses + input_image，或设置 VISION_API_PROTOCOL=anthropic 使用 Anthropic Messages；此时 Base URL 应以 /v1 结尾，不要包含 /messages。需要英文描述时加 LANG=en（默认中文）。

2. 把 CLI 放进 PATH：

git clone https://github.com/Anionex/agent-vision-toolkit.git
export PATH="$PWD/agent-vision-toolkit/bin:$PATH"   # 写进 shell 配置以持久生效

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/），重启生效。

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

glance screenshot.png -q "这张图片的主色调是什么？"
glance screenshot.png --ocr

这张图片的主色调为**白色和浅灰色，局部带淡蓝色。**

用户名
密码
登录

遇到滚动长截图或聊天记录时，skill 内置的工作流会寻找安全切口，调用 glance 逐块 OCR，合并重叠内容，并生成边界复查报告：

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

定位图片中的对象或区域，输出原图像素坐标下的边界框：

ground screenshot.png "发送按钮"

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

每次分析一张完整图片。加 --region X1,Y1,X2,Y2 可只在该框内查找，输出仍是原图坐标——小目标的放大通道。

盘点图片（或指定区域）中的元素——输出编号清单，带逐字可见文字和像素框：

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 在本地确定性地恢复扁平高对比图形的中心轨迹，再拟合成可编辑的 SVG 图元，如 <circle>、<line>、<polyline>、<polygon>；紧凑的实心圆点会保留成填充圆，闭合曲线也不会再被直线拟合切碎。放大镜会还原成一个圆加一条线，闪电笔画会还原成真实线段，而不是沿墨迹两侧生成杂乱 path。小图标会在内部放大分析，但输出 SVG 仍使用原图坐标。LLM 不参与这一步几何拟合；DeepSeek 之类的 agent 只负责外围的定位、裁剪、渲染和验收。只有明确需要填充物体的外轮廓时才使用 --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 把图片中的像素盒裁成独立文件——就是 ground/detect 输出的那组 X1,Y1,X2,Y2 坐标，超出图片边界时自动收敛。同一个盒子接下来要喂给 pixel_diff、dominant_colors、trace 多次时，先裁一次存成文件复用，而不是每次 调用都在内存里重裁。需要可选依赖 pillow。

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

Codex -> 127.0.0.1:19100 -> 用户原有的纯文本模型上游
             |
             +-- 请求含图片时：
                 focus hint（用户的请求，或模型调用 view_image 时自述的动机）
                   -> 视觉 prompt -> 文字描述 -> 替换图片

独立 CLI 和 Python 代理使用这些环境变量，必填的只有 3 个。Pi 与 OpenCode 原生扩展使用各自设置，目前仅调用 /chat/completions。

代理默认直连（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 秒 socket 超时）才切换路由，上游返回的 HTTP 状态错误原样透传。所有路由都失败时返回 502，逐条列出路由与失败原因。HTTP 代理 URL 未写端口时使用标准端口 80；暂不支持代理鉴权。

不需要。访问上游的网络请求虽然由 127.0.0.1:19100 的代理进程发出，但上游的 API key 仍由 Codex 按原有配置放在 Authorization 请求头中，代理会将这个请求头原样转发出去：

Codex（携带原有 Authorization）
  -> 127.0.0.1:19100
  -> 纯文本模型上游（原样收到 Authorization）

因此不要修改 Codex 原有的认证配置，也不要在代理 env 中重复保存上游的 API key。代理 env 只需配置 VISION_API_KEY、VISION_BASE_URL 和 VISION_MODEL。