email-invoice-processor

Name: email-invoice-processor
Author: 43college

github.com/43collegeDocuments2861 installsUpdated 7w ago

About email-invoice-processor

email-invoice-processor is a skill for collecting and organizing Chinese VAT invoices from IMAP mailboxes. It handles several attachment and link download paths, then exports extracted fields and items needing review to Excel.

Key features

01Search mail by keywords and date
02Download invoice attachments and links
03Validate files and handle ZIPs and QR codes
04Extract invoice fields and create Excel files
05List review items and processing logs

Use cases

01Organize mailbox invoices by month or date range
02Collect invoice files from email attachments and links
03Summarize invoice fields and flag exceptions

Install

Copy the command and run it in a terminal.

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

After installing, type/email-invoice-processorin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

.gitignore

.gitkeep

config.json.template

README.md

SETUP.md

scripts/

process_invoices.py

Details

From the project README

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 / 图片 / 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 浏览器兜底（需安装可选依赖）
下载后校验：
- Magic bytes 文件类型检测（防止 HTML 页面被存为 PDF）
- ZIP 自动解压：识别 PK\x03\x04/PK\x05\x06 magic bytes 自动取出内部 PDF（12306 火车票 ZIP / 字节系发票 <a download> 直链）；仅含 OFD 时记日志（pdfplumber 不支持 OFD）
- 发票有效性校验（PDF 关键词 / 图片尺寸）
- 二维码自动处理（解码 → 浏览器访问 → 下载 PDF）
字段提取 — pdfplumber 表格提取 + 文本正则双策略
- 支持负数金额：12306 退票红冲发票（￥-88.50）正确识别
- 红冲发票备注：检测到「红冲」或「原发票号码」关键字，自动在备注列写入「退票红冲，原发票号 xxx」
- 无"价税合计"标签兜底：12306 电子客票直接 ￥xx.xx 格式，取绝对值最大的金额作为价税合计
邮件正文 NLP 兜底 — 每封邮件先扫描正文文本，提取发票号码/开票日期/购买方/销售方/价税合计；附件抓取失败时仍能落表（标"正文提取，待核对"），附件解析成功但缺字段时用正文补全
生成 Excel — 按购买方分 sheet，含合计行
- ⚠️ 待人工核对：xlsx 首页插入醒目橙底 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 签名链接有时效，过期需重新获取
发票字段提取针对中国增值税发票格式优化
ZIP 内仅含 OFD（国标版式文件）时不会提取（pdfplumber 不支持 OFD），日志会标注
邮件正文 NLP 兜底依赖关键词模板，非标准模板邮件（如纯图片邮件）仍可能漏字段，需查看 ⚠️ 待人工核对 sheet

Comments

Markdown supported

Details

Author: 43college
Repository: 43college/43-agent-skills
Category: Documents
Installs: 61
GitHub stars: 28

Report

More skills

All skills

handoff

github.com/mattpocock

1.1M

Compact the current conversation into a handoff document for another agent to pick up

lark-doc

open.feishu.cn

823.9k

Operate on Feishu cloud documents (Docx / Wiki): read, create, and edit documents; insert or download image attachments; and work with mind notes. Use when the user provides a document URL/token (including /docx/ or /wiki/ on doubao.com); route by URL path/token rather than domain. `/page/<token>` is a Miaoda app, not a Feishu cloud document. Route embedded document resources according to the unified rules in the reading reference. Use lark-drive for standalone comment operations; use docs +fetch to read comments alongside the main text. Operations on spreadsheet or Base internal data are outside this skill.

lark-drive

open.feishu.cn

823.2k

Feishu cloud storage (Drive): manage Drive files and folders, including uploads/downloads, folder creation, copying/moving/deleting, viewing metadata, checking permission settings, comments/permissions/subscriptions, titles, versions, Feishu document security labels (secure labels), and local file imports. Use when users need to organize Drive folders, handle cloud storage resource URLs/tokens, identify link types/actual tokens/titles, or import Word/Markdown/Excel/CSV/PPTX/.base as docx/sheet/bitable/slides. Route doubao.com cloud storage URLs/tokens by resource path and token too; do not fall back to WebFetch. Not responsible for: editing document content (use lark-doc), spreadsheet/Base table data operations (use lark-sheets/lark-base), knowledge space node/member management (use lark-wiki), or native Markdown file read/write/patch/diff (use lark-markdown).

lark-sheets

open.feishu.cn

821.8k

Feishu Spreadsheets: create and operate spreadsheets. Supports worksheets and row/column structures (add/delete/merge/size/hide/freeze/group), cell read/write (values/formulas/styles/comments/cell images), range copy/move/sort/fill, find and replace, bulk updates, and creating and maintaining objects such as charts, pivot tables, conditional formatting, filters and filter views, dropdown lists, sparklines, and floating images. Also supports formula validation, restoring historical versions, and importing/exporting local Excel/CSV files and Feishu spreadsheets. Use when users need to create or edit spreadsheets, summarize and visualize data, format spreadsheets, calculate formulas (including migrating Excel formulas), or build financial models (DCF, three statements, budgets, Sensitivity, etc.). For multidimensional tables (Base/bitable), use lark-base. If users want to search for spreadsheet files in cloud storage (Drive/cloud storage) by name or keyword, use lark-drive's drive +search to locate resources first. When users provide a doubao.com /sheets/ URL/token, use this skill directly; do not fall back to WebFetch because the domain is not Feishu. Routing is based on the URL path pattern and token, not the domain.