dsh-vision-router 1.0.1 → 1.1.1

package/README.md

@@ -10,8 +10,8 @@
 
 <p align="center">
   <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="awesome · DSH plugin" /></a>
-  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.0.0"><img src="https://img.shields.io/badge/release-v1.0.0-5B4CF0?style=flat-square" alt="Release v1.0.0" /></a>
-  <a href="tests"><img src="https://img.shields.io/badge/verified-86%20tests-2EA44F?style=flat-square" alt="Verified: 86 tests" /></a>
+  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.1.1"><img src="https://img.shields.io/badge/release-v1.1.1-5B4CF0?style=flat-square" alt="Release v1.1.1" /></a>
+  <a href="tests"><img src="https://img.shields.io/badge/verified-101%20tests-2EA44F?style=flat-square" alt="Verified: 101 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" />
@@ -20,6 +20,11 @@
 
 <p align="center">English · <a href="README.zh.md">中文</a></p>
 
+> [!WARNING]
+> 📌 **Announcement (v1.1.1)**
+>
+> Existing DSH providers are now **auto-wrapped on install**: text-only routes gain paste-and-go vision automatically, while native multimodal models keep their original image input and use Vision Router tools only when useful. Windows sharp/libvips startup conflicts are fixed by sharing the host sharp; install/update docs now distinguish npm/npx from source-checkout pnpm usage.
+
 <p align="center">
   <img src="assets/vision-demo.gif" width="640" alt="Demo: paste an image, the agent locates the send button with vision_ground / vision_crop / vision_pixel_diff and answers with coordinates" />
 </p>
@@ -28,7 +33,7 @@
 
 Most DSH vision plugins bridge images to DeepSeek as *text descriptions* — lossy, one-shot, and blind to pixels. This plugin keeps the **original pixels on the vision model's side** and DeepSeek on the reasoning side, and makes looking at an image an **ordinary tool call**:
 
-- **One command install, purely additive.** The package ships its own composition patch (`dsh.bundle.patch`): `dsh plugin add` mounts the plugin row and nothing else — no core row is disabled or overridden (issue #34).
+- **One command install.** The package ships its own composition patch (`dsh.bundle.patch`): `dsh plugin add` wires the row, the admission wrapper and the attachment limits automatically — zero manual file edits. Taking over the official DeepSeek route is an optional setting (stealth mode, off by default).
 - **Free by default.** The vision chain starts with a built-in OVHcloud anonymous endpoint (`Qwen2.5-VL-72B-Instruct`, no account, no key, 2 req/min per IP). Paid chains (OpenRouter, Pi-AI providers, direct OpenAI-compatible endpoints) are optional upgrades.
 - **No Python.** The whole pipeline — downscale, grounding, crop, pixel diff, palette, OCR, SVG trace, cutout, HTML screenshot — runs on sharp / potrace / tesseract / system Chrome.
 - **Continuous multi-step image work.** An image turn is a text turn that calls tools: `vision_ground` → `vision_crop` → `vision_describe` → `vision_pixel_diff` → fix → screenshot again. The agent keeps iterating until the work is done.
@@ -37,30 +42,43 @@ Most DSH vision plugins bridge images to DeepSeek as *text descriptions* — los
 
 ## How it compares
 
-Most DSH vision plugins feed DeepSeek a *text description* of the image. This plugin keeps the **original pixels on the vision model's side**, ships a **built-in free chain**, and treats looking at an image as an **ordinary tool call** — paste it and it just works, multi-step until done.
+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**:
 
-| | Manual model switching | Description bridges (dsh-vision-sidecar · dsh-vision-proxy · dsh-vision · dsh-tool-vision) | @anionex/dsh-vision-toolkit | modlens | dsh-vision-router |
-|---|---|---|---|---|---|
-| Works out of the box, no key | ❌ | partial | ❌ remote tools need your own key | ❌ needs your own key | ✅ built-in keyless vision chain |
-| Original-pixel fidelity | ✅ after manual switching | ❌ text description only | ✅ | ✅ structured evidence | ✅ original pixels + pixel tools |
-| No per-turn manual switching | ❌ | ✅ | ✅ | ✅ | ✅ auto tool mounting + stealth routing |
-| Daily model untouched | ❌ session swapped | ✅ | ✅ | ✅ | ✅ DeepSeek stays the brain |
-| Multi-provider fallback with classified errors | ❌ | ❌ | partial | — | ✅ chain + 429 backoff + downscale |
-| No Python runtime | ✅ | ✅ | ❌ Python 3.11+ | ✅ | ✅ Node only |
-| One-command install | — | — | ✅ | ✅ | ✅ bundle patch, zero file edits |
+| | 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 | ✅ Paste it — the turn auto-routes to the vision chain and auto-mounts the tools | 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 | 86 | 162 |
+| Install | One command | One command (npm) |
 
-Want the pixel loop instead? All five routes converge on the same `vision_*` tool family — grounding, crop, pixel diff, colors, OCR, SVG trace, cutout, screenshots — so you can mix and match as you like.
+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.)
 
 ## Quick start
 
