在 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。
