Yaohx Expense Tracker

记账助手 (Expense Tracker)

概述

一个纯本地处理的个人记账技能。支持文本输入和支付截图两种方式记录消费，按月归档到本地 JSON 文件，支持消费分类管理、记录查询、月度报告生成。所有数据存储和处理均在本地完成，不依赖任何云端 API。

数据存储位置

所有数据文件存放在工作区根目录下（即当前工作目录）：

数据格式详见 references/data_schema.md。

触发场景

1. 文本记账：用户发送消费描述，如 "午餐花了25元"、"打车15块"
2. 图片记账：用户发送微信支付/支付宝截图，直接识图后记录
3. 手动记录：用户说"记账"并提供详细信息
4. 查看记录：用户说"看看本月消费"、"本月花了多少"
5. 月度报告：用户说"生成本月消费报告"、"月度总结"
6. 删除记录：用户说"删除刚才那条记录"、"删掉某笔消费"

工作流程

初始化（首次使用时执行）

当用户首次使用记账功能时，先执行初始化：

python scripts/init_db.py

此脚本在工作区根目录创建：

• categories.json（含默认分类）
• expenses/ 目录
• 当前月份的 expenses/expenses-YYYYMM.json 空文件

流程 A：处理文本账单

1. 从用户消息中提取关键信息：日期、时间、金额、商家、消费类别、支付方式、备注
2. 如果用户未提供日期/时间，默认使用当前日期和时间
3. 根据商家名称和备注，自动匹配消费分类（匹配规则见下方）
4. 调用脚本写入记录
5. 回复用户确认记录成功，展示本次消费摘要和本月累计

关键：调用脚本时使用独立参数，绝不传递 JSON 字符串

正确调用方式：

python scripts/record_expense.py --amount 25 --merchant "兰州拉面" --category "餐饮" --date 2026-07-09 --time 1230 --payment "微信" --note "午餐"

参数说明：

• --amount：金额（数字，必填）
• --merchant：商家名称（必填）
• --category：消费分类（可选，不传则自动匹配）
• --date：日期，格式 YYYY-MM-DD（可选，默认今天）
• --time：时间，格式 HHMM（可选，默认当前时间）
• --payment：支付方式（可选，如 微信/支付宝/现金/银行卡）
• --note：备注（可选）

流程 B：处理图片账单（支付截图）

根据模型能力选择路径：

路径 B1：多模态模型（能直接识图）

如果你是多模态模型，可以直接观察图片：

1. 用户发送支付截图后，直接观察图片，提取以下信息：
   • 金额（必填）
   • 商家/收款方名称
   • 支付方式（微信/支付宝等）
   • 交易时间（如图片中可见）
   • 备注/商品说明
2. 将提取结果展示给用户确认（如有不确定的信息请用户补充）
3. 用户确认后，使用独立参数调用 record_expense.py 写入记录
4. 回复确认

路径 B2：非多模态模型（无法识图，使用本地 OCR）

如果你无法直接观察图片（非多模态模型），使用本地 OCR 脚本提取文字：

1. 获取用户发送的截图文件路径
2. 调用 OCR 脚本提取文字和结构化信息：

python scripts/ocr_image.py --image "截图文件路径"

脚本使用 rapidocr-onnxruntime 进行本地 OCR：

1. OCR 脚本输出 JSON 格式结果：

{
  "success": true,
  "raw_text": "微信支付 ¥25.00 向兰州拉面付款...",
  "structured": {
    "amount": 25.00,
    "merchant": "兰州拉面",
    "date": "2026-07-09",
    "time": "1230",
    "payment": "微信",
    "note": null
  },
  "method": "rapidocr"
}

1. 读取 structured 中的字段，如果关键信息（金额、商家）已提取到，展示给用户确认后调用 record_expense.py 写入记录
2. 如果 structured 中部分字段为 null，根据 raw_text 上下文自行推断补充，或请用户手动补充缺失信息
3. 如果 OCR 脚本返回 "success": false，说明 OCR 不可用，此时必须请用户手动输入消费信息（金额、商家等），不要直接报错终止

