个人记账

SKILL.md

---
name: personal-ledger
name_zh: 个人记账
description: A natural language personal finance tool for income/expense tracking, budget management, financial goals, and investment portfolio monitoring. Triggers on phrases like "I spent XX", "check balance", "monthly report", "bought XX stock", "set budget", and "savings goal".
description_zh: 面向普通人的自然语言记账工具，支持记账、查询、预算、目标和投资跟踪。当用户说"花了XX"、"查账"、"月度报告"、"买入XX股"、"设定预算"、"攒钱目标"等时触发。
metadata:
  openclaw:
    requires:
      bins: [python3]
      pypi: [akshare]
    tags: [ledger, budget, personal-finance, accounting, csv, natural-language, zh]
---

## 概述

面向普通人的自然语言记账工具。用户只需说"今天吃饭花了50块"，即可自动生成 CSV 格式账本条目。

> ⚠️ **网络说明：** 投资功能会联网查询证券代码（使用 akshare），其他功能均为纯本地操作，数据不会上传。

**原创 CSV 格式**。无需安装数据库，一个 CSV 文件搞定一切。

## 账本格式（CSV）

本 Skill 使用**完全原创的 CSV 格式**，简单直观。

```
# 日期,类型,金额,分类,描述,账户
余额,微信钱包,1000.00
余额,支付宝,2000.00
余额,银行卡,50000.00
余额,现金,500.00
2026-05-21,支出,50.00,餐饮,午餐,微信钱包
2026-05-22,收入,8000.00,工资,5月工资,银行卡
2026-05-23,支出,299.00,购物,外套,支付宝
```

格式规则：
- 6 个字段：`日期,类型,金额,分类,描述,账户`
- 类型只能是 `收入` 或 `支出`
- 金额填正数（系统通过类型字段判断方向）
- 账户用扁平中文名，无需层级路径
- 初始余额用 `余额,账户,金额` 格式

## 默认位置

`~/.openclaw/workspace/data/ledger/default.csv`

## 触发条件

> ⚠️ **网络说明：** 投资相关功能会联网查询证券代码（使用 akshare），其他功能均为纯本地操作。

当用户提到以下意图时激活本 Skill：

- 记一笔账（"花了XX"、"买了XX"、"收入XX"、"工资到账"）
- 查询消费（"这个月花了多少"、"上个月餐饮多少钱"、"查账"）
- 账户管理（"我的余额"、"银行卡还有多少"）
- 月度报告（"月度报告"、"这个月花销总结"、"消费分析"）
- 投资操作（"买入XX股"、"卖了XX"、"查持仓"、"投资收益"） — ⚠️ 联网
- 预算管理（"设定预算"、"预算多少"、"超支了吗"、"生成预算模板"）

## 核心能力

### 1. 📝 自然语言记账

**输入示例：**
- "今天中午吃饭花了50块"
- "昨天打车花了23.5"
- "工资到账8000"
- "充话费30"
- "买了一件外套299，用支付宝付的"
- "给小王转了200"

**处理流程：**
1. 使用 LLM 从用户输入中提取：日期、金额、分类、描述、账户
2. 调用 `scripts/parse_entry.py` 格式化为标准 CSV 行
3. 追加写入账本 CSV 文件

**AI 解析规则：**

| 字段 | 说明 | 默认值 |
|------|------|--------|
| `date` | 日期（"今天"、"昨天"、"上周三"等） | 当天 |
| `amount` | 金额（支持小数） | 必填 |
| `category` | 消费分类 | 自动推断 |
| `description` | 摘要描述 | 提取关键信息 |
| `account` | 支付账户 | 默认微信钱包 |

**分类自动映射规则：**

