ray-household-finance — 家庭财务管理框架

Overview

家庭财务的通用管理框架，当前以投资组合分析为核心、面向家庭财务全场景扩展。

数据源无关——无论输入是天天基金 Excel 导出、手机截图 OCR、手动录入还是未来接入的 API，都先经「数据源适配器」归一化为标准化持仓 JSON，下游分析（分类/对比/轮动/比例控制/预测/可视化）只认这个 JSON，与输入源完全解耦。

双契约（v2.2 起）：①持仓快照 JSON（现状，存量资金有多少、结构如何）；②交易流水 transactions（历史，append-only 记买入/卖出/分红）。快照回答「现在怎么样」，流水回答「从头到尾真实赚了多少」——真实收益率/XIRR 只有流水才能算，快照里的 gpct 只是阶段收益。无流水时全部场景照常工作（流水是增强项，非前置依赖）。

核心流水线：数据源适配 → 标准化 JSON → 对比快照 → 按场景分析 → 生成 HTML → 验证 → 交付。

定位演进：本 skill 由「个人基金投资组合分析」演进为「家庭财务通用管理」，未来按需扩展收支记账、预算、保险、储蓄目标、资产负债全景——新场景沿用同一「数据源适配 + 标准化 JSON」架构，增量接入。已规划的扩展：收支场景引入「财务健康评分」四维度（储蓄率/必要支出占比/消费波动/应急储备 3-6 个月），待收支数据源接入后落地。评分量化阈值参考（v2.4 补，外部同类校准）：储蓄率 20%+ 及格 / 40%+ 优秀；负债收入比 <36% 健康 / 36-50% 警告 / >50% 危险；应急储备 3-6 个月月支出。

收支记账方法论（v2.3 新增，收支场景落地时套用）——记账是家庭财务第二常见场景，外部方法论已验证的核心规则（克制吸收，不重写架构）：

落地方式：沿用数据源适配架构，新增 manual（口述记账）或 excel（账单导出）adapter 产出标准流水 JSON → 复用月度复盘/预算分析。触发词「记账/收支/预算」进入该场景。

标准化持仓 JSON（全流程的唯一契约）

所有适配器的产出、所有分析步骤的输入，都遵循同一 schema（完整字段定义见 references/json-schema.md，交易流水 schema 亦在该文件）。核心字段：acls 四类 bond|index|qdii|mixed；四类资产口径 = 活期宝/国内债基/美债QDII/ETF权益（指数型+纳指QDII 归 ETF 权益）；yield_rate/gpct_s 是字符串（可能含 --）。任何新数据源，只做「把原始数据映射成这个 JSON」这一件事，下游零改动。

数据源适配层（新增数据源的唯一接入点）

新增数据源时：写一个 adapter 产出标准 JSON，其余六步流程完全复用。

manual 先落盘纪律（v2.9.0）：用户在对话中提供的任何财务数字（"买了 XX ¥5000"、"余额 8000"、"工资 4500/月"）——即使只是顺口一提、即使只是提问的一部分——先持久化再回答：写入标准 JSON（source: manual）→ 一行回执（"已存：1 笔（餐饮 ¥50）"）→ 继续对话。数字只在对话里飘过一次 = 下次会话必然丢失。

实时金融数据 MCP（v2.9.2 新增，2026-10-02）

DSH desktop profile 已挂载 AKShare MCP（serverName: akshare，工具前缀 mcp__akshare__，28 工具，免费无凭证）。

• 用途：用户问「XX 基金现在净值多少 / 大盘多少点 / 最近 CPI / 这只 ETF 行情」→ 直接调 mcp__akshare__*，不再让用户手动导出或截图
• 常用工具：get_fund_open_fund_daily（基金净值）｜get_stock_zh_a_hist（A 股 K 线）｜get_stock_financial_indicator（PE/PB/ROE）｜get_stock_hsgt_hist（北向资金）｜get_macro_china_cpi / get_macro_china_gdp（宏观）
• ⚠️ 失效与降级纪律（2026-10-02）：曾失效的 search_fund_code、get_stock_zh_index_spot、get_fund_etf_spot 已当日修复（改用 fund_name_em/分类过滤/同花顺源）；但免费源随 akshare 版本与东财接口持续漂移——FAIL 时换工具不重试，重复 FAIL 的工具按当时实际报错换 WebSearch，勿假设本节黑名单永远最新
• 数据来自东财/新浪公开接口，仅供研究参考、不构成投资建议（与「诚实声明」节同规）；宏观类实测可用，行情类接口偶发断连属正常

场景路由（先识别场景，再走对应流程）

通用执行流程（六步）

第 1 步：数据源适配（必须先做，不能跳过）

将任意输入归一化为标准 JSON。Excel 源：scripts/adapters/excel.py <excel路径> <日期> → 默认写 ~/.workbuddy/data/ray-household-finance/_portfolio_data.json（v2.4.1 起默认输出技能包外数据目录，第 3 参数可覆盖——家庭财务敏感数据不进技能包）。

⚠️ Excel 结构铁律（仅 Excel 适配器）：天天基金 Excel 是纯位置解析（非标准表格），必须先 load_workbook 打印 sheetnames + 前 6 行原始值，核对后再写解析逻辑。活期宝 sheet 行结构：名称 | 7日年化 | 可用/可取/总份额 | 未付收益 | 累计收益；基金 sheet 每只基金占 6-7 行块（名称行 + 类型行 + 金额行 + 状态行 + 盈亏行 + 收益率行），状态值含「有在途交易/到期/未到期/将到期」四种，块高随状态变化（6 或 7 行），必须用「名称行含 6 位代码」作为锚点 + 状态值判断动态跳行。

