在 DeepSeek Harness（DSH）或智能体开发中，当模型需要处理图片或 PDF 却没有原生视觉输入时，OCR 是必不可少的步骤。调用云端 OCR 接口会产生费用且可能受网络限制。local-ocr 插件提供了一个基于 Windows 原生引擎的离线解决方案，将图片或 PDF 转换为结构化文本。
是什么¶
local-ocr 是一个离线本地 OCR 技能，专为 Agent 环境设计，即模型需要以 OCR 文本形式获取视觉信息。它优先使用 Windows 原生 OCR 引擎，并提供自动降级机制。
安装¶
在安装之前，请确保系统已安装 Python 3.11（这是必需的；3.14 在 onnxruntime 方面存在兼容性问题）。
dsh plugin --profile <profile> add github:Daive1119/local-ocr
用法¶
安装后（需要 DSH v1.1.0+），它向模型注册了一个 ocr 工具。开发者也可以直接调用脚本。
CLI 使用¶
# 图片或 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
参数¶
--json：结构化 JSON 输出（推荐）。--engine auto|win|rapid|tess：引擎选择（默认 auto）。--preprocess：图片预处理（放大 2x/灰度/对比度/降噪），用于低分辨率图片。--selftest：生成包含中文测试图的对比报告。
工作原理¶
插件实现了一个引擎优先级链和自动降级机制。
- 引擎选择：
- Windows 原生 (winocr)：首选引擎。调用
Windows.Media.Ocr。中文精度最高。 - RapidOCR：如果 win 不可用或返回空结果。
- Tesseract：最后的兜底方案。
- Windows 原生 (winocr)：首选引擎。调用
- 自动降级：如果 win 可用但输出为空（例如异常图片），脚本会静默继续尝试 rapid 或 tess，而不会报错。
- 输出：返回结构化 JSON。图片返回
text和lines（包含score），PDF 返回pages。
注意事项¶
- 依赖：需要
winocr和pillow。Tesseract 是可选的。需要安装 Windows 中文 OCR 语言包（zh-Hans-CN）。 - 置信度分数：Windows 原生 OCR API 不提供置信度分数。脚本将返回
score=100.0，但这仅表示“该行已返回”，并不代表质量完美。Tesseract 提供真实的置信度分数。 - 许可证：MIT 许可证。
- 兼容性：支持 PNG, JPG, JPEG, BMP, WebP, TIFF, GIF。