| 关键词（部分列举） | 分类 |
|--------|------|
| 吃饭、午餐、晚餐、早餐、早饭、午饭、晚饭、夜宵、外卖、火锅、烧烤、麻辣烫、冒菜、米线、黄焖鸡、小龙虾、面、米饭、粥、炒菜、快餐、零食、奶茶、咖啡、饮料、水果、甜品、蛋糕、面包、酸奶、牛奶、矿泉水、零食、口香糖、肯德鸡、KFC、麦当劳、汉堡王、星巴克、瑞幸、蜜雪冰城、霸王茶姬、喜茶、一点点、便利店、食堂、团购、秒杀、满减 | 餐饮 |
| 打车、滴滴、快车、专车、出租车、地铁、公交、巴士、大巴、加油、充电、停车、过路费、高速费、火车票、高铁、飞机票、机票、船票、共享单车、电瓶车、摩的、轮渡、顺风车、拼车、通勤、出行、交通、车费、路况、违章 | 交通 |
| 租房、房租、房租押金、水电费、电费、水费、燃气费、物业费、网费、宽带费、手机套餐、话费、充值、流量、居住、住房、宿舍、维修、家电维修、管道疏通、开锁、搬家、家政、保洁、住宿费、押金、民宿、酒店、宾馆 | 居住 |
| 电影、电视剧、会员、视频会员、音乐会员、体育会员、KTV、唱歌、酒吧、夜店、喝酒、演出、演唱会、话剧、音乐会、脱口秀、展览、博物馆、景点、门票、旅游、团建、旅行、酒店预订、健身、游泳、瑜伽、体育运动、羽毛球、篮球、足球、跑步、骑行、游戏、steam、PS5、Switch、游戏皮肤、手游氪金、剧本杀、密室逃脱、棋牌、桌游 | 娱乐 |
| 淘宝、京东、拼多多、唯品会、得物、咸鱼、网购、超市、便利店、沃尔玛、大润发、永辉、盒马、衣服、裤子、裙子、上衣、外套、衬衫、T恤、鞋子、球鞋、运动鞋、包包、背包、行李箱、帽子、围巾、手套、眼镜、墨镜、化妆品、护肤品、彩妆、口红、香水、面霜、面膜、洗面奶、牙膏、洗发水、沐浴露、纸巾、洗衣液、洗衣粉、厨房用品、家居用品、收纳、收纳盒、拖把、抹布、垃圾桶、床上用品、被子、枕头、四件套、窗帘、地毯、摆件、装饰画、小家电、电饭煲、烧水壶、电风扇、加湿器、空气净化器、数码、手机、电脑、平板、耳机、充电宝、数据线、手机壳、钢化膜、Kindle、相机、镜头、存储卡、电池 | 购物 |
| 话费、充值、流量、手机费、电话费、固话、宽带、座机 | 通讯 |
| 看病、挂号、门诊、急诊、体检、医药费、药费、买药、处方、住院、手术、检查、化验、B超、心电图、牙科、眼科、皮肤科、妇科、儿科、中医、疫苗、核酸检测、医保卡、医疗险、看病、验血、血常规、输液、理疗、康复、医保、药房、药店、阿里健康 | 医疗 |
| 课程、学费、培训班、考试报名、教材、书籍、Kindle买书、网课、慕课、极客时间、得到、知乎、网易云课堂、腾讯课堂、有道精品课、学而思、新东方、沪江、CFA、CPA、教师资格证、驾照、学车、学钢琴、学画画、留学、留学中介、语言班、夏令营、研学 | 教育 |
| 红包、礼物、礼金、请客、请吃饭、聚餐、聚会、应酬、随份子、份子钱、结婚礼金、生日礼物、节日礼物、人情往来、人情债、给钱、转账、送礼、压岁钱、年终礼物、伴手礼、纪念品 | 社交 |
| 工资、薪资、薪水、底薪、奖金、年终奖、绩效、提成、加班费、补贴、报销、佣金、稿费、兼职费、外快、副业收入、自由职业收入 | 工资 |
| 理财、利息、存款利息、基金分红、股票分红、股息、债券利息、理财产品收益、P2P收益、房租收入、版税、知识产权费、专利费、分成 | 理财收益 |

**账户自动映射规则：**

