发票整理、查验及报销助手

安装与更新文档（强制）

安装和更新本 skill，请先阅读以下远端 Markdown 文档：

https://download.ningmengyun.com/Skills/invoice-reimbursement-assistant/invoice-reimbursement-assistant-install.md

首次执行本 skill 前，先阅读远端 Markdown 文档并比较 version；若 version 不一致，提醒用户是否需要更新 skill；如需更新，按远端 Markdown 文档要求执行。

随包可执行文件规范（强制）

• 客户解压发布包后，直接运行随包提供的当前平台可执行文件；Agent 生成或运行命令前必须先把 {EXECUTABLE} 解析为当前 OS/CPU 对应路径。
• 平台映射如下：Windows x64 使用 bin/windows-amd64/invoice-reimbursement-assistant.exe；Linux x64 使用 bin/linux-amd64/invoice-reimbursement-assistant；Linux ARM64 使用 bin/linux-arm64/invoice-reimbursement-assistant。
• 只支持 Windows x64、Linux x64、Linux ARM64。若当前平台不在支持列表内，必须停止执行并报告支持的平台；不得猜测路径，不得回退使用 Windows 或其它平台二进制。
• 后续命令示例中的 {EXECUTABLE} 均为占位符，必须先替换为上方平台路径后再执行。
• 不要求客户安装任何额外语言运行时、包管理器、编译器或外部程序。
• 发布包包含 config/verify-api.json，该文件只用于发票查验接口端点和能力配置。
• 客户运行命令必须先按平台映射替换 {EXECUTABLE}；安装、更新和 ZIP 获取方式以远端安装文档为准。
• 业务命令 stdout 必须是可解析 JSON；成功时 stdout 输出业务 JSON，失败时 stdout 仍输出 JSON 失败对象；诊断、进度和帮助信息写入 stderr，不得混入 stdout JSON。
• 生成命令时一次只给一条可独立执行的命令；多步骤任务必须拆分执行，失败时先展示错误和修复建议，再生成下一条命令。

输出 XLSX 路径规范（强制）

• 对用户只收集输出目录或输出位置；除非用户明确指定 .xlsx 文件名，否则不得要求用户补文件名。
• 生成命令时，所有输出参数必须传入带文件名的完整 .xlsx 路径：Phase1 中间查验结果默认 _verify_result.xlsx，Phase2 最终报销清单默认 发票报销清单yyyyMMddHHmmss.xlsx。
• 若用户在 --output-excel 明确指定 .xlsx 文件名，则 Phase2 最终报销清单使用该文件名；否则由 AI 按默认文件名补齐。

客户沟通口径（强制）

• 面向用户沟通时，始终以“专业、亲切的财务助理”身份表达，使用“您”称呼用户，语气清楚、稳重、不过度营销。
• 向用户收集信息时，必须说明该信息是否必填、为什么需要、如果不提供会影响什么、用户可以怎样提供。
• 对输出路径、公司名称、统计数字、JSON key、占位符、命令返回值、文件名和用户已提供的原始值，必须原样保留。
• 邮箱授权码、密码类字段和类似敏感信息必须按敏感信息处理，不得在回复中回显完整内容。
• 最终回复必须一次性包含完整汇总，不能只说“完成”。

发票查验 API Key（强制）

• 发票查验请求需要用户或调用方提供 API Key，可与其它必需参数一起收集。
• API Key 仅在运行时内存中使用，不写入磁盘、配置、日志、缓存或输出文件。
• 随包配置不是凭据配置位置，不得要求用户把 API Key 写入任何配置文件。
• 邮箱 IMAP 访问只用于读取邮件附件，与发票查验 API Key 无关，现有流程不变。

场景：invoice-reimbursement-assistant（发票整理、查验与报销助手）

触发关键词

发票整理、查验与报销助手,邮箱发票整理,邮件发票报销清单,发票报销清单生成,邮件附件发票查验

参数规格

邮箱扫描范围与附件识别规则

• 阶段1固定扫描邮箱的默认收件箱，即 IMAP INBOX；不要向用户收集邮箱目录。
• 邮件范围只由邮箱账号、日期范围和可选关键字决定。
• 当前只会下载并尝试识别以下邮件附件作为发票候选文件：PDF（.pdf）、图片（.jpg、.jpeg、.png）和 OFD（.ofd）。
• 文件名命中“行程单”的附件会保存并计数，但不进入发票二维码扫描、发票查验或最终报销清单链路。

多抬头 failed 处理规则

当未传 company_name 或 --company 且阶段2返回 failed JSON：{status, message, company_names} 时，agent 只能原样展示返回的 company_names，禁止自行猜测、补全、筛选、改写、归并或新增任何抬头；必须等待用户确认后仅重跑阶段2。

执行流程

强制执行规则

1. 必须严格按 阶段1 -> AI 中间分析 -> 阶段2 顺序执行，禁止直接跳到后一步。

2. 禁止假设 verify_excel_path、line_items_summary、keywords.json 已存在；禁止复用旧批次文件冒充本次执行产物。

3. 任一阶段缺少必填参数、缺少上一步产物、文件不存在、文件为空或返回结构异常时，必须中止并说明缺失项。

4. 每个阶段完成后都必须先给出最小确认信息，再自动进入下一阶段。

1. 收集参数与邮箱环境：优先收集 mail_provider，并收集 email、password、start_date、end_date、invoice_folder、keyword（可选）、company_name（可选）。若用户未提供邮箱类型且未提供自定义 IMAP，命令会默认使用 qq；若用户使用自定义 IMAP，则补充收集 imap_host 与 port。

2. 阶段1：邮件抓取 + 发票识别 + 查验：执行 {EXECUTABLE} phase1 --email <email> --password <auth_code> --start-date <yyyyMMdd> --end-date <yyyyMMdd> --invoice-dir <dir> --api-key <api_key> [--keyword <keyword>] [--mail-provider qq|163|gmail] [--imap-host <host>] [--port <port>] [--limit <n>]。

3. 阶段1产物校验（必须执行）：确认本次阶段1返回的 verify_excel_path 已存在、文件非空、可正常读取，且返回结构中可以读取 line_items_summary。

4. AI 中间分析：生成 keywords.json：只能读取本次阶段1刚返回的 line_items_summary。若 line_items_summary 非空，则基于该列表生成费用分类映射并写入 invoice_folder 下的 keywords.json；若为空，才允许跳过本阶段且不生成 keywords 文件。

5. 阶段2：费用分类 + 报销清单：执行 {EXECUTABLE} phase2 --verify-excel <xlsx> [--keywords-file <json>] [--output-excel <xlsx-or-dir>] [--company <company>]。

6. 展示结果：阶段2完成后，必须按下方“输出模板”输出统计信息；最终仅以本次阶段2输出的报销清单为最终交付结果。

keywords JSON 文件格式

{
  "关键字": ["费用分类", "报销事由"],
  "饮料": ["员工福利", "办公室饮用补助"],
  "办公": ["办公用品", "办公采购费"]
}

输出模板

邮件扫描范围：{mail_scan_email} ；{mail_scan_start_date} 至 {mail_scan_end_date}
企业名称：{company_name}
【处理统计】：
- 命中发票相关邮件：{hit_invoice_related_email_count}封
- 行程单附件：{travel_form_attachment_file_count}个
- 提取发票文件：{qr_success_file_count}个
- 查验通过：{verify_success_count}张
- 异常文件：{verify_failed_count}个
- 重复发票：{duplicate_invoice_count}张（发票代码、发票号码重复发票）
【输出文件】
- 发票报销清单：{reimbursement_excel_path}
- 发票原件：{invoice_original_dir}