safaiyeh-finance-skill

个人财务记忆层技能，可解析账单、存储交易记录并查询支出。支持 PDF 全页提取、分类汇总与手动记账，数据存储于 OpenClaw 工作区。

## 概述（中文）

个人财务记忆层技能，可解析账单、存储交易记录并查询支出。支持 PDF 全页提取、分类汇总与手动记账，数据存储于 OpenClaw 工作区。

## 技能正文

# 财务技能

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

## 数据位置
- 交易记录：`~/.openclaw/workspace/finance/transactions.json`
- 原始账单：`~/.openclaw/workspace/finance/statements/`

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

## 工具

### 1. 解析账单
当用户分享账单（图片或 PDF）时：

**⚠️ 重要：Telegram/频道预览会截断 PDF！**
务必先用 pypdf 提取全部页面：

```bash
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 → 筛选/聚合 → 回答

**查询示例：**
- 「上个月花了多少？」→ 汇总日期范围内所有负数金额
- 「食物花了多少？」→ 按分类筛选
- 「最大支出有哪些？」→ 按金额排序

### 3. 手动添加交易
用户说「我在 Y 花了 $X」→ 追加到 transactions.json

## 文件格式

```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 Card** — 不支持 Plaid，仅支持账单上传

## 未来：Plaid 集成
- 添加 `finance_connect` 工具用于 Plaid OAuth 流程
- 从已连接银行自动同步交易
- 相同查询接口，不同数据源