| 关键词 | 账户 |
|--------|------|
| 微信、微信支付、零钱 | 微信钱包 |
| 支付宝、花呗 | 支付宝 |
| 银行卡、银行 | 银行卡 |
| 现金 | 现金 |
| 无关键词 | 微信钱包（默认）|

### 2. 📊 消费查询

**支持查询方式：**
- 按时间："这个月花了多少"、"上周支出"、"2025年3月"
- 按分类："餐饮花了多少"、"交通费用"
- 组合："这个月餐饮花了多少"
- 全部列表："最近的账单"、"最近10笔"

**处理方式：** Agent 读取账本 CSV，按条件筛选并计算汇总。

**输出格式：**
```
📊 查询结果：2026年5月 餐饮支出

日期        金额      描述
2026-05-01  ¥50.00   午餐
2026-05-03  ¥128.00  火锅
2026-05-05  ¥15.00   早餐
2026-05-05  ¥45.00   午饭
─────────────────────────
合计        ¥238.00
```

### 3. 💰 账户余额管理

**支持操作：**
- 查看余额："微信钱包还有多少"、"各账户余额"
- 设置初始余额："微信钱包初始余额1000"
- 调整余额："银行卡余额修正为5000"

**余额计算方式：** 初始余额 + 收入合计 - 支出合计

Agent 读取账本 CSV，找到该账户的余额行和所有相关交易，自动计算当前余额。

### 4. 📐 预算管理

**支持操作：**
- **设定预算**：`python budget.py <账本.csv> --set 餐饮 2000`
- **查看进度**：`python budget.py <账本.csv> --progress 2026-05`
- **超支预警**：`python budget.py <账本.csv> --alert 2026-05`
- **生成模板**：`python budget.py <账本.csv> --template 15000`
- **列出预算**：`python budget.py <账本.csv> --list`
- **删除预算**：`python budget.py <账本.csv> --remove 餐饮`

**命令参考：**
```bash
# 设定预算
python budget.py ./default.csv --set 餐饮 2000

# 查看所有预算
python budget.py ./default.csv --list

# 查看执行进度
python budget.py ./default.csv --progress 2026-05

# 超支预警
python budget.py ./default.csv --alert 2026-05

# 生成预算模板（50/30/20法则，基于月收入）
python budget.py ./default.csv --template 15000

# 自定义比例模板
python budget.py ./default.csv --template 15000 --ratio 40 30 20 10

# 移除预算
python budget.py ./default.csv --remove 餐饮
```

**预算指南：** 详见 `references/budget_guide.md`

### 5. 📈 月度报告

**触发方式：** "月度报告"、"5月消费分析"、"这个月总结"

**命令：**
```bash
python generate_report.py ./default.csv --month 2026-05
python generate_report.py ./default.csv --month 2026-05 --output report.txt
```

**报告内容：**
1. 收支概览（总收入、总支出、净结余）
2. 分类支出排行（文字图表）
3. 日均消费
4. 最大单笔支出
5. 与上月环比对比
6. 简短消费建议

**输出示例：**
```
📈 2026年5月 月度报告

━━━ 收支概览 ━━━
收入：¥8,500.00
支出：¥4,230.50
结余：¥4,269.50

━━━ 支出分类 TOP 5 ━━━
████████████ 餐饮    ¥1,280.00  (30.3%)
██████       购物    ¥890.00    (21.0%)
████         交通    ¥620.50    (14.7%)
███          娱乐    ¥480.00    (11.3%)
██           居住    ¥450.00    (10.6%)
其他                   ¥510.00    (12.1%)

日均消费：¥201.45
最大单笔：¥299.00（购物-外套）
```

### 6. 📍 财务目标

**触发方式：**
- "我要攒钱旅行"、"建一个应急基金目标"
- "目标进度怎么样"、"旅行基金存了多少"
- "列出我的财务目标"

**命令参考：**

