补充MCP图像视觉桥接特性的研究

PR 地址：NousResearch/hermes-agent#85994 · 把 MCP ImageContent 桥接到辅助视觉模型摘要，让纯文本主模型"看见"图像

研究摘要

之前，返回 ImageContent 块的 MCP 工具（浏览器截图、read_image、read_video 帧）对纯文本主模型是彻底盲目的：Hermes 缓存图片字节后只交给模型一个裸 MEDIA:<path> 标签，对纯文本 provider 而言这个标签携带零像素信息（Qwen-MM-Plugins 官方手册确认"provider 收不到图像像素"）。手动调用 vision_analyze 可以补救，但要求模型记得自己是盲的并主动调第二个工具——这是会反复出现的失败模式。现在，配置了 auxiliary.vision 后，MCP 图像块在缓存后由辅助视觉模型描述一次，文本摘要随 MEDIA: 标签一起输出（双轨输出），纯文本模型从"完全看不见"变成"看到完整描述"。

实测（M5 Max + 本地 Mage-VL-8bit + deepseek-v4-flash 纯文本模型）：受控对比下文本信息量从 66-76 字符（仅尺寸元数据）提升到 1,263-2,073 字符（视觉描述），增益 18-27 倍；K 线图标识、金融 OCR 提取、网页识别三类推理任务从 0% 正确率升到 100%，无桥接时 3/3 回答"无法回答"。桥接全程 fail-open：任何失败都返回空串，原始 MEDIA: 标签永远存活。

一、问题背景

1.1 双轨信息流的单轨断裂

MCP 工具结果管线对图像的处理是：cache_image_from_bytes 缓存字节 → 返回 MEDIA:<path>。这条路径对多模态主模型成立（标签指向的媒体可被原生渲染），对纯文本 provider 信息完全丢失。用户选择纯文本主模型（成本、速度、隐私）并不意味着放弃图像信息——问题出在管线没有自动替他们做"描述"这一步。

1.2 手动回退的认知负担

内置 vision_analyze 工具是现成的回退，但依赖模型"记得自己盲"并在每个图像结果上主动发起第二次工具调用。桥接的价值是把这一步自动化，消除这个记忆负担造成的失败模式。

二、特性设计

2.1 一个函数，一条窄腰

tools/mcp_tool.py 新增 _summarize_mcp_image(image_tag)，从既有图像块分支调用：

• fail-open 契约：任何失败 / 超时 / 配置错误返回空串，原始 MEDIA: 标签始终存活，单个坏块永不杀死整个工具结果（与文件既有 fail-open 惯例一致）；
• 配置门：未配置 auxiliary.vision 时完全 no-op（零足迹）；auxiliary.vision.summarize_mcp_images: false 显式关闭；
• 超时：每图上限 auxiliary.vision.mcp_summary_timeout（默认 20s），慢视觉后端不会卡死 MCP 工具结果；
• 会话去重：图片缓存路径是内容哈希，同一张图每个进程至多分析一次（_MCP_IMAGE_SUMMARY_CACHE）；
• 模型对齐：auxiliary.vision.model 的解析与内置 vision_analyze 完全一致（配置 model → AUXILIARY_VISION_MODEL 环境变量 → None），避开未配置云视觉时 provider=auto 的回退报错。

窄腰原则：零新核心工具、零新环境变量、无系统提示词改动、无 prompt 缓存失效——只有 MCP 结果渲染这一条边发生变化。

2.2 安全审计

威胁模型：图像内容变成模型可读文本，引入了新的提示注入载体——图像里嵌入的恶意文本会被转写进摘要。缓解：摘要显式标记 [图片内容摘要]（数据标记而非指令），桥接只描述、从不执行；逐用户 opt-out（summarize_mcp_images: false）；超时约束资源占用；会话缓存限制重复分析。无新凭据面（复用既有 auxiliary.vision 配置与 vision_analyze 路径）、无新环境变量、无遥测、出口流量不超出已配置的辅助视觉端点。

三、实测结果

3.1 受控对比（M5 Max，Mage-VL-8bit 本地 + deepseek-v4-flash 纯文本模型，9 个场景，同模型同提示词仅输入不同）

3.2 已记录的失败模式

视觉模型在低信息图像上会幻觉——1×1 像素红点被描述成"旅行网页"；视觉输出依赖提示词——验证码用针对性提示词能读对、通用提示词下会幻觉。这两类边界写进文档，提示用户对关键数据保留人工复核。

3.3 测试

tests/tools/test_mcp_image_summary.py 新增 7 个测试（无配置 no-op、opt-out、成功路径、会话缓存、三种 fail-open 变体、超时 fail-open、非图像/缺失文件 no-op）；既有 MCP 套件（test_mcp_image_content / test_mcp_resource_content / test_mcp_tool）合计 124 passed 无回归。

四、平台兼容性与能力边界

• macOS / Linux：完整支持（asyncio + 标准库）；
• Windows：桥接与 POSIX 无关，既有 MCP 管线的平台守卫照常生效；
• 多模态主模型用户：行为不变（MEDIA 标签照常，摘要只是多余文本，无害）。

边界与局限：每张图增加 5-72 秒延迟（取决于本地视觉模型），默认 20s 超时对 100KB+ 大图可能偏紧，需调 mcp_summary_timeout；桥接依赖 auxiliary.vision 已配置且 model 字段存在（缺失时报 “No LLM provider configured for task=vision”）；摘要质量受视觉模型能力约束，低信息图像存在幻觉与提示词依赖；提示注入经图像进入摘要的风险由数据标记与"只描述不执行"缓解，但不能完全消除。

五、PR 信息

• PR 地址：https://github.com/NousResearch/hermes-agent/pull/85994
• 改动规模：+277 / -0，2 个文件
• 状态：open
• 提交时间：2026-08-14

本文记录 x7peeps 向 Hermes Agent 上游贡献的特性研究，所有数据来自 PR 实测记录。