Jst-Well-Dan/invoice-processor

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.