+Recommended for normal npm/npx installs (the same launch style used by the DSH README):
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router
+npx @deepseek-ai/dsh web
+```
+
+If you run DeepSeek Harness from a source checkout with pnpm, use the workspace script instead — `dsh` is not necessarily on your shell `PATH`:
+
 ```sh
-dsh plugin --profile web add dsh-vision-router
+cd deepseek-harness
+pnpm dsh plugin --profile web add dsh-vision-router
+pnpm dsh web
 ```
 
-Restart `dsh web` — done. Zero configuration:
+If you already installed the DSH CLI globally and `dsh` is on `PATH`, the shorter `dsh ...` form works too. Restart a long-lived Web profile after installation — done. Zero configuration:
 
-- the plugin's bundle patch mounts the row only: the official DeepSeek route stays untouched, and image turns use the "自动识图" wrapper entry in the picker (or the extra wrappers you configure);
+- the plugin's bundle patch mounts the row, adds the admission wrapper and relaxes attachment limits to 20 MB / 100 MP — pure-additive, it never touches the core rows; whether the official DeepSeek route is taken over is decided by the optional stealth setting (off by default);
 - the default vision chain is the built-in free endpoint;
+- custom/third-party routes (e.g. opencode) gain image input through **Extra vision wrappers**;
 - every setting is editable live in **Settings → Plugins → Plugin config → 视觉路由（自动识图）**.
 
 Then just paste an image into a conversation. The agent mounts the vision tools automatically and looks at it through `vision_describe` (and friends) — multi-step if needed.
@@ -119,6 +137,7 @@ All ten deep tools mount automatically on image turns (`autoActivateOnImage`); t
 | `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_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).
 
@@ -135,6 +154,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_long_screenshot_ocr image="chat-log.png" chunkHeight=1200 overlap=120
 ```
 
 ## Provider fallback chain
@@ -151,7 +171,9 @@ Failures are classified (region / tos / quota / rate-limit / context / network)
 
 ## Stealth mode
 
-**Stealth mode is opt-in.** The plugin never disables the official `llm-deepseek` row by itself (issue #34). To take over the official `deepseek-official` route — the model picker looks exactly like stock, but each entry is the auto-vision wrapper that declares image input and delegates text turns to a rebuilt native DeepSeek adapter — add the disable to YOUR profile patch layer:
+Stealth mode is **off by default** (explicit opt-in since issue #34): with it off, the official `deepseek-official` route stays untouched and image turns go through the visible "DeepSeek + 自动识图" wrapper entry in the picker.
+
+With stealth on, the plugin takes over the official `deepseek-official` route: the model picker looks exactly like stock (same DeepSeek group, same model names), but each entry is the auto-vision wrapper that declares image input and delegates text turns to a rebuilt native DeepSeek adapter (same `llm-deepseek` settings section and credentials). Old sessions keep working through the hidden `deepseek-vision` alias. The takeover requires the stock row to be absent — disable it in your profile patch layer (`~/.dsh/profiles/<profile>/cordis.patch.yml`):
 
 ```yaml
 - id: llm-deepseek
