发票工作流

概述

把「QQ 邮箱里的发票」变成「桌面一份按类别分 sheet 的 Excel 汇总」。本技能已优化为极简入口：你只需加载后输入「执行」，剩下的一步步跟着卡片选就行，不用记任何命令、不用写 prompt、也不用打字描述需求。

启动方式（唯一入口）

• 加载本技能后，首条消息输入「执行」即开始引导流程。
• 如果你还没输入「执行」就发了别的消息，回复你：请直接输入「执行」两个字启动发票整理流程。

交互铁律（本技能必须 100% 遵守，违反即为执行错误）

铁律 1 · 顺序不可颠倒，一步一问严格按 第 0 步 → 第 1 步 → 第 2 步 → 第 3 步 → 第 4 步 → 第 5 步 推进。在邮箱凭据拿到手之前，绝对不要去问时间范围（凭据是后续一切的前提）。每次只推进当前这一步，拿到用户回复才进下一步；不得跳步、不得把后面步骤的问题提前问、不得一口气连问好几个参数。

铁律 2 · 全程用选项卡交互，禁止让用户自由输入凡需要用户提供信息或做选择（邮箱、授权码、时间范围、是否删除、是否保存配置……），必须调用交互式选项卡工具（AskUserQuestion）呈现，由用户在卡片上「点选选项」或「在卡片自带输入框里填写」。严禁出现这类自然语言讨要：

• ❌「请把下面两项发我（直接贴这里即可）：邮箱地址 / 授权码」
• ❌「请告诉我你要检查哪段时间的邮件」
• ❌ 任何形式的「请用户自己打字回复」话术

正确做法：把要收的信息做成选项卡问题，文本类信息（邮箱、授权码）给一个「在下方输入框填写」选项，用户选它之后直接在输入框里填。

铁律 3 · 全面脱敏技能包内不得出现任何真实个人信息：真实邮箱、真实手机号、授权码、密钥、真实姓名/公司名、含真实用户名的路径。一律用占位示例：邮箱 xxxxxx@qq.com、授权码 abcd1234efgh、路径 C:/Users/用户名/Desktop/...。（本技能包已按此规则脱敏，后续改动也须遵守。）

引导流程（每一步都通过选项卡等你确认后再继续）

第 0 步 · 前置准备：先连接你的 QQ 邮箱（必须先做，做完才问时间范围）

0.1 先给两种方式的操作说明（纯展示，不要求你打字）：

• 方式 A · 邮箱名 + 授权码：适用于你还没在 WorkBuddy 里连过 QQ 邮箱的情况。先去网页版 QQ 邮箱开通 IMAP：

设置 → 账户 → POP3/IMAP/SMTP/…服务 → 开启 IMAP/SMTP 服务 → 按提示生成授权码

注意：要用的是授权码（16 位），不是 QQ 登录密码。开通后到下方卡片填写邮箱 + 授权码即可。

• 方式 B · 连接器已连接：适用于你之前已经在 WorkBuddy 左侧连接器里完成过 QQ 邮箱授权连接。这条路不需要授权码——技能直接通过已连接的 QQ 邮箱连接器读取邮件、逐条下载附件（中小范围很省事；因为是逐条下载，比脚本直连稍慢）。

0.2 先弹「连接方式」选择卡片（调用 AskUserQuestion，一次只问 1 个问题）：

这一步必须最先问，在收任何邮箱 / 授权码 / 时间范围之前。

0.3 按选择分支处理：

• 选「邮箱名 + 授权码」 → 弹凭据卡片（调用 AskUserQuestion，一次问以下 3 个问题，用户在卡片输入框填写）：

• 用户在选项 1 选「使用已保存的配置」时，跳过提问 2，直接读 scripts/config.json。
• 用户在提问 2 选了「还没生成，先看步骤」时，重新展示 0.1 的生成路径说明，然后再次弹出同一张卡片，不要改用文字索要。
• 选「连接器已连接」 → 检查 WorkBuddy 的 QQ 邮箱连接器当前连接状态：
  • 若连接器已连接：跳过授权码填写，直接确认就绪，进入第 1 步（后续下载走连接器路线，见「执行细节 · 步骤 1-B」）。
  • 若连接器未连接 / 连接失效：提示「检测到 QQ 邮箱连接器尚未连接（或连接已失效），请先在 WorkBuddy 左侧连接器里完成 QQ 邮箱授权」，随后重新弹 0.2 的方式选择卡片让用户改选方式 A。

0.4 检查依赖：确认本机已装 pymupdf openpyxl pillow；缺哪个就给出对应安装命令（pip install pymupdf openpyxl pillow），等装好再继续。

等你以某种方式确认 QQ 邮箱已就绪（填好授权码 / 确认使用已保存配置 / 确认连接器已连接）后，才进入第 1 步。此前不得询问任何时间范围相关的问题。

