invoice-processor

請求書プロセッサー

AI ビジョンモデルを使用して請求書ファイルを処理し、構造化された情報を抽出して書式設定済みの Excel レポートを作成する、完全自動化されたワークフローです。

使用するタイミング

ユーザーが次のように述べた場合に自動的に起動します：

• 「处理发票」／「识别发票」／「提取发票信息」／「发票转Excel」
• 請求書ファイル（PDF、JPG、PNG）の処理
• 請求書を Excel 形式に変換

実行環境に関する注意事項

⚠️ 重要：ASCII 以外の文字を含むディレクトリ名のパス処理

プロジェクトディレクトリに中国語などの ASCII 以外の文字（例：「发票助手agent」）が含まれる場合は、プロジェクトルートからの完全な相対パスを必ず使用してください：

# ❌ WRONG - Will fail with encoding errors
python scripts/check_env.py

# ✅ CORRECT - Use full paths from .claude/skills/
python .claude/skills/invoice-processor/scripts/check_env.py

クロスプラットフォーム互換性：

• Unix スタイルのコマンドを使用してください（Git Bash、Linux、macOS）
• ❌ dir /b → ✅ ls

セットアップ

invoice-processor ディレクトリに .env ファイルを作成します：

# Copy from template
cp .env.example .env

# Edit with your API key
# .env content:
GLM_API_KEY=your_actual_api_key_here

API キーは https://open.bigmodel.cn/ から取得してください。

ワークフロー

ステップ 1：環境チェック（推奨）

python .claude/skills/invoice-processor/scripts/check_env.py

確認内容：GLM_API_KEY が設定されていること、必要なパッケージ（aiohttp、PyMuPDF、openpyxl）がインストールされていること

ステップ 2：請求書を認識

# Default: process 'invoices' directory → 'invoice_results.json'
python .claude/skills/invoice-processor/scripts/invoice_ocr.py

# Custom paths
python .claude/skills/invoice-processor/scripts/invoice_ocr.py -i <input_path> -o <output.json>

処理内容：

• 請求書ファイル（JPG、JPEG、PNG、PDF）を検索します
• PDF を画像（200 DPI）に変換します
• 最大 5 ファイルを同時に処理します
• 9 項目を抽出します：種類、番号、日付、買い手／売り手の名称、金額（税抜／税込）、税額、明細
• 成功／エラーのステータスとともに JSON に保存します

引数：

• -i, --input：入力パス（デフォルト：invoices）
• -o, --output：出力 JSON（デフォルト：invoice_results.json）

前提条件：

• GLM_API_KEY を設定した .env ファイル（下記のセットアップを参照）
• pip install aiohttp PyMuPDF

ステップ 3：Excel レポートを作成

# Default: 'invoice_results.json' → 'invoice_results.xlsx'
python .claude/skills/invoice-processor/scripts/convert_to_excel.py

# Custom paths
python .claude/skills/invoice-processor/scripts/convert_to_excel.py -i <input.json> -o <output.xlsx>

処理内容：

• ステップ 2 の JSON を読み込みます
• 12 列の書式設定済み Excel を作成します
• 変換に成功すると、入力 JSON を自動的に削除します

引数：

• -i, --input：入力 JSON（デフォルト：invoice_results.json）
• -o, --output：出力 Excel（デフォルト：invoice_results.xlsx）

前提条件：

• pip install openpyxl

使用例

基本（ASCII 以外の文字を含むディレクトリ名）

# Full 3-step workflow
python .claude/skills/invoice-processor/scripts/check_env.py
python .claude/skills/invoice-processor/scripts/invoice_ocr.py -i invoices -o invoice_results.json
python .claude/skills/invoice-processor/scripts/convert_to_excel.py -i invoice_results.json -o invoice_results.xlsx

カスタムパス

python .claude/skills/invoice-processor/scripts/invoice_ocr.py -i invoices_2024 -o results_2024.json
python .claude/skills/invoice-processor/scripts/convert_to_excel.py -i results_2024.json -o report_2024.xlsx

トラブルシューティング

スクリプトが見つからない／エンコードエラー

エラー： can't open file '...\��Ʊ����agent\scripts\...' 原因： ASCII 以外の文字を含むディレクトリでは、短いパス（scripts/）が機能しません 解決策： 完全なパスを使用してください：.claude/skills/invoice-processor/scripts/...

コマンドが見つからない

エラー： dir: cannot access '/b' 原因： Unix シェルで Windows CMD のコマンドを使用しています 解決策： dir の代わりに ls を使用してください

API キーが設定されていない

エラー： 错误: 请在 .env 文件中设置 GLM_API_KEY 解決策： invoice-processor ディレクトリに GLM_API_KEY=your_key を記載した .env ファイルを作成してください

PDF のサポートが無効

警告： 未安装 PyMuPDF，PDF 支持已禁用 解決策： pip install PyMuPDF

注意事項

• GLM API の制限：同時リクエストは 5 件、リクエストごとのタイムアウトは 60 秒です
• 画像の制限：最大 5MB、6000x6000 ピクセル
• PDF は自動的に画像に変換されます（一時ファイルは削除されます）
• パスのベストプラクティス： プロジェクトディレクトリに ASCII 以外の文字が含まれる場合は、常に完全な相対パス（.claude/skills/invoice-processor/scripts/）を使用してください

---

設計原則、カスタマイズオプション、アーキテクチャのガイドラインについて詳しくは、README.md を参照してください。