本页提纲
图像观察
ViewImage 让 Holon Agent 通过视觉模型检查本地图片文件。Agent 提供图片路径和描述要检查
内容的提示词，运行时返回结构化的视觉观察结果。
ViewImage 做什么
Agent 调用 ViewImage 时，运行时会：
- 校验图片：读取文件，检查体积上限（最大 20 MB、5000 万像素），计算 SHA-256， 检测 MIME 类型和尺寸。
- 选择视觉模型：使用配置的
vision.default提供商/模型，或自动发现一个支持图片输入 且已认证的提供商。 - 生成观察结果：把图片和提示词发给视觉模型，返回结构化观察结果。
- 缓存结果：之后用相同图片和提示词调用时复用缓存的观察结果。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
path | 是 | workspace 相对路径或绝对路径的图片路径 |
prompt | 是 | 要在图片中检查或描述的内容 |
model | 否 | 本次调用的显式模型路由（provider@endpoint/model） |
支持的图片格式：PNG、JPEG、GIF、WebP，以及所选视觉模型支持的其他格式。
ViewImage 返回什么
结果分两部分：
视觉引用（持久元数据）
无论视觉模型是否可用，每次调用都会记录：
| 字段 | 说明 |
|---|---|
id | 稳定的引用 ID |
mime | 媒体类型（例如 image/png） |
byte_count | 文件大小（字节） |
sha256 | 内容哈希 |
path | 解析后的文件路径 |
size | 可检测时的图片尺寸（宽 × 高） |
视觉观察（生成的）
视觉模型可用时，观察结果包含：
| 字段 | 说明 |
|---|---|
generated_by | 提供商、模型和生成模式 |
prompt | 产生该观察结果的提示词 |
summary | 观察结果的可读摘要 |
ocr | 提取的文本（适用时） |
elements | 识别出的视觉元素 |
relations | 元素之间的空间或逻辑关系 |
issues | 检测到的问题或异常 |
uncertainties | 模型不确定的地方 |
视觉模型选择
显式配置
设置专用的视觉模型：
holon config set vision.default "anthropic/claude-sonnet-4-6"
配置了 vision.default 时，ViewImage 对所有图片观察都用该模型。这是生产环境的推荐做法。
按调用指定模型
Agent 可通过传递 model（例如 "anthropic@direct/claude-sonnet-4-6"）为单次检查指定特定模型路由。显式按调用指定绝不触发回退，也不会修改 vision.default。若所选模型不支持图片输入，调用将直接报错，而不会静默替换为其他候选模型。
自动发现
未设置 vision.default 时，ViewImage 会扫描已配置的提供商，自动发现可用的视觉模型，
条件包括：
- 凭据有效
- 声明支持
image_input - 使用支持生成图片观察结果的 transport（OpenAI 兼容 API、Anthropic Messages 或 Gemini GenerateContent）
选择结果会随工具响应一起返回，你能看到选了哪个模型。
Gemini 原生图像输入与预检预算
Gemini 模型通过 GenerateContent 的原生 inlineData parts 接收本地图像。该传输方式严格保留文本与图像的相对顺序，并使用 JSON Schema lowering 提取结构化视觉观察。
图像输入完整纳入请求前置准入与配额核算：
- 图像部分按图片张数和解码字节上限核算，不再被折算为纯文本 Token 估算。
- 缺少图像输入支持的回退路由会在实际分发前提前拒绝必需图片，防止触发不可预期的下游调用异常。
没有可用视觉模型时
如果没有已配置的模型支持图片输入，ViewImage 返回 vision_adapter_unavailable 错误，
并附带评估过的候选列表。持久视觉引用元数据仍会记录。
观察结果缓存
ViewImage 用「图片哈希 + 提示词」的组合键缓存观察结果。如果 Agent 用相同图片和提示词再次 调用 ViewImage，运行时直接返回缓存结果，不再调用模型：
ViewImage reused cached visual observation
在 Agent 反复查看同一张图片的多轮会话中，这能省下延迟和成本。
Agent 何时使用 ViewImage
任务涉及视觉检查时，Agent 会调用 ViewImage：
- 从截图做代码审查：检查 UI 稿、错误画面或示意图。
- 文档分析：从扫描件、收据或白板照片中提取文本或结构。
- 排查问题：诊断生成输出或测试失败中的视觉异常。
- 数据提取：从以图片呈现的图表、表格或表单中提取结构化数据。
Agent 根据任务上下文判断 ViewImage 是否相关。该工具属于 LocalEnvironment 能力族，
默认对每个 Agent 可用。
请求级图片预算与多模态预检
为防止包含大量图片的会话耗尽提供商上下文窗口，Holon 实施请求级 Markdown 图片附件预算与多模态预检估算：
- 附件额度限制 — 单次请求最多容纳 8 张不重复图片或 20 MiB 解码前文件字节。单文件限制（20 MB / 5000 万像素）依然有效。
- 优先级与内容去重 — 当前轮次必需的图片优先保留配额，历史附件按可选规则降级。不同路径下的相同文件通过内容哈希自动去重，单轮最多探测 16 个不重复本地路径。超出预算的历史图片会自动降级并附带文本提示。
- 多模态上下文预检 — 传输层将文本与工具负载同图片分离统计，仅从最多 64 KiB 的头部字节中探测图像尺寸，无需完整解码像素阵列或发起远程网络拉取。基于模型家族的 patch/tile 启发式规则估算上下文占用，在发起网络请求前完成上游准入验证。
CLI 验证
ViewImage 是面向模型的工具，不能直接从 CLI 调用。Agent 通过正常的工具调用机制使用它。
另见
- 模型工具 schema 清册：工具注册与稳定性
- 模型参考：支持的提供商和视觉模型可用性
- 配置参考：
vision.default和提供商设置