dsh-vision-bridge

English | 简体中文

A DSH-native Vision Evidence bridge for text-only reasoning models. When a request contains images, dsh-vision-bridge sends them to an image-capable Vision model on a DSH route you configure, converts the result into validated structured Evidence, and hands that Evidence to your text-only reasoning model as clearly labeled, untrusted observed data.

Community plugin for DeepSeek Harness (DSH) — not affiliated with or endorsed by DeepSeek.

Official distribution:

• npm: @liangdacheng/dsh-vision-bridge
• GitHub Releases: TwistedRiCen/dsh-vision-bridge — latest stable v0.2.5

Also discoverable under the DSH Community Plugins GitHub topic (dsh-plugin).

Table of contents

• What is dsh-vision-bridge?
• Why use it?
• Key features
• How it works
• Requirements
• Installation
  • Quick Install (recommended)
  • Manual Installation
• Configuration
• Advanced Installer Options
• Quick Start
• Usage examples
• Multi-image behavior
• Evidence and trust boundary
• Caching behavior
• Error and retry behavior
• Robustness: leading U+200B tolerance
• Troubleshooting
• Upgrading
• Uninstalling
• Development and testing
• Security notes
• Limitations
• Contributing
• License and third-party notices

What is dsh-vision-bridge?

dsh-vision-bridge is a plugin for the DeepSeek Harness (dsh). It registers a synthetic provider wrapper around an existing text-only reasoning route and makes the wrapped models accept native image attachments.

Under the hood, the bridge never runs a vision model itself. It delegates image understanding to a separate image-capable model on a DSH route you choose (the Vision route). The Vision output is strictly parsed and validated into structured Evidence, which is then rendered into the request as an explicitly untrusted text block for the downstream text-only model.

In other words: your primary model stays text-only, and image understanding is delivered to it as data.

Why use it?

DSH workflows built around a text-only reasoning model (for example a DeepSeek reasoning model) cannot consume image attachments directly. Typical workarounds require switching the whole workflow to a multimodal model or reading images outside DSH.

With dsh-vision-bridge you keep the same downstream model and workflow, and gain:

• Native attachment flow — users paste or attach images the usual DSH way.
• A dedicated Vision model — the image-capable model and provider are your choice, configured per profile.
• Validated Evidence — Vision output must parse and validate before it ever reaches the downstream model.
• A clear trust boundary — Evidence is labeled untrusted observed data, so the downstream model is instructed to treat it as data, not instructions.
• Multi-image support — several images in one request are analyzed in a single batch while each image keeps its own identity.

Key features

Capability	Behavior
Native image attachment bridging	Image attachments pass through to the Vision route as DSH-native image blocks; the bridge itself never reads raw image bytes.
Single-image Evidence	One image occurrence → one Vision call → one validated Evidence object that replaces the image in the request.
Multi-image Evidence batching	A run of two or more images becomes one Vision call carrying all images in order, producing one batch Evidence.
Explicit Image 1..N separation	Every image keeps its own Evidence entry; the batch must contain exactly one entry per image (images.length === N, indexes 1..N).
Cross-image relations	Relationships between images are represented in a separate relations list, never by merging attachments.
Strict Evidence validation	Vision output is strictly parsed and validated against a local schema before any downstream use.
Fail-closed behavior	Invalid, missing, or unverifiable Vision output fails the request; the downstream provider is never invoked without valid Evidence.
Bounded multi-image retry	Multi-image output-contract recovery is bounded to at most 2 Vision attempts per work unit.
Deterministic multi-image retry policy	Multi-image Vision attempts use temperature: 0. Single-image calls are not forced to a temperature.
Session-scoped Evidence cache	Completed, validated Evidence is cached in memory per session to skip repeated Vision calls for the same images.
Vision Auto-Discovery	With only upstreamProvider configured, the bridge finds the unique DSH model that positively declares image input and pins it as the Vision target.
Zero runtime dependencies	The released package has no runtime dependencies and stores no credentials of its own.

How it works

flowchart LR
    A[User message + N image attachments] --> B[dsh-vision-bridge wrapper]
    B -->|1 Vision call, images in order| C[Image-capable Vision route]
    C -->|raw JSON observation| B
    B -->|strict JSON parse + Evidence validation| D{Valid Evidence?}
    D -->|yes| E[Downstream text-only model<br/>untrusted Evidence text + Image n anchors]
    D -->|no| F[Request fails closed<br/>downstream is never called]

