zeberg-salomon-rotator

<essential_principles>

Zeberg–Salomon 模型將市場簡化為兩種狀態：

• RISK_ON: 持有股票（SPY），景氣擴張期
• RISK_OFF: 持有長債（TLT），景氣收縮期

切換邏輯基於「領先指標先轉弱，同時指標後確認」的景氣循環規律。

合成方式：

1. 各序列做 transform（yoy/mom/diff）
2. 統一方向（direction +1/-1）
3. Rolling z-score 標準化
4. EMA 平滑
5. 加權合成

Iceberg Event: LeadingIndex < iceberg_threshold
  → 預警：景氣開始轉弱
  → 搭配「領先指標下降」+ 可選「市場亢奮」濾鏡

Sinking Event: CoincidentIndex < sinking_threshold
  → 確認：實體經濟收縮
  → 通常在 Iceberg 之後數月發生

狀態機邏輯：

• RISK_ON → RISK_OFF：Iceberg 連續確認 + 斜率為負
• RISK_OFF → RISK_ON：領先指標回升超過 (threshold + hysteresis)

本 skill 使用無需 API key 的資料來源：

• FRED CSV: https://fred.stlouisfed.org/graph/fredgraph.csv?id={SERIES_ID}
• Yahoo Finance: yfinance 套件抓取 SPY, TLT, VIX

腳本位於 scripts/ 目錄，可直接執行。

</essential_principles>

1. 建構指標：從 FRED 數據合成 LeadingIndex 與 CoincidentIndex
2. 偵測事件：識別「冰山」（領先轉弱）與「下沉」（同時確認）
3. 切換訊號：產生 RISK_ON ↔ RISK_OFF 切換事件
4. 回測績效：計算累積報酬、MaxDD、CAGR、與 benchmark 比較

輸出：切換事件清單、指標時間序列、回測摘要、診斷資訊。

<quick_start>

最快的方式：執行預設回測

cd skills/zeberg-salomon-rotator
pip install pandas numpy yfinance pandas-datareader  # 首次使用
python scripts/rotator.py --quick

輸出範例：

{
  "state": "RISK_ON",
  "latest_indices": {"LeadingIndex": 0.41, "CoincidentIndex": 0.22},
  "iceberg_event": false,
  "sinking_event": false,
  "last_switch": {"date": "2023-06-30", "action": "EXIT_LONG_BOND_ENTER_EQUITY"}
}

完整回測：

python scripts/rotator.py --start 2000-01-01 --end 2026-01-01 --output result.json

</quick_start>

1. 快速檢查 – 查看目前的景氣狀態與最新指標
2. 完整回測 – 執行完整的歷史回測與績效分析
3. 視覺化圖表 – 生成多面板回測結果圖表
4. 監控模式 – 設定持續監控與切換警報
5. 方法論學習 – 了解 Zeberg-Salomon 模型的邏輯

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

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

<directory_structure>

zeberg-salomon-rotator/
├── SKILL.md                           # 本文件（路由器）
├── skill.yaml                         # 前端展示元數據
├── manifest.json                      # 技能元數據
├── workflows/
│   ├── backtest.md                    # 完整回測工作流
│   ├── visualize.md                   # 視覺化工作流
│   ├── monitor.md                     # 持續監控工作流
│   └── analyze.md                     # 深度分析工作流
├── references/
│   ├── data-sources.md                # FRED 系列代碼與資料來源
│   ├── methodology.md                 # Zeberg-Salomon 方法論解析
│   └── input-schema.md                # 完整輸入參數定義
├── templates/
│   ├── output-json.md                 # JSON 輸出模板
│   └── output-markdown.md             # Markdown 報告模板
└── scripts/
    ├── rotator.py                     # 主輪動腳本
    ├── visualize.py                   # 視覺化繪圖工具
    └── fetch_data.py                  # 數據抓取工具

</directory_structure>

<reference_index>

方法論: references/methodology.md

• Zeberg-Salomon 模型概念
• 冰山/下沉事件定義
• 兩態切換邏輯

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

• FRED 系列代碼（領先/同時）
• Yahoo Finance 資產代碼
• 數據頻率與對齊

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

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

</reference_index>

<workflows_index>

<templates_index>

<scripts_index>

<input_schema_summary>

核心參數

門檻參數

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

</input_schema_summary>

<output_schema_summary>

{
  "skill": "zeberg-salomon-rotator",
  "as_of": "2026-01-14",
  "state": "RISK_ON",
  "latest_indices": {
    "LeadingIndex": 0.41,
    "CoincidentIndex": 0.22,
    "iceberg_event": false,
    "sinking_event": false
  },
  "switch_events": [...],
  "backtest_summary": {
    "cagr": 0.123,
    "max_drawdown": -0.27,
    "turnovers": 10
  }
}

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

<success_criteria> 執行成功時應產出：

• 當前狀態（RISK_ON 或 RISK_OFF）
• LeadingIndex 與 CoincidentIndex 數值
• 冰山/下沉事件判定
• 切換事件清單（含日期、原因）
• 回測績效摘要（CAGR, MaxDD, 換手次數）
• 與 benchmark 比較（買入持有、60/40）
• 診斷資訊（各指標貢獻）
• 視覺化圖表（可選，輸出至 output/ 目錄） </success_criteria>