@@ -159,16 +181,25 @@ Failures are classified (region / tos / quota / rate-limit / context / network)
   disabled: true
 ```
 
-Without the takeover, the plugin registers the visible "DeepSeek + 自动识图" (`deepseek-vision`) wrapper entry — pick it in the model picker for image turns; for third-party text routes, add them to the settings card's **extra vision wrappers**. Recovery from a broken install is the same one-line override (delete the `disabled` line).
+With the stock row present, the plugin falls back to the visible wrapper entry. Conversely, with stealth off but the stock row still disabled, the plugin performs a keep-alive takeover so the DeepSeek models don't vanish (the settings card explains this); to restore the fully official route, flip the `disabled` above back to `false` and restart.
+
+> Stealth mode **only affects the official DeepSeek route**. Custom/third-party routes like opencode are unrelated — use **Extra vision wrappers** below to give them image input.
+
+## Extra vision wrappers
+
+`wrappedProviders` registers an auto-vision twin for any third-party/custom text route: pick the twin in the model selector and send images; text turns delegate to the original route unchanged. The typical use case is a custom interface such as opencode — it only declares text input, and one wrapper row makes it image-ready. In the settings card, configure it with two dropdowns (provider + model); leaving the model empty wraps every model of that route.
 
 ## Web settings
 
 The Web profile registers a **视觉路由（自动识图）** card under **Settings → Plugins → Plugin config**, styled like the built-in cards. It live-edits:
 
-- switches: whole-turn legacy routing, vision tools, image-block rewriting, stealth;
+- switches: whole-turn legacy routing, vision tools, image-block rewriting, stealth (official DeepSeek route only);
+- **extra vision wrappers**: provider + model dropdowns that register image-capable twin entries for custom routes such as opencode;
 - vision request timeout, wrapper/chain route names;
 - the **vision chain** (one `provider/model` per line, top-down fallback) and the text model;
-- every field shows an "overridden" badge with a one-click reset to the composition default, plus discard/save.
+- every field shows an "overridden" badge with a one-click reset to the composition default, plus discard/save;
+- a **Test connection** button probes the first vision provider and reports latency inline;
+- artifact-producing tools render dedicated call cards with result facts and open-file buttons.
 
 <p align="center">
   <img src="assets/vision-settings.png" width="72%" alt="The vision-router card in Settings > Plugins > Plugin config." />
@@ -184,12 +215,13 @@ Everything is optional; defaults work out of the box. Edit via the Web card or a
 |---|---|---|
 | `provider` / `model` | `vision-http` / `ovh/Qwen2.5-VL-72B-Instruct` | shorthand chain (adapter-backed provider + model) |
 | `fallbacks` | `[]` | backup models for the shorthand provider |
-| `providers` | `[]` | multi-provider chain `{ provider, model, fallbacks[] }`, tried in order; wins over the shorthand |
+| `providers` | built-in free `vision-http` pair | multi-provider chain `{ provider, model, fallbacks[] }`, tried in order; wins over the shorthand. The first row ships as the built-in free model |
 | `httpProviders` | built-in OVH entry | direct OpenAI-compatible endpoints `{ name, baseURL, model, apiKeyEnv, maxTokens }` |
+| `wrappedProviders` | `[{ provider: 'deepseek-official', models: [] }]` | extra text routes to wrap as image-capable twins: `{ provider, models[] }` — registers an auto-vision twin for any custom/third-party route (e.g. opencode); in the card, provider + model dropdowns, empty model = wrap all. The pre-filled deepseek-official row marks the built-in wrapper and is a no-op; changes apply live |
 | `routing` | `false` | legacy whole-turn chain routing (one-shot answer). `false` = tools-first flow (recommended) |
 | `reverseRouting` | `true` | with `routing: true`, route text turns back to `textProvider` |
 | `wrapperRoute` / `chainRoute` | `deepseek-vision` / `vision-chain` | admission wrapper route name / fallback chain route name (empty disables) |
-| `stealth` | `true` | take over the official `deepseek-official` route |
+| `stealth` | `false` | take over the official `deepseek-official` route (official row only; custom routes use `wrappedProviders`) |
 | `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 |
 | `rewriteImages` | `true` | rewrite image blocks in the model input (cached description or tool-hint marker); the UI log keeps images |
@@ -201,7 +233,7 @@ Everything is optional; defaults work out of the box. Edit via the Web card or a
 
 ## Requirements
 
-- DeepSeek Harness with a Web profile and `pnpm` available to `dsh plugin`.
+- DeepSeek Harness Web profile. Normal installs can use `npx @deepseek-ai/dsh ...`; source checkouts use `pnpm dsh ...`. A bare `dsh ...` command only works when the CLI is already on your shell `PATH`.
 - Node ≥ 22 (host side).
 - No API key for the default free chain; a credential reference (`apiKeyEnv`) only for paid `httpProviders`.
 - Chrome / Chromium / Edge only for `vision_html_screenshot`; every other tool works without a browser.