1. Detect. The bridge examines each outgoing message for image blocks (including images nested inside tool results).
2. Analyze. Images are sent to the configured image-capable Vision route via DSH's LLM service. The bridge itself only consumes the llm service — raw attachment bytes are resolved by the Vision provider's own adapter.
3. Validate. The Vision output must be one complete JSON document that passes the local Evidence schema check.
4. Transform. The validated Evidence is rendered as an explicitly untrusted text block (plus positional [Image n] anchors for multi-image batches) and forwarded to the text-only downstream provider.
5. Fail closed. If any step fails, the whole request fails and nothing reaches the downstream provider.

Requirements

• DeepSeek Harness with a working profile and the dsh CLI available (installed on your PATH, or run on demand through npx @deepseek-ai/dsh …). DSH is a developer preview; this plugin is tested against the DSH checkout at commit 47f943859bef60e4160492346772ded9b24f765a (CLI 0.1.0-rc.5), and the installation/upgrade/uninstall flow documented here was also verified against the currently published CLI 0.1.0-rc.6. Compatibility with other DSH versions is not guaranteed.
• Node.js ≥ 22.19 — the declared engine. The plugin runs inside DSH's own Node.js process; building from source requires it too.
• pnpm on your PATH — the dsh plugin command manages profile plugins by forwarding to pnpm.
• A text-only reasoning route (the upstream) — the model you want to wrap must positively declare text input and not declare image input.
• An image-capable Vision route — only needed when you configure visionProvider/visionModel explicitly. Without explicit configuration the bridge auto-discovers a model that positively declares image input (its credentials still live in DSH's credentials layer; the bridge stores no credentials of its own).
• Platform. Developed and verified on Windows. The plugin itself is platform-independent JavaScript, but no claims are made about untested operating systems.

Installation

The project is distributed through two official channels:

Channel	Identity
GitHub Release	repository dsh-vision-bridge — release tarball + guided installer
npm	official package @liangdacheng/dsh-vision-bridge (public, registry.npmjs.org)

Important: The official npm package for this project is @liangdacheng/dsh-vision-bridge. The unscoped npm package dsh-vision-bridge is unrelated to this project and is not published or maintained by this repository. Do not install it as this project.

npm publication starts with v0.2.4; v0.2.3 and earlier were distributed only via GitHub Release and were never published to npm. The current stable release is v0.2.5.

Release facts for v0.2.5:

Release page	https://github.com/TwistedRiCen/dsh-vision-bridge/releases/tag/v0.2.5
Artifact	dsh-vision-bridge-0.2.5.tgz
SHA-256	published in the dsh-vision-bridge-0.2.5.tgz.sha256 release asset
npm package	@liangdacheng/dsh-vision-bridge@0.2.5

For future versions, follow the same steps with the values from the latest release.

Quick Install (recommended)

A guided installer automates download, SHA-256 verification, plugin install, profile configuration (with backup and rollback), and validation. It does not need a global dsh install — the installer drives a pinned, tested DSH CLI (@deepseek-ai/dsh@0.1.0-rc.6). You only need Node.js >= 22.19 and pnpm on your PATH.

Invoke-WebRequest 'https://github.com/TwistedRiCen/dsh-vision-bridge/releases/download/v0.2.5/setup.mjs' -OutFile setup.mjs
node .\setup.mjs

The wizard will:

1. list your DSH profiles (or create a new one);
2. discover your upstream (text-only) provider route — when DSH's settings.yaml exposes exactly one text-only candidate it is selected automatically; with several candidates you pick from a numbered list (or pass --upstream-provider <id>). The installer writes the minimal upstream-only (Vision Auto-Discovery) configuration and never guesses route or model ids;
3. download and verify the v0.2.5 release tarball, install it into the profile, write the bridge configuration (backing up the previous file), and validate the result with dsh --dump-config.

Vision Auto-Discovery runs at the first image request. To pin an explicit Vision route instead, set visionProvider + visionModel together in the profile's cordis.patch.yml (see Configuration).

No Vision request is made during installation.

To verify the installer file itself before running it (recommended):

Invoke-WebRequest 'https://github.com/TwistedRiCen/dsh-vision-bridge/releases/download/v0.2.5/setup.mjs.sha256' -OutFile setup.mjs.sha256
(Get-FileHash .\setup.mjs -Algorithm SHA256).Hash
Get-Content .\setup.mjs.sha256

The two values must match. Always download and inspect first — do not run irm ... | iex. Installer flags (--what-if, --yes, --tarball, non-interactive arguments) are documented in Advanced Installer Options.

Manual Installation

If you prefer to audit or run every step yourself — or if the installer cannot run in your environment — the manual path below remains fully supported:

1. Prerequisites

Make sure the dsh CLI is available, and know which profile you use. A DSH profile is a directory under $DSH_HOME/profiles/<name> (by default ~/.dsh/profiles/<name>) that holds the profile's plugin list (package.json with a dsh.profile.bundles array) and your own configuration (cordis.patch.yml). Replace <profile> in every command below with that name.

dsh --help
dsh --version

If dsh is not recognized as a command, you can run the published DSH CLI on demand with npx — no global install needed:

npx @deepseek-ai/dsh --version

Throughout this guide, every dsh … command can be run as npx @deepseek-ai/dsh … (for example npx @deepseek-ai/dsh plugin --profile <profile> add …). The rest of the prerequisites are unchanged: you still need Node.js and pnpm on your PATH.

2. Download the release

Download the artifact from the v0.2.5 release page or with a command:

Windows PowerShell

Invoke-WebRequest -Uri 'https://github.com/TwistedRiCen/dsh-vision-bridge/releases/download/v0.2.5/dsh-vision-bridge-0.2.5.tgz' -OutFile 'dsh-vision-bridge-0.2.5.tgz'

macOS / Linux

curl -LO https://github.com/TwistedRiCen/dsh-vision-bridge/releases/download/v0.2.5/dsh-vision-bridge-0.2.5.tgz

3. Verify the checksum

Compare the file's SHA-256 against the value published on the release page (the dsh-vision-bridge-0.2.5.tgz.sha256 release asset). If it differs, do not install the file — delete it and download again from the official release page.

Windows PowerShell

(Get-FileHash .\dsh-vision-bridge-0.2.5.tgz -Algorithm SHA256).Hash

macOS / Linux

sha256sum dsh-vision-bridge-0.2.5.tgz     # Linux
shasum -a 256 dsh-vision-bridge-0.2.5.tgz # macOS

4. Install the plugin into your profile

Run this from the directory that contains the downloaded file:

dsh plugin --profile <profile> add .\dsh-vision-bridge-0.2.5.tgz

dsh plugin initializes the profile on first use, installs the package with pnpm, and then reconciles the profile's bundle list: because the package declares a dsh.bundle manifest entry, @liangdacheng/dsh-vision-bridge is added to dsh.profile.bundles in the profile's package.json automatically.

Verify the reconciliation by checking the profile's package.json:

{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@liangdacheng/dsh-vision-bridge"
      ]
    }
  }
}

