financial-expense-automation

name	financial-expense-automation
description	当用户上传 PDF、JPG、JPEG、PNG 附件，或消息中包含"报销""发票""票据""录入""火车票""机票"等关键词时触发。对附件内容进行识别，若确认为报销票据则提取结构化字段并写入飞书多维表格；若识别后内容不是报销票据，告知用户并终止流程。

Financial Expense Automation

目标

运行本地 Financial Automation 流水线，对用户上传的报销票据进行：

• 识别
• 结构化提取
• 校验
• 真实写入飞书多维表格

请始终记住：

• bitable_write_plan 只是中间产物
• 识别成功不等于任务完成
• 只有真实调用 Feishu Bitable create/update 成功，并完成回读确认，才算完成

项目依赖

这个 skill 依赖完整项目仓库，不能只拷贝 SKILL.md 单独使用。

按以下顺序定位项目根目录：

1. 环境变量 FINANCIAL_AUTOMATION_ROOT
2. ~/projects/agentic-ai/financial-automation
3. ~/.openclaw/workspace/financial-automation

若这些路径都不存在，应明确告诉用户：当前环境尚未部署完整项目仓库，请先完成部署。

主要入口与配置：

• <repo_root>/src/skill_entry.py
• <repo_root>/config/app_config.yaml

支持输入

附件输入格式：

[
    {"file_name": "hotel_invoice.pdf", "content_bytes": b"..."},
    {"file_name": "ticket.jpg", "source_path": "/path/to/ticket.jpg"},
]

支持文件类型：

• .pdf
• .jpg
• .jpeg
• .png

若过滤后没有可处理附件，应直接告知用户：没有收到可处理的报销附件。

非报销内容处理

识别完成后，若内容不是报销票据（如普通图片、截图、合同等），应：

1. 告知用户：该附件不是可识别的报销票据
2. 简述识别到的内容类型
3. 终止流程，不继续写表

唯一入口

必须通过：

from src.skill_entry import run_skill_job
result = run_skill_job(attachments)

如有需要可显式传配置：

result = run_skill_job(
    attachments,
    config_path=f"{repo_root}/config/app_config.yaml",
)

不要手工拼接 ingest / OCR / validate / formatter 流程。

正式执行流程

1. 定位 repo root
2. 将用户上传文件整理成 run_skill_job(...) 所需的附件 payload
3. 调用 run_skill_job(...)
4. 使用返回的 skill_result 作为识别结果主对象
5. 生成真实写表输入
6. 若当前会话具备 Feishu Bitable 工具能力，继续执行真实写表
7. 写入后回读确认，再向用户回复结果

写表强制规则

1. bitable_write_plan 只是中间产物，不是最终结果
2. 只要当前会话可用飞书多维表格工具，就必须继续真实写表
3. 禁止停留在“建议写入 / 准备写入 / 可写入”状态
4. 只有真正调用 create/update 成功，才算完成
5. 如果没有真实写入成功，必须明确说明失败点
6. 禁止把“已识别 / 已生成 plan / 已生成 handoff”描述成已经完成落表

目标表路由规则

• transportation_fee → 交通报销表
• 其他费用类票据 → 费用报销表

写入策略

默认采用：

• update_first_blank_row_then_create

具体规则：

1. 先查询目标表
2. 若存在可复用空白行（优先判断 doc_id 为空），优先 update
3. 若不存在可复用空白行，再 create
4. 不要盲目追加新记录

附件写入规则

附件字段必须遵守以下规则：

1. 禁止直接使用通用 Drive upload token 作为 Bitable 附件
2. 必须先上传到当前 bitable attachment context
3. 再将返回的合法 file_token 写入附件字段
4. 图片走 bitable_image
5. PDF/其他文件走 bitable_file

降级规则

如果当前环境附件链路不可用：

• 不要伪造 file_token
• 不要把通用 Drive token 冒充 bitable 附件
• 可以先真实写入非附件字段
• 并明确告诉用户：附件尚未成功挂载

注意：

• 如果附件失败但非附件字段已落表，必须把两件事分开说清楚
• 如果连真实 create/update 都没发起，也必须明确说明尚未完成真实写表

PDF / 图片识别规则

• 图片走 OCR
• PDF 优先走原生文本抽取
• 如果 PDF 原生抽取结果不足或不可用，应继续走 OCR fallback
• 不能因为某个提取分支失败就直接把整单描述成“不可识别”

返回对象重点字段

最重要字段：

• user_summary
• summary
• highlights
• documents
• review_queue
• job
• bitable_write_plan

说明：

• documents 是标准化结构化结果
• review_queue 表示需要人工复核的项目
• bitable_write_plan 是真实写表的中间输入，不是完成态

完成标准

以下情况才算完成：

• 已成功识别票据
• 已成功判断目标表
• 已真实调用 Feishu Bitable create/update
• 已明确回读或确认写入结果

以下情况都不算完成：

• 只输出结构化字段
• 只输出 bitable_write_plan
• 只说“待写入 / 准备写入 / 建议写入”
• 只生成 handoff/prompt 但没有真实 create/update

回复用户规则

回复用户时：

1. 先用 user_summary.headline 概括结果
2. 若有 review_queue，明确列出复核项与原因
3. 发票场景总结购方、销方、金额、项目名称等关键字段
4. 火车票场景总结购买方、路线、日期、乘客、席位等关键字段
5. 不要只汇报识别结果，必须汇报真实写表结果，或明确失败点

当前业务范围

当前优先支持：

• 普通电子发票
• 铁路电子客票

重点提取字段包括：

• 发票号码
• 开票日期
• 金额
• 币种
• 购方与销方信息
• 行项目 / 税率 / 税额
• 铁路票路线 / 车次 / 乘客 / 出行日期 / 席位
• 校验结论与复核原因