Mail Invoice Archiver_办公效率 skill-PHP中文网

Mail Invoice Archiver

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

读取支持的邮箱（如126、163、Gmail），识别发票附件或下载链接，按月归档发票并去重。

邮件发票存档器QQQ快速启动

功能概述

邮件发票存档器QQQ快速启动是一项面向实际任务的技能，主要用于在安装后的第一会话中, 请在做其他事前询问用户想要的证书存储模式；@ info: whatsthon3 { baseDir}/ spits/ cli. py。

核心要点

它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。
使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。
该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。

使用与执行

从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；

结果检查与注意事项

若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。

邮件发票归档器

快速开始

安装后的首次会话中，在执行任何其他操作前，先向用户询问其希望使用的凭据存储模式。
如需查看当前支持的邮箱服务商及其配置说明，请运行 python3 {baseDir}/scripts/cli.py providers --json。
首先运行 python3 {baseDir}/scripts/cli.py doctor --json。若返回结果中包含 setup_required: true，请引导用户完成配置流程，并等待其确认。
使用 python3 {baseDir}/scripts/cli.py setup 启动交互式配置向导；或通过传入 --mail-provider 126|163|gmail|custom 和 --provider system|env|config|prompt 参数实现脚本化配置。
使用 python3 {baseDir}/scripts/cli.py sync --month YYYY-MM --json 将指定月份的邮件拉取至本地归档目录。
使用 python3 {baseDir}/scripts/cli.py report --month YYYY-MM --json 检查该月归档的汇总信息，包括总金额、标准发票数量、高价值发票、重复项、冲突项及失败项。
使用 python3 {baseDir}/scripts/cli.py deliver --month YYYY-MM --json 为当前对话准备一个 ZIP 包及摘要文件。

工作流

运行 doctor。
若 doctor 报告 setup_required 为真，则首先询问用户希望使用的邮箱服务商：126、163、gmail 或 custom。
询问用户希望使用的认证方式：系统凭据存储（system credential store）、环境变量（environment variables）、配置文件（config file）或每次会话提示输入（prompt-each-session）。
使用选定的邮箱服务商和认证方式运行 setup，然后等待用户确认其已完成所有外部步骤（例如导出环境变量）。
再次运行 doctor，验证配置是否生效。
如需快速预览邮箱内容而不下载附件，可运行 list --month YYYY-MM --limit 20 --json。
运行 sync --month YYYY-MM --json，将候选发票归档至 ~/Documents/invoice-archive/YYYY-MM/ 目录下。
同步完成后运行 report --month YYYY-MM --json 并生成摘要：总金额、标准发票数量、高价值发票、重复项、冲突项及失败项。
运行 deliver --month YYYY-MM --json，然后将返回的 ZIP 文件作为附件上传至当前对话，并粘贴摘要文本。

Windows 环境配置

若用户在 Windows 上选择 env 模式，请提供以下任一精确代码片段，并在用户确认后重新运行 doctor。

$env:MAIL_INVOICE_ARCHIVER_EMAIL = "your-mail@example.com"
$env:MAIL_INVOICE_ARCHIVER_AUTH_CODE = "your-provider-secret"
python "{baseDir}/scripts/cli.py" doctor --json

set MAIL_INVOICE_ARCHIVER_EMAIL=your-mail@example.com
set MAIL_INVOICE_ARCHIVER_AUTH_CODE=your-provider-secret
python "{baseDir}\scripts\cli.py" doctor --json

对于 Gmail，MAIL_INVOICE_ARCHIVER_AUTH_CODE 必须是 Gmail 应用专用密码（App Password），而非 Google 账户的常规登录密码。

规则

优先使用以下认证方式：system（适用于 macOS 和 Windows）、env（适用于 Linux、CI 或无界面会话），仅当用户明确拒绝在任何位置持久化密钥时才使用 prompt。
system 当前指：macOS 上的 Keychain，Windows 上的 Credential Manager。
第一阶段内置支持的邮箱服务商为：126、163 和 gmail。
126 邮箱的首选 IMAP 主机为 appleimap.126.com。
仅当对应服务商明确需要时，才向 IMAP 客户端发送已配置的 ID 字段。目前仅 126 和 163 需要该字段，Gmail 不需要。
当前 Gmail 支持基于 IMAP 应用专用密码（App Password）实现，适用于个人 Gmail 账户。部分 Google Workspace 租户可能仍需管理员侧启用 IMAP 或改用 OAuth 认证——该能力属于未来增强特性，不在当前运行时支持范围内。
去重分为两层：
- 存储层去重依据：消息 UID + 部件索引 + SHA256 哈希值；
- 业务层去重依据：发票号码 + 金额。
若发票号码相同但金额不同，则保留两个文件，并将其报告为“冲突”（conflict），禁止自动合并。
发票金额与 OCR 结果应保存于 SQLite 元数据中，不得嵌入文件名。
若链接下载失败，但该邮件仍符合发票特征，则需将该失败情况反馈给用户。
当一封邮件中以多种附件格式出现同一张发票时，应优先选择对用户更友好的格式作为标准归档文件。默认格式优先级为：图像（png/jpg/jpeg）或 PDF 优先，其次为 XML，再次为 OFD，最后为 ZIP。若同一发票已有可读的 PDF 或图像版本，则不得优先选用 OFD 或 ZIP。
OFD 应视为归档备选格式，而非默认面向用户的格式；仅当其为唯一可用的标准表示形式时方可作为主格式。
从 PDF 发票中提取金额时，不可盲目选取第一个出现的 ¥ 金额。PDF 文本提取可能打乱发票区域顺序，导致税基金额、税额与合计金额被错误排序。
针对 PDF 发票，应优先使用专用于“合计金额”的提取器，而非通用正则表达式回退方案。优先定位发票中的“合计金额”区域进行提取；仅当该区域缺失时再启用回退逻辑。
PDF 发票中买方与卖方名称在文本提取后可能出现 名称：名称： 这类重复布局。此时应优先采用布局感知型提取方法，而非单条正则表达式，以准确区分买方与卖方。
月度汇总结果必须保持稳定，即使某条当月记录因与窗口期外的旧标准记录匹配而被标记为 duplicate。汇总逻辑应基于当月的业务主键聚合，而不仅限于按当月内 status='saved' 的行进行统计。
若用户为特定发票类型（invoice family）指定了业务规则（例如统一使用 价税合计 字段作为总金额），则需在后续提取与报告中一致记录并遵循该规则。