Finance Skill

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

数据位置

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

存储规范：OpenClaw 工作区（~/.openclaw/workspace/）是持久化用户数据的标准路径，与 session-memory 及其他 hook 存储 agent 数据的位置保持一致。如需存放凭证或配置，应置于 ~/.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. 核对总额是否匹配账单（支出总和应等于账单中的 “Total purchases”）

提取格式要求：

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

分类说明：

• food：餐厅、杂货店、咖啡、快餐等
• transport：Waymo、Uber、汽油、公共交通等
• shopping：实体零售、线上购物等
• bills：水电煤、网络、订阅服务等
• entertainment：电影、演唱会、主题公园等
• health：药房、诊所、医院就诊等
• travel：酒店、航班等

2. 查询交易记录

用户提出关于消费的问题 → 读取 transactions.json → 过滤/聚合 → 给出回答

典型查询示例：

• “我上个月花了多少钱？” → 对指定日期范围内的所有负值金额求和
• “我在食品上花了多少钱？” → 按 category 字段过滤
• “列出我最大的几笔支出” → 按 amount 字段降序排序

3. 手动添加交易记录

用户说 “我在 Y 处花费了 $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. Agent：通过视觉模型提取交易记录，并确认数量
3. Agent：运行 add 脚本将记录存入本地存储
4. 用户：“我在食品上花了多少钱？”
5. Agent：读取本地存储，执行过滤并返回答案

依赖项

• jq — 用于 JSON 交易记录的存储与查询（apt install jq / brew install jq）
• pypdf — 用于完整提取 PDF 文本内容（pip3 install pypdf）

经验总结

• Telegram 会截断 PDF 预览 — 必须使用 pypdf 获取全部页面内容
• 务必核对总额 — 在导入前，需将提取出的支出总和与账单所列 “Total purchases” 进行比对
• Coinbase Card — 不支持 Plaid，仅可通过上传账单方式同步

未来规划：Plaid 集成

• 新增 finance_connect 工具，支持 Plaid OAuth 授权流程
• 自动同步已连接银行账户的交易记录
• 保持现有查询接口不变，仅更换底层数据源