@@ -211,9 +243,18 @@ Everything is optional; defaults work out of the box. Edit via the Web card or a
 
 ### Install
 
+Normal npm/npx install:
+
 ```sh
-dsh plugin --profile web add dsh-vision-router
-dsh --profile web --dump-config | grep vision-router   # one row, mounted by the bundle patch
+npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router
+npx @deepseek-ai/dsh --profile web --dump-config | grep vision-router
+```
+
+From a DeepSeek Harness source checkout:
+
+```sh
+pnpm dsh plugin --profile web add dsh-vision-router
+pnpm dsh --profile web --dump-config | grep vision-router
 ```
 
 Restart a long-lived Web profile. The host discovers the browser bundle through `dsh.client` at startup.
@@ -230,15 +271,44 @@ Set it back to `false` to re-enable. Unloading removes the wrapper routes, tools
 ### Upgrade
 
 ```sh
-dsh plugin --profile web update dsh-vision-router
+# normal npm/npx install
+npx @deepseek-ai/dsh plugin --profile web update dsh-vision-router
+
+# DeepSeek Harness source checkout
+pnpm dsh plugin --profile web update dsh-vision-router
 ```
 
 Settings live in the profile's settings provider and survive upgrades.
 
+> **Upgrading from a pre-bundle-patch install (v0.x):** the package now mounts
+> itself through its own bundle patch, so a leftover manual row in
+> `~/.dsh/profiles/<profile>/cordis.patch.yml` duplicates it and `dsh web`
+> fails at startup with `duplicate loader entry id: vision-router`. Delete the
+> old block:
+>
+> ```yaml
+> - insert:            # remove this whole block
+>     - id: vision-router
+>       name: dsh-vision-router
+> ```
+>
+> To keep custom settings, replace it with a plain by-id override (no
+> `insert`):
+>
+> ```yaml
+> - id: vision-router
+>   config:
+>     # your overrides …
+> ```
+
 ### Uninstall
 
 ```sh
-dsh plugin --profile web remove dsh-vision-router
+# normal npm/npx install
+npx @deepseek-ai/dsh plugin --profile web remove dsh-vision-router
+
+# DeepSeek Harness source checkout
+pnpm dsh plugin --profile web remove dsh-vision-router
 ```
 
 This removes the dependency and the bundle layer. If you disabled the stock DeepSeek row manually, re-enable it in your profile patch.

package/README.zh.md

@@ -10,8 +10,8 @@
 
 <p align="center">
   <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="awesome · DSH plugin" /></a>
-  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.0.0"><img src="https://img.shields.io/badge/release-v1.0.0-5B4CF0?style=flat-square" alt="Release v1.0.0" /></a>
-  <a href="tests"><img src="https://img.shields.io/badge/verified-86%20tests-2EA44F?style=flat-square" alt="Verified: 86 tests" /></a>
+  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.1.1"><img src="https://img.shields.io/badge/release-v1.1.1-5B4CF0?style=flat-square" alt="Release v1.1.1" /></a>
+  <a href="tests"><img src="https://img.shields.io/badge/verified-101%20tests-2EA44F?style=flat-square" alt="Verified: 101 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" />
@@ -20,6 +20,11 @@
 
 <p align="center"><a href="README.md">English</a> · 中文</p>
 
+> [!WARNING]
+> 📌 **公告（v1.1.1）**
+>
+> 现在安装后会**自动包装 DSH 已有模型**：纯文本路由自动获得粘贴即用的识图入口，原生多模态模型保留原图直传，仅在需要精确定位 / OCR / 像素验证时按需使用 Vision Router 工具。另修复 Windows sharp/libvips 启动冲突，并补齐 npm/npx 与源码 pnpm 两套安装/升级指引。
+
 <p align="center">
   <img src="assets/vision-demo.gif" width="640" alt="演示：粘贴图片，Agent 用 vision_ground / vision_crop / vision_pixel_diff 定位发送按钮并给出坐标" />
 </p>
@@ -28,7 +33,7 @@
 
 大多数 DSH 视觉插件把图片“翻译”成一段文字描述再喂给 DeepSeek——有损、一次性、看不见像素。本插件把**原图像素留在视觉模型侧**、把推理留在 DeepSeek 侧，并把“看图”变成一次**普通的工具调用**：
 
