jiawood2006/hermes-skills

Doc-OCR ドキュメント認識 + 構造化

PDF / スキャン / 画像 → 編集可能なテキスト → 構造化データ。テキストレイヤーがある PDF は直接抽出し、スキャン文書は自動的に OCR 処理（macOS Vision 標準搭載、日本語・英語対応）。レイアウト復元（多段組み・複雑レイアウトを読取順に並べ替え、単なる行出力ではありません）。OCR 後、LLM を使用して請求書・契約書のフィールド抽出や表形式への変換が可能です。

📁 インストール：hermes skills install jiawood2006/hermes-skills/skills/doc-ocr または README の方法2でコピー → デフォルトは ~/.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 2段組み論文.pdf --md --force-ocr

4. 構造化抽出（請求書/契約書/表、LLM キーが必要）

# まず 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
• 出力は見やすい形式で表示され、-o オプションで JSON/CSV として保存可能

依存関係（初回使用時にインストール）

pip3 install pymupdf pyobjc-framework-Vision
# 構造化抽出には LLM キーが必要（環境変数 LLM_API_KEY または ~/.deai_writer.conf）

注意：OCR は macOS Vision に依存します（macOS のみ利用可能）。Linux の場合は別途 tesseract などのエンジンをインストールする必要があります。

既知の注意点

• スキャン判定：PDF のテキストレイヤーが 20 文字未満の場合は自動的に OCR を実行し、通常の PDF は直接テキスト抽出します。
• レイアウト復元：Vision OCR は文字枠の座標に基づいて並べ替え（上から下へ、同じ行は左から右へ）；2段組みの印刷物は「左段→右段」の順に処理されるため、論文やレポートには適していますが、雑誌のような複雑なレイアウトでは順序が乱れる可能性があります。その場合は --force-ocr を試して目視確認してください。
• 手書き文字：Vision は印刷フォントや明確な手書きには効果的ですが、乱雑な手書きは保証されません。
• プライバシー面：ファイルはローカルで処理され、サードパーティにアップロードされません（構造化抽出では LLM API を呼び出すため、機密ファイルには注意）。
• フィールド欠落：docstruct は欠落フィールドに対して null を設定し、捏造はしません。OCR の品質が低いとフィールドが少なくなる可能性があります。
• バッチエラーハンドリング：ディレクトリモードでは、単一ファイルの失敗は集計に記録されますが、バッチ全体は中断しません。

クイック検証 / 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 ファイルに編集可能なテキストが含まれていること