dsh-vision-router 1.2.3 → 1.3.0

package/README.md

@@ -15,7 +15,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.2.1"><img src="https://img.shields.io/badge/release-v1.2.1-5B4CF0?style=flat-square" alt="Release v1.2.1" /></a>
+  <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="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,7 +28,9 @@
 <p align="center">💬 <strong>QQ community group: 1105463028</strong></p>
 
 > [!WARNING]
-> 📌 **Announcement (v1.2.3)**
+> 📌 **Announcement (v1.3.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).
 >
@@ -110,7 +112,7 @@ The auto-vision group follows the live DSH model catalog. Adding models or chang
 
 ### 3. Paste or upload the image
 
-After choosing the “+ Auto Vision” group, paste or upload an image normally. The agent auto-mounts the vision tools and can use `vision_describe`, `vision_ground`, `vision_crop`, and the rest across multiple steps when needed.
+After choosing the “+ Auto Vision” group, paste or upload an image normally. By default the complete vision tool schema is stable from session start, so the agent can immediately use `vision_describe`, `vision_ground`, `vision_crop`, and the rest across multiple steps when needed.
 
 The built-in anonymous OVH vision fallback is already configured, so normal image use needs no signup or API key. **The lower-right chat picker selects only the brain/conversation model**; vision backends do not belong there. Advanced options live under **Settings → Plugins → Plugin config → 视觉路由（自动识图）**: each vision-backend row selects one image-capable user model already configured under **Settings → Models**. Leaving every user row empty is valid; the OVH chain remains the final fallback. `Vision HTTP` is an internal transport route, not a model group users should select.
 
@@ -129,7 +131,7 @@ The built-in anonymous OVH vision fallback is already configured, so normal imag
 - **Automatic failover with classified errors.** Region blocks, ToS filtering, 402 quota, 429 rate limits (with Retry-After backoff), context overflow, network failures — the chain walks providers one by one and only reports after all of them failed, with actionable advice.
 - **Image memory.** Vision answers are cached by attachment content hash; later text turns substitute the recorded description (marked as untrusted evidence), so DeepSeek genuinely remembers earlier images without re-spending vision calls.
 - **A verifiable pixel loop.** Reference → `vision_html_screenshot` → `vision_pixel_diff` (ratio + red heatmap + worst-region ranking) → fix → repeat until the mismatch converges. UI restoration becomes measurable instead of eyeballed.
-- **Progressive schema exposure.** Only a zero-arg `vision_activate` bootstrap is always visible; image turns auto-mount all eleven deep tools with a one-time usage note, and a `vision-tools` skill is registered for text-only turns.
+- **Stable tool schema.** All eleven deep tools are registered from session start by default, avoiding a mid-conversation tool-list expansion that can invalidate long-context KV/prefix caches. `progressiveTools: true` remains an advanced boot-time opt-in; only then does `vision_activate` mount the tools on demand. See [`docs/progressive-tools-cache.md`](docs/progressive-tools-cache.md).
 - **Selective proxy.** Only the configured vision provider hosts go through your local proxy; DeepSeek stays direct.
 
 ### Pixel loop in practice
@@ -150,7 +152,7 @@ The vision model is **only the eyes**; DeepSeek is **always the brain**. An imag
 
 ## Tools
 
-All eleven deep tools mount automatically on image turns (`autoActivateOnImage`); text turns can mount them via `vision_activate` or the `/vision-tools` skill. Built on sharp / potrace / tesseract / system Chrome — no Python:
+Default `progressiveTools: false`: all eleven deep tools stay registered from plugin startup, so text and image turns can call them immediately. If you explicitly set `progressiveTools: true` in the profile/composition `cordis.patch.yml`, progressive mode is restored: only `vision_activate` is exposed initially, the full tool set mounts on first use, and the `vision-tools` skill is registered. This is a boot-time switch; restart DSH after changing it. Built on sharp / potrace / tesseract / system Chrome — no Python:
 
 <p align="center">
   <img src="assets/vision-tools.svg" width="100%" alt="Eleven vision tools available in DSH Vision Router." />
@@ -266,7 +268,7 @@ Everything is optional; defaults work out of the box. Edit via the Web card or a
 | `wrapperRoute` / `chainRoute` | `deepseek-vision` / `vision-chain` | admission wrapper route name / fallback chain route name (empty disables) |
 | `stealth` | `false` | take over the official `deepseek-official` route (official row only; custom routes are auto-wrapped by default) |
 | `textProvider` | `deepseek-official` / `deepseek-v4-pro` | the model that reasons (your daily model) |
-| `tool` / `progressiveTools` / `autoActivateOnImage` | `true` ×3 | vision tools on / progressive mounting / auto-mount on image turns |
+| `tool` / `progressiveTools` / `autoActivateOnImage` | `true` / `false` / `true` | vision tools on / progressive mounting (off by default for a stable tool schema) / image-turn auto-mount when progressive mode is enabled; `progressiveTools` is boot-time config |
 | `rewriteImages` | `true` | rewrite image blocks in the model input (cached description or tool-hint marker); the UI log keeps images |
 | `downscale` / `downscaleMaxPixels` | `true` / `4000000` | pre-call downscale and its pixel budget (latency guard) |
 | `cache` / `cacheTtlSeconds` / `cacheMaxEntries` | `true` / `3600` / `200` | vision answer cache |

package/README.zh.md

@@ -15,7 +15,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.2.1"><img src="https://img.shields.io/badge/release-v1.2.1-5B4CF0?style=flat-square" alt="Release v1.2.1" /></a>
+  <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="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,7 +28,9 @@
 <p align="center">💬 <strong>QQ 用户交流群：1105463028</strong></p>
 
 > [!WARNING]