-- **一条命令安装，纯增量。** 包自带组合补丁（`dsh.bundle.patch`）：`dsh plugin add` 只挂载插件行，不禁用、不覆写任何核心行（issue #34）。
+- **一条命令安装。** 包自带组合补丁（`dsh.bundle.patch`）：`dsh plugin add` 自动完成插件行挂载、准入包装与附件限制放宽——不用手改任何文件。是否接管官方 DeepSeek 路由由「隐身模式」开关决定（默认关）。
 - **默认免费。** 视觉链内置 OVHcloud 匿名端点（`Qwen2.5-VL-72B-Instruct`，免注册、免 Key，每 IP 2 次/分钟）。付费链路（OpenRouter、Pi-AI 供应商、任意 OpenAI 兼容直连端点）是可选升级。
 - **无 Python。** 整条管线——缩放、定位、裁剪、像素对比、取色、OCR、SVG 矢量化、抠图、HTML 截图——全部基于 sharp / potrace / tesseract / 系统 Chrome。
 - **可连续多步看图。** 图片轮 = 调用工具的文本轮：`vision_ground` → `vision_crop` → `vision_describe` → `vision_pixel_diff` → 修复 → 再截图，Agent 可以一直迭代到任务完成。
@@ -37,30 +42,43 @@
 
 ## 对比同类插件
 
-大多数 DSH 视觉插件是把图片转成**文字描述**再喂给 DeepSeek。本插件让视觉模型**直接读原图像素**，内置**免费视觉链**，并把看图变成一次**普通工具调用**——粘贴图片即可用，可连续多步做到完成为止。
+最接近的同类是 [@anionex/dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit)（Anionex），它是知名 `agent-vision-toolkit` 系列的 DSH 原生版。两者都提供 `vision-tools` 技能和一组像素级工具，区别在理念：**零配置粘贴即用** vs **Agent 主导的视觉工程**：
 
-| | 手动切换模型 | 描述桥（dsh-vision-sidecar · dsh-vision-proxy · dsh-vision · dsh-tool-vision） | @anionex/dsh-vision-toolkit | modlens | dsh-vision-router |
-|---|---|---|---|---|---|
-| 开箱即用、免 Key | ❌ | 部分 | ❌ 远程工具需自备 Key | ❌ 需自备 Key | ✅ 内置免 Key 视觉链 |
-| 原图像素保真 | ✅ 切换后 | ❌ 只有文字描述 | ✅ | ✅ 结构化证据 | ✅ 原图像素 + 像素工具 |
-| 免手动逐轮切换 | ❌ | ✅ | ✅ | ✅ | ✅ 自动挂载工具 + 隐身路由 |
-| 日常模型不受影响 | ❌ 整会话切换 | ✅ | ✅ | ✅ | ✅ DeepSeek 始终是大脑 |
-| 多供应商降级 + 分类报错 | ❌ | ❌ | 部分 | — | ✅ 降级链 + 429 退避 + 自动压缩 |
-| 无需 Python | ✅ | ✅ | ❌ Python 3.11+ | ✅ | ✅ 纯 Node |
-| 一条命令安装 | — | — | ✅ | ✅ | ✅ bundle 补丁零手改 |
+| | 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 自动化） |
+| 测试 | 86 | 162 |
+| 安装 | 一条命令 | 一条命令（npm） |
 
-想要像素闭环？五条路线最终都落在同一套 `vision_*` 工具族上——定位、裁剪、像素对比、取色、OCR、矢量化、抠图、截图——按需混用即可。
+两者都是 MIT 许可、一条命令安装。想要图片**粘贴即用**、零配置就选本插件；需要 Headless 部署或更丰富的案例库，可以看 @anionex/dsh-vision-toolkit。（功能对比以其 README 2026-08 状态为准。）
 
 ## 快速开始
 
+普通 npm / npx 安装方式推荐这样用（与 DSH 官方 README 的启动方式一致）：
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router
+npx @deepseek-ai/dsh web
+```
+
+如果你是从 DeepSeek Harness 源码仓库通过 pnpm 运行，`dsh` 不一定在系统 `PATH` 里，请改用工作区脚本：
+
 ```sh
