差旅费用自动报销助手

📊 完整流程图见 references/flowchart.md，建议先阅读流程图了解整体流程。

一、能力范围

• 支持：
  • 12306火车票电子客票
  • 携程机票电子行程单
  • 去哪网机票/酒店
  • 华住会酒店住宿发票
  • 美团发票（外卖、酒店、打车等）
• 功能：读取邮箱、下载PDF附件/通过链接下载发票PDF、解析发票信息、生成报销数据、上传发票到FOL、提交差旅报销
• 发票获取方式：
  • 附件下载：邮件直接携带PDF附件，通过 himalaya/IMAP 下载
  • 链接下载：邮件正文含发票链接，通过浏览器自动化访问并下载PDF
• 限制：非发票类邮件会被过滤掉，但不会人为限制发票类型

二、依赖技能

三、全局执行规则

🚫 IMAP 严格串行规则（重要）

所有涉及 IMAP 连接的操作必须严格串行执行，禁止并发调用同一邮箱账号。

• IMAP 连接是同步阻塞 IO，单连接串行操作最稳定
• 每次 imaplib.IMAP4_SSL() 操作完成后记得 mail.logout()
• 不需要在 exec 中设置特殊超时，Python imaplib 自己管理超时
• 如果 IMAP 连接超时或报错，立即切换到 himalaya CLI（最后备用）

🚫 OCR 严格串行规则

OCR 解析必须一张一张串行执行，禁止并发/并行调用多个 OCR 进程。

RapidOCR 每进程需加载模型占用 350MB+ 内存，并行会导致内存暴涨触发 OOM Killer 杀死 gateway 进程。

四、执行步骤（严格按顺序执行）

步骤1：初始化工作目录

工作目录：/tmp/openclaw/uploads/{session_id}/（每次报销使用独立的动态子目录，如 /tmp/openclaw/uploads/run-20260529-001/）。

创建子目录：

/tmp/openclaw/uploads/{session_id}/
├── inbox/             # 所有发票PDF统一存放，不做分类子目录
├── processed/         # 已解析的发票数据
└── output/            # 生成的报销文件

动态目录命名规则：run-{YYYYMMDD}-{序号}，先检查 /tmp/openclaw/uploads/ 下已有目录避免冲突。

步骤2：从邮箱搜索并下载邮件附件

四步判断流程（严格按顺序执行）：

第一步：判断有无附件

通过 himalaya envelope list 获取今日邮件列表，根据发件人和主题过滤出发票邮件。 对每封邮件判断：himalaya message read 查看邮件结构，确认是否有 PDF/OFD 附件（has_attachment: true 的邮件）。

第二步：有附件则下载附件

对有附件的邮件，执行：

himalaya attachment download  -d /tmp/openclaw/uploads/{session_id}/inbox/

附件直接落入 inbox/，标记该邮件处理完毕，跳过第三、四步。

第三步：无附件则提取下载地址

对无附件的邮件，读取正文（himalaya message read ），按以下优先级提取下载 URL：

1. 正则提取：re.findall(r'https?://[^s"''<>]+', text) 从 HTML 正文直接匹配 http 链接
2. 解析 MIME 结构：用 Python email 模块解析原始邮件，对每个 part 的 text/html 或 text/plain 内容深度扫描 URL
3. 按钮文字识别：若正文仅含"下载PDF文件"等按钮文字而无真实链接，标记为链接不可提取，进入第四步

常见发件人 URL 特征：

• 百望：pis.baiwang.com/smkp-vue/previewInvoiceAllEle?param=
• 吉祥航空：einvoice@juneyaoair.com / www.juneyaoair.com/eflight/invoice
• 深圳航空：百望链接（同百望逻辑）

第四步：下载无附件情况的发票 PDF

调用 url_downloader.py 下载：

import sys
sys.path.insert(0, '/app/skills/travel-expense-reimbursement/references')
from url_downloader import download_file

filepath = download_file(
    url='<提取到的URL>',
    save_dir='/tmp/openclaw/uploads/{session_id}/inbox/',
    filename_hint='invoice.pdf',
)