第 1 步 · 用选项卡确认发票邮件的时间范围

1.1 弹出选项卡（AskUserQuestion），header「时间范围」，问：要整理哪个时间段的发票邮件？选项：

• 最近 30 天
• 最近 90 天
• 今年至今
• 自定义区间（在下方输入框填写，格式：2024-01-01 到 2026-08-15）

1.2 收到后按当前连接方式换算成对应的查询参数，再弹一张确认卡片给你确认（选项：确认无误，开始下载 / 我要修改）：

• 方式 A（脚本） → 换算成脚本参数 --since（含）/ --before（不含）；脚本内部会自动转成 IMAP 要求的日期格式。
• 方式 B（连接器） → 换算成连接器参数 after（含）/ before（不含），用 ISO 8601（如 2026-08-15）。

等你确认后，按当前方式执行下载（方式 A：运行 invoice_download.py；方式 B：走连接器路线，见「执行细节 · 步骤 1-B」），把发票附件按类别下到桌面 QQ邮箱发票/ 文件夹，并告诉你下载了多少个、各分类各多少。

第 2 步 · 内容核查 + 清理（只留纯发票，删前必确认）

1. 自动运行内容核查脚本（不删任何文件），按「实际内容」判定哪些是非发票（汇总单/行程单/对账单/保险/明细/账单等），生成待删清单。
2. 用选项卡给出待删清单摘要：header「清理确认」，问「以下 N 个文件判定为非发票，是否删除？」，选项：确认删除 / 先别删，我看看清单 / 只删除前 10 个试试。详细清单同时在正文列出，并说明会先整目录备份、再进回收站（可恢复、每批≤10个）。

你确认后，才执行清理；若选「先别删」，立即停下等你。

第 3 步 · 全部转为 PDF（非破坏性）

1. 你确认清理后，自动运行转 PDF 脚本：把 zip/ofd/图片/xml 统一渲染成 PDF，原文件保留不删。
2. 完成后告诉你生成了多少 PDF、有无失败。

自动进行，无需确认。

第 4 步 · 汇总成 Excel

1. 自动运行汇总脚本，生成桌面 发票信息汇总.xlsx：
   • 7 个 sheet：汇总 + 6 个分类子表（餐饮 / 差旅票务 / 加油费 / 商超购物 / 通讯话费 / 其他发票）。
   • 17 列：序号 / 发票日期(收信) / 发票类型 / 发票代码 / 发票号码 / 开票日期(发票) / 购买方名称 / 购买方纳税人识别号 / 销售方名称 / 销售方纳税人识别号 / 发票内容 / 金额(不含税) / 税率 / 税额 / 价税合计 / 文件名 / 原始发票文本。

自动进行，无需确认。

第 5 步 · 完成汇报

告诉你：

• 桌面 QQ邮箱发票/ 里纯发票 PDF 的位置；
• 桌面 发票信息汇总.xlsx 的最终交付路径；
• 本次下载 / 清理 / 转换 / 汇总的统计数字；
• 已知的小局限（约 15% 买/卖方列可能为空等，详见下）。

执行细节（脚本原样保留，供排错参考）

四步流水线，脚本均在 scripts/ 下，参数化、可复用。

步骤 1 · 连接 QQ 邮箱，按时间段下载发票

python scripts/invoice_download.py --email xxxxxx@qq.com --auth-code abcd1234efgh 
    --since 2018-01-01 --before 2026-08-15 
    --root "C:/Users/用户名/Desktop/QQ邮箱发票"

• 按邮件主题自动分到子目录：餐饮 / 差旅票务 / 加油费 / 商超购物 / 通讯话费 / 其他发票。
• 文件名加 YYYY.MM.DD. 日期前缀（来自邮件收发时间）。
• 仅下载带附件的邮件；链接型发票（无附件）本次不下载，会在 download_report.json 列出，按需另议。
• ⚠️ QQ 邮箱总邮件量大（数千封），务必用 --since/--before 限定范围，避免全量拉取过久。
• 凭据也可提前写入 scripts/config.json：{"email":"xxxxxx@qq.com","auth_code":"abcd1234efgh"}（第 0 步卡片选「保存」时由技能自动写入）。

步骤 1-B · 方式B专用：通过「QQ 邮箱连接器」下载（免授权码）

当用户在第 0 步选了「连接器已连接」，不要运行 invoice_download.py，改走已连接的 QQ 邮箱连接器：

1. 用连接器的消息列表/搜索能力（mcp__qq-mail__ListMessages 或 mcp__qq-mail__SearchMessages）在 dir=inbox 下按 after/before（ISO 8601）+ has_attachments=true 拉取命中邮件；分页拉取（limit 最大 50，用 cursor 翻页）直到取完。
2. 对每封邮件用 mcp__qq-mail__ListAttachments（传 message_id）拿到附件的 attachment_id、文件名、大小。
3. 对每个附件用 mcp__qq-mail__DownloadAttachment 取回 Base64 内容，先落到临时 .b64 文件，再用本技能脚本解码落盘并按分类归档：

   python scripts/save_b64_attachment.py --b64-file "<临时.b64>" 
       --root "C:/Users/用户名/Desktop/QQ邮箱发票" 
       --cat "<餐饮/差旅票务/加油费/商超购物/通讯话费/其他发票>" 
       --date "<邮件日期前缀，如 2026.04.09.>" --name "<原附件名>"

