批量下载 Gmail 里的报销票据,自动 OCR、配对、出交付物。覆盖中国境内酒店住宿(发票 + 水单)、餐饮、网约车(发票 + 行程单)、话费等常见报销场景,一条命令跑完 10 步 pipeline。
支持多种 AI Agent(OpenClaw、Quick 等)做报销自动化的开发者,也可以当独立 CLI 单独用。
Amazon Quick 用户:推荐直接把安装指南的完整链接丢进 Quick 对话框,让它带你走完全程 —— 包括 Run MCP 的安装(Quick 沙盒不能直接执行 shell,需要这个极简 MCP 代跑命令;但沙盒可以用内置浏览器查看链接内容,所以 Quick 能照着指南一步步指导你装好 Run MCP,之后就能自己完成 clone、装依赖、自检)。例如在 Quick 里输入:
按照这个指南帮我安装 Gmail 发票下载器(含 Run MCP):
https://gitlab.aws.dev/kentpeng/gmail-invoice-downloader/-/blob/main/quick_install_guide.md
手工安装步骤见 quick_install_guide.md。
目前只附带 Gmail OAuth 配置指南。下载 + OCR + 匹配 + 报告这套后半段跟邮件源解耦 —— 只要另一个邮箱(Outlook、Lark Mail、企业邮箱 IMAP 等)能通过 API / connector 拿到附件和正文,改一个
GmailClient实现就能复用。Outlook 用户可参考已有的移植实现:outlook-invoice-downloader。
一条命令输入日期区间,输出:
下载报告.md— 带金额汇总表、P1/P2/P3 匹配详情、跨季度边界项说明的中文报告发票汇总.csv— UTF-8 BOM,Excel 直接打开,带小计 + 总计行missing.json— Agent 可读的状态机(converged/needs_retry/max_iterations_reached/user_action_required),v1.0 schemaexpense_data.json— 机读入口(schema v1.1),供下游报销工具消费:已配对 groups(每条含locationCity,如"Wuxi, Jiangsu",城市不明为 null)、orphans、unparsed 与汇总发票打包_<时间>.zip— 交给财务的最终打包(仅 PDF + MD + CSV)
覆盖的票据类型:
- 酒店发票(中国增值税电子普票 / 专票)+ 水单 / Guest Folio(自动按
确认号/日期+金额/ 同日兜底三级匹配) - 网约车发票 + 行程报销单(按金额匹配,发票号做 tiebreaker)
- 餐饮 / 话费 / 铁路电子客票 / 通行费 等其它类目
支持 9 种中国电子发票平台 short link:百望云 / 诺诺网 / fapiao.com / xforceplus / 云票 / 百旺金穗云 / 金财数科 / 克如云 / 12306。Agent 遇到新平台时可调 scripts/probe-platform.py 逆向 + 走 scripts/record-unknown-platform.py 把未知平台的邮件上报给用户(Agent Loop Playbook 自动处理)。
# 1. clone(内部 GitLab 需先完成 Midway 认证:mwinit -f)
mwinit -f
git clone git@ssh.gitlab.aws.dev:kentpeng/gmail-invoice-downloader.git
cd gmail-invoice-downloader
# 2. 装依赖(用到 curl + poppler-utils,需要先 brew install)
brew install poppler
pip install -r requirements.txt
# 3. 配 Gmail OAuth(见 references/setup.md)
# 默认凭据目录:~/.config/gmail/
# 放入 credentials.json 后运行:
python3 scripts/gmail-auth.py
# 4. 配 LLM provider(默认 Bedrock,Sonnet 4.6)
export AWS_REGION=us-east-1
# BEDROCK_MODEL_ID 默认 global.anthropic.claude-sonnet-4-6
# 想换 Opus: export BEDROCK_MODEL_ID=global.anthropic.claude-opus-4-7
# 其它 provider(Anthropic / OpenAI / 兼容端点 / 离线 none)见 SKILL.md
# 5. preflight 检查(exit 0 = 全绿)
python3 scripts/doctor.py
# 6. 跑一次
python3 scripts/download-invoices.py \
--start 2026/01/01 --end 2026/04/01 \
--output ~/invoices/2026-Q1支持 --stage {search,download,ocr,match,report} 分阶段执行,Agent 可在各阶段间渲染进度(详见 SKILL.md § Agent First-Run Procedure)。
完整参数、多 LLM provider 选型(Bedrock / Anthropic / Anthropic-compatible / OpenAI / OpenAI-compatible / none)、Agent Loop Playbook、Exit Codes 契约、Lessons Learned 都在 SKILL.md。
这个 repo 是 Agent-ready 的 —— CLAUDE.md 写了架构边界和编辑规范,SKILL.md 是 Agent 执行契约(含 Loop Playbook、Exit Codes、missing.json schema)。把 repo URL 给能跑 shell 的 Agent(Claude Code / OpenClaw Skill / Cursor / Cline 等),它会自己 clone、读上下文、跑起来。
你需要先告诉 Agent 的三件事(直接把这个Repo链接丢给 Agent 也行,它会指导你按流程走 ):
- Gmail OAuth 凭据 —— 参考
references/setup.md在 Google Cloud 建一个 OAuth client,把credentials.json放到~/.config/gmail/credentials.json(或另选路径 + 运行时带--creds <path>覆盖)。首次跑python3 scripts/gmail-auth.py会交互式地生成token.json,之后自动刷新 —— 这一步需要人打开浏览器授权,Agent 做不了。 - LLM provider 凭据 —— 默认 AWS Bedrock,需要
AWS_REGION+ 任一种 AWS 凭据(IAM role /AWS_PROFILE/ AK/SK /AWS_BEARER_TOKEN_BEDROCK)。要用 Anthropic / OpenAI 直连或兼容端点(DeepSeek / OpenRouter / LiteLLM 等)看SKILL.md§ LLM Provider。 - 日期范围 + 输出目录 —— 比如 "下载 2026 年第一季度的报销票据到
~/invoices/2026-Q1",或者更宽松的 "上个季度的",Agent 会翻成--start YYYY/MM/DD --end YYYY/MM/DD。
Agent 自动做的事:pip install -r requirements.txt、python3 scripts/doctor.py 自检、跑主命令、读 missing.json 决定要不要 --supplemental 补搜、对 failed short link 调 scripts/probe-platform.py 做补救、最后把 发票打包_<时间>.zip 交付给你。遇到未知平台 Agent 不会盲改代码 —— 会通过 scripts/record-unknown-platform.py 把信息上报到 missing.json.items[],让你决定是否扩展支持(references/platforms.md 有 5-step playbook)。
目前
scripts/gmail-auth.py里的凭据路径在某些平台上是硬编码的/home/ubuntu/...。macOS / 其它 Linux 用户首次跑可能需要改成自己的路径,或把credentials.json放到脚本期望的位置。这是已知的小摩擦,路线图里会清理。
10 步 pipeline,分两层:
| 层 | 负责 | 代码 |
|---|---|---|
| Layer 1:Gmail 下载(v5.2 稳定) | Step 1–5:搜索 / 分类 / 附件 + ZIP + 9 个平台 short link 解析 / %PDF header 校验 |
scripts/invoice_helpers.py |
| Layer 2:LLM 后处理 | Step 6–10:OCR(ThreadPool 默认并发 5,可用 LLM_OCR_CONCURRENCY 覆盖)+ 可信度校验 / 按 OCR 重命名 / P1 remark → P2 日期+金额 → P3 同日兜底 / 跨季度边界项路由到 out_of_range_items[] / 写 3 份交付物 + zip |
scripts/postprocess.py + scripts/core/ |
当脚本的批量下载跑完后如果有 failed short link,Agent 可以用 --postprocess-only 跳过 Gmail、只重跑 Step 6–10,配合 scripts/probe-platform.py 做手工 / 自动补救。
完整的目录说明、每步数据流、Agent Loop 契约、文件级改动边界在 CLAUDE.md 和 SKILL.md。
# 425 个测试,全量 ~10 秒,离线 mock 了 Gmail + LLM
python3 -m pytest tests/ -q
# 跑集成测试需要真实 PDF 样本,默认路径:
# ~/Documents/agent Test/
# 或用环境变量覆盖:
export GMAIL_INVOICE_FIXTURES=/path/to/your/samples
python3 -m pytest tests/ -q季度 smoke runbook(真实 Gmail + 真实 LLM):references/seasonal-smoke.md
发布历史 + 升级备注:CHANGELOG.md
- 必须:Python 3.10+、
boto3>=1.35.17、curl、pdftotext(poppler-utils) - 可选:
anthropic>=0.34(LLM_PROVIDER=anthropic/anthropic-compatible)、openai>=1.50(LLM_PROVIDER=openai/openai-compatible) - 测试:
pytest、pytest-mock
Gmail OAuth 走手写 HTTPS + OAuth token 刷新(GmailClient._api_get)。google-api-python-client 故意不引入 —— 依赖更少,transient 网络错误的重试策略更可控。