Skip to main content

dsh-ocr-local

6Stars0Forks0Issues0Watchers

Local image-to-text OCR plugin based on PP-OCRv5 and ONNX Runtime for offline recognition. Automatically invokes when pasting images in TUI or Web.

Evidence4/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
JavaScript
License
NOASSERTION
Branch
main
deepseek-harnessdsh-pluginocronnxruntimepp-ocrv5

Install

cmdweb profile
$ dsh plugin --profile web add dsh-ocr-local

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 balcoz/dsh-ocr-local for me: review the repository at https://github.com/balcoz/dsh-ocr-local 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-Line Description

Add local image-to-text capability to DeepSeek Harness: paste screenshots, error dialogs, chat records, or document photos into the conversation, and the plugin automatically invokes the local PP-OCRv5 model to read the text. The entire recognition runs locally, images stay on the machine, and no vision LLM is required.

Core Features

  • Paste images in TUI terminal client and Web client, path automatically inserted into input box, text model automatically calls ocr_image to recognize text in images
  • Register ocr_image tool, pass in absolute image path to return recognition result (output by line, each line with confidence score)
  • Register ocr_setup tool, one-click to create Python virtual environment, install ONNX Runtime and other dependencies, download recognition model (~20MB), entire process is idempotent
  • Images saved to local cache ~/.dsh/ocr/cache, deduplicated by content hash, auto-cleaned by file count and days
  • Dark theme screenshots automatically processed with color inversion, lines with too small text or low confidence are marked with ⚠

Technical Implementation

  • Languages: Node.js (plugin host) + Python (OCR inference script), cordis plugin protocol
  • Key Dependencies: @deepseek-ai/cordis (host integration), @deepseek-ai/dsh-tools (tool registration), onnxruntime + opencv-python-headless + numpy (Python-side OCR inference), PaddleOCR PP-OCRv5 mobile model (ONNX format)
  • Architecture Pattern: Plugin provides both Node-side cordis plugin (dsh/index.js registers ocr_image/ocr_setup tools and /ocr/paste HTTP route) and browser-side lazy-CJS module (dsh/client.js listens for paste event and uploads image bytes to host route via fetch), automatically injected to Web side via dsh.client.inject field; Python script invoked by Node side via child_process.execFile, standard output returned as JSON
  • Entry Files: dsh/index.js (cordis plugin main entry), dsh/client.js (browser-side paste-to-path), ocr/ocr.py (PP-OCRv5 inference), ocr/setup.py (one-click bootstrap)

Use Cases

When the model cannot directly view images (text model, tight context window, vision bridge disabled), but you want the agent to read text from screenshots, error dialogs, chat records, or document photos, installing this plugin enables seamless "paste image" + "read text from image" workflow. It's especially suitable for sensitive screenshots—the image never leaves the local machine and doesn't depend on any cloud vision API.

Prerequisites and Compatibility

DependencyMin VersionDescription
Host DSHIntegrated via @deepseek-ai/cordis ^4.0.1 + @deepseek-ai/dsh-tools ^0.0.1-rc.1No separate DSH version field declared in package, provided by host at runtime
Node.jsNot declaredNo engines field declared in package, host dsh provides Node runtime
PythonOnly calls python3/python, no minimum version limitOn first use, will automatically create venv to install onnxruntime/numpy/opencv-python-headless
PlatformmacOS / Windows / LinuxTUI paste patch adapted for all three platforms, Linux Wayland requires wl-clipboard, X11 requires xclip
Native ModulesNoneOnly uses Node built-in modules (fs/crypto/path/child_process) and Python wheels (onnxruntime etc. installed via pip)

Installation

dsh plugin --profile web add dsh-ocr-local

Tip: DSH profiles are isolated from each other. For TUI client, install again and run installation script to configure paste key (./install.sh --profile <profile> or powershell -ExecutionPolicy Bypass -File install.ps1 -Profile <profile>).

Configuration Options

Config file located at ~/.dsh/profiles/<profile>/cordis.patch.yml, all options have default values, works without configuration.