OCR 不可用时输出示例：

{
  "success": false,
  "error": "rapidocr-onnxruntime not installed",
  "install_hint": "pip install rapidocr-onnxruntime",
  "fallback_instruction": "OCR is not available. Please ask the user to manually input the expense details."
}

OCR 依赖安装（非多模态模型必须安装）：

如需使用图片记账功能，运行：

python -m pip install rapidocr-onnxruntime

如果未安装 rapidocr，OCR 脚本会返回 fallback_instruction，此时必须请用户手动输入消费信息。 多模态模型不需要安装 OCR——直接识图即可。

流程 C：查看消费记录

调用脚本查询：

# 查看指定月份
python scripts/list_expenses.py --month 202607

# 查看指定月份某分类
python scripts/list_expenses.py --month 202607 --category "餐饮"

# 不传 --month 则默认当前月
python scripts/list_expenses.py

流程 D：生成月度消费报告

# 指定月份
python scripts/generate_report.py --month 202607

# 不传则默认当前月
python scripts/generate_report.py

报告内容包含：

• 本月总支出金额
• 各分类支出金额及占比
• 日均消费金额
• 单笔最高消费
• 支付方式分布
• 与上月对比（如果上月数据存在）

将报告摘要回复给用户，可配合 show_widget 展示饼图或柱状图。

流程 E：删除消费记录

python scripts/delete_expense.py --id 2026-07-09-001

删除后回复用户确认。

消费分类自动匹配规则

当用户未明确指定分类时，根据商家名称和备注自动匹配：

• 含"餐、饭、面、粉、菜、外卖、咖啡、奶茶、饮料、零食、烧烤、火锅、早点、早餐、午餐、晚餐、夜宵"等 → 餐饮
• 含"打车、滴滴、公交、地铁、加油、停车、充电、单车、出租、高铁、火车、机票、飞机"等 → 交通
• 含"超市、便利店、淘宝、京东、拼多多、天猫、苏宁、网购"等 → 购物
• 含"房租、房贷、水电、燃气、物业、宽带"等 → 居住
• 含"电影、KTV、游戏、旅游、景点、门票、健身"等 → 娱乐
• 含"医院、药房、诊所、挂号、药"等 → 医疗
• 含"话费、流量、充值"等 → 通讯
• 含"衣服、鞋、裤、裙、外套、服装"等 → 服饰
• 含"书、课程、培训、学费、教育"等 → 教育
• 其他默认归入 其他

脚本调用注意事项

绝不传递 JSON 字符串

所有脚本均使用 argparse 接收独立参数。不要将数据组装成 JSON 字符串再传给脚本。这是为了避免 Windows 下 shell 引号转义问题。

错误示例（会导致 Windows 下引号冲突）：

python scripts/record_expense.py '{"amount": 25, "merchant": "兰州拉面"}'

正确示例（独立参数，无嵌套引号问题）：

python scripts/record_expense.py --amount 25 --merchant "兰州拉面"

使用 python 而非 python3

在 Windows 上，python3 命令通常不存在。始终使用 python。

中文参数

中文参数用双引号包裹即可，不需要额外转义：

python scripts/record_expense.py --amount 25 --merchant "兰州拉面" --category "餐饮"

脚本路径

脚本路径相对于 skill 目录。脚本内部会自动以当前工作目录作为数据存储根目录。如需指定其他数据目录，使用 --data-dir 参数：

python scripts/record_expense.py --amount 25 --merchant "兰州拉面" --data-dir "C:\Users\me\my-expenses"

脚本清单

数据格式

数据格式详见 references/data_schema.md。

注意事项

• expenses-YYYYMM.json 中 id 格式为 YYYY-MM-DD-NNN，NNN 为当天序号（001 起），同一日期内递增
• 每次写入后自动更新 last_updated 时间戳
• 金额保留原始精度，汇总时四舍五入到两位小数
• 所有 Python 脚本使用 UTF-8 编码
• 脚本输出为 JSON 格式，方便模型解析