@liangdacheng/dsh-vision-bridge

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/ /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:    # 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 -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.

Minimal configuration (Vision Auto-Discovery)

Only the upstream route is required:

- id: dsh-vision-bridge
  config:
    upstreamProvider:    # 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 -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.

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.