| 指令 | 示例 | 脚本调用 |
|------|------|----------|
| 创建目标 | "建一个旅行基金目标，10000块，年底前" | `goal.py create "旅行基金" 10000 2026-12-31` |
| 存入金额 | "给旅行基金存2000" | `goal.py deposit "旅行基金" 2000` |
| 查看进度 | "旅行基金进度" | `goal.py progress "旅行基金"` |
| 列出所有 | "我的财务目标" | `goal.py list` |
| 删除目标（需确认） | "删掉旅行基金目标" | `goal.py delete "旅行基金"` |

**详细指南：** 参见 `references/goal_guide.md`

### 7. 📈 投资跟踪

**触发方式：** "买入XX股"、"买了XX基金"、"卖了XX"、"查持仓"、"投资收益"

**新用户买入流程（名称优先，无需记忆代码）：**

当用户说"买入XX股/基金"但没说代码时，系统会自动：
1. 联网搜索代码（akshare 实时查询）
2. 搜到唯一结果 → 直接记录 ✅
3. 搜到多个候选 → 列出选项，让用户确认代码后再记录
4. 搜不到 → 提示用户提供代码

**交互示例：**

```
用户: 买入有色金属ETF南方，3100股，2.07元
Agent: 🔍 正在联网查询「有色金属ETF南方」的代码...
      ✅ 自动找到代码：有色金属ETF南方（512400）<基金>
      ✅ 已记录买入
         📅 2026-01-10
         📊 有色金属ETF南方 (512400)
         🔢 3100.0股 × ¥2.07 = ¥6,412.66
         💳 银行卡

用户: 买入沪深300ETF，100股，3.5元
Agent: 🔍 正在联网查询「沪深300ETF」的代码...
      ⚠️  找到 10 个候选，请手动确认代码：
         1. 华夏沪深300ETF联接A（000051）<基金> ← 推荐
         2. 国寿安保沪深300ETF联接A（000613）<基金>
         ...
      请用 --buy "沪深300ETF" <代码> <数量> <单价> <日期> 重新输入

用户: 买入贵州茅台，10股，1600元
Agent: 🔍 正在联网查询「贵州茅台」的代码...
      ✅ 自动找到代码：贵州茅台（600519）<股票>
      ✅ 已记录买入...
```

**命令参考：**

| 指令 | 示例 | 脚本调用 |
|------|------|----------|
| 记录买入（自动查代码） | "买入有色金属ETF南方，3100股" | `invest.py --buy "有色金属ETF南方" auto 3100 2.07 2026-01-10` |
| 记录买入（手动代码） | "买入沪深300ETF，100股" | `invest.py --buy "沪深300ETF" 510050 100 3.50 2026-01-15` |
| 记录卖出 | "卖了500股沪深300ETF，4块" | `invest.py --sell "沪深300ETF" 510050 500 4.00 2026-03-01` |
| 记录分红 | "沪深300ETF分红了45块" | `invest.py --dividend "沪深300ETF" 510050 45.60 2026-02-10` |
| 设置价格 | "沪深300ETF现在3.62" | `invest.py --price 510050 3.62` |
| 持仓概览 | "看看我的持仓" | `invest.py --portfolio` |
| 单只收益 | "沪深300ETF赚了多少" | `invest.py --return 510050` |
| 汇总收益 | "投资总体情况" | `invest.py --summary` |
| 交易记录 | "看看交易记录" | `invest.py --list` |

**详细指南：** 参见 `references/invest_guide.md`

---

## 首次使用初始化

当用户首次触发记账时，Agent 应：

1. 检查账本文件是否存在
2. 不存在则创建，写入模板头部
3. 询问用户常用支付方式和初始余额

**初始化模板：**
```
# 日期,类型,金额,分类,描述,账户
# 个人账本 - 创建于 YYYY-MM-DD
# 格式说明见 references/ledger_format.md

# 账户初始余额
余额,微信钱包,0.00
余额,支付宝,0.00
余额,银行卡,0.00
余额,现金,0.00

# === 交易记录 ===
```

## 交互模式

### 单行记账（最常用）

```
用户: 今天中午吃了碗面花了25
Agent: 已记录 ✅
      📅 2026-05-21
      💰 ¥25.00
      📂 餐饮
      💳 微信钱包
      📝 午餐

      微信钱包余额：¥975.00
```

