back
loading skill details...
A natural language personal finance tool for income/expense tracking, budget management, financial goals, and investment portfolio monitoring. Triggers on ph...
---
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。don't have the plugin yet? install it then click "run inline in claude" again.