第 2 步：资产分类

• 债券型 → bond；指数型 → index；QDII → qdii；混合型 → mixed
• 四类资产口径：活期宝 / 国内债基 / 美债QDII / ETF权益（指数型+纳指QDII 归入 ETF 权益）
• ⭐ 穿透校验（v2.7 新增）：type_info 的分类标签不等于实际风险——「债券型」里混着二级债基 / 可转债基（含权益）。分类后必须回查实际资产占比（股票 %），不可只看标签。实证：110027 标签为债券型、acls=bond，实际股票 19.72%，波动率 9.16% vs 纯债 0.61% = 15 倍；近 1 月 −1.21% 而同期纯债 +0.26%。
• 提取后立即打印核对：部分之和 == 总资产，验证通过才继续。

第 3 步：对比快照

读上次快照做类别增减表 + 上次建议执行核对表（✅已执行/🟡部分/⏳未执行）。基线取数优先级（v2.9.0）：① ~/.workbuddy/data/ray-household-finance/_snapshots/ 归档目录（按日期命名、永不覆盖，excel.py 导入时自动写入）→ ② 项目 MEMORY.md / 默认快照文件。⚠️ 默认 _portfolio_data.json 是单文件覆盖式的，用它做旧基线前先确认日期；归档目录里没有对应日期时才降级。

第 4 步：按场景分析

• rotate：不按收益率排序选品种。先查结构性理由（费率合计 / 规模连续净赎回 / 逼近清盘线 / 快赎与到账规则），再比机会成本（大类配置缺口 vs 同类内轮换，通常差一个数量级）——见下方「货基轮动判据」节
• bond：先按久期四型分层（中短债·短债 / 滚动持有 / 长期纯债 / 二级债基），再算当前→目标→加仓额。搬家优先中短债 A 类（久期短、吃票息、最不惧利率上行）；长久期纯债与二级债基不因"收益高"而选。
• 四型久期假设（评估敏感度用，非实测）：中短债/短债 1.0 年｜滚动持有 1.0 年｜长期纯债 3.5 年｜二级债基债券部分 1.0 年（权益部分另算）。
• ratio/project：见下方「比例控制模型」

第 5 步：生成 HTML（可视化）

模板注入模式：Python 脚本生成 HTML，图表数据必须由脚本注入（json.dumps 或 f-string），绝不手写数据数组（手写必抄错，已踩坑）。

第 6 步：验证 + 交付

A. 数据验证清单（交付前逐项核对）：

• [ ] 部分之和 == 总资产：mm_total + fund_total == grand_total；class_totals 各键求和 == grand_total
• [ ] 四类和 == total（比例/预测场景）：模拟输出四类资产之和恒等于总资产，逐月校验
• [ ] 权重和 = 100%：四类占比（或持仓明细权重）加总为 100%（允许 cash 项）
• [ ] 数据源标注：输出开头标注数据来源与快照日期（如「数据：Financial-0809.xlsx，净值日期 08-07」）
• [ ] stale data 警告：若净值日期距快照日期 >3 天，或收益率明显异常（如货基年化 >5% 或 <0.3%），显式提示数据可能滞后
• [ ] \ufffd 扫描：html.count('\ufffd') 必须为 0（零容忍）
• [ ] 金额转"万"用 toFixed(1)：(x/10000).toFixed(1)，不要 Math.round(x/10000)/100

B. 集中度检查：

• 单只基金金额 > 总资产 10% → 标记 ⚠️ 集中度风险
• 债基双核心（嘉实汇鑫/长安泓沣）合计占国内债基比，若 >60% 需提示分散

C. 输出结构模板（固定 7 段，不遗漏）：

1. 快照总览（类别 × 金额 × 占比表）
2. 对比变化（本次 vs 上次，类别增减表）
3. 执行核对（上次建议 ✅已执行/🟡部分/⏳未执行）
4. 场景分析（rotate/bond/ratio 按触发场景）
5. 集中度提示（如有 >10% 或 >60% 集中，单独列出）
6. 行动清单（P0/P1/P2 分级，具体到金额和基金）
7. 结论信号（组合状态 + 下一步核心动作 + 置信度，见下）

D. 结论信号框（结尾固定输出）：

┌─ 投资结论 ─────────────────┐
│ 状态: 稳健 / 需调整 / 偏谨慎 │
│ 下一步: [核心动作一句话]      │
│ 置信度: 高 / 中 / 低         │
└────────────────────────────┘

• present_files 打开预览；回复给核心结论表 + 行动清单（P0/P1/P2）。

比例控制模型（核心方法论，2026-08-05 确立）

用户已采纳的资产配置策略（替代固定定投）：

• 目标比例（方案A）：活期宝 30% / 国内债基 50% / 美债QDII 12% / ETF权益 8%
• ⚠️ 加权年化三态分列，勿混（v2.7 订正）：现行目标 2.8% ｜ 测算 2.81%（配置到位 2.56% ＋ 债基提质 0.25pp）｜ 旧记 2.46% 已过期，不得再引
• 机制：每月定额充入活期宝 → 计算四类目标额 = 总资产 × 目标比例 → 活期宝超配部分按缺口比例流向低配类
• 漂移带（v2.2 新增，±5%）：某类资产实际占比偏离目标 < 5 个百分点时当月不调仓（带内不动），超带才调——避免月月微调、减少无意义操作。scripts/ratio_control.py --band 5（默认 5，--band 0 恢复逐月精确调仓）
• 约束：① 月转出上限（默认约 5 万）② QDII 限购约 1 万/月（超额转债基）
• 收敛：活期宝首月 67.4% → 约第12月<40% → 第15月收敛到 30%；3年后达到目标资产规模
• 模型代码：scripts/ratio_control.py（模拟 36 月，输出每月余额 + 建议转出额）