-> 📌 **公告（v1.2.3）**
+> 📌 **公告（v1.3.0）**
+>
+> **v1.3.0** 重点加固长会话稳定性与插件共存：视觉工具 schema 默认从会话开始保持稳定，减少 prefix/KV cache 失效；诊断日志可持久化并从设置页直接打开；自定义视觉模型缺失 image 元数据时会明确解释并支持重新检测；宿主提供的 DSH capability 包使用正确的 peer 依赖契约；与其他视觉插件共装时，同名工具卡不再导致启动失败，同时保留 Vision Router 自己的渲染优先级。
 >
 > v1.2.3 现已支持：修复 DSH Desktop 每次启动都重复弹出首次引导的问题——引导「已读」标记与模型引导步骤改存 profile 设置文件（不再依赖按 origin 隔离、每次随机端口重启即清零的 `localStorage`）（issue #78）。
 >
@@ -110,7 +112,7 @@ opencode-go + 自动识图       ← 发图片时选这个
 
 ### 3. 直接粘贴或上传图片
 
-选好「+ 自动识图」模型组后，直接往对话里贴图即可。Agent 会自动挂载视觉工具，通过 `vision_describe`、`vision_ground`、`vision_crop` 等工具看图，需要时连续多步操作。
+选好「+ 自动识图」模型组后，直接往对话里贴图即可。默认情况下完整视觉工具表从会话开始就保持稳定，Agent 可直接调用 `vision_describe`、`vision_ground`、`vision_crop` 等工具看图，需要时连续多步操作。
 
 默认已经有内置 OVH 匿名视觉兜底，无需注册、无需 Key。**聊天页右下角只选择“脑子/会话模型”**；视觉模型不要在那里选。高级配置在 **设置 → 插件 → 插件配置 → 视觉路由（自动识图）**：视觉后端链每一行只选择一个你在 **设置 → 模型** 中已经配置且支持图片输入的用户模型；一行都不填也可以，OVH 免费链会固定在最后兜底。插件内部的 `Vision HTTP` 只是传输实现，不是用户需要选择的模型组。
 
@@ -129,7 +131,7 @@ opencode-go + 自动识图       ← 发图片时选这个
 - **自动降级 + 分类报错。** 地区限制、ToS 风控、402 额度、429 限流（尊重 Retry-After 退避重试）、上下文超长、网络故障——链路逐供应商尝试，全部失败才报错并给出可操作的建议。
 - **图片记忆。** 视觉答案按附件内容哈希缓存；后续文字轮用记录的描述替换历史图片（标注为不可信证据），DeepSeek 真正“记得”之前发过的图，且不重复消耗视觉调用。
 - **可验证的像素闭环。** 参照图 → `vision_html_screenshot` → `vision_pixel_diff`（差异率 + 红色热力图 + 最差区域排行）→ 修复 → 再对比，直到差异收敛。UI 还原从“目测”变成“实测”。
-- **渐进式 schema 暴露。** 平时只有一个零参引导工具 `vision_activate`；图片轮自动挂载全部 11 个深看工具（附一次性使用提示），并为纯文字轮注册 `vision-tools` 技能。
+- **稳定工具 schema。** 默认从会话开始就注册完整 11 个深看工具，避免图片轮中途扩展工具列表导致长上下文的 KV / prefix cache 失效。仍保留 `progressiveTools: true` 作为高级启动期 opt-in；开启后才使用 `vision_activate` 按需挂载。详见 [`docs/progressive-tools-cache.md`](docs/progressive-tools-cache.md)。
 - **选择性代理。** 只有配置的视觉供应商域名走本地代理；DeepSeek 保持直连。
 
 ### 像素闭环实测
@@ -150,7 +152,7 @@ Agent 仅根据参考图复刻 UI，再用 `vision_pixel_diff` 验证最终结
 
 ## 工具
 
-11 个深看工具在图片轮自动挂载（`autoActivateOnImage`）；文字轮可通过 `vision_activate` 或 `/vision-tools` 技能挂载。全部基于 sharp / potrace / tesseract / 系统 Chrome——无 Python：
+默认 `progressiveTools: false`：11 个深看工具从插件启动时就保持常驻，文本轮和图片轮都可直接调用。若你在 profile / composition 的 `cordis.patch.yml` 中显式开启 `progressiveTools: true`，才会恢复渐进模式：初始只暴露 `vision_activate`，首次需要时再挂载完整工具，并注册 `vision-tools` 技能。该开关是启动期配置，修改后需重启 DSH。全部工具基于 sharp / potrace / tesseract / 系统 Chrome——无 Python：
 
 <p align="center">
   <img src="assets/vision-tools-zh.svg" width="100%" alt="DSH Vision Router 的 11 个视觉工具。" />
@@ -266,7 +268,7 @@ Web 配置页在 **设置 → 插件 → 插件配置** 下注册「视觉路由
 | `wrapperRoute` / `chainRoute` | `deepseek-vision` / `vision-chain` | 准入包装路由名 / 降级链路由名（置空关闭） |
 | `stealth` | `false` | 接管官方 `deepseek-official` 路由（仅官方行；自定义路由默认由自动包装处理） |
 | `textProvider` | `deepseek-official` / `deepseek-v4-pro` | 负责思考的模型（你的日常模型） |
