0a1ac19a62567d09 Smart Expense Tracker

---
slug: personal-life-ledger
displayName: 个人记账｜说句话就记好账
name: smart-expense-tracker
description: 口语化记账与统计分析；支持一句话记多笔账、自动分类收支、查询统计、改错删记录，适合个人与家庭日常流水管理。附完整类目规则与常见歧义处理表。
version: 3.1.0
dependency:
  python:
    - uuid==1.30
---

# 智能记账助手

## 任务目标
- 本Skill用于:个人与家庭的日常收支记录与分析
- 能力包含:口语化记账、多笔同记、自动分类、流水查询、统计报表、记录修改与删除
- 触发条件:用户表达记/查/改/删账相关意图

---

## 一、快速上手｜直接复制就能用

### 记一笔账
```
今天中午吃了碗面15块，下午网购了一件衣服200，晚上请客户吃饭花了350
```
→ AI自动拆分3条记录，分别归入餐饮、购物、人情

### 查账统计
```
帮我看看这个月花了多少钱
```
→ 输出本月总支出、各类目金额及占比

### 修改记录
```
把昨天那笔50块的餐饮改成购物
```
→ AI定位记录并修改类目

### 删除记录
```
删掉上周三那条地铁费记录
```
→ AI查询确认后删除

---

## 二、类目定义（自动分类）

### 收入类目
| 类目 | 关键词(部分匹配) |
|------|----------------|
| 工资 | 工资、发工资、月薪、年终奖 |
| 兼职 | 兼职、外快、稿费、佣金、私活 |
| 理财 | 理财、利息、股息、基金分红、投资收益 |
| 礼金 | 礼金、红包(收)、份子钱(收) |
| 其他收入 | 其他、退款、报销、奖励、奖学金 |

### 支出类目
| 类目 | 关键词(部分匹配) |
|------|----------------|
| 餐饮 | 餐饮、吃饭、早饭、午饭、晚饭、点外卖、下馆子、请客 |
| 购物 | 购物、网购、淘宝、京东、拼多多、超市、衣服、鞋、化妆品 |
| 居住 | 房租、房贷、水电、物业、燃气、暖气、维修 |
| 交通 | 交通、地铁、公交、打车、开车、油费、停车、机票、火车票 |
| 人情 | 人情、送礼、请客(出)、红包(出)、份子钱(出) |
| 医疗 | 医疗、看病、买药、体检、医保 |
| 教育 | 教育、学费、补习班、培训、书籍、资料 |
| 娱乐 | 娱乐、电影、游戏、旅游、健身、音乐、会员 |
| 通讯 | 通讯、电话费、流量、宽带 |
| 其他支出 | 其他、日用、杂项 |

**匹配优先级**：金额后的关键词 > 动词(吃/买/付) > 名词(餐/交通费)

---

## 三、数据存储

数据文件位置:`./expense_records.json`

记录结构:
```json
{
  "id": "uuid",
  "type": "income|expense",
  "category": "类目名称",
  "amount": 数字(元),
  "description": "描述备注",
  "date": "YYYY-MM-DD",
  "created_at": "ISO时间戳"
}
```

---

## 四、操作流程

### 1. 记账(记多笔)

**智能体解析步骤:**
1. 识别用户输入中的所有收支项(一句多笔时用"和"/"还有"/"再"等连接词拆分)
2. 每笔提取:金额、类型(收入/支出)、类目、日期、备注
3. 日期默认当天，可用"昨天"/"3号"/"本月5号"等表述
4. 金额解析:"50"→50元，"50块"→50元，"1500"→1500元

**调用脚本:**
```bash
python scripts/record.py --records '[{"type":"expense","category":"餐饮","amount":35,"description":"午餐","date":"2024-01-15"}]'
```

**脚本参数:**
- `--records`: JSON数组，每项包含type/category/amount/description/date

### 2. 查账统计

**查询方式:**
- 按时间:本月/上月/本周/指定日期范围
- 按类目:某类目的所有记录
- 按类型:仅收入/仅支出
- 汇总统计:总收支/类目占比/趋势分析

**调用脚本:**
```bash
# 本月统计
python scripts/query.py --mode summary --period month

# 指定类目查询
python scripts/query.py --mode detail --category 餐饮 --period month

# 日期范围查询
python scripts/query.py --mode detail --start-date 2024-01-01 --end-date 2024-01-31

# 查看最近10条
python scripts/query.py --mode recent --limit 10
```

**脚本参数:**
- `--mode`: summary(统计汇总)|detail(明细)|recent(最近记录)
- `--period`: today/week/month/year 或省略
- `--category`: 指定类目(支持模糊匹配)
- `--start-date`/`--end-date`: 日期范围(YYYY-MM-DD)
- `--type`: income|expense 过滤
- `--limit`: 返回条数(默认20)

### 3. 修改记录

**调用脚本:**
```bash
python scripts/manage.py --action update --id <记录ID> --field <字段名> --value <新值>
```

**可修改字段:** category/amount/description/date

### 4. 删除记录

**调用脚本:**
```bash
# 删除单条
python scripts/manage.py --action delete --id <记录ID>

# 批量删除(按日期范围)
python scripts/manage.py --action delete-batch --start-date 2024-01-01 --end-date 2024-01-31 --category 餐饮
```

---

## 五、效果预览

### 输入（一句话记多笔）
```
今天中午吃了碗面15块，下午网购了一件衣服200，晚上请客户吃饭花了350
```

### 输出（自动拆分）
```
✅ 已记录3笔：
1. 餐饮 -15.00元 (午餐面条) [2024-01-15]
2. 购物 -200.00元 (衣服) [2024-01-15]
3. 人情 -350.00元 (请客户) [2024-01-15]

今日支出：565.00元
本月累计：2,340.00元
```