货基轮动判据：结构性理由，不看收益率排名（v2.6 修订，2026-09-13 回测证伪）

> ⛔ v2.5 的「双边合格线（收益率判据）」已于 2026-09-13 被回测正式证伪、整节废止——旧内容存档于 references/superseded.md，不得据此下单。
>
> 证伪证据（近 1 年 20 只货基，真实万份收益逐日复利；近 3 年 18 只同结论）：

• 追排名是负 alpha：当期第 1 名 3 个月后中位落到第 9.0/20 名，进前 3 命中率 12% ＜ 随机 15%；但当期 → 未来 3 月秩相关 +0.461 ⇒ 排名中段有持续性、顶端反转，而轮动恰只抓顶端。
• 摩擦成本与理论收益同量级：作用于全部活期宝 → 1 天空档 −¥1,325/年、2 天空档 −¥2,649/年，而横截面收益极差仅 0.3080pp。
• 差距的一半是费率，不是能力：费前收益极差 0.1590pp ≈ 费率极差 0.1600pp ⇒ 费率占到手差距 52%；费率 ↔ 到手收益 −0.737。

✅ 现行判据（按可靠性排序，v2.6 生效）

配套纪律：① 轮动候选排序以非零持仓为基础（shares > 1），零残渣基金不参与比较；② 动手前先比机会成本——同类别内轮换的增益通常比大类配置纠偏低一个数量级以上（实测 ¥166/年 vs ¥3,032/年 = 18.3 倍），先补齐大类缺口；③ 数据字段：货基 7日年化在标准 JSON 的 yield_rate，形如 "0.3336（1.2420%）"——括号内是 7日年化，括号外是万份收益。

📕 作废判据留档：v2.5 的「双边合格线（收益率判据）」已于 2026-09-13 被回测证伪，整节存档于 references/superseded.md（仅作教训查阅，不得据此下单）。唯一保留进正文的残值：7日年化 >2% 视为异常 → 先观望一周再操作（一次性收益尖峰实证：某货基 5 个交易日从 1.4070% 掉到 1.2010%）——这是风险提示而非轮动依据。

定投与锁定期纪律（v2.5 新增，2026-09-05 实证）

核心规则：有锁定期的产品，禁止做高频（日/周）定投。

实证（2026-09-05）：用户自行为"中加聚安60天滚动"开 ¥500/日 定投，想法是"日定投形成滚动流动性"；当晚想清楚锁定期摩擦后自行停止。→ 原判断"滚动流动性是优点"被推翻：事实是每笔各锁 60 天、流动性碎片化。
> 这条也是正面案例：用户试错快、纠错快——但 AI 的职责是在开定投之前就提示锁定期摩擦，而不是等用户自己发现。

定投计划表解析（v2.5 新增：天天基金 Sheet3）

天天基金导出的 Excel 第三个 sheet = 定投计划全表（Sheet3，早期导出可能无此表）。这是"用户当前在扣哪些款"的权威来源——比逐个询问快得多。

表结构（非标准表格，须按锚点解析）：

输出建议形态：结构化 JSON（每条含 name/code/cls/amount/freq/next/run/act/reason），act 为处置建议枚举（keep 保留 / rm 清理 / pause 建议暂停 / hold 保持暂停观察 / keep_pause 暂停待启用条件单），供仪表盘分页展示。

已见模式：无对应持仓的暂停计划（清理或挂观察）、同质叠加（AI + 云计算）、宽基条件单（暂停但勿删，等 PE 分位触发启用）。

交易流水与成本基准（v2.2 新增）

schema：transactions.json（append-only，完整定义见 references/json-schema.md）——每笔交易含 date / fund_code / fund_name / type(buy|sell|dividend) / amount / nav / fee。只追加、不修改；从启用日起记录，历史无法回补，成本基准以流水起点为准。

错账更正——红字分录（v2.9.0 新增）：append-only 意味着记错一笔不能删不能改，否则污染成本基准且破坏对账证据链。更正 = 追加一对分录：

1. 原错误分录原样保留（作为纠错依据）；
2. 追加一笔 type: "reversal"（红字冲销），amount = 原笔金额、ref 字段指向错误笔的 date+fund_code+amount 组合（流水无全局 ID，用三元组定位）；
3. cost_basis.py 汇总时按「buy/sell/dividend 计入、reversal 按反向计入」（red 字分录净额抵销），原始记录不动；
4. 输出成本基准报告时，被冲销的参与方各标注一行 （含红字冲销 ¥X），用户可见纠错痕迹。

实证动机（09-28 流水对账）：007529 流向误读后，若无更正分录机制，错误口径只能靠口头更正，下次计算仍会用错数据。

计算（scripts/cost_basis.py <transactions.json> [snapshot.json]，口径均为金额口径为主、份额法为辅）：

• 累计投入 = Σ buy；累计回收 = Σ sell + Σ dividend
• 累计损益 = 期末现值 + 累计回收 − 累计投入；真实收益率 = 累计损益 / 累计投入
• 加权平均成本 = Σ买入净额 / Σ买入份额（仅统计带 nav 的买入）
• XIRR：每笔买入为负现金流、卖出/分红记为正、期末现值为最后一笔，解年化内部收益率

