invoice-auto-forward

自动扫描邮箱（支持 QQ/163/126 等主流邮箱，provider 一键切换）里的发票邮件，解析发票（PDF/OFD/XML 三种格式）后按标准化模板转发给指定收件人（如财务/行政），支持抬头白名单过滤、定时无人值守运行、发送节奏控制（防反垃圾风控）。对「链接型发票」（邮件只有下载链接、无 PDF 附件，如腾讯云电子发票）也能自动扫描正文链接并下载发票文件（PDF/OFD/XML）后转发。This skill should be used when 用户想把邮箱收到的发票自动转发给他人、设置发票自动归档/报销流程、配置发票转发规则（授权码/收件人/主题模板），或触发词包括：发票转发、发票自动转发、QQ邮箱发票、163邮箱发票、126邮箱发票、链接型发票、OFD发票、XML发票、转发发票给财务、invoice forward。

Evan Song@songhonglei

Install

openclaw skills install @songhonglei/invoice-auto-forward

Invoice Auto Forward — 邮箱发票自动转发

概述

本 skill 引导用户完成一次性配置（邮箱授权码、转发规则、收件人、主题/正文模板），之后即可自动扫描邮箱中的发票邮件，解析 PDF 发票并按统一格式转发给指定人。支持定时无人值守运行与对话手动触发。

主脚本：scripts/invoice_forward.py（子命令：setup / check / scan / run / parse）
配置模板与全字段说明：references/config.example.json
排障与授权码获取指引：references/troubleshooting.md

依赖

Python 3.8+，网络可达邮箱 IMAP/SMTP 服务器
首次使用自动安装（check --install-deps，装到当前 Python 环境）：pdfplumber（PDF 解析首选）、pymupdf（PDF 兜底，二者至少其一）。OFD / XML 用 Python 内置 zipfile + xml.etree 解析，无需任何额外依赖。
手动安装等价命令：pip install pdfplumber pymupdf
可选环境变量：INVOICE_FORWARD_CONFIG（自定义 config.json 路径，默认 ~/.workbuddy/invoice-forward/config.json）

Setup 引导流程（首次使用，按序执行）

检查依赖：直接运行 python3 scripts/invoice_forward.py check --install-deps——缺少 pdfplumber/pymupdf 时会自动 pip 安装到当前 Python 环境（执行前向用户说明将安装这两个库）；若用户环境禁止自动安装，改为给出 pip install pdfplumber pymupdf 命令让其自行执行。
收集凭证：向用户询问邮箱地址与 SMTP/IMAP 授权码。QQ 获取路径：网页版 → 设置 → 账号 → POP3/IMAP/SMTP 服务 → 生成授权码；163/126 获取路径：网页版 → 设置 → 开启 POP3/SMTP/IMAP 服务（默认禁用）→ 短信验证 → 生成授权码（详见 references/troubleshooting.md）。这些值与转发规则可一次性交给 setup 子命令完成（推荐，见下方「一键配置」），它会验证连通性后写入 secrets（chmod 600）+ config.json，无需手工改文件。授权码只进 secrets 文件，绝不写入 config.json、SKILL.md 或任何 skill 包内文件。
收集转发规则（逐项询问，给默认值，允许用户直接回车采用）：
- 抬头白名单：默认空 = 全部转发；填写后仅转发购买方抬头匹配的发票
- 扫描天数：默认 7
- 主题关键词：默认 ["发票"]
- 收件人（必填，支持多个）
- 主题模板：默认 {item} {amount} {date}
- 正文模板：默认含发票号码/日期/抬头/销售方/物品/金额六要素
生成配置：按 references/config.example.json 的结构写入 ~/.workbuddy/invoice-forward/config.json（用 setup 子命令则自动生成）。
验证：依次执行
- python3 scripts/invoice_forward.py check — 体检全过才继续
- python3 scripts/invoice_forward.py scan — 干跑预览，向用户展示将转发的邮件清单（主题渲染结果），请用户确认
定时任务（可选，引导创建）：询问用户是否创建定时任务及频率（如每 3 天）。WorkBuddy 环境用 automation 工具创建，任务内容就是执行 run 子命令并复述输出；非 WorkBuddy 环境给出 crontab 行。提醒：创建后核对下次运行时间是否符合预期。
完成汇报：告知用户配置位置、手动执行方式、如何修改规则。

一键配置（setup 子命令，推荐）

把上面步骤 2–5 合并成一条命令：自动合并已有配置、应用你给的参数、交互补缺失项、验证 IMAP/SMTP 连通性，确认授权码真能用后才写入 secrets（chmod 600）与 config.json。凭证绝不会写进 config.json。

bash

