Skip to main content

dsh-deepseek-vision

7Stars1Forks0Issues0Watchers

Adds sticker support to text-only DeepSeek: registers a visual routing mechanism where images are first described as text by a VL model, then passed to DeepSeek—no model changes or official modifications required.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
TypeScript
License
MIT
Branch
main
coding-agentdeepseekdeepseek-harnessdshdsh-pluginllm-gatewaymultimodalplugin

Install

cmdweb profile
$ dsh plugin --profile web add dsh-deepseek-vision

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin siegfly/dsh-deepseek-vision for me: review the repository at https://github.com/siegfly/dsh-deepseek-vision first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

One-Sentence Positioning

Give plain-text DeepSeek models "image attachment" capability: register a new model route deepseek-vision, declare image input support in the chat window, but internally first send images to your configured vision model (default qwen3-vl-flash) to describe them word-by-word in text, then pass to the original DeepSeek streaming interface.

Core Capabilities

  • Register a new provider route DeepSeek + Vision. After selecting in the Models page, images pasted in the chat window, embedded images in tool results, and images passed from MCP/ACP clients can all pass the official admission threshold
  • Rewrite image blocks into VL model-generated description text before sending to DeepSeek. The original images are still written as-is to session logs, history and replay remain unaffected
  • Do LRU description caching by attachmentId in-process. The same image is recognized only once during retries, session compression, and subsequent turns
  • Any VL gateway compatible with OpenAI /chat/completions interface can be connected (DashScope, vLLM self-hosted, OpenRouter, LM Studio, etc.). Just change the endpoint in the settings card, no code changes needed
  • Clear failure semantics: default fail-closed and return stable error codes (AUTH / TIMEOUT / TRANSPORT / RATE_LIMIT / IMAGE_TOO_LARGE, etc.), optional placeholder strategy degrades to text placeholder to continue
  • Pre-check image size limits: when image bytes or pixels exceed host limits, fail with IMAGE_TOO_LARGE before base64 encoding, don't send large images to the VL endpoint only to fail there

Technical Implementation

  • Language: TypeScript (host side + React client side)
  • Key Dependencies: @deepseek-ai/dsh-llm-deepseek (inherits DeepSeekAdapter streaming/retry/wire serialization), @deepseek-ai/dsh-llm (error codes and stable states), @deepseek-ai/dsh-credentials (credential parsing)
  • Architecture Pattern: Server registers llm-vl-gateway settings section and one provider route at the bundle layer via cordis.patch.yml, inherits official DeepSeekAdapter and overrides stream(): first uses ImageBridge to rewrite image blocks into text descriptions, then calls super.stream(); client injects a settings card via settings.plugin.item slot. Registration/reregistration is atomic, route id and display name take effect immediately in the settings card
  • Entry Points: Server src/index.ts (exports apply, Config, VisionGatewayAdapter, ImageBridge), Client src/client/index.ts (exports apply and injects card to settings.plugin.item)

Use Cases

Developers who use DeepSeek daily for programming and writing code, often needing to paste error screenshots, UI screenshots, ASCII之外的草图 (sketches beyond ASCII), terminal output images into conversations for model understanding. The official DeepSeek API rejects images for plain-text models. This plugin fills this capability without you changing official configuration or switching models. When you want to switch between different VL vendors, or don't want to introduce extra local models and third-party relays, this "thinnest bridge" is the most direct solution.

Prerequisites & Compatibility

DependencyMin VersionDescription
DSH>=0.1.0-rc.6 (compatible with both rc.6 and rc.7)Same release artifact can load on both slot forms; build anchor declared at dshCompat.anchorVersion = 0.1.0-rc.8 (source declaration, not install gate)
Node.js>=22.19.0 (or 24+)Official CLI installation path doesn't require Node version; CLI-free replica path (pnpm install-profile) needs it
PlatformmacOS / Windows / LinuxCI validates on ubuntu, windows, macos-latest runners; client is browser bundle, no host system requirement
Native ModulesNonePure fetch/Node standard library, no native deps like node-pty/node:sqlite

Installation

dsh plugin --profile web add github:siegfly/dsh-deepseek-vision

Configuration Options

