mcpField
E
email-invoice-processor

email-invoice-processor

github.com/43college文档处理2861 次安装7 周前更新
代码仓库

关于 email-invoice-processor

email-invoice-processor 是用于从 IMAP 邮箱收集并整理中国增值税发票的技能，适合需要批量处理邮件发票的人。它支持多种附件和链接下载方式，并将提取结果及待核对项汇总到 Excel。

主要功能

  1. 01按关键词和日期搜索邮件
  2. 02下载附件及邮件中的发票链接
  3. 03校验文件并处理 ZIP、二维码
  4. 04提取发票字段并生成 Excel
  5. 05汇总待人工核对项和处理日志

适用场景

  1. 01按月或日期范围整理邮箱发票
  2. 02从邮件附件和链接收集发票文件
  3. 03汇总发票字段并筛出异常条目

安装

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

$npx skills add https://github.com/43college/43-agent-skills --skill email-invoice-processor

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

包含的文件

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

.gitignore
.gitkeep
config.json.template
README.md
SETUP.md
scripts/
process_invoices.py

详细介绍

来自项目 README

email-invoice-processor — 邮箱发票处理器

作者：43 COLLEGE 凯寓 (KAIYU) 出品 版本：v1.0

首次配置

如果运行报错找不到 config.json 或邮箱连接失败，读 SETUP.md 完成首次配置。

跨平台兼容

项目macOS / LinuxWindows
Pythonpython3python
脚本路径${CLAUDE_SKILL_DIR}/scripts/process_invoices.py${CLAUDE_SKILL_DIR}\scripts\process_invoices.py
默认输出~/Desktop/发票-日期/%USERPROFILE%\Desktop\发票-日期\
pip 安装pip install ... 或 pip3 install ...python -m pip install ...

使用方式

macOS / Linux：

# 整月处理
python3 ${CLAUDE_SKILL_DIR}/scripts/process_invoices.py 2026-03

# 指定日期范围
python3 ${CLAUDE_SKILL_DIR}/scripts/process_invoices.py 2026-03-01~2026-03-15

# 单日
python3 ${CLAUDE_SKILL_DIR}/scripts/process_invoices.py 2026-03-15

# 自定义输出目录
python3 ${CLAUDE_SKILL_DIR}/scripts/process_invoices.py 2026-03 -o ~/Desktop/三月发票

Windows：

python ${CLAUDE_SKILL_DIR}\scripts\process_invoices.py 2026-03
python ${CLAUDE_SKILL_DIR}\scripts\process_invoices.py 2026-03 -o %USERPROFILE%\Desktop\三月发票

处理流程

  1. 依赖预检 — 必需依赖缺失则退出，可选依赖缺失仅警告
  2. 连接邮箱 — 通过 IMAP SSL 连接（凭证从 config.json 读取）
  3. 服务端搜索 — 按关键词+日期在邮箱服务器筛选，避免全量拉取
  4. 关键词过滤 — 对邮件主题/发件人/正文做发票关键词匹配
  5. 三级附件下载：
    • 直接附件（PDF / 图片 / ZIP 都支持；含 application/octet-stream 伪装的 ZIP）
    • 提取正文中的 HTTP 链接（自动处理 HTML 实体编码，支持 .pdf/.png/.jpg/.zip 直链）
    • 302 启发式：短链先 HEAD 嗅探，若 302 Location 的 query string 里带 pdfUrl=/fileUrl=/downloadUrl= 参数则绕过 SPA 落地页直取真 PDF（云票 bwjf.cn 等 SPA 平台）
    • Playwright 浏览器兜底（需安装可选依赖）
  6. 下载后校验：
    • Magic bytes 文件类型检测（防止 HTML 页面被存为 PDF）
    • ZIP 自动解压：识别 PK\x03\x04/PK\x05\x06 magic bytes 自动取出内部 PDF（12306 火车票 ZIP / 字节系发票 <a download> 直链）；仅含 OFD 时记日志（pdfplumber 不支持 OFD）
    • 发票有效性校验（PDF 关键词 / 图片尺寸）
    • 二维码自动处理（解码 → 浏览器访问 → 下载 PDF）
  7. 字段提取 — pdfplumber 表格提取 + 文本正则双策略
    • 支持负数金额：12306 退票红冲发票（￥-88.50）正确识别
    • 红冲发票备注：检测到「红冲」或「原发票号码」关键字，自动在备注列写入「退票红冲，原发票号 xxx」
    • 无"价税合计"标签兜底：12306 电子客票直接 ￥xx.xx 格式，取绝对值最大的金额作为价税合计
  8. 邮件正文 NLP 兜底 — 每封邮件先扫描正文文本，提取 发票号码/开票日期/购买方/销售方/价税合计；附件抓取失败时仍能落表（标"正文提取，待核对"），附件解析成功但缺字段时用正文补全
  9. 生成 Excel — 按购买方分 sheet，含合计行
    • ⚠️ 待人工核对：xlsx 首页插入醒目橙底 sheet，汇总下载失败、解析失败、仅靠正文落表、购买方未识别等条目（类型/邮件主题/字段提取情况/建议处置）
  10. 处理日志 — 记录跳过/失败项

输出结构

~/Desktop/发票-2026-03/
├── 001-XX公司发票通知.pdf
├── 002-YY平台电子发票.pdf
├── 003-ZZ服务发票-qr.pdf      ← 二维码发票自动解码下载的 PDF
├── 发票汇总.xlsx
└── 处理日志.txt

提取字段

发票号码、发票代码、开票日期、销售方、购买方、金额（不含税）、税额、价税合计、备注（红冲 / 原发票号 / 正文兜底来源）

依赖

必需（缺少会退出）：

  • pdfplumber — PDF 解析
  • openpyxl — Excel 生成
  • requests — HTTP 下载
  • Pillow — 图片处理

可选（缺少仅部分功能受限）：

  • playwright + chromium — 需要 JS 渲染的发票链接下载
  • pyzbar — 二维码图片自动解码（Windows 需额外安装 libzbar.dll）

安装必需依赖：

pip install pdfplumber openpyxl requests Pillow

邮箱兼容性

当前通过 IMAP 协议连接邮箱，config.json 中可配置任意支持 IMAP 的邮箱：

邮箱imap_server备注
QQ 邮箱imap.qq.com需开启 IMAP 并生成授权码
163 邮箱imap.163.com需开启 IMAP 并设置客户端授权密码
Gmailimap.gmail.com需开启 IMAP 并生成 App Password
Outlookoutlook.office365.com需开启 IMAP

默认配置为 QQ 邮箱。更换邮箱只需修改 config.json 中的 email、password、imap_server。

已知限制

  1. 部分 JS 重度平台（诺诺网等）headless Playwright 可能失败
  2. 非标准发票格式可能字段提取不完整
  3. OSS 签名链接有时效，过期需重新获取
  4. 发票字段提取针对中国增值税发票格式优化
  5. ZIP 内仅含 OFD（国标版式文件）时不会提取（pdfplumber 不支持 OFD），日志会标注
  6. 邮件正文 NLP 兜底依赖关键词模板，非标准模板邮件（如纯图片邮件）仍可能漏字段，需查看 ⚠️ 待人工核对 sheet

评论

支持 Markdown