家庭收支分析报告 (ym-household-budget)

省去了记账数据导出后不知道怎么分析、分类全靠手动、看不出异常支出的低效。

何时使用

• 用户提到「帮我分析下这个月开销」时
• 用户提到「这个月钱花哪了」时
• 用户提到「家庭支出分析」时
• 用户提到「记账数据分析」时
• 用户提到「帮我看看花了多少钱」时
• 用户提到「收支分析报告」时
• 用户提到「记账app导出的数据」时
• 用户提到「怎么省钱」时
• 用户提到「这个月花太多了正常吗」时
• 用户提到「帮我整理下记账数据」时
• 用户提到「月度开销报告」时
• 用户提到「expense analysis」时
• 用户提到「household budget」时

版本自检（每次动手前先跑）

python scripts/sync.py --json

只读比对线上版本：退出码 0 最新 · 10 有新版建议重装 · 20 主版本不同必须重装 · 30 联网失败按旧版继续。

本技能不自动更新自己 —— 换版本只有一条路：用户明确重装（skillhub install ym-household-budget）。

运行前提

• 依赖：pandas、matplotlib、jieba；首次使用先跑 python scripts/setup.py 安装依赖。
• 字体回退顺序：generate_report.py 中 matplotlib 字体回退链为 ['Microsoft YaHei', 'SimHei', 'Arial Unicode MS', 'PingFang SC', 'WenQuanYi Micro Hei', 'Noto Sans CJK SC', 'DejaVu Sans']。字体缺失时中文渲染为方框（□），不影响数据计算和HTML报告生成，仅影响图表中文标签显示。乱码排查参考 references/common-pitfalls.md。
• 配置：运行时配置放 ~/.workbuddy/ym-household-budget_config.json，对外只留 config/settings.example.json 空模板。

适用范围与边界

适用：家庭收支数据的解析、自动分类、月度趋势分析、异常支出识别和可视化HTML报告生成。支持多种记账APP导出格式和文本粘贴。

不适用：
- 企业财务分析（不做损益表、资产负债表、现金流表）
- 投资收益合并计算（不做基金/股票/理财收益的盈亏合并）
- 多币种换算（不做汇率转换，不同币种数据需用户预先换算）
- 税务申报（不做个税计算、专项扣除、年度汇算）

输入数据格式

支持的数据源

字段最低要求

必须包含以下字段中的至少一种组合：
- 日期 + 金额 + 备注（或交易对方）
- 日期 + 金额 + 分类（若APP已分类）

缺少日期或金额时，提示用户补充；仅有金额无日期时，按当月1日填充并标注「日期缺失」。

格式自动识别与字段归一化

1. 自动识别：读取数据前20行，匹配已知APP的表头特征，确定数据源类型。
2. 字段归一化：将各APP的不同字段名映射到标准字段（date、amount、description、counterparty、type）。映射规则参考 references/field-mapping.md。
3. 流水账解析模式：自然语言流水账（如「3月5日 买菜 35元」）使用jieba分词提取日期、金额和描述关键词，再走分类流程。

分类体系

一级分类

二级分类示例

分类优先级链

按以下优先级依次匹配，命中即定分类，不再继续：

1. 备注关键词匹配（最高优先级）— 备注中含「美团」「饿了么」→ 餐饮
2. 交易对方商家名匹配 — 交易对方含「滴滴」「高德」→ 交通
3. 金额特征推断（最低优先级）— 无备注和交易对方时，按金额区间粗分

详细关键词映射表和规则参考 references/classification-rules.md。

分析维度

1. 月度总览

2. 分类占比分析

• 各一级分类金额占总支出的百分比
• 生成饼图（matplotlib pie chart）
• 标注占比最高的3个分类

3. 趋势分析

• 多月份总支出对比柱状图
• 环比折线图（本月 vs 上月 vs 上上月）
• 各分类环比变化（标注增减幅度最大的分类）

4. 异常支出识别

节省机会推荐

基于分析结果生成针对性建议：

1. 基于分类占比：占比最高的分类给出可缩减的具体建议（如餐饮占比40%→建议每周减少2次外卖）。
2. 基于异常支出：标注异常支出并提示「这笔支出是否符合预期？若为偶发可忽略」。
3. 基于趋势：若某分类连续多月上升，给出预算目标建议（如「购物连续3月上升，建议下月设上限800元」）。

报告生成

HTML报告结构

使用 templates/report-template.html 模板，包含以下区块：