@liangdacheng/dsh-vision-bridge must be present in dsh.profile.bundles. If your DSH build does not add it automatically (the reconciliation behavior varies by DSH build), append "@liangdacheng/dsh-vision-bridge" to that array manually and save the file.

Alternative: install from npm

From v0.2.4 the package is also published to the official npm registry as @liangdacheng/dsh-vision-bridge. With a global dsh:

dsh plugin --profile <profile> add @liangdacheng/dsh-vision-bridge@0.2.5

Without a global dsh:

npx -y "@deepseek-ai/dsh@0.1.0-rc.6" plugin --profile <profile> add "@liangdacheng/dsh-vision-bridge@0.2.5"

dsh plugin add forwards to pnpm, which installs the exact published version and reconciles @liangdacheng/dsh-vision-bridge into dsh.profile.bundles. Never install the unscoped dsh-vision-bridge npm package — it is a different, unrelated project.

5. Configure the bridge (required)

The bridge needs a text-only upstream route; everything else can be auto-discovered. The minimal configuration is a single key — supply it by editing the profile's cordis.patch.yml (see Configuration for the full contract):

- id: dsh-vision-bridge
  config:
    upstreamProvider: <text-provider>   # your text-only reasoning route

That is all. On the first image request the bridge automatically discovers the DSH model that positively declares image input and pins it as the Vision target for this plugin lifetime. Users who prefer explicit control can still set visionProvider and visionModel — see Configuration for both modes.

6. Start or restart DSH

DSH boots a profile as a foreground process; there is no separate start command. Stop a running instance with Ctrl+C and boot the profile again:

dsh --profile <profile>

(Without dsh on your PATH, use npx @deepseek-ai/dsh --profile <profile>.)

Use the same profile you installed the plugin into. The bridge registers itself during boot; a config error fails the boot loudly, so a clean boot is itself a first signal that the plugin is active.

7. Verify the installation

