视觉翻译桥 BingL-Li/vision-translation

使用视觉基元进行翻译

一个稳定的视觉翻译 Core；任何 Agent 都可以通过 Bridge 接入。

一个稳定的视觉翻译 Core，任意 Agent 都可以通过 Bridge 即插即用。

本项目将图像转换为结构化的 文本。辅助 VLM 负责查看图像，而 Core 生成 norm-1000 xyxy 视觉基元，根据几何计算空间关系，并提取 OCR。主 Agent 只消费文本：它不处理像素，也不需要更换模型。

本项目把图片转换成结构化的 文本：辅助 VLM 负责看图，Core 统一生成 norm-1000 xyxy 视觉基元、由几何计算空间关系并提取 OCR。主 Agent 只消费文本，不接触像素，也不需要修改模型。

这个名称有意呼应 DeepSeek 的论文 Thinking with Visual Primitives。该论文将视觉基元置于模型内部；本项目则反其道而行之，将视觉在模型外部翻译为基元，并交给普通的文本模型。

项目名有意呼应 DeepSeek 的论文 Thinking with Visual Primitives。论文让模型在内部使用视觉基元，本项目则把方向反过来：在模型外部把视觉翻译成基元，再交给原本的文本模型。

架构：一个 Core，任意 Agent，每个 Agent 一个 Bridge

架构：一个 Core，任意 Agent，各自的 Bridge

交互式图表： 打开 vision-translation-architecture.html 查看整体分层架构，或打开 vision-context-roundtrip.html 查看 image + question → 往返流程。下方的 Mermaid 备用图可直接在 GitHub 上渲染。

交互图： 用浏览器打开 vision-translation-architecture.html 查看整体分层架构，或打开 vision-context-roundtrip.html 查看 image + question → 往返。下面的 Mermaid 兜底图可直接在 GitHub 渲染。

flowchart LR
A["Any AgentHermes · dsh · Claude Code"]
B["BridgeOne per Agent · integration and protocol mapping only"]
C["cli.pyCross-language boundary · PROTOCOL v1"]
D["Single Corevision_translation.py"]
V["Auxiliary VLMOptional · image to JSON"]

A -- "image + question" --> B
B -- "in-process import (Hermes / MCP)" --> D
B -- "spawn (cross-language / isolated process)" --> C
C --> D
D -. "on demand" .-> V
D -- "vision-context" --> B
B -- "vision-context" --> A

调用方向是一个往返：Core 调用辅助 VLM，Bridge 调用 Core，最终的 通过 Bridge 返回给 Agent。Python Bridge 可以直接导入 Core；其他语言和隔离进程使用 cli.py 和 PROTOCOL v1。

图中的调用在实现上是往返的：Core 调用辅助 VLM，Bridge 调用 Core，最终 经 Bridge 返回 Agent。Python Bridge 可以直接导入 Core，其他语言和隔离进程通过 cli.py 与 PROTOCOL v1 调用。

vision_translation.py Core: the only visual-translation logic; import-pure
cli.py Cross-language protocol entry point: argv/stdin → one JSON object
__init__.py Hermes 原生 Bridge（进程内） adapters/mcp/ 通用 MCP Bridge（进程内导入 Core） adapters/_template/ 社区 Bridge 模板（使用 CLI）

核心不随 Agent 改变。 新接入只需贡献一个薄 Bridge，把宿主的图片和问题交给既有 Core，再把结果映射回宿主。Bridge 不得复制提示词、JSON 解析、框归一化、关系计算或 VLM 调用逻辑。

核心不随 Agent 改变。 新接入只需贡献一个薄 Bridge，把宿主的图片和问题交给既有 Core，再把结果映射回宿主。Bridge 不得复制提示词、JSON 解析、框归一化、关系计算或 VLM 调用逻辑。

快速开始

快速开始

配置

配置

辅助 VLM 通道由三个环境变量配置，默认值保持 OpenRouter 兼容，老用户零迁移成本：

辅助 VLM 通道由三个环境变量配置，默认值保持 OpenRouter 兼容，老用户零迁移成本：

| 环境变量 | 默认值 | 作用 |
| VISION_TRANSLATE_API_KEY | （回退 OPENROUTER_API_KEY） | 辅助 VLM 的 API key；新名字优先 |
| VISION_TRANSLATE_BASE_URL | https://openrouter.ai/api/v1/chat/completions | OpenAI 兼容的 /chat/completions 端点 |
| VISION_TRANSLATE_VLM | xiaomi/mimo-v2.5 | 发送给端点的模型名 |

