zeberg-salomon-rotator

name	zeberg-salomon-rotator
description	用領先和同時指標建構景氣模型，並判讀兩種景氣階段：景氣擴張期 (Risk-On) 與景氣收縮期 (Risk-Off)，並根據理論給出 "撞冰山" 與 "下沉" 事件訊號。

<essential_principles>

**兩態切換模型核心**

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

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

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

**領先 vs 同時指標**

類型	作用	典型成分	領先時間
Leading	預警	殖利率曲線、新訂單、房市許可	6-12 月
Coincident	確認	就業、工業生產、實質收入	同步

合成方式：

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

**冰山事件 vs 下沉事件**

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>

實作 Zeberg–Salomon 兩態輪動策略：

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 模型的邏輯

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

| Response | Action | |-------------------------------|---------------------------------------------| | 1, "快速", "quick", "check" | 執行 `python scripts/rotator.py --quick` | | 2, "回測", "backtest", "full" | 閱讀 `workflows/backtest.md` 並執行 | | 3, "視覺化", "chart", "plot" | 閱讀 `workflows/visualize.md` 並執行 | | 4, "監控", "monitor", "alert" | 閱讀 `workflows/monitor.md` 並執行 | | 5, "學習", "方法論", "why" | 閱讀 `references/methodology.md` | | 提供參數 (如日期範圍) | 閱讀 `workflows/backtest.md` 並使用參數執行 |

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

<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>

Workflow	Purpose	使用時機
backtest.md	完整歷史回測	需要績效分析時
visualize.md	生成視覺化圖表	需要圖表展示時
monitor.md	持續監控狀態	日常監控或警報
analyze.md	深度指標分析	理解當前市場狀態
</workflows_index>

<templates_index>

Template	Purpose
output-json.md	JSON 輸出結構定義
output-markdown.md	Markdown 報告模板
</templates_index>

<scripts_index>

Script	Command	Purpose
rotator.py	--quick	快速檢查當前狀態
rotator.py	--start DATE --end DATE	完整回測
visualize.py	-i result.json -o chart.png	生成視覺化圖表
fetch_data.py	--series T10Y3M,PAYEMS	抓取 FRED 資料
</scripts_index>

<input_schema_summary>

核心參數

參數	類型	預設值	說明
start_date	string	2000-01-01	回測起始日
end_date	string	today	回測結束日
freq	string	M	頻率（M=月）
equity_proxy	string	SPY	風險資產代理
bond_proxy	string	TLT	長債代理

門檻參數

參數	類型	預設值	說明
iceberg_threshold	number	-0.3	領先指標門檻
sinking_threshold	number	-0.5	同時指標門檻
confirm_periods	int	2	連續確認期數
hysteresis	number	0.15	進出場間距

完整參數定義見 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>