Finance Skill

个人财务记忆层。解析账单、存储交易记录、查询支出情况。

数据位置

• 交易记录：~/.openclaw/workspace/finance/transactions.json
• 原始账单文件：~/.openclaw/workspace/finance/statements/

*存储规范：OpenClaw 工作区（~/.openclaw/workspace/）是持久化用户数据的标准位置。这与会话内存及其他钩子存储代理数据的位置一致。如需配置或凭证，可存放在 ~/.config/finance/ 目录下。*

工具

1. 解析账单

当用户分享账单（图片或 PDF）时：

⚠️ 重要提示：Telegram/频道预览会截断 PDF 内容！

请务必使用 pypdf 提前提取所有页面内容：

python3 -c "
import pypdf
reader = pypdf.PdfReader('/path/to/statement.pdf')
for i, page in enumerate(reader.pages):
    print(f'=== PAGE {i+1} ===')
    print(page.extract_text())
"

然后对完整文本输出进行解析：

1. 从所有页面中提取交易信息
2. 返回 JSON 数组格式：[{date, merchant, amount, category}, ...]
3. 运行 scripts/add-transactions.sh 将新交易追加至存储
4. 验证总金额是否匹配账单（支出总和应等于“总消费”金额）

提取格式：

每条交易记录：{"date": "YYYY-MM-DD", "merchant": "名称", "amount": -XX.XX, "category": "food|transport|shopping|bills|entertainment|health|travel|other"}
负数表示支出，正数表示收入或退款。

分类说明：

• food：餐厅、超市、咖啡、快餐
• transport：Waymo、Uber、加油、公共交通
• shopping：零售、线上购物
• bills：水电费、订阅服务
• entertainment：电影、演唱会、主题公园
• health：药房、医生就诊
• travel：酒店、机票

2. 查询交易记录

用户询问支出情况 → 读取 transactions.json → 筛选与聚合 → 回答问题

示例查询：

• “我上个月花了多少钱？” → 在指定日期范围内统计所有负值金额之和
• “我在食物上花了多少？” → 按类别筛选
• “列出我最大的几笔支出” → 按金额降序排列

3. 手动添加交易

用户输入“我在某地花了 X 元” → 将记录追加至 transactions.json

文件格式

{
  "transactions": [
    {
      "id": "uuid",
      "date": "2026-02-01",
      "merchant": "Whole Foods",
      "amount": -87.32,
      "category": "food",
      "source": "statement-2026-01.pdf",
      "added": "2026-02-09T19:48:00Z"
    }
  ],
  "accounts": [
    {
      "id": "uuid",
      "name": "Coinbase Card",
      "type": "credit",
      "lastUpdated": "2026-02-09T19:48:00Z"
    }
  ]
}

使用流程

1. 用户：*分享账单图片*
2. 代理：通过视觉识别提取交易信息，并确认数量
3. 代理：运行添加脚本将数据存入存储
4. 用户：*“我上个月在食物上花了多少钱？”*
5. 代理：读取存储数据，筛选并返回结果

依赖项

• jq — 用于 JSON 存储与查询操作（安装命令：apt install jq 或 brew install jq）
• pypdf — 用于完整提取 PDF 文本（安装命令：pip3 install pypdf）

经验总结

• Telegram 会截断 PDF 预览 — 请始终使用 pypdf 提取全部页面内容
• 必须核对总额 — 在导入前，将提取出的支出总和与账单中的“总消费”金额进行比对
• Coinbase 卡 — 不支持 Plaid 接入，仅可通过上传账单方式同步数据

未来规划：Plaid 集成

• 新增 finance_connect 工具，支持 Plaid OAuth 流程
• 自动同步已连接银行的交易记录
• 保持相同的查询接口，但数据来源改为实时同步