1. 概览卡片区：总支出/总收入/结余率/日均支出（4个数字卡片）
2. 分类占比饼图区：matplotlib生成的饼图嵌入为Base64图片
3. 月度趋势折线图区：matplotlib生成的折线图嵌入为Base64图片
4. 异常支出高亮表格：日期/金额/类别/备注/异常原因
5. 预算建议区：针对性节省建议列表

matplotlib中文字体设置

import matplotlib
matplotlib.rcParams['font.sans-serif'] = ['Microsoft YaHei', 'SimHei', 'Arial Unicode MS']
matplotlib.rcParams['axes.unicode_minus'] = False

执行步骤

当用户需要分析家庭收支数据时，按以下步骤执行：

1. 接收数据 — 获取用户提供的数据（文件路径、粘贴文本或APP导出文件）；确认数据存在且非空。
2. 格式识别与字段归一化 — 读取数据前20行匹配已知APP表头特征，确定数据源类型；参考 references/field-mapping.md 将字段名映射到标准字段（date/amount/description/counterparty/type）；流水账文本走jieba分词解析模式。执行 python scripts/parse_data.py {input}，产出归一化CSV到工作目录。若识别失败，提示用户补充表头信息。
3. 执行分类 — 对归一化数据执行 python scripts/classify_expenses.py {normalized_csv}，按分类优先级链（备注关键词 > 交易对方匹配 > 金额推断）逐条分类；产出带分类标签的CSV。参考 references/classification-rules.md。
4. 生成报告 — 执行 python scripts/generate_report.py {classified_csv}，计算月度总览指标、分类占比、趋势分析和异常支出识别；matplotlib生成饼图和折线图嵌入HTML；使用 templates/report-template.html 渲染最终报告。产出 report_{YYYYMM}.html 到工作目录。
5. 校验报告 — 打开生成的HTML确认：概览数字合理（总支出 = 各分类之和）；饼图无乱码；异常支出表非空（若空则说明无异常，正常）；预算建议区有内容。校验失败参考 references/common-pitfalls.md。
6. 交付报告 — 将 report_{YYYYMM}.html 文件路径告知用户，用 file_export 声明产物。

目录说明

• scripts/ — 执行逻辑
• parse_data.py — 数据解析与字段归一化
• classify_expenses.py — 自动分类
• generate_report.py — HTML报告生成
• sync.py — 版本自检（只读）
• setup.py — 依赖安装
• templates/ — HTML报告模板（report-template.html）
• references/ — 分类规则、字段映射、常见坑参考文档

参考资料

• references/classification-rules.md — 分类规则和关键词映射表
• references/field-mapping.md — 各记账APP导出格式字段映射表
• references/common-pitfalls.md — 常见坑和解决方案

常见坑

1. matplotlib中文乱码 — 现象：生成的饼图和折线图中文字符显示为方框。原因：系统未安装matplotlib默认中文字体，或字体名与系统注册名不一致。规避：在 generate_report.py 中设置字体回退链 ['Microsoft YaHei', 'SimHei', 'Arial Unicode MS']；检查系统字体目录下是否存在中文字体；仍乱码时参考 references/common-pitfalls.md 手动指定字体路径。 # skill-audit: ignore

2. 字段KeyError — 现象：parse_data.py 报错 KeyError: 'date' 或类似字段名错误。原因：不同记账APP导出的字段名不一致（如随手记用「交易时间」、鲨鱼记账用「日期」），字段映射表未覆盖该APP格式。规避：参考 references/field-mapping.md 检查该APP的字段映射；若为新APP格式，将导出文件的表头前5行与映射表对比，补充缺失映射后再执行。

3. 分类全落「其他」 — 现象：报告显示80%以上支出归入「其他」分类，饼图无法反映真实消费结构。原因：备注字段为空或只含交易流水号（如「202403051234」），交易对方也未匹配到已知商家名。规避：在 classify_expenses.py 中增加金额特征推断规则（如金额<50元优先归入餐饮/交通）；提示用户在记账APP中补充备注信息后再导出；对支付宝/微信账单优先使用交易对方字段做分类。

4. 流水账文本无法解析 — 现象：用户粘贴的自然语言流水账（如「3月5号买菜35，打车12块」）解析后字段缺失或金额提取错误。原因：自然语言表述方式多样，jieba分词未能正确识别日期、金额和描述的边界。规避：提示用户按「日期 金额 备注」或「日期 类别 金额」格式分行书写（如「3月5日 35 买菜」每行一条）；金额后加「元」字提高识别率；解析失败时改用表格格式重新粘贴。