2 jiawood2006

doc-ocr Skill

文档识别+结构化。用户提供 PDF/扫描件/图片(合同、发票、书页、截图),需要提取文字、转成可编辑文本、生成可搜索 PDF、剔除页眉页脚水印、或抽取结构化字段(发票号码/合同金额/表格)时使用。扫描件自动 OCR(macOS Vision,中英文),OCR 后可接 LLM 抽取发票/合同关键字段或转表格。Document OCR: extract editable text from PDFs, scans, images — plus searchable-PDF output, header/footer/watermark region filtering, and structured field extraction (invoices, contracts, tables) via LLM.

安装方式:把技能目录放入 ~/.claude/skills/(Claude Code)或在 claude.ai 设置中启用;也可复制右侧安装命令一键添加。

查看源码

技能指令原文(SKILL.md)

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

配合站内内容