vision-translation-dsh

vision-translation-dsh — native dsh adapter

A native dsh (DeepSeek Harness) Cordis plugin that lets any dsh profile ground images through the vision-translation pipeline. It registers one tool, vision_translate, and returns a structured <vision-context> block that the main model reasons over.

Chosen npm package name: vision-translation-dsh (checked free on the npm registry at implementation time via npm view vision-translation-dsh). This adapter lives in the repo at adapters/dsh/. For an MCP-based alternative see adapters/mcp/.

Discoverability (official dsh plugin tag)

Per the dsh README, plugin repos get discovered through the dsh-plugin topic and the npm keywords of the published package. This adapter ships the required tags:

• GitHub topic: dsh-plugin (add it on the repository's About/Topics page).
• npm keywords: dsh, dsh-plugin, deepseek-harness, deepseek-harness-plugin, cordis, cordis-plugin, vision, vision-translation, visual-primitives, mcp, grounding.

The dsh profile installs the plugin by package name (vision-translation-dsh) via the bundle patch, so discoverability does not affect the plugin id or tool id (vision-translate).

How it works

The plugin is the thin non-Python shell the architecture prescribes (ADAPTERS.md, CONTRIBUTING.md):

dsh agent ──tools──▶ vision_translate(image, question?, model?, max_objects?)
                          │  (uses the dsh attachment ref directly)
                          ▼
                    spawn `python cli.py`  (PROTOCOL v1 stdin envelope)
                          │  b64 envelope (attachment) or image.path
                          ▼
                    core (vision_translation.py) → <vision-context>

Key difference vs the MCP preset: the dsh Web UI hands images to the model as ImageBlock attachments — an opaque sha256:<hex> reference, not a file path. A stdio MCP tool can only ever receive strings, so the MCP path cannot see Web-uploaded images. This native plugin resolves the ref through ctx.attachments.readImage and ships the bytes to the CLI over a stdin b64 envelope — no shared filesystem required. This is the host integration the ADAPTERS.md registry marks as the native-plugin trigger.

Install

With a dsh workspace, add the package as a profile dependency and merge the bundle patch:

npm add vision-translation-dsh          # or pnpm add / yarn add

Then append the - insert: block from cordis.patch.yml to your profile's cordis.patch.yml (e.g. ~/.dsh/profiles/web/cordis.patch.yml) or mount it as a deployment bundle patch. The block registers the plugin row id: vision-translate for the vision-translation-dsh package.

Zero runtime dependencies; the only peer packages are dsh's @deepseek-ai/dsh-tools and @deepseek-ai/dsh-attachment, which any dsh profile already provides.

Profile configuration

config key	default	meaning
cliPath	"" (auto)	Absolute path to cli.py. Resolution order: cliPath → env VISION_TRANSLATION_CLI → package-relative ../../cli.py (in-repo adapters/dsh layout).
pythonBin	"python3"	Python binary used to run cli.py.
toolCallTimeoutMs	120000	Cooperative tool-call timeout; also the CLI kill timer.

Merging via the bundle patch:

- insert:
    - id: vision-translate
      name: vision-translation-dsh
      config:
        cliPath: ""            # "" = auto-detect
        pythonBin: "python3"
        toolCallTimeoutMs: 120000

Tool usage

vision_translate(image, question?, model?, max_objects?)

• image — required. A local absolute/relative file path or a dsh image attachment reference (sha256:<hex> / attachment:sha256:<hex>).
• question — optional guiding question for the parse focus.
• model — optional auxiliary VLM override (empty → the CLI's default chain).
• max_objects — optional primitive cap (1..16, default 16, clamped).

Returned value is a string: the <vision-context> text when vision succeeded, or an explicit vision unavailable (reason: …) message when it could not produce context (no key, VLM down, …). When the result says vision is unavailable, tell the user you cannot see the image — do not guess or fabricate it. error states surface as a failed tool call.

Comparing with the MCP preset

axis	MCP preset (adapters/mcp/)	native plugin (this adapter)
image input	local file path only	file path or dsh attachment ref (Web uploads work)
process	one stdio MCP server per host	spawns python cli.py per call only; no server
lifecycle	long-lived server process	Cordis plugin, HMR with the profile
bytes	CLI reads the file	b64 stdin envelope for attach-ments; path for files
deps	mcp + venv	zero runtime deps (peer-only)

Privacy

• Images are sent to the configured OpenRouter auxiliary VLM (default xiaomi/mimo-v2.5) by the Python core. See vision_translation.py.
• The API key is never hardcoded or read by this plugin. The CLI resolves it itself, in order: process env OPENROUTER_API_KEY, ~/.hermes/.env, or ~/.env (see cli._ensure_key / PROTOCOL.md).
• No image bytes, OCR text, or full request is written to logs.

Development / test

Node ≥ 20 required (uses node:test). Tests are offline and dependency-free:

cd adapters/dsh
npm test        # = node --test "tests/**/*.test.js" (Node ≥ 20 built-in glob)

npm pack --dry-run verifies the publishable tarball (only lib/, cordis.patch.yml, README.md package.json contents).

License

MIT © 2026 Binglun Li. See LICENSE.