expense-agent 0.1.1

Local reimbursement invoice and payment proof matching agent

Expense Agent

本地运行的报销凭证匹配与自动命名 Agent。当前版本使用规则引擎，不依赖大模型。

支持 macOS、Linux 和 Windows。Python 要求 3.10+。

安装

pip install expense-agent
# 或
uv add expense-agent

首次运行时 PaddleOCR 会自动下载模型文件（约 100 MB），请保持网络畅通。

本地批处理

expense-agent --input ./input --output ./output

输入

支持 pdf、jpg、jpeg、png。

• PDF：使用 pypdf 提取文本。
• 图片：默认使用 PaddleOCREngine 调用 PaddleOCR。若 PaddleOCR 未安装或初始化失败，会在结果中输出明确错误信息。
• 开发和测试时可使用同名 .txt 旁路作为 mock OCR 文本。例如 payment.png 对应 payment.txt。

输出

输出目录包含：

• renamed/：按建议文件名生成的副本，不覆盖原始文件。
• result.json：结构化识别和匹配结果。
• summary.txt：人工可读摘要和异常说明。

异常、风险和审核提示只写入 result.json 与 summary.txt，不会塞进文件名。

飞书多维表格 Job

手动处理一批"待处理"记录：

expense-agent-feishu --once

定时串行处理：

expense-agent-feishu --schedule

配置

在运行目录下创建 .env 文件，只需填写 4 个飞书凭证：

FEISHU_APP_ID=
FEISHU_APP_SECRET=
FEISHU_APP_TOKEN=
FEISHU_TABLE_ID=

Job 启动时自动读取当前目录下的 .env，无需手动 source。

字段映射（表头名称）已内置默认值，如需覆盖，在 .env 中追加对应的环境变量即可：

# 以下均有默认值，仅在表头与默认不同时才需要覆盖
FIELD_STATUS=处理状态
FIELD_INVOICE=发票原件
FIELD_PAYMENT=支付凭证
FIELD_CONSUMPTION_DETAIL=消费清单
FIELD_OUTPUT_INVOICE=重命名后的发票附件
FIELD_OUTPUT_PAYMENT=重命名后的支付凭证
FIELD_OUTPUT_CONSUMPTION_DETAIL=重命名后的消费清单
FIELD_INVOICE_AMOUNT=发票识别金额
FIELD_PAYMENT_AMOUNT=支付凭证识别金额
FIELD_INVOICE_DATE=开票日期
FIELD_SELLER=销售方
FIELD_BUYER=购买方
FIELD_PAYMENT_TIME=支付时间
FIELD_EXPENSE_TYPE=费用类型
FIELD_MATCH_RESULT=匹配结果
FIELD_RISK=风险等级
FIELD_SUMMARY=处理说明
FIELD_PROCESSED_AT=处理时间
FIELD_ERROR_MESSAGE=错误信息

可选的运行参数：

WORKSPACE_DIR=/tmp/expense-agent-workspace  # 默认走系统临时目录
JOB_BATCH_SIZE=20                           # 1..500，默认 20
JOB_INTERVAL_MINUTES=60                     # --schedule 模式的轮询间隔

工作目录

WORKSPACE_DIR 未设置时默认为系统临时目录下的 expense-agent-workspace（macOS/Linux：/tmp/...，Windows：%TEMP%\...）。按 record 隔离：

• downloads/{record_id}/：原始附件
• outputs/{record_id}/summary.txt 与 result.json：处理结果

返回码

--once 返回码：

• 0：本批次全部记录处理成功，或没有待处理记录。
• 1：至少一条记录处理失败，或本机已有 Job 在运行。
• 2：缺少必填环境变量等配置错误。

开发

依赖通过 uv 管理：

uv run --extra test pytest -q           # 运行全部测试
uv run python -m expense_agent.app.main --input ./input --output ./output
uv run python -m expense_agent.app.feishu_job --once