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，含可编辑文字