分类沿用 invoice_download.py 里的 classify() 规则（按邮件主题判断）；日期前缀取邮件收发日期，格式 YYYY.MM.DD.。

1. 落盘结构、文件命名与方式 A 完全一致，因此步骤 2 / 3 / 4 照常用脚本运行（它们只处理本地文件，与下载方式无关）。方式 B 下也照常生成 download_report.json（字段与脚本一致）。
2. ⚠️ 连接器逐条下载较慢、每页最多 50 封：务必先用时间范围缩小命中量；若命中数很大（数百封以上），建议提示用户改用方式 A（脚本直连）更快。

步骤 2 · 逐一打开，内容核查，只留纯发票

核心原则：按「实际内容」判定，绝不只看文件名。 历史教训：文件名含「行程/明细」的高德打车电子发票是真发票，而「通行费电子票据汇总单」才是非发票。

python scripts/invoice_content_verify.py --root "C:/Users/用户名/Desktop/QQ邮箱发票"

• 输出 content_verify_plan.json：keep（纯发票信号）/ delete（汇总单/行程单/对账单/保险/明细/账单等非发票）/ visual（有文件但无明确信号，需人工/多模态视觉确认）/ unopenable（损坏/空文件，默认保留待核）。
• 对 visual 项：用 Read 工具打开 scripts/inspect/ 下渲染的 PNG，肉眼判定是否纯发票，必要时把误判项在 plan 里手动改归类。
• 确认 delete 列表无误后执行删除（先整目录备份，再进回收站，每批≤10个）：

python scripts/invoice_cleanup.py --root "C:/Users/用户名/Desktop/QQ邮箱发票" --apply

• 关键坑：不要把 header 当删除词——数电发票 XML 内部含 <Header> 标签会误伤真发票。

步骤 3 · 全部转为 PDF（非破坏性）

python scripts/invoice_convert.py --root "C:/Users/用户名/Desktop/QQ邮箱发票"

• 自动把 zip 解压、ofd/图片/xml 渲染为 PDF；已存在同名 PDF 的跳过，不删原文件。日志见 convert_log.json。
• 目的：统一为可文本提取的 PDF，供步骤 4 解析。

步骤 4 · 汇总成 Excel

python scripts/invoice_excel_build.py 
    --root "C:/Users/用户名/Desktop/QQ邮箱发票" 
    --out "C:/Users/用户名/Desktop/发票信息汇总.xlsx"

• 生成 7 个 sheet：汇总（各类张数+价税合计求和）+ 6 个分类子表。
• 每表 17 列：序号 / 发票日期(收信,取文件名日期前缀) / 发票类型(普票/专票) / 发票代码 / 发票号码 / 开票日期(发票) / 购买方名称 / 购买方纳税人识别号 / 销售方名称 / 销售方纳税人识别号 / 发票内容 / 金额(不含税) / 税率 / 税额 / 价税合计 / 文件名 / 原始发票文本。
• 原始发票文本 保留 100% 内容作兜底，结构化字段解析不全时可直接查原文。

输出与产物

• 桌面 QQ邮箱发票/：纯 PDF 发票（按类别分子目录）。
• 桌面 发票信息汇总.xlsx：最终交付。
• scripts/ 下还会产生：download_report.json、content_verify_plan.json、convert_log.json、invoice_data.json、inspect/（视觉核查切片）。

已知边界（PDF 文本层固有，属正常局限）

• 电信类发票买/卖方版式乱序；数电发票(dzfp)名称在文本层被 · 掩码 → 这两类买/卖方列可能空（约 15% 单元格）。
• 极个别无日期前缀的文件（如 03200170031141907642.pdf）收信日期列为空。
• 字段填充率参考：类型/号码/合计 100%、开票日期 90%、内容 90%、金额税额 86%、买/卖方 85%、发票代码 74%。

安全规范（个人文件，必须严格遵守）

• 删除（步骤 2）只进回收站，不 rm；执行前整目录备份；每批 ≤10、校验后继续、失败即停。
• 下载/转换均非破坏性，原始附件保留直至用户确认。
• 所有「删除 / 覆盖」动作前必须拿到用户明确确认（通过选项卡），不得擅自执行。
• 凭据隐私：邮箱、授权码仅在本地 scripts/config.json 存放（如用户选择保存），不得写入技能包、日志或回复正文；回复里一律用 xxxxxx@qq.com 形式指代。