输出必带两条诚实声明：①成本基准从流水起点算起，不含启用前的历史交易，故非「完整历史收益率」；②快照中未记流水的基金会缺失现值，脚本会显式提示（属正常，不是 bug）。

诚实声明（每次分析必带）

输出任何分析/预测/建议时，必须包含以下三条（可直接放在结论信号框下或文末）：

1. 这是条件规划，不是指令：比例模型/3年预测的所有数字都是「给定假设下的条件测算」，不是交易指令；实际操作需用户确认。
2. 收益是概率估算，非承诺：债基 2.5%/QDII 3.5%/ETF 5% 均为历史均值假设，不构成收益承诺；市场波动会使实际偏离。
3. 降低持仓 ≠ 必然增值：轮动/搬家优化的是结构（提升预期收益、分散风险），不是保证每笔都赚钱；久期长、汇率波动都可能造成短期回撤。

失败模式编码（thesis-break gate）

明确「什么情况该暂停/停止」，而非盲目执行：

每次按比例模型执行前，先检查上表是否触发；触发即调整节奏，不机械照搬模型输出。

闸门数据源与自洽校验（v2.8 固化，2026-09-21 实战验证）

闸门检验必须独立 HTTP 源 + 三源交叉 + 自洽校验，不依赖 MCP 工具是否暴露到会话：

配套纪律：① 区间统计防「pageSize 陷阱」——RPTA_WEB_TREASURYYIELD 默认 pageSize=60，会把「近60日」误当「2026年内」（实测区间宽 6.69bp vs 真值 22.25bp）；要年区间必须 pageSize≥300 并双口径分列。② 东财日期为非交易日时顺延取最近披露日并在输出标注 non_trading_day_carry。③ 闸门结果必须落盘 JSON（含 dist_gate_bp 距离字段），作为触发有效性的证据文件。

定投周检监控（monitor 场景，v2.8 新增）

触发词：周检、宽基监控、黄金回本、PE 分位巡检

三段式架构（已验证稳定运行）：数据 JSON（_wide_index_data.json / _gold_monitor_data.json）+ 生成脚本（_build_wide_monitor.py）+ 每周日 20:00 自动化巡检（AI 承担 WebSearch 分位/金价更新）。

自动化提示词纪律（2026-09-21 事故回流）：巡检自动化提示词里禁止写死会随时间失效的数值（乘数/区间/持仓金额）——一律改为「读 JSON 派生字段」；且闸门步骤必须显式写入提示词（只写在 skill 文档里，自动化执行体会跳过——09-20 周检漏闸门的根因即此）。

金额与预算的派生纪律（v2.8 新增）

• 汇总数从明细项实时求和，禁用手写总数：停掉一条定投线后，月投合计若沿用旧口径手写值就会多算（实证：010810 停扣 ¥100/日 后总数仍按 v5 口径写 ¥1,300/日）。判据与「数量类标注计算注入」同源——凡会因增删条目而变的数字，一律 sum() 现算。
• 同一数字多口径时分母显式标注：如「机会成本」有活期宝超配与债基缺口两个分母，引用前先确认分母。

共享红线（全场景通用）