ConfigTypeDescriptionDefault
autoOcrBooleanMonitor image attachments in conversation, auto-save and prompt model to call ocr_image for local recognitiontrue
pasteToPathBooleanWeb client "paste image auto-convert to path inserted into input box"true
pythonPathStringSpecify Python interpreter path for OCR; empty = auto-find via venv → DSH_OCR_PYTHON → python3/pythonNot set
modelDirStringModel storage directory~/.dsh-ocr/models
maxCacheFilesNumberMax number of cached pasted images to retain; exceed = evict oldest by modification time300
maxCacheAgeDaysNumberDays to retain pasted image cache; expired auto-cleaned30

Common environment variables:

VariablePurpose
DSH_OCR_MODELS_MIRRORModel download mirror prefix (set when downloads are slow in China, e.g., https://ghproxy.com/)
DSH_OCR_PYTHONSpecify which Python to use for OCR (default auto-find)
DSH_OCR_MODELSModel storage directory (default ~/.dsh-ocr/models)
DSH_OCR_VENVCustom venv directory (default ~/.dsh-ocr/venv)

FAQ

Q: First use error "environment not ready / missing dependencies" what to do?

A: Tell the agent "use ocr_setup tool to install OCR environment", the plugin will automatically create Python virtual environment, install onnxruntime/numpy/opencv-python-headless, download PP-OCRv5 model. Can also manually run python .../ocr/setup.py, entire process is idempotent and can be re-executed.

Q: Model download very slow or fails?

A: Set mirror prefix and re-run: DSH_OCR_MODELS_MIRROR=https://ghproxy.com/ python .../ocr/setup.py. Download includes sha256 verification, corrupted files will auto re-download.

Q: TUI client paste image no response?

A: First confirm terminal can read clipboard image: Windows/macOS works out of box; Linux Wayland needs wl-clipboard installed, X11 needs xclip, otherwise terminal cannot read clipboard image and paste will silently fail. After installing, paste should work.

Q: Web client paste image no response?

A: Confirm plugin is installed to web profile, config pasteToPath not changed to false, and dsh web restarted. Browser console will have [dsh-ocr] error messages.

Q: Recognition results have typos?

A: Look at ⚠ markers in output, lines with too small text or low confidence are marked. Try zooming in the original image, or ask agent to reconfirm the corresponding lines. PP-OCRv5 mobile has limited effect on long lines, artistic fonts, and blurry images.

Q: After plugin upgrade, functionality unchanged?

A: Restart dsh to reload plugin. After TUI upgrade if paste fails (plugin files overwritten), re-run installation script install.sh or install.ps1 (patch is idempotent).

Q: System prompts pip externally-managed-environment (PEP 668)?

A: Don't add --break-system-packages. Just use ocr/setup.py, it will automatically create a virtual environment, bypassing system Python restrictions.

Learning Curve

Beginner — After installation, just tell the agent "use ocr_setup to install environment" or "recognize this image" and it runs, no configuration needed; only edit cordis.patch.yml if you want to change paste key or cache strategy.

Known Issues and Limitations

  • Very small text (e.g., below 4px) or lines with low detection confidence are marked as low confidence, recognition results may be incorrect (see ocr/ocr.py:59-60)
  • TUI paste key only supports ctrl+v / ctrl+shift+v / alt+v three options, other combinations not recognized (see patch/apply-cc-tui-patch.mjs:23)
  • Web client single paste image size limit 16MB (PASTE_MAX_BYTES), returns 413 if exceeded
  • Linux Wayland paste image requires wl-clipboard, X11 requires xclip, otherwise terminal cannot read clipboard image and paste will silently fail (see docs/usage.md:108-114)
  • Model is only PP-OCRv5 mobile, effect is average for long paragraphs, artistic fonts, handwritten text, severely blurred or compressed images
  • autoOcr enabled by default, after disabling model will no longer auto-recognize pasted images (can still manually ask model to call ocr_image)

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/balcoz/dsh-ocr-local)

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