ConfigTypeDescriptionDefault
providerstringRegistered route id (avoid official deepseek-official)deepseek-vision
displayNamestringName shown in Models selectorDeepSeek + Vision
deepseek.*sectionFully isomorphic with official DeepSeek config (apiKeyEnv, baseURL, thinking, reasoningEffort, maxTokens, models, retryPolicy, etc.)Inherits official defaults
vl.apiKeyEnvcredential ref nameName of VL model key in credentials/env varsQWEN_VL_API_KEY
vl.baseURLstringVL gateway address, will auto-append /chat/completions; supports any OpenAI compatible interfacehttps://dashscope.aliyuncs.com/compatible-mode/v1
vl.modelstringVL model id, can switch to qwen-vl-max for complex visual reasoningqwen3-vl-flash
vl.describePromptstringPrompt for describing images, recommend requiring word-by-word extraction of code, errors, logs, UI textDetailed English word-by-word extraction prompt
vl.timeoutMsnumber (ms)Hard timeout for single description request120000
vl.maxCacheEntriesintegerIn-process description cache capacity (LRU)64
vl.onFailurefail or placeholderBehavior when description fails: fail immediately, or degrade to text placeholder to continuefail

FAQ

Q: What do I need to do after installation to paste images in chat?

A: Open dsh Settings → Plugins → Plugin Config, find the "DeepSeek + Vision (Vision-Language Bridge)" card, fill in the VL model key (or export QWEN_VL_API_KEY in terminal), then switch the provider to DeepSeek + Vision in the Models page. You can now paste images in the chat. DeepSeek key reuses existing credentials, no additional config needed.

Q: Will image-containing history sessions break after uninstalling this plugin?

A: Data won't be lost, but such sessions can't switch back to plain-text models—official selectModel rejects text models for image-containing sessions based on inputModalities. This is expected behavior, not data corruption. New sessions are unaffected, reinstalling the plugin restores functionality.

Q: If VL model description fails, is the whole request wasted?

A: Default is fail-closed: description failure terminates the entire request with stable error codes (AUTH, TIMEOUT, TRANSPORT, RATE_LIMIT, IMAGE_TOO_LARGE), won't silently drop images. If you want the conversation to continue even on recognition failure, change the failure strategy to placeholder in the card. Images will be replaced with a text placeholder explanation.

Q: The same image appears repeatedly, will I be charged multiple times?

A: No. The plugin does LRU caching by image attachmentId in-process. Retries, session compression, and subsequent turns all reuse the same description text. Cache clears after uninstall or restart, next time will recognize again.

Q: Must I use qwen3-vl-flash?

A: No. The vl.baseURL and vl.model in the settings card are prepared for switching VL. Any gateway providing OpenAI-compatible /chat/completions interface can be used, e.g., vLLM self-hosted, OpenRouter, LM Studio. Complex visual reasoning can switch to qwen-vl-max.

Q: Can I use it in headless mode?

A: Yes. Gateway routing behaves identically in web and headless profiles; the visual settings card only appears in web profile. In headless, edit settings.yaml directly to configure the llm-vl-gateway.vl section.

Q: Will it automatically lock to official DSH version?

A: No. dshCompat.anchorVersion only declares the build source of lib/, not an install gate. Official CLI installation path directly installs the release artifact; CLI-free replica path rebuilds on target machine, successful build itself is compatibility proof.

Q: How do I uninstall?

A: Execute dsh plugin --profile web remove dsh-deepseek-vision (replace web with headless for headless). This only uninstalls the plugin itself. Original images written to session logs are unaffected.

Getting Started Difficulty

Beginner — After installation, just fill in one VL model key and select DeepSeek + Vision in the Models page to use. No programming or extra config needed. Enter settings card again only when you want to switch VL models or adjust cache size.

Known Issues & Limitations

  • No image downsampling capability: when images exceed host attachments.imageLimits, they are rejected with IMAGE_TOO_LARGE. Images within deployment limits may still exceed VL vendor's own size limits. Need to control vl.timeoutMs and consult vendor docs
  • Description text consumes DeepSeek's context window, a few hundred tokens per image, charged only on first attempt
  • Default fail-closed: VL key invalid, timeout, 429, etc. errors terminate the entire request, won't silently drop images (can change to placeholder strategy to degrade)
  • If session compression strategy is manually pinned to deepseek-official and history contains images, compression phase fails due to official UNSUPPORTED_CONTENT; continuing to use this route's provider (deepseek-vision) doesn't have this issue
  • After uninstalling, image-containing history sessions can't switch back to text models (official admission rejects based on inputModalities, expected behavior); new sessions unaffected
  • Official CLI installation path doesn't rebuild on target machine or run compatibility gates. When target machine's dsh differs from build anchor API, issues surface at startup or invocation; CLI-free replica path (pnpm install-profile) rebuilds first with tiered gates

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/siegfly/dsh-deepseek-vision)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory