littlewrite / dsh-local-ocr

dsh-local-ocr

English | 简体中文

An independent local OCR library and DeepSeek Harness tool plugin for macOS and Windows. It does not modify deepseek-harness, own a cache, or decide when OCR should run.

The native adapter uses @napi-rs/system-ocr, which exposes macOS system OCR and Windows Media OCR through one Node.js API. Its native work credits win-ocr-rs and mac-system-ocr.

Install

Requirements: Node.js 20 or newer, pnpm, and an installed DeepSeek Harness dsh command.

Install the plugin into the Web profile directly from GitHub:

npx -y github:littlewrite/dsh-local-ocr install

The installer adds the bundle to the selected Harness profile. Restart dsh web after installation. To select another profile:

npx -y github:littlewrite/dsh-local-ocr install --profile web

To remove it:

npx -y github:littlewrite/dsh-local-ocr uninstall --profile web

For local development, clone the repository and install its dependencies:

git clone https://github.com/littlewrite/dsh-local-ocr.git
cd dsh-local-ocr
pnpm install

The current native dependency supports macOS and Windows. Linux is not supported by this MVP.

DeepSeek Harness plugin

The bundle loads dsh-plugin/index.js. It registers one model-facing tool, local_ocr_image, and creates the OCR service without loading the native addon. The addon loads only when the model calls the tool.

Start Harness normally from the Harness repository:

cd /path/to/deepseek-harness
pnpm dsh web

When the plugin is loaded from a source checkout, it expects the Harness checkout to be the current working directory. Set DSH_HARNESS_ROOT only when it is loaded from another launcher or packaged installation.

Ask the agent to call local_ocr_image with an absolute local image path:

Please call the `local_ocr_image` tool instead of `read_image`.
Read all text from this local image:
/absolute/path/to/image.png

Library API

import { createOcrService } from './src/ocr.js'

const ocr = createOcrService()
const result = await ocr.recognize({
  path: '/tmp/image.png',
  languages: ['zh-cn', 'en-US'],
  mode: 'accurate',
  signal,
})

The result contains stable fields only:

{
  "text": "recognized text",
  "confidence": 0.8,
  "engine": "darwin-system-ocr",
  "durationMs": 12
}

An image with no detectable text returns an empty text value and confidence: 0. Set emptyWhenNoText: false to preserve the native no-text error.

Development

pnpm test

Tests inject a fake engine, so they do not require a host OCR runtime. Native smoke tests should run on each supported operating system.