finance-tracker (财滚滚) v2.0 💰🐶 - 个人财务小助手#

可爱的个人记账工具，支持 第三方账单导入 与 财务分析，轻松管理您的财务数据。

🆕 v2.0 更新#

• 数据结构优化：标准化交易记录格式
• 第三方账单导入：支持导入其他记账App导出的Excel账单
• 账户余额管理：实时计算，支持负数余额
• 分类体系完善：15个一级分类覆盖日常收支

⚠️ 安全提示#

破坏性操作需确认！ 在执行以下操作前，必须向用户确认：

1. 清空数据：用户说"清空数据"、"清空账单"、"删除所有记录"时
   • ✅ 先问： "⚠️ 确认要清空所有账单数据吗？此操作不可恢复！输入'确认'继续"
   • ✅ 用户回复"确认"后，执行： python tracker.py clear --confirm
   • ❌ 不要直接执行清空操作（必须带--confirm参数）
2. 删除记录：用户说"删除..."时
   • ✅ 先显示要删除的记录，再请用户确认
   • ✅ 批量删除时尤其要谨慎
3. 导入账单：用户说"导入账单"时
   • ✅ 提醒用户：导入会合并到现有数据（不会清空原有数据）
   • ✅ 建议用户先导出备份
4. 其他破坏性操作：
   • 删除账户、删除账本等操作也需要确认

原则：当用户说"清空"、"删除所有"、"恢复出厂"等词时，先确认再执行！

📁 数据存储#

财滚滚采用 双存储架构，确保数据安全且支持云同步：

存储位置#

1. 主数据目录（本地存储）
   • 路径： ~/.cai-gun-gun/data/
   • 说明：跨平台兼容（Windows/Mac/Linux/Android/iOS）
   • 自定义：设置环境变量 CAI_GUN_GUN_DATA_DIR 可修改路径
2. 同步目录（云同步）
   • 路径： skill目录/data/
   • 说明：如果agent支持skill云同步，此目录会被自动同步

同步机制#

• 每次保存数据后，自动同步到skill目录
• 加载数据时，优先从主数据目录读取
• 主数据损坏或丢失时，自动从同步目录恢复

数据文件#

• transactions.json - 交易记录
• accounts.json - 账户信息
• categories.json - 分类配置
• config.json - 用户配置

核心能力#

1. 快速记账#

用户用自然语言描述消费或收入，自动解析并记录：

text

中午吃饭花了30
咖啡 25
工资到账 8000
买衣服 299

2. 记录管理#

• 删除记录： 删掉早上的咖啡账单
• 查看记录： 今天的账单、 本周消费、 本月支出

3. 财务分析#

• 简单查询： 本月花了多少、 最近一周的消费
• 账户余额： 我现在有多少钱

4. 数据管理#

• 导出 Excel： 导出账单
• 导入 Excel： 导入账单 文件路径（支持第三方记账App导出格式）

数据结构#

交易记录字段#

字段说明示例交易类型支出/收入支出日期日期时间2026-05-08 16:30:00一级分类主分类食品水果二级分类子分类餐饮账户1支付账户微信钱包账户2转账目标null账户币种货币CNY金额金额30.5成员记账成员我商家商家名称星巴克项目分类项目分类null项目项目null记账人记账人QClaw备注备注说明下午茶

分类体系#

支出分类（15个一级分类）：

一级分类二级分类食品水果餐饮、买菜、零食、水果、茶饮、咖啡出行交通交通、打车、用车、火车票、租车购物消费购物、电子产品、衣服鞋包、淘宝、京东生活服务生活用品、彩妆洗漱、家电、家具、理发、洗衣、快递、打印住房成本房租、水电、物业、宽带、维修娱乐休闲电影、游戏、KTV、旅游、运动、会员医疗健康药品、看病、体检教育培训书籍、文具、学费、课程、培训社交人情红包、礼物、请客、人情通讯网络话费、上网茶水饮料酒水饮料、奶茶、咖啡、茶叶网络资源服务器、软件、会员订阅保险保障保险其他支出其他、捐赠、宠物、彩票

收入分类：

一级分类二级分类工资收入基本工资、奖金、绩效、加班费投资收益股票、基金、理财、分红副业收入兼职、稿费、接单、副业其他收入红包、退款、报销、其他

账户列表#

• 💵 现金
• 💳 微信钱包
• 💰 支付宝余额
• 🏦 银行卡
• 💳 信用卡

工作流程#

记账流程#

1. 解析用户输入 — 识别金额、类型、分类、账户、备注
2. 智能推断分类 — 根据备注关键词匹配分类
3. 调用脚本存储 — 运行 python scripts/tracker.py add ...
4. 更新账户余额 — 收入+支出-
5. 友好反馈 — 保存成功 + 分类确认 + AI夸奖

自然语言解析规则#

用户说解析为X元、 X块、 X (数字)金额花、 买了、 消费支出收入、 到账、 收到收入用支付宝、 微信支付、 现金账户

分类推断关键词#

二级分类关键词餐饮吃饭、午餐、晚餐、外卖、餐厅、食堂买菜买菜、超市、菜市场、蔬菜交通地铁、公交、出行、巴士打车打车、滴滴、出租车、网约车购物购物、买、淘宝、京东、拼多多电影电影、影院、观影游戏游戏、steam、手游、充值话费话费、充值、手机费工资工资、薪水、月薪

成功反馈模板#

text

✅ 记好啦！{类型} {金额}元 — {一级分类}>{二级分类}

💳 账户：{账户名称} | 💵 余额：{当前余额}元

{AI夸奖语}

💡 **小提示：当前版本暂时无云服务，数据只保存到了本地，记得及时导出保存防止丢失哦！**

🎲 {随机小贴士}

AI夸奖语生成原则#

• 根据时间段、金额、分类自然生成
• 语气像朋友聊天，不像机器人
• 收入一定要夸！"工资到账！人生赢家~"

脚本调用#

bash

# 添加记录
python scripts/tracker.py add --type expense --amount 30 --note "午饭"

# 指定分类
python scripts/tracker.py add --type expense --category 食品水果 --subcategory 餐饮 --amount 30

# 指定账户
python scripts/tracker.py add --type expense --amount 30 --account 微信钱包 --note "午饭"

# 删除记录
python scripts/tracker.py delete --note "咖啡"

# 查询记录
python scripts/tracker.py list --limit 10

# 统计汇总
python scripts/tracker.py summary --period month

# 账户余额
python scripts/tracker.py account list

# 导出Excel
python scripts/tracker.py export -o 账单.xlsx

# 导入Excel（支持第三方记账App导出格式）
python scripts/tracker.py import 账单.xlsx

# 清空数据
python scripts/tracker.py clear --confirm

依赖#

• Python 3.8+
• pandas（数据处理）
• openpyxl（Excel导入导出）

第三方账单导入#

支持导入其他记账App导出的Excel账单数据，智能识别字段格式，自动映射到标准分类体系。