read_image refuses on vision-capable models whose image input is not declared — refusal should point at the fix

[ffournierm]

Version

@deepseek-ai/dsh 0.1.2-rc.1 (global npm install)

What happened

A real agent session needed to read a page of a scanned PDF (a French PLU zoning regulation, raster-only, no text layer). It rasterized the page to PNG and called read_image:

Error: cannot read ".../page_02.png" as an image: model "zai-org/GLM-5.3-Flash" does not declare image input; switch to an image-capable model to read images

GLM 5.3 Flash is image-input-capable on its OpenAI-compatible endpoint — the refusal was about the declaration, not the model. The agent then pip-installed rapidocr-onnxruntime + pymupdf into a scratch venv and OCR'd the page locally to get text into context — work a supported read_image call would have made unnecessary.

Root cause

read_image's capability gate (assertImageCapableRoute, dsh-tool-fs) requires the resolved route to explicitly declare image input. Modality resolution for a custom-provider model falls through:

1. per-model input: on the provider's models entry,
2. pi-ai's catalog entry for the model id,
3. the provider's defaultInput,
4. DEFAULT_INPUT = ["text"].

Two gaps:

• pi-ai's catalog has glm-5.3-flash only under provider zai, declared "input": ["text"] — no friendli entry, and no image modality anywhere in the GLM family. (The openai-completions transport itself carries image parts fine — see verification below.)
• The user-facing fix exists but is undiscoverable. Adding input: [text, image] to the model entry in settings resolves it, but nothing points there: the refusal message says "switch to an image-capable model", the settings templates don't mention the input field, and the tool description ("Requires the current model to accept image input") reads as a model property, not a configuration one.

Verified workaround

llm-pi-ai:
  providers:
    friendli:
      models:
        - id: zai-org/GLM-5.3-Flash
          name: GLM 5.3 Flash
          contextWindow: 1048576
          maxTokens: 65536
          input: [text, image]   # <- this line

Headless run after the change: read_image on a 1×1 PNG returned the image block, and the model correctly reported the rendered pixel color (r=0, g=255, b=0, a=127). Same harness, same model, one line of config.

Requests

1. Refusal message should hint at the declaration path — e.g. ...does not declare image input; if this model accepts images, declare "input: [text, image]" on its models entry. The current message sends users model-shopping when the model is fine.
2. Catalog refresh: GLM 5.3 / 5.3-flash (and plausibly 5.2) accept image input; pi-ai's zai.json (and any friendli coverage) should carry "input": ["text", "image"].
3. Docs: the custom-provider models schema accepts input: [text, image] — worth one line wherever custom providers are documented, plus a mention in read_image's tool description.

Happy to file the pi-ai catalog piece wherever that data lives upstream if this isn't the right home for item 2.

[argszero]

@ffournierm 你这篇把"声明面 vs 能力面"的裂缝又推到一处新的可操作位置——read_image 的读路径能力门（dsh-tool-fs 的 assertImageCapableRoute）跟发送附件那道的 admission gate 是同一根因的两面。我在同基线（5dda764ed3 / 0.1.5-alpha.1）核对后全部成立，且归属一个已有 5 成员的家族。

源级确认

1. 能力门读的是解析后的声明，不是模型能力：packages/fs/tool-fs/src/read-image.ts:119-133 assertImageCapableRoute 走 llm.resolveModelInfo(provider, model, signal) 拿 active.inputModalities；没有 image 就抛你截的这条 message（:131）。门本身不校验传输层能不能带图——openai-completions 传输携带 image parts 没问题（你已验证），所以纯声明面假阴性。
2. 自定义 provider 的解析链末尾落到 ['text']：packages/llm/llm-pi-ai/src/catalog.ts:914 input: declaredInput(entry.input) ?? base?.input ?? [...request.defaultInput]——base 是 catalog 条目，friendli 无 GLM 条目 → base?.input undefined → 落 defaultInput（config.ts:77 DEFAULT_INPUT=['text']）。你的模型声明 input: [text, image] 正是最高优先级 declaredInput(entry.input) 命中 → 一行配置即可，验证正确。
3. 这张图的家族位置：项目-model-inputmodalities-ui-gap 家族已有 5 成员——Model settings UI never exposes the catalog schema existing inputModalities — image-capable custom models are silently rejected #5367（声明面静默 text-only）/ `llm-pi-ai`: custom provider entries silently resolve to text-only when the model is actually multimodal (no auto-merge of provider catalog modalities, undocumented per-model `input` field, no vision badge in the model selector) #5837（自定义 providers.*.models[] 静默 text-only）/ Admit image attachments on text-only model routes (the dispatch layer already degrades them) #5848（发送附件 admission gate 的镜像面：文本-only 路由硬拒图片、消息不入库）/ [UX] Models without explicit input capability are silently treated as text-only; image attachments fail with no warning #5941（实产 7 个视觉模型误判、HTTP 200 但图被剥 = dispatch 投影 placeholder 走了 content.ts:298）/ `llm-pi-ai`: custom provider entries silently resolve to text-only when the model is actually multimodal (no auto-merge of provider catalog modalities, undocumented per-model `input` field, no vision badge in the model selector) #5837+. 本篇是第 6 个，且把落点从"发送侧"扩到"工具读侧"（read_image 能力门）——同一根因：解析链把"未声明"当成"不支持"，而健康的多模态模型常未声明。

三个请求 + 一个插件可挂载面观察

• 请求 ①（改拒绝消息提示声明路径）：完全同意，且是这三项里最该先做的。这条 message 目前"送用户去换模型"，但模型没毛病——改成 if this model accepts images, declare "input: [text, image]" on its models entry 就把用户引向正确修复。这是 core 一行文案，但属插件无法触及的读路径（能力门在 tool-fs 内），归档 upstream-fix 候选即可。
• 请求 ②（catalog 补 GLM 图像声明）：同意，pi-ai zai.json 无 image 是 catalog 缺口。但注意——这是声明面修复，不解决"用户自定义 provider 没走 catalog"的根本；对 friendli 这类不在 catalog 的 route，仍要靠 per-model input 或文档。所以 ② 治标、①+③ 治"用户可发现性"。
• 请求 ③（文档 + tool description 指向 input 字段）：同意，且这一条对"自定义 provider 用户"最实惠——字段在 zod config 里存在但 UI 无处可见（config.ts:298 no-default、不可见）。
• 插件可挂载面（本家族的新机会）：你的绕过（手动 pip rapidocr-onnxruntime + pymupdf 现做 OCR）正是插件形态的天然场景——一个 read_image 的 around-wrapper 插件，在 assertImageCapableRoute 抛"未声明图像"时不吃掉拒绝，而是（a）透明降级到 OCR（把局部 OCR 文本作为 text 回填给模型，job 走 read_image 同语义）或（b）把"模型能力 vs 声明"做一次探测并返回可操作错误。这落 tools/execute 接缝（与 in-tree timeout-policy / 我的 @argszero/cordis-plugin-steer-preempt 同缝），不需要动 core。我这边已把 [UX] Models without explicit input capability are silently treated as text-only; image attachments fail with no warning #5941 的"doctor models 能力 lint"列过插件候选，你的 OCR-fallback 是第二个——若你愿意，下一轮我可以把"声明探测 + 可操作报错"的最小版做出来并在此帖提及闭环。（声明面 catalog 修复归 core，插件是绕过/探测面。）

判别：这是 inputModalities 家族第 6 成员，read_image 工具读侧能力门为新增面；建议先把请求①的 message 改文案归档 upstream-fix（core 小改，一行），插件面（OCR-fallback / 能力探测）走 tools/execute seam，不与 core 冲突。

[argszero]

@ffournierm 我按上一条里说的，把「声明探测 + 可操作报错」的最小版做出来了，现在以插件形态发布，直接回此帖闭环。

发布：@argszero/cordis-plugin-read-image-guidance v0.1.0

• npm：https://www.npmjs.com/package/@argszero/cordis-plugin-read-image-guidance
• 源码：https://github.com/argszero/cordis-plugin-read-image-guidance

它做什么。 你的请求①（改那条误导的拒绝消息）在 core 里是 dsh-tool-fs 读路径里的一行文案（assertImageCapableRoute），社区合并不了，所以这里用插件在 tools/execute 接缝做一个等价物：当 read_image 抛出的拒绝消息带 "does not declare image input; switch to an image-capable model" 这个稳定签名时，把模型可读的 content 改写成具体的配置指引——declare "input: [text, image]" on the model's models entry（对自定义 provider/user 那一类、能自己改 settings.yaml 的人最实惠），并且保留 isError 与结构化 error，重试/回放路由不受影响。其它工具结果、成功结果、非该签名的失败一律原样放行。

安装：

dsh plugin --profile web add github:argszero/cordis-plugin-read-image-guidance

默认开启改写；config: { rewrite: false } 可只观察不改写。

与讨论的关系。 这是 inputModalities 族第 6 成员（read_image 工具读侧能力门）里，请求①的社区侧可交付版；请求②（catalog 补声明）与请求③（文档/描述指向 input 字段）仍是 core / catalog 侧，归档 upstream-fix 候选即可。v0.1 只做「声明探测 + 可操作报错」，没有引入原生 OCR 依赖——你手动 pip rapidocr 那个其实是另一个更重的候选（OCR 回填模型），如果后面要做我可以评估成 v0.2。

顺带：插件用了 peerDeps: @deepseek-ai/dsh-tools >=0.1.2，只依赖 tools/execute 接缝，与 guard/timeout-policy、我的 @argszero/cordis-plugin-steer-preempt 同缝，不碰 core。9 个行为测试全过（npm test），源码注释里标了在 0.1.5-alpha.1 上的机制核对点。