扫描件 PDF 文字识别
> v0.2.0：新增子命令 ocr / batch、自动纠斜（--deskew）、去噪（--clean）、文本旁路（--sidecar）与批量汇总报告（ocr_report.csv）。
概述
扫描件本质是图片，无法选字。OCRmyPDF 调用 tesseract 识别并回写文字层，输出仍是 PDF。这是唯一一个需要系统级二进制（tesseract）的技能，其余 11 个纯 pip 即可。
何时使用
- PDF 是扫描图片、无法选中文字
- 需要让历史扫描件可被全文检索
- 有一堆扫描件要批量处理
- OCR 后配合 pdf-text-extract 抽表
快速使用
# —— 需先 cd 到本技能目录再运行 ——
# 环境自检（强烈建议先跑一次）
python3 scripts/ocr_pdf.py --doctor
# 单文件 OCR（默认中英文）
python3 scripts/ocr_pdf.py ocr 扫描件.pdf 可搜索.pdf
python3 scripts/ocr_pdf.py ocr 扫描件.pdf 可搜索.pdf -l eng # 仅英文
python3 scripts/ocr_pdf.py ocr 扫描件.pdf 可搜索.pdf --deskew # 自动纠斜
python3 scripts/ocr_pdf.py ocr 扫描件.pdf 可搜索.pdf --clean # 去噪去黑边
python3 scripts/ocr_pdf.py ocr 扫描件.pdf 可搜索.pdf --sidecar 文本.txt # 同步输出纯文本
# 批量 OCR 整个目录
python3 scripts/ocr_pdf.py batch 扫描件目录/ 输出目录/
# 完成后输出：ocr_report.csv（file/status/error 三列）+ 控制台成功/失败统计
python3 scripts/ocr_pdf.py batch 扫描件目录/ 输出目录/ --deskew --sidecar
系统依赖（一次安装）：
# macOS
brew install tesseract tesseract-lang
# Debian/Ubuntu
sudo apt install tesseract-ocr tesseract-ocr-chi-sim
依赖安装
# 提示：脚本用相对路径 scripts/，请先 cd 到本技能目录再运行
python3 -m pip install ocrmypdf
常见错误 / 注意
- 必须系统安装 tesseract + 对应语言包，否则脚本会明确报错并提示安装命令
- 中文识别需
tesseract-ocr-chi-sim（简体）/chi_tra（繁体） --clean依赖系统unpaper，缺失会导致该文件 OCR 失败（batch 下计入失败报告而非中断）- 大文件 OCR 较慢且吃内存；
skip_text已开启，已有文字层页会跳过 - 与另外 11 个纯 pip 技能不同，这个依赖系统二进制，发布说明需写清
实测验证（v0.2.0）
- 核心依赖：
ocrmypdf - 安装体积：🟡 102.4 MB（依赖闭包实测，中量级）
- 环境要求：需要外部二进制：tesseract 与 gs(Ghostscript) 为必需；pngquant / unpaper / jbig2 为可选。实测 macOS 常见缺 gs。
- 单元测试：
python3 -m unittest tests.test_ocr_pdf（须 cd 到本技能目录运行），8 项全过 - CLI 冒烟：已通过端到端实测
已验证行为
- ✅ --doctor：列出缺失项并给出对应平台安装命令
- ✅ 缺依赖时报错含安装指引，不会抛无意义的底层异常
- ✅ ocr() 正确把 --deskew / --clean / --sidecar 透传给 ocrmypdf.ocr()
- ✅ batch 在依赖缺失时单文件失败被记录为 error 而非整体崩溃；batch CLI 正常写出 ocr_report.csv
已知边界 / 坑
- ⚠️ 本机实测缺失 gs → brew install ghostscript
- ⚠️ pngquant / unpaper 可选项缺失不影响运行，仅影响体积与去噪效果
> 运行前建议先 python3 scripts/ocr_pdf.py --doctor 自检环境。
