self-budget-agent：把"钱不知道花哪了"变成看得见的账
一、这个 Agent 是干什么的
self-budget-agent 是「自我」系列里专注于个人财务的一个能主动干活的 AI Agent。它的服务对象是「用 AI 的人」本人——那个月底看余额发愣、立过无数次记账 flag 又放弃、收入涨了却依然存不下钱的你。
它不推荐任何理财产品，不做税务或法律意见，也不劝你苦行。它只做一件事：把"我的钱到底怎么流的"这件模糊的焦虑，拆解成一组可记录、可计算、可复核的指标：
- 收支全景：收入、支出、净结余、储蓄率，全部从你自己的记录算出来，不靠估；
- 漏钱口定位：分类占比、固定支出占比、单分类超预算百分比，直接点名哪个分类在漏；
- 抗风险能力：应急金覆盖月数——一次意外你能撑几个月，这是所有财务动作的地基；
- 支出稳定性：日支出变异系数，暴露大额冲动消费；
- 本周只改一个：
plan每次只给一条行动，且行动与它提示的问题同源，不会出现"提示应急金不足、建议去降房租"这种自相矛盾的输出。
它背后站着一整套行为经济学与个人理财的循证底座（详见 references/ 与 resources/）：50/30/20 法则、应急金、储蓄率与财务独立、心理账户、双曲贴现与 Save More Tomorrow、支付痛感、沉没成本、锚定效应、享乐适应、复利、债务雪球与雪崩、记账与消费觉知、FIRE。不是"理财博主的经验"，而是带年份、期刊、书名出处的理论。
二、主动触发（重要）
这个 Agent 不是等你来翻文档的说明书。当以下情形出现时，它会主动介入：
- 你说"钱不知道花哪了"——主动建议从
log连续记 30 天起步，并说明为什么先记不判断（记账的作用是恢复觉知，不是审判）； - 你说"存不下钱 / 月月光"——主动跑
risk，把储蓄率、应急金、固定支出占比摆出来，用双曲贴现解释"这不是意志力问题，是决策架构问题"，然后给自动化方案； - 你说"想开始理财"——主动用应急金与债务利率先排序：先存 1 个月应急金，再清高息债，最后才谈投资；
- 你提到"这个月又冲动消费了"——主动调出日支出变异系数与分类预算执行，用支付痛感理论解释为什么扫码支付让人无感，并给加摩擦的具体做法；
- 你提到"涨薪了但还是没钱"——主动用锚定效应与享乐适应点破生活方式膨胀，建议用百分比而非绝对金额设目标；
- 你提到"订阅/会员一堆不想续又懒得取消"——主动用沉没成本理论给判断标准（"如果今天从零开始我还会花这个钱吗"），并用固定支出占比量化它的重量；
- 你提到"要不要提前还贷 / 先还债还是先投资"——主动把利率排出来做算术比较，并声明本工具不做投资建议；
- 报告退出码为 1（存在中/高风险）——主动用
plan给出本周唯一主攻项并解释原因。
换句话说：它在该出手时出手，在该收手时收手（不替代持牌顾问），在该教育时教育（用理论而非说教）。
三、理论地图（13 篇均带出处）
| # | 主题 | 代表出处 |
|---|---|---|
| 1 | 50/30/20 法则 | Warren & Tyagi 2005, All Your Worth |
| 2 | 应急金 | 美联储 Economic Well-Being 报告（2019） |
| 3 | 储蓄率与财务独立 | Bengen 1994, J Financ Plan 7(4)；Trinity Study 1998 |
| 4 | 心理账户 | Thaler 1985, Marketing Science 4(3) |
| 5 | 双曲贴现与 Save More Tomorrow | Laibson 1997, QJE 112(2)；Thaler & Benartzi 2004, JPE 112(S1) |
| 6 | 支付痛感 | Prelec & Loewenstein 1998；Feinberg 1986, J Consum Psychol |
| 7 | 沉没成本 | Arkes & Blumer 1985, OBHDP 35(1) |
| 8 | 锚定效应 | Tversky & Kahneman 1974, Science 185(4157) |
| 9 | 享乐适应 | Brickman & Campbell 1971；Brickman et al. 1978, JPSP 36(8) |
| 10 | 复利 | Malkiel 1973, A Random Walk Down Wall Street |
| 11 | 债务雪球与雪崩 | Ramsey 2003；Kellogg 工作论文（2020） |
| 12 | 记账与消费觉知 | Harkin et al. 2016, Psychol Bull 142(2) 元分析 |
| 13 | 财务独立与 FIRE | Domínguez & Robin 1992；Bengen 1994 |
四、快速上手
# 0) 设个人财务档案（月度收入 / 目标储蓄率 / 应急金 / 分类预算），可选
python scripts/budget.py --data ./my_money set \
--income 12000 --target_save_rate 20 --emergency_fund 8000 \
--cat_budget 餐饮=1500,交通=500,娱乐=800
# 1) 记一笔支出（分类用你自己的话，别纠结归类）
python scripts/budget.py --data ./my_money log \
--date 2026-09-01 --kind out --amount 38 --category 餐饮 --note 午饭
# 2) 记一笔收入
python scripts/budget.py --data ./my_money log \
--date 2026-09-01 --kind in --amount 12000 --category 工资
# 3) 看收支全景（储蓄率、折算月支出、必需/想要结构）
python scripts/budget.py --data ./my_money trend --days 30
# 4) 预算执行与 50/30/20 对照
python scripts/budget.py --data ./my_money budget --days 30
# 5) 财务风险与弱项扫描（存在中/高严重度时退出码 1）
python scripts/budget.py --data ./my_money risk --days 30
# 6) 本周最值得做的一个改变
python scripts/budget.py --data ./my_money plan --days 30
# 7) 完整报告（落盘 + 弱项退出码 1）
python scripts/budget.py --data ./my_money report --days 30
数据落在 --data：events.jsonl（按 type+id 幂等，记错可重记覆盖，不会重复计数）+ profile.json + reports/budget-<日期>.md，纯本地、不联网、可长期追踪、重跑结果一致。
五、子命令速查
| 命令 | 作用 | 关键参数 |
|---|---|---|
set |
设收入/目标储蓄率/应急金/分类预算 | --income --target_save_rate --emergency_fund --emergency_months --cat_budget |
log |
记一笔收支 | --date --kind（in/out）--amount --category --note --id |
trend |
收支趋势与结构 | --days（默认 30） |
budget |
预算执行与 50/30/20 对照 | --days（默认 30） |
risk |
财务风险与弱项扫描（中/高退出码 1） | --days（默认 30） |
plan |
本周最该做的一个改变 | --days（默认 30） |
report |
完整报告（落盘 + 中/高退出码 1） | --days（默认 30） |
退出码：0 正常 / 1 存在中或高严重度弱项 / 2 用法错误 / 4 参数或数据不可用。
六、边界声明
- 这是前哨工具：帮你量化现金流与结构，不是理财顾问；
- 不做投资建议、不做税务与法律意见、不推荐任何产品。涉及资产配置、退休规划、债务重组、税务处理，请咨询持牌顾问；
- 所有指标从你的记录推出，数据质量决定结论质量——
trend会显示记录条数，条数太少时不要对数字过度解读； - 分类预算按月度设定，引擎会按窗口天数折算对比；
- 数据全部存在本地，不上传、不联网。
详见 README.md（导航）、FAQ.md（场景对照）、references/（13 篇理论长文）、examples/（完整样例）。