python3 scripts/invoice_forward.py setup \
  --user yourname@163.com \         # 登录邮箱；省略 provider 时由域名推导主机
  --provider 163 \                  # qq/163/126/yeah 或域名；可省略，由 --user 域名自动推导
  --auth-code xxxxxxxx \            # IMAP/SMTP 授权码；不传则交互隐藏输入（getpass，不回显）
  --to finance@example.com \        # 转发收件人，多个用空格分隔
  --days 7 \                        # 扫描天数窗口
  --buyer-whitelist "公司A" "公司B" \  # 抬头白名单，空=全部
  --interval 3 --batch-limit 20 \   # 163/126 防反垃圾节奏（QQ 可设 0）
  --fetch-links \                   # 启用链接型发票抓取（默认开）；--no-fetch-links 关闭
  --link-domains myqcloud.com tencent.com \  # 仅下载这些域名后缀的链接（空=全部，靠 PDF 闸门兜底）
  --config ~/.workbuddy/invoice-forward/config.json   # 可放任意路径；默认即此

要点：

准确性保证：默认会真实登录 IMAP + SMTP 验证；验证不通过绝不写 secrets（config.json 仍会保存，方便重跑）。加 --no-verify 可跳过（仅当你确定授权码正确、或离线调试时）。
幂等合并：目标 config.json 已存在时在其基础上合并，不会清空你已有的其他设置。
交互兜底：缺 --user/--auth-code 等且在终端（tty）下运行时会逐项交互询问；非交互（agent 批处理）则缺项直接报错，提示补参数。
域名推导：不传 --provider 时，按 --user 域名（如 163.com/126.com）自动选主机，少记一个参数。
写盘后打印配置路径与权限，并提示下一步跑 check。

日常使用

对话手动执行：用户说"跑一次发票转发"等——先执行 python3 scripts/invoice_forward.py scan 向用户展示将发送清单，用户确认后再执行 python3 scripts/invoice_forward.py run 并复述输出（已发送/跳过/无PDF 各几封）。仅当用户明确说"直接发、不用确认"时才跳过 scan 直接 run。
指定扫描窗口：scan --days 30 / run --days 30（默认取 config.json 的 scan.days）。
预览不发送：python3 scripts/invoice_forward.py scan（不写状态、不发送，随时可跑）。
修改规则：直接编辑 ~/.workbuddy/invoice-forward/config.json 后重跑 check 验证。
调试单张发票：python3 scripts/invoice_forward.py parse /path/to/发票.pdf（或 .ofd / .xml，自动识别格式）。

行为与边界

去重：按 Message-ID + 发票号双重去重，run 重复执行不会重复转发（状态存于 ~/.workbuddy/invoice-forward/processed.json）。
链接型发票（无 PDF 附件）：邮件没有发票附件时，自动扫描正文链接（HTML 的 href/src + 纯文本 URL，HTML 实体反转义）逐一尝试下载，仅当最终响应确为发票文件才采用——支持 PDF / OFD / XML 三种格式（按 Content-Type / Content-Disposition 后缀 / 魔数判定：PDF=%PDF、OFD=ZIP 且含 OFD.xml、XML=<?xml 开头），随后照常解析转发。适用于腾讯云电子发票等"邮件内只有下载链接"的场景（实测：腾讯云用 COS 预签名 URL，无需登录即可下载）。链接均失败才列入"无发票待人工"并注明原因（链接未返回发票文件=可能需登录或链接已过期 / 链接抓取已禁用）。
链接抓取安全闸门：config.json 的 scan 段可设 fetch_links（默认开）、link_domains（非空时仅下载这些域名后缀的链接，如 ["myqcloud.com","tencent.com"]，空=全部）、link_timeout（下载超时秒）、link_max_bytes（单链接上限字节，默认 25MB）、link_user_agent。仅 http(s) 会被下载；字面量私有/环回/链路本地 IP 会被拒绝（SSRF 基础防护）；真正兜底的是"仅接受发票格式响应"——绝不执行下载内容，只保存发票字节。
防循环：收件人地址发来的邮件自动排除。
发送节奏（防反垃圾风控）：config.json 的 send 段可设 interval（每封最小间隔秒）、jitter（额外随机秒上限）、batch_limit（单批上限，超出下轮续跑）。QQ 默认 0 即可；163/126 等严格风控邮箱建议 interval>=3、batch_limit<=20，主题模板建议加 {invoice_no} 提升区分度。
多邮箱：支持在 account.provider 写 qq/163/126/yeah 或域名后缀自动选主机；也可直接写 imap_host/smtp_host 覆盖。网易系（163/126）登录后会自动发 IMAP ID 自报身份以绕过 "Unsafe Login" 风控（否则选文件夹会被拒）。
凭证安全：secrets 文件 chmod 600；也支持环境变量 MAIL_USER/MAIL_AUTH_CODE 临时传入（优先级高于 secrets 文件，便于隔离验证 / CI，授权码免落盘）；排查问题时不得把授权码打印到聊天或日志。
发送侧记录：QQ 邮箱默认不把 SMTP 发出的邮件存入网页版「已发送」，验证送达以收件方为准（用户可在邮箱设置中开启保存）。

常见问题

优先查阅 references/troubleshooting.md（含授权码获取、QQ IMAP 三个实测坑、限流说明、扩展支持 163 等其他邮箱的方法）。