中国发票专用 · 云端优先识别 · 数字票本地秒出 · 3 分钟上手
| 场景 | 传统方式 | 发票夹子 |
|---|---|---|
| 收票 | 手动下载邮箱附件 | 📧 自动扫描下载 |
| 识别 | 手工录入 / 重型本地大模型 | ☁️ 云端视觉 API（免费额度优先）+ 数字票本地解析 |
| 整理 | Excel 手工统计 | 📊 自动分类 + 一键导出 |
| 验真 | 税局网站逐张查 | ✅ 自动验真 + 风险预警 |
本地跑 Qwen-VL / 大参数 OCR 对内存和运维要求都不低。对个人报销量来说：
- 火山引擎方舟等平台常见有 每日大量免费 token（量级可到百万～千万级，以官网活动为准），足够发票 OCR、字段整理、简单分析；
- 硅基流动等 OpenAI 兼容网关也有新人额度；
- 数字 PDF / OFD 仍 100% 本地文本解析（零费用、可选择不上传）；
- 只有扫描件/图片才调用视觉 API。
本机 MLX 仍保留为可选离线兜底，不是默认安装路径。
方式一：一键安装（推荐）
如果你使用 OpenClaw，一行命令搞定：
npx clawhub@latest install fapiao-clipper👉 https://clawhub.ai/skills/fapiao-clipper
方式二：GitHub 手动安装
git clone https://github.com/Alan5168/fapiao-clipper.git
cd fapiao-clipper
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
# 或: pip install -r requirements.txt# 交互向导（推荐）
python3 setup_config.py
# 或手动：
cp config/config.example.yaml config/config.yaml
# 编辑 config.yaml：填入云端 API Key（火山引擎 Ark / 硅基流动等）环境变量（可代替写入 yaml）：
| 变量 | 用途 |
|---|---|
FAPIAO_OCR_API_KEY |
通用 OCR Key（优先） |
ARK_API_KEY / VOLCENGINE_API_KEY |
火山引擎方舟 |
SILICONFLOW_API_KEY |
硅基流动 |
OPENAI_API_KEY |
其他 OpenAI 兼容端点 |
python3 main.py scan # 扫描邮箱和本地目录
python3 main.py list # 查看已识别发票
python3 main.py export --format both # 导出报销 Excel + 合并 PDF🎉 完成！文件在 ~/Documents/发票夹子/exports/，直接发给财务。
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .
cp config/config.example.yaml config/config.yaml
streamlit run app.py浏览器打开 http://localhost:8501
⚠️ 必须先pip install -e .，否则 Streamlit 无法导入invoice_clipper。
💡 局域网外访问：Tailscale / frp（见下文「远程访问」）。
功能说明：
- 📤 扫描发票：拖拽上传 PDF/图片，实时显示识别结果
- 📋 发票列表：表格展示，状态筛选与批量操作
- 🔍 查询筛选：日期 / 销售方 / 购买方
- 📥 导出报销：Excel 明细 + PDF 报销包
上图：发票列表页面
Web UI 默认只在 localhost:8501。公司 WiFi / 手机热点下可用：
- 安装 Tailscale（Mac / 手机同一账号）
- 访问：
http://<你的Tailscale IP>:8501
[streamlit]
type = tcp
local_ip = 127.0.0.1
local_port = 8501
remote_port = 18501| 级别 | 引擎 | 何时触发 | 费用/隐私 |
|---|---|---|---|
| 1 | PyMuPDF / pdfplumber 文本 | 可搜索 PDF | 本地，零费用 |
| 1.5 | OFD 原生 XML | .ofd |
本地，零费用，绕过缺中文字体 |
| 2 | OpenAI 兼容云端视觉（默认） | 扫描件/图片或文本置信度不足 | 走你的 Ark/硅基等额度 |
| 3 | MLX 本地 OCR（可选） | provider: mlx 或 fallbacks: [mlx] |
完全离线，需自备服务 |
ocr:
provider: openai_compatible # 推荐默认
openai_compatible:
api_key: "YOUR_ARK_API_KEY" # 或用环境变量
base_url: https://ark.cn-beijing.volces.com/api/v3
vision_model: "doubao-seed-1.6-vision" # 以控制台接入点为准
# fallbacks: [mlx] # 可选：云挂了再试本机🔒 隐私分层：电子票（PDF 文本层 / OFD XML）可全程本地；只有需要「看图」时才上传渲染页到你配置的云端。
完全不想上云：设provider: mlx并自备本机 OCR 服务。
- IMAP 邮箱附件扫描
- 邮件正文发票链接抓取
- 本地目录监控入库
对接国税查验相关能力 + 本地规则，覆盖真伪、作废/红冲、超期、重复报销、销售方风险、金额阈值、税率异常、抵扣检查等。
python3 main.py export --format both报销明细_YYYYMMDD.xlsx报销发票_YYYYMMDD.pdf（合并包）
python3 main.py scan
python3 main.py list
python3 main.py export --from 2026-03-01 --to 2026-03-31 --format both
python3 main.py verify
python3 main.py problems
python3 main.py exclude 123邮箱 / 目录 / 拖入
│
▼
PDF·OFD·图片入库
│
▼
┌─────────────────────────┐
│ 第1级 PyMuPDF 文本 │ 数字 PDF
│ 第1.5 OFD 原生 XML │ 电子 OFD
│ 第2级 云端视觉 API │ 扫描件（默认）
│ 第3级 本机 MLX（可选） │ 离线兜底
└───────────┬─────────────┘
▼
字段标准化 / 风控 / SQLite
▼
Excel + 合并 PDF
- PDF / OFD：PyMuPDF、pdfplumber、easyofd、原生 OFD XML
- 视觉识别（默认）：任意 OpenAI-compatible 多模态 API（火山引擎方舟 / 硅基流动 / 自定义）
- 视觉识别（可选）：本机 MLX OpenAI-compatible OCR
- Web UI：Streamlit
- 存储：SQLite
- ✅ 配置与数据库仅存本机（
config/config.yaml已 gitignore） - ✅ 数字 PDF / OFD 默认可完全本地识别
- ✅ API Key 支持环境变量，勿提交仓库
⚠️ 选择云端视觉时，扫描件渲染图会发送到你配置的服务商——请阅读其隐私条款- ✅ 可选
provider: mlx实现扫描件也离线
MIT License — 见 LICENSE。
npx clawhub@latest install fapiao-clipper👉 https://clawhub.ai/skills/fapiao-clipper
大版本：云端优先 + 本地演进合并发布
- 🎯 产品默认：扫描件视觉识别改为 OpenAI-compatible 云端优先（火山引擎方舟 / 硅基流动 / 自定义网关）
- 📝 明确注释与文档：本地大模型对机器要求高，个人报销优先用云上免费/低成本额度
- 🆕 统一引擎
OpenAICompatibleVisionEngine（一份实现覆盖多云 + 本地 OpenAI 兼容端点） - 🆕 配置：
ocr.openai_compatible/volcengine/siliconflow，API Key 支持多环境变量 - 🆕
ocr.fallbacks: [mlx]：云端失败时可选本机 MLX - ✨ OFD 原生 XML 提取（绕过 Mac 缺中文字体豆腐块，不依赖 OCR）
- ✨ PDF 文本层增强（pdfplumber、跨行/散列字符等修复，沿用本地长期维护）
- ♻️ Ollama / Qwen3-VL 本地默认路径退役（仍可自建 OpenAI 兼容端点接入）
- 📚 README / SKILL / setup 向导 / 示例配置全面对齐 v2.0
- 发票内容验证、Web UI 风控可视化、OFD 中文路径、DPI/超时等
- v1.4 Web UI · v1.3 简化架构 · v1.2 OpenDataLoader · v1.1 多级降级 · v1.0 首发
发票夹子 · 让报销不再头疼 🧾✨
Made with ❤️ by Alan Li | 中国自由职业者 & 小微企业财务效率工具