Umi-OCR 转 Markdown（umi-ocr-to-md）
把一整批扫描件 PDF / 图片批量 OCR，并在源文件同目录生成同名 .md，例如：
D:\扫描件\合同A.pdf → D:\扫描件\合同A.md
D:\扫描件\发票1.png → D:\扫描件\发票1.md
完全离线本地识别（引擎在你自己电脑上跑），不上传任何数据，适合合同、票据、公文、资料归档等场景。
⚠️ 第一步：安装 Umi-OCR（首次使用必看）
本技能不自带 OCR 引擎，依赖免费开源的 Umi-OCR（MIT 协议，无需注册、无限制、无广告）。请按系统选择下载方式：
| 下载渠道 | 地址 | 说明 |
|---|---|---|
| GitHub Releases（官方） | <https://github.com/hiroi-sora/Umi-OCR/releases/latest> | 全球可用；选 Umi-OCR_v2.x.x_win64.7z 或 .7z.exe 自解压包 |
| 蓝奏云（国内推荐） | <https://hiroi-sora.lanzoul.com/s/umi-ocr> | 国内免注册、下载快 |
| SourceForge | <https://sourceforge.net/projects/umi-ocr> | 备选镜像 |
| Scoop（极客） | scoop bucket add extras && scoop install extras/umi-ocr |
适合已经用 Scoop 的用户 |
安装步骤（Windows）：
- 下载后解压（绿色软件，无需安装），得到
Umi-OCR文件夹 - 双击
Umi-OCR.exe启动一次，首次启动会自动在UmiOCR-data/plugins/下初始化插件引擎，看到界面即安装成功，可直接关闭 - （可选验证）插件引擎位于：
Umi-OCR\UmiOCR-data\plugins\win7_x64_PaddleOCR-json\PaddleOCR-json.exe
> 💡 确认引擎是否就绪：技能会自动在下列位置探测引擎——
> 脚本目录、%LOCALAPPDATA%\Programs\Umi-OCR、C:\Program Files\Umi-OCR、
> C:\Program Files (x86)\Umi-OCR、~/Downloads/Umi-OCR、~/Desktop/Umi-OCR。
> 若安装在其他位置，用 --plugin-dir 显式指定即可。
第二步：运行批量识别
在你想处理的目录（或单个文件）上运行脚本：
# 处理整个目录（递归扫描所有 PDF）
python umi_scan2md.py --dir "D:\扫描件"
# 同时处理 PDF 和图片
python umi_scan2md.py --dir "D:\扫描件" --pattern *.pdf *.png *.jpg
# 处理单个文件
python umi_scan2md.py --file "D:\scan\a.png"
# 先预览哪些文件会被处理（不实际执行）
python umi_scan2md.py --dir "D:\扫描件" --dry-run
参数说明
| 参数 | 默认值 | 说明 |
|---|---|---|
--dir DIR |
无 | 要处理的目录（递归遍历） |
--file PATH |
无 | 处理单个文件（优先于 --dir） |
--pattern |
*.pdf |
匹配模式，可多个：*.pdf *.png *.jpg *.jpeg *.bmp *.tif *.webp |
--workers N |
4 |
并行引擎数，CPU 强可调大 |
--dpi N |
170 |
PDF 渲染分辨率，清晰度不够可调大到 200 |
--chunk N |
100 |
大 PDF 每个分片页数 |
--dry-run |
关 | 只列出待处理文件，不执行 |
--plugin-dir |
自动 | 手动指定 PaddleOCR-json 引擎目录 |
运行要求
- Python 3.9+；处理 PDF 需要
PyMuPDF（fitz），处理图片需要Pillow：
bash pip install PyMuPDF Pillow - Windows 7+ / 解压即用的 Umi-OCR。
输出说明
- 每个源文件 → 源文件同目录下同名
.md，Markdown 结构：
```markdown
# 合同A.pdf（OCR识别，共3页）
## 第 1 页
（识别出的文字……）
``
- 若源文件已有同名.md且大于 200 字节，自动跳过（**断点续跑**，可中断后重跑）
- 大 PDF 按--chunk分片产出.partNNNNN临时文件，全部完成后自动合并并清理
- 进度日志写入脚本旁的umi_scan2md_progress.log`
常见问题
-
提示"未找到 PaddleOCR-json 引擎"？
按上面第一步安装 Umi-OCR 并启动一次；或在命令中加--plugin-dir "你的Umi-OCR目录\UmiOCR-data\plugins\win7_x64_PaddleOCR-json"。 -
识别结果里有顺序错乱 / 表格列对不齐？
OCR 对排版复杂的表格、旋转文字还原有限。关键数字请以原件为准。 -
速度太慢？
加大--workers；或调低--dpi（160 足够中文公文）；每页约 0.5~1 秒属正常。 -
图片是 CMYK / 带透明通道？
脚本会自动归一化转 RGB 后再识别，无需预处理。 -
Program Files 下安装报 PermissionError？
将Umi-OCR文件夹整体复制到你的工作目录（如D:\tools\Umi-OCR）再运行。
已验证环境
Windows + Umi-OCR v2.x + PaddleOCR-json 管道协议（{"image_base64": "..."} 请求 / {"code":100} 响应），
每引擎一个子进程、4 并发在真实合同扫描件上跑通（分片→合并→断点续跑）。
