email-invoice-processor — 邮箱发票处理器
作者：43 COLLEGE 凯寓 (KAIYU) 出品 版本：v1.0
首次配置
如果运行报错找不到 config.json 或邮箱连接失败，读 SETUP.md 完成首次配置。
跨平台兼容
| 项目 | macOS / Linux | Windows |
|---|---|---|
| Python | python3 | python |
| 脚本路径 | ${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\三月发票处理流程
- 依赖预检 — 必需依赖缺失则退出，可选依赖缺失仅警告
- 连接邮箱 — 通过 IMAP SSL 连接（凭证从 config.json 读取）
- 服务端搜索 — 按关键词+日期在邮箱服务器筛选，避免全量拉取
- 关键词过滤 — 对邮件主题/发件人/正文做发票关键词匹配
- 三级附件下载：
- 直接附件（PDF 优先） - 提取正文中的 HTTP 链接（自动处理 HTML 实体编码） - Playwright 浏览器兜底（需安装可选依赖）
- 下载后校验：
- Magic bytes 文件类型检测（防止 HTML 页面被存为 PDF） - 发票有效性校验（PDF 关键词 / 图片尺寸） - 二维码自动处理（解码 → 浏览器访问 → 下载 PDF）
- 字段提取 — pdfplumber 表格提取 + 文本正则双策略
- 生成 Excel — 按购买方分 sheet，含合计行
- 处理日志 — 记录跳过/失败项
输出结构
~/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 并设置客户端授权密码 |
| Gmail | imap.gmail.com | 需开启 IMAP 并生成 App Password |
| Outlook | outlook.office365.com | 需开启 IMAP |
默认配置为 QQ 邮箱。更换邮箱只需修改 config.json 中的 email、password、imap_server。
已知限制
- 部分 JS 重度平台（诺诺网等）headless Playwright 可能失败
- 非标准发票格式可能字段提取不完整
- OSS 签名链接有时效，过期需重新获取
- 发票字段提取针对中国增值税发票格式优化