1. Print the composed profile configuration and confirm the bridge row and your config appear:

   dsh --profile <profile> --dump-config

   You should see a row with id: dsh-vision-bridge carrying at least your upstreamProvider value (plus visionProvider/visionModel when you configured them explicitly).

2. Boot the profile and open your DSH interface. The model catalog now contains a synthetic provider named after <upstreamProvider>-vision-bridge; its models are listed as <original name> (vision bridge).

3. Select a (vision bridge) model and attach an image to a message — see Usage examples.

Configuration

All configuration is plugin row configuration for the dsh-vision-bridge row. The package's own bundle layer (cordis.patch.yml) inserts the row; your profile's cordis.patch.yml supplies the row's config.

The file to edit is $DSH_HOME/profiles/<profile>/cordis.patch.yml — a YAML array of loader patch entries. Add (or extend) an entry with id: dsh-vision-bridge:

Minimal configuration (Vision Auto-Discovery)

Only the upstream route is required:

- id: dsh-vision-bridge
  config:
    upstreamProvider: <text-provider>   # your text-only reasoning route

When visionProvider and visionModel are both omitted, the bridge enters Vision Auto-Discovery: on the first request that actually contains an image, it asks DSH for the current provider catalog, keeps only models whose metadata positively declares image input (inputModalities contains image), re-confirms the capability through DSH's exact-model metadata, and then:

• exactly one such model → it is pinned as the Vision target for this plugin lifetime (profile restart or config reload re-discovers);
• none → the image request fails closed with guidance (configure an image-capable model in DSH, or set visionProvider + visionModel);
• more than one → the image request fails closed and lists every candidate, asking you to configure visionProvider + visionModel explicitly.

Discovery is lazy: text-only requests never trigger it. Discovery is also strictly capability-based — model names, provider names, and external knowledge are never used to guess image support; only explicit DSH metadata counts, and no probing request is ever sent to test capability.

Explicit configuration (advanced override)

To pin a specific Vision route yourself, configure both keys:

- id: dsh-vision-bridge
  config:
    upstreamProvider: deepseek-official # example: a text-only reasoning route
    visionProvider: deepseek-official   # example: the route serving the vision model
    visionModel: deepseek-vl            # example: the image-capable model id
    # providerId: my-bridge             # optional synthetic provider id

Explicit configuration always wins over Auto-Discovery. Configure both visionProvider and visionModel or neither — configuring only one is a configuration error and fails fast at boot.

Configuration keys

Key	Required	Meaning
upstreamProvider	yes	The DSH provider route to wrap. Its models must be positively text-only (declare text and not image input).
visionProvider	no*	The DSH provider route that serves the image-capable Vision model. Required together with visionModel; when both are omitted, Vision Auto-Discovery applies.
visionModel	no*	The image-capable model id on the Vision route. Required together with visionProvider; when both are omitted, Vision Auto-Discovery applies.
providerId	no	The synthetic wrapper's provider id. Defaults to <upstreamProvider>-vision-bridge. It must differ from upstreamProvider (and from visionProvider when configured).

* Either both or neither must be configured.

Notes:

• upstreamProvider and visionProvider may be the same route — one DSH route can serve both a text-only reasoning model and an image-capable Vision model.
• Vision capability is detected positively. The Vision route must positively declare image input (inputModalities contains image), and the upstream model must positively declare text-only input. Models with unknown or ambiguous modalities are refused.
• Vision credentials belong to the configured DSH provider (DSH credentials layer). The bridge has no secret store of its own.
• The Evidence cache is not configurable. Its scope is fixed (session-scoped, in-memory — see Caching behavior).
• If the bridge is enabled but upstreamProvider is missing, or only one of visionProvider/visionModel is set, the profile fails to boot with an error naming the problem.

Advanced Installer Options

The installer (setup.mjs) is interactive by default and asks for any value it does not have. The following flags are supported:

Flag	Meaning
--profile <name>	Profile to install into (created if missing). Names are restricted to letters, digits, _ and -.
--upstream-provider <id>	Text-only provider route to wrap.
--vision-provider <id>	Provider route serving the image-capable model.
--vision-model <id>	Image-capable model id on the vision route.
--provider-id <id>	Optional custom wrapper provider id (defaults to <upstreamProvider>-vision-bridge).
--version <release>	Bridge release to install (must be a trusted release; default 0.2.5).
--tarball <path>	Install from a local release tarball (SHA-256 verified against the trusted release map).
--yes	Skip the final confirmation (never skips verification).
--what-if	Print the plan — including the exact configuration that would be written — without downloading or writing anything.

