dsh-vision-router 1.4.0 → 1.4.2

package/README.md

@@ -15,8 +15,8 @@
 </p>
 
 <p align="center">
-  <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="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.4.2"><img src="https://img.shields.io/badge/release-v1.4.2-5B4CF0?style=flat-square" alt="Release v1.4.2" /></a>
+  <a href="tests"><img src="https://img.shields.io/badge/verified-252%20tests-2EA44F?style=flat-square" alt="Verified: 252 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.4.0)**
+> 📌 **Announcement (v1.4.2)**
 >
-> **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.
+> **v1.4.2 now supports** Oh-DSH Desktop — the plugin no longer races the stock DeepSeek route on the bundled DSH 0.1.0-rc.5 runtime (fixes "DSH runtime exited before readiness"), opencode-go qwen3.6-plus vision calls reach the correct Anthropic endpoint, and "+ Auto Vision" twins keep the picker's reasoning effort across multi-step turns.
 
 <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" />
@@ -40,6 +40,7 @@
 
 - [Why this exists](#why-this-exists)
 - [How it compares](#how-it-compares)
+- [Acknowledgements](#acknowledgements)
 - [Quick start](#quick-start)
 - [Highlights](#highlights)
 - [How it works](#how-it-works)
@@ -61,20 +62,41 @@ Most DSH vision plugins bridge images to DeepSeek as *text descriptions* — los
 
 ## How it compares
 
-The closest alternative is [@anionex/dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit) (Anionex), a native DSH bundle of the well-known `agent-vision-toolkit` lineage. Both packages ship a `vision-tools` skill and a family of pixel-level tools; they differ in philosophy — **zero-config paste-and-go** versus **agent-driven visual engineering**:
+**One-line take**: most dsh vision plugins turn images into *text descriptions* for DeepSeek
+(description bridge — lossy); this plugin hands the image turn *straight to a vision model*
+(routing bridge — pixel-faithful), with a built-in keyless free fallback.
 
-| | dsh-vision-router | @anionex/dsh-vision-toolkit |
-|---|---|---|
-| Image Q&A out of the box | ✅ Built-in free chain (anonymous OVHcloud endpoint) — no account, no key | Requires your own vision API key (local pixel tools work without one) |
-| Runtime | ✅ Node only — no Python | Python 3.11+ managed runtime |
-| Getting an image in | ✅ Pick a “+ Auto Vision” group once, then paste directly | Workspace path + `/vision-tools` command, then explicit tool calls |
-| Turn routing | ✅ Image turns switch to vision, text turns switch back to DeepSeek — optional stealth takeover keeps the model picker looking stock | Tool-driven; no whole-turn auto-routing |
-| Profiles | Web | Web + Headless |
-| Playbooks | The pixel loop: ground → crop → diff → fix → screenshot again | Richer case library (long-screenshot OCR, UI restoration, GUI automation) |
-| Tests | 144 | 162 |
-| Install | One command | One command (npm) |
+| | Manual model switching | MCP vision bridge | dsh-vision-router |
+|---|---|---|---|
+| Pixel fidelity | ✅ full (when switched) | ❌ text description only | ✅ full, on the image turn |
+| Automatic | ❌ | ✅ | ✅ |
+| Daily model untouched | ❌ (whole session swapped) | ✅ | ✅ |
+| Provider failure recovery | ❌ | ❌ | ✅ fallback chains |
+| Reusable structured queries | — | partial | ✅ JSON mode + caching |
+| Free out-of-the-box | ❌ | ❌ | ✅ built-in keyless endpoint |
+| Fits dsh composition | — | external server | ✅ one plugin row |
+
+**Difference from existing dsh community projects** (all excellent, each with its own focus; descriptions reflect their READMEs as of 2026-08):
 
-Both are MIT-licensed and one command away. Pick this plugin when you want images to *just work* with zero setup; pick theirs when you need headless profiles or the extended playbook library. (Feature comparison reflects their README as of 2026-08.)
+| Project | Approach | What this plugin adds |
+|---|---|---|
+| [dsh-vision-sidecar](https://github.com/121103qwq/dsh-vision-sidecar) | Pre-describes images with an external VLM; the description joins the session as a message to DeepSeek; LLM7.io anonymous endpoint by default (OVHcloud listed as a no-key alternative) | Description bridge; this plugin adds raw-image routing, with `vision_describe` covering descriptions on demand |
+| [dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy) | Wraps a provider route and transcribes images into text in the request stream | Transcription bridge; this plugin wraps no provider — it rewrites routing through `agent/request` waterfalls |
+| [dsh-vision-provider](https://github.com/libinyam/dsh-vision-provider) | Registers `DeepSeek + Vision` combined routes: images are described by the chosen vision model before reaching DeepSeek | Two-model bridge idea; this plugin adds automatic routing, fallback chains and tools on top |
+| [modlens](https://github.com/liustack/modlens) | The first dsh vision plugin; reuses local Claude Code/Codex/OpenCode/Pi logins as vision engines | Engine-reuse idea; this plugin ships its own provider chain and depends on no other local CLI |
+| [dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit) | Ten intent-aware visual tools (Q&A/OCR/pixel verification/UI restoration), called explicitly on demand | Broader tool set; this plugin adds whole-turn auto-routing and a keyless free fallback |
+| [dsh-tool-vision](https://github.com/Scorp1o117/dsh-tool-vision) | An `inspect_image` tool plus an `agent/pre-step` waterfall bridge (pasted images become tool hints before entering the log) | Similar waterfall bridge; this plugin adds turn routing, fallback chains, caching and the free endpoint |
+
+## Acknowledgements
+
+This project borrows ideas from all of the above — especially the keyless free-endpoint
+exploration (LLM7.io and OVHcloud anonymous tiers) by
+[dsh-vision-sidecar](https://github.com/121103qwq/dsh-vision-sidecar). Thanks to the authors of
+[dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy),
+[dsh-vision-provider](https://github.com/libinyam/dsh-vision-provider),
+[modlens](https://github.com/liustack/modlens),
+[dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit), and
+[dsh-tool-vision](https://github.com/Scorp1o117/dsh-tool-vision).
 
 ## Quick start
 
@@ -176,7 +198,7 @@ Default `progressiveTools: false`: all eleven deep tools stay registered from pl
 | `vision_ocr` | Text transcription: local tesseract (chi_sim+eng) first, vision model fallback | — |
 | `vision_trace` | SVG vectorization (potrace posterization; icons/logos) | SVG |
 | `vision_extract_foreground` | Cutout via border flood fill (uniform backgrounds) | transparent PNG |
-| `vision_html_screenshot` | Screenshot a local HTML file (headless system Chrome) | PNG |
+| `vision_html_screenshot` | Screenshot a local HTML file (headless system Chrome); `fullPage: true` captures the whole page and reports `pageHeight` | PNG |
 | `vision_long_screenshot_ocr` | Long-screenshot transcription: overlapping chunks, tesseract first / vision model fallback, stitched Markdown | chunk PNGs + Markdown + manifest |
 
 Formats are sniffed from magic bytes, so extensionless content-addressed attachment files work everywhere (no `.png` renaming needed).
@@ -194,6 +216,7 @@ vision_colors image="ref.png" top=8
 vision_trace image="icon.png" steps=4
 vision_extract_foreground image="logo.png"
 vision_html_screenshot source="page.html" width=1200 height=720
+vision_html_screenshot source="page.html" width=1200 height=720 fullPage=true
 vision_long_screenshot_ocr image="chat-log.png" chunkHeight=1200 overlap=120
 ```
 
@@ -282,6 +305,7 @@ Everything is optional; defaults work out of the box. Edit via the Web card or a
 | `timeoutMs` | `120000` | per vision call deadline |
 | `artifactsDir` | `.dsh-vision-router/artifacts` | artifact directory (relative to the session workspace) |
 | `proxy` / `proxyHosts` | `''` / openrouter hosts | optional proxy for vision provider hosts only |
+| `catalogCorrections` | `true` | built-in catalog-routing corrections: when the installed pi-ai catalog routes a known model to the wrong wire protocol (e.g. `opencode-go/qwen3.6-plus` to OpenAI chat completions while OpenCode Go only serves it on `/v1/messages`), the plugin answers that backend directly over the corrected protocol. Each correction disarms itself once the catalog is fixed upstream |
 
 ## Requirements
 
@@ -316,6 +340,25 @@ npx @deepseek-ai/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.**
 
+### Oh-DSH Desktop
+
+[Oh-DSH Desktop](https://github.com/hust-open-atom-club/oh-dsh) ships its own packaged DSH runtime and its own home layout: the desktop surface runs the `desktop` profile under `~/.ohdsh` and does **not** load ordinary `~/.dsh` profiles. The `--profile web` commands above therefore install into the wrong environment on that product.
+
+Install into the desktop profile by pointing `DSH_HOME` at the Oh-DSH home:
+
+```sh
+DSH_HOME=~/.ohdsh npx @deepseek-ai/dsh plugin --profile desktop add dsh-vision-router
+```
+
+(Windows PowerShell: run `$env:DSH_HOME = "$env:USERPROFILE\.ohdsh"` first, then the same command.)
+
+> [!WARNING]
+> Oh-DSH Desktop ≤ 0.1.5 bundles DSH `0.1.0-rc.5`. `dsh-vision-router` v1.4.1 and earlier crash that runtime at startup (`configurable provider "deepseek-official" is already declared`, surfacing as `DSH runtime exited before readiness`). Install v1.4.2+.
+
+If a broken install already keeps the Desktop from starting, open `~/.ohdsh/profiles/desktop/package.json`, remove the `dsh-vision-router` entry from both `dependencies` and `dsh.profile.bundles`, save, and restart the Desktop.
+
+Oh-DSH Desktop's built-in plugin marketplace (search → prepare → isolated preview → apply, with a `previous` snapshot for recovery) also works once the community catalog lists this plugin; do not mix marketplace installs with the direct command above. The bundled `@oh-dsh/vision` (`view_image`) coexists with this plugin — the tool names do not collide.
+
 ### Disable / re-enable
 
 ```yaml
@@ -328,16 +371,17 @@ Set it back to `false` to re-enable. Unloading removes the wrapper routes, tools
 ### Upgrade
 
 ```sh
-# normal npm/npx install
-npx @deepseek-ai/dsh plugin --profile web update dsh-vision-router
+# normal npm/npx install — install the version you want explicitly; a bare
+# `update` is silently held back for releases younger than 24h (pnpm v11)
+npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router@<version>
 
 # DeepSeek Harness source checkout
-pnpm dsh plugin --profile web update dsh-vision-router
+pnpm dsh plugin --profile web add dsh-vision-router@<version>
 ```
 
-Settings live in the profile's settings provider and survive upgrades.
+Settings live in the profile's settings provider and survive upgrades. The settings card's one-click update installs the registry-confirmed version explicitly and verifies the installed manifest afterwards — it never reports success on a package-manager exit code alone.
 
-> **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.
+> **A fresh release does not take effect (`downloaded 0` / `added 0`):** pnpm v11 holds versions younger than 24h back; install the target version explicitly as above (pnpm auto-exempts it), or `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

package/README.zh.md

@@ -15,8 +15,8 @@
 </p>
 
 <p align="center">
-  <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="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.4.2"><img src="https://img.shields.io/badge/release-v1.4.2-5B4CF0?style=flat-square" alt="Release v1.4.2" /></a>
+  <a href="tests"><img src="https://img.shields.io/badge/verified-252%20tests-2EA44F?style=flat-square" alt="Verified: 252 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.4.0）**
+> 📌 **公告（v1.4.2）**
 >
-> **v1.4.0 现已支持**：未声明视觉模型的自动识别与直连桥接、doctor 修复过期版本钉住豁免、引导流程聚光灯高亮——并增强设置保存校验与视觉后端兼容性。
+> **v1.4.2 现已支持**：Oh-DSH Desktop 兼容——在内置的 DSH 0.1.0-rc.5 上不再与官方 DeepSeek 路由竞争导致启动崩溃（修复「DSH runtime exited before readiness」）；opencode-go qwen3.6-plus 视觉调用走正确的 Anthropic 端点；「+ 自动识图」twin 组在多步对话中保留选择器里的推理等级。
 
 <p align="center">
   <img src="assets/vision-demo.gif" width="640" alt="演示：粘贴图片，Agent 用 vision_ground / vision_crop / vision_pixel_diff 定位发送按钮并给出坐标" />
@@ -40,6 +40,7 @@
 
 - [为什么做这个](#为什么做这个)
 - [对比同类插件](#对比同类插件)
+- [致谢](#致谢)
 - [快速开始](#快速开始)
 - [亮点](#亮点)
 - [工作原理](#工作原理)
@@ -61,20 +62,39 @@
 
 ## 对比同类插件
 
-最接近的同类是 [@anionex/dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit)（Anionex），它是知名 `agent-vision-toolkit` 系列的 DSH 原生版。两者都提供 `vision-tools` 技能和一组像素级工具，区别在理念：**零配置粘贴即用** vs **Agent 主导的视觉工程**：
+**一句话讲清区别**：其他 dsh 视觉插件大多"把图片转成文字描述再喂给 DeepSeek"（描述桥，有信息损耗）；
+本插件主打"**图片轮直接交给视觉模型看原图**"（路由桥，像素保真），同时内置免 Key 免费模型兜底。
 
-| | dsh-vision-router | @anionex/dsh-vision-toolkit |
-|---|---|---|
-| 开箱图片问答 | ✅ 内置免费视觉链（OVHcloud 匿名端点），免注册免 Key | 远程工具需自备视觉 API Key（本地像素工具免 Key） |
-| 运行时 | ✅ 纯 Node，无需 Python | 需要 Python 3.11+ 受管运行时 |
-| 图片怎么进来 | ✅ 选一次「+ 自动识图」模型组后直接粘贴 | 工作区路径 + `/vision-tools` 命令，再显式调用工具 |
-| 轮次路由 | ✅ 图片轮切视觉、文本轮切回 DeepSeek——可选隐身接管，模型选择器与官方一致 | 工具驱动，无整轮自动路由 |
-| 支持 profile | Web | Web + Headless |
-| 玩法库 | 像素循环：定位 → 裁剪 → 对比 → 修复 → 再截图 | 更丰富的案例库（长截图 OCR、UI 还原、GUI 自动化） |
-| 测试 | 144 | 162 |
-| 安装 | 一条命令 | 一条命令（npm） |
+| | 手动切换模型 | MCP 视觉桥 | 本插件 |
+|---|---|---|---|
+| 像素保真 | ✅ 完整（切换后） | ❌ 只有文字描述 | ✅ 完整，图片轮内 |
+| 自动化 | ❌ | ✅ | ✅ |
+| 日常模型不受影响 | ❌（整会话被换） | ✅ | ✅ |
+| 供应商失败恢复 | ❌ | ❌ | ✅ 降级链 |
+| 可复用的结构化查询 | — | 部分 | ✅ JSON 模式 + 缓存 |
+| 免费开箱即用 | ❌ | ❌ | ✅ 内置免 Key 免费端点 |
+| 贴合 dsh 组合体系 | — | 外部服务器 | ✅ 一行插件行 |
+
+**与现有 dsh 社区方案的差异**（均为优秀项目，各有侧重；描述以各家 README 2026-08 状态为准）：
 
-两者都是 MIT 许可、一条命令安装。想要图片**粘贴即用**、零配置就选本插件；需要 Headless 部署或更丰富的案例库，可以看 @anionex/dsh-vision-toolkit。（功能对比以其 README 2026-08 状态为准。）
+| 项目 | 思路 | 本插件的差异 |
+|---|---|---|
+| [dsh-vision-sidecar](https://github.com/121103qwq/dsh-vision-sidecar) | 图片先经外部 VLM 做 OCR/描述，描述作为会话消息交给 DeepSeek；默认 LLM7.io 匿名端点（OVHcloud 为无 Key 备选） | 描述桥方案；本插件提供"原图直看"路由，描述能力由 `vision_describe` 按需替代 |
+| [dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy) | 包装 provider 路由，请求流里把图片转译成文本再交给 DeepSeek | 转译桥方案；本插件不包装 provider，通过 `agent/request` 瀑布改写路由 |
+| [dsh-vision-provider](https://github.com/libinyam/dsh-vision-provider) | 注册 `DeepSeek + Vision` 组合路由：图片先经所选视觉模型转成描述，再交给 DeepSeek | 双模型桥思路；本插件在此基础上增加自动路由、降级链与工具 |
+| [modlens](https://github.com/liustack/modlens) | 最早的 dsh 视觉插件；复用本机 Claude Code/Codex/OpenCode/Pi 等登录态作为视觉引擎 | 引擎复用思路；本插件自带供应商链，不依赖本机其他 CLI |
+| [dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit) | 10 个意图化视觉工具（Q&A/OCR/像素校验/UI 还原），按需显式调用 | 工具集更全；本插件多出整轮自动路由与免 Key 免费兜底 |
+| [dsh-tool-vision](https://github.com/Scorp1o117/dsh-tool-vision) | `inspect_image` 工具 + `agent/pre-step` 瀑布图片桥（粘贴图入日志前转成工具提示） | 瀑布桥思路相近；本插件多出轮次路由、降级链、缓存与免费端点 |
+
+## 致谢
+
+本插件借鉴了以上全部社区项目的思路，特别是 [dsh-vision-sidecar](https://github.com/121103qwq/dsh-vision-sidecar)
+对免注册免 Key 视觉端点的探索（LLM7.io 与 OVHcloud 匿名层）。感谢
+[dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy)、
+[dsh-vision-provider](https://github.com/libinyam/dsh-vision-provider)、
+[modlens](https://github.com/liustack/modlens)、
+[dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit)、
+[dsh-tool-vision](https://github.com/Scorp1o117/dsh-tool-vision) 作者们的探索。
 
 ## 快速开始
 
@@ -176,7 +196,7 @@ Agent 仅根据参考图复刻 UI，再用 `vision_pixel_diff` 验证最终结
 | `vision_ocr` | 文字转写：本地 tesseract（中英）优先，视觉模型兜底 | — |
 | `vision_trace` | SVG 矢量化（potrace 分色；图标/logo） | SVG |
 | `vision_extract_foreground` | 边界洪泛抠图（纯色背景） | 透明 PNG |
-| `vision_html_screenshot` | 给本地 HTML 文件截图（无头系统 Chrome） | PNG |
+| `vision_html_screenshot` | 给本地 HTML 文件截图（无头系统 Chrome）；`fullPage: true` 截整页并返回 `pageHeight` | PNG |
 | `vision_long_screenshot_ocr` | 长截图转写：重叠分片，tesseract 优先 / 视觉模型回退，按序拼接 Markdown | 分片 PNG + Markdown + manifest |
 
 图片格式按**魔数识别**，无扩展名的内容寻址附件文件也能直接用（不用再复制成 `.png`）。
@@ -194,6 +214,7 @@ vision_colors image="ref.png" top=8
 vision_trace image="icon.png" steps=4
 vision_extract_foreground image="logo.png"
 vision_html_screenshot source="page.html" width=1200 height=720
+vision_html_screenshot source="page.html" width=1200 height=720 fullPage=true
 vision_long_screenshot_ocr image="chat-log.png" chunkHeight=1200 overlap=120
 ```
 
@@ -282,6 +303,7 @@ Web 配置页在 **设置 → 插件 → 插件配置** 下注册「视觉路由
 | `timeoutMs` | `120000` | 单次视觉调用超时 |
 | `artifactsDir` | `.dsh-vision-router/artifacts` | 产物目录（相对会话工作区） |
 | `proxy` / `proxyHosts` | `''` / openrouter 域名 | 仅视觉供应商域名可选的本地代理 |
+| `catalogCorrections` | `true` | 内置目录纠错：当已安装的 pi-ai 目录把已知模型路由到错误协议时（例如 `opencode-go/qwen3.6-plus` 被指向 OpenAI chat completions，而 OpenCode Go 只在 `/v1/messages` 上提供该模型），插件直接按正确协议应答该后端；上游目录修复后每条纠错自动失效 |
 
 ## 环境要求
 
@@ -316,6 +338,25 @@ npx @deepseek-ai/dsh --profile web --dump-config | grep vision-router
 
 首次把插件装进已经长期运行的 Web profile 时，需要让 Web 进程重新加载插件本体；宿主在启动时通过 `dsh.client` 声明发现浏览器端包。**插件加载完成后，模型目录与包装范围的变化会热更新，不需要为这些变化重启。**
 
+### Oh-DSH Desktop
+
+[Oh-DSH Desktop](https://github.com/hust-open-atom-club/oh-dsh) 自带一套独立打包的 DSH 运行时和独立的数据目录：桌面端实际运行的是 `~/.ohdsh` 下的 `desktop` profile，**不会**加载普通 `~/.dsh` 的 profile。因此上面 `--profile web` 的命令在 Oh-DSH Desktop 上会装错环境。
+
+把 `DSH_HOME` 指向 Oh-DSH 的数据目录再安装即可：
+
+```sh
+DSH_HOME=~/.ohdsh npx @deepseek-ai/dsh plugin --profile desktop add dsh-vision-router
+```
+
+（Windows PowerShell 先执行 `$env:DSH_HOME = "$env:USERPROFILE\.ohdsh"`，再运行同一命令。）
+
+> [!WARNING]
+> Oh-DSH Desktop ≤ 0.1.5 内置的是 DSH `0.1.0-rc.5`。`dsh-vision-router` v1.4.1 及更早版本会让该运行时在启动时崩溃（报 `configurable provider "deepseek-official" is already declared`，在 Oh-DSH Desktop 里表现为 `DSH runtime exited before readiness`）。请安装 v1.4.2+。
+
+如果错误安装已经导致 Desktop 无法启动：打开 `~/.ohdsh/profiles/desktop/package.json`，从 `dependencies` 和 `dsh.profile.bundles` 中删掉 `dsh-vision-router` 条目，保存后重启 Desktop。
+
+Oh-DSH Desktop 内置的插件市场（搜索 → 准备 → 隔离预览 → 应用，并保留 `previous` 快照用于恢复）在社区目录收录本插件后同样可用；不要与上面的直接安装命令混用。其内置的 `@oh-dsh/vision`（`view_image`）与本插件可共存，工具名不冲突。
+
 ### 禁用 / 恢复
 
 ```yaml
@@ -328,16 +369,17 @@ npx @deepseek-ai/dsh --profile web --dump-config | grep vision-router
 ### 升级
 
 ```sh
-# 普通 npm / npx 安装
-npx @deepseek-ai/dsh plugin --profile web update dsh-vision-router
+# 普通 npm / npx 安装 —— 显式安装目标版本；裸 `update` 会被 pnpm v11
+# 静默拦下发布不足 24 小时的新版本
+npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router@<版本号>
 
 # DeepSeek Harness 源码仓库
-pnpm dsh plugin --profile web update dsh-vision-router
+pnpm dsh plugin --profile web add dsh-vision-router@<版本号>
 ```
 
-设置存放在 profile 的设置提供方里，升级不丢失。
+设置存放在 profile 的设置提供方里，升级不丢失。设置卡里的一键更新会自动显式安装 registry 已确认的版本，并在命令结束后核对实际安装版本——绝不只凭包管理器退出码就报成功。
 
-> **新版本一直不生效（`downloaded 0` / `added 0`）：** pnpm v11 会拦下发布不足 24 小时的版本；运行 `npx dsh-vision-router repair` 修复过期的带版本号豁免条目后，更新立即生效。
+> **新版本一直不生效（`downloaded 0` / `added 0`）：** pnpm v11 会拦下发布不足 24 小时的版本；按上面方式显式安装目标版本（pnpm 会自动写入豁免），或运行 `npx dsh-vision-router repair` 修复过期的带版本号豁免条目后，更新立即生效。
 
 > **从 bundle 补丁之前（v0.x）升级：** 现在插件由自带的 bundle 补丁自动挂载，
 > 若 `~/.dsh/profiles/<profile>/cordis.patch.yml` 里还残留旧版手动行，会与之

package/docs/update-check.md

@@ -18,25 +18,27 @@ DSH and the plugin may have been launched through different paths, including `np
 When an update is available, the plugin inspects the CLI entry of the current process. One-click update is enabled only when that entry can be traced to a real `@deepseek-ai/dsh` package and can be executed safely by the current Node runtime. In that case Vision Router runs the documented DSH updater through the **same DSH CLI that is already hosting the plugin**:
 
 ```sh
-dsh plugin --profile <current-profile> update dsh-vision-router
+dsh plugin --profile <current-profile> add dsh-vision-router@<latest>
 ```
 
-The subprocess uses `execFile` with `shell: false`; no shell command is constructed from browser input. The update endpoint also requires a process-local token returned by the same-origin update-check endpoint. After the updater exits successfully, the settings card asks the user to restart DSH so the new plugin bundle is loaded.
+The registry-confirmed target version is installed explicitly rather than through a bare `update`. This matters because pnpm 11 applies `minimumReleaseAge` (default 1440 minutes): a plain `pnpm update` silently keeps the current version while every candidate release is younger than 24h and still exits 0 ("Already up to date") — a false-success update that leaves the old version running after restart. `add <name>@<version>` installs the confirmed release (pnpm auto-exempts the requested version from the policy when needed). For non-registry installs (git/file/link/workspace specs) the updater keeps `update` semantics and only verifies the result.
+
+The subprocess uses `execFile` with `shell: false`; no shell command is constructed from browser input. The update endpoint also requires a process-local token returned by the same-origin update-check endpoint. After the updater exits, the plugin reads the `dsh-vision-router` manifest under the profile's `node_modules` and verifies that the installed version actually reached the target — **a zero exit code alone is never reported as success**. Only a verified update asks the user to restart DSH so the new plugin bundle is loaded.
 
 If the CLI cannot be verified — for example a raw TypeScript source entry that needs a workspace-specific loader — the one-click button is not offered. This commonly applies to a DSH source checkout launched with `pnpm dsh`: version checking still works, but updating remains under the source workspace's own pnpm workflow. The card keeps the version information and release-notes link and tells the user to update through their original DSH installation path instead.
 
 ## Manual recovery
 
-If automatic update is unavailable, the version check fails, or a one-click update fails, the settings card still shows direct Project/Releases links and a manual command. For a DeepSeek Harness source checkout run:
+If automatic update is unavailable, the version check fails, or a one-click update fails, the settings card still shows direct Project/Releases links and a manual command. When a newer version is known, the shown commands install that version explicitly, which bypasses the release-age withholding described above. For a DeepSeek Harness source checkout run:
 
 ```sh
-pnpm dsh plugin --profile web update dsh-vision-router
+pnpm dsh plugin --profile web add dsh-vision-router@<latest>
 ```
 
 For normal npm/npx DSH usage run:
 
 ```sh
-npx @deepseek-ai/dsh plugin --profile web update dsh-vision-router
+npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router@<latest>
 ```
 
-The settings card substitutes the active profile when it can determine one.
+The settings card substitutes the active profile when it can determine one. If the version still does not change after an update command, check the profile's `pnpm-workspace.yaml` for a version-pinned `minimumReleaseAgeExclude` entry — `npx dsh-vision-router repair` rewrites stale pins to bare names so future releases resolve again (see `docs/doctor.md`).

package/docs/update-check.zh-CN.md

@@ -18,25 +18,27 @@ Vision Router 会检查是否有新的已发布版本；当当前运行中的 DS
 发现新版本后，插件会检查当前进程真正使用的 DSH CLI 入口。只有该入口能够向上验证到真实的 `@deepseek-ai/dsh` 包，并且可以由当前 Node 运行时安全执行时，设置卡才显示“一键更新”。此时调用的不是某个猜出来的包管理器，而是**当前正在托管插件的同一套 DSH CLI**：
 
 ```sh
-dsh plugin --profile <当前 profile> update dsh-vision-router
+dsh plugin --profile <当前 profile> add dsh-vision-router@<最新版>
 ```
 
-子进程通过 `execFile` 且 `shell: false` 启动，不会把浏览器输入拼成 shell 命令。更新接口还要求由同源更新检查接口返回的本进程临时 token，避免网页跨站请求直接触发更新。更新命令成功后，设置卡会提示用户重启 DSH，让新插件 bundle 真正加载。
+这里会**显式安装 registry 已确认的目标版本**，而不是裸 `update`。原因是 pnpm 11 默认启用 `minimumReleaseAge`（1440 分钟）：当候选新版本发布不足 24 小时时，裸 `pnpm update` 会静默保留当前版本并仍然以退出码 0 结束（输出 “Already up to date”）——这就是“点了更新、提示成功、重启后版本没变”的假成功。`add <包名>@<版本>` 会安装确认过的发布版（pnpm 需要时会自动为新版本写入策略豁免）。对于非 registry 安装（git / file / link / workspace 规格），更新器保持 `update` 语义、只校验结果。
+
+子进程通过 `execFile` 且 `shell: false` 启动，不会把浏览器输入拼成 shell 命令。更新接口还要求由同源更新检查接口返回的本进程临时 token，避免网页跨站请求直接触发更新。更新命令退出后，插件会读取 profile `node_modules` 下 `dsh-vision-router` 的清单并核对安装版本确实达到目标——**仅凭退出码 0 永远不会被当作成功**。只有校验通过的更新才会提示用户重启 DSH，让新插件 bundle 真正加载。
 
 若无法可靠验证当前 CLI——例如直接运行需要 workspace 专用 loader 的 TypeScript 源码入口——就不会显示一键更新按钮。**源码仓库里通过 `pnpm dsh` 启动通常属于这种情况：版本检查仍然可以正常工作，只是一键更新继续交给源码工作区自己的 pnpm 流程。** 此时仍会显示当前/最新版本和 Release Notes，并提示用户沿用原来的 DSH 安装方式手动更新。
 
 ## 手动兜底
 
-如果自动更新不可用、版本检查失败，或一键更新失败，设置卡仍会直接显示项目主页 / Releases 入口和可执行的手动命令。DeepSeek Harness 源码仓库通过 pnpm 启动时使用：
+如果自动更新不可用、版本检查失败，或一键更新失败，设置卡仍会直接显示项目主页 / Releases 入口和可执行的手动命令。发现新版本时，显示的命令会带版本号显式安装，从而绕过上面描述的发布龄拦截。DeepSeek Harness 源码仓库通过 pnpm 启动时使用：
 
 ```sh
-pnpm dsh plugin --profile web update dsh-vision-router
+pnpm dsh plugin --profile web add dsh-vision-router@<最新版>
 ```
 
 普通 npm / npx DSH 使用：
 
 ```sh
-npx @deepseek-ai/dsh plugin --profile web update dsh-vision-router
+npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router@<最新版>
 ```
 
-如果插件能识别当前 profile，设置页会把命令里的 `web` 自动替换成实际 profile。
+如果插件能识别当前 profile，设置页会把命令里的 `web` 自动替换成实际 profile。若执行后版本仍未变化，请检查 profile 的 `pnpm-workspace.yaml` 里是否有版本钉住的 `minimumReleaseAgeExclude` 条目——`npx dsh-vision-router repair` 会把过期的钉住条目改写为裸名，让后续新版本恢复正常解析（见 `docs/doctor.md`）。

package/entry.js

@@ -9,6 +9,7 @@
 import z from '@deepseek-ai/schemastery'
 import * as core from './index.js'
 import { installVisionRouterFileLogging } from './lib/file-logger.js'
+import { contextWithDelegatedReplay } from './lib/replay-delegation.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
@@ -21,13 +22,14 @@ 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.
+// schema-changing progressive mode. The wrapped context changes logger plus a
+// private llm view used only by Vision Router: wrapper -> delegate calls can
+// restore adapter-owned replay identity without mutating the host LLM service.
 export function apply(ctx, config = {}) {
   const logging = installVisionRouterFileLogging(ctx)
+  const runtimeCtx = contextWithDelegatedReplay(logging.ctx)
   try {
-    const result = core.apply(logging.ctx, {
+    const result = core.apply(runtimeCtx, {
       ...config,
       progressiveTools: config.progressiveTools === true,
     })