| 环境变量 | 默认值 | 作用 |
| VISION_TRANSLATE_API_KEY | （回退 OPENROUTER_API_KEY） | 辅助 VLM 的 API key；新名字优先 |
| VISION_TRANSLATE_BASE_URL | https://openrouter.ai/api/v1/chat/completions | OpenAI 兼容的 /chat/completions 端点 |
| VISION_TRANSLATE_VLM | xiaomi/mimo-v2.5 | 发送给端点的模型名 |

OPENROUTER_API_KEY 继续作为旧名字回退支持；两个 key 都设置时，VISION_TRANSLATE_API_KEY 优先。

OPENROUTER_API_KEY 继续作为旧名字回退支持；两个 key 都设置时，VISION_TRANSLATE_API_KEY 优先。

任何 OpenAI 兼容的 /chat/completions 端点都可以使用——OpenAI、DeepSeek、opencode、vLLM、Ollama、LiteLLM 及自建网关都使用该协议。Core 不负责协议转换，请只填写 OpenAI 兼容端点。

任何 OpenAI 兼容的 /chat/completions 端点都可以使用——OpenAI、DeepSeek、opencode、vLLM、Ollama、LiteLLM 及自建网关都使用该协议。Core 不负责协议转换，请只填写 OpenAI 兼容端点。

示例：DeepSeek（OpenAI 兼容）
export VISION_TRANSLATE_BASE_URL="https://api.deepseek.com/v1/chat/completions"
export VISION_TRANSLATE_API_KEY="sk-..."
export VISION_TRANSLATE_VLM="deepseek-chat"

示例：opencode（OpenAI 兼容网关；host/port 取决于你的部署）
export VISION_TRANSLATE_BASE_URL="http://localhost:4096/v1/chat/completions"
export VISION_TRANSLATE_API_KEY="opencode"
export VISION_TRANSLATE_VLM="your-opencode-vision-model"

示例：本地 vLLM（OpenAI 兼容服务器）
export VISION_TRANSLATE_BASE_URL="http://localhost:8000/v1/chat/completions"
export VISION_TRANSLATE_API_KEY="EMPTY"
export VISION_TRANSLATE_VLM="Qwen/Qwen2.5-VL-7B-Instruct"

示例：本地 Ollama（OpenAI 兼容端点）
export VISION_TRANSLATE_BASE_URL="http://localhost:11434/v1/chat/completions"
export VISION_TRANSLATE_API_KEY="ollama"
export VISION_TRANSLATE_VLM="llava"

直接使用 CLI

Core 运行时仅依赖 Python 标准库；Pillow 是可选的图片旋转和缩放增强。

export VISION_TRANSLATE_API_KEY=sk-... # 或旧版 OPENROUTER_API_KEY
python cli.py path/to/image.jpg "What is the layout?"

stdout 始终只有一个 JSON 对象；日志只能写入 stderr：

{
"protocol": 1,
"core_version": "",
"status": "ok",
"context": "…", "model": "xiaomi/mimo-v2.5" }

示例中的 是占位符；实际值以 python cli.py --protocol-version 输出为准，CI 会检查它与 plugin.yaml 一致。

三种 status 是：

- ok：已得到视觉上下文，退出码 0。
- unavailable：无密钥、上游不可用或 VLM 输出无效等可预期降级，退出码 0。
- error：请求错误或内部错误，退出码 1–2。

完整契约见 PROTOCOL.md。以下握手命令不读取图片、不使用 Token、不访问网络，适合 CI：

python cli.py --self-check
python cli.py --protocol-version

Hermes Agent 原生 Bridge

Hermes 原生插件需要为 Hermes 配置 OPENROUTER_API_KEY：

推荐：从 GitHub 安装 hermes plugins install BingL-Li/vision-translation --enable

或放入用户插件目录
git clone https://github.com/BingL-Li/vision-translation ~/.hermes/plugins/vision-translation
hermes plugins enable vision-translation

重启承载对话的 Hermes 进程，再验证插件和工具：

hermes plugins list
hermes tools list

升级 Hermes 插件 — Hermes 通过自己的 CLI 原生管理插件，只需官方命令（无需自定义脚本）：

hermes plugins update vision-translation # 官方：git pull + 元数据 + 清缓存 + 能力重授权 hermes gateway restart # 进程内 import 加载新代码

注意：插件必须先通过 hermes plugins install BingL-Li/vision-translation（或等效的手动 git clone）安装，以便安装元数据存在；hermes plugins update 会拒绝更新没有 git remote 或没有元数据记录的插件。

说明：插件须先经 hermes plugins install BingL-Li/vision-translation 安装（或等价的手动 git clone）使安装元数据存在；hermes plugins update 对没有 git remote 或没有元数据记录的插件会拒绝更新。

