# deepseek-visionary

> Provides DeepSeek Harness with DeepSeek web visual model native tools (image recognition/OCR/login) and text model image bridging, no API Key required.

## Metadata

- Author: [@xlight](https://github.com/xlight)
- Repo: <https://github.com/xlight/deepseek-visionary.git>
- GitHub: [xlight/deepseek-visionary](https://github.com/xlight/deepseek-visionary)
- Stars: 13
- Language: Rust
- Topics: `agent`, `deepseek`, `deepseek-harness`, `dsh-plugin`, `harness`, `mcp`, `mcp-server`, `skills`
- Forks: 2
- Open Issues: 2
- Last push: 2026-08-18T04:31:39.000Z
- Added: 2026-08-17T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:xlight/deepseek-visionary#path:packages/dsh-plugin
```

## Wiki

## One-Sentence Pitch
DSH plugin that wraps DeepSeek web version vision and OCR capabilities into host-level native tools (no API Key required), and provides bridging capability for "text-only models rejecting pasted images".

## Core Capabilities
- Register 5 DSH native tools: `deepseek_vision` (image recognition, supports multi-image/continued chat), `deepseek_ocr` (text extraction), `deepseek_vision_status` (login status), `deepseek_vision_login` (browser auto-login), `deepseek_vision_logout` (clear credentials)
- Reuse `visionary-server` Rust binary for heavy lifting: PoW, upload, fork, HIF, SSE; plugin only handles parameter mapping and JSON parsing
- Execute directly within host process (not via bash sandbox), so browser login and multi-round session continuation are not restricted by workspace write permissions
- Auto-bridge pasted images for text-only models (e.g., `deepseek-v4-flash`): save to `pastedDir` and rewrite as guiding text, then let agent call `deepseek_vision` for analysis
- Settings panel and `$DSH_HOME/settings.yaml` dual entry points, modifications hot-reload instantly without DSH restart
- Bridge supports `deterministic` mode: directly invoke CLI for analysis and inject as "untrusted evidence" into model messages

## Technical Implementation
- **Language**: Node.js (ESM, `"type": "module"`)
- **Key Dependencies**: `@deepseek-ai/dsh-tools` (`defineTool`), `@deepseek-ai/dsh-settings` (`installSettingsSection`), `@deepseek-ai/dsh-attachment`, `@deepseek-ai/cordis` + `@deepseek-ai/schemastery` (runtime config schema)
- **Architecture Pattern**: Cordis plugin, registers 3 plugin lines via `packages/dsh-plugin/cordis.patch.yml` in `dsh.profile.bundles` overlay (`visionary-vision`, `visionary-image-bridge`, `visionary-settings-card`); `exec.signal`联动 with subprocess `kill` for cancellable timeouts
- **Entry File**: `packages/dsh-plugin/lib/index.mjs` (main toolset), subpaths `lib/image-bridge/index.mjs`, `lib/settings-card/index.mjs`

## Use Cases
For developers in DeepSeek Harness who want models to "understand" user-pasted images, screenshots, and documents, but don't want to provide their own API Key or are limited by bash sandbox. Especially suitable for users of text-only models (e.g., `deepseek-v4-flash`) who want image input support, and scenarios requiring multi-round follow-up questions on the same image across multiple tool calls.

## Prerequisites & Compatibility
| Dependency | Minimum Version | Description |
|---|---|---|
| DSH Host | `^0.1.0-rc.6` | peerDependencies lock dsh-tools / dsh-llm / dsh-attachment / dsh-settings; cordis ^4.0.1 |
| Node | `>=20` | from `package.json#engines.node` |
| Platform | macOS / Windows / Linux | Plugin itself cross-platform; Windows additionally parses npm shim to locate exe in `.bin_real/` |
| Native Modules | None | No native compilation dependencies, but requires host-executable `visionary-server` binary |
| `visionary-server` Binary | ≥0.5.x | 0.5.x fixes the old issue of reporting `CONTENT_EMPTY` for images without OCR text |

## Installation
```bash
dsh plugin --profile web add github:xlight/deepseek-visionary#path:packages/dsh-plugin
```

## Configuration Options
`visionary-vision` namespace (vision tool config):

| Config | Type | Description | Default |
|---|---|---|---|
| `binaryPath` | string | Absolute path to `visionary-server` binary; empty triggers lazy resolution via `DEEPSEEK_VISIONARY_BIN` → `PATH` order | `""` |
| `modelType` | enum | Upload pipeline for `deepseek_vision`: `vision` (full vision understanding) or `ocr` (text extraction only); switching takes effect instantly | `vision` |
| `loginTimeoutSeconds` | number | Browser login wait timeout (seconds), can be overridden by `DEEPSEEK_LOGIN_TIMEOUT` env var | 600 |
| `visionTimeoutMs` | number | Timeout for single `deepseek_vision` / `deepseek_ocr` call | 300000 |
| `statusTimeoutMs` | number | Timeout for `status` / `logout` calls | 60000 |

`visionary-image-bridge` namespace (image bridge config):

| Config | Type | Description | Default |
|---|---|---|---|
| `enabled` | boolean | Master switch; when off, fully restores host's original "text model rejects images" behavior | `true` |
| `routes` | array | Provider/model list for bridge routing; empty array = all routes active | `[]` |
| `pastedDir` | string | Directory for image persistence, dir permission 0700 / file 0600, supports `~` | `~/.deepseek-visionary/pasted` |
| `promptTemplate` | string | Guiding template (agentic mode), **must contain `{path}` placeholder** (missing will be rejected by validation) | Built-in default with "untrusted evidence" annotation |
| `retainHours` | number | Hours to retain persisted copies; `<= 0` means no cleanup | 168 (7 days) |
| `scope` | enum | `text-only` (bridge text models only) or `also-vl` (VL models also go through bridge rewrite) | `text-only` |
| `mode` | enum | `agentic` (rewrite as guiding text) or `deterministic` (bridge directly calls CLI for analysis and injects "untrusted evidence" annotation) | `agentic` |
| `cleanPasted` | boolean | Manual cleanup trigger: set to `true` to clean all copies in pastedDir and auto-reset to `false` | `false` |

## FAQ

**Q: Tools don't appear in DSH tool list after installation. What should I do?**

A: Confirm installation via `dsh plugin --profile web add` was successful and DSH has been restarted (bundle loading requires restart). Use `dsh --profile web --dump-config` to check if `@xlight-oss/visionary-dsh` layer appears, containing both `visionary-vision` and `visionary-image-bridge` lines.

**Q: Do I need a DeepSeek API Key?**

A: No. This plugin calls DeepSeek web version vision model (chat.deepseek.com), reusing web-side credentials via browser auto-login; run `deepseek_vision_login` to complete login before first use, credentials saved to `~/.deepseek-visionary/config.json`, shared with skill/CLI/MCP paths.

**Q: Text-only model rejects pasted images. How to enable bridging?**

A: `visionary-image-bridge` is enabled by default (`enabled: true`). If disabled, go to "Settings → Left Nav → Visionary" to re-enable `enabled`; if `routes` is explicitly configured, add current session's provider/model to whitelist. Settings panel changes don't require DSH restart.

**Q: Where are images and session data saved? Is there automatic cleanup?**

A: Bridge saves pasted images to `~/.deepseek-visionary/pasted` (dir permission 0700, file 0600), lazy cleanup per `retainHours` default 7 days; original image bytes in host attachment library are permanently retained, unaffected by `retargetHours`, to fully delete clear the corresponding session.

**Q: How to uninstall the plugin?**

A: Use `dsh plugin --profile web remove @xlight-oss/visionary-dsh` to uninstall and restart DSH. After uninstall, text-only model pasted images will restore to host's original behavior (direct rejection).

**Q: `deepseek_vision` reports `File ... processing failed: status=CONTENT_EMPTY`. What to do?**

A: This is a known upstream binary issue: backend performs OCR text extraction on uploaded images, pure illustrations, gradients, dark images without text get marked `CONTENT_EMPTY`. Fixed in `visionary-server ≥0.5.x` (no longer aborts, continues to vision model). Please reinstall the latest binary per README instructions.

**Q: Which operating systems are supported? How to install the binary?**

A: Plugin itself is cross-platform. `visionary-server` provides installation scripts for macOS, Linux, Windows (one-click install script, Homebrew, `npm install -g`); on Windows, plugin additionally parses npm shim (`.cmd` / `.ps1`) text to locate actual `.bin_real/visionary-server.exe` to avoid losing stdout pipe and orphan processes.

## Learning Curve
Beginner — install and use, tools automatically appear in DSH; only enter settings panel to adjust configuration when default behavior doesn't meet expectations (e.g., only want to bridge specific models, want to disable deterministic mode).

## Known Issues & Limitations
- Upstream binary old version (<0.5.x) reports `CONTENT_EMPTY` and aborts for images without OCR text (pure illustrations/gradients/solid colors); users must upgrade `visionary-server` to ≥0.5.x for normal use
- Persisted copies (`pastedDir`) are independently cleaned per `retainHours`, separate from host attachment library's permanent retention policy: cleanup may delete old session referenced path copies, causing expired paths when user revisits old sessions for re-analysis; mitigate by increasing `retainHours` or setting to `<= 0`
- On Windows, `binaryPath` resolution depends on shim text matching `node_modules\@xlight-oss\visionary-server\run-visionary-server.js` pattern; if installed via unconventional methods (e.g., manual rename/custom directory structure), binary may not be found and return installation guide error
- Custom `promptTemplate` must contain `{path}` placeholder, missing will be rejected on both settings panel write and load (fail-loud); when customizing, must preserve "untrusted evidence" framework to avoid prompt injection surface
- Settings panel Visionary entry depends on host `webServer` / `settings` services; read-only deployments or hosts without Web panel enabled will show "Settings service unavailable"
- `settings-card` plugin line provides independent `/visionary/api/settings.*` routes (loopback + Origin verification), intended to bypass host `settings.describe` whitelist for third-party namespaces; disabling this plugin line makes panel unavailable but doesn't affect tools and bridge lines

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [deepseek-visionary](https://deepseek-plugin.org/plugins/xlight/deepseek-visionary/packages/dsh-plugin)
Wiki generated by AI (model: `MiniMax-M2.5`)