dsh-vision-router 1.3.0 → 1.4.0

package/README.md

@@ -15,7 +15,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.3.0"><img src="https://img.shields.io/badge/release-v1.3.0-5B4CF0?style=flat-square" alt="Release v1.3.0" /></a>
+  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.4.0"><img src="https://img.shields.io/badge/release-v1.4.0-5B4CF0?style=flat-square" alt="Release v1.4.0" /></a>
   <a href="tests"><img src="https://img.shields.io/badge/verified-149%20tests-2EA44F?style=flat-square" alt="Verified: 149 tests" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2EA44F?style=flat-square" alt="License: MIT" /></a>
   <a href="package.json"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-339933?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white" alt="Node.js >=22" /></a>
@@ -28,20 +28,26 @@
 <p align="center">💬 <strong>QQ community group: 1105463028</strong></p>
 
 > [!WARNING]
-> 📌 **Announcement (v1.3.0)**
+> 📌 **Announcement (v1.4.0)**
 >
-> **v1.3.0** makes long sessions and mixed-plugin setups safer: the vision-tool schema is stable by default to protect prefix/KV caches, diagnostics can be persisted and opened from Settings, custom vision-model filtering explains missing image metadata and supports re-detection, host-provided DSH capability packages use the correct peer contract, and Vision Router tool cards can coexist with other vision plugins while keeping Vision Router rendering precedence.
->
-> v1.2.3 fixes DSH Desktop's re-appearing first-run dialog: the onboarding "seen" flag and the model-guide step now persist in the profile settings file instead of origin-scoped `localStorage`, which a random per-launch port (`--port 0`) wiped on every boot (issue #78).
->
-> v1.2.2 closed the last attachment-id gap — ids announced for images the host persisted itself (e.g. `read_image` re-uploads, `sha256:…`) now resolve in `vision_describe` and every pixel tool (issue #72) — stopped `vision_present` and other tool-result image blocks from ever locking a text-model session with `UNSUPPORTED_CONTENT` (issue #74; already-locked sessions heal after upgrading), and warned loudly when a stale sharp left over from a pre-v1.2 upgrade would break the pixel tools with `colourspace: parameter space not set` (issue #75).
->
-> v1.2.1 hardened the pixel loop: all eleven pixel tools now accept uploaded-image attachment ids directly (no more `cannot read …/sha256:…` round trips), artifact filenames carry collision-free fingerprints, `vision_ground` retries degenerate boxes, the model guide replays fully from step 1 (leaving the settings first), and the settings card scrolls smoothly even with hundreds of models per provider.
+> **v1.4.0 now supports** automatic recognition and direct-channel bridging of undeclared vision models, doctor repair of stale version-pinned exemptions, and a spotlight-guided onboarding walkthrough — plus hardened settings-save verification and vision-backend compatibility.
 
 <p align="center">
   <img src="assets/vision-demo.gif" width="640" alt="Demo: paste an image, the agent locates the send button with vision_ground / vision_crop / vision_pixel_diff and answers with coordinates" />
 </p>
 
+## Contents
+
+- [Why this exists](#why-this-exists)
+- [How it compares](#how-it-compares)
+- [Quick start](#quick-start)
+- [Highlights](#highlights)
+- [How it works](#how-it-works)
+- [Tools](#tools)
+- [Configuration](#configuration)
+- [Install and lifecycle](#install-and-lifecycle)
+- [Troubleshooting](#troubleshooting)
+
 ## Why this exists
 
 Most DSH vision plugins bridge images to DeepSeek as *text descriptions* — lossy, one-shot, and blind to pixels. This plugin keeps the **original pixels on the vision model's side** and DeepSeek on the reasoning side, and makes looking at an image an **ordinary tool call**:
@@ -72,24 +78,25 @@ Both are MIT-licensed and one command away. Pick this plugin when you want image
 
 ## Quick start
 
-### 1. Install and load the plugin
+### 1. Install the plugin
 
-Recommended for normal npm/npx installs (the same launch style used by the DSH README):
+For normal npm/npx installs, installation is a single command:
 
 ```sh
 npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router
-npx @deepseek-ai/dsh web
 ```
 
+> [!NOTE]
+> Third-party `dsh-web-plugin-manager` / `dshpm` **v0.4.2+** is also compatible: its quality gate now correctly allows `@deepseek-ai/schemastery` as a runtime dependency. The official DSH CLI above remains the recommended install path.
+
 If you run DeepSeek Harness from a source checkout with pnpm, use the workspace script instead — `dsh` is not necessarily on your shell `PATH`:
 
 ```sh
 cd deepseek-harness
 pnpm dsh plugin --profile web add dsh-vision-router
-pnpm dsh web
 ```
 
-If you already installed the DSH CLI globally and `dsh` is on `PATH`, the shorter `dsh ...` form works too.
+If you already installed the DSH CLI globally and `dsh` is on `PATH`, the shorter `dsh ...` form works too. After installation, start or reload DSH Web as you normally do.
 
 > [!NOTE]
 > If you install the plugin **into a Web process that was already running long-term**, let that DSH Web process reload once so the plugin bundle itself is discovered. After the plugin is loaded, adding/removing models or changing wrapper scope **hot-updates without further DSH restarts**.
@@ -288,18 +295,23 @@ Everything is optional; defaults work out of the box. Edit via the Web card or a
 
 ### Install
 
-Normal npm/npx install:
+Normal npm/npx install — one command:
 
 ```sh
 npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router
-npx @deepseek-ai/dsh --profile web --dump-config | grep vision-router
 ```
 
 From a DeepSeek Harness source checkout:
 
 ```sh
 pnpm dsh plugin --profile web add dsh-vision-router
-pnpm dsh --profile web --dump-config | grep vision-router
+```
+
+Optional verification:
+
+```sh
+npx @deepseek-ai/dsh --profile web --dump-config | grep vision-router
+# source checkout: pnpm dsh --profile web --dump-config | grep vision-router
 ```
 
 When first adding the plugin to an already long-lived Web profile, let that Web process reload the plugin bundle; the host discovers the browser bundle through `dsh.client` at startup. **After the plugin is loaded, model-catalog and wrapper-scope changes hot-update and do not require a restart.**
@@ -325,6 +337,8 @@ pnpm dsh plugin --profile web update dsh-vision-router
 
 Settings live in the profile's settings provider and survive upgrades.
 
+> **A fresh release does not take effect (`downloaded 0` / `added 0`):** pnpm v11 holds versions younger than 24h back; `npx dsh-vision-router repair` fixes the stale version-pinned profile exemption so updates take effect immediately.
+
 > **Upgrading from a pre-bundle-patch install (v0.x):** the package now mounts
 > itself through its own bundle patch, so a leftover manual row in
 > `~/.dsh/profiles/<profile>/cordis.patch.yml` duplicates it and `dsh web`

package/README.zh.md

@@ -15,7 +15,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.3.0"><img src="https://img.shields.io/badge/release-v1.3.0-5B4CF0?style=flat-square" alt="Release v1.3.0" /></a>
+  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.4.0"><img src="https://img.shields.io/badge/release-v1.4.0-5B4CF0?style=flat-square" alt="Release v1.4.0" /></a>
   <a href="tests"><img src="https://img.shields.io/badge/verified-149%20tests-2EA44F?style=flat-square" alt="Verified: 149 tests" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2EA44F?style=flat-square" alt="License: MIT" /></a>
   <a href="package.json"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-339933?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white" alt="Node.js >=22" /></a>
@@ -28,20 +28,26 @@
 <p align="center">💬 <strong>QQ 用户交流群：1105463028</strong></p>
 
 > [!WARNING]
-> 📌 **公告（v1.3.0）**
+> 📌 **公告（v1.4.0）**
 >
-> **v1.3.0** 重点加固长会话稳定性与插件共存：视觉工具 schema 默认从会话开始保持稳定，减少 prefix/KV cache 失效；诊断日志可持久化并从设置页直接打开；自定义视觉模型缺失 image 元数据时会明确解释并支持重新检测；宿主提供的 DSH capability 包使用正确的 peer 依赖契约；与其他视觉插件共装时，同名工具卡不再导致启动失败，同时保留 Vision Router 自己的渲染优先级。
->
-> v1.2.3 现已支持：修复 DSH Desktop 每次启动都重复弹出首次引导的问题——引导「已读」标记与模型引导步骤改存 profile 设置文件（不再依赖按 origin 隔离、每次随机端口重启即清零的 `localStorage`）（issue #78）。
->
-> v1.2.2 现已支持：补上最后一处附件 ID 缺口——宿主 `read_image` 回挂图片公布的 `sha256:…` ID 现在可被 `vision_describe` 与全部像素工具解析（issue #72）；`vision_present` 等工具结果里的图像块不再把文本模型会话锁死在 `UNSUPPORTED_CONTENT`（issue #74，已锁死的历史会话升级后自动修复）；检测到 v1.1.x 升级残留的旧版 sharp 时明确告警，把玄学的 `colourspace` 报错变成一眼可见的修复指引（issue #75）。
->
-> v1.2.1 加固像素闭环：十一个像素工具可直接接受上传图片的附件 ID（告别 `cannot read …/sha256:…` 的绕路），产物文件名带指纹不再互相覆盖，`vision_ground` 对退化框自动重试，模型引导支持从第 1 步完整重放（先退出设置页），设置卡片在数百模型目录下滚动依然流畅。
+> **v1.4.0 现已支持**：未声明视觉模型的自动识别与直连桥接、doctor 修复过期版本钉住豁免、引导流程聚光灯高亮——并增强设置保存校验与视觉后端兼容性。
 
 <p align="center">
   <img src="assets/vision-demo.gif" width="640" alt="演示：粘贴图片，Agent 用 vision_ground / vision_crop / vision_pixel_diff 定位发送按钮并给出坐标" />
 </p>
 
+## 目录
+
+- [为什么做这个](#为什么做这个)
+- [对比同类插件](#对比同类插件)
+- [快速开始](#快速开始)
+- [亮点](#亮点)
+- [工作原理](#工作原理)
+- [工具](#工具)
+- [配置项](#配置项)
+- [安装与生命周期](#安装与生命周期)
+- [故障排查](#故障排查)
+
 ## 为什么做这个
 
 大多数 DSH 视觉插件把图片“翻译”成一段文字描述再喂给 DeepSeek——有损、一次性、看不见像素。本插件把**原图像素留在视觉模型侧**、把推理留在 DeepSeek 侧，并把“看图”变成一次**普通的工具调用**：
@@ -72,24 +78,25 @@
 
 ## 快速开始
 
-### 1. 安装并让插件加载
+### 1. 安装插件
 
-普通 npm / npx 安装方式推荐这样用（与 DSH 官方 README 的启动方式一致）：
+普通 npm / npx 安装只需要一条命令：
 
 ```sh
 npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router
-npx @deepseek-ai/dsh web
 ```
 
+> [!NOTE]
+> 第三方 `dsh-web-plugin-manager` / `dshpm` **v0.4.2+** 现已兼容：其质量门已正确放行作为运行时依赖的 `@deepseek-ai/schemastery`。上面的官方 DSH CLI 仍是推荐安装方式。
+
 如果你是从 DeepSeek Harness 源码仓库通过 pnpm 运行，`dsh` 不一定在系统 `PATH` 里，请改用工作区脚本：
 
 ```sh
 cd deepseek-harness
 pnpm dsh plugin --profile web add dsh-vision-router
-pnpm dsh web
 ```
 
-如果你已经全局安装 DSH CLI，并且终端里能直接执行 `dsh`，也可以继续使用较短的 `dsh ...` 写法。
+如果你已经全局安装 DSH CLI，并且终端里能直接执行 `dsh`，也可以继续使用较短的 `dsh ...` 写法。安装完成后，按你平时的方式启动或重新加载 DSH Web 即可。
 
 > [!NOTE]
 > 如果你是把插件**首次安装进一个已经长期运行的 Web 进程**，需要让 DSH Web 进程重新加载一次插件本体。插件加载完成后，新增/删除模型、修改自动识图包装范围都会**热更新，无需再重启 DSH**。
@@ -288,18 +295,23 @@ Web 配置页在 **设置 → 插件 → 插件配置** 下注册「视觉路由
 
 ### 安装
 
-普通 npm / npx 安装：
+普通 npm / npx 安装——一条命令：
 
 ```sh
 npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router
-npx @deepseek-ai/dsh --profile web --dump-config | grep vision-router
 ```
 
 从 DeepSeek Harness 源码仓库运行：
 
 ```sh
 pnpm dsh plugin --profile web add dsh-vision-router
-pnpm dsh --profile web --dump-config | grep vision-router
+```
+
+可选验证：
+
+```sh
+npx @deepseek-ai/dsh --profile web --dump-config | grep vision-router
+# 源码仓库：pnpm dsh --profile web --dump-config | grep vision-router
 ```
 
 首次把插件装进已经长期运行的 Web profile 时，需要让 Web 进程重新加载插件本体；宿主在启动时通过 `dsh.client` 声明发现浏览器端包。**插件加载完成后，模型目录与包装范围的变化会热更新，不需要为这些变化重启。**
@@ -325,6 +337,8 @@ pnpm dsh plugin --profile web update dsh-vision-router
 
 设置存放在 profile 的设置提供方里，升级不丢失。
 
+> **新版本一直不生效（`downloaded 0` / `added 0`）：** pnpm v11 会拦下发布不足 24 小时的版本；运行 `npx dsh-vision-router repair` 修复过期的带版本号豁免条目后，更新立即生效。
+
 > **从 bundle 补丁之前（v0.x）升级：** 现在插件由自带的 bundle 补丁自动挂载，
 > 若 `~/.dsh/profiles/<profile>/cordis.patch.yml` 里还残留旧版手动行，会与之
 > 重复，`dsh web` 启动即报 `duplicate loader entry id: vision-router`。删除

package/docs/doctor.md

@@ -32,7 +32,7 @@ To inspect only the Web profile:
 npx dsh-vision-router doctor --profile web
 ```
 
-The command locates the DSH home (`$DSH_HOME` when set, otherwise `~/.dsh`), scans profile `package.json` files, reports UTF-8 BOM bytes, validates the JSON after ignoring a leading BOM for diagnosis, and reports whether `dsh-vision-router` is present as a profile dependency and bundle layer.
+The command locates the DSH home (`$DSH_HOME` when set, otherwise `~/.dsh`), scans profile `package.json` files, reports UTF-8 BOM bytes, validates the JSON after ignoring a leading BOM for diagnosis, reports whether `dsh-vision-router` is present as a profile dependency and bundle layer, and flags version-pinned `minimumReleaseAgeExclude` entries in the profile's `pnpm-workspace.yaml` that would hold back the next release.
 
 ## Repair the UTF-8 BOM startup failure
 
@@ -50,3 +50,21 @@ npx dsh-vision-router repair --profile web
 ```
 
 `repair` removes only the three-byte UTF-8 BOM prefix (`EF BB BF`) when it is present, then validates the remaining JSON. It does not reformat, regenerate, or otherwise rewrite the profile contents. If JSON is still invalid for another reason, the command reports that and stops rather than guessing a repair.
+
+## Repair a stale release-age exemption (the "update does nothing" gate)
+
+pnpm v11 defaults `minimumReleaseAge` to 1440 minutes: a version published less than 24 hours ago is not resolved, so `dsh plugin update` silently keeps the previous version and prints `downloaded 0 / added 0`. An exemption entry that pins a version — `dsh-vision-router@1.2.0` — only exempts that one version and goes stale on the next release, which is why "a new release is out but the update does nothing" keeps recurring.
+
+The doctor flags version-pinned entries for `dsh-vision-router` and the `@deepseek-ai/*` host packages:
+
+```text
+✗ web — … — release-age exemption version-pinned (dsh-vision-router@1.2.0) — releases younger than 24h will not be picked up
+```
+
+Run:
+
+```sh
+npx dsh-vision-router repair --profile web
+```
+
+to rewrite them to bare names (`dsh-vision-router`, `@deepseek-ai/*`), which exempt every future version, so upgrades take effect immediately again. Unrelated entries and the rest of the file are left untouched.

package/index.js

@@ -233,6 +233,12 @@ export const Config = z.object({
   tool: z.boolean().default(true),
   progressiveTools: z.boolean().default(true),
   autoActivateOnImage: z.boolean().default(true),
+  // User feedback (Zhipu official channel): some channels expose vision
+  // models whose catalog metadata does not declare image input. Models the
+  // built-in name inference does not recognize can be forced here — one model
+  // id (or "provider/model") per entry. Only consulted for vision BACKEND
+  // capability (the session-side admission stays host-owned).
+  extraVisionModels: z.array(z.string()).default([]),
   // Client-persisted UI state (issue #78): DSH Desktop serves the Web UI from
   // a random port on every launch, so origin-scoped localStorage forgets the
   // first-run onboarding dialog and it re-appeared on every boot. These keys
@@ -2005,6 +2011,158 @@ export function modelInfoAcceptsImages(info) {
   return Array.isArray(info && info.inputModalities) && info.inputModalities.includes('image')
 }
 
+// User feedback: channels like the Zhipu official one (open.bigmodel.cn,
+// configured with a custom model list) expose vision models whose catalog
+// metadata does NOT declare image input, even though the models accept images
+// (e.g. glm-4.6v). DSH's Web settings do not write the `input: [text, image]`
+// declaration for custom channels either, so a strict metadata check hides
+// perfectly usable vision backends. The conservative, curated name patterns
+// below recognize well-known multimodal model families as a fallback; models
+// that still do not match can be forced via the `extraVisionModels` setting.
+// A vision-looking name does not necessarily identify a generative chat model.
+// Embedding and reranker endpoints often share the same VL family prefix but
+// cannot answer vision_describe. Keep them out of the automatic candidate
+// set; an explicit extraVisionModels override remains the expert escape hatch.
+const NON_GENERATIVE_VISION_MODEL_HINTS = [
+  /(^|[\/_.-])(embedding|embeddings|embed)(?=$|[\/_.-])/i,
+  /(^|[\/_.-])(rerank|reranker|reranking)(?=$|[\/_.-])/i,
+]
+
+export function looksLikeNonGenerativeVisionModel(modelId) {
+  const id = String(modelId ?? '').trim()
+  if (id === '') return false
+  return NON_GENERATIVE_VISION_MODEL_HINTS.some((pattern) => pattern.test(id))
+}
+
+const VISION_MODEL_NAME_HINTS = [
+  // Zhipu VLM family: glm-4.6v, glm-4.6v-flash, glm-4v-plus, glm-4.5v(-plus)…
+  /(^|\/)glm-4[\w.-]*v(?=$|[-/])/i,
+  /(^|\/)glm-4v(?=$|[-/])/i,
+  // Qwen VL / QVQ vision-reasoning family (excludes plain qwen3-14b etc.).
+  /(^|\/)qwen[\w.-]*(vl|vision)/i,
+  /(^|\/)qvq(?=$|[-.])/i,
+  // OpenAI multimodal line (gpt-4o*, gpt-4.1*, gpt-5*, gpt-oss*).
+  /(^|\/)gpt-(4o|4\.1|5|oss)(?=$|[-.])/i,
+  /(^|\/)gemini/i,
+  // Claude 3+ / Sonnet/Opus/Haiku are multimodal (claude-2 is not).
+  /(^|\/)(claude-(3|4)(?=$|[-.])|claude[\w.-]*(sonnet|opus|haiku))/i,
+  /(^|\/)(internvl|cogvlm|llava|pixtral)/i,
+  /(^|\/)(doubao|hunyuan|minimax|ernie)[\w.-]*(vl|vision)/i,
+  /(^|\/)ernie-4\.5/i,
+  /(^|\/)(yi-vision|kimi[\w.-]*vision|moonshot[\w.-]*vision)/i,
+  /(^|\/)step[\w.-]*(v|vision)(?=$|[-/])/i,
+  /(^|\/)grok[\w.-]*vision/i,
+  /(^|\/)grok-4(?=$|[-.])/i,
+  /(^|\/)llama[\w.-]*vision/i,
+  /(^|\/)mistral[\w.-]*pixtral/i,
+  /(^|\/)(phi[\w.-]*vision|florence[\w.-]*)/i,
+]
+
+/**
+ * Conservative name-based inference for vision capability: true only when the
+ * model id matches a well-known multimodal naming pattern. Used as a fallback
+ * when catalog metadata does not declare image input; never overrides an
+ * explicit text-only declaration on the session/twin paths.
+ */
+export function looksLikeVisionModel(modelId) {
+  const id = String(modelId ?? '').trim()
+  if (id === '' || looksLikeNonGenerativeVisionModel(id)) return false
+  return VISION_MODEL_NAME_HINTS.some((pattern) => pattern.test(id))
+}
+
+/**
+ * Pure capability decision for a vision backend: an explicit user override
+ * wins first, known non-generative endpoint roles are excluded next, then
+ * declared image metadata and conservative name inference are considered.
+ *
+ * @param info - resolved model metadata (may be undefined when the lookup failed).
+ * @param provider - provider id, used to match "provider/model" override entries.
+ * @param model - model id.
+ * @param extraVisionModels - user-configured model ids (or "provider/model") forced vision-capable.
+ * @returns { image, inputModalities, inferred, reason } where `inferred` is
+ * false for declared image input, 'override' for the user list, 'name' for the
+ * naming heuristic, and `reason` explains a text-only verdict.
+ */
+export function decideVisionBackendCapability(info, provider, model, extraVisionModels) {
+  const inputModalities = Array.isArray(info && info.inputModalities)
+    ? info.inputModalities.filter((item) => typeof item === 'string')
+    : []
+  const modelId = String(model ?? '').trim()
+  const providerId = String(provider ?? '').trim()
+  const extras = Array.isArray(extraVisionModels)
+    ? extraVisionModels.map((entry) => String(entry ?? '').trim()).filter((entry) => entry !== '')
+    : []
+  const forced =
+    modelId !== '' &&
+    extras.some((entry) => entry === modelId || (providerId !== '' && entry === `${providerId}/${modelId}`))
+  // Manual override is deliberately strongest: advanced users can still
+  // force an unusual endpoint that our role/name heuristics reject.
+  if (forced) {
+    return { image: true, inputModalities: [...new Set([...inputModalities, 'image'])], inferred: 'override', reason: undefined }
+  }
+  // A model can consume images and still be the wrong KIND of endpoint
+  // for this plugin: embedding/reranking produces no assistant answer.
+  if (modelId !== '' && looksLikeNonGenerativeVisionModel(modelId)) {
+    return {
+      image: false,
+      inputModalities,
+      inferred: false,
+      reason: 'model name indicates an embedding/reranker endpoint, not a generative vision backend',
+    }
+  }
+  if (inputModalities.includes('image')) {
+    return { image: true, inputModalities, inferred: false, reason: undefined }
+  }
+  if (modelId !== '' && looksLikeVisionModel(modelId)) {
+    return { image: true, inputModalities: [...new Set([...inputModalities, 'image'])], inferred: 'name', reason: undefined }
+  }
+  return {
+    image: false,
+    inputModalities,
+    inferred: false,
+    reason: 'model metadata does not declare image input',
+  }
+}
+
+/**
+ * Resolve transport facts for the direct channel compatibility bridge.
+ * Raw llm-pi-ai settings commonly omit baseURL/api for built-in catalog
+ * providers; the materialized pi-ai model carries the effective values.
+ */
+export function resolveChannelBridgeTransport(rawProfile, resolvedProfile, modelId) {
+  let resolvedModel
+  try {
+    const getModels = resolvedProfile && resolvedProfile.piProvider && resolvedProfile.piProvider.getModels
+    const models = typeof getModels === 'function'
+      ? getModels.call(resolvedProfile.piProvider)
+      : []
+    resolvedModel = Array.isArray(models)
+      ? models.find((entry) => entry && String(entry.id) === String(modelId))
+      : undefined
+  } catch {
+    resolvedModel = undefined
+  }
+  const firstString = (...values) =>
+    values.find((value) => typeof value === 'string' && value.trim() !== '')
+  return {
+    baseURL: firstString(
+      resolvedModel && resolvedModel.baseUrl,
+      rawProfile && rawProfile.baseURL,
+      resolvedProfile && resolvedProfile.baseURL,
+      resolvedProfile && resolvedProfile.piProvider && resolvedProfile.piProvider.baseUrl,
+    ),
+    api: firstString(
+      resolvedModel && resolvedModel.api,
+      rawProfile && rawProfile.api,
+      resolvedProfile && resolvedProfile.api,
+    ),
+    apiKeyEnv: firstString(
+      rawProfile && rawProfile.apiKeyEnv,
+      resolvedProfile && resolvedProfile.apiKeyEnv,
+    ),
+  }
+}
+
 export function apply(ctx, config = {}) {
   // Route sharp version diagnostics (issue #75) through the harness logger
   // instead of console.warn, so the warning lands in the server log.
@@ -2640,15 +2798,13 @@ export function apply(ctx, config = {}) {
     }
     try {
       const info = await ctx.llm.resolveModelInfo(provider, model)
-      const inputModalities = Array.isArray(info && info.inputModalities)
-        ? info.inputModalities.filter((item) => typeof item === 'string')
-        : []
-      return {
-        image: modelInfoAcceptsImages(info),
-        inputModalities,
-        reason: modelInfoAcceptsImages(info) ? undefined : 'model metadata does not declare image input',
-      }
+      return decideVisionBackendCapability(info, provider, model, current().extraVisionModels)
     } catch (error) {
+      // Metadata lookup failed (custom model lists often do): fall back to
+      // the user override list and the name heuristic before declaring the
+      // model text-only.
+      const fallback = decideVisionBackendCapability(undefined, provider, model, current().extraVisionModels)
+      if (fallback.image) return fallback
       return {
         image: false,
         inputModalities: [],
@@ -2657,6 +2813,123 @@ export function apply(ctx, config = {}) {
     }
   }
 
+  // ── direct OpenAI-compatible bridge for undeclared vision channels ─────────
+  //
+  // User feedback (Zhipu official channel, open.bigmodel.cn): some channels
+  // expose vision models whose catalog metadata does NOT declare image input,
+  // so the channel adapter refuses image requests at the wire
+  // (UNSUPPORTED_CONTENT: model "x" does not support image input) even though
+  // the models accept images. For backends recognized only through the name
+  // inference or the extraVisionModels override, fall back to calling the
+  // channel's OpenAI-compatible endpoint directly with the channel's own
+  // baseURL and credential — no hand-edited settings.yaml needed. Defensive
+  // reads only: if the channel settings section, the baseURL, or the
+  // credential cannot be resolved, the bridge is simply unavailable and the
+  // adapter's own error is reported.
+  const rawChannelProfileOf = (provider) => {
+    try {
+      const settings = ctx.get('settings')
+      const section =
+        settings && typeof settings.get === 'function' ? settings.get('llm-pi-ai') : undefined
+      return section && section.providers ? section.providers[provider] : undefined
+    } catch {
+      return undefined
+    }
+  }
+  // DSH's public model metadata intentionally omits endpoint/protocol
+  // details. PiAiAdapter has already materialized those facts in its
+  // resolved profile, so feature-detect that shape as a compatibility
+  // shim. If upstream changes it, this fails closed to the normal chain.
+  const resolvedPiAiProfileOf = (provider) => {
+    try {
+      const registration = ctx.llm.registration(provider)
+      const adapter = registration && registration.adapter
+      const config = adapter && adapter.config
+      const profiles = config && typeof config.profiles === 'function' ? config.profiles() : undefined
+      return profiles && typeof profiles.get === 'function' ? profiles.get(provider) : undefined
+    } catch {
+      return undefined
+    }
+  }
+  const channelBridgePlan = (provider, model) => {
+    const rawProfile = rawChannelProfileOf(provider)
+    const resolvedProfile = resolvedPiAiProfileOf(provider)
+    const transport = resolveChannelBridgeTransport(rawProfile, resolvedProfile, model)
+    if (!transport.baseURL) {
+      return { ok: false, reason: 'no resolved channel baseURL', rawProfile, resolvedProfile, transport }
+    }
+    // callOpenAICompatible speaks Chat Completions. Never send another
+    // provider protocol through this bridge just because its name looks visual.
+    if (transport.api !== 'openai-completions') {
+      return {
+        ok: false,
+        reason: `channel protocol ${transport.api || 'unknown'} is not OpenAI Chat Completions`,
+        rawProfile,
+        resolvedProfile,
+        transport,
+      }
+    }
+    return { ok: true, rawProfile, resolvedProfile, transport }
+  }
+  const resolveChannelApiKey = async (plan) => {
+    const ref = plan && plan.transport && plan.transport.apiKeyEnv
+    if (typeof ref === 'string' && ref !== '') {
+      try {
+        const credentials = ctx.get('credentials')
+        if (credentials !== undefined) {
+          const hit = await credentials.resolve(ref)
+          if (hit && typeof hit.value === 'string' && hit.value.length > 0) return hit.value
+        }
+      } catch {
+        /* fall through to the ambient environment */
+      }
+      if (typeof process !== 'undefined' && process.env && typeof process.env[ref] === 'string') {
+        return process.env[ref]
+      }
+    }
+    // Catalog routes may use provider-native environment discovery and
+    // therefore carry no explicit Harness credential reference.
+    try {
+      const auth = plan && plan.resolvedProfile && plan.resolvedProfile.piProvider
+        && plan.resolvedProfile.piProvider.auth && plan.resolvedProfile.piProvider.auth.apiKey
+      if (auth && typeof auth.resolve === 'function') {
+        const hit = await auth.resolve({ credential: undefined })
+        const value = hit && hit.auth && hit.auth.apiKey
+        if (typeof value === 'string' && value.length > 0) return value
+      }
+    } catch {
+      /* unavailable native auth */
+    }
+    return undefined
+  }
+  const directChannelVisionAnswer = async (provider, model, blocks, instruction, signal) => {
+    const plan = channelBridgePlan(provider, model)
+    if (!plan.ok) throw new Error(`vision bridge unavailable: ${plan.reason}`)
+    const apiKey = await resolveChannelApiKey(plan)
+    if (apiKey === undefined || apiKey === '') {
+      throw new Error('vision bridge unavailable: channel credential could not be resolved')
+    }
+    const attachments = ctx.get('attachments')
+    if (attachments === undefined) {
+      throw new Error('vision bridge unavailable: attachment service is not registered')
+    }
+    const content = []
+    for (const block of blocks) {
+      const stored = await attachments.readImage(block.attachment)
+      content.push(...toOpenAIContent([block], () => stored.data))
+    }
+    return callOpenAICompatible(
+      {
+        name: provider,
+        baseURL: plan.transport.baseURL,
+        model,
+        apiKeyEnv: '__vision-router-channel__',
+      },
+      [{ role: 'user', content: [...content, { type: 'text', text: instruction }] }],
+      { maxTokens: 4096, signal, resolveCredential: () => apiKey },
+    )
+  }
+
   const collectVisionBackendCapabilities = async () => {
     const capabilities = {}
     if (typeof ctx.llm.listProviders !== 'function') return capabilities
@@ -3768,6 +4041,7 @@ export function apply(ctx, config = {}) {
       const block = await visionBlocksFromBytes(imageBytes, mediaType)
       const signal = AbortSignal.timeout(timeoutMs())
       const usablePairs = await resolveToolVisionPairs()
+      const pairCapabilities = new Map()
       for (const pair of pairs()) {
         if (!pair || pair.provider === HTTP_ROUTE) continue
         if (!adapterAvailable(ctx.llm, pair.provider)) {
@@ -3775,6 +4049,7 @@ export function apply(ctx, config = {}) {
           continue
         }
         const capability = await resolveVisionBackendCapability(pair.provider, pair.model)
+        pairCapabilities.set(`${pair.provider}/${pair.model}`, capability)
         if (!capability.image) {
           errors.push(
             `${pair.provider}/${pair.model}: not an image-capable backend (${capability.reason ?? 'unknown capability'})`,
@@ -3782,6 +4057,16 @@ export function apply(ctx, config = {}) {
         }
       }
       for (const pair of usablePairs) {
+        // usablePairs also contains auto-discovered models. Before this fix the
+        // map was populated only from explicit config rows, so inferred
+        // SiliconFlow models failed pi-ai image admission and never reached
+        // the direct channel bridge that was meant to rescue them.
+        const pairKey = `${pair.provider}/${pair.model}`
+        let pairCapability = pairCapabilities.get(pairKey)
+        if (pairCapability === undefined) {
+          pairCapability = await resolveVisionBackendCapability(pair.provider, pair.model)
+          pairCapabilities.set(pairKey, pairCapability)
+        }
         try {
           const text = await visionAnswer(ctx.llm, {
             provider: pair.provider,
@@ -3794,6 +4079,30 @@ export function apply(ctx, config = {}) {
           })
           if (text && text.trim() !== '') return { text: text.trim() }
         } catch (error) {
+          // Channels whose catalog does not declare image input reject images
+          // at the adapter wire. When the backend was recognized by the name
+          // inference or the extraVisionModels override, call the channel's
+          // OpenAI-compatible endpoint directly with its own baseURL and
+          // credential before giving up on this pair.
+          const capability = pairCapabilities.get(`${pair.provider}/${pair.model}`)
+          if (capability && capability.inferred) {
+            try {
+              const direct = await directChannelVisionAnswer(
+                pair.provider,
+                pair.model,
+                [block],
+                instruction,
+                signal,
+              )
+              if (direct && direct.trim() !== '') return { text: direct.trim() }
+            } catch (bridgeError) {
+              errors.push(
+                `${pair.provider}/${pair.model}: direct channel fallback failed (${
+                  bridgeError && bridgeError.message ? bridgeError.message : String(bridgeError)
+                })`,
+              )
+            }
+          }
           errors.push(`${pair.provider}/${pair.model}: ${error && error.message ? error.message : String(error)}`)
         }
       }