local-ocr: Offline Local OCR Skill

In DeepSeek Harness (DSH) or agent development, OCR is an essential step when a model needs to process images or PDFs but does not have native visual input. Calling cloud OCR APIs may incur costs and can be subject to network restrictions. The local-ocr plugin provides an offline solution based on the Windows native engine, converting images or PDFs into structured text.

What It Is¶

local-ocr is an offline local OCR skill designed for agent environments, where a model needs to obtain visual information as OCR text. It preferentially uses the Windows native OCR engine and provides an automatic fallback mechanism.

Installation¶

Before installing, ensure that Python 3.11 is installed on the system (this is required; 3.14 has compatibility issues with onnxruntime).

dsh plugin --profile <profile> add github:Daive1119/local-ocr

Usage¶

After installation (requires DSH v1.1.0+), it registers an ocr tool with the model. Developers can also invoke the script directly.

CLI Usage¶

# 图片或 PDF，输出结构化 JSON（推荐）
python scripts/ocr_tool.py "<File Path>" --json

# 或使用批处理包装
scripts\ocr.bat "<File Path>" --json

# 自测：生成中文测试图并对比各引擎
python scripts/ocr_tool.py --selftest

# 指定引擎 / 低清图预处理
python scripts/ocr_tool.py "<Image>" --json --engine tess --preprocess

Parameters¶

--json: structured JSON output (recommended).
--engine auto|win|rapid|tess: engine selection (default auto).
--preprocess: image preprocessing (2x upscaling/grayscale/contrast/noise reduction) for low-resolution images.
--selftest: generates a comparison report containing a Chinese test image.

How It Works¶

The plugin implements an engine priority chain and an automatic fallback mechanism.

Engine selection:
- Windows native (winocr): the preferred engine. It calls Windows.Media.Ocr and provides the best Chinese accuracy.
- RapidOCR: used when win is unavailable or returns empty results.
- Tesseract: the final fallback option.
Automatic fallback: if win is available but produces empty output (for example, due to an abnormal image), the script silently continues trying rapid or tess without raising an error.
Output: returns structured JSON. For images, it returns text and lines (including score); for PDFs, it returns pages.

Notes¶

Dependencies: requires winocr and pillow. Tesseract is optional. The Windows Chinese OCR language pack (zh-Hans-CN) must be installed.
Confidence scores: the Windows native OCR API does not provide confidence scores. The script will return score=100.0, but this only indicates that “the line was returned” and does not mean the result is perfect. Tesseract provides real confidence scores.
License: MIT license.
Compatibility: supports PNG, JPG, JPEG, BMP, WebP, TIFF, and GIF.