### 对话记账（多字段补全）

```
用户: 花了200块
Agent: 买的什么？

用户: 买了本书
Agent: 已记录 ✅
      📅 2026-05-21
      💰 ¥200.00
      📂 教育
      💳 微信钱包
      📝 书籍

      微信钱包余额：¥775.00
```

### 目标记账

当用户提到给某个目标存钱时，同时完成两步：
1. 调用 `goal.py deposit` 更新目标进度
2. 按常规记账流程记录这笔支出/转账

### 批量记账

```
用户: 今天花了：早餐15、打车30、午饭45
Agent: 已记录 3 笔 ✅
      1. 餐饮  ¥15.00  早餐
      2. 交通  ¥30.00  打车
      3. 餐饮  ¥45.00  午饭
      合计：¥90.00
```

### 修改/删除

> ⚠️ 所有删除操作会要求用户确认（Y/N），不会直接删除。

- **删除最近一笔**（需确认）："删掉刚那笔"
- **删除指定笔**（需确认）："删除5月15日那笔餐饮"
- **修改金额**（需确认）："把刚才那笔改成30块"

## 工作流总结

```
用户输入
  │
  ├─ 记账意图 → 解析字段 → 生成CSV行 → 追加写入 → 确认反馈
  │
  ├─ 查询意图 → 读取CSV → 筛选过滤 → 计算汇总 → 格式化输出
  │
  ├─ 余额意图 → 读取CSV → 找余额行 → 累计收支 → 计算余额
  │
  ├─ 报告意图 → 读取CSV → 按月统计 → 分类排行 → 生成报告
  │
  ├─ 投资意图 → 写入 investments.csv / 查询持仓
  │
  ├─ 目标意图 → goals.json CRUD
  │
  └─ 预算意图 → budget.py → .budget.json
```

## 参考文档

按需加载：

- **`references/ledger_format.md`**：账本 CSV 格式详细说明
- **`references/budget_guide.md`**：预算管理功能指南
- **`references/goal_guide.md`**：财务目标功能指南
- **`references/invest_guide.md`**：投资跟踪功能指南
- **`references/user_guide.md`**：用户操作 FAQ
- **`references/financial_benchmarks.md`**：财务健康基准数据
- **`references/education.md`**：财务知识科普

## 专业标准（Professional Standards）

### 免责声明

本 Skill 提供**财务记录和基础分析工具**，不是投资顾问服务。

| 可以做 | 不可以做 |
|--------|----------|
| 帮你记录和分析消费数据 | 推荐具体理财产品 |
| 对比你的支出和通用基准 | 保证任何投资收益 |
| 基于你的数据给出节省建议 | 预测市场走势 |
| 解释财务概念（复利、通胀等） | 提供税务筹划方案 |
| 帮你制定储蓄计划 | 做资产配置方案 |

**底线原则：** 我帮你搞清楚「钱去哪了」，不帮你决定「钱该去哪」。

## 语气风格（Tone and Approach）

| 场景 | 风格 |
|------|------|
| 记账成功 | 简洁确认 + 关键信息 "已记录 ✅ 餐饮 ¥35 余额 ¥965" |
| 月度报告 | 数据清晰 + 一两句建议 |
| 用户花了太多 | 委婉提醒，不是批评 |
| 用户攒到了钱 | 真诚鼓励 |
| 用户问投资建议 | 给教育内容 + 免责 |

**语气忌讳：** 说教口吻、用数字羞辱、过度谨慎、假装亲密。

## 约束

1. **只写，不删。** 删除操作需用户明确要求。
2. **金额必填。** 无法确认金额时，追问。
3. **分类可猜。** 有把握时自动分类，不确定时给选项。
4. **日期可省。** 默认今天，支持相对日期。
5. **账户可省。** 默认微信钱包。
6. **文件即数据库。** 所有数据存储在 CSV 文件中，用户随时可用任何编辑器查看和修改。
7. **零外部依赖。** 纯 Python 标准库，无需 pip install。