邮件发票归档器

快速开始

• 安装后的首次会话中，在执行任何其他操作前，先向用户询问其希望使用的凭据存储模式。
• 如需查看当前支持的邮箱服务商及其配置说明，请运行 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 包及摘要文件。

工作流

1. 运行 doctor。
2. 若 doctor 报告 setup_required 为真，则首先询问用户希望使用的邮箱服务商：126、163、gmail 或 custom。
3. 询问用户希望使用的认证方式：系统凭据存储（system credential store）、环境变量（environment variables）、配置文件（config file）或每次会话提示输入（prompt-each-session）。
4. 使用选定的邮箱服务商和认证方式运行 setup，然后等待用户确认其已完成所有外部步骤（例如导出环境变量）。
5. 再次运行 doctor，验证配置是否生效。
6. 如需快速预览邮箱内容而不下载附件，可运行 list --month YYYY-MM --limit 20 --json。
7. 运行 sync --month YYYY-MM --json，将候选发票归档至 ~/Documents/invoice-archive/YYYY-MM/ 目录下。
8. 同步完成后运行 report --month YYYY-MM --json 并生成摘要：总金额、标准发票数量、高价值发票、重复项、冲突项及失败项。
9. 运行 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）指定了业务规则（例如统一使用 价税合计 字段作为总金额），则需在后续提取与报告中一致记录并遵循该规则。

资源

• 运行时入口：scripts/cli.py
• 详细兼容性发现与常见陷阱：references/compatibility-notes.md
• 飞书本地配置示例：config/feishu/config.example.yaml

本地密钥配置规范

当本技能需使用飞书（Feishu）应用凭据以支持本地投递助手或后续集成时，严禁将真实密钥存放在已发布的技能目录内。

请采用如下分离方式：

• 提交至仓库的示例配置：位于技能目录内的 config/feishu/config.example.yaml
• 本地实际配置：位于 ~/.config/openclaw/mail_invoice_archiver/feishu.config.yaml

该规范存在的原因：

• .gitignore 可降低 Git 提交风险，但不应被视为技能发布过程中的安全边界。
• 发布流程未必完全等同于 Git 行为，因此真实密钥必须置于技能目录之外。
• 技能包中仅应包含示例、文档及密钥加载逻辑，绝不可包含真实的凭据文件。

飞书凭据推荐加载顺序：

1. 显式设置的环境变量
2. 位于 ~/.config/openclaw/mail_invoice_archiver/feishu.config.yaml 的本地私有配置
3. 提示用户手动输入

环境变量命名：

• MAIL_INVOICE_ARCHIVER_FEISHU_APP_ID
• MAIL_INVOICE_ARCHIVER_FEISHU_APP_SECRET
• MAIL_INVOICE_ARCHIVER_FEISHU_RECEIVE_ID_TYPE
• 可选覆盖路径：MAIL_INVOICE_ARCHIVER_FEISHU_CONFIG

切勿发布或共享真实的本地配置文件。

若在技能目录内发现 config/feishu/config.yaml，应视作不安全的错误配置。运行时应立即失败，并强制要求用户将该文件移出技能目录。