dsh-vision-router 1.5.0 → 1.5.2

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center"><strong>Paste an image and it just works — eyes for text-only agents on DeepSeek Harness. Free out of the box, no key, no Python, one command.</strong></p>
 
-<p align="center">DeepSeek keeps thinking; the built-in free vision chain and thirteen deep tools do the seeing. Image turns behave like ordinary tool-calling turns — grounded, measurable, repeatable.</p>
+<p align="center">DeepSeek keeps thinking; the built-in free vision chain and fourteen deep tools do the seeing. Image turns behave like ordinary tool-calling turns — grounded, measurable, repeatable.</p>
 
 <p align="center">
   <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="awesome · DSH plugin" /></a>
@@ -15,8 +15,8 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.5.0"><img src="https://img.shields.io/badge/release-v1.5.0-5B4CF0?style=flat-square" alt="Release v1.5.0" /></a>
-  <a href="tests"><img src="https://img.shields.io/badge/verified-348%20tests-2EA44F?style=flat-square" alt="Verified: 348 tests" /></a>
+  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.5.2"><img src="https://img.shields.io/badge/release-v1.5.2-5B4CF0?style=flat-square" alt="Release v1.5.2" /></a>
+  <a href="tests"><img src="https://img.shields.io/badge/verified-355%20tests-2EA44F?style=flat-square" alt="Verified: 355 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>
   <img src="https://img.shields.io/badge/runtime-no%20Python-8A2BE2?style=flat-square" alt="No Python" />
@@ -28,9 +28,9 @@
 <p align="center">💬 <strong>QQ community group: 1105463028</strong></p>
 
 > [!WARNING]
-> 📌 **Announcement (v1.5.0)**
+> 📌 **Announcement (v1.5.2)**
 >
-> **v1.5.0:** Adds local Ollama / LM Studio vision and desktop screenshots, with stronger Settings and lifecycle reliability.
+> **v1.5.2:** Fixes DSH Settings keyed-slot loading.
 
 <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" />
@@ -190,7 +190,7 @@ Any of these channels can join the vision chain as an `httpProviders` entry (key
 - **Automatic failover with classified errors.** Region blocks, ToS filtering, 402 quota, 429 rate limits, context overflow, network failures — the chain walks providers one by one and only reports after all of them failed, with actionable advice. A 429 immediately advances to the next backend and opens a Retry-After-aware cooldown instead of sleeping inside the request.
 - **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.
-- **Stable tool schema.** All thirteen 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).
+- **Stable tool schema.** All fourteen 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
@@ -211,18 +211,19 @@ The vision model is **only the eyes**; DeepSeek is **always the brain**. An imag
 
 ## Tools
 
-Default `progressiveTools: false`: all thirteen 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:
+Default `progressiveTools: false`: all fourteen 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 image-processing tools available in DSH Vision Router." />
 </p>
 
-The diagram covers the eleven image-processing tools. `vision_present` (durable image delivery) and `vision_bootstrap` (the optional 1+x structured first pass) bring the default deep-tool set to thirteen. Enabling the privacy-gated `vision_screenshot` at boot adds an optional fourteenth tool.
+The diagram covers the eleven image-processing tools. `vision_present` (durable image delivery) and `vision_bootstrap` (the optional 1+x structured first pass) bring the default deep-tool set to fourteen. Enabling the privacy-gated `vision_screenshot` at boot adds an optional fifteenth tool.
 
 | Tool | What it does | Artifact |
 |---|---|---|
 | `vision_bootstrap` | Optional 1+x structured first visual pass; establishes task-independent evidence before at least one follow-up vision call | — |
 | `vision_describe` | Image Q&A / multi-image compare / structured-evidence JSON mode (summary + layout regions + entity inventory + verbatim transcription) | — |
+| `vision_materialize` | Copy an authorized attachment into the session workspace and return a filesystem path for local OCR/parser fallbacks; no vision/network call | image copy |
 | `vision_ground` | Locate a target → **original-pixel box x1/y1/x2/y2** | annotated PNG (optional) |
 | `vision_detect` | Numbered inventory of every element of a kind (buttons/inputs/links…) with original-pixel boxes | annotated PNG with numbered boxes |
 | `vision_crop` | Crop and zoom into a pixel box | PNG |

package/README.zh.md

@@ -6,7 +6,7 @@
 
 <p align="center"><strong>图片粘贴即用：给 DeepSeek Harness 的纯文本 Agent 装上“眼睛”——开箱免费、免 Key、无 Python、一条命令安装。</strong></p>
 