-dsh plugin --profile web add dsh-vision-router
+cd deepseek-harness
+pnpm dsh plugin --profile web add dsh-vision-router
+pnpm dsh web
 ```
 
-重启 `dsh web`——完成，零配置：
+如果你已经全局安装 DSH CLI，并且终端里能直接执行 `dsh`，也可以继续使用较短的 `dsh ...` 写法。长期运行的 Web profile 安装后重启——完成，零配置：
 
-- 插件的 bundle 补丁只挂载插件行：官方 DeepSeek 路由保持原样，图片入口使用选择器里的「自动识图」包装条目（或你在设置里配置的额外包装）；
+- 插件的 bundle 补丁自动挂载插件行、挂上准入包装并放宽附件限制到 20MB / 1 亿像素——纯增量、不碰核心行；是否接管官方 DeepSeek 路由由「隐身模式」开关决定（默认关）；
 - 默认视觉链就是内置免费端点；
+- opencode 等自定义/第三方路由用「额外识图包装」获得发图能力；
 - 全部配置可在 **设置 → 插件 → 插件配置 → 视觉路由（自动识图）** 实时修改。
 
 然后直接往对话里贴一张图。Agent 自动挂载视觉工具，通过 `vision_describe`（以及其余 8 个工具）看图，需要时连续多步。
@@ -119,6 +137,7 @@ Agent 仅根据参考图复刻 UI，再用 `vision_pixel_diff` 验证最终结
 | `vision_trace` | SVG 矢量化（potrace 分色；图标/logo） | SVG |
 | `vision_extract_foreground` | 边界洪泛抠图（纯色背景） | 透明 PNG |
 | `vision_html_screenshot` | 给本地 HTML 文件截图（无头系统 Chrome） | PNG |
+| `vision_long_screenshot_ocr` | 长截图转写：重叠分片，tesseract 优先 / 视觉模型回退，按序拼接 Markdown | 分片 PNG + Markdown + manifest |
 
 图片格式按**魔数识别**，无扩展名的内容寻址附件文件也能直接用（不用再复制成 `.png`）。
 
@@ -135,6 +154,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_long_screenshot_ocr image="chat-log.png" chunkHeight=1200 overlap=120
 ```
 
 ## 供应商降级链
@@ -151,7 +171,9 @@ vision_html_screenshot source="page.html" width=1200 height=720
 
 ## 隐身模式
 
-**隐身模式改为显式可选。** 插件永远不会自己禁用官方 `llm-deepseek` 行（issue #34）。想接管官方 `deepseek-official` 路由——模型选择器看起来和原版完全一样，但每个条目背后都是声明了图片输入的自动识图包装，文字轮交给插件重建的原生 DeepSeek 适配器——在你自己的 profile 补丁层加上：
+隐身模式默认**关闭**（issue #34 起显式 opt-in）：关闭时官方 `deepseek-official` 路由原样保留，发图走选择器里可见的「DeepSeek + 自动识图」包装入口。
+
+开启隐身模式后，插件接管官方 `deepseek-official` 路由：模型选择器看起来和原版完全一样（同一个 DeepSeek 组、同样的模型名），但每个条目背后都是声明了图片输入的自动识图包装；文字轮交给插件重建的原生 DeepSeek 适配器（读取同一个 `llm-deepseek` 设置段与凭据）。老会话通过隐藏的 `deepseek-vision` 别名继续工作。接管的前提是官方行不在场——在你的 profile 补丁层（`~/.dsh/profiles/<profile>/cordis.patch.yml`）禁用即可：
 
 ```yaml
 - id: llm-deepseek
@@ -159,16 +181,25 @@ vision_html_screenshot source="page.html" width=1200 height=720
   disabled: true
 ```
 
-不接管时，插件注册选择器里可见的「DeepSeek + 自动识图」（`deepseek-vision`）包装入口——发图前选它即可；第三方文本路由则在设置卡片的「额外识图包装」里添加。安装出问题时删掉 `disabled` 行即可恢复。
+官方行在场时，插件自动回退为可见包装入口。反过来，隐身模式关闭但官方行仍被禁用时，插件会做 keep-alive 兜底接管，保住 DeepSeek 模型（设置卡片会给出提示）；想完全恢复官方原生行，把上面的 `disabled` 改回 `false` 再重启即可。
+
+> 隐身模式**只作用于官方 DeepSeek 路由**。opencode 等自定义/第三方文本路由与隐身模式无关——用「额外识图包装」让它们支持发图。
+
+## 额外识图包装
+
+`wrappedProviders` 给任意第三方/自定义文本路由注册「自动识图」孪生条目：模型选择器里选中它就能发图，文字轮原样交给原路由处理。典型用法是 opencode 等接入的自定义接口——它们默认只声明文本输入，加一行包装即可直接发图。设置卡片里用两个下拉（provider + 模型）配置；模型留空 = 包装该路由的全部模型，同一 provider 要包装多个模型就添加多行。
 
 ## Web 设置
 
 Web 配置页在 **设置 → 插件 → 插件配置** 下注册「视觉路由（自动识图）」卡片，样式与内置卡片一致，可实时修改：
 