-| `tool` / `progressiveTools` / `autoActivateOnImage` | `true` ×3 | 视觉工具开关 / 渐进式挂载 / 图片轮自动挂载 |
+| `tool` / `progressiveTools` / `autoActivateOnImage` | `true` / `false` / `true` | 视觉工具总开关 / 渐进式挂载（默认关闭以稳定工具 schema）/ 渐进模式下图片轮自动挂载；`progressiveTools` 为启动期配置 |
 | `rewriteImages` | `true` | 模型输入层改写图片块（缓存描述或工具提示标记）；界面日志保留图片 |
 | `downscale` / `downscaleMaxPixels` | `true` / `4000000` | 调用前压缩及其像素预算（延迟保护） |
 | `cache` / `cacheTtlSeconds` / `cacheMaxEntries` | `true` / `3600` / `200` | 视觉答案缓存 |

package/cordis.patch.yml

@@ -8,11 +8,15 @@
 # 挂载后是否接管官方 deepseek-official 路由由设置里的「隐身模式」开关决定
 # （默认关；开启后需自行在 profile 补丁层禁用 llm-deepseek 行）。
 
-# 挂载插件行。配置全部可选（默认即内置免费视觉端点 + 工具优先的图片流程），
-# 可在 Web 设置 > 插件 > 插件配置 的「视觉路由」卡片里实时修改。
+# 挂载插件行。默认保持完整视觉工具表常驻（issue #81）：虽然渐进挂载可以
+# 少发一小段工具 schema，但图片轮首次扩展工具列表会改变请求前缀，可能让
+# 长会话的 provider KV/prefix cache 整体失效。高级用户仍可在 profile /
+# composition 补丁中显式把 progressiveTools 改回 true（启动期配置）。
 - insert:
     - id: vision-router
       name: dsh-vision-router
+      config:
+        progressiveTools: false
 
 # 放宽附件图片限制（部署默认 5MB / 4000 万像素 → 20MB / 1 亿像素），
 # 大尺寸设计稿/扫描图可过审。字段可选，不需要可在 profile 补丁层覆写。

package/docs/progressive-tools-cache.md

@@ -0,0 +1,57 @@
+# Progressive tools and prefix cache
+
+中文 | English
+
+## 中文
+
+Vision Router 默认让完整视觉工具表从会话开始就保持稳定。正常通过 DSH bundle 安装时，组合层会提供：
+
+```yaml
+- id: vision-router
+  name: dsh-vision-router
+  config:
+    progressiveTools: false
+```
+
+插件入口本身也把 `progressiveTools` 的 schema 默认值设为 `false`，因此即使后续 profile patch 整块覆盖了 bundle 的 `config`、但没有重述这个字段，也不会意外回到渐进模式。
+
+原因是很多模型服务的 KV / prefix cache 会把工具 schema 视为请求前缀的一部分。若长会话一开始只暴露 `vision_activate`，第一次图片轮再挂载完整视觉工具，工具列表发生变化后可能导致此前的大段会话前缀无法命中缓存。
+
+渐进式暴露仍然保留为高级 opt-in。如果你更在意平时请求中少携带工具 schema，而不依赖长会话前缀缓存，请在 **profile / composition 的 `cordis.patch.yml`** 中显式给 `vision-router` 设置：
+
+```yaml
+- id: vision-router
+  config:
+    progressiveTools: true
+```
+
+`progressiveTools` 决定插件启动时注册哪组工具，因此它是**启动期配置**；不要依赖运行中的 Web 设置热切换这个字段。修改 profile patch 后重启 DSH。
+
+开启后，平时只暴露 `vision_activate`，首次需要时再挂载完整视觉工具；默认关闭时，完整视觉工具从一开始就常驻。视觉工具本身的能力不变。
+
+## English
+
+Vision Router keeps the complete vision tool schema stable from the beginning of a session by default. Normal DSH bundle installs provide this composition layer:
+
+```yaml
+- id: vision-router
+  name: dsh-vision-router
+  config:
+    progressiveTools: false
+```
+
+The public plugin entrypoint also makes `false` the schema default. Therefore a later profile patch that replaces the bundle `config` without restating this field cannot accidentally fall back to progressive mode.
+
+Many model providers include tool schemas in the KV/prefix-cacheable request prefix. If a long conversation starts with only `vision_activate` and the first image turn later mounts the complete vision tool set, that prefix change can invalidate a large cached history.
+
+Progressive exposure remains available as an advanced opt-in. If minimizing the always-present tool schema matters more than long-context prefix-cache stability, explicitly set it in the **profile/composition `cordis.patch.yml`**:
+
+```yaml
+- id: vision-router
+  config:
+    progressiveTools: true
+```
+
+`progressiveTools` determines which tools are registered at plugin startup, so it is a **boot-time setting**; do not rely on changing this field through live Web settings. Restart DSH after changing the profile patch.
+
+When enabled, only `vision_activate` is exposed initially and the complete vision tool set mounts on first use. With the default disabled mode, the complete vision tool set is present from the start. The vision capabilities themselves are unchanged.

package/entry.js

