Cai Gun Gun

财滚滚(Cai Gun Gun) 💰🐶 个人记账小助手，支持快速记账、智能分类、账户余额管理、第三方账单导入导出与财务分析。触发词：记账、我要记账、记一笔、查账单、本周消费、本月支出、导出账单、财务分析、财滚滚。

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账单数据，智能识别字段格式，自动映射到标准分类体系。