[research/design] 帳戶績效衡量的終局:TWR(對大盤) + IRR(實際報酬) — 交易-only 近似的盲點與現金流分離需求

[atomchung]

來源

2026-07-08 owner 與 Claude 對 #37「帳戶 vs 大盤數字版」的設計討論。owner 拍板:近期只用交易紀錄處理(不要求每期報現金),整體 IRR/TWR 另開此 issue 討論。

問題:要正確回答「我選股 vs 大盤 / 我的錢實際賺多少」,一行 NAV 永遠不夠

復盤卡目前有市場背景(#145:SPY/QQQ/VIX 漲跌)但沒有帳戶績效的數字對比。SKILL.md line 150 現行契約明禁「別自己算一個你 vs SPY 的百分比」(需要每週市值序列)。

兩個不同的問題,兩個標準答案

問題	衡量	剔除什麼
我選股/策略有沒有贏大盤?	TWR(時間加權)	剔除「何時、存多少錢」→ 才能公平對 SPY
我實際的錢賺了多少?(IRR)	IRR / MWR(金額加權)	反而計入現金流時機——漲前加碼則 IRR > TWR

兩者都對、回答不同問題。#37 原始意圖(「選錯股 vs 大盤跌」)要 TWR vs SPY;owner 另問的「最終 IRR」是第二根柱子。

共同的關鍵障礙:交易 ≠ 現金流

• 買股票不是現金流——內部搬家(現金→股票,NAV 不變)。
• 只有存款/提款(外部錢進出)才需要剔除。
• 交易 CSV 只有交易、沒有存提款 → 引擎分不出「NAV 多 $20k」是選股賺的還是存錢進來的。
• ⇒ 數學上,正確衡量必須能分離外部現金流,無法從交易 CSV 單獨得到。

兩條路線

A. 交易-only 近似(owner 選的近期路線,零額外摩擦)

只算「前後兩期都持有的部位的純價格變化」vs SPY 同期。

• ✅ 不需 owner 每期報現金。
• ⚠️ 已知盲點(owner 親自指出):新部署的現金,當期漲跌被漏掉(要到下一期變「沿用部位」才算)。持續多期部署現金 → 系統性少算「剛買的」。適合少加減碼的人。

B. Proper TWR + IRR(終局,需要現金流)

帳本(#131 ledger)的 append-snapshot 已支援 --cash。若每期宣告「持倉 + 現金」全額,外部現金流即可推導:
```
外部現金流 = 期末現金 − 期初現金 + 買入總額 − 賣出總額 − 股息
```
有了每期 (NAV, 外部現金流, 日期):

• Modified Dietz(業界標準近似 TWR,不需每日 NAV) → 當期報酬,正確處理 A 的盲點
• 鏈接多期 → 累積 TWR vs SPY
• 有日期的現金流序列 → 直接解 IRR
• ⚠️ 成本:owner 每期多報一個現金/存提款數字(產品摩擦 vs 精度的取捨)。

待討論 / 決策點

1. 近期 A 版要不要做(還是等 B)?owner 傾向「先只用交易紀錄」→ A 的盲點可接受?
2. B 版的現金宣告怎麼降摩擦(對帳單多半有現金餘額欄,Step 0 標準化可順帶抓)?
3. IRR 呈現在卡的哪裡、跟 α/β(已有的風險調整超額)怎麼分工不重複?
4. 這是 research Part 2「NAV 快照需求」的正式落點。

關聯

• [Phase 2] 市場背景自動注入：SPY/QQQ/VIX 週漲跌進復盤卡 #37(市場背景/數字版,近期範圍)— 本 issue 是其「數字版」的正確終局
• 現有 α/β(dim_alpha_beta)已是風險調整的市場相對報酬,IRR/TWR 是現金流視角的補充,非取代

[atomchung]

2026-07-10 討論沉澱(owner 拍板,下個 session 從這接手)

現況修正(讀碼後,兩處修正本 issue 原假設)

1. A 路線「已經做了」:_port_daily_returns(trade_recap.py)是日尺度鏈式重建(昨日持股×今日價,排除當日現金流)——新買入只漏「買入當天」,次日即進投組,不是 issue 原文想像的「整期漏掉」。持倉視角 TWR 骨架已活在 α 面板(port_tot/bench_tot/excess),剩的是呈現問題。
2. IRR 不需要等現金流宣告:「已部署資金 XIRR」= 每筆買入(−)/賣出(+)/期末持倉市值(終值),交易 CSV 即完整序列,零新摩擦。它答「投進股市的錢金額加權滾多快」;帳戶級 IRR(含閒置現金)才需要 B 路線。

Owner 拍板(2026-07-10)

• ✅ XIRR 加入,分季拆,取年化報酬率。分季:季初已持倉=該季期初虛擬投入(用季初市值,引擎從價格序列重建,用戶零輸入)。
• ✅ TWR vs SPY 上卡:「直接說拿引擎算的數字就行,一樣要避免過度膨脹 skills」——SKILL 契約從「不准出現你 vs SPY」改為「只准照抄引擎數字,不准 Claude 自己算」;SKILL 主檔不長 prose(對齊 [design·P1] SKILL.md 漸進披露:399 行 ~25k tokens 全量載入,超官方 Level-2 建議 5 倍 → dispatcher + per-mode 子檔案(card-spec 模式推廣) #149/[design] 卡片呈現一致性完全依賴執行當下的 self-check 自律,沒有機械式強制 #82 原則,判定與數字全在 engine)。
• 縫 A(踏空/躲跌不進持倉日對比):上卡同時配 honesty_ledger 揭露「對比僅涵蓋持倉日」(owner 未反對,照建議走)。
• 縫 B 升級為正確性 bug [bug·正確性] total_pnl 混用兩套成本基礎:已實現走 FIFO、未實現剩餘走平均成本 — 部分賣出+分批不同價時加總偏離真值 #162(realized FIFO + unrealized avg cost 混基礎,攤平後部分賣出加總偏真值)→ 已修,PR fix(engine): 未實現改 FIFO 剩餘 lots,與 realized 同成本基礎 — 攤平後部分賣出 total_pnl 不再偏離真值 (closes #162) #163。

三柱分工(呈現設計錨點)

α(統計顯著才用能力語氣)答「技巧 vs 運氣」/ XIRR 答「錢實際滾多快」(含加減碼時機)/ TWR-vs-SPY 答「該不該乾脆買指數」。三柱互相解釋,單獨上任一柱都會被誤讀。

明確不做(本輪)

B 路線(帳戶級 IRR/Modified Dietz,需每期現金宣告)繼續躺——A+已部署 XIRR 對資金常駐場內者已覆蓋 ~90%;append-snapshot --cash 前置仍在,哪天要做隨時接。

規格 issue 另開(見下一則 comment 連結)。

[atomchung]

2026-07-12 owner 拍板：啟動 B 路線（帳戶級、含現金）

回答本 issue「待討論/決策點 1」：A 路線已由 #164 落地（續行），B 路線正式啟動（解除原標記的「另議」）。

觸發：2026-07-11 同週雙跑對比（inote weekly-review vs fomo-kernel 卡，同源 CSV）暴露三個現金相關盲區——① 兩系統都答不出「本週組合賺多少 / 該不該乾脆買指數」；② fomo-kernel 看不見新入金 $15,582 該不該部署（engine 在 trade_recap.py:117 把所有非交易 row 丟棄，零現金餘額概念）；③ AI 曝險/分散度缺正確分母。在「現金做到哪層」的分叉上，owner 選 帳戶級全套。

落地規格 = #171（分階段 PR：現金地基 → Modified Dietz TWR → 帳戶級 IRR → cash drag）。前置基礎設施齊備：ledger append-snapshot --cash 已支援現金錨點、#132 多市場幣別傳導已 merged、#163 成本基礎歸一已合。

認知修正：本 issue 已定的 A 路線 XIRR 是「已部署資金」口徑、不含現金；帳戶級 IRR（含閒置現金）是 B 路線的第二根柱子，兩者卡上並存、命名區分（閒置現金越多 → 帳戶 IRR 應低於已部署 XIRR，這個分岔本身是訊號 = cash drag）。