@@ -0,0 +1,51 @@
+// Public plugin entrypoint.
+//
+// Keep the large implementation in index.js, but normalize the progressive
+// tools switch here before Cordis reads the exported Config. Issue #81 showed
+// that changing the tool schema mid-session can invalidate provider prefix/KV
+// caches for very long conversations, so progressive exposure is now an
+// explicit opt-in rather than the implicit fallback.
+
+import z from '@deepseek-ai/schemastery'
+import * as core from './index.js'
+import { installVisionRouterFileLogging } from './lib/file-logger.js'
+
+// Schemastery object schemas expose set() as the supported way to replace a
+// field schema. This mutates the Config object that index.js itself later uses
+// for the settings namespace, so composition config and settings validation
+// agree on the same default.
+core.Config.set('progressiveTools', z.boolean().default(false))
+
+export * from './index.js'
+export const Config = core.Config
+
+// Defense in depth for direct/programmatic callers that invoke apply() without
+// first running the Cordis Config resolver: only an explicit true enables the
+// schema-changing progressive mode. The wrapped context changes only logger:
+// every existing vision-router diagnostic still reaches the host logger and is
+// also persisted to ~/.dsh/logs/vision-router/vision-router.log.
+export function apply(ctx, config = {}) {
+  const logging = installVisionRouterFileLogging(ctx)
+  try {
+    const result = core.apply(logging.ctx, {
+      ...config,
+      progressiveTools: config.progressiveTools === true,
+    })
+    if (result && typeof result.then === 'function') {
+      return result.catch((error) => {
+        logging.logger.error(
+          'vision-router: plugin apply failed: %s',
+          error && error.stack ? error.stack : error && error.message ? error.message : String(error),
+        )
+        throw error
+      })
+    }
+    return result
+  } catch (error) {
+    logging.logger.error(
+      'vision-router: plugin apply failed: %s',
+      error && error.stack ? error.stack : error && error.message ? error.message : String(error),
+    )
+    throw error
+  }
+}

package/lib/client.js

