GARCH 方法 — 波動率預測 + 部位規模設定
此技能回答了散戶從不問、但每個基金每天都在問的問題：多少？
它不預測方向。GARCH 預測的是波動的幅度——明天波動可能有多劇烈，而非走勢方向。在呈現結果時請務必向使用者說明這點。
三大工具
所有指令碼都位於 scripts/ 目錄下，並使用 uv run 執行（相依性透過內嵌 metadata 自動解析——無需 pip-install）。
1. garch_forecast.py — 預測
Walk-forward GARCH(1,1)，無前瞻偏差（每 21 天在擴張視窗上重新估計參數；在重新擬合之間僅使用過去資料進行遞迴滾動）。
uv run scripts/garch_forecast.py --csv prices.csv --json
uv run scripts/garch_forecast.py --ticker BTC-USD --json
輸出：1 日前瞻波動率預測（每日與年化）、與過去一年相比的波動率百分位數、狀態（平靜 / 正常 / 風暴）。
2. vol_target.py — 規模
核心概念：size = target_vol / forecast_vol，限制在 [0.25x, 2.0x]。
uv run scripts/vol_target.py --csv prices.csv --target-vol 15 --json
輸出：部位規模乘數。「執行基準的 0.6 倍」——這就是答案。
3. compare.py — 誠實的測試
以固定規模與波動率目標化兩種方式執行相同的訊號，並排顯示兩者的權益曲線與統計數據。內建 EMA 9/21 交叉示範範例；可透過 --signals mine.csv 接受任何策略（欄位：date, signal 為 {-1,0,1}）。
u run scripts/compare.py --csv prices.csv --target-vol 58 --chart equity.png --json
uv run scripts/compare.py --csv prices.csv --signals mine.csv
輸出：年化報酬率、年化波動率、夏普比率、最大回撤、最差月份、最終權益——兩種版本皆有——並附帶標示風暴狀態的權益曲線圖。
JSON 合約
每個指令碼都支援 --json。核心輸出格式：
{
"as_of": "2026-05-23",
"forecast_vol_annualized_pct": 41.2,
"vol_percentile_1y": 78.0,
"regime": "storm",
"position_size_multiplier": 0.6,
"note": "GARCH forecasts magnitude (volatility), not direction."
}
三種組合模式
A. 部位規模層 — 套接在任何既有策略之上。你的策略決定是否進場；此技能決定進多少。將策略的訊號乘以 position_size_multiplier 即可。
B. 風險調節開關 — 獨立啟動的緊急停止機制。若 regime == "storm"，則無論訊號為何，所有曝險都削減至乘數水準。適用於任何管理部位的 agent。
C. 比較框架 — 在信任任何策略之前，先透過 compare.py 執行，並檢查波動率目標化是否改善了其夏普比率/回撤。若部位規模設定無幫助，則該策略的優勢可能過弱，無法在真實條件下存活。
可與方向性技能（例如馬可夫風格的多頭/空頭分類器）完美組合：它們的輸出回答哪個方向，此技能回答多少。將兩者相乘即可。
預設值與慣例
- 加密貨幣：
--periods-per-year 365（預設）。股票：--periods-per-year 252。 - 目標波動率：15% 是合理的保守預設值。若要與無槓桿策略進行風險匹配比較，請將目標波動率設定為約等於該策略本身的實際波動率。
- 資料：yfinance ticker（需網路連線）或任何含有日期與收盤價欄位的 CSV——可無縫整合到使用者既有的任何資料管道中。
- 最低歷史資料：進行首次預測前約需 510 筆每日觀測值。
誠實守則（不可協商）
- 切勿將 GARCH 輸出呈現為方向性判斷。
- 報告比較結果時，絕不隱藏回撤或最差月份的數字。
- 若波動率目標化並未改善使用者的策略，請明確告知——這個結果同樣具有價值。