下载策略（curl 优先，Playwright 兜底）：

curl 直接下载
  ↓ 失败（超时/非PDF响应）
Playwright 访问页面
  → 页面直接触发 PDF 下载？拦截保存
  → 未触发？查找并点击下载按钮
  → 找到 PDF 直链？curl 下载
  → 全部失败 → 截图备用，告知用户手动下载

扩展新的发票下载类型（在 url_downloader.py 中添加 handler）：

def download_myinvoice(page_url: str, save_dir: str) -> Optional[str]:
    return download_file(page_url, save_dir)

URL_PATTERN_HANDLERS.append((
    'https://myinvoice.example.com/',
    download_myinvoice,
))

⚠️ 吉祥航空特别说明：部分吉祥航空邮件正文中的"下载PDF文件"仅为文字按钮，非真实超链接。若第二步和第三步均无法获取真实下载地址，应告知用户手动从吉祥航空App或官网下载发票附件后发送至邮箱。

步骤4：OCR解析发票

批量解析：所有 PDF 一次性完成，不逐张调用。

import sys
import os
import glob
sys.path.insert(0, '/app/skills/pdf-ocr-skill/scripts')
from pdf_ocr_processor import PDFOCRProcessor

inbox_dir = '/tmp/openclaw/uploads/{session_id}/inbox/'
pdf_files = sorted(glob.glob(os.path.join(inbox_dir, '*.pdf')))

processor = PDFOCRProcessor(engine='rapid')
results = []
for pdf_path in pdf_files:
    result = processor.ocr_pdf(pdf_path)
    results.append({
        'pdf_path': pdf_path,
        'filename': os.path.basename(pdf_path),
        'text': result['text'],
        'page_count': result['page_count']
    })
    print(f"[OK] {os.path.basename(pdf_path)} ({result['page_count']}页)")

# 输出汇总供后续步骤使用
import json
print('n=== OCR_RESULTS_JSON ===')
print(json.dumps(results, ensure_ascii=False))

• 批量解析完成后，所有发票的 OCR 文本在 results 列表中，进入步骤5汇总
• 不再逐张调用 pdf-ocr，所有 PDF 在一条 exec 命令内全部完成

步骤5：发票信息汇总

1. 按时间排序，生成 /tmp/openclaw/uploads/{session_id}/processed/invoice-list.json
2. 向用户展示发票汇总表（表格形式）：类型、发票号码、行程/内容、日期、金额、姓名
3. 标注总金额
4. 明确说明过滤掉的非目标人员发票

步骤6：行程分析

依据 references/行程分析指南.md 分析行程，先自行分析整理，遇到不确定的再问用户。

步骤7：确认报销参数（记忆 + 交互式）

以下参数从发票自动推断，不需要问用户：

• 出发/出差城市、交通方式、住宿天数、附件路径等

只需要确认两个参数：报销事由和项目名称。

7.1 读取记忆

通过 memory_search 搜索历史报销记忆，关键词：报销 项目名称、差旅报销 事由

7.2 确认参数

向用户一次性确认：

请确认：
- 报销事由：出差（记忆中最常用）/ 或用户输入
- 项目名称：????（历史曾用：A、B、C）/ 或用户输入新项目

其余参数不询问，从发票自动填充。

7.3 写入记忆

用户确认后，只将事由和项目名称写入 memory/YYYY-MM-DD.md：

## 差旅报销 (当日日期)

- 事由: XXX
- 项目名称: XXX

步骤8：上传发票到FOL

调用 fol-invoice-upload 技能，一次性批量上传所有发票PDF（不要逐张上传）。

收集所有待上传发票的文件路径列表，一次性传递给上传流程（如果上传流程支持批量），或尽可能连续快速上传减少等待。

发票文件路径使用 /tmp/openclaw/uploads/{session_id}/inbox/ 下的文件。

步骤9：提交报销

调用 fol-travel-expense 技能，按行程分段提交报销单。

步骤10：输出结果

向用户展示：处理发票数、总金额、行程汇总、提交状态。

五、错误处理

六、支持的邮箱发件人