Foreword

In plugin-based runtime environments like DSH, a common issue is that text-only models don’t accept images, but developers often need to pass screenshots, receipts, and interface text to models for processing. Common approaches include configuring the model as multimodal or directly sending image bytes to a remote model API. The maxwell-feng/dsh-windows-ocr plugin introduces another method: first using Windows.Media.Ocr locally to recognize images on Windows, then sending the recognized text to the model. This article introduces its features, installation methods, and important notes.

What Is This

maxwell-feng/dsh-windows-ocr is a DeepSeek Harness (dsh) plugin maintained by maxwell-feng, licensed under the MIT license.

Its purpose is to allow text-only models to accept attached images. The plugin first uses Windows’ built-in OCR engine Windows.Media.Ocr to locally recognize images, then sends the recognized text to the model. For true vision models, passing through the original image bytes is an optional behavior.

Core Features

The following are verified plugin capabilities:

  • Allows text-only models to accept attached images.
  • Uses Windows.Media.Ocr to locally recognize images.
  • By default, only sends the recognized text to the model API, not the original image bytes.
  • Supports optional passthrough: true to let true vision models receive original image bytes.
  • No need to change the model to input: [text, image] in settings.yaml.
  • Supports any provider/model in dsh; by default, it performs OCR on attached images before requests leave the local machine.
  • Fail-closed: When the plugin is not loaded, the model remains text-only and rejects image attachments.
  • Missing attachments are replaced with refusal text blocks, not raw images.
  • Provides configuration options: language, passthrough, ocrScript, timeoutMs, and maxCacheEntries.
  • The npm-installed version is pre-built with Sigstore provenance, requiring no source building or allowBuilds.

Installation and Enabling

Before installation, ensure the environment meets the requirements: Windows 10/11, Windows PowerShell 5.1+, and the Windows OCR language pack for the target language; Chinese requires a available Chinese language pack; dsh and a profile already exist, with package.json declaring Node.js >= 20. The README notes the tested version is dsh 0.1.0-rc.8.

Install from npm

First, run the following command to install the plugin into the web profile:

dsh plugin --profile web add @maxwell-feng/dsh-windows-ocr

If using a different profile, replace web with the profile name, such as tui.

The npm-installed version will automatically register the windows-ocr loader entry; do not manually add the same entry id.

Permanent Installation

If using source code or manual file setup, first prepare the plugin file path. The following example appends to the profile’s cordis.patch.yml:

- insert:
    - id: windows-ocr
      name: 'file:///C:/absolute/path/to/windows-ocr/lib/index.js'
      config:
        language: ''
        passthrough: false

Windows file paths must use file:// URLs; bare C:/... paths will be rejected by the loader.

Configuring passthrough: false means OCR all images by default; true allows vision models to receive unprocessed images.

After modification, restart dsh web.

Temporary Installation

For temporary installation, prepare similar rows in an overlay file first, then run:

dsh --profile web --patch C:/path/to/overlay.yml

This method does not modify the profile.

Overwriting Configuration

If a windows-ocr row already exists, use an id-targeted row to overwrite the configuration instead of inserting another row with the same name. Example:

- id: windows-ocr
  config:
    language: zh-Hans

Typical Usage

Follow these steps sequentially from installation to verification.

  1. After installation, start dsh web and check the startup logs for windows-ocr.

  2. Attach an image to a text model session.

  3. Observe whether the model responds with the recognized text.

When the model receives an image, each image block will be replaced with a text block similar to:

<image_ocr>
...
</image_ocr>

If an EADDRINUSE error occurs when starting dsh web, first run the following command to find and stop the old instance occupying port 3080:

netstat -ano | findstr :3080

Use Cases and Notes

Suitable use cases:

  • Running dsh on Windows 10/11 and wanting text models to process text from local images.
  • Preferring not to send original image bytes to the model API by default, only sending locally OCR-processed text.
  • Needing to switch between different provider/model in dsh without modifying model capability configurations individually.

Important notes:

  • Do not use both npm bundle and manual insert to register the same windows-ocr entry id; otherwise, dsh will fail to start with an error like duplicate loader entry id: windows-ocr.
  • passthrough: false is the default behavior, OCR-ing all images; only when explicitly set to passthrough: true will true vision models receive unprocessed images.
  • When the plugin is not loaded, it is fail-closed: the model remains text-only and rejects image attachments; missing attachments are replaced with refusal text blocks, not raw images.
  • The plugin runs with the current dsh process permissions; before installation, check the source code, dependencies, and MIT license.
  • Chinese OCR requires an available Chinese language pack; other languages also require the corresponding Windows OCR language packs.

Conclusion

The value of maxwell-feng/dsh-windows-ocr lies in localizing “text models processing images” through local OCR and text injection, sending only recognized text to the model API by default. The following links can be used to view the project:

  • Plugin directory page: https://www.skillhub.cn/plugins/maxwell-feng/dsh-windows-ocr
  • GitHub repository: https://github.com/maxwell-feng/dsh-windows-ocr