Invoice Processor

Fully automated workflow for processing invoice files using AI vision models to extract structured information and generate formatted Excel reports.

When to Use

Auto-trigger when users mention:

"处理发票" / "识别发票" / "提取发票信息" / "发票转Excel"
Processing invoice files (PDF, JPG, PNG)
Converting invoices to Excel format

Execution Environment Notes

⚠️ CRITICAL: Path handling for non-ASCII directory names

When the project directory contains Chinese or other non-ASCII characters (e.g., "发票助手agent"), you MUST use full relative paths from project root:

# ❌ 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

Cross-platform compatibility:

Use Unix-style commands (Git Bash, Linux, macOS)
❌ dir /b → ✅ ls

Setup

Create a .env file in the invoice-processor directory:

# Copy from template
cp .env.example .env

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

Get your API key from: https://open.bigmodel.cn/

Workflow

Step 1: Environment Check (Recommended)

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

Verifies: GLM_API_KEY is set, required packages installed (aiohttp, PyMuPDF, openpyxl)

Step 2: Recognize Invoices

# 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>

What it does:

Scans for invoice files (JPG, JPEG, PNG, PDF)
Converts PDFs to images (200 DPI)
Processes up to 5 files concurrently
Extracts 9 fields: type, number, date, buyer/seller names, amounts (excl/incl tax), tax, items
Saves to JSON with success/error status

Arguments:

-i, --input: Input path (default: invoices)
-o, --output: Output JSON (default: invoice_results.json)

Prerequisites:

.env file with GLM_API_KEY (see Setup below)
pip install aiohttp PyMuPDF

Step 3: Generate Excel Report

# 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>

What it does:

Reads JSON from Step 2
Creates formatted Excel with 12 columns
Auto-deletes input JSON after successful conversion

Arguments:

-i, --input: Input JSON (default: invoice_results.json)
-o, --output: Output Excel (default: invoice_results.xlsx)

Prerequisites:

pip install openpyxl

Usage Examples

Basic (Non-ASCII directory names)

# 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

Custom Paths

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

Troubleshooting

Script Not Found / Encoding Errors

Error: can't open file '...\��Ʊ��agent\scripts\...' Cause: Short paths (scripts/) fail in non-ASCII directories Solution: Use full paths: .claude/skills/invoice-processor/scripts/...

Command Not Found

Error: dir: cannot access '/b' Cause: Windows CMD command in Unix shell Solution: Use ls instead of dir

API Key Not Set

Error: 错误: 请在 .env 文件中设置 GLM_API_KEY Solution: Create .env file in invoice-processor directory with GLM_API_KEY=your_key

PDF Support Disabled

Warning: 未安装 PyMuPDF，PDF 支持已禁用 Solution: pip install PyMuPDF

Notes

GLM API limit: 5 concurrent requests, 60s timeout per request
Image limits: 5MB max, 6000x6000 pixels
PDFs auto-converted to images (temp files cleaned up)
Path Best Practice: Always use full relative paths (.claude/skills/invoice-processor/scripts/) when project directory contains non-ASCII characters

For detailed design principles, customization options, and architecture guidelines, see README.md.