Behavior notes:

• The installer never reads, prints, or stores provider credentials; credentials stay in the DSH credentials layer.
• Ports are not part of the installer: the DSH profile / web app owns the UI port.
• Re-running is idempotent: the same version reports "No changes required"; newer versions upgrade in place (configuration kept); older versions are refused (no downgrade).
• If anything fails, the previous configuration is restored and the installed package is kept, with a clear explanation and the manual path above as fallback.

Quick Start

Already have DSH installed and a profile? Here is the shortest verified path. Every dsh … command can also be run as npx @deepseek-ai/dsh … if dsh is not on your PATH (see 1. Prerequisites):

1. Download the v0.2.5 artifact from the release page:

   Invoke-WebRequest -Uri 'https://github.com/TwistedRiCen/dsh-vision-bridge/releases/download/v0.2.5/dsh-vision-bridge-0.2.5.tgz' -OutFile 'dsh-vision-bridge-0.2.5.tgz'

2. Verify the checksum (details):

   (Get-FileHash .\dsh-vision-bridge-0.2.5.tgz -Algorithm SHA256).Hash

   Compare it against the value published on the release page (the dsh-vision-bridge-0.2.5.tgz.sha256 release asset).

3. Install into your profile (details):

   dsh plugin --profile <profile> add .\dsh-vision-bridge-0.2.5.tgz

   (Or, from npm: dsh plugin --profile <profile> add @liangdacheng/dsh-vision-bridge@0.2.5.)

4. Configure the row in $DSH_HOME/profiles/<profile>/cordis.patch.yml (details):

   - id: dsh-vision-bridge
     config:
       upstreamProvider: <text-provider>

   (The bridge auto-discovers the Vision target on the first image request. To pin a specific Vision route instead, add visionProvider and visionModel — see Configuration.)

5. Boot your profile (details):

   dsh --profile <profile>

6. Select the <original name> (vision bridge) model in your DSH interface and send a message with an image attached:

   Describe only what can be verified from this image.

7. Check. If the reply is grounded in the image, the bridge is working. If the request fails, see Troubleshooting.

Placeholders: <profile> — the DSH profile you normally use; <text-provider> — the route of the text-only model you want to wrap. <vision-provider> / <vision-model> — only needed for the explicit (non-auto) configuration: the route and model id of an image-capable model available to your DSH installation.

Usage examples

The examples below show what to ask and what the bridge does. Replies are produced by your models — treat them as illustrative, not guaranteed output.

Single-image request

Attach one image (a screenshot, a diagram, a receipt) and ask:

Describe only what can be verified from this image.

What happens:

1. The bridge detects the image block and makes one Vision call with the image.
2. The Vision output is parsed and validated into a single Evidence object (summary, ocr, layout, semantics, visual, uncertainty).
3. The image is replaced by the rendered Evidence text, and the downstream text-only model answers from that Evidence.

Two-image comparison

Attach two images and ask:

Compare Image 1 and Image 2. Describe each independently, then state only
relationships that can be verified across the two images.

What happens:

1. The two images form one multi-image work unit: a single Vision call carries both images in attachment order.
2. The batch Evidence contains exactly two entries — Image 1 and Image 2 — each with its own summary/ocr/uncertainty, plus any verified cross-image relationships in a separate relations list.
3. The downstream model receives [Image 1] and [Image 2] anchors at the original positions plus one Evidence block, so it can answer about each image and about their relationship without the images themselves.

Multi-image relationship analysis

Attach several related images (for example three screenshots of a workflow) and ask:

Walk through the steps visible across these screenshots and note any
sequence that can be verified from the images.

Each attachment stays an independent source image. The batch Evidence keeps one entry per image and records objective cross-image relations separately; the downstream model reasons over the Evidence, not over merged image data.

Multi-image behavior

If a request contains N image attachments, the bridge treats them as follows:

• Per-attachment boundary labels (v0.2.3). To improve multi-image separation robustness, v0.2.3 interleaves an explicit per-attachment boundary label (Image i of N:) immediately before each native image block in the multi-image Vision request. Strict cardinality validation and the two-attempt fail-closed retry policy remain unchanged and remain the final safety boundary.
• The images of one consecutive run become one work unit analyzed by one Vision call that carries all N images in traversal order.
• Each attachment remains an independent source image. Adjacent, visually related, or visually continuous attachments are never merged into a single Evidence entry.
• Valid multi-image Evidence must satisfy:
  • images.length === N — exactly one entry per attachment;
  • indexes = 1..N — each entry's index equals its input-order position (no gaps, no duplicates, no extras).
