mcpField
I
invoice-processor

invoice-processor

github.com/jst-well-dan文档处理1050 次安装31 周前更新
代码仓库

关于 invoice-processor

invoice-processor 是将发票文件转为结构化数据和 Excel 报表的处理 Skill，适用于需要批量整理发票的工作。它用视觉模型识别 PDF、JPG、PNG 中的字段，先输出 JSON，再生成格式化 Excel。

主要功能

  1. 01识别 PDF、JPG、JPEG 和 PNG 发票
  2. 02将 PDF 转为图像后处理
  3. 03提取发票类型、号码、日期及金额等字段
  4. 04将识别结果保存为 JSON
  5. 05从 JSON 生成格式化 Excel 报表

适用场景

  1. 01整理目录中的多种格式发票
  2. 02提取发票信息供后续处理
  3. 03将识别结果汇总为 Excel 报表

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jst-well-dan/skill-box --skill invoice-processor

安装后在 Claude Code 中输入/invoice-processor确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.env.example
docs/
README.md
scripts/
check_env.py
convert_to_excel.py
invoice_ocr.py
requirements.txt

详细介绍

发票处理器

使用 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）

前置条件：

  • .env 文件中包含 GLM_API_KEY（见下方“设置”）
  • 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 shell 中使用了 Windows CMD 命令 解决方法： 使用 ls 替代 dir

未设置 API 密钥

错误： 错误: 请在 .env 文件中设置 GLM_API_KEY 解决方法： 在 invoice-processor 目录中创建 .env 文件，并设置 GLM_API_KEY=your_key

未启用 PDF 支持

警告： 未安装 PyMuPDF，PDF 支持已禁用 解决方法： pip install PyMuPDF

备注

  • GLM API 限制：最多 5 个并发请求，每个请求超时时间为 60 秒
  • 图像限制：最大 5MB，最大尺寸为 6000x6000 像素
  • PDF 会自动转换为图像（临时文件会被清理）
  • 路径最佳实践： 当项目目录包含非 ASCII 字符时，始终使用完整相对路径（.claude/skills/invoice-processor/scripts/）

有关详细的设计原则、自定义选项和架构指南，请参阅 README.md。

评论

支持 Markdown