Skill: tsag1/simple-ledger (version 1.3.0)

--- 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。


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)