信息卡

一句话定位

让纯文本编码代理（如 DeepSeek 系列）不开多模态也能"看图"：一组视觉 CLI 工具外加 agent skill，覆盖图像问答、长截图 OCR、前端 UI 复原与截图驱动的 GUI 自动化——核心理念是"视觉能力不必住在模型里，可以住在 harness 里"。

走红原因分析

纯文本强模型与多模态强模型之间仍有明显价格与能力差，许多人被迫为偶尔看图付费升级。该项目给出优雅中间态：提取请求意图发给外部多模态 API，返回任务感知的描述而非泛泛识图。加上透明本地代理让 Codex/Claude Code 无缝获得图像能力，以及 GUI 自动化 playbook（locate → act → recapture → verify）这样的实战配方，精准命中了"省钱的伪多模态"需求。

核心功能拆解

• glance：图像问答与转写，`--ocr` 切文本提取模式。
• ground：查询语义元素，返回原图像素级边界框。
• detect：输出编号元素清单（可见文本+坐标框），支持区域限定。
• crop：按区域裁剪截图，配合 ground 完成取证链路。
• trace：确定性的本地图标/线条中心线提取并拟合 SVG 图元（circle/line/polyline），完全不依赖 LLM，`--outline` 回退需 vtracer。
• long_screenshot_ocr.py：长截图分块 OCR 并重叠合并，`--mode chat` 针对聊天记录排版。
• vision-skills 技能：教代理选工具、定顺序、做验证，可用 npx 一键安装到 codex 等 CLI。

架构与技术栈浅析

Python 3.11+，`pillow` 支撑 ground/detect/crop 与 OCR 流水线，`numpy` 支撑 trace。无缝集成层是一个监听 19100 端口的本地透明代理：把发往你现有纯文本上游的请求截获，将图片替换为由所选视觉 API 生成的文字描述再转发；协议兼容 OpenAI Chat Completions（默认）、Responses 与 Anthropic Messages，由 `VISION_API_PROTOCOL` 切换。另配 Pi/Oh My Pi 与 OpenCode 的原生扩展插件，及 DeepSeek Harness 子模块 `dsh-vision-toolkit`（10 个视觉工具含 grounding、像素 diff、主色分析）。

安装与环境要求

需一个任意模型的编码代理 + 一个兼容三种协议之一的多模态 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

git clone https://github.com/Anionex/agent-vision-toolkit.git
export PATH="$PWD/agent-vision-toolkit/bin:$PATH"
npx skills add Anionex/agent-vision-toolkit --skill vision-skills -a codex -g --copy -y

也可直接复制 `skills/vision-skills/` 到 `~/.codex/skills/`。

快速上手示例

glance screenshot.png -q "What is the dominant color of this image?"
ground screenshot.png "Send button"
long_screenshot_ocr.py long-chat.png --mode chat -o long-chat.ocr.md
trace icon.png -o icon.svg          # 本地确定性执行
crop screenshot.png --region 1563,514,1668,621 -o send-button.png

进阶使用要点

• 代理无需复制上游密钥：转发时保留原始 Authorization 头，Codex 认证配置原样不动。
• 成本低的原因是只传"意图+图片"，并有截断防上下文膨胀；更省钱可接本地小型多模态 sidecar。
• 出站默认直连 TCP/TLS 且忽略系统代理，需要时用 `--upstream-proxy/--proxy-first`，成功路由会缓存复用。
• 局限要清楚：严格的图→文桥接，视觉 token 不会抵达文本模型，效果由两端模型共同决定，代理重启后缓存清空。

典型应用场景

• DeepSeek/Codex 纯文本模型的前端像素级 UI 还原工作流；
• 长聊天记录/文档长图的全文 OCR 归档；
• 截图驱动的 GUI 自动化：定位→操作→复拍→验证闭环；
• 设计稿/草图转 Mermaid/Graphviz 结构图与图标 SVG 化。

同类生态位对比

对比直接换用多模态模型，它在效果上有天花板但换来极低的边际成本与自由组合；对比 GPT-4V 式通用视觉助手，它的价值在各 playbook 的工艺沉淀（OCR 合并、UI 复原、确定性 SVG）。与 LongHorizon-Harness（P065）这类 process 层框架互补：那个管恢复循环，这个管感知补件。

资源导航

• skills/vision-skills/SKILL.md 为日常用法总纲
• 配置文件 `~/.config/agent-vision-toolkit/env`，语言开关 `LANG=zh|en`
• CONTRIBUTING/SECURITY/FUNDING 齐备，作者 anionex