1. 反引号坑（铁律）：写含反引号(`)的 Markdown 文件必须用 .py 脚本文件方式，禁止 bash -c 内联（反引号被 shell 解析成命令替换，会破坏文件内容、混入垃圾行）。已两次踩坑。
2. 图表数据脚本生成：HTML 图表的数据数组绝不手写，一律脚本注入（手写曾把大额数字写错一个数量级，还出现过数组笔误导致曲线锯齿）。推论（v2.5）：数量类文字标注也须由数据计算注入（如表格标题的"N 条"用 len(arr)，不写死数字）——2026-09-05 实证：数据已从 25 条收敛到 17 条，标题仍写"25 条"，数据对而标注错，肉眼扫过不易发现。
3. 金额转"万"用 toFixed(1)：(x/10000).toFixed(1)，不要 Math.round(x/10000)/100（多除 100 导致大额显示成小一个数量级）。
4. Python 列表深拷贝：模拟循环里 append 列表用 bal[:]，引用复用会导致下一轮覆盖、误报偏差。
5. 写完必扫 \ufffd：零容忍，任何产出文件都扫描。
6. 用户画像固定：保守型投资者，核心诉求"稳"，目标年化 2.5%；货基每周轮动 Top5-6；操作风格少问多做、输出表格+emoji。
7. 隐私保护（v2.1 新增，v2.3 升级为脚本级，v2.4.1 加路径红线）：处理的是家庭财务敏感数据（持仓金额、银行账号、收入）。四条强制：①脚本级脱敏——所有 scripts/*.py 输出账号/卡号前必须自动 mask（****1234 只留末 4 位，输出前统一过滤，不靠"记得手动脱敏"）；新增脚本/适配器时默认套用；②敏感数据优先本地处理，不主动上传第三方；③生成的 HTML/报告含金额时，默认仅本地预览，分享前先经用户确认；④运行时数据文件不进技能包——快照/流水 JSON 默认写 ~/.workbuddy/data/ray-household-finance/（技能包外），发现包内出现数据 JSON 即为泄漏隐患，先移出再继续。
8. % 转义坑（v2.7 新增，与红线 2 并列）：Python 模板里 % 写 %% 是对 f-string/% 格式化的要求；非格式化字符串里写 %% 会被原样渲染成 %%（实证 2026-09-17：_rate_bond_0917.py 直出文本第 44–50 行全部 %% 双写，肉眼扫过不易发现，只在落盘回读时暴露）。→ 生成器加 assert '%%' not in html 自校验；定位法 = AST 取 Assign(Name('html')) 的字面量逐字符扫（正则法误报率高）。
9. 数字单一源（v2.9.0 新增）：输出中引用的任何金额/费率/阈值/乘数/区间，必须来自当场读取的数据文件（快照 JSON / 监控 JSON / 流水 JSON）或当场检索的结果——凭记忆引用 = 违规（记忆里的数字会过期：09-21 巡检提示词写死 ×1.261 乘数与区间已实证翻车，v2.8 只对 automation 层设防，本条把同一纪律补齐到 skill 执行体层）。引用前自问：「这个数字是我刚从文件里读的，还是上次会话留下的？」

资源结构

ray-household-finance/
├── SKILL.md                      # 本文件（框架 + 路由 + 红线 + 诚实声明 + 失败模式）
├── evals/
│   └── prompts.md                # 触发用例套件（3 正向 + 3 near-miss，改后回归用，v2.9.1）
├── references/
│   ├── json-schema.md            # 标准化 JSON + 交易流水 schema 完整定义（按需加载）
│   └── superseded.md             # 作废判据存档（教训查阅用，不得用于决策）
└── scripts/
    ├── adapters/
    │   └── excel.py              # 天天基金 Excel → 标准 JSON（含快照自动归档）
    ├── extract_portfolio.py      # 别名入口（向后兼容，转发到 adapters/excel.py）
    ├── ratio_control.py          # 比例控制模型：36月模拟 + ±5%漂移带 + 建议转出额
    └── cost_basis.py             # 交易流水 → 成本基准 + 真实收益率 + XIRR + 红字分录（v2.9.0）

实战经验

• 2026-09-21｜[LRN-20260921-001]｜场景：monitor + gate｜经验：闸门与周检的流程缺口三件套回流。① 09-20 周检漏做闸门检验，根因＝自动化提示词无该步骤（skill 文档里有但执行体看不到）→ 闸门步骤必须显式写入自动化提示词；② 东财国债接口 pageSize=60 会把近60日当全年（区间宽 6.69bp vs 真值 22.25bp）→ 年区间统计须 pageSize≥300 且双口径分列；③ 巡检提示词写死 ×1.261 乘数与 $4,400-4,500 区间（均已过期）→ 动态数值一律改读 JSON 派生字段。以上已固化为 v2.8「闸门数据源与自洽校验」+「monitor 场景」节｜死路：以为「skill 文档写了」自动化就会执行；用接口默认 pageSize 做年区间统计｜来源：09-21 self-neat（automation-1787489198215 重写）｜计数：1｜状态：resolved

• 2026-09-11｜场景：版本回流｜经验：定投计划表解析规范（Sheet3）+「定投与锁定期纪律」回流入包（scripts/adapters/ 侧）：代码常省前导 0 须补全（7194→007194）、同基金新旧两条并存视为重复、状态字段是判断运行/暂停的唯一依据；有锁定期产品禁做高频定投｜死路：按"下次扣款日"推断状态、把滚动锁定当流动性优点｜来源：v2.4.1 → v2.5.0｜状态：resolved（③双边合格线已证伪 → 见 09-13 条）

• 2026-09-13｜场景：rotate｜教训：「按收益率轮动」被回测证伪，判据整节替换为结构性理由（费率/规模/快赎）。回测（近 1 年 20 只，真实万份收益逐日复利）：等权持有 1.4741% ＞ 追「4 周最优」无摩擦 1.3618% ＞ 扣 2 天空档 1.1155%（跑输反向对照"追最差"1.2304%）；近 3 年同结论。抓「当期第一」是负 alpha：3 个月后中位第 9.0/20 名、进前 3 命中 12% ＜ 随机 15%；但当期 → 未来 3 月秩相关 +0.461（中段持续、顶端反转）。另一半真相：费前收益极差 0.1590pp ≈ 费率极差 0.1600pp ⇒ 费率占到手差距 52%、费率 ↔ 到手 −0.737。实证教训两条：某货基 2.524% 虚高被追买 ¥31K 一周崩至 1.034%（追高站岗）；另一只 ¥30.7K 轮入时仅 1.112%（低换低白折腾）｜死路：按 7 日年化排序挑轮入品种（追排名 = 负 alpha）、只看收益率不看费率与规模｜来源：Financial-0912 活期宝收益率复核｜状态：resolved（判据已替换 → v2.6.0）

• 2026-09-05｜场景：bond｜教训：有锁定期的产品禁止做高频定投——"60天滚动"型日定投会使每笔份额各锁 60 天、流动性碎片化；债基搬家应聚焦无锁定中短债 A 类双核心。易误判点：停止定投 ≠ 解除既有份额锁定（存量仍按各买入日计锁定期）。实证：用户自开"中加聚安60天" ¥500/日后当晚想清摩擦自行停止，原判断"滚动流动性是优点"被推翻｜死路：用日定投制造"滚动流动性"（实为碎片化）｜来源：Financial-0905 定投体系讨论｜状态：resolved

• 2026-09-05｜场景：adapt｜经验：天天基金 Excel Sheet3 = 定投计划全表，是"当前在扣哪些款"的权威来源，比逐个询问快。格式=计划头（代码/名称/金额/周期/扣款日/下次/状态）+ 银行卡附属行；代码常省略前导 0 须补全（7194→007194）；同基金可能新旧两条并存（视为重复）；状态字段是判断运行/暂停的唯一依据｜死路：按"下次扣款日"推断状态｜来源：Financial-0905 Sheet3 解析（25 条 → 用户清理至 17 条）｜状态：resolved

• 2026-09-08｜场景：进化+隐私整改｜经验：外部对比吸收 2 项（财务健康评分量化阈值：储蓄率 20/40%、负债收入比 36/50%、应急金 3-6 月；记账输出按数据量分级 + 占比阈值预警）→ v2.4.0。隐私整改：进化轮隐私检查发现包内 _portfolio_data.json 含真实持仓（25 基金代码/大额金额）——excel.py 默认输出原写在脚本自身目录（技能包内），改为默认 ~/.workbuddy/data/ray-household-finance/（第 3 参数可覆盖），真实数据文件迁出，共享红线④新增"运行时数据文件不进技能包" → v2.4.1｜来源：v2.3.0 → v2.4.1

• 2026-09-02｜场景：进化｜经验：外部对比吸收 2 项——①共享红线「隐私保护」从纯文字升级为脚本级脱敏（所有 scripts 输出账号自动 mask，不靠"记得手动脱敏"）；②新增「收支记账方法论」增量接入（科目≤8/三字段起步/习惯二选一/只给 Top3 设预算），作为收支场景落地默认方法论，沿用数据源适配架构不重写。克制吸收：跳过 beancount 复式记账（个人家庭场景过重）、跳过预算 vs actual 企业级 variance 分析（非家庭场景）｜来源：v2.2.0 → v2.3.0

• 2026-08-28｜场景：进化｜经验：外部对比吸收 2 项——①交易流水第二契约（transactions.json append-only + cost_basis.py：加权平均成本/真实收益率/XIRR），补上「快照只能看现状、算不了真实收益」的架构级差距；②比例控制模型加 ±5% 漂移带（带内不动、超带才调），避免月月微调。克制吸收：跳过 sparkline（已有时效标注）和 provider fallback（边际）｜来源：v2.1.1 → v2.2.0

• 2026-08-15｜场景：进化｜经验：对比外部 skill 吸收 2 项——①隐私保护红线（账号脱敏、敏感数据本地处理、分享前确认）；②财务健康评分四维度（储蓄率/必要支出/波动/应急储备）记为未来扩展规划，待收支数据源接入后落地｜来源：v2.0.0 → v2.1.0

• 2026-08-15｜场景：改名｜决策：ray-financial-analysis → ray-household-finance（家庭财务管理），定位从「个人基金投资组合分析」升级为「家庭财务通用管理」；当前核心是投资组合分析，未来增量扩展收支/预算/保险/储蓄/资产负债，沿用同一数据源适配架构｜来源：v1.2.0 → v2.0.0（改名+定位升级，major bump）

• 2026-08-15｜场景：进化｜经验：对比外部 skill 吸收 5 个机制——数据验证清单、输出结构模板(7段)、集中度检查(>10%)、诚实声明(3条)、失败模式编码(thesis-break gate)；JSON schema 卸载到 references/｜来源：v1.1.0 → v1.2.0
• 2026-08-15｜场景：架构｜经验：skill 从「Excel 工具」升级为「数据源无关的持仓分析平台」——引入「标准化持仓 JSON」作为唯一契约 + 「数据源适配层」隔离输入差异（excel/screenshot/manual/api），新增数据源只写 adapter、下游六步零改动｜来源：v1.0.0 → v1.1.0
• 2026-08-09｜场景：parse+compare｜教训：天天基金 Excel 基金 sheet 块高随状态值变化（有在途交易=6行/到期=7行），必须用"名称行含6位代码"锚点 + 状态值动态跳行，不能固定步长｜来源：Financial-0804/0809 解析
• 2026-08-05｜场景：ratio｜教训：比例模型首次跑出"第1月建议一次性大额转出"（违反分批定投原则）+ QDII 单月转出触发限购；加"月转出上限 + QDII 月限购"约束后渐进收敛｜来源：比例控制仪表盘开发
• 2026-08-05｜场景：dashboard｜教训：KPI 金额 Math.round(x/10000)/100 把大额显示成小一个数量级（多除100）；改 (x/10000).toFixed(1)｜来源：比例控制仪表盘
• 2026-08-05｜场景：dashboard｜教训：对话内嵌曲线手写数组笔误导致"波动上升"锯齿；HTML 脚本生成的数据一直正确，此后图表数据一律脚本注入｜来源：3年预测仪表盘
• 2026-08-05｜场景：bond｜教训：某中短债基金"年度收益高"是记忆偏差（近1年跑输同类），且单日限购极低无法加仓；久期长的中长期纯债债牛猛、震荡落后，不适合保守组合做主力｜来源：债基加仓讨论
• 2026-07-13｜场景：plan｜经验：年化目标计划三阶段（活期宝从高配逐步搬到国内债基+美债QDII）；用户风险偏好保守，原更高目标过于激进已下调｜来源：目标计划制定
• 2026-08-23｜场景：parse｜经验：天天基金导出 sheet 名可能变化（"活期宝/基金" → "Sheet1/Sheet2"），适配器已改按位置取 sheet（第一个=活期宝，第二个=基金），不再依赖 sheet 名｜死路：按名匹配（wb['活期宝'] 直接 KeyError）｜来源：Financial-0823 解析｜状态：resolved
• 2026-08-23｜场景：compare｜经验：旧快照 JSON 会被新数据覆盖，对比基线可从历史仪表盘 HTML 内嵌的 const FUNDS = [...] / const MM = [...] 用正则提取，无需重新解析旧 Excel｜死路：依赖 _portfolio_data.json 存历史（单文件被覆盖）｜来源：0815 vs 0823 对比｜状态：resolved
• 2026-08-23｜场景：monitor｜经验：指数估值数据源可用性——东财 push2 估值字段接口有风控（RemoteDisconnected）、乐咕乐股 405 需登录、腾讯 proxy.finance.qq.com 只给行情不给 PE；分位数据靠每周 AI WebSearch 更新，点位走腾讯接口（稳定）｜死路：东财字段探测（连发触发风控）｜来源：宽基监控工具开发｜状态：resolved

• 2026-08-23｜场景：monitor｜经验：条件触发型定投工具（宽基 PE 分位阈值 + 黄金回本线）可做成「数据 JSON + 生成脚本 + 每周日自动化巡检」三段式，AI 在自动化里承担 WebSearch 数据更新职责；看板数据一律脚本注入不手写｜死路：全自动 API 拉分位（免费接口拿不到）｜来源：宽基+黄金监控｜状态：resolved

• 2026-09-15｜[LRN-20260915-001]｜场景：diagnose（持仓诊断）｜经验：摊薄成本假象校验 —— 「跌」与「亏」是两个问题。① 先回数据核对区间涨跌（用户描述"一路跌"，实测近 1 年 +5.35%、近 6 月 +12.27%、位置分位 66.4%，−8% 属正常波动，年化波动 23.68%）；② 再做成本口径校验：累计净值 ≡ 单位净值（差恒 0.0000）⇒ 无分红 ⇒ 由 市值 ÷ 净值 反推份额 ⇒ 反推成本净值 = 单位净值 × 成本 ÷ 市值；③ 若 反推成本净值 > 成立以来最高净值，则该收益率必含"已减仓部分的已实现亏损"，属摊薄成本假象，真实浮亏更小（实测 017436：反推 2.7586 > 历史最高 2.5259，−16.01% 实际最多 −8.28%）｜死路：拿"累计收益 ÷ 当前市值"直接推回本线（分母错 → 回本线被系统性高估）｜来源：017436 止损决策｜计数：1｜状态：resolved

• 2026-09-17｜[LRN-20260917-001]｜场景：macro（宏观传导）｜经验：宏观先算暴露面，再谈影响。① 收到"美联储加息对我持仓有什么影响"类问题，第一动作是算敞口而非判断宏观：本币利率资产 95.58% / 直接美元暴露 2.418% / 本币权益 2.00%；② 量级用 年化波动 ÷ √252 折单日 1σ 再乘金额（实测合计 ±¥243.63 = 总资产 0.0149%）；③ 方向反转——真正受损的是不能投的那部分（活期宝超配 ¥584,479 缺美元通道，机会成本 ¥29,801/年），而非持有的美元仓位；④ 利差 ≠ 汇率方向：10Y 美债−中债 334bp 本该压垮人民币，但中间价 6.7743 反而调升 44BP ⇒ 升值源自美元信用折价，不是利差 ⇒ 不构成加仓美元资产的理由｜死路：从新闻直接推结论（不先量敞口）、用"最坏情景"替代 1σ 判量级｜来源：美欧加息对持仓的传导分析｜计数：1｜状态：resolved

• 2026-09-17｜[LRN-20260917-002]｜场景：rotate 衍生（外币货基，场景缺口）｜经验：路由表无「外币货币基金」分支，现有 rotate 只管人民币货基（费率/规模/快赎）。外币货基须补 3 项判据：① 是否占 QDII 额度（决定能否突破 ¥10K/月，是本类任务的全部价值来源）② 汇兑损益 vs 利差对账（名义利差须减去人民币年化升贬，出敏感性表）③ 可申购性 / 起购 / 当前限购（买不进即出局）。另：同桶 ≠ 同类——QDII 桶内美股股票与美元债风险等级差 7 倍（波动 23.68% vs 3.35%），相关性仅 +0.209、同向 51.0%｜死路：沿用人民币货基判据直接选外币货基（漏掉额度与汇率两个决定性变量）｜来源：挑选美元货币基金（HANDOFF-2026-09-17-usdmm.md）｜计数：1｜状态：pending（场景未回流，待用户批准）

• 2026-09-17｜[LRN-20260917-003]｜场景：bond（事件冲击穿透）｜经验：加息对固收持仓的影响，要按久期分层算、并穿透"名义类别"。① 用户问"加息对我正在搬去的债基有什么影响"，不要笼统答"利空债基"——先按久期四型分层（中短债/短债 88.91%·滚动持有 2.07%·长期纯债 4.71%·二级债基 4.32%），久期短的那 88.91% 几乎不受影响（AAA 1Y 票息 1.5203% 是合同收益）；② 受影响的是资本利得一层：长端原本可预期下行 20bp → 汇率约束后约 7.5bp，损失 12.5bp × 久期敞口 ¥545,778 = ¥682/年（占债基 0.140%、占年化目标收益 1.5%）；③ 真正受损的是含权益那只——110027 标签「债券型」实为二级债基、股票 19.72%，重仓半导体/光模块（正是美债利率上行的承压名单）；④ 代价 vs 收益要对照量级：加息代价 ¥682/年 vs 搬活期宝超配收益 ¥4,676/年 = 6.85 倍 ⇒ 加息不改变搬家方向，只微调终点排序（ETF 尤其银行/红利 ↑ ＞ 债基 ↓ ＞ 美元资产 ✗）。方向判据：一句话错位会翻转结论——「利率被压低」→ 债基受益；「利率跌不下去」→ 债基轻微受损。用户原话"加息意味着人民币利率被锁在低位"属后者，须先纠正因果方向再答。"
  ｜死路：把"债券型"标签当纯债（漏掉 19.72% 权益）、只看总量不看久期分层（会把 ¥682 的代价说成重大利空）｜来源：加息对债基持仓的影响（_rate_bond_0917.py）｜计数：1｜状态：resolved

• 2026-09-28｜场景：进化｜经验：外部对比吸收 6 项 → v2.9.0（来源：SkillHub 8 候选 + GitHub 8 候选，深读 Top4）。①快照归档机制（excel.py 导入时自动存 _snapshots/portfolio_YYYYMMDD.json 不覆盖；对比基线优先从归档取——08-23「单文件被覆盖只能从 HTML 正则考古」死 workaround 正式废弃）②manual 适配器先落盘纪律（对话中财务数字先写 JSON→回执→继续；🧩→✅）③流水红字分录（append-only 的错账更正：type:"reversal" + ref 指向，cost_basis.py 净额抵销、纠错痕迹可见）④预算执行红绿灯（80% 黄灯/100% 红灯，进度维度）⑤复盘最小纪律（一次复盘只改一个科目）⑥数字单一源红线（凭记忆引数字=违规，09-21 教训从 automation 层补齐到 skill 层）。克制吸收：Monte Carlo 区间预测、订阅追踪、微信/支付宝账单全链路（工程量大）、企业预算差异分析（读者不一致）。减法 2 项：作废判据整节卸载 references/superseded.md（−48 行）、3 条 superseded 实战经验合并精简（−8 行）｜来源：v2.8.0 → v2.9.0（ray-skill-evolve 轮）

• 2026-09-28｜[LRN-20260928-001]｜场景：adapt（数据源适配）｜经验：天天基金导出格式会变，解析异常第一动作＝回读原始 sheet 行结构。0928 实测新格式：①活期宝 sheet 无「简称」表头、首行即数据、每只货基占 2 行（数据行+日期行）②基金 sheet 无表头区（首行直接是第一只基金）、块尾多「买入卖出明细」分隔行③定投计划表 Sheet3 → Sheet4。旧适配器因表头识别失败回退错 sheet，输出活期宝=0、总资产少 74%（静默错误，退出码 0）⇒ 适配器已加版式探测（新/旧格式自动分流）+ 漏抓闸门（货基<15 或基金<10 即 FATAL）。定投计划表位置自 0928 起须按「名称含'普通定投计划'」定位而非写死 Sheet3/4｜死路：按 sheet 名或序号定位（都会变）；表头识别失败后回退另一 sheet 继续解析（把错数据当真数据）｜来源：Financial-0928 导入事故｜计数：1｜状态：resolved

• 2026-09-28｜[LRN-20260928-002]｜场景：compare（流水对账）｜经验：流水归属判定必须用快照持仓存在性交叉验证；基金属性陈述必读快照字段。① 把流水代码行注释（有充值）当「转入目标」语义，推出「007529 是承接方」——实际已被清仓（快照中消失）；② 把 006609 凭记忆说成「90 天滚动持有」（实为无锁定），属性从 016748 串扰（撞名陷阱在记忆里是 🚨 级条目却没回查）。两条同根＝用二手信息（流水注释/记忆）替代一手信息（快照字段/持仓存在性），且都发生在「很确定」的陈述里。判据：资金流向终审证据＝持仓快照（出现/消失）；类型/锁定/费率陈述＝先读 name/type_info 字段（3 秒）｜死路：只读流水注释推断流向；凭记忆陈述基金属性（「知道坑」≠「避坑」）｜来源：0928 流水对账两次误读（用户各纠错一次）｜计数：1｜状态：resolved

• 2026-09-17｜[LRN-20260917-004]｜场景：cross（「同桶 ≠ 同类」跨任务复发，计数 1→2）｜经验：分类桶相同 ≠ 风险同类——下单前看实际资产占比，不看分类标签。首次（LRN-20260917-002）：QDII 桶内美股股票 vs 美元债，波动 23.68% vs 3.35%（差 7 倍）、相关性仅 +0.209、同向 51.0%。复发（本次）：bond 桶内纯债 vs 二级债基，波动 0.61% vs 9.16%（差 15 倍）。两次都因"只看桶名"而险些误判 ⇒ 已具备升格条件（跨 2 任务复发），待提纯升格进 SKILL.md 正文（第 2 步"穿透校验"即为本次落地形态）｜死路：用桶名代表风险等级｜来源：美元货基遴选 + 加息对债基影响｜计数：2｜状态：monitoring（待第三次复现或用户确认后升格正文）

• 2026-09-30｜场景：进化（RSI 批次 P2）｜v2.9.0 → v2.9.1：补建 evals/prompts.md 触发用例套件（3 正向：持仓分析/货基轮动/记账录入；3 near-miss：债基筛选→ray-fund-screener、目标倒推→ray-goal-planner、方向发现→ray-market-scan）。动机：RSI 四阶段 Evaluate 定量化——本 skill 此前无 evals，优化后回归只能靠"章节完整性对比"定性确认；套件与 fund-screener/market-scan/goal-planner 的路由边界对齐（near-miss 全部指向六层链路的相邻层）。基线建档，下次优化后按 ray-skill-evolve Step 5.6「evals 定量回归」重跑出 delta｜状态：resolved