-<p align="center">DeepSeek 只负责思考，内置免费视觉链 + 13 个深看工具负责“看”；图片轮次就像普通工具调用一样自然、可定位、可验证。</p>
+<p align="center">DeepSeek 只负责思考，内置免费视觉链 + 14 个深看工具负责“看”；图片轮次就像普通工具调用一样自然、可定位、可验证。</p>
 
 <p align="center">
   <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="awesome · DSH plugin" /></a>
@@ -15,8 +15,8 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.5.0"><img src="https://img.shields.io/badge/release-v1.5.0-5B4CF0?style=flat-square" alt="Release v1.5.0" /></a>
-  <a href="tests"><img src="https://img.shields.io/badge/verified-348%20tests-2EA44F?style=flat-square" alt="Verified: 348 tests" /></a>
+  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.5.2"><img src="https://img.shields.io/badge/release-v1.5.2-5B4CF0?style=flat-square" alt="Release v1.5.2" /></a>
+  <a href="tests"><img src="https://img.shields.io/badge/verified-355%20tests-2EA44F?style=flat-square" alt="Verified: 355 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>
   <img src="https://img.shields.io/badge/runtime-no%20Python-8A2BE2?style=flat-square" alt="No Python" />
@@ -28,9 +28,9 @@
 <p align="center">💬 <strong>QQ 用户交流群：1105463028</strong></p>
 
 > [!WARNING]
-> 📌 **公告（v1.5.0）**
+> 📌 **公告（v1.5.2）**
 >
-> **v1.5.0：新增 Ollama / LM Studio 本地视觉与桌面截图，强化设置和生命周期稳定性。**
+> **v1.5.2：修复 DSH 设置页 keyed-slot 加载失败。**
 
 <p align="center">
   <img src="assets/vision-demo.gif" width="640" alt="演示：粘贴图片，Agent 用 vision_ground / vision_crop / vision_pixel_diff 定位发送按钮并给出坐标" />
@@ -189,7 +189,7 @@ opencode-go + 自动识图       ← 发图片时选这个
 - **自动降级 + 分类报错。** 地区限制、ToS 风控、402 额度、429 限流、上下文超长、网络故障——链路逐供应商尝试，全部失败才报错并给出可操作的建议。遇到 429 会立即尝试下一后端，并按 Retry-After 开启冷却，不会在单次请求内睡眠等待。
 - **图片记忆。** 视觉答案按附件内容哈希缓存；后续文字轮用记录的描述替换历史图片（标注为不可信证据），DeepSeek 真正“记得”之前发过的图，且不重复消耗视觉调用。
 - **可验证的像素闭环。** 参照图 → `vision_html_screenshot` → `vision_pixel_diff`（差异率 + 红色热力图 + 最差区域排行）→ 修复 → 再对比，直到差异收敛。UI 还原从“目测”变成“实测”。
-- **稳定工具 schema。** 默认从会话开始就注册完整 13 个深看工具，避免图片轮中途扩展工具列表导致长上下文的 KV / prefix cache 失效。仍保留 `progressiveTools: true` 作为高级启动期 opt-in；开启后才使用 `vision_activate` 按需挂载。详见 [`docs/progressive-tools-cache.md`](docs/progressive-tools-cache.md)。
+- **稳定工具 schema。** 默认从会话开始就注册完整 14 个深看工具，避免图片轮中途扩展工具列表导致长上下文的 KV / prefix cache 失效。仍保留 `progressiveTools: true` 作为高级启动期 opt-in；开启后才使用 `vision_activate` 按需挂载。详见 [`docs/progressive-tools-cache.md`](docs/progressive-tools-cache.md)。
 - **选择性代理。** 只有配置的视觉供应商域名走本地代理；DeepSeek 保持直连。
 
 ### 像素闭环实测
@@ -210,7 +210,7 @@ Agent 仅根据参考图复刻 UI，再用 `vision_pixel_diff` 验证最终结
 
 ## 工具
 