-- 开关：整轮自动路由（旧模式）、识图工具、图片块改写、隐身模式；
+- 开关：整轮自动路由（旧模式）、识图工具、图片块改写、隐身模式（仅官方 DeepSeek 路由）；
+- **额外识图包装**：provider + 模型双下拉，给 opencode 等自定义路由注册可发图的孪生条目；
 - 视觉请求超时、包装/链路由名；
 - **视觉模型链**（每行一个 `provider/model`，自上而下降级）与文本模型；
-- 每个字段都有「已覆盖」徽标与一键恢复组合默认，以及放弃/保存。
+- 每个字段都有「已覆盖」徽标与一键恢复组合默认，以及放弃/保存；
+- 「测试连接」按钮探测第一个视觉提供方并内联显示延迟/失败原因；
+- 产出制品的工具在对话里渲染专用调用卡（关键字段 + 打开文件按钮）。
 
 <p align="center">
   <img src="assets/vision-settings.png" width="72%" alt="设置 → 插件 → 插件配置 里的视觉路由卡片。" />
@@ -184,12 +215,13 @@ Web 配置页在 **设置 → 插件 → 插件配置** 下注册「视觉路由
 |---|---|---|
 | `provider` / `model` | `vision-http` / `ovh/Qwen2.5-VL-72B-Instruct` | 简写链路（有适配器的供应商 + 模型） |
 | `fallbacks` | `[]` | 简写供应商的备用模型 |
-| `providers` | `[]` | 多供应商链路 `{ provider, model, fallbacks[] }`，按序尝试；优先于简写形式 |
+| `providers` | 内置免费 `vision-http` 条目 | 多供应商链路 `{ provider, model, fallbacks[] }`，按序尝试；优先于简写形式。第一行开箱预置内置免费模型 |
 | `httpProviders` | 内置 OVH 条目 | OpenAI 兼容直连端点 `{ name, baseURL, model, apiKeyEnv, maxTokens }` |
+| `wrappedProviders` | `[{ provider: 'deepseek-official', models: [] }]` | 额外识图包装：`{ provider, models[] }`，给 opencode 等任意第三方/自定义文本路由注册可发图的孪生条目（卡片里 provider + 模型双下拉；模型留空 = 包装全部）。预置的 deepseek-official 条目标记内置包装、无副作用；改动即时生效 |
 | `routing` | `false` | 旧版整轮链路由（一次性整轮回答）。`false` = 工具优先流程（推荐） |
 | `reverseRouting` | `true` | 开启 `routing` 时，文字轮路由回 `textProvider` |
 | `wrapperRoute` / `chainRoute` | `deepseek-vision` / `vision-chain` | 准入包装路由名 / 降级链路由名（置空关闭） |
-| `stealth` | `true` | 接管官方 `deepseek-official` 路由 |
+| `stealth` | `false` | 接管官方 `deepseek-official` 路由（仅官方行；自定义路由用 `wrappedProviders`） |
 | `textProvider` | `deepseek-official` / `deepseek-v4-pro` | 负责思考的模型（你的日常模型） |
 | `tool` / `progressiveTools` / `autoActivateOnImage` | `true` ×3 | 视觉工具开关 / 渐进式挂载 / 图片轮自动挂载 |
 | `rewriteImages` | `true` | 模型输入层改写图片块（缓存描述或工具提示标记）；界面日志保留图片 |
@@ -201,7 +233,7 @@ Web 配置页在 **设置 → 插件 → 插件配置** 下注册「视觉路由
 
 ## 环境要求
 
-- DeepSeek Harness 的 Web profile，且 `dsh plugin` 可用 `pnpm`。
+- DeepSeek Harness 的 Web profile。普通安装可用 `npx @deepseek-ai/dsh ...`；从源码仓库运行时用 `pnpm dsh ...`。只有 CLI 已经进入系统 `PATH` 时才能直接写 `dsh ...`。
 - Node ≥ 22（宿主侧）。
 - 默认免费链路无需 API Key；付费 `httpProviders` 只需一个凭据引用（`apiKeyEnv`）。
 - `vision_html_screenshot` 才需要 Chrome / Chromium / Edge；其余工具无浏览器也能用。