@@ -77,6 +77,14 @@ window.__ModuleLoader__.load({
       visionCapsLoading: '正在验证哪些模型真正支持图片输入…',
       visionCapsError: '视觉能力元数据暂时不可用；为防止误选，暂不提供用户视觉模型下拉。内置 OVH 免费兜底仍可用。',
       visionCapsFiltered: '视觉后端下拉只显示明确声明 image 输入的模型。',
+      visionCapsEmptyTitle: '没有可选的用户视觉模型',
+      visionCapsEmptyBody: '检测到 {count} 个用户模型，但它们都没有被 DSH 明确标记为支持图片，因此已被安全隐藏。',
+      visionCapsHiddenPrefix: '被隐藏的模型：',
+      visionCapsReasonMissingImage: '未声明 image',
+      visionCapsReasonUnverified: '无法验证图片能力',
+      visionCapsHiddenMore: '另有 {count} 个模型未显示',
+      visionCapsMissingImageHint: '如果这里有你刚在「设置 → 模型 → 添加自定义提供方」中添加的视觉模型，请在 $DSH_HOME/settings.yaml 为该模型补上 input: [text, image]，或为整个提供方补上 defaultInput: [text, image]。DSH 当前 Web 表单不会写入这个字段。',
+      visionCapsRetry: '重新检测模型',
       chainInvalidCurrent: '当前保存的视觉后端不支持图片或无法验证，已从下拉列表隐藏，运行时也会跳过：',
       retryCatalog: '重试加载目录',
       advanced: '高级设置',
@@ -98,6 +106,8 @@ window.__ModuleLoader__.load({
       testConnecting: '测试中…',
       testOk: '连接正常',
       testFailed: '连接失败',
+      openLogFolder: '打开日志文件夹',
+      openLogFolderFailed: '无法打开日志文件夹',
       updateTitle: '版本更新',
       checkUpdate: '检查更新',
       updateChecking: '检查中…',
@@ -248,6 +258,14 @@ window.__ModuleLoader__.load({
       visionCapsLoading: 'Checking which models genuinely accept image input…',
       visionCapsError: 'Vision capability metadata is unavailable; user vision-model choices are hidden to prevent bad selections. The built-in OVH fallback still works.',
       visionCapsFiltered: 'The vision-backend dropdown only shows models that explicitly declare image input.',
+      visionCapsEmptyTitle: 'No selectable user vision models',
+      visionCapsEmptyBody: 'DSH reported {count} user models, but none are explicitly marked as accepting images, so Vision Router hid them safely.',
+      visionCapsHiddenPrefix: 'Hidden models:',
+      visionCapsReasonMissingImage: 'image input not declared',
+      visionCapsReasonUnverified: 'image capability could not be verified',
+      visionCapsHiddenMore: '{count} more models not shown',
+      visionCapsMissingImageHint: 'If one of these is a vision model you just added through Settings → Models → Add custom provider, add input: [text, image] to that model in $DSH_HOME/settings.yaml, or defaultInput: [text, image] to the provider. The current DSH Web form does not write this field.',
+      visionCapsRetry: 'Re-detect models',
       chainInvalidCurrent: 'This saved vision backend does not support images or could not be verified. It is hidden from the dropdown and skipped at runtime: ',
       retryCatalog: 'Retry catalog',
       advanced: 'Advanced settings',
@@ -269,6 +287,8 @@ window.__ModuleLoader__.load({
       testConnecting: 'Testing…',
       testOk: 'Connected',
       testFailed: 'Connection failed',
+      openLogFolder: 'Open logs folder',
+      openLogFolderFailed: 'Could not open logs folder',
       updateTitle: 'Updates',
       checkUpdate: 'Check for updates',
       updateChecking: 'Checking…',
@@ -385,9 +405,6 @@ window.__ModuleLoader__.load({
         .map((group) => {
           const models = (group && Array.isArray(group.models) ? group.models : []).filter((model) => {
             if (!model || typeof model.id !== 'string') return false
-            // The built-in backend is defined by this plugin and always
-            // declares image input. Keeping it visible while the capability
-            // request is still loading avoids a blank default editor.
             if (group.id === 'vision-http') return false
             return !!(caps[group.id] && caps[group.id][model.id] && caps[group.id][model.id].image === true)
           })
@@ -396,6 +413,33 @@ window.__ModuleLoader__.load({
         .filter((group) => group && group.models.length > 0)
     }
 
+    function collectFilteredVisionBackends(groups, capabilities) {
+      const caps = capabilities && typeof capabilities === 'object' ? capabilities : {}
+      const hidden = []
+      for (const group of Array.isArray(groups) ? groups : []) {
+        if (
+          !group ||
+          typeof group.id !== 'string' ||
+          group.id === 'vision-http' ||
+          group.id === 'vision-chain' ||
+          group.id.endsWith('-vision')
+        ) continue
+        for (const model of Array.isArray(group.models) ? group.models : []) {
+          if (!model || typeof model.id !== 'string' || model.id === '') continue
+          const capability = caps[group.id] && caps[group.id][model.id]
+          if (capability && capability.image === true) continue
+          hidden.push({
+            provider: group.id,
+            model: model.id,
+            reason: capability && typeof capability.reason === 'string' ? capability.reason : undefined,
+            missingImageDeclaration:
+              !!capability && capability.reason === 'model metadata does not declare image input',
+          })
+        }
+      }
+      return hidden
+    }
+
     // ── field specs ──────────────────────────────────────────────────────────
     const TOGGLE_KEYS = ['routing', 'tool', 'autoWrapProviders', 'stealth']
     const ADVANCED_TOGGLE_KEYS = ['reverseRouting', 'rewriteImages', 'downscale', 'cache', 'freeFallback']
@@ -495,6 +539,10 @@ window.__ModuleLoader__.load({
       '.vr-chain-row{display:flex;align-items:center;gap:8px;margin:6px 0}' +
       '.vr-stealth-notice{color:var(--dsw-alias-label-warning,var(--dsw-alias-label-secondary))}' +
       '.vr-catalog-error{display:flex;align-items:center;gap:10px;flex-wrap:wrap}' +
+      '.vr-vision-empty{margin:8px 0 2px;padding:11px 12px;border:1px solid var(--dsw-alias-label-warning,var(--dsw-alias-border-l2));border-radius:9px;background:var(--dsw-alias-bg-module-platform);display:flex;flex-direction:column;gap:7px}' +
+      '.vr-vision-empty-title{font-size:12px;font-weight:650;color:var(--dsw-alias-label-primary);margin:0}' +
+      '.vr-vision-empty-list{margin:0;padding-left:18px;color:var(--dsw-alias-label-secondary);font-size:12px;line-height:1.6;word-break:break-word}' +
+      '.vr-vision-empty-actions{display:flex;align-items:center;gap:8px;flex-wrap:wrap}' +
       '.vr-subheader{display:flex;align-items:center;justify-content:space-between;gap:8px;width:100%;padding:8px 0;border:none;background:none;cursor:pointer;font:inherit;color:var(--dsw-alias-label-primary);text-align:left}' +
       '.vr-group{content-visibility:auto;contain-intrinsic-size:auto 96px;border-top:1px solid var(--dsw-alias-border-l2);padding:10px 0 2px;display:flex;flex-direction:column;gap:8px}' +
       '.vr-group-title{font-size:12px;font-weight:600;color:var(--dsw-alias-label-tertiary);margin:0}' +
@@ -985,6 +1033,8 @@ window.__ModuleLoader__.load({
       const [visionCaps, setVisionCaps] = useState({ status: 'idle', capabilities: {}, builtinFallback: [], anonymousRpmPerModel: 2, error: undefined })
       const catalogReady = catalog.status === 'ready' && catalog.groups.length > 0
       const visionGroups = filterVisionBackendGroups(catalog.groups, visionCaps.capabilities)
+      const hiddenVisionBackends =
+        visionCaps.status === 'ready' ? collectFilteredVisionBackends(catalog.groups, visionCaps.capabilities) : []
       const visionModelsFor = (providerId) => {
         const group = visionGroups.find((entry) => entry.id === providerId)
         return group && Array.isArray(group.models) ? group.models : []
@@ -1013,8 +1063,8 @@ window.__ModuleLoader__.load({
         }, 220)
         return () => window.clearTimeout(timer)
       }, [guideActive, open, catalog.status, visionCaps.status])
-      const loadCatalog = () => {
-        if (catalog.status === 'loading' || catalog.status === 'ready') return
+      const loadCatalog = (force = false) => {
+        if (!force && (catalog.status === 'loading' || catalog.status === 'ready')) return
         setCatalog({ status: 'loading', groups: [], error: undefined })
         try {
           const connection = props.getConnection ? props.getConnection() : undefined
@@ -1061,8 +1111,8 @@ window.__ModuleLoader__.load({
           })
         }
       }
-      const loadVisionCapabilities = () => {
-        if (visionCaps.status === 'loading' || visionCaps.status === 'ready') return
+      const loadVisionCapabilities = (force = false) => {
+        if (!force && (visionCaps.status === 'loading' || visionCaps.status === 'ready')) return
         setVisionCaps({ status: 'loading', capabilities: {}, builtinFallback: [], anonymousRpmPerModel: 2, error: undefined })
         fetch('/_dsh/vision-router/model-capabilities')
           .then(async (response) => {
@@ -1091,6 +1141,12 @@ window.__ModuleLoader__.load({
               }),
           )
       }
+      const retryVisionModels = () => {
+        setCatalog({ status: 'idle', groups: [], error: undefined })
+        setVisionCaps({ status: 'idle', capabilities: {}, builtinFallback: [], anonymousRpmPerModel: 2, error: undefined })
+        loadCatalog(true)
+        loadVisionCapabilities(true)
+      }
       let snapshot
       let renderError
       try {
@@ -1531,6 +1587,37 @@ window.__ModuleLoader__.load({
           h('p', { className: 'vr-hint' }, t('chainHint')),
         )
       }
+      const emptyVisionModelsPanel = () => {
+        if (!(catalogReady && visionCaps.status === 'ready' && visionGroups.length === 0 && hiddenVisionBackends.length > 0)) {
+          return null
+        }
+        const preview = hiddenVisionBackends.slice(0, 8)
+        const remaining = hiddenVisionBackends.length - preview.length
+        const hasMissingDeclaration = hiddenVisionBackends.some((entry) => entry.missingImageDeclaration)
+        return h('div', { className: 'vr-vision-empty' },
+          h('p', { className: 'vr-vision-empty-title' }, t('visionCapsEmptyTitle')),
+          h('p', { className: 'vr-hint' }, t('visionCapsEmptyBody', { count: hiddenVisionBackends.length })),
+          h('p', { className: 'vr-hint' }, t('visionCapsHiddenPrefix')),
+          h('ul', { className: 'vr-vision-empty-list' },
+            preview.map((entry) =>
+              h('li', { key: entry.provider + '/' + entry.model },
+                entry.provider + '/' + entry.model + ' — ' +
+                  t(entry.missingImageDeclaration ? 'visionCapsReasonMissingImage' : 'visionCapsReasonUnverified')),
+            ),
+            remaining > 0 ? h('li', { key: 'more' }, t('visionCapsHiddenMore', { count: remaining })) : null,
+          ),
+          hasMissingDeclaration
+            ? h('p', { className: 'vr-hint vr-stealth-notice' }, t('visionCapsMissingImageHint'))
+            : null,
+          h('div', { className: 'vr-vision-empty-actions' },
+            h('button', {
+              type: 'button', className: 'vr-btn',
+              disabled: catalog.status === 'loading' || visionCaps.status === 'loading',
+              onClick: retryVisionModels,
+            }, t('visionCapsRetry')),
+          ),
+        )
+      }
       const builtinFallbackPanel = () => {
         const list = Array.isArray(visionCaps.builtinFallback) ? visionCaps.builtinFallback : []
         const enabled = format('freeFallback') !== false
@@ -1826,6 +1913,7 @@ window.__ModuleLoader__.load({
                   : visionCaps.status === 'ready'
                     ? h('p', { className: 'vr-hint' }, t('visionCapsFiltered'))
                     : null,
+              emptyVisionModelsPanel(),
               catalogReady
                 ? chainEditor()
                 : h('div', {
@@ -1899,6 +1987,28 @@ window.__ModuleLoader__.load({
                           ? `${t('testOk')}（${typeof testState.result.latencyMs === 'number' ? testState.result.latencyMs + 'ms' : 'ok'}）`
                           : `${t('testFailed')}：${testState.result && testState.result.error ? testState.result.error : 'unknown'}`)
                   : null,
+                h('button', {
+                  type: 'button', className: 'vr-btn',
+                  onClick: async () => {
+                    try {
+                      const response = await fetch('/_dsh/vision-router/logs', {
+                        method: 'POST',
+                        cache: 'no-store',
+                      })
+                      const result = await response.json().catch(() => undefined)
+                      if (!response.ok || !result || result.ok !== true) {
+                        throw new Error(result && result.error ? result.error : `HTTP ${response.status}`)
+                      }
+                    } catch (error) {
+                      if (typeof window.alert === 'function') {
+                        window.alert(
+                          t('openLogFolderFailed') + '：' +
+                            (error && error.message ? error.message : String(error)),
+                        )
+                      }
+                    }
+                  },
+                }, t('openLogFolder')),
                 h('button', {
                   type: 'button', className: 'vr-btn', disabled: testState.status === 'running',
                   onClick: runTestConnection,
@@ -2141,12 +2251,12 @@ window.__ModuleLoader__.load({
         () =>
           ctx.slots.inject('tool.call.toolview', function* () {
             yield ctx.slots.register(
-              { name: 'tool.call.toolview', key: 'vision_present', inject: () => ({}) },
+              { name: 'tool.call.toolview', key: 'vision_present', priority: -10, inject: () => ({}) },
               VisionPresentCard,
             )
             for (const key of ARTIFACT_TOOL_KEYS) {
               yield ctx.slots.register(
-                { name: 'tool.call.toolview', key, inject: () => ({}) },
+                { name: 'tool.call.toolview', key, priority: -10, inject: () => ({}) },
                 ArtifactCard,
               )
             }
@@ -2159,6 +2269,7 @@ window.__ModuleLoader__.load({
     exports.inject = ['settingsScope', 'slots', 'locale', 'sessions']
     exports.unwrapModelsResult = unwrapModelsResult
     exports.filterVisionBackendGroups = filterVisionBackendGroups
+    exports.collectFilteredVisionBackends = collectFilteredVisionBackends
     return module.exports
   },
 })

package/lib/file-logger.js

@@ -0,0 +1,273 @@
+import { appendFile, mkdir, rename, rm, stat } from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+import { execFile } from 'node:child_process'
+import { format as formatArgs, promisify } from 'node:util'
+import { createRequire } from 'node:module'
+import { resolveDshHome } from './doctor.js'
+
+export const LOG_FILE_NAME = 'vision-router.log'
+export const LOG_BACKUP_FILE_NAME = 'vision-router.1.log'
+export const DEFAULT_LOG_MAX_BYTES = 2 * 1024 * 1024
+
+const execFileAsync = promisify(execFile)
+const installs = new WeakMap()
+
+export function resolveVisionRouterLogPaths(dshHome = resolveDshHome()) {
+  const directory = path.join(dshHome, 'logs', 'vision-router')
+  return {
+    directory,
+    file: path.join(directory, LOG_FILE_NAME),
+    backup: path.join(directory, LOG_BACKUP_FILE_NAME),
+  }
+}
+
+/**
+ * Diagnostics are intended to be shareable in bug reports. Existing runtime
+ * messages should not contain secrets, but redact common credential shapes as
+ * defense in depth before anything reaches disk.
+ */
+export function sanitizeLogText(value) {
+  let text = String(value ?? '')
+  text = text.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, 'Bearer [REDACTED]')
+  text = text.replace(/\bsk-(?:proj-)?[A-Za-z0-9_-]{8,}\b/g, '[REDACTED_KEY]')
+  text = text.replace(
+    /([?&](?:api[_-]?key|access[_-]?token|token|key|auth)=)[^&\s]+/gi,
+    '$1[REDACTED]',
+  )
+  text = text.replace(
+    /\b(authorization|api[_-]?key|access[_-]?token)\s*[:=]\s*["']?[^\s"',}]+/gi,
+    '$1=[REDACTED]',
+  )
+  return text
+}
+
+export function createFileLogSink({
+  file,
+  backup,
+  maxBytes = DEFAULT_LOG_MAX_BYTES,
+  onError = () => {},
+} = {}) {
+  let queue = Promise.resolve()
+  let initialized = false
+  let size = 0
+  let disabled = false
+  let reportedError = false
+
+  const reportError = (error) => {
+    if (reportedError) return
+    reportedError = true
+    try {
+      onError(error)
+    } catch {
+      // A diagnostics failure must never affect the plugin runtime.
+    }
+  }
+
+  const prepare = async () => {
+    if (initialized || disabled) return
+    await mkdir(path.dirname(file), { recursive: true })
+    try {
+      size = (await stat(file)).size
+    } catch (error) {
+      if (error && error.code !== 'ENOENT') throw error
+      size = 0
+    }
+    initialized = true
+  }
+
+  const rotate = async () => {
+    try {
+      await rm(backup, { force: true })
+      await rename(file, backup)
+    } catch (error) {
+      if (error && error.code !== 'ENOENT') throw error
+    }
+    size = 0
+  }
+
+  const write = (level, args) => {
+    if (disabled) return queue
+    const rendered = sanitizeLogText(formatArgs(...args))
+    const line = `[${new Date().toISOString()}] [${String(level).toUpperCase()}] ${rendered}\n`
+    const bytes = Buffer.byteLength(line)
+    queue = queue.then(async () => {
+      try {
+        await prepare()
+        if (size > 0 && size + bytes > maxBytes) await rotate()
+        await appendFile(file, line, { encoding: 'utf8', mode: 0o600 })
+        size += bytes
+      } catch (error) {
+        disabled = true
+        reportError(error)
+      }
+    })
+    return queue
+  }
+
+  return {
+    write,
+    flush: () => queue,
+    get disabled() {
+      return disabled
+    },
+  }
+}
+
+function packageVersion() {
+  try {
+    const require = createRequire(import.meta.url)
+    const manifest = require('../package.json')
+    return typeof manifest?.version === 'string' ? manifest.version : 'unknown'
+  } catch {
+    return 'unknown'
+  }
+}
+
+function teeLogger(baseLogger, sink) {
+  const levels = new Set(['debug', 'info', 'warn', 'error'])
+  return new Proxy(baseLogger ?? {}, {
+    get(target, property) {
+      if (levels.has(property)) {
+        return (...args) => {
+          const method = target && typeof target[property] === 'function' ? target[property] : undefined
+          if (method) {
+            try {
+              method.apply(target, args)
+            } catch {
+              // Keep the file logger from changing host logger semantics.
+            }
+          }
+          void sink.write(property, args)
+        }
+      }
+      const value = Reflect.get(target, property, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+}
+
+function contextWithLogger(ctx, logger) {
+  return new Proxy(ctx, {
+    get(target, property) {
+      if (property === 'logger') return logger
+      const value = Reflect.get(target, property, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+}
+
+export async function openLogDirectory(directory, {
+  platform = process.platform,
+  exec = execFileAsync,
+} = {}) {
+  await mkdir(directory, { recursive: true })
+  if (platform === 'darwin') {
+    await exec('open', [directory], { timeout: 10_000, windowsHide: true })
+    return
+  }
+  if (platform === 'win32') {
+    await exec('explorer.exe', [directory], { timeout: 10_000, windowsHide: true })
+    return
+  }
+  await exec('xdg-open', [directory], { timeout: 10_000, windowsHide: true })
+}
+
+function sameOrigin(req) {
+  const origin = req?.headers?.origin
+  const host = req?.headers?.host
+  const fetchSite = req?.headers?.['sec-fetch-site']
+  if (fetchSite && fetchSite !== 'same-origin' && fetchSite !== 'none') return false
+  if (!origin) return true
+  if (!host) return false
+  try {
+    return new URL(origin).host === host
+  } catch {
+    return false
+  }
+}
+
+function sendJson(res, status, body) {
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  })
+  res.end(JSON.stringify(body))
+}
+
+function installLogRoute(ctx, paths) {
+  ctx.inject(['webServer'], (webCtx) => {
+    webCtx.effect(() => webCtx.webServer.register({
+      kind: 'exact',
+      path: '/_dsh/vision-router/logs',
+      handler: async (req, res) => {
+        if (req.method === 'GET') {
+          sendJson(res, 200, { ok: true, directory: paths.directory, file: paths.file })
+          return
+        }
+        if (req.method !== 'POST') {
+          res.setHeader('Allow', 'GET, POST')
+          sendJson(res, 405, { ok: false, error: 'method not allowed' })
+          return
+        }
+        if (!sameOrigin(req)) {
+          sendJson(res, 403, { ok: false, error: 'cross-origin request rejected' })
+          return
+        }
+        try {
+          await openLogDirectory(paths.directory)
+          sendJson(res, 200, { ok: true, directory: paths.directory, file: paths.file })
+        } catch (error) {
+          sendJson(res, 500, {
+            ok: false,
+            directory: paths.directory,
+            file: paths.file,
+            error: error && error.message ? error.message : String(error),
+          })
+        }
+      },
+    }), 'vision-router: diagnostics log route')
+  })
+}
+
+/**
+ * Return a Cordis context whose logger tees this plugin's existing diagnostics
+ * to a small rotating file while preserving the host logger. The original
+ * context is otherwise untouched.
+ */
+export function installVisionRouterFileLogging(ctx, options = {}) {
+  if (ctx && typeof ctx === 'object' && installs.has(ctx)) return installs.get(ctx)
+
+  const paths = resolveVisionRouterLogPaths(options.dshHome)
+  const baseLogger = ctx?.logger
+  const sink = createFileLogSink({
+    file: paths.file,
+    backup: paths.backup,
+    maxBytes: options.maxBytes ?? DEFAULT_LOG_MAX_BYTES,
+    onError: (error) => {
+      try {
+        baseLogger?.warn?.(
+          'vision-router: diagnostics file logging disabled: %s',
+          error && error.message ? error.message : String(error),
+        )
+      } catch {
+        // Logging failure remains non-fatal.
+      }
+    },
+  })
+  const logger = teeLogger(baseLogger, sink)
+  const wrappedCtx = contextWithLogger(ctx, logger)
+  const installed = { ctx: wrappedCtx, logger, sink, ...paths }
+  if (ctx && typeof ctx === 'object') installs.set(ctx, installed)
+
+  installLogRoute(ctx, paths)
+  logger.info(
+    'vision-router: diagnostics log enabled at %s (plugin=%s node=%s platform=%s/%s)',
+    paths.file,
+    packageVersion(),
+    process.version,
+    process.platform,
+    process.arch,
+  )
+  return installed
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vision-router",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "Eyes for text-only DeepSeek Harness agents: built-in free vision chain (no key) + pixel-level vision tools (Q&A, grounding, crop, pixel diff, colors, OCR, SVG trace, cutout, screenshots). One-command install, no Python, image turns work like ordinary tool-calling turns.",
   "license": "MIT",
   "repository": {
@@ -9,12 +9,12 @@
   },
   "homepage": "https://github.com/ysr666/dsh-vision-router",
   "type": "module",
-  "main": "index.js",
+  "main": "entry.js",
   "bin": {
     "dsh-vision-router": "./lib/doctor-cli.js"
   },
   "exports": {
-    ".": "./index.js",
+    ".": "./entry.js",
     "./client": "./lib/client.js",
     "./package.json": "./package.json",
     "./cordis.patch.yml": "./cordis.patch.yml"
@@ -26,6 +26,7 @@
     "assets",
     "cordis.patch.yml",
     "docs",
+    "entry.js",
     "index.js",
     "lib",
     "presets"
@@ -50,18 +51,20 @@
     "@deepseek-ai/schemastery": ">=3.18.0",
     "potrace": "^2.1.8",
     "puppeteer-core": "^25.6.0",
-    "undici": ">=6.15.0",
-    "@deepseek-ai/dsh-llm-deepseek": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-anonymous-user-id": "^0.1.0-rc.6"
+    "undici": ">=6.15.0"
   },
   "peerDependencies": {
+    "@deepseek-ai/dsh-anonymous-user-id": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm-deepseek": "^0.1.0-rc.6",
     "sharp": ">=0.35.3 <1"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-anonymous-user-id": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm-deepseek": "^0.1.0-rc.6",
     "sharp": "^0.35.3"
   },
   "scripts": {
-    "test": "node --test tests/core.test.js tests/client.test.js tests/http-compat.test.js tests/update-check.test.js tests/self-update.test.js tests/doctor.test.js"
+    "test": "node --test tests/core.test.js tests/client.test.js tests/http-compat.test.js tests/update-check.test.js tests/self-update.test.js tests/doctor.test.js tests/bundle-defaults.test.js tests/file-logger.test.js tests/logging-ui.test.js tests/manifest-dependencies.test.js"
   },
   "pnpm": {
     "onlyBuiltDependencies": [

package/presets/README.md

@@ -4,6 +4,9 @@
 把它合并进你自己的 `settings.yaml`（或复制整个段），填一个 `apiKeyEnv` 对应的 Key 即可。
 **仓库绝不内置任何第三方 Key**。
 
+> [!IMPORTANT]
+> DSH 当前的 Web「设置 → 模型 → 添加自定义提供方」表单不会写入图片输入能力元数据。即使端点实际是智谱 GLM-4.6V、Qwen-VL 等视觉模型，如果模型没有显式的 `input: [text, image]`（或提供方没有 `defaultInput: [text, image]`），DSH 仍会把它报告为纯文本模型，Vision Router 会为安全起见从视觉后端下拉中隐藏它。下面这些 preset 已经带好 `input` 声明；如果你是通过 Web 手动添加的自定义视觉提供方，请在 `$DSH_HOME/settings.yaml` 补上该字段。
+
 - `dashscope.yaml` —— 阿里云百炼，大陆直连，新用户每系列 100 万 token/90 天（推荐首选）
 - `zhipu.yaml` —— 智谱 bigmodel.cn，`glm-4.6v-flash` 永久免费（provider key 用 `zhipu`，避免与 pi-ai 内置目录里的 `zai` 编码端点冲突）
 - `siliconflow.yaml` —— 硅基流动，¥14 赠金覆盖 Qwen2.5-VL