agent-vision-toolkit

环境要求

• Python 3.11+（glance 仅需此项）
• 准备一个支持 OpenAI Chat Completions / Responses 或 Anthropic Messages 的多模态 API（含 base
• 使用 ground/detect/crop 及长截图 OCR 需额外安装 pillow
• 使用 trace 需 pillow + numpy（仅 --outline 回退时需要 vtracer）
• Node.js/npx（用 npx skills 安装 skill 时需要，也可手动拷贝 skills 目录）

安装与启动步骤

1. 1写入视觉 API 配置

   在本机配置目录创建 env 文件，写入三个必填变量并存为仅本人可读（chmod 600）。

   mkdir -p ~/.config/agent-vision-toolkit && printf 'VISION_API_KEY=sk-xxxxxxxx
   VISION_BASE_URL=https://openrouter.ai/api/v1
   VISION_MODEL=google/gemini-3.6-flash
   ' > ~/.config/agent-vision-toolkit/env && chmod 600 ~/.config/agent-vision-toolkit/env

   复制

2. 2克隆仓库并加入 PATH

   把仓库拉到本地，将 bin 目录加入 PATH 以便直接调用 CLI；写入 shell 配置文件才能持久生效。

   git clone https://github.com/Anionex/agent-vision-toolkit.git
   export PATH="$PWD/agent-vision-toolkit/bin:$PATH"

   复制

3. 3按需装可选依赖

   仅为你实际使用的工具在隔离的 venv 中安装依赖：pillow 供 ground/detect/crop 与长截图 OCR，numpy 供 trace。

   python3 -m venv .venv && .venv/bin/pip install pillow numpy

   复制

4. 4安装 vision-skills 技能

   让智能体知道这些工具存在及如何组合使用；也可把 skills/vision-skills/ 拷进智能体技能目录（如 ~/.codex/skills/）。

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

   复制

5. 5重启智能体并粘贴图片

   安装可选集成后重启智能体，直接粘贴图片或让模型调用其内置图片工具触发识别。

关键配置

如何确认成功

重启智能体后粘贴一张图片，或让模型调用内置图片工具，能得到图片描述或识别结果即成功。

常见问题

注意事项

• 配置文件含密钥，务必保持 chmod 600 权限。
• 代理默认直连上游、不读 Windows 系统代理，显式代理需用 --upstream-proxy 或 VISION_UPSTREAM_PROXY。
• 代理路由按连接成功情况切换，全部失败时返回 502 并列出各路由失败原因。
• Pi 与 OpenCode 原生扩展使用各自设置，目前只调用 /chat/completions。