vision_translation toolset 中的 vision_translate 工具参数如下：

| 参数 | 类型 | 说明 |
| image_path | string | 本地图片路径，必填 |
| question | string | 用于引导解析重点的可选问题 |
| max_objects | int | 保留的最大基元数，默认 12、上限 16 |

只需一句廉价描述时使用 Hermes 内置 vision_analyze；需要坐标、计数、相对位置、UI/PCB 元素位置、结构化实体或 OCR 时使用 vision_translate。

MCP Bridge

MCP Bridge 适用于 dsh、Claude Code、Cursor、Hermes、Codex 以及任意 MCP Host：

cd adapters/mcp
python -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python smoke_test.py

随后把 adapters/mcp/server.py 配置为 stdio MCP Server。dsh 可合并 adapters/mcp/dsh-preset.yml；Claude Code 和 Cursor 分别使用 .mcp.json 和 ~/.cursor/mcp.json。完整配置见 adapters/mcp/README.md。

Hermes 用户应在原生插件与 MCP Bridge 中二选一，避免注册两个用途相同的工具。

端到端 Demo

python demos/vision_translate_demo.py path/to/image.jpg "What is the layout?"

Demo 额外演示把 交给文本 LLM；生产集成只需 Bridge + Core，Core 本身不会嵌套调用文本 LLM。

为其他 Agent 增加 Bridge

cp -r adapters/_template adapters/

实现宿主接入、补充 README 和离线 smoke test、登记到 ADAPTERS.md，即可提交 PR。详细流程见 CONTRIBUTING.md。

数据流图示： vision-context-roundtrip.html 以交互式序列图展示这一往返流程。

1. Bridge 接收 Agent 给出的图片路径、问题和可选参数。
2. Core 处理 EXIF 方向，并在 Pillow 可用时将长边限制为 1568 像素。
3. Core 把图片交给配置的 OpenAI 兼容辅助 VLM 端点（默认 OpenRouter 的 xiaomi/mimo-v2.5；可通过 VISION_TRANSLATE_VLM、VISION_TRANSLATE_BASE_URL、VISION_TRANSLATE_API_KEY 覆盖）。
4. Core 容错解析 JSON，校验并规范化对象框；坐标越界会被钳制并产生警告，零面积或非有限坐标会被丢弃。
5. Core 根据几何关系计算 left_of / right_of / above / below / inside / overlaps，而不是让 VLM 猜关系。
6. Core 渲染不超过 2000 字符的 ；优先保留基元和关系，超限时先裁剪描述文本。
7. Bridge 将成功、不可用或错误状态转换成宿主 Agent 能理解的结果。

设计边界

- 统一坐标契约： norm-1000、xyxy，左上角 (0, 0)，右下角 (1000, 1000)。
- 诚实 Grounding： 坐标是 VLM 按提示生成，不是原生检测器输出，因此明确标记为 grounding: prompted。
- 几何而非语言关系： 方向关系只在两个框以 EPS=20 明确分离时产生；包含和重叠也由框计算。
- 失败即关闭： 三次无效 VLM 输出后返回 unavailable；绝不注入看似合理的空上下文或编造内容。此路径最多可发送三次图片请求。
- 可测试 Core： 导入 vision_translation.py 不会发起网络请求、执行 argparse 工作或产生输出；VLM 边界的 HTTP 可被 mock。
- 可扩展 Bridge： 宿主生命周期、附件格式和工具协议属于 Bridge；视觉语义、解析和几何属于 Core。
- 隐私边界： 图片会发送到配置的 OpenAI 兼容 VLM 端点，而不是主文本模型；请确认你的使用场景符合其数据政策。
- 失败关闭： 三次无效 VLM 输出后返回 unavailable，绝不注入看似合理的空上下文或编造内容；失败路径最多会发送三次带图请求，需留意成本。
- Core 可测试： vision_translation.py 导入时无网络、无 argparse、无输出；测试可以在 HTTP 边界 Mock VLM。
- Bridge 可扩展： 宿主生命周期、附件格式、工具协议属于 Bridge；视觉语义、解析和几何只属于 Core。
- 隐私边界： 图片会发送到配置的 OpenAI 兼容 VLM 端点，不会发送给主文本模型；使用前应确认数据策略满足场景。

输出示意

- v1 | type: box | box: [86, 120, 420, 630] | ref: panel | confidence: 0.96 | grounding: prompted
- v2 | type: box | box: [610, 210, 900, 520] | ref: button | confidence: 0.93 | grounding: prompted

- v1 left_of v2 | source: geometry | confidence: 1.0