### 输入（查询统计）
```
帮我看看这个月花了多少钱
```

### 输出（统计报表）
```
📊 2024年1月收支统计

总支出：2,340.00元
总收入：8,500.00元
净结余：+6,160.00元

类目占比：
├─ 餐饮 680.00元 (29.1%)
├─ 居住 1,200.00元 (51.3%)
├─ 交通 260.00元 (11.1%)
├─ 购物 200.00元 (8.5%)
└─ 其他 --
```

---

## 六、明确不支持清单

| 不支持项 | 说明 | 建议 |
|----------|------|------|
| ❌ 多用户协同记账 | 数据仅存在本地JSON，不支持多账号同步 | 将文件放在云盘同步目录 |
| ❌ 数据导入导出(CSV/Excel) | 暂无导入导出功能 | 手动复制JSON数据转换 |
| ❌ 预算管理与提醒 | 不支持设置预算和超支提醒 | 定期查询统计监控 |
| ❌ 周期重复记账 | 不支持自动记每月固定账单 | 每月手动记录或使用其他工具 |
| ❌ 多币种/跨境消费 | 仅支持人民币金额 | 外币请换算后记录 |
| ❌ 账单图片识别 | 仅支持文字输入，不支持OCR识别图片 | 手动输入金额和类目 |
| ❌ 云端备份 | 数据仅本地存储，换设备可能丢失 | 定期备份JSON文件到云盘 |
| ❌ 容量上限说明 | 未明确单文件记录上限 | 建议每月新建文件或定期归档 |

---

## 七、异常处理指南

| 异常情况 | 处理方式 | 用户指令示例 |
|----------|----------|-------------|
| 金额写错 | 修改记录："把昨天那笔50改成80" | 提供正确金额 |
| 类目分错 | 修改类目："把餐饮改成购物" | 说明正确类目 |
| 日期模糊 | 智能体追问："请问是哪一天？" | 补充具体日期 |
| 记录找不到 | 查询确认："查一下上周的地铁费" | 提供更多关键词 |
| 歧义场景 | 按优先级规则处理，不确定时追问 | 明确说明是收入还是支出 |
| 删除误操作 | 无撤销功能，需重新添加记录 | 谨慎删除，确认后再执行 |
| 文件损坏 | 返回空数据，提示检查文件 | 从备份恢复JSON文件 |
| 参数错误 | 返回错误提示和正确用法示例 | 按示例格式重新输入 |

---

## 八、常见歧义处理（速查表）

| 歧义场景 | 处理建议 |
|---------|---------|
| "红包" | 有明确指向收入时→收入(礼金)，无明确指向时→支出(人情) |
| "请客" | 支出类目(人情) |
| "工资" | 收入类目(工资) |
| "理财" | 收入类目(理财收益) |
| "报销" | 收入类目(其他收入) |
| "退款" | 收入类目(其他收入) |

---

## 九、使用示例

### 示例1:一句话记多笔账
- 输入:"今天中午吃了碗面15块，下午网购了一件衣服200，晚上请客户吃饭花了350"
- 智能体解析:
  - 餐饮:15元(午餐面条)
  - 购物:200元(衣服)
  - 人情:350元(请客户)
- 脚本调用:record.py 写入3条记录

### 示例2:查询统计
- 输入:"帮我看看这个月花了多少钱"
- 智能体调用:query.py --mode summary --period month
- 输出:本月总支出/各类目金额及占比

### 示例3:修改记录
- 输入:"把昨天那笔50块的餐饮改成购物"
- 智能体先query查找到记录，确认id后调用:manage.py --action update --id xxx --field category --value 购物

### 示例4:删除记录
- 输入:"删掉上周三那条地铁费记录"
- 智能体查询定位后调用:manage.py --action delete --id xxx

---

## 十、FAQ

| 问题 | 回答 |
|------|------|
| 支持多用户共用吗？ | 不支持。数据存储在本地JSON文件，建议放在云盘同步目录实现多设备查看。 |
| 能导入支付宝/微信账单吗？ | 暂不支持。只能手动输入或复制粘贴。 |
| 数据会丢失吗？ | 数据存在本地，换设备或误删文件会丢失。建议定期备份。 |
| 支持设置预算吗？ | 暂不支持预算管理功能，可通过定期查询统计监控。 |
| 记账说错话了怎么办？ | 支持修改记录，只需说"把XX改成XX"即可。 |
| 删除能撤销吗？ | 不能撤销。删除前会确认，请谨慎操作。 |
| 支持外币吗？ | 仅支持人民币，外币请换算后记录。 |
| 最多能记多少笔？ | 未明确上限，建议每月归档或分文件存储。 |
| 数据存在哪里？ | 当前目录下的 `expense_records.json` 文件。 |
| 换电脑能同步吗？ | 将JSON文件放在云盘同步目录即可跨设备。 |

---

## 十一、资源索引

- 脚本:见 [scripts/record.py](scripts/record.py)(用途:新增记账记录，支持多笔批量写入)
- 脚本:见 [scripts/query.py](scripts/query.py)(用途:查询明细与统计汇总)
- 脚本:见 [scripts/manage.py](scripts/manage.py)(用途:修改与删除已有记录)
- 参考:见 [references/category_rules.md](references/category_rules.md)(何时读取:需调整类目关键词匹配规则时)

---

## 十二、注意事项

- 金额默认单位为元，大额可用"万"为单位(如"工资2万")
- 日期表述优先按自然语言解析，确实模糊时默认当天
- 删除操作需先确认记录存在，涉及金额较大的删除应二次确认
- 跨设备同步依赖文件存储位置(建议放在云盘同步目录)