-默认 `progressiveTools: false`：13 个深看工具从插件启动时就保持常驻，文本轮和图片轮都可直接调用。若你在 profile / composition 的 `cordis.patch.yml` 中显式开启 `progressiveTools: true`，才会恢复渐进模式：初始只暴露 `vision_activate`，首次需要时再挂载完整工具，并注册 `vision-tools` 技能。该开关是启动期配置，修改后需重启 DSH。全部工具基于 sharp / potrace / tesseract / 系统 Chrome——无 Python：
+默认 `progressiveTools: false`：14 个深看工具从插件启动时就保持常驻，文本轮和图片轮都可直接调用。若你在 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 个图像处理工具。" />
@@ -222,6 +222,7 @@ Agent 仅根据参考图复刻 UI，再用 `vision_pixel_diff` 验证最终结
 |---|---|---|
 | `vision_bootstrap` | 可选 1+x 结构化首遍视觉识别；先建立任务无关证据底图，再至少进行 1 次后续视觉调用 | — |
 | `vision_describe` | 看图问答 / 多图对比 / 结构化证据 JSON 模式（摘要 + 布局区域 + 实体清单 + 原文转写） | — |
+| `vision_materialize` | 把已授权附件复制到会话工作区并返回真实文件路径，供本地 OCR/解析器降级使用；不调用视觉模型或网络 | image copy |
 | `vision_ground` | 定位目标 → **原图像素框 x1/y1/x2/y2** | 标注 PNG（可选） |
 | `vision_detect` | 盘点某类元素（按钮/输入框/链接…）→ 编号清单 + 原图像素框 | 编号标注 PNG |
 | `vision_crop` | 按像素框裁剪放大 | PNG |

package/index.js

