jiawood2006 Doc-OCR 文档识别 + 结构化
PDF / 扫描件 / 图片 → 可编辑文字 → 结构化数据。有文字层的 PDF 直接提取，扫描件自动 OCR（macOS Vision 自带，中英文），版面还原（多栏/复杂排版按阅读顺序重排，不是裸行输出），区域过滤（剔除页眉/页脚/水印），可搜索 PDF（扫描件写隐形文字层，可 Ctrl+F / 复制），OCR 后可用 LLM 抽取发票/合同字段、转表格。
与同类工具的关系：跨平台批量 OCR 可以看 Umi-OCR / PaddleOCR，生成可搜索 PDF 可以看 OCRmyPDF——本技能覆盖这两者的核心高频用途，且文件全程本机处理、零上传（仅在结构化抽取时调用 LLM API）。
📁 安装：
hermes skills install jiawood2006/hermes-skills/skills/doc-ocr或按 README 方式二复制 → 默认在~/.hermes/skills/utilities/doc-ocr/。以下命令基于该路径。
触发条件
用户提供 PDF/图片文件，要求：
- "提取文字""转文字""OCR"
- 处理扫描件、合同、发票、书页、截图
- "提取发票信息""合同要点""转成表格"（结构化）
使用步骤
1. 单个文件 → 文字
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 合同.pdf
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 发票.jpg
输出保存为 <输入名>_ocr.txt。
2. 批量目录（逐文件容错，坏文件不中断）
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py ./扫描件/ -o 全部.txt
# 批量完成输出汇总：成功 N/M + 失败清单（坏文件单独记录不中断整批）
3. Markdown 输出 / 多栏 PDF 强制版面还原
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 书.pdf --md
# 多栏 PDF 文字层乱序时，强制走 Vision OCR 版面还原：
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 双栏论文.pdf --md --force-ocr
4. 剔除页眉/页脚/水印带（--ignore-region）
扫描件常带页眉、页脚、水印、骑缝章文字，污染提取结果。按归一化比例剔除，不需要知道具体坐标：
# 去掉顶部 8% 和底部 6% 的文字带
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 合同.pdf --ignore-region "top=8%,bottom=6%"
# 也可组合 left= / right=（去掉左侧装订线区域的花边/水印）
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 扫描件.pdf --ignore-region "top=7%,bottom=5%,left=4%"
- 支持
top/bottom/left/right四边，比例为页面尺寸的百分比（也可写小数0.08） - 判定依据是文字块的中心点落在忽略带内
- 运行时打印
↳ 忽略区域剔除 N 块文字，可确认生效
5. 生成可搜索 PDF（--searchable-pdf）
扫描件变可搜索 / 可复制的 PDF：在原页面上写入隐形文字层，版面观感完全不变（对标 OCRmyPDF 的核心价值，本地零上传）：
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 扫描合同.pdf --searchable-pdf
# 输出：扫描合同_searchable.pdf（可在阅读器里 Ctrl+F 搜索、可选中复制）
# 配合区域过滤：把页眉页脚也排除在文字层之外
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 扫描合同.pdf \
--searchable-pdf --ignore-region "top=8%,bottom=6%"
- 文字块用 CJK 内置字体写入，中文可正常检索（已实测）
- 仅 PDF 输入适用（图片输入会跳过并提示）
- 原文件不动，另存
_searchable.pdf
6. 指定识别语言（--lang）
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 日文.pdf --lang ja,en
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 繁体.pdf --lang zh-Hant,en
缺省 zh-Hans,en（简体中文 + 英文）。
7. 结构化抽取（发票/合同/表格，需 LLM key）
# 先 OCR，再抽取字段
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 发票.jpg
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/docstruct.py 发票_ocr.txt --type invoice
# 合同字段（甲方/乙方/金额/工期/违约条款）
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/docstruct.py 合同_ocr.txt --type contract
# 表格 → CSV
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/docstruct.py 表格_ocr.txt --type table -o 表格.csv
--type invoice：发票号码/日期/金额/税额/价税合计/购买方/销售方/税号--type contract：合同名称/甲乙双方/签订日期/金额/付款方式/工期/违约条款--type table：自动识别行列结构 → CSV- 输出友好显示 + 可保存 JSON/CSV（
-o）
依赖（首次使用时安装）
pip3 install pymupdf pyobjc-framework-Vision
# 结构化抽取需 LLM key（环境变量 LLM_API_KEY 或 ~/.deai_writer.conf）
注意：OCR 依赖 macOS Vision（仅 macOS 可用）。Linux 需另装 tesseract 等引擎。
已知陷阱
- 扫描件判定：PDF 文字层 <20 字自动走 OCR，正常 PDF 直接提取。
- 版面还原：Vision OCR 按文字框坐标重排（从上到下、同行从左到右）；双栏印刷体会被当成"先左栏再右栏"处理，适合论文/报告，杂志花式排版可能仍乱序——用
--force-ocr+ 目测。 - 手写体：Vision 对印刷体/清晰手写效果好，潦草手写不保证。
- 隐私卖点：文件在本机处理，不上传第三方（结构化抽取会调 LLM API，注意敏感文件）。
- 字段缺失：docstruct 对缺失字段填 null 不编造，OCR 质量差时字段会少。
- 批量容错：目录模式单文件失败会记录进汇总，不会中断整批。
- 区域过滤是"按比例"不是"按内容"：
--ignore-region剔除的是版面带，不是识别特定文字。如果页眉只占 3% 就别设 top=8%，会误删正文首行。先跑一次不带过滤的，看清页眉/页脚位置再定比例。 - 可搜索 PDF 依赖原图质量：文字层是按 OCR 结果写的，OCR 认错的字搜索时也认错（字形和原图仍一致）。要更高准确率就换更清晰的扫描源。
- 可搜索 PDF 是另存新文件：原 PDF 不会被改动；
_searchable.pdf体积略增（多了一层文字）。
快速验证 / Smoke Test
# 安装验证（无文档在手也能跑）
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py --help
# 有任意 PDF/图片时的真实验证
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 任意文档.pdf --md
# 期望：输出 *_ocr.md，含可编辑文字