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
Metadata
Release files for expense-agent 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| expense_agent-0.1.1.tar.gz | 182.5 kB | Without provenance | Details for expense_agent-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| expense_agent-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for expense_agent-0.1.1-py3-none-any.whl |
Total release size: 259.9 kB
Release files / expense_agent-0.1.1.tar.gz
| Download URL | expense_agent-0.1.1.tar.gz |
|---|---|
| Size | 182.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b48834b7292720b241f25ce6448768fad35c7bf9da048ab3a6dd9d2d416369a9
|
|
BLAKE2b-256 checksum How to use checksums |
3459ab9172aec3340ad3f2fb6abe2543de70e4cf95e4f477449c56a42765fccf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.7.12
|
Release files / expense_agent-0.1.1-py3-none-any.whl
| Download URL | expense_agent-0.1.1-py3-none-any.whl |
|---|---|
| Size | 77.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
19f42fcbfa3577d9f702922ff3649223046bc02fc758c68a34348c483aa32f07
|
|
BLAKE2b-256 checksum How to use checksums |
5ebeccfe82ad3f4590ebe68e0cbde674642c2aee11d704cdd18e4f38a34ca147
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.7.12
|
Security for expense-agent 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.