@@ -4947,7 +4947,8 @@ export function apply(ctx, config = {}) {
         'question — rephrasing cannot fix an auth, rate-limit or outage problem. Answer from the information ' +
         'you already have and continue the text task, telling the user vision is temporarily unavailable. ' +
         'Only content-level uncertainty in a SUCCESSFUL answer justifies a second look (vision_crop, ' +
-        'vision_ground or another vision_describe).',
+        'vision_ground or another vision_describe). If infrastructure failure leaves a file_path-only OCR/parser as the fallback, ' +
+        'use vision_materialize on the uploaded attachment id; never guess a same-named local file or private attachment-store path.',
       parameters: {
         type: 'object',
         properties: {
@@ -4997,6 +4998,12 @@ export function apply(ctx, config = {}) {
         if (paths.length + attachmentIds.length === 0 || paths.length + attachmentIds.length > 4) {
           throw new Error('vision_describe: provide 1-4 images via paths and/or attachmentIds')
         }
+        // Preserve only durable upload ids for a deterministic offline fallback.
+        // Never expose or guess the attachment store's private filesystem path.
+        const materializableAttachmentIds = [...new Set([
+          ...attachmentIds.map((id) => String(id)).filter((id) => isAttachmentIdInput(id)),
+          ...paths.map((item) => String(item)).filter((item) => isAttachmentIdInput(item)),
+        ])]
 
         for (const path of paths) {
           let bytes
@@ -5363,11 +5370,18 @@ export function apply(ctx, config = {}) {
           attempted.length > 0 ? attempted : errors.map((text) => ({ backend: 'configured', kind: 'NO_ADAPTER', error: text })),
           reason,
         )
-        return JSON.stringify(
-          attempted.length > 0
-            ? failure
-            : { ...failure, code: VISION_RESULT_CODES.UNSUPPORTED_BACKEND },
-        )
+        const baseFailure = attempted.length > 0
+          ? failure
+          : { ...failure, code: VISION_RESULT_CODES.UNSUPPORTED_BACKEND }
+        if (materializableAttachmentIds.length > 0) {
+          baseFailure.degradedAccess = {
+            tool: 'vision_materialize',
+            attachmentIds: materializableAttachmentIds,
+            advice:
+              'If another local/OCR tool requires a filesystem path, call vision_materialize for the uploaded attachment id. Do not guess a filename or the attachment store path.',
+          }
+        }
+        return JSON.stringify(baseFailure)
       },
     }
     deepToolDefs.push(visionDescribeTool)
@@ -5539,6 +5553,44 @@ export function apply(ctx, config = {}) {
       render: (_args, value) => [{ type: 'text', text: value }],
     }
 
+    // issue #153: materialize an authorized attachment into the workspace for
+    // file_path-only local parsers without coupling them to DSH storage internals.
+    deepToolDefs.push({
+      name: 'vision_materialize',
+      description:
+        'Copy an uploaded image attachment (sha256:...) or readable local image into the session workspace and return a real filesystem path. ' +
+        'This tool performs NO vision model/network call. Use it after vision_describe/vision_bootstrap returns ok:false when a local OCR/parser accepts only file_path. ' +
+        'Never guess the attachment store path or search for a same-named file.',
+      parameters: {
+        type: 'object',
+        properties: {
+          image: { type: 'string', description: 'Uploaded image attachment id (recommended, e.g. sha256:...) or a readable local image path' },
+        },
+        required: ['image'],
+        additionalProperties: false,
+      },
+      output: stringOutput,
+      async execute(args, exec) {
+        const source = String(args.image ?? '')
+        const { bytes, mediaType } = await readImageBytes(exec, source)
+        const extension = mediaType === 'image/jpeg'
+          ? 'jpg'
+          : mediaType === 'image/webp'
+            ? 'webp'
+            : mediaType === 'image/gif'
+              ? 'gif'
+              : 'png'
+        const target = await saveArtifact(exec, `${artifactStem(source, 'materialized')}.${extension}`, bytes)
+        return JSON.stringify({
+          path: target,
+          mediaType,
+          bytes: bytes.length,
+          ...(isAttachmentIdInput(source) ? { source } : {}),
+          safeWorkspaceCopy: true,
+        })
+      },
+    })
+
     const visionPresentOutput = {
       schema: {
         type: 'object',
@@ -6763,7 +6815,7 @@ export function apply(ctx, config = {}) {
       }
       return (
         '视觉深看工具已挂载：vision_bootstrap（结构化预识别）、vision_describe（看图问答）、vision_ground（像素定位）、vision_detect（元素清单）、' +
-        'vision_crop（裁剪放大）、vision_pixel_diff（像素对比验证）、vision_colors（取色）、' +
+        'vision_materialize（附件落盘）、vision_crop（裁剪放大）、vision_pixel_diff（像素对比验证）、vision_colors（取色）、' +
         'vision_ocr（文字识别）、vision_trace（SVG 矢量化）、vision_extract_foreground（抠图）、' +
         'vision_html_screenshot（页面截图）。现在可以直接调用已启用的工具。' +
         '注意：vision_ocr 只用于读取图片文字；视觉工具返回 ok:false 后端不可用结果时，不要改问法重复调用，继续文本任务。'
@@ -6773,7 +6825,7 @@ export function apply(ctx, config = {}) {
       ctx.tools.register({
         name: 'vision_activate',
         description:
-          'Mount the deep vision tools (vision_bootstrap / vision_describe / vision_ground / vision_detect / vision_crop / ' +
+          'Mount the deep vision tools (vision_bootstrap / vision_describe / vision_ground / vision_detect / vision_materialize / vision_crop / ' +
           'vision_pixel_diff / vision_colors / vision_ocr / vision_trace / ' +
           'vision_extract_foreground / vision_present / vision_html_screenshot) for this session. Desktop screenshot remains disabled until the user explicitly opts in through Vision Router settings. They mount ' +
           'automatically on image turns; call this only when you need them on a text-only turn.',

package/lib/client.js

@@ -163,6 +163,8 @@ window.__ModuleLoader__.load({
       updateCurrent: '已是最新版本 v{current}',
       updateAhead: '当前 v{current} 高于 registry 最新 v{latest}；可能是源码或预发布构建，不会建议降级。',
       updateFailed: '更新检查失败：{error}',
+      updateNoDiagnostic: '更新检查接口未返回可诊断的错误详情',
+      updateInvalidResponse: '更新检查接口返回了无效响应',
       updateInstallHint: '已安全识别当前 DSH CLI，可直接用这套 DSH 更新插件；完成后需要重启 DSH 才会加载新版本。',
       updateAutoUnavailable: '当前 DSH CLI 无法被安全识别，因此不执行自动更新。请沿用你原来安装 DSH / 插件的方式手动更新。',
       updateNow: '一键更新到 v{latest}',
@@ -173,10 +175,12 @@ window.__ModuleLoader__.load({
       updateActionFailed: '一键更新失败：{error}',
       updateReleaseNotes: '查看更新说明',
       updateRegistryFallback: '当前配置的 registry 不可用，已自动改用 npm 官方源完成检查。',
+      updateReleaseFallback: 'npm registry 检查失败，已通过 GitHub Releases 获取最新版本号；安装仍需 npm registry 可访问。',
+      updateManualUnknownTarget: '无法确认最新版本，因此不会生成 @latest 或普通 update 命令。请先打开 Releases 确认最新版本号，再把下方 <version> 替换为该版本。',
       updateManualTitle: '手动更新',
       updateManualSource: '源码仓库 / pnpm DSH：',
       updateManualNpx: '普通 npm / npx DSH：',
-      updateManualAgeHint: '若执行后版本仍未变化：pnpm 11 默认在新版本发布 24 小时内静默拦截更新（minimumReleaseAge 策略，但命令仍显示成功）。请使用上方带版本号的安装命令，或运行 npx dsh-vision-router repair 清理过期的版本钉住豁免后重试。',
+      updateManualAgeHint: '上方只会使用已确认的具体版本号；若无法确认版本，则只提供 <version> 模板。pnpm 11 默认会在新版本发布 24 小时内静默拦截 @latest / 普通 update（minimumReleaseAge 策略，但命令仍可能显示成功），所以这里不再推荐这两种模糊更新方式。',
       updateProject: '项目主页',
       updateReleases: 'Releases',
       save: '保存',
@@ -398,6 +402,8 @@ window.__ModuleLoader__.load({
       updateCurrent: 'Up to date: v{current}',
       updateAhead: 'Current v{current} is ahead of registry v{latest}; this may be a source or prerelease build, so no downgrade is suggested.',
       updateFailed: 'Update check failed: {error}',
+      updateNoDiagnostic: 'The update-check endpoint returned no diagnostic error details',
+      updateInvalidResponse: 'The update-check endpoint returned an invalid response',
       updateInstallHint: 'The current DSH CLI was verified, so Vision Router can update through this same DSH installation. Restart DSH after the update to load the new plugin bundle.',
       updateAutoUnavailable: 'The current DSH CLI could not be verified safely, so automatic update is disabled. Update through the same DSH/plugin installation path you originally used.',
       updateNow: 'Update to v{latest}',
@@ -408,10 +414,12 @@ window.__ModuleLoader__.load({
       updateActionFailed: 'One-click update failed: {error}',
       updateReleaseNotes: 'View release notes',
       updateRegistryFallback: 'The configured registry failed; the check succeeded through the official npm registry.',
+      updateReleaseFallback: 'npm registry checks failed, so the latest version was resolved from GitHub Releases; installation still requires an accessible npm registry.',
+      updateManualUnknownTarget: 'The latest version could not be confirmed, so no @latest or plain update command is generated. Open Releases first, confirm the newest version, then replace <version> in the template below.',
       updateManualTitle: 'Manual update',
       updateManualSource: 'DSH source checkout / pnpm:',
       updateManualNpx: 'Normal npm / npx DSH:',
-      updateManualAgeHint: 'If the version still has not changed after running this: pnpm 11 silently withholds releases younger than 24h (minimumReleaseAge policy, default 1440 minutes) while the command still reports success. Use the versioned install command above, or run npx dsh-vision-router repair to clean up a stale version-pinned exemption, then retry.',
+      updateManualAgeHint: 'The command above only uses a confirmed exact version; if no version can be confirmed, the UI shows a <version> template instead. pnpm 11 can silently withhold @latest / plain update for releases younger than 24h (minimumReleaseAge) even while reporting success, so those ambiguous update forms are no longer recommended here.',
       updateProject: 'Project',
       updateReleases: 'Releases',
       save: 'Save',
@@ -1026,6 +1034,12 @@ window.__ModuleLoader__.load({
     let settingsPersistence
     function installSettingsPersistence(scope) {
       const pending = new Map()
+      // Browser-side hidden settings (onboardingSeen / visionGuideStep) are
+      // best-effort durability hints, not a retry queue. Remember the last
+      // mutation issued for each field for this page lifetime so a rejected
+      // Host write or a stale/oscillating snapshot can never create an
+      // endless /api/settings.mutate loop (issue #155).
+      const issued = new Map()
       let flushing = false
       const readSnapshot = () => {
         try {
@@ -1038,14 +1052,32 @@ window.__ModuleLoader__.load({
         const snapshot = readSnapshot()
         return snapshot && snapshot.value ? snapshot.value : undefined
       }
+      const sameMutation = (left, operation, value) =>
+        !!left && left.operation === operation &&
+        (operation === 'unset' || jsonValueEqual(left.value, value))
+      const alreadyStored = (field, operation, value) => {
+        const snapshot = readSnapshot()
+        const user = snapshot && snapshot.user
+        const stored = !!user && typeof user === 'object' && Object.prototype.hasOwnProperty.call(user, field)
+        return operation === 'unset'
+          ? !stored
+          : stored && jsonValueEqual(user[field], value)
+      }
       const queue = (field, operation, value) => {
-        const previous = pending.get(field)
-        if (
-          previous && previous.operation === operation &&
-          (operation === 'unset' || jsonValueEqual(previous.value, value))
-        ) {
+        // No network mutation when the raw user layer already has the exact
+        // requested state. This also makes repeated finish/dismiss handlers
+        // idempotent after a successful write.
+        if (alreadyStored(field, operation, value)) {
+          pending.delete(field)
+          issued.set(field, { operation, value })
           return
         }
+        const previous = pending.get(field)
+        if (sameMutation(previous, operation, value)) return
+        // Once an identical hidden-state mutation was attempted in this page,
+        // never auto-retry it merely because subscribe/readback fired again.
+        // A genuinely different value/operation is still allowed through.
+        if (sameMutation(issued.get(field), operation, value)) return
         pending.set(field, { operation, value, attempted: false })
         void flush()
       }
@@ -1068,6 +1100,7 @@ window.__ModuleLoader__.load({
           for (const [field, entry] of work) {
             if (pending.get(field) !== entry) continue
             entry.attempted = true
+            issued.set(field, { operation: entry.operation, value: entry.value })
             try {
               if (entry.operation === 'unset') {
                 if (typeof scope.unset !== 'function') continue
@@ -1083,6 +1116,10 @@ window.__ModuleLoader__.load({
           }
         } finally {
           flushing = false
+          // A different value may have been queued while the previous write
+          // was in flight. Drain it once; identical mutations were filtered by
+          // `issued`, so this cannot become a subscribe-driven busy loop.
+          if ([...pending.values()].some((entry) => !entry.attempted)) void flush()
         }
       }
       settingsPersistence = {
@@ -1109,6 +1146,7 @@ window.__ModuleLoader__.load({
         },
       }
       void flush()
+      return settingsPersistence
     }
 
     function readOnboardingSeen() {
@@ -2344,6 +2382,14 @@ window.__ModuleLoader__.load({
         }).catch(() => {})
       }
 
+      const diagnosticError = (value, fallback) => {
+        if (typeof value === 'string' && value.trim() !== '') return value.trim()
+        if (value && typeof value.message === 'string' && value.message.trim() !== '') {
+          return value.message.trim()
+        }
+        return fallback
+      }
+
       const runUpdateCheck = async (force = false) => {
         if (updateState.status === 'running') return
         setUpdateState({ status: 'running', result: updateState.result })
@@ -2354,7 +2400,10 @@ window.__ModuleLoader__.load({
           )
           const result = await response.json().catch(() => undefined)
           if (!response.ok) {
-            throw new Error(result && result.error ? result.error : `HTTP ${response.status}`)
+            throw new Error(diagnosticError(result && result.error, `HTTP ${response.status}`))
+          }
+          if (!result || typeof result !== 'object' || typeof result.ok !== 'boolean') {
+            throw new Error(t('updateInvalidResponse'))
           }
           setUpdateState({ status: 'done', result })
         } catch (error) {
@@ -2383,7 +2432,10 @@ window.__ModuleLoader__.load({
           })
           const result = await response.json().catch(() => undefined)
           if (!response.ok) {
-            throw new Error(result && result.error ? result.error : `HTTP ${response.status}`)
+            throw new Error(diagnosticError(result && result.error, `HTTP ${response.status}`))
+          }
+          if (!result || typeof result !== 'object' || typeof result.ok !== 'boolean') {
+            throw new Error(t('updateInvalidResponse'))
           }
           setSelfUpdateState({ status: 'done', result })
         } catch (error) {
@@ -2955,13 +3007,18 @@ window.__ModuleLoader__.load({
           result && typeof result.releasesUrl === 'string' && result.releasesUrl
             ? result.releasesUrl
             : projectUrl + '/releases/latest'
-        // When a newer version is known, the manual commands install it
-        // explicitly: plain `update` can be silently withheld by pnpm 11's
-        // minimumReleaseAge policy while still reporting success.
-        const manualAction =
-          result && typeof result.latestVersion === 'string' && result.latestVersion
-            ? 'add dsh-vision-router@' + result.latestVersion
-            : 'update dsh-vision-router'
+        // Manual recovery is executable only when an exact target was
+        // confirmed by npm metadata or GitHub Releases. If every version source
+        // is unavailable, show a non-executable <version> template instead of
+        // falling back to @latest / plain update, both of which pnpm 11 may
+        // silently withhold while still reporting success.
+        const manualVersion =
+          result && typeof result.latestVersion === 'string' && result.latestVersion.trim()
+            ? result.latestVersion.trim()
+            : ''
+        const manualTargetKnown = manualVersion !== ''
+        const manualPackageSpec = 'dsh-vision-router@' + (manualTargetKnown ? manualVersion : '<version>')
+        const manualAction = 'add ' + manualPackageSpec
         const pnpmCommand = 'pnpm dsh plugin --profile ' + profile + ' ' + manualAction
         const npxCommand = 'npx @deepseek-ai/dsh plugin --profile ' + profile + ' ' + manualAction
         let status
@@ -2978,7 +3035,7 @@ window.__ModuleLoader__.load({
           }
         } else if (updateState.status === 'done') {
           failedUpdate = true
-          status = t('updateFailed', { error: result && result.error ? result.error : 'unknown' })
+          status = t('updateFailed', { error: diagnosticError(result && result.error, t('updateNoDiagnostic')) })
         }
         let selfUpdateStatus
         let selfUpdateFailed = false
@@ -2998,7 +3055,7 @@ window.__ModuleLoader__.load({
         } else if (selfUpdateState.status === 'error') {
           selfUpdateFailed = true
           selfUpdateStatus = t('updateActionFailed', {
-            error: selfUpdateState.result && selfUpdateState.result.error ? selfUpdateState.result.error : 'unknown',
+            error: diagnosticError(selfUpdateState.result && selfUpdateState.result.error, t('updateNoDiagnostic')),
           })
         }
         const showManualHelp =
@@ -3013,6 +3070,9 @@ window.__ModuleLoader__.load({
         const manualHelp = showManualHelp
           ? h('div', { className: 'vr-update-manual' },
               h('div', { className: 'vr-update-manual-title' }, t('updateManualTitle')),
+              !manualTargetKnown
+                ? h('p', { className: 'vr-update-note' }, t('updateManualUnknownTarget'))
+                : null,
               auto && auto.reason === 'source-cli-needs-loader'
                 ? commandBlock(t('updateManualSource'), pnpmCommand)
                 : null,
@@ -3043,6 +3103,9 @@ window.__ModuleLoader__.load({
           result && result.ok === true && result.registryFallbackFrom
             ? h('p', { className: 'vr-hint' }, t('updateRegistryFallback'))
             : null,
+          result && result.ok === true && result.releaseFallback === true
+            ? h('p', { className: 'vr-hint' }, t('updateReleaseFallback'))
+            : null,
           result && result.ok === true && result.updateAvailable === true
             ? h('div', { className: 'vr-catalog-error' },
                 h('p', { className: 'vr-hint' }, auto && auto.supported === true ? t('updateInstallHint') : t('updateAutoUnavailable')),
@@ -3305,6 +3368,7 @@ window.__ModuleLoader__.load({
       typeof React.memo === 'function' ? React.memo(VisionRouterCard) : VisionRouterCard
 
     const ARTIFACT_TOOL_KEYS = [
+      'vision_materialize',
       'vision_crop',
       'vision_pixel_diff',
       'vision_trace',
@@ -3507,6 +3571,7 @@ window.__ModuleLoader__.load({
             yield ctx.slots.register(
               {
                 name: 'settings.plugin.item',
+                key: 'vision-router',
                 id: 'vision-router',
                 order: 30,
                 label: () => t('nav'),
@@ -3546,6 +3611,7 @@ window.__ModuleLoader__.load({
     exports.parseLocalProviderDraft = parseLocalProviderDraft
     exports.jsonValueEqual = jsonValueEqual
     exports.commitSettingsPlan = commitSettingsPlan
+    exports.installSettingsPersistence = installSettingsPersistence
     return module.exports
   },
 })

package/lib/update-check.js

@@ -7,6 +7,7 @@ export const PACKAGE_NAME = 'dsh-vision-router'
 export const CURRENT_VERSION = String(packageJson.version ?? '')
 export const DEFAULT_NPM_REGISTRY = 'https://registry.npmjs.org'
 export const RELEASES_URL = 'https://github.com/ysr666/dsh-vision-router/releases/latest'
+export const GITHUB_LATEST_RELEASE_API = 'https://api.github.com/repos/ysr666/dsh-vision-router/releases/latest'
 
 function parseIdentifier(value) {
   return /^\d+$/.test(value) ? { numeric: true, value: Number(value) } : { numeric: false, value }
@@ -96,6 +97,25 @@ async function fetchLatestVersion({ fetchImpl, registryBase, signal, timeoutMs }
   return latestVersion
 }
 
+
+async function fetchLatestReleaseVersion({ fetchImpl, releaseApi, signal, timeoutMs }) {
+  const requestSignal = signal ?? AbortSignal.timeout(timeoutMs)
+  const response = await fetchImpl(releaseApi, {
+    method: 'GET',
+    headers: {
+      accept: 'application/vnd.github+json',
+      'user-agent': 'dsh-vision-router-update-check',
+    },
+    signal: requestSignal,
+  })
+  if (!response.ok) throw new Error(`GitHub releases API returned HTTP ${response.status}`)
+  const body = await response.json().catch(() => undefined)
+  const tag = body && typeof body.tag_name === 'string' ? body.tag_name.trim() : ''
+  const latestVersion = tag.replace(/^v/i, '')
+  if (!parseSemver(latestVersion)) throw new Error('GitHub latest release returned an invalid tag')
+  return latestVersion
+}
+
 /**
  * Check only; never installs or mutates anything. This deliberately stays
  * independent of whether DSH/plugin was installed via npx, a global CLI,
@@ -111,6 +131,7 @@ export async function checkPackageUpdate({
   currentVersion = CURRENT_VERSION,
   registry = registryBaseFromEnv(),
   fallbackRegistry = DEFAULT_NPM_REGISTRY,
+  releaseApi = GITHUB_LATEST_RELEASE_API,
   signal,
   timeoutMs = 10_000,
 } = {}) {
@@ -155,10 +176,48 @@ export async function checkPackageUpdate({
     }
   }
 
-  throw new Error(
-    'update check failed: ' +
-      failures.map((item) => `${item.registry} (${item.error})`).join(' -> '),
-  )
+  // Registry metadata is the source of truth for installability, but a user's
+  // registry path can be blocked while GitHub remains reachable. Use the
+  // project's latest release only as a read-only version fallback so the UI
+  // can still show an exact `@<version>` recovery command instead of falling
+  // back to a bare `update` (which pnpm 11 may silently withhold for 24h).
+  if (signal?.aborted) throw signal.reason ?? new Error('update check aborted')
+  try {
+    const latestVersion = await fetchLatestReleaseVersion({
+      fetchImpl,
+      releaseApi,
+      signal,
+      timeoutMs,
+    })
+    const precedence = compareSemver(currentVersion, latestVersion)
+    return {
+      ok: true,
+      packageName: PACKAGE_NAME,
+      currentVersion,
+      latestVersion,
+      updateAvailable: precedence === -1,
+      aheadOfRegistry: precedence === 1,
+      checkedAt: Date.now(),
+      latestSource: 'github-release',
+      releaseFallback: true,
+      registryFailures: failures,
+      releasesUrl: RELEASES_URL,
+      // Exact on purpose: `@latest` can still be filtered by pnpm 11's
+      // minimumReleaseAge policy, while an explicit version is exempted.
+      packageSpec: `${PACKAGE_NAME}@${latestVersion}`,
+      installMethodAgnostic: true,
+    }
+  } catch (error) {
+    if (signal?.aborted) throw error
+    const releaseFailure = errorMessage(error)
+    throw new Error(
+      'update check failed: ' +
+        [
+          ...failures.map((item) => `${item.registry} (${item.error})`),
+          `${releaseApi} (${releaseFailure})`,
+        ].join(' -> '),
+    )
+  }
 }
 
 /**
@@ -170,6 +229,7 @@ export function createCachedUpdateChecker({
   currentVersion = CURRENT_VERSION,
   registry = registryBaseFromEnv(),
   fallbackRegistry = DEFAULT_NPM_REGISTRY,
+  releaseApi = GITHUB_LATEST_RELEASE_API,
   successTtlMs = 6 * 60 * 60 * 1000,
   failureTtlMs = 5 * 60 * 1000,
   timeoutMs = 10_000,
@@ -191,6 +251,7 @@ export function createCachedUpdateChecker({
       currentVersion,
       registry,
       fallbackRegistry,
+      releaseApi,
       timeoutMs,
     }).catch((error) => ({
       ok: false,
@@ -198,7 +259,9 @@ export function createCachedUpdateChecker({
       checkedAt: Date.now(),
       registry: normalizeRegistryBase(registry),
       releasesUrl: RELEASES_URL,
-      packageSpec: `${PACKAGE_NAME}@latest`,
+      // No ambiguous package target when every version source failed. The UI
+      // must require the user to confirm an exact release before constructing
+      // a recovery command.
       installMethodAgnostic: true,
       error: errorMessage(error),
     }))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vision-router",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "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": {