Detect Us Equity Valuation Percentile Extreme

將不同單位的估值指標（PE、PB、CAPE 等）統一成「0-100 的歷史分位數」：

• 分位數 = 100 × (歷史中 ≤ 當前值的樣本數 / 總樣本數)
• 例：CAPE 位於歷史第 98 分位 → 過去 130 年只有 2% 的時間比現在更貴
• 統一單位後，可跨指標合成「綜合估值分位數」

合成公式：composite_percentile = 加權平均(各指標分位數)

支援三種合成方式：

重要：各指標可能有不同歷史長度，預設使用「各自歷史」計算分位數再合成。

if composite_percentile >= extreme_threshold (預設 95):
    → 判定「歷史極端高估」
    → 觸發風險解讀流程

歷史類比事件識別：

1. 找出合成分位數超過門檻的峰值
2. 用 episode_min_gap_days 去重（預設 10 年內只保留最高點）
3. 輸出：1929、1965、1999、2021、當前...

「估值極端高」≠「明天崩盤」，但歷史特徵是：

• 風險分布不對稱：下跌尾巴變厚
• 未來中期報酬壓縮：估值均值回歸壓低長期報酬上限
• 波動先升後跌：事件後 6-12 月波動率通常上升

輸出事後統計：

• 未來 180/365/1095 天報酬分布
• 最大回撤中位數與尾部風險
• 波動率變化機率

本 skill 使用公開替代資料，非彭博原始數據：

• Shiller CAPE: Robert Shiller 公開資料集（可回溯至 1871 年）
• 市值/GDP: FRED 公開數據（可回溯至 1950 年代）
• PE/PB/PS: 公開金融資料（歷史較短，約 30-50 年）

必須揭露：

• 各指標可得期間不同
• 合成分位數為「近似重建」，非精確複製

1. 收集估值指標：從公開數據源取得 PE、CAPE、PB、PS、市值/GDP 等
2. 計算分位數：將各指標轉換為歷史分位數（0-100）
3. 合成總分：加權平均（或中位數）得到綜合估值分位數
4. 判定極端：若總分 ≥ 門檻（預設 95），觸發極端高估警報
5. 歷史類比：找出歷史上的類似事件（1929、1965、1999 等）
6. 事後統計：計算這些事件後的報酬、回撤、波動變化

輸出：當前狀態、各指標分位數、歷史類比事件、風險解讀。

最快的方式：執行視覺化分析

cd skills/detect-us-equity-valuation-percentile-extreme
pip install pandas numpy yfinance requests matplotlib openpyxl xlrd  # 首次使用
python scripts/visualize_valuation.py -o output

輸出：

• output/us_valuation_percentile_YYYY-MM-DD.png - 歷史走勢圖（類似 @ekwufinance 風格）
• output/us_valuation_breakdown_YYYY-MM-DD.png - 各指標分位數分解圖
• output/us_valuation_analysis_YYYY-MM-DD.json - JSON 結果

圖表特色：

• 多指標合成分位數的歷史走勢（非單一時間點）
• 歷史峰值標記：1929、1965、1999、2021
• S&P 500 指數疊加（對數刻度）
• 當前「新高」標註

快速檢查（純 JSON）：

python scripts/valuation_percentile.py --quick

完整分析：

python scripts/valuation_percentile.py \
  --as_of_date 2026-01-21 \
  --universe "^GSPC" \
  --metrics "cape,mktcap_to_gdp,trailing_pe,pb" \
  --output result.json

1. 視覺化分析（推薦） - 生成歷史走勢圖表，標記歷史峰值
2. 快速檢查 - 查看目前的估值分位數與極端狀態
3. 完整分析 - 執行完整的歷史分位數分析與風險解讀
4. 歷史類比 - 深入分析歷史極端高估事件與事後表現
5. 方法論學習 - 了解估值分位數模型的邏輯
6. 自訂參數 - 指定估值指標、門檻、合成方式等

請選擇或直接提供分析參數。

路由後，閱讀對應文件並執行。

方法論: references/methodology.md

• 分位數標準化原理
• 多指標合成邏輯
• 極端偵測與歷史類比

資料來源: references/data-sources.md

• Shiller CAPE 資料集
• FRED 系列代碼
• 公開替代資料說明

估值指標: references/valuation-metrics.md

• PE、Forward PE、CAPE 定義
• PB、PS、EV/EBITDA 定義
• Q Ratio、市值/GDP 定義

輸入參數: references/input-schema.md

• 完整參數定義
• 預設值與建議範圍

核心參數

門檻參數

完整參數定義見 references/input-schema.md。

完整輸出結構見 templates/output-json.md。

• 當前綜合估值分位數（0-100）
• 各指標個別分位數
• 極端高估判定（是/否）
• 歷史類比事件清單（日期、分位數）
• 事後統計（報酬、回撤、波動）
• 資料品質說明（各指標可得期間）
• 風險解讀框架（可選，輸出至 Markdown）

視覺化輸出（使用 visualize_valuation.py）：

• 歷史走勢圖（us_valuation_percentile_YYYY-MM-DD.png）
  • 多指標合成分位數時間序列
  • 歷史峰值標記（1929、1965、1999、2021）
  • S&P 500 指數疊加（對數刻度）
  • 當前位置標註
• 指標分解圖（us_valuation_breakdown_YYYY-MM-DD.png）
  • 各指標分位數橫向條形圖
  • 極端門檻參考線
• JSON 結果檔（us_valuation_analysis_YYYY-MM-DD.json）