• Cross-image relationships are represented separately in the relations list; each relation references at least two distinct image indexes. They never replace or merge the per-image entries.
• On the downstream wire, each image is replaced in place by a positional [Image n] anchor and exactly one batch Evidence block is appended, so the original text/image association is preserved.
• Tool results are boundaries. Images nested inside tool-result content are processed at their own nesting level; work units never merge across tool-result boundaries or across messages. Work units run one after another, in traversal order.
• A single-image work unit keeps the simple single-image path: one Vision call, one Evidence object, the image replaced by the Evidence text — no anchors.

Example: two attached receipts → one Vision call with Image 1 (first receipt) and Image 2 (second receipt) → Evidence with two independent entries plus, if the Vision model found any, a relation such as imageIndexes: [1, 2] with a description of a verified shared detail.

Evidence and trust boundary

Evidence is the structured JSON the Vision model must produce. Its core concepts:

summary      — what the image shows
ocr          — transcribed text (full_text, lines)
layout       — observable regions in reading order
semantics    — scene, entities, and in-image relations
visual       — qualitative visual properties
uncertainty  — what the model could not read or verify

Multi-image Evidence wraps one such entry per image (plus the image's index) and adds the cross-image relations list. Bounding boxes and numeric confidence values are deliberately absent — models tend to fabricate them.

Trust model:

• Image/model observations are untrusted observed data.
• Vision output must be one complete JSON document that parses strictly and validates against the Evidence schema. Invalid Evidence never continues downstream.
• The bridge never invents missing Evidence, never deterministically splits merged model output, never accepts partial cardinality, and never performs semantic repair of Evidence.
• Evidence delivered downstream is wrapped in an explicit boundary that instructs the text-only model to treat every line strictly as data, not as system, developer, or tool instructions.

This boundary is a prompt-injection mitigation, not a security boundary — it does not sandbox the downstream model.

Caching behavior

The bridge keeps a session-scoped, in-memory cache of completed Evidence:

• What is cached: only Evidence that was successfully parsed and validated. A hit reuses that exact Evidence with zero Vision calls.
• Scope: partitioned by the DSH request's sessionId; different sessions never share entries.
• Capacity and lifetime: a bounded LRU (32 entries), held in memory only. It is not persistent and disappears when the plugin instance is unloaded (profile restart, config reload, or plugin disable/remove).
• What is never cached: failures, cancellations, invalid output, and anything in-flight. A failed request leaves the cache untouched.
• Bypass: requests without a usable sessionId, or images without valid attachment ids, bypass the cache entirely and run Vision normally.
• No single-flight: two concurrent identical misses may each run a Vision call; the first completed valid result wins the cache entry.

The cache is an internal performance optimization — there is no configuration for it, and it never changes correctness or the trust boundary.

Error and retry behavior

The bridge fails closed: any Vision failure fails the whole request, and the downstream provider is never invoked without valid Evidence. A failed batch never emits partial Evidence.

Single-image

Exactly one Vision call per image occurrence. There is no retry for output-contract problems. Single-image calls are not forced to any temperature.

Multi-image

Multi-image output-contract recovery is bounded to at most two Vision attempts per work unit:

• One shared retry budget covers both failure classes:
  • the Vision output is not valid JSON;
  • the output parses but fails the multi-image Evidence schema.
• Each retry is a completely fresh Vision call with the same prompt, images, and order, using temperature: 0. Failed attempt output is discarded wholesale and never fed into a later attempt.
• Provider/transport/stream failures are not retried — they fail the request immediately.
• After the second failed attempt the request fails. There is no Attempt 3.

Robustness: leading U+200B tolerance

For multi-image Vision output only, the strict JSON parser tolerates one narrowly scoped envelope artifact: a leading run of U+200B (zero-width space) characters at the very start of the parse input is stripped once, before strict JSON.parse.

What this is not:

• It is not general JSON repair, normalization, or extraction.
• U+200B characters inside the JSON value are never touched.
• The remaining input must still be one complete JSON document accepted by strict parsing, and the parsed Evidence must still pass the strict schema validation.
• Trailing or mid-document noise is not repaired.

The single-image path is unchanged and keeps strict parsing without this tolerance.

Troubleshooting

Symptom	Likely cause	What to check
dsh is not recognized as a command (dsh: command not found)	The DSH CLI is not installed or not on your PATH.	Install DeepSeek Harness per its README, or run the same commands on demand with npx @deepseek-ai/dsh … (for example npx @deepseek-ai/dsh plugin --profile <profile> add …).
Profile boot fails with config "upstreamProvider" must be a non-empty string	The bridge row has no upstreamProvider.	Add upstreamProvider to the dsh-vision-bridge entry in the profile's cordis.patch.yml.
Profile boot fails with config "visionProvider" and "visionModel" must be configured together	Only one of the two Vision keys is configured.	Configure both visionProvider and visionModel, or omit both to use Vision Auto-Discovery.
Request fails: vision auto-discovery found no image-capable model	Auto mode is on, and no DSH model positively declares image input.	Configure an image-capable model in DSH (its metadata must include image in inputModalities), or set visionProvider + visionModel explicitly.
Request fails: vision auto-discovery found multiple image-capable models	Auto mode is on and more than one DSH model positively declares image input.	Set visionProvider + visionModel explicitly to pick one of the listed candidates.
dsh: profile "<name>" does not exist	The profile was never created.	Create it with dsh plugin --profile <profile> add ..., or use the profile you normally boot.
The bridge row is missing from dsh --dump-config output	The bundle was not registered in the profile.	Check that @liangdacheng/dsh-vision-bridge is in dsh.profile.bundles in the profile's package.json; append it manually if your DSH build does not reconcile automatically, then restart.
The (vision bridge) models do not appear in the model catalog	The upstream route is unavailable at discovery time, or its models are not text-only.	Make sure the upstream provider plugin is enabled in the profile and that the model you want to wrap declares text-only input. Restart the profile after providers register.
Request fails: vision model is not positively-confirmed image-capable	visionModel on the Vision route does not declare image input.	Point visionModel at a model whose inputModalities include image.
Request fails: vision output is not valid JSON (retry exhausted)	The Vision model twice returned output that is not one complete JSON document.	Check the Vision model/provider; multi-image recovery is bounded to 2 attempts by design.
Request fails: vision evidence failed validation (retry exhausted)	The Vision output parsed but violates the Evidence schema (for example wrong images.length or wrong indexes).	This is a model output problem, not a configuration problem. Do not try to weaken the parser or schema.
Images seem to be ignored and the request goes straight to the text model	You are using the bare upstream model instead of the wrapped one.	Select the <original name> (vision bridge) model, not the original model.
Multi-image request fails after retry	Both Vision attempts produced invalid output.	See Error and retry behavior; verify the Vision model. There is no third attempt.
Checksum does not match	Corrupted download or wrong file.	Delete the file and download again from the official release page.
After uninstalling, boot logs patch: entry "dsh-vision-bridge" not found	The config entry was left in cordis.patch.yml.	Remove the dsh-vision-bridge entry from the profile's cordis.patch.yml. The warning is harmless, but clean it up.

Do not loosen parser or schema rules as a workaround, and do not edit files inside the installed package.

Upgrading

Upgrading from v0.2.3 or earlier (package identity migration)

Starting with v0.2.4 the npm package identity is scoped (@liangdacheng/dsh-vision-bridge); v0.2.3 and earlier installed the unscoped package name dsh-vision-bridge. When upgrading a profile that was installed by an earlier release:

• The guided installer (v0.2.4) migrates automatically: it removes the old unscoped dependency and bundle entry before installing the scoped package and keeps your bridge configuration. A backup of the profile manifest is taken and restored if the upgrade fails.

• Manually, remove the old identity first, then add the new one:

  dsh plugin --profile <profile> remove dsh-vision-bridge
  dsh plugin --profile <profile> add @liangdacheng/dsh-vision-bridge@0.2.5

  (Instead of the registry spec you can add the downloaded v0.2.5 tarball.) Do not add the new package while the old unscoped dependency is still present — both bundle entries would then be active.

Upgrading within the scoped identity (v0.2.4 and later)

To upgrade from an older v0.2.4+ version:

1. Stop DSH (Ctrl+C on the running instance).

2. Download the new release artifact from GitHub Releases and verify its SHA-256 (the checksum is published on the release page).

3. Install the new artifact with dsh plugin — an add with the new tarball replaces the installed version; no remove step is required:

   dsh plugin --profile <profile> add .\dsh-vision-bridge-<new-version>.tgz

   (Or: dsh plugin --profile <profile> add @liangdacheng/dsh-vision-bridge@<new-version>.)

4. Verify the configuration still matches your routes and models (dsh --profile <profile> --dump-config).

5. Restart DSH:

   dsh --profile <profile>

6. Repeat a smoke test (one image, then two images).

Upgrading replaces the installed package; the profile's bundle entry and your config entry in cordis.patch.yml carry over unchanged. (The installer performs the same upgrade automatically: download → verify → plugin add, with your configuration preserved.)

Uninstalling

Remove the plugin from the profile with the verified command:

dsh plugin --profile <profile> remove @liangdacheng/dsh-vision-bridge

dsh plugin remove uninstalls the package with pnpm and removes @liangdacheng/dsh-vision-bridge from dsh.profile.bundles automatically.

Configuration is not removed automatically: also delete the dsh-vision-bridge entry from the profile's cordis.patch.yml. If you leave it, booting logs a harmless warning (patch: entry "dsh-vision-bridge" not found) and ignores the entry.

Development and testing

Building from source requires Node.js ≥ 22.19 and pnpm:

pnpm install   # dev dependencies only (typescript, @types/node, and the installer build tools)
pnpm build     # tsc -> dist
pnpm test      # build, then run the deterministic suite with node --test
pnpm pack      # build the release tarball (see the package files whitelist)

The installer is built separately:

pnpm run build:installer   # bundle scripts/installer/setup-src.mjs -> dist-installer/setup.mjs (+ .sha256)
pnpm run test:installer    # deterministic installer suite (tests/setup)

The bridge test suite is fully deterministic and runs in-process — it performs no network access and no real provider calls. It covers the accumulator contract, single-image bridging, multi-image batching, Evidence schema validation, the bounded retry state machine, the U+200B envelope tolerance, and the session-scoped cache. The installer suite covers the CLI surface, YAML mutation, backups, rollback, idempotency, download/checksum failures, and the Windows path matrix with a fake DSH CLI; no live GitHub, npm, or provider access is needed.

Runtime dependencies: 0. The released artifact contains only dist, cordis.patch.yml, README.md, LICENSE, and THIRD_PARTY_NOTICES.md.

Security notes

• The bridge consumes only DSH's llm service and reads no raw image bytes; attachments pass through to the Vision route, whose own adapter resolves them.
• Vision credentials live in the configured DSH provider (credentials layer), not in this plugin.
• Image-derived text is labeled untrusted observed data before the downstream model sees it. This is a prompt-injection mitigation, not a security boundary — treat model output (including Evidence) with normal caution.
• The installer never reads, prints, or stores credentials, sends no telemetry, and refuses downloads whose SHA-256 does not match its trusted release map.

Limitations

• Distribution: GitHub Release and npm (@liangdacheng/dsh-vision-bridge, from v0.2.4). v0.2.3 and earlier are GitHub-only. The unscoped npm package dsh-vision-bridge is unrelated to this project.
• DSH compatibility: DSH is a developer preview. The plugin is tested against one DSH commit; other versions may behave differently.
• Real-provider scope: deterministic tests never call real providers. Real-provider validation is limited to a tested pi-ai-backed route; no claim is made about other providers or arbitrary image counts.
• Wrapping rules: only positively text-only models can be wrapped; the Vision route must positively declare image input.
• Vision Auto-Discovery: discovery runs on the first image request and pins the target for the plugin lifetime. It fails closed when DSH declares zero or multiple image-capable models (list every candidate in the latter case); it never guesses capability from model/provider names and never probes providers. The installer (v0.2.5) writes the minimal upstream-only configuration automatically; switch to Auto-Discovery by omitting visionProvider/visionModel from the profile config.
• Retry budget: multi-image recovery is at most 2 attempts; provider and transport errors are never retried.
• Cache: in-memory and session-scoped only; no persistence, no single-flight (concurrent identical misses may duplicate Vision calls).
• Evidence contract: no bounding boxes and no numeric confidence, by design.
• Installer: provider/model IDs are entered manually — DSH currently has no stable boot-free catalog API for tools. The installer is verified on Windows; no claims are made about untested operating systems.

Contributing

Issues and pull requests are welcome. Please include reproducible steps and the relevant environment information (DSH version/commit, profile configuration, and the error output).

License and third-party notices

• License: MIT
• Third-party notices: THIRD_PARTY_NOTICES.md

Recursive image/tool-result traversal, evidence projection, the evidence schema concepts, and the local validation approach are adapted from @liustack/modlens v3.16.6 (MIT, (c) Leon Liu). No ModLens code is directly copied — see THIRD_PARTY_NOTICES.md for the full record.