smart-ledger（智能账本）

Smart Expense Tracker - 智能收支追踪器

通过自然语言快速记账，自动生成财务报告的智能工具。

功能特性

• 📝 自然语言记账: "今天午饭花了35元"、"收到工资8000"
• 🏷️ 智能自动分类: 自动识别餐饮、交通、购物等分类
• 📊 多维度报告: 日报、周报、月报、趋势分析
• 🔒 本地数据存储: JSON文件存储，保护隐私
• 🌐 中英文支持: 支持中英文自然语言输入
• ⚠️ 消费异常检测: 自动识别异常消费模式

快速开始

添加收支记录

# 记录支出
python scripts/expense-tracker.py add "今天午饭花了35元"
python scripts/expense-tracker.py add "昨天打车去公司28块"
python scripts/expense-tracker.py add "买衣服花了299元"

# 记录收入
python scripts/expense-tracker.py add "今天发工资8000元"
python scripts/expense-tracker.py add "收到红包200"

查看记录

# 列出最近7天记录
python scripts/expense-tracker.py list

# 列出最近30天记录
python scripts/expense-tracker.py list 30

# 只显示支出
python scripts/expense-tracker.py list 7 expense

生成报告

# 日报
python scripts/report-generator.py daily
python scripts/report-generator.py daily 2024-01-15

# 周报
python scripts/report-generator.py weekly
python scripts/report-generator.py weekly 1  # 上周

# 月报
python scripts/report-generator.py monthly
python scripts/report-generator.py monthly 1  # 上月

# 趋势分析
python scripts/report-generator.py trend 30

查看统计

# 最近30天收支摘要
python scripts/expense-tracker.py summary

# 最近90天摘要
python scripts/expense-tracker.py summary 90

# 查看分类列表
python scripts/expense-tracker.py categories

项目结构

smart-ledger/
├── SKILL.md                      # 本文件
├── scripts/
│   ├── expense-tracker.py       # 核心记账逻辑
│   └── report-generator.py      # 报告生成器
└── assets/
    └── categories.json          # 分类配置

数据存储

• 路径: ~/.openclaw/workspace/data/expenses/expenses.json
• 格式: JSON
• 隐私: 纯本地存储，不上传云端

数据结构:

{
  "expenses": [
    {
      "id": "a1b2c3d4",
      "date": "2024-01-15",
      "type": "expense",
      "amount": 35.00,
      "category": "餐饮",
      "note": "午饭",
      "raw_text": "今天午饭花了35元",
      "created_at": "2024-01-15T12:30:00"
    }
  ],
  "categories": {
    "income": ["工资", "奖金", "投资", ...],
    "expense": ["餐饮", "交通", "购物", ...]
  }
}

自然语言支持示例

时间表达

• "今天..." - 今天
• "昨天..." - 昨天
• "前天..." - 前天
• "2024-01-15..." - 指定日期

金额表达

• "花了35元"
• "花了35块"
• "35元"
• "收入5000"

自动分类关键词

分类配置

分类配置存储在 assets/categories.json，包含:

• 收入分类: 工资、奖金、投资、兼职、红包、退款、其他收入
• 支出分类: 餐饮、交通、购物、娱乐、居住、医疗、教育、通讯、人情、其他支出
• 预算预警: 每个分类可设置预算阈值
• 关键词映射: 自定义分类识别关键词

自定义分类

编辑 assets/categories.json 添加自定义分类和关键词。

报告类型

日报

• 当日收支总览
• 分类明细
• 交易记录列表

周报

• 本周收支总览
• 日均支出
• 每日明细
• TOP支出分类

月报

• 月度收支总览
• 预算执行情况
• 周度趋势
• 分类统计
• 日均支出

趋势分析

• 消费趋势（上升/下降/稳定）
• 异常消费检测（超过均值2倍）
• 环比变化分析
• 消费建议

高级用法

删除记录

# 删除指定ID的记录
python scripts/expense-tracker.py delete a1b2c3d4

JSON格式输出

# 报告输出JSON格式（便于程序处理）
python scripts/report-generator.py monthly 0 json

批量导入

可通过直接编辑 expenses.json 文件实现批量导入。

使用建议

1. 每日记账: 养成每天记录的习惯，可以在每天晚上花2分钟回顾当天支出
2. 及时分类: 如果自动分类不准确，可以在备注中添加更具体的关键词
3. 定期复盘: 每周查看周报，每月查看月报，了解自己的消费模式
4. 设置预算: 在 categories.json 中为各分类设置预算预警值

故障排除

无法识别金额

• 确保金额格式正确，如 "35元"、"35块"
• 尝试明确表达："花了35元"

分类不准确

• 在描述中添加更多关键词，如 "淘宝买衣服" 会比 "买衣服" 更准确
• 可在 categories.json 中添加自定义关键词

数据文件损坏

• 数据文件是纯JSON，可用文本编辑器修复
• 建议定期备份 ~/.openclaw/workspace/data/expenses/expenses.json

扩展开发

添加新的自动分类规则

编辑 scripts/expense-tracker.py 中的 KEYWORD_MAPPING 字典:

KEYWORD_MAPPING = {
    # 现有规则...
    "新关键词": "目标分类",
    " another keyword": "Category Name"
}

集成其他工具

expense-tracker.py 可作为模块导入:

from scripts.expense_tracker import ExpenseTracker

tracker = ExpenseTracker()
record = tracker.add("今天买书花了50元")
print(record)

技术规格

• Python版本: 3.9+
• 依赖: 无外部依赖，仅使用标准库
• 编码: UTF-8
• 数据格式: JSON

许可证

MIT License