visible_text: Submit

仓库结构

| 路径 | 作用 |
| vision_translation.py | 唯一 Core |
| cli.py | PROTOCOL v1 跨语言入口 |
| __init__.py | Hermes 原生 Bridge |
| adapters/_template/ | 社区 Bridge 脚手架 |
| adapters/mcp/ | 通用 MCP Bridge 与 dsh preset |
| demos/ | 含文本 LLM 步骤的端到端演示 |
| tests/ | 离线 Core 与协议测试 |
| PROTOCOL.md | CLI 协议唯一规范 |
| ADAPTERS.md | Bridge 注册表与生态规则 |
| docs/architecture.md | 专用架构文档（archify 图 + Mermaid 兜底图） |
| docs/architecture/diagrams/ | Archify 生成的 HTML 图与 JSON spec |
| CONTRIBUTING.md | 贡献流程与审查边界 |
| CHANGELOG.md | 版本历史 |

局限

- Grounding 来自 VLM 提示而非原生检测器，适合布局、UI 和场景理解，但不保证像素级准确。
- 需要支持图片输入的 OpenAI 兼容 VLM；更换模型前应核对其 input_modalities。
- 主模型需要能可靠理解坐标文本和空间关系；DeepSeek 系列是最初目标，但 Core 与主 Agent 模型无关。
- MCP Bridge 当前接收本地文件路径；只提供内存附件且不共享文件系统的宿主需要自行增加原生 Bridge 或附件转换。
心路历程

这个项目并非从一张完整蓝图开始，而是从一篇论文、阅读开源实现的过程，以及一个一直放不下的想法逐步长出来的。

2026-07-10：想法出现。 阅读 Thinking with Visual Primitives 时，最打动我的并不是模型架构，而是表示方法：图片不一定以像素或散文式描述进入模型，也可以变成少量带标签、位于统一坐标系中的视觉基元。论文把这种表示放进模型；这里把它反过来，让另一个组件看图并交给主模型 。

2026 年 7 月：寻找前人的路。 OpenHanako 的 core/vision-bridge.ts 已经把图片转成包含 norm-1000 xyxy 基元的 。本项目有意沿用了它的上下文格式、坐标空间、保守的基元和标签上限，以及区分检测坐标与提示坐标的 Grounding 诚实性。

2026 年 7–8 月：把边界做窄。 四个选择最终塑造了实现：结构优先于描述、VLM 负责看图而程序负责几何、Core 不嵌套文本 LLM 推理，以及失败关闭。vision_translation.py 始终保持无导入副作用，使解析、归一化和几何可以脱离 Agent 测试，并由所有 Bridge 复用。

2026-08-14：首次发布。 项目以 Hermes Agent 插件 0.1.0 发布；同日完成代码审查，删除死代码，加入坐标越界警告，并整理模块语言。

2026-08-15：从插件走向生态。 PROTOCOL v1、cli.py、离线测试、Bridge 模板、MCP Bridge、生态文档和 CI 逐步加入。仓库不再只是“一个 Hermes 插件”，而成为“一个 Core + 稳定边界 + 一圈 Bridge”。Hermes 仍是官方原生 Bridge，但不再是 Core 的前提。

下一步不是让 Core 感知更多 Agent，而是让社区为自己的 Agent 贡献 Bridge。只要共同遵守协议和“不复制 Core”的规则，Agent 可以不断增加，核心保持不变。

致谢
- Thinking with Visual Primitives 的作者启发了视觉基元表示。
- OpenHanako 的作者和贡献者，尤其是 core/vision-bridge.ts 的维护者，为上下文格式、坐标契约和 grounding 诚实性提供了参考。
- Nous Research 提供了 Hermes Agent 插件系统，承载了第一个原生 Bridge。

- Thinking with Visual Primitives 的作者：这个项目建立在其视觉基元表示启发上。
- OpenHanako 的作者和贡献者，尤其是 core/vision-bridge.ts 的维护者：本项目的上下文格式、坐标契约和 Grounding 诚实性来自对该实现的学习。
- Nous Research：Hermes Agent 插件系统承载了本项目最早的原生 Bridge。

Implementation mistakes remain the responsibility of this project.

实现中的任何错误都由本项目承担。

Contributing and license

贡献与许可证

Core changes receive high-threshold review, while Bridge contributions use a lower threshold. See CONTRIBUTING.md and ADAPTERS.md.

Core 变更采用高门槛审查，Bridge 贡献采用低门槛审查。详见 CONTRIBUTING.md 和 ADAPTERS.md。

MIT © 2026 Binglun Li.

MIT © 2026 Binglun Li。