Skip to content
Back to search

dsh-vision-router

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ysr666/dsh-vision-router with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ysr666/dsh-vision-router'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ysr666--dsh-vision-router/badge.svg)](/listings/ysr666--dsh-vision-router)

HTML

<a href="/listings/ysr666--dsh-vision-router"><img src="/api/listings/ysr666--dsh-vision-router/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install the plugin

For normal npm/npx installs, installation is a single command:

npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router

> [!IMPORTANT] > **Which profile?** Install into an **existing profile that already serves the Web UI**: > > - Web DSH: `--profile web` (default data directory `~/.dsh`); > - the official DeepSeek Harness desktop app: `--profile desktop` (same `~/.dsh` data directory; reload the plugin or restart the app afterwards); > - Oh-DSH Desktop: its data directory is `~/.ohdsh`, see [Oh-DSH Desktop](#oh-dsh-desktop) below. > > `dsh plugin add` only adds the plugin to the profile you name. A **brand-new** profile contains just `@deepseek-ai/dsh-base`, and `dsh web` never binds a port in that state (no Web surface). Install into an existing profile, or give the new profile a Web surface first.

> [!WARNING] > If this profile already loads community plugins manually through `cordis.patch.yml`, do **not** mix that legacy setup with `dsh plugin add` / `dsh plugin list`: current DSH CLI behavior can also append bundle-patch dependencies to `dsh.profile.bundles`, causing those plugins to register twice. Migrate the existing manual plugin rows to bundle-managed loading first, or keep using the manual installation path. See [deepseek-harness discussion #2889](https://github.com/deepseek-ai/deepseek-harness/discussions/2889).

> [!NOTE] > Third-party `dsh-web-plugin-manager` / `dshpm` **v0.4.2+** is also compatible: its quality gate now correctly allows `@deepseek-ai/schemastery` as a runtime dependency. The official DSH CLI above remains the recommended install path.

If you run DeepSeek Harness from a source checkout with pnpm, use the workspace script instead — `dsh` is not necessarily on your shell `PATH`:

cd deepseek-harness
pnpm dsh plugin --profile web add dsh-vision-router

If you already installed the DSH CLI globally and `dsh` is on `PATH`, the shorter `dsh ...` form works too. After installation, start or reload DSH Web as you normally do.

> [!NOTE] > If you install the plugin **into a Web process that was already running long-term**, let that DSH Web process reload once so the plugin bundle itself is discovered. After the plugin is loaded, adding/removing models or changing wrapper scope **hot-updates without further DSH restarts**.

2. Pick your normal model, then enable “👁 Vision” when needed

The stock model selector in the lower-right corner still chooses your **brain/conversation model** — DeepSeek, Qwen, or any other ordinary route. Vision Router’s generated “+ Auto Vision” wrappers remain real Host routes for image admission, but are hidden from the stock picker and `/model` when ownership can be established safely.

When you need image input, explicitly click **“👁 Vision”** beside the composer:

- `👁 Vision`: the ordinary model is active and Vision is off; - `👁 Vision ✓`: Vision Router has switched the session to that model’s internal vision wrapper; - the mode persists across sends and **does not auto-reset**; - turning it off switches back to the same ordinary model; choosing a different ordinary model turns Vision off; - changing only reasoning effort keeps Vision on.

> [!IMPORTANT] > **Pasting or uploading an image does not enable Vision automatically. Before sending an image, make sure the control shows `👁 Vision ✓`.** > > The real wrapper route is still present underneath to satisfy DSH image admission. Hiding is presentation-only and fails open: if the browser cannot confidently prove a route belongs to Vision Router, that route remains visible rather than risking hiding a third-party provider.

3. Paste or upload the image

With “👁 Vision” enabled, paste or upload an image normally. By default the complete vision tool schema is stable from session start, so the agent can immediately use `vision_describe`, `vision_ground`, `vision_crop`, and the rest across multiple steps when needed.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 646 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/hero.svg" width="100%" alt="DSH Vision Router — eyes for text-only DeepSeek Harness agents" />
  3. </p>
  4. <h1 align="center">dsh-vision-router</h1>
  5. <p align="center"><strong>Turn vision on when you need it — eyes for text-only agents on DeepSeek Harness. Free out of the box, no key, no Python, one command.</strong></p>
  6. <p align="center">DeepSeek keeps thinking; the built-in free vision chain and fourteen deep tools do the seeing. When an image matters, enable the composer’s “👁 Vision” control and use image turns like ordinary tool-calling turns — grounded, measurable, repeatable.</p>
  7. <p align="center">
  8. <a href="https://github.com/zp-home/dsh-recommend"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fzp-home%2Fdsh-recommend%2Fmain%2Fdata%2Fbadges%2Fysr666__dsh-vision-router.certified.json&amp;style=flat-square" alt="dsh-recommend 🏅 certified" /></a>
  9. <a href="https://www.dshbase.com/plugins/dsh-vision-router/"><img src="https://img.shields.io/badge/dshbase-install--tested-2EA44F?style=flat-square" alt="dshbase install-tested" /></a>
  10. <a href="https://github.com/SoberReport-AI/DeepGuard/blob/main/reports/dsh-vision-router/2.0.1/39c8f2b2d69aa398418fd6c8ab40b691a92a1a3d.json"><img src="https://img.shields.io/badge/DeepGuard-audit%20clean-2EA44F?style=flat-square" alt="DeepGuard audit clean" /></a>
  11. </p>
  12. <p align="center"><sub>DeepGuard badge links to a historical v2.0.1 audit; it does not certify current releases.</sub></p>
  13. <p align="center">English · <a href="README.zh.md">中文</a></p>
  14. > [!CAUTION]
  15. > **Data leaves your machine by default.** When a cloud vision model is used, Vision Router sends the image (or a derived crop), the vision prompt and related request metadata to that provider. A fresh install has an anonymous OVHcloud vision fallback enabled, so "free" and "no key" do **not** mean offline. Do not use the cloud chain for confidential, regulated or classified material. See [Data flow and strict local-only use](#data-flow-and-strict-local-only-use).
  16. > [!WARNING]
  17. > **v3.4.0 minor release — confirm publication through GitHub Releases/npm:** Local OCR is now strictly **opt-in**. In Settings → Local & device → Optional local OCR, a working system Tesseract with `chi_sim` + `eng` is reused without another installation; otherwise you can install/remove a plugin-owned, SHA-verified Tesseract.js/WASM engine and Chinese/English models on demand. PP-OCRv6/ncnn can be installed or removed only from a user-provided, SHA-verified offline bundle on supported macOS ARM64/Windows x64; **public native binary/model redistribution remains NOT cleared**, with no automatic download. Most users need install neither engine: the existing consent/policy-governed vision-model fallback remains unchanged, including cloud image egress unless strict local-only is enabled. DSH >=0.2.1-rc.5 <0.3.0-0 and Node.js >=24.9.0 remain required. No automatic profile migration. Back up your profile, run read-only `doctor --upgrade-preflight`, and retain v3.3.0 for rollback. See [v3.4.0 release notes](docs/releases/v3.4.0.md).
  18. ## Start here
  19. **1. Install in an existing DSH Web profile:**
  20. ```sh
  21. npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router
  22. ```
  23. **2. Keep your usual chat model** and click **👁 Vision** beside the composer; check for **👁 Vision ✓**.
  24. **3. Paste or upload an image** and ask the agent what to inspect. The built-in keyless cloud fallback is available out of the box.
  25. Using Desktop? Change `--profile web` to `--profile desktop` and reload the app. For Oh-DSH and manual setups, follow the [complete installation guide](#quick-start).
  26. [Full quick start](#quick-start) · [What it can do](#highlights) · [Data flow and local-only use](#data-flow-and-strict-local-only-use)
  27. <p align="center">
  28. <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" />
  29. </p>
  30. ## Try it on real images
  31. - **Understand a screenshot:** “What does this error dialog mean? Read the exact message.”
  32. - **Find a UI element:** “Where is the Save button in this screenshot? Give me its position.”
  33. - **Compare two designs:** “Compare my page to this reference. What should I fix next?” Use `vision_pixel_diff` to measure changes after each iteration.
  34. - **Read and inspect a long image:** “Extract the relevant text, then crop the unclear part to double-check it.”
  35. These are ordinary chat requests: your normal model reasons through the task and calls vision tools as needed. [See the tool list](#tools) or [configure your own/local vision backend](#configuration).
  36. ## Contents
  37. - [Try it on real images](#try-it-on-real-images)
  38. - [Highlights](#highlights)
  39. - [How it works](#how-it-works)
  40. - [Tools](#tools)
  41. - [Quick start](#quick-start)
  42. - [Data flow and strict local-only use](#data-flow-and-strict-local-only-use)
  43. - [Configure your own vision models](#configure-your-own-vision-models)
  44. - [Why this exists](#why-this-exists)
  45. - [How it compares](#how-it-compares)
  46. - [Configuration](#configuration)
  47. - [Install and lifecycle](#install-and-lifecycle)
  48. - [Troubleshooting](#troubleshooting)
  49. - [Design lineage](#design-lineage)
  50. - [Acknowledgements](#acknowledgements)
  51. - [Release notes and community](#release-notes-and-community)
  52. ## Highlights
  53. - **Capability-aware Auto routing.** Keep configured order for deterministic control, or explicitly enable Auto to prioritize already-configured models using measured capability evidence. Auto never infers capability from model names, and enabling Auto alone does not start benchmarks.
  54. - **Verifiable model profiling.** Exact Test Vision sends one request to one exact model; Quick and Full benchmark OCR / general / structured / document / grounding capabilities. Background profiling is separately authorized and yields to real foreground vision work.
  55. - **Original pixels, real answers.** The vision chain reads the image at original resolution (auto-downscaled only to protect latency/quota); the agent's question travels with the image, so answers are about *your* question, not a generic description.
  56. - **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.
  57. - **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.
  58. - **A verifiable pixel loop.** Reference → `vision_html_screenshot` → `vision_pixel_diff` (ratio + worst 8×8-grid regions) → fix → repeat until the mismatch converges. UI restoration becomes measurable instead of eyeballed.
  59. - **Stable tool schema.** All fourteen deep tools register globally at startup by default, avoiding a mid-conversation tool-list expansion that can invalidate long-context KV/prefix caches. Individual Agents see them only while their conversation has Vision enabled. `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).
  60. - **Selective proxy.** Only the configured vision provider hosts go through your local proxy; DeepSeek stays direct.
  61. ### Pixel loop in practice
  62. [![Reference design and final agent rebuild, verified with vision_pixel_diff at 2.54% final difference.](https://raw.githubusercontent.com/ysr666/dsh-vision-router/main/assets/pixel-loop.png)](https://raw.githubusercontent.com/ysr666/dsh-vision-router/main/assets/pixel-loop.png)
  63. <p align="center"><sub>Click the image to open the full-resolution original.</sub></p>
  64. The agent rebuilt the UI from the reference image, then verified the final result with `vision_pixel_diff`: **2.54% final diff** (32,939 / 1,296,000 differing pixels, threshold 16/channel).
  65. ## How it works
  66. <p align="center">
  67. <img src="assets/how-it-works.svg" width="100%" alt="How DSH Vision Router keeps DeepSeek as the brain and vision tools as the eyes." />
  68. </p>
  69. The vision model is **only the eyes**; DeepSeek is **always the brain**. An image turn is never hijacked by a one-shot vision answer — the agent drives the tools itself and can keep operating on the image across as many steps as the task needs.
  70. ## Tools
  71. Default `progressiveTools: false`: all fourteen deep tools are registered at startup. **Registration does not grant access in every conversation**: turn **Vision ON** in the current chat to make them visible and callable by its Agent. While Vision is OFF, that Agent cannot use `vision_colors`, `vision_ocr`, or the other Vision Router tools, even with `tool: true` in Settings. Under this default mode, `vision_activate` is **not registered**.
  72. To opt into progressive mounting, explicitly set `progressiveTools: true` in the profile/composition `cordis.patch.yml`. Only then is `vision_activate` initially exposed to Vision-enabled Sessions; the full tool set mounts upon activation and the `vision-tools` skill is registered. This is a boot-time switch; restart DSH after changing it. Built on sharp / VTracer / tesseract / system Chrome — no Python:
  73. <p align="center">
  74. <img src="assets/vision-tools.svg" width="100%" alt="Eleven image-processing tools available in DSH Vision Router." />
  75. </p>
  76. 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.
  77. | Tool | What it does | Artifact |
  78. |---|---|---|
  79. | `vision_bootstrap` | Optional 1+x structured first visual pass; establishes task-independent evidence before at least one follow-up vision call | — |
  80. | `vision_describe` | Image Q&A / multi-image compare / structured-evidence JSON mode (summary + layout regions + entity inventory + verbatim transcription) | — |
  81. | `vision_materialize` | Copy an authorized attachment into a stable content-addressed workspace handoff file and return absolute + short workspace-relative paths for local OCR/parser fallbacks; no vision/network call | image copy |
  82. | `vision_ground` | Locate a target → **original-pixel box x1/y1/x2/y2** | annotated PNG (optional) |
  83. | `vision_detect` | Numbered inventory of every element of a kind (buttons/inputs/links…) with original-pixel boxes | annotated PNG with numbered boxes |
  84. | `vision_crop` | Crop and zoom into a pixel box | PNG |
  85. | `vision_present` | Publish a generated or edited local image as a durable chat attachment so the user can see it | image attachment |
  86. | `vision_pixel_diff` | Per-pixel comparison: diff ratio + worst 8×8-grid regions | red heatmap PNG + JSON report |
  87. | `vision_colors` | Dominant colors (hex + share) | — |
  88. | `vision_ocr` | Text transcription: configurable default engine (`auto` / local Tesseract / vision model); an explicit per-call engine still wins | — |
  89. | `vision_trace` | SVG vectorization (VTracer posterization; icons/logos) | SVG |
  90. | `vision_extract_foreground` | Cutout via border flood fill (uniform backgrounds) | transparent PNG |
  91. | `vision_html_screenshot` | Screenshot a local HTML file (headless system Chrome); `fullPage: true` captures the whole page and reports `pageHeight` | PNG |
  92. | `vision_screenshot` | **Disabled by default; explicit opt-in required.** Capture the Windows virtual screen, macOS main display, or Linux root display. Windows uses PowerShell CopyFromScreen, macOS uses `screencapture`, and Linux requires ImageMagick `import` or `scrot`; optional `identify=true` tries enabled local recognition backends in order and returns the description with the path | PNG / + description |
  93. | `vision_long_screenshot_ocr` | Long-screenshot transcription: overlapping chunks, tesseract first / vision model fallback, stitched Markdown | chunk PNGs + Markdown + manifest |
  94. Formats are sniffed from magic bytes, so extensionless content-addressed attachment files work everywhere (no `.png` renaming needed).
  95. **Common workflows**
  96. ```text
  97. vision_ground image="ref.png" target="the send button"
  98. vision_detect image="page.png" target="input fields"
  99. vision_crop image="ref.png" region="1067,841,1108,881"
  100. vision_present path="rebuilt.png"
  101. vision_describe paths=["ref.png","impl.png"] question="list the differences" json=true
  102. vision_pixel_diff original="ref.png" rebuilt="screenshot.png"
  103. vision_ocr image="screenshot.png"
  104. vision_colors image="ref.png" top=8
  105. vision_trace image="icon.png" steps=4
  106. vision_extract_foreground image="logo.png"
  107. vision_html_screenshot source="page.html" width=1200 height=720
  108. vision_html_screenshot source="page.html" width=1200 height=720 fullPage=true
  109. vision_long_screenshot_ocr image="chat-log.png" chunkHeight=1200 overlap=120
  110. ```
  111. ## Quick start
  112. ### 1. Install the plugin
  113. For normal npm/npx installs, installation is a single command:
  114. ```sh
  115. npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router
  116. ```
  117. > [!IMPORTANT]
  118. > **Which profile?** Install into an **existing profile that already serves the Web UI**:
  119. >
  120. > - Web DSH: `--profile web` (default data directory `~/.dsh`);
  121. > - the official DeepSeek Harness desktop app: `--profile desktop` (same `~/.dsh` data directory; reload the plugin or restart the app afterwards);
  122. > - Oh-DSH Desktop: its data directory is `~/.ohdsh`, see [Oh-DSH Desktop](#oh-dsh-desktop) below.
  123. >
  124. > `dsh plugin add` only adds the plugin to the profile you name. A **brand-new** profile contains just `@deepseek-ai/dsh-base`, and `dsh web` never binds a port in that state (no Web surface). Install into an existing profile, or give the new profile a Web surface first.
  125. > [!WARNING]
  126. > If this profile already loads community plugins manually through `cordis.patch.yml`, do **not** mix that legacy setup with `dsh plugin add` / `dsh plugin list`: current DSH CLI behavior can also append bundle-patch dependencies to `dsh.profile.bundles`, causing those plugins to register twice. Migrate the existing manual plugin rows to bundle-managed loading first, or keep using the manual installation path. See [deepseek-harness discussion #2889](https://github.com/deepseek-ai/deepseek-harness/discussions/2889).
  127. > [!NOTE]
  128. > Third-party `dsh-web-plugin-manager` / `dshpm` **v0.4.2+** is also compatible: its quality gate now correctly allows `@deepseek-ai/schemastery` as a runtime dependency. The official DSH CLI above remains the recommended install path.
  129. If you run DeepSeek Harness from a source checkout with pnpm, use the workspace script instead — `dsh` is not necessarily on your shell `PATH`:
  130. ```sh
  131. cd deepseek-harness
  132. pnpm dsh plugin --profile web add dsh-vision-router
  133. ```
  134. If you already installed the DSH CLI globally and `dsh` is on `PATH`, the shorter `dsh ...` form works too. After installation, start or reload DSH Web as you normally do.
  135. > [!NOTE]
  136. > If you install the plugin **into a Web process that was already running long-term**, let that DSH Web process reload once so the plugin bundle itself is discovered. After the plugin is loaded, adding/removing models or changing wrapper scope **hot-updates without further DSH restarts**.
  137. ### 2. Pick your normal model, then enable “👁 Vision” when needed
  138. The stock model selector in the lower-right corner still chooses your **brain/conversation model** — DeepSeek, Qwen, or any other ordinary route. Vision Router’s generated “+ Auto Vision” wrappers remain real Host routes for image admission, but are hidden from the stock picker and `/model` when ownership can be established safely.
  139. When you need image input, explicitly click **“👁 Vision”** beside the composer:
  140. - `👁 Vision`: the ordinary model is active and Vision is off;
  141. - `👁 Vision ✓`: Vision Router has switched the session to that model’s internal vision wrapper;
  142. - the mode persists across sends and **does not auto-reset**;
  143. - turning it off switches back to the same ordinary model; choosing a different ordinary model turns Vision off;
  144. - changing only reasoning effort keeps Vision on.
  145. > [!IMPORTANT]
  146. > **Pasting or uploading an image does not enable Vision automatically. Before sending an image, make sure the control shows `👁 Vision ✓`.**
  147. >
  148. > The real wrapper route is still present underneath to satisfy DSH image admission. Hiding is presentation-only and fails open: if the browser cannot confidently prove a route belongs to Vision Router, that route remains visible rather than risking hiding a third-party provider.
  149. ### 3. Paste or upload the image
  150. With “👁 Vision” enabled, paste or upload an image normally. By default the complete vision tool schema is stable from session start, so the agent can immediately use `vision_describe`, `vision_ground`, `vision_crop`, and the rest across multiple steps when needed.
  151. If the session already contains images, DSH may reject switching from a vision wrapper back to a text-only route. Vision Router does not bypass that Host rule: it shows a transient error using the same interaction style as the stock model selector, keeps the real current model unchanged, and leaves `👁 Vision ✓` reflecting the actual state so the session stays usable.
  152. The built-in anonymous OVH vision fallback is already configured, so normal image use needs no signup or API key. **The lower-right chat picker selects only the brain/conversation model**; vision backends do not belong there. Advanced options live under **Settings → Vision Router**: each vision-backend row may select any callable generative user model already configured under **Settings → Models**. DSH image-capability metadata is advisory for backend selection, but an explicit text-only declaration makes the Host replace image pixels with text placeholders before adapter dispatch. Vision Router uses a direct pixel bridge only for verified http(s) OpenAI Chat Completions endpoints; otherwise that backend fails safely and the chain continues. WebSocket, RPC, Responses API and other native protocols use their registered adapters when image input is declared or modalities are unknown. If a custom model genuinely supports images, first enable **Image** under **Settings → Models → provider editor → Customized settings → Model options → Input types** when that Host control is available. On older Hosts without the control, set the provider-specific model field (`llm-pi-ai`: `input: [text, image]`; `llm-deepseek`: `inputModalities: [text, image]`) and reload the model configuration. Never claim image input for an endpoint that cannot accept images. Leaving every user row empty is valid; the OVH chain remains the final fallback. `Vision HTTP` is an internal transport route, not a model group users should select.
  153. ### See it in action
  154. *Left: an image turn — the user sends a picture, the agent calls `vision_describe` through the free chain and answers. Right: the finished structured answer.*
  155. <p align="center">
  156. <img src="assets/dsh-conversation-image-qa.png" width="49%" alt="A conversation turn in which the agent looks at an uploaded image through vision_describe." />
  157. <img src="assets/dsh-conversation-image-qa-result.png" width="49%" alt="The agent's structured answer describing the image content." />
  158. </p>
  159. ## Data flow and strict local-only use
  160. Vision Router does not operate fully offline in its default configuration. The exact boundary depends on the operation and the selected models:
  161. | Operation | Where data goes |
  162. |---|---|
  163. | Local pixel tools such as crop, pixel diff, palette, SVG trace, cutout, materialize and HTML screenshot | Processed on the DSH machine; these operations do not call a vision model. |
  164. | `vision_ocr` with Tesseract | Processed on the DSH machine. With the default `auto` engine, an unavailable or empty local OCR result may fall back to a vision model. |
  165. | Image-turn routing and vision-model tools such as describe, detect, ground or vision OCR | The image or derived crop, prompt and relevant context are sent to the selected vision provider. |
  166. | Built-in free fallback | Sent anonymously (no API key) to OVHcloud AI Endpoints at `oai.endpoints.kepler.ai.cloud.ovh.net`; the service still receives the request payload and network metadata such as the source IP. |
  167. | User-configured cloud model / HTTP provider | Sent to that provider's configured endpoint under its own retention and privacy terms. |
  168. | Local Ollama / LM Studio | Image pixels are sent to the configured local endpoint. The resulting text still returns to the current chat model, which may itself be remote. |
  169. To stop **Vision Router itself** from sending image data to remote vision endpoints, enable **Settings → Vision Router → General → Local-only vision**. This is a runtime policy, not a destructive rewrite: saved cloud rows and `freeFallback` stay configured but cannot execute while the switch is on. Only loopback visual endpoints (`localhost`, `127.0.0.0/8`, `::1`) are eligible, including Ollama, LM Studio, and custom local HTTP backends. For a **strict local-only workflow**, also use a local chat model because vision result text still returns to the current chat model. Test the final network boundary in your own environment; Vision Router cannot make a remote chat model, proxy or Host integration local.
  170. ## Configure your own vision models
  171. **DSH owns providers, credentials and the global model catalog; Vision Router uses configured Host models for visual orchestration, execution, testing and diagnostics.** No plugin-specific commercial vendor YAML is required. Vision Router can privately supplement its own backend picker with live `/models` evidence for **already configured** Host providers and endpoint-scoped image-capability hints; these never register a new provider or mutate DSH's global model directory. Cached/saved-only IDs do not themselves authorize a direct model bridge. See [architecture provenance](docs/architecture/model-catalog-ownership.md).
  172. Manage provider credentials and models in **DSH Settings → Models**, then pick those models from the same Host catalog in **Settings → Vision Router**. Use **Test Vision** to verify that the exact model actually reads image content. If Host metadata incorrectly marks a real vision model text-only, prefer DSH **Model input types → Image**; on older Hosts, declare `input: [text, image]` on a **verified image-capable** `llm-pi-ai` model and reload configuration. Never fabricate image support for text-only models.
  173. The built-in anonymous OVH fallback is a separate Vision Router `httpProviders` runtime and not a DSH provider preset. Strictly local workflows also require a local chat model and the Local-only vision setting. Vendor price, quota and model IDs change; this project does not keep an ongoing marketing or free-tier list. The [August 2026 survey](docs/free-models.zh-CN.md) remains available solely as historical research.
  174. ## Why this exists
  175. Most DSH vision plugins bridge images to DeepSeek as *text descriptions* — lossy, one-shot, and blind to pixels. This plugin keeps the **Host-canonical image pixels on the vision model's side** and DeepSeek on the reasoning side, and makes looking at an image an **ordinary tool call**:
  176. - **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).
  177. - **Free by default.** Vision tools end with a four-model OVHcloud anonymous fallback: no account, no key, 2 requests/minute per IP per model, roughly 8 RPM in theory across independent buckets. User-provided vision models run first.
  178. - **No Python.** The whole pipeline — downscale, grounding, crop, pixel diff, palette, OCR, SVG trace, cutout, HTML screenshot — runs on sharp / VTracer / tesseract / system Chrome.
  179. - **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.
  180. - **DeepSeek stays the brain.** Text turns are untouched in model, cost and context. The vision model is only the eyes, called on demand; answers are cached by image content.
  181. - **Transparent to the user.** Uploaded images keep rendering as images in the conversation UI; the rewrite that points the model at the vision tools happens only inside the model call, never in the session log.
  182. ## How it compares
  183. **One-line take**: most dsh vision plugins turn images into *text descriptions* for DeepSeek
  184. (description bridge — lossy); this plugin hands the image turn *straight to a vision model*
  185. (routing bridge — pixel-level), with a built-in keyless free fallback.
  186. > [!NOTE]
  187. > On DSH 0.1.2-alpha.1+, attachments remain Host-owned. Vision Router consumes the Host-persisted canonical image: clean single-frame 8-bit sRGB/sRGBA images inside the configured normalization limits can pass through byte-identically, while images that need orientation, color-space, metadata, animation, or size normalization may be re-encoded. Pixel tools therefore promise the Host-canonical raster, not preservation of the uploader's original encoded bytes.
  188. | | Manual model switching | MCP vision bridge | dsh-vision-router |
  189. |---|---|---|---|
  190. | Image pixels | ✅ available (when switched) | ❌ text description only | ✅ Host-canonical raster, on the image turn |
  191. | Automatic | ❌ | ✅ | ✅ |
  192. | Daily model untouched | ❌ (whole session swapped) | ✅ | ✅ |
  193. | Provider failure recovery | ❌ | ❌ | ✅ fallback chains |
  194. | Reusable structured queries | — | partial | ✅ JSON mode + caching |
  195. | Free out-of-the-box | ❌ | ❌ | ✅ built-in keyless endpoint |
  196. | Fits dsh composition | — | external server | ✅ one plugin row |
  197. **Difference from existing dsh community projects** (all excellent, each with its own focus; descriptions reflect their READMEs as of 2026-08):
  198. | Project | Approach | What this plugin adds |
  199. |---|---|---|
  200. | [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 image routing, with `vision_describe` covering descriptions on demand |
  201. | [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 |
  202. | [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 |
  203. | [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 |
  204. | [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 |
  205. | [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 |
  206. ## Provider fallback chain
  207. The vision tools try backends in order and surface an error only after all of them fail:
  208. 1. **User vision models**: one per settings row, top to bottom; active providers remain visible even when model enumeration is partial, callable generative models stay selectable, image metadata is advisory, and actual support is verified at runtime;
  209. 2. **Local Ollama (optional, off by default)**: `localOllama.enabled` adds keyless, offline recognition through your local Ollama (for example qwen2.5vl);
  210. 3. **Local LM Studio (optional, off by default)**: `localLmStudio.enabled` follows Ollama and requires the real model identifier shown in LM Studio Developer or returned by `/v1/models`;
  211. 4. **Advanced custom HTTP vision endpoints**: legacy/advanced `httpProviders`, when present, run after the local backends;
  212. 5. **Built-in anonymous OVH fallback**: always last and never exposed in a model picker. The current quality-first chain is `Qwen3.5-397B-A17B` → `Qwen2.5-VL-72B-Instruct` → `Qwen3.6-27B` → `Qwen3.5-9B`. OVH anonymous limits are **2 requests/minute per IP per model**. The four models have independent buckets, so spreading requests across them is about **8 RPM in theory**, subject to OVH's actual rate limiting. No signup or API key is required. OVH has scheduled the previously bundled Mistral Small 3.2 model for decommission on November 4, 2026; it is no longer part of the automatic fallback, but user-managed rows are not changed. For more capacity, configure your own model in DSH; see [Configure your own vision models](#configure-your-own-vision-models).
  213. > [!IMPORTANT]
  214. > This “vision chain” is the **eyes** used by Vision Router: each settings row selects one user vision model, while the lower-right chat picker selects the **brain/conversation model**. The two are deliberately separate. Text-only DeepSeek/opencode models are filtered out of the vision-backend dropdown, and the internal `Vision HTTP` transport route is no longer exposed to users.
  215. > In the legacy `routing: true` mode, the whole-turn chain walks only `provider + fallbacks` — `httpProviders` (including the free fallback) do not participate there. The default `routing: false` (tools-first) tries everything.
  216. Failures are classified (region / tos / quota / rate-limit / context / network) and the final error carries advice; a `429` advances immediately to the next backend and applies a capped, `Retry-After`-aware circuit-breaker cooldown. Oversized uploads are downscaled before the call (default budget 4 MP) to keep tool calls fast.
  217. ## Stealth mode
  218. Stealth mode is **off by default** (explicit opt-in since issue #34): the official `deepseek-official` route stays untouched. When you need images, the composer’s “👁 Vision” control switches to the internal DeepSeek wrapper, which is hidden from the stock picker and `/model` presentation by default.
  219. On every DSH Host supported by DVR 2.3, the official DeepSeek provider owns request-local attachment, file and image-access behavior. Vision Router therefore **never reconstructs or resurrects `deepseek-official`**. Keep `llm-deepseek` enabled and use the internal “DeepSeek + Auto Vision” wrapper / “👁 Vision” control for image tasks. If the official row is disabled or unavailable, the settings card reports that configuration problem instead of silently recreating a partial provider.
  220. The historical `stealth` field is retained only so existing profiles continue to parse cleanly; it no longer grants provider-takeover authority on the DVR 2.3 support window.
  221. > Custom/third-party routes such as opencode also receive internal vision wrappers by default, used through the composer toggle rather than a second user-facing model group.
  222. ## Auto-vision wrappers and manual scope
  223. `autoWrapProviders` is on by default. The plugin discovers the provider/model entries currently enabled under **Settings → Models** and registers matching internal vision wrappers. **The original group is never changed.** Ordinary users do not need to find or manually select these routes: when ownership is confidently established, the wrappers are hidden from the stock picker and `/model`, and the composer’s “👁 Vision” control switches to them as needed. DSH `llm/adapters-updated` events are synced live, so adding/removing models does not require a restart.
  224. `wrappedProviders` is an **optional manual scope control**, not a required setup step. Use it only when:
  225. 1. automatic wrapping is off and you want to choose which provider/models can use “👁 Vision”; or
  226. 2. automatic wrapping remains on but one provider should generate wrappers for only selected models.
  227. The settings card uses provider + model dropdowns; an empty model means every model on that route. Add multiple rows to select multiple models. Changes apply immediately with no restart. If browser-side ownership or exact mirroring cannot be established, presentation hiding fails open so a third-party route is never hidden merely for cosmetic cleanliness.
  228. ## Web settings
  229. The Web profile registers a first-class **Settings → Vision Router** surface. Its General page keeps model choice and v2 routing authority together; Vision Strategy, Local & Device, Advanced and Diagnostics separate tool behavior, local backends, sensitive/performance controls and troubleshooting.
  230. **Reverse proxy deployments:** Preserve the original browser-facing `Host` when forwarding to DSH, as required by [upstream DSH](https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/docs/user/guide/public-deployments.md). A remote request forwarded over loopback must not become a *local-machine-only* request. Proxy-marked loopback requests are denied local-only Vision Router capabilities; proxies that rewrite `Host` to localhost **and strip all forwarding metadata cannot be reliably identified by the current Host API**. See [remote settings security](docs/remote-settings.md) and [Issue #680](https://github.com/ysr666/dsh-vision-router/issues/680).
  231. - **Vision model chain**: the real image-capable models used by `vision_describe` and friends; the built-in free chain remains the final fallback;
  232. - **Model selection**: keep the configured order, or explicitly enable capability-aware Auto with Balanced / Quality / Speed / Local preference;
  233. - **Background capability data**: `off`, `local-free`, or `all`; this is separately authorized and never turns on merely because Auto was enabled;
  234. - **Test Vision / Benchmark**: exact one-request image verification plus Quick (~3 requests, OCR + General) and Full (~6 requests, Structured + OCR + Document + Grounding + General) profiling; benchmark work continues if Settings is closed;
  235. - **Local & Device**: Ollama / LM Studio and privacy-gated desktop screenshot controls;
  236. - **Advanced / Diagnostics**: timeout, wrapper scope, proxy/network, compatibility, version, runtime status and troubleshooting.
  237. <p align="center">
  238. <img src="assets/vision-settings.png" width="72%" alt="The Vision Router settings surface." />
  239. </p>
  240. ## Configuration
  241. Everything is optional; defaults work out of the box. Prefer **Settings → Vision Router**; profile overrides remain available for advanced deployments:
  242. | Field | Default | Meaning |
  243. |---|---|---|
  244. | `routingMode` | `ordered` | `ordered` keeps the configured model-chain order; `auto` delegates prioritization to measured capability evidence. Auto is never enabled by migration |
  245. | `routingPreference` | `balanced` | Auto preference: `balanced`, `quality`, `speed`, or `local`; changes ordering only among already-authorized candidates |
  246. | `backgroundBenchmarking` | `off` | background capability profiling authority: `off`, `local-free`, or `all`; enabling Auto does not change it, and authorized background work runs only while Auto is active |
  247. | `provider` / `model` | `vision-http` / `ovh/Qwen2.5-VL-72B-Instruct` | shorthand **vision backend** route (adapter-backed provider + model that genuinely accepts images) |
  248. | `fallbacks` | `[]` | backup image models for the shorthand vision provider |
  249. | `providers` | built-in free `vision-http` pair | multi-provider **vision backend** chain `{ provider, model, fallbacks[] }`, tried in order; do not put text-only models here |
  250. | `httpProviders` | built-in OVH entry | direct OpenAI-compatible endpoints `{ name, baseURL, model, apiKeyEnv, maxTokens }` |
  251. | `autoWrapProviders` | `true` | discover enabled provider/models and live-sync their internal vision wrappers; confidently owned wrappers are hidden from the stock model picker while original groups stay unchanged |
  252. | `wrappedProviders` | `[{ provider: 'deepseek-official', models: [] }]` | optional manual wrapper scope `{ provider, models[] }`, used after disabling auto-wrap or to restrict which models can enter an internal wrapper through “👁 Vision”; changes apply live, no restart |
  253. | `routing` | `false` | legacy whole-turn chain routing (one-shot answer). `false` = tools-first flow (recommended) |
  254. | `reverseRouting` | `true` | with `routing: true`, route text turns back to `textProvider` |
  255. | `wrapperRoute` / `chainRoute` | `deepseek-vision` / `vision-chain` | developer route names. Leaving either field blank in current Settings clears the override and restores its default; explicitly blank values are retained only for legacy/manual persisted-config compatibility. |
  256. | `stealth` | `false` | take over the official `deepseek-official` route (official row only; custom routes are auto-wrapped by default) |
  257. | `textProvider` | `deepseek-official` / `deepseek-v4-pro` | the model that reasons (your daily model) |
  258. | `tool` / `progressiveTools` / `autoActivateOnImage` | `true` / `false` / `true` | vision tools on / progressive mounting (off by default for a stable tool schema) / image-turn auto-mount when progressive mode is enabled; `progressiveTools` is boot-time config |
  259. | `rewriteImages` | `true` | rewrite image blocks in the model input (cached description or tool-hint marker); the UI log keeps images |
  260. | `desktopScreenshot` | `false` | privacy opt-in for the model-callable `vision_screenshot` desktop-capture tool; checked live before every capture |
  261. | `localOnlyVision` | `false` | visual-endpoint privacy policy: only loopback vision endpoints may execute, so Vision Router keeps image bytes/crops off cloud vision services; derived result text (descriptions, OCR, coordinates) still goes to the current chat model, so strict end-to-end local use also requires a local chat model |
  262. | `freeFallback` | `true` | append the anonymous OVH models after explicit local/custom HTTP backends; ignored while `localOnlyVision` is enabled |
  263. | `localOllama` | `{ enabled: false, baseURL: 'http://127.0.0.1:11434/v1', model: 'qwen2.5vl', format: 'openai', maxTokens: 4096, reasoningEffort: 'none' }` | local vision backend; OpenAI mode disables supported model reasoning by default so the output budget is spent on answer text |
  264. | `localLmStudio` | `{ enabled: false, baseURL: 'http://localhost:1234/v1', model: '', format: 'openai', maxTokens: 4096, reasoningEffort: 'none' }` | local LM Studio backend after Ollama; LM Studio 0.4+ can use `format: 'lmstudio'` for documented native reasoning control |
  265. | `visionTurnBudgetMs` | `0` | whole-turn vision wall-clock budget; `0` means unlimited. Concrete provider calls/tools still keep their own hard deadlines |
  266. | `downscale` / `downscaleMaxPixels` | `true` / `4000000` | pre-call downscale and its pixel budget (latency guard) |
  267. | `cache` / `cacheTtlSeconds` / `cacheMaxEntries` | `true` / `3600` / `200` | vision answer cache |
  268. | `timeoutMs` | `120000` | per vision call deadline |
  269. | `artifactsDir` | `.dsh-vision-router/artifacts` | artifact directory (relative to the session workspace) |
  270. | `proxy` / `proxyHosts` | `''` / openrouter hosts | **advanced override**: empty follows the DSH/Host network path; only an explicit value proxies selected vision hosts through Vision Router |
  271. | `catalogCorrections` | `true` | built-in catalog-routing corrections for known upstream wire-protocol mismatches; each correction disarms itself once the catalog is fixed upstream |
  272. ### Network proxy: DSH/Host first
  273. Vision Router does **not own network egress by default**. When `proxy` is empty, Router-owned vision HTTP injects no private dispatcher and the Host-owned compatibility wrapper stays transparent, so requests continue on the current DSH/Host network path. With an explicit override, Host-owned adapter traffic is intercepted only while Vision Router is actively executing that configured visual provider; unrelated concurrent Host traffic keeps the Host route.
  274. On the DSH 0.1.5 line (rc.1+), the Host provides process-wide outbound proxy policy from `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` / `NO_PROXY`; TUN mode also works transparently below the process. DSH does not automatically read the macOS/Windows “system proxy” switch, so enabling only an app's System Proxy is not the same as proxying the CLI.
  275. Set `proxy` only when you intentionally need a **vision-only proxy override**. It remains available for older Hosts, SOCKS5 users, and deployments that need selected vision domains to take a different route; `proxyHosts` scopes only this plugin override and does not redefine the Host's global proxy policy. Redirects cannot widen that scope: once a DVR-proxied request redirects to a host outside `proxyHosts`, that hop returns to the request's inherited Host/caller dispatcher. A request whose initial URL is outside `proxyHosts` stays fully Host-owned, even if a later redirect enters the list.
  276. ### Local Ollama vision backend (merged from dsh-vision)
  277. > **Incremental author**: [shaoqiuyuavailable](https://github.com/shaoqiuyuavailable) (router local-vision increment)
  278. >
  279. > **Design credit**: the local vision backends (Ollama / LM Studio dual backends, structured recognition, screenshot identification, same-image memory dedup, failure fallback, concurrency protection and timeout handling) inherit their design from [dsh-vision](https://github.com/shaoqiuyuavailable/text-llm-vision/tree/dsh-vision) — merged into the HTTP vision chain here, with per-level fallback and dual-protocol support added on top.
  280. An optional keyless local-first vision path for private, free, offline recognition. It plugs into the existing HTTP vision chain as `local-ollama`; if it fails, any configured cloud backends can still be tried unless you deliberately configure a local-only chain.
  281. **1. Install Ollama and pull a vision model**
  282. ```sh
  283. # https://ollama.com — then:
  284. ollama pull qwen2.5vl
  285. ```
  286. **2. Enable it** — under **Settings → Vision Router → Local & Device**, or via a profile patch:
  287. ```yaml
  288. - id: vision-router
  289. config:
  290. localOllama:
  291. enabled: true
  292. baseURL: 'http://127.0.0.1:11434/v1'
  293. model: 'qwen2.5vl'
  294. temperature: 0.5
  295. top_p: 0.8
  296. ```
  297. **3. What happens**
  298. - When enabled, `local-ollama` heads the HTTP vision chain. To hard-block remote visual egress without deleting saved cloud settings, enable **General → Local-only vision**; only loopback visual endpoints remain executable while the policy is on.
  299. - The selected loopback Ollama model is prewarmed through Ollama's native API and kept resident for 30 minutes. If it is cold when Ollama is the primary image backend, loading completes before the normal vision-task budget starts; a short `/api/ps` probe keeps a dead service on the fast fallback path. Remote Ollama URLs are never auto-warmed.
  300. - **LM Studio works the same way** — enable `localLmStudio` with its OpenAI-compatible endpoint (default `http://localhost:1234/v1`) and enter the exact model identifier shown in Developer or `/v1/models`. It sits after `local-ollama` and before custom/cloud HTTP backends.
  301. - Local backends keep **OpenAI** as the compatibility default and can also use **Anthropic**. LM Studio additionally offers **LM Studio native** mode (`format: 'lmstudio'`, LM Studio 0.4+) at `/api/v1/chat`; use it when you need documented reasoning control (`reasoningEffort: 'none'` maps to `reasoning: off`). `maxTokens` is configurable and defaults to 4096.
  302. - If a local backend is down or the call times out, its entry is skipped automatically. Normally the chain can continue to cloud backends; with **Local-only vision** enabled, remote fallbacks remain blocked and the visual call fails closed instead.
  303. - `vision_screenshot` is disabled by default. After the separate Desktop screenshot opt-in, `identify=true` uses the same Ollama → LM Studio fallback.
  304. ## Requirements
  305. - 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`.
  306. - **DSH Host policy (DVR 3.2+ / 3.3.0 candidate):** Minimum DSH 0.2.1-rc.5; currently recommended DSH 0.2.2-rc.1. DSH 0.1.x, 0.2.0 and earlier 0.2.1 prereleases are retired. DSH owns native Connection authentication, routing and trustedHosts. Older sessions, attachments and Settings data remain readable. See [new Host support window](docs/architecture/dsh-support-window.md) and [retirement plan](docs/architecture/dvr32-host-retirement.md).
  307. - Node.js >=24.9.0 (Host side; Node 22 is retired).
  308. - No API key for the default free chain; a credential reference (`apiKeyEnv`) only for paid `httpProviders`.
  309. - Chrome / Chromium / Edge is needed only for `vision_html_screenshot`; every other tool works without a browser.
  310. - Desktop capture is opt-in. Windows and macOS use OS-provided capture facilities; Linux needs ImageMagick `import` or `scrot` and a capturable desktop session (Wayland support depends on the environment).
  311. - Local OCR engines are **optional**. `vision_ocr` defaults to `ocrEngine: auto`: verified owner-installed PP-OCRv6/ncnn on supported Mac ARM64 / Windows x64 → managed or system Tesseract → authorized vision-model fallback. Settings → Advanced → **Default OCR engine** can force Tesseract-only or vision-model-only behavior; per-call `engine=tesseract|vision` overrides it.
  312. - **On-demand setup (new optional feature):** Settings → Local & device → Optional local OCR shows independent installation states and controls. A system Tesseract with both `chi_sim` and `eng` is reused automatically, without a redundant download or a system uninstall option. If missing, the user can install or remove a private Tesseract.js/WASM with Chinese and English models; installation happens only after a click. PP-OCRv6 can be imported and removed from a user-supplied verified offline archive. Public PP-OCRv6 binary distribution remains unapproved; **there is no automatic native download** yet. Most users can continue with the authorized vision-model fallback without installing either engine.
  313. ## Install and lifecycle
  314. **Source developers:** use [Web development watch, Live Reload and native HMR](docs/development/web-live-reload.md) with an isolated DSH profile. This workflow is separate from packaged installation and does not enable Desktop HMR.
  315. ### Install
  316. Normal npm/npx install — one command:
  317. ```sh
  318. npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router
  319. ```
  320. > [!NOTE]
  321. > Profiles that mix legacy manual `cordis.patch.yml` plugin rows with bundle-managed plugins should read the compatibility warning in [Quick start](#1-install-the-plugin) before running DSH plugin commands.
  322. From a DeepSeek Harness source checkout:
  323. ```sh
  324. pnpm dsh plugin --profile web add dsh-vision-router
  325. ```
  326. Optional verification:
  327. ```sh
  328. npx @deepseek-ai/dsh --profile web --dump-config | grep vision-router
  329. # source checkout: pnpm dsh --profile web --dump-config | grep vision-router
  330. ```
  331. 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.**
  332. ### Oh-DSH Desktop
  333. [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.
  334. Install into the desktop profile by pointing `DSH_HOME` at the Oh-DSH home:
  335. ```sh
  336. DSH_HOME=~/.ohdsh npx @deepseek-ai/dsh plugin --profile desktop add dsh-vision-router
  337. ```
  338. (Windows PowerShell: run `$env:DSH_HOME = "$env:USERPROFILE\.ohdsh"` first, then the same command.)
  339. > [!WARNING]
  340. > 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+.
  341. 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.
  342. 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.
  343. ### Disable / re-enable
  344. ```yaml
  345. - id: vision-router
  346. disabled: true
  347. ```
  348. Set it back to `false` to re-enable. Unloading removes the wrapper routes, tools, skill and settings card; cached artifact files remain.
  349. ### Upgrade
  350. ```sh
  351. # normal npm/npx install — install the version you want explicitly; a bare
  352. # `update` is silently held back for releases younger than 24h (pnpm v11)
  353. npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router@<version>
  354. # DeepSeek Harness source checkout
  355. pnpm dsh plugin --profile web add dsh-vision-router@<version>
  356. ```
  357. 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.
  358. > **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.
  359. > **Upgrading from a pre-bundle-patch install (v0.x):** the package now mounts
  360. > itself through its own bundle patch, so a leftover manual row in
  361. > `~/.dsh/profiles/<profile>/cordis.patch.yml` duplicates it and `dsh web`
  362. > fails at startup with `duplicate loader entry id: vision-router`. Delete the
  363. > old block:
  364. >
  365. > ```yaml
  366. > - insert: # remove this whole block
  367. > - id: vision-router
  368. > name: dsh-vision-router
  369. > ```
  370. >
  371. > To keep custom settings, replace it with a plain by-id override (no
  372. > `insert`):
  373. >
  374. > ```yaml
  375. > - id: vision-router
  376. > config:
  377. > # your overrides …
  378. > ```
  379. > **After upgrading from v1.1.x, pixel tools fail with
  380. > `colourspace: parameter space not set`:** a stale sharp 0.34.0 from the
  381. > v1.1.0 era still sits in the profile and its libvips DLL conflicts with the
  382. > host's sharp 0.35.3 in the same process (issues #42 / #75). Delete
  383. > `~/.dsh/profiles/<profile>/node_modules/sharp` and
  384. > `~/.dsh/profiles/<profile>/node_modules/@img` and restart, or run
  385. > `pnpm install` inside the profile. Since v1.2.2 the plugin detects the
  386. > stale version at runtime and prints the same guidance itself.
  387. ### Uninstall
  388. ```sh
  389. # normal npm/npx install
  390. npx @deepseek-ai/dsh plugin --profile web remove dsh-vision-router
  391. # DeepSeek Harness source checkout
  392. pnpm dsh plugin --profile web remove dsh-vision-router
  393. ```
  394. This removes the dependency and the bundle layer. If you disabled the stock DeepSeek row manually, re-enable it in your profile patch.
  395. ## Troubleshooting
  396. ### Using dsh-web-ui / dsh-web-ui-all together
  397. If `dsh-web-ui` / `@linxin666/dsh-web-ui-all` is installed alongside Vision Router, its `dsh-tool-describe-image` send hook can rewrite image uploads into `describe-image` references before downstream vision plugins receive the original image block.
  398. `dsh-web-ui` now provides an explicit compatibility switch. Go to **Settings → Plugin config → Image understanding** and turn off **“Rewrite images to describe-image references on send”**, or set `interceptImageSend: false`. Image sends will then pass through unchanged so `dsh-vision-router` can receive the original image block. The switch is read on every send, so no hook reinstall or DSH restart is required.
  399. See [dsh-web-ui#301](https://github.com/zhu1090093659/dsh-web-ui/issues/301) for the upstream compatibility change.
  400. ### Startup fails with `Unexpected token ... is not valid JSON` (UTF-8 BOM)
  401. **Symptom:** `dsh web` / `pnpm dsh web` exits immediately at startup:
  402. ```
  403. SyntaxError: Unexpected token ...
  404. is not valid JSON
  405. at JSON.parse (<anonymous>)
  406. at readProfileManifest (packages/boot/app-boot/src/profile.ts)
  407. ```
  408. **Cause:** `~/.dsh/profiles/<profile>/package.json` was saved as **UTF-8 with BOM** by an editor. The invisible `\uFEFF` character at the start makes `JSON.parse` fail, because JSON does not allow it before the opening brace.
  409. **Recommended fix:** run Vision Router's standalone repair command. It does not require DSH to boot first; it locates the profile, detects a UTF-8 BOM, removes only the three leading BOM bytes, and then validates the JSON again:
  410. ```sh
  411. npx dsh-vision-router repair --profile web
  412. ```
  413. To diagnose without changing the file:
  414. ```sh
  415. npx dsh-vision-router doctor --profile web
  416. ```
  417. Replace `web` if you use another profile, or omit `--profile` to scan all profiles.
  418. Manual fallback: in VS Code, use “Save with Encoding” → `UTF-8` (without BOM). If `repair` removes the BOM but the JSON is still invalid, it will not guess or rewrite any other JSON content; inspect the file manually.
  419. ## Security notes
  420. - Image text is **untrusted evidence**: descriptions, OCR output and the auto-mount note all tell the agent never to execute instructions found inside images.
  421. - Tool inputs resolve through `ctx.fs` (sandbox-aware); vision uploads never send anything but the selected image and the question.
  422. - Artifacts write only under `<workspace>/.dsh-vision-router/artifacts`; results return absolute paths and byte counts.
  423. - Secrets never travel: `apiKeyEnv` names a DSH credential reference; the value is resolved per call and never logged.
  424. - The settings write path goes through the settings service (schema-validated, revision-checked) — a stale or invalid save is rejected, not partially applied.
  425. ## Design lineage
  426. The deep-vision tool layer and UI-restoration workflow in this project were informed by [Anionex/agent-vision-toolkit](https://github.com/Anionex/agent-vision-toolkit) and its native DSH implementation [Anionex/dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit). In particular, this project drew on their intent-driven tool selection, progressive tool exposure, pixel-diff verification loop, and parts of the visual-tool decomposition and naming, including long-screenshot OCR, foreground extraction, and HTML screenshot tooling.
  427. All code in `dsh-vision-router` is independently implemented. On top of those referenced design ideas, this project independently developed its turn-level/tools-first vision routing, DSH admission/wrapper integration, multi-backend provider and failure fallback chains, built-in free vision chain, attachment/image-memory handling, caching, and related runtime resilience mechanisms.
  428. We appreciate Anionex's prior work and the broader DSH community. Clear attribution and independent iteration can coexist; both help keep the DSH ecosystem open, collaborative, and healthy.
  429. ## Acknowledgements
  430. This project borrows ideas from all of the above — especially the keyless free-endpoint
  431. exploration (LLM7.io and OVHcloud anonymous tiers) by
  432. [dsh-vision-sidecar](https://github.com/121103qwq/dsh-vision-sidecar). Thanks to the authors of
  433. [dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy),
  434. [dsh-vision-provider](https://github.com/libinyam/dsh-vision-provider),
  435. [modlens](https://github.com/liustack/modlens),
  436. [dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit), and
  437. [dsh-tool-vision](https://github.com/Scorp1o117/dsh-tool-vision).
  438. ## Release notes and community
  439. Release details: [v3.4.0 notes](docs/releases/v3.4.0.md). Check GitHub Releases or npm for the actually published version.
  440. <p align="center">
  441. <sub>Ecosystem:</sub>
  442. <a href="https://dshplugin.app/plugins/dsh-vision-router">DSHPlugin.app</a> ·
  443. <a href="https://github.com/diegosouzapw/awesome-omni-dsh-plugins">Awesome Omni DSH Plugins</a> ·
  444. <a href="https://dshpluginhub.ai/plugins/dsh-vision-router">dshpluginhub.ai</a> ·
  445. <a href="https://www.dsh.plus/en/plugins/dsh-vision-router/">dsh.plus</a> ·
  446. <a href="https://dshplugins.ai/">dshplugins.ai</a> ·
  447. <a href="https://dshmarket.com/p/ysr666/dsh-vision-router/">dsh-market</a>
  448. </p>
  449. <p align="center">Repository: <a href="https://github.com/ysr666/dsh-vision-router">GitHub (primary · issues, PRs and releases)</a> · <a href="https://atomgit.com/ysr666/dsh-vision-router">AtomGit (China mirror)</a></p>
  450. <p align="center">💬 <strong>QQ community group: 1105463028</strong></p>
  451. ## License
  452. [MIT](LICENSE)
  453. <!-- star-history-chart -->
  454. ## Star History
  455. <p align="center">
  456. <a href="https://www.star-history.com/?repos=ysr666%2Fdsh-vision-router&type=date&legend=top-left">
  457. <picture>
  458. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=ysr666/dsh-vision-router&type=date&theme=dark&legend=top-left&sealed_token=bl3whaniTB54-d4wMda4a454thk48mT71wkNh8VrSD8OhCKWdBOOQpVKGUXzoEq4kx0_0jhQzEimHIqKAaGftFVV48sqgJ1niBfGy51AX5k_soGw_e7-5Nea6ZY5To0iz7jY9ORc5a_P5N6Qlfm32G2pdHf8_5dZeuHMn5NOZCyTgFcmq2eK1Jwg8ILe" />
  459. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=ysr666/dsh-vision-router&type=date&legend=top-left&sealed_token=bl3whaniTB54-d4wMda4a454thk48mT71wkNh8VrSD8OhCKWdBOOQpVKGUXzoEq4kx0_0jhQzEimHIqKAaGftFVV48sqgJ1niBfGy51AX5k_soGw_e7-5Nea6ZY5To0iz7jY9ORc5a_P5N6Qlfm32G2pdHf8_5dZeuHMn5NOZCyTgFcmq2eK1Jwg8ILe" />
  460. <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=ysr666/dsh-vision-router&type=date&legend=top-left&sealed_token=bl3whaniTB54-d4wMda4a454thk48mT71wkNh8VrSD8OhCKWdBOOQpVKGUXzoEq4kx0_0jhQzEimHIqKAaGftFVV48sqgJ1niBfGy51AX5k_soGw_e7-5Nea6ZY5To0iz7jY9ORc5a_P5N6Qlfm32G2pdHf8_5dZeuHMn5NOZCyTgFcmq2eK1Jwg8ILe" width="100%" />
  461. </picture>
  462. </a>
  463. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.