mimo-vision
DeepSeek Harness (DSH) 原生插件：describe_image 工具，通过 ctx.fs / ctx.credentials 接口提供视觉桥接（图像 -> mimo-v2.5 -> 文本描述）
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add mimo-vision@0.1.0Mimo Vision 以 mimo-vision 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 中文
mimo-vision is a native plugin for DeepSeek Harness (DSH), package name mimo-vision. It registers a describe_image tool that sends an image to a mimo-v2.5-series multimodal model and returns the text description to the main model — a "vision bridge" built for main models (e.g. deepseek-v4-flash) that have no vision input of their own.
It is not a standalone process: it is a first-class citizen of DSH's "everything is a plugin" model. apply does exactly one thing — registers the capability as a first-class dsh tool. Dependencies, files, credentials, and subprocesses all go through dsh's defined capability seams; uninstalling cleans up cleanly.
apply(ctx) contains a single ctx.tools.register(defineTool(...)). register() returns a disposer; when the plugin fiber disposes, the tool is unregistered and its schema is automatically withdrawn from the system prompt. There is no leftover cleanup code — clean uninstall is a structural guarantee, not hand-written cleanup.inject declares dependencies: export const inject = ['tools', 'fs', 'credentials'] follows the pure Cordis effect spec — activation only happens once the seams are in place. ctx.get('subprocess') in transcode.ts is an optional capability with a default fallback, used at execution time, not activation time. This is "declared dependencies", not "probed dependencies".ctx.fs.resolve/stat/readBytes + ctx.emit('fs/observed'); credentials use ctx.credentials.resolve(credentialRef(...)) with no hand-rolled parsing; subprocess (transcoding) uses ctx.subprocess. The one exception: transcode temp files are written via node:fs to the system temp directory (see Known Limitations below).| Tool | Arguments | Description |
|---|---|---|
describe_image | path (required), question (optional) | Describes an image file and returns text |
Supported image formats:
.tif) / HEIC (.heif) / PSD / ICO / EXR / JP2 / JXL / AVIF — when ImageMagick is installed locally, these are transcoded to PNG before sending, downscaled to a ≤2048px long edge (saves tokens)Usage example (tell the model): Use describe_image to describe D:\photos\cat.png, focusing on what breed of cat it is.
ctx.credentials.resolve takes the first non-empty of OPENCODE_GO_API_KEY → OPENCODE_API_KEY (DSH credential layering: process env > ~/.dsh/.credentials.yaml > .env).ctx.fs.resolve (relative paths resolve against the session workspace cwd) → ctx.fs.readBytes (20 MiB cap); non-native formats (SVG/TIFF/HEIC…) are transcoded to PNG via ImageMagick (through the ctx.subprocess seam) and downscaled to a 2048px long edge → base64.mimo-v2.5-free) is tried first; on failure (non-2xx / timeout) it falls back to the paid Go route (mimo-v2.5) once per request; allowPaid: false disables the paid fallback.Design decisions are documented in adr/0002-dsh-native-plugin.md (which supersedes the earlier MCP approach, ADR-0001).
For
npx @deepseek-ai/dsh webor a globally installed DSH. The repo ships prebuilt artifacts (lib/index.js) — no build toolchain required.
Prerequisite: Node ^22.19 || >=24, and DSH already able to start.
mimo-vision declares dsh.bundle (see the dsh field in package.json), so dsh plugin add reconciles it as a bundle layer of the profile — installing the package, mounting the layer, and activating the tool happen in one step:
# from the npm registry (recommended once this package is published)
dsh plugin --profile web add mimo-vision
# from GitHub (source install, prebuilt lib/)
dsh plugin --profile web add github:wulusai2333/mimo-vision
If the repo is not on its default branch, use
github:wulusai2333/mimo-vision#<branch-or-tag>. This path relies on the dependency closure that DSH maintains in~/.dsh/profiles/node_modules(symlinking all@deepseek-ai/*seams to the dsh install tree), so the plugin's runtimeimport "@deepseek-ai/dsh-tools"etc. resolves to the same instance DSH uses — singleton-safe,register()/injectsemantics unchanged. GitHub-source installs require this repo to commit a prebuiltlib/(kept in sync withsrc/): pnpm installs the source withlib/included, no build runs, noallowBuildsneeded.
Manually copy the artifacts into the profile's plugin resolution root, then mount the patch in the profile's cordis.patch.yml (equivalent to automatic bundle mounting, but two manual steps):
# Windows PowerShell
$dst = "$env:USERPROFILE\.dsh\profiles\node_modules\mimo-vision"
New-Item -ItemType Directory -Path $dst -Force | Out-Null
Copy-Item package.json -Destination $dst -Force
Copy-Item cordis.patch.yml -Destination $dst -Force
Copy-Item lib -Destination $dst -Recurse -Force
# macOS / Linux
dst="$HOME/.dsh/profiles/node_modules/mimo-vision"
mkdir -p "$dst"
cp package.json "$dst/"
cp cordis.patch.yml "$dst/"
cp -r lib "$dst/"
Then edit ~/.dsh/profiles/web/cordis.patch.yml and add:
- insert:
- id: tool-vision
name: 'mimo-vision'
config:
allowPaid: true
Put an opencode key in ~/.dsh/.credentials.yaml (OPENCODE_GO_API_KEY preferred, OPENCODE_API_KEY as fallback):
OPENCODE_GO_API_KEY: sk-...
You can also put it in the environment of the process that starts DSH (
OPENCODE_GO_API_KEY=... dsh web). Credential seam layering priority: process env >.credentials.yaml>.env.
A restart is required on first integration (so the process imports the new package). After that, changes to this plugin's code or config such as allowPaid hot-reload without restart.
After restarting, verify: mimo-vision should appear in DSH's settings, with describe_image among the available tools; or just tell the model "use describe_image to describe some image" and try it.
dsh plugin remove takes the package name (the key in the profile's dependencies), not the install source:
dsh plugin --profile web remove mimo-vision
Passing
github:wulusai2333/mimo-visionerrors withERR_PNPM_CANNOT_REMOVE_MISSING_DEPS("no such dependency found") — the dependency is recorded by package namemimo-vision, soremoveneeds that key. The command removes both the dependency and the bundle layer.
| Field | Default | Description |
|---|---|---|
allowPaid | true | Whether to fall back to the paid route after the free route fails |
freeBaseUrl | https://opencode.ai/zen/v1 | Free route base URL |
freeModel | mimo-v2.5-free | Free route model |
paidBaseUrl | https://opencode.ai/zen/go/v1 | Paid route base URL |
paidModel | mimo-v2.5 | Paid route model |
A minimal registration only sets allowPaid; everything else uses the defaults:
- insert:
- id: tool-vision
name: 'mimo-vision'
config:
allowPaid: false
To modify the plugin source, put it into the DSH source tree and go through the repo gates:
# 1. Copy this repo as packages/vision/tool-vision
cp -r /path/to/mimo-vision <dsh>/deepseek-harness/packages/vision/tool-vision
# 2. Install and verify (tsc typecheck + vitest unit tests + oxlint)
cd <dsh>/deepseek-harness
pnpm install
npx tsc -b packages/vision/tool-vision # typecheck
npx vitest run packages/vision/tool-vision # unit tests
npx oxlint packages/vision/tool-vision # lint
# 3. Produce lib/index.js (prebuilt artifacts)
cd packages/vision/tool-vision
pnpm run build
pnpm run buildrunstsc --buildfirst (emitting the intermediatelib/types/*.jsthat tsdown consumes) and then bundleslib/index.js/lib/invariant.js. Steps 2/3 can also be run inside the package withpnpm run test/pnpm run typecheck/pnpm run build(the scripts are inpackage.json).
Note: the
@deepseek-ai/dsh-*seams are versioned by the DSH dependency closure, not by this package. The peer dependencies are marked optional so a standalonenpm install mimo-visionsucceeds, but the plugin only runs inside DSH (where the closure provides those seams as a singleton). For development, either use the prebuilt artifacts from "Quick install" above, or run it from source inside the monorepo.
Any failure (no key, unsupported format, both routes failing, file missing / not a regular file, over the limit, non-image response) is returned as a tool-level error: execute throws, the registry materializes isError, the process does not exit and the session does not break.
ctx.fs sandbox: when non-native formats (SVG/TIFF/HEIC…) are transcoded via ImageMagick, the source bytes and the resulting PNG go through node:fs to the system temp directory (os.tmpdir()), because ctx.subprocess needs real OS paths to feed the local magick, while ctx.fs's FsTarget may be an abstract/remote/sandboxed path. This bypasses the dsh-fs-sandbox file sandbox policy; the temp directory is deleted immediately after conversion. It only triggers when ImageMagick is installed locally and a transcode format is requested — native formats (PNG/JPEG/GIF/WebP/BMP) never take this path.lib/ must stay in sync with src/: GitHub-source installs load the committed lib/index.js directly and never build at install time. After changing src/, rebuild and commit lib/, or the deployed version loads stale artifacts.ctx.credentials.resolve — never printed, never written to disk, never directory-scanned;Authorization: Bearer ...;ctx.fs and sent straight as base64, never written to disk (non-native formats are routed through the system temp dir during transcoding and deleted immediately after).MIT