@@ -211,9 +243,18 @@ Web 配置页在 **设置 → 插件 → 插件配置** 下注册「视觉路由
 
 ### 安装
 
+普通 npm / npx 安装：
+
 ```sh
-dsh plugin --profile web add dsh-vision-router
-dsh --profile web --dump-config | grep vision-router   # 一行，由 bundle 补丁挂载
+npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router
+npx @deepseek-ai/dsh --profile web --dump-config | grep vision-router
+```
+
+从 DeepSeek Harness 源码仓库运行：
+
+```sh
+pnpm dsh plugin --profile web add dsh-vision-router
+pnpm dsh --profile web --dump-config | grep vision-router
 ```
 
 长期运行的 Web profile 需重启。宿主在启动时通过 `dsh.client` 声明发现浏览器端包。
@@ -230,15 +271,42 @@ dsh --profile web --dump-config | grep vision-router   # 一行，由 bundle 补
 ### 升级
 
 ```sh
-dsh plugin --profile web update dsh-vision-router
+# 普通 npm / npx 安装
+npx @deepseek-ai/dsh plugin --profile web update dsh-vision-router
+
+# DeepSeek Harness 源码仓库
+pnpm dsh plugin --profile web update dsh-vision-router
 ```
 
 设置存放在 profile 的设置提供方里，升级不丢失。
 
+> **从 bundle 补丁之前（v0.x）升级：** 现在插件由自带的 bundle 补丁自动挂载，
+> 若 `~/.dsh/profiles/<profile>/cordis.patch.yml` 里还残留旧版手动行，会与之
+> 重复，`dsh web` 启动即报 `duplicate loader entry id: vision-router`。删除
+> 旧块：
+>
+> ```yaml
+> - insert:            # 删除整块
+>     - id: vision-router
+>       name: dsh-vision-router
+> ```
+>
+> 若要保留自定义配置，改为不带 insert 的按 id 覆盖行：
+>
+> ```yaml
+> - id: vision-router
+>   config:
+>     # 你的配置…
+> ```
+
 ### 卸载
 
 ```sh
-dsh plugin --profile web remove dsh-vision-router
+# 普通 npm / npx 安装
+npx @deepseek-ai/dsh plugin --profile web remove dsh-vision-router
+
+# DeepSeek Harness 源码仓库
+pnpm dsh plugin --profile web remove dsh-vision-router
 ```
 
 同时移除依赖与 bundle 层。若你曾手动禁用官方 DeepSeek 行，记得在 profile 补丁里恢复。

package/cordis.patch.yml

@@ -4,13 +4,19 @@
 # without any manual cordis.patch.yml edits. Later layers (the profile's own
 # cordis.patch.yml, --patch overlays) override these rows by id.
 
-# 纯增量安装：只挂载插件行，不改动任何核心行。
-# 官方 llm-deepseek 行保持原样（安装即安全，无隐式接管）；
-# 图片入口使用选择器里插件注册的「自动识图」包装条目（deepseek-vision），
-# 或把第三方文本路由写入设置卡片的「额外识图包装」。
-# 想要隐身模式（接管 deepseek-official、选择器看起来和原来一模一样）时，
-# 由用户在自己的 profile cordis.patch.yml 里显式禁用官方行——插件永不
-# 自动替用户禁用核心行（issue #34）。
+# 纯增量补丁（issue #34）：不碰核心行。官方 llm-deepseek 行保持原样，插件
+# 挂载后是否接管官方 deepseek-official 路由由设置里的「隐身模式」开关决定
+# （默认关；开启后需自行在 profile 补丁层禁用 llm-deepseek 行）。
+
+# 挂载插件行。配置全部可选（默认即内置免费视觉端点 + 工具优先的图片流程），
+# 可在 Web 设置 > 插件 > 插件配置 的「视觉路由」卡片里实时修改。
 - insert:
     - id: vision-router
       name: dsh-vision-router
+
+# 放宽附件图片限制（部署默认 5MB / 4000 万像素 → 20MB / 1 亿像素），
+# 大尺寸设计稿/扫描图可过审。字段可选，不需要可在 profile 补丁层覆写。
+- id: attachment-local
+  config:
+    maxImageBytes: 20971520
+    maxImagePixels: 100000000