| name | forecast-sector-relative-return-from-yield-spread |
| description | 用美債殖利率曲線利差（如 2Y-10Y）建立「領先關係」，推估未來一段時間內成長股（Nasdaq 100）相對防禦股（Healthcare/XLV）的相對績效方向與幅度。 |
<essential_principles>
**領先落後關係定義**
美國公債利差（Yield Spread）作為領先指標：
spread_t = short_yield_t - long_yield_t
= US02Y_t - US10Y_t
spread 越高：短端相對更高（曲線更倒掛/更緊）
spread 越低（或從負回到 0、轉正）：曲線「回正/變陡」
此 spread 被認為領先反映：
- 經濟週期預期（倒掛 → 衰退預期）
- 風險偏好轉換（曲線變陡 → 風險偏好回升）
**相對報酬定義**
相對強弱比率（Ratio）：
ratio_t = risk_asset_t / defensive_asset_t
= QQQ_t / XLV_t
ratio 上升：成長股（Nasdaq）相對更強
ratio 下降：防禦股（Healthcare）相對更強（XLV 跑贏）
預測目標為「未來 H 個月的對數相對報酬」：
future_rel_return = log(ratio(t+H) / ratio(t))
正值 → Nasdaq 跑贏，負值 → XLV 跑贏
**「2 Years in Advance」的真正含義**
圖表的時間對齊邏輯：
- 把 spread 往前平移 lead_months 個月
- 目標是檢查：spread(t) 是否能解釋 ratio(t + H)
工程化寫法：
X = spread(t)
Y = future_rel_return(t, H) = log(ratio(t+H) / ratio(t))
然後做相關性/迴歸/交叉相關掃描來找「最佳領先期」。
避免直接用 ratio 水平做迴歸（有趨勢/非平穩問題），改用對數報酬。
**領先關係驗證框架**
需回答三件事：
-
是否真的存在穩定領先關係？
- 掃描多個 lead（6, 12, 18, 24, 30 個月）
- 看哪個 lead 下 corr(spread, future_rel_return) 最穩、顯著
- 跨子樣本驗證（前半段 vs 後半段）
-
目前情境對應的預測方向
- 最近 spread 水準、變化率
- 模型預測 E[future_rel_return]
- 分位數區間（如 80% 信心區間）
-
把預測翻譯成直覺語句
- 由 future_rel_return 轉回百分比：
exp(future_rel_return) - 1
- 「未來 24 個月 XLV 相對 QQQ 勝率 X%、中位數報酬 Y%」
**數據對齊原則**
- 頻率選擇：週頻（weekly）降低雜訊，建議 1wk
- 平滑視窗：可選 13 週或 26 週移動平均
- 回測長度：至少涵蓋 1-2 次完整景氣循環（如 2007-present）
殖利率來源：FRED（DGS2, DGS10）
資產價格來源：Yahoo Finance（QQQ, XLV）
</essential_principles>
實作「美國公債利差 → 板塊相對報酬」領先關係分析：
- 數據整合：取得殖利率（FRED）與資產價格（yfinance）
- 利差計算：計算 spread = short_yield - long_yield
- 相對報酬計算：計算 future_rel_return = log(ratio(t+H) / ratio(t))
- 領先關係驗證：掃描多個 lead 找最佳相關性與穩定性
- 情境預測：基於當前 spread 產出未來相對報酬預測區間
- 輸出報告：驗證結論、預測方向、風險提示
輸出：領先關係驗證、當前預測、區間估計、歷史類比、風險提示。
<quick_start>
最快的方式：執行預設情境分析
cd skills/forecast-sector-relative-return-from-yield-spread
pip install pandas numpy yfinance matplotlib statsmodels requests
python scripts/spread_forecaster.py --quick
完整分析（含領先掃描與穩定性驗證）
python scripts/spread_forecaster.py \
--risk-ticker QQQ \
--defensive-ticker XLV \
--lead-months 24 \
--lookback-years 12 \
--output result.json
生成 Bloomberg 風格視覺化圖表
python scripts/plot_bloomberg_style.py --quick --output output/yield_spread_forecast_$(date +%Y-%m-%d).png
完整版圖表（自訂參數）
python scripts/plot_bloomberg_style.py \
--lookback-years 18 \
--lead-months 24 \
--risk-ticker QQQ \
--defensive-ticker XLV \
--output output/yield_spread_analysis.png
輸出範例：
{
"skill": "forecast_sector_relative_return_from_yield_spread",
"signal_name": "US02Y_minus_US10Y_leads_QQQ_over_XLV",
"lead_months": 24,
"current_spread": -0.35,
"model": {
"type": "lagged_regression",
"alpha": 0.02,
"beta": -0.45,
"corr_x_y": -0.32
},
"forecast": {
"future_24m_relative_return_pct": -0.077,
"interval_pct_80": [-0.22, 0.04],
"interpretation": "若此關係維持，未來24個月QQQ相對XLV期望報酬為-7.7%，XLV較可能跑贏。"
}
}
</quick_start>
需要進行什麼操作？
- 快速分析 - 使用預設參數（QQQ/XLV, 24 個月領先）計算當前預測
- 完整分析 - 自訂參數進行領先關係驗證與情境預測
- 領先掃描 - 掃描多個領先期（6-30 個月）找最佳相關性
- 視覺化圖表 - 生成利差與相對報酬對齊圖
- 穩定性驗證 - 檢查領先關係在不同子樣本的一致性
- 方法論學習 - 了解領先關係邏輯與計算方式
請選擇或直接提供分析參數。
| Response | Action |
|--------------------------------|------------------------------------------------------------------------|
| 1, "快速", "quick", "分析" | 執行 `python scripts/spread_forecaster.py --quick` |
| 2, "完整", "full", "自訂" | 閱讀 `workflows/analyze.md` 並執行 |
| 3, "掃描", "scan", "領先" | 閱讀 `workflows/analyze.md` 並聚焦 lead_scan |
| 4, "圖表", "chart", "視覺化" | 執行 `python scripts/plot_bloomberg_style.py --quick --output output/` |
| 5, "驗證", "穩定", "stability" | 閱讀 `workflows/analyze.md` 並聚焦穩定性驗證 |
| 6, "學習", "方法論", "why" | 閱讀 `references/methodology.md` |
| 提供參數 (如 ticker, lead) | 閱讀 `workflows/analyze.md` 並使用參數執行 |
路由後，閱讀對應文件並執行。
<directory_structure>
forecast-sector-relative-return-from-yield-spread/
├── SKILL.md # 本文件（路由器）
├── skill.yaml # 前端展示元數據
├── manifest.json # 技能元數據
├── workflows/
│ ├── analyze.md # 完整分析工作流
│ └── data-research.md # 數據源研究與替代方案
├── references/
│ ├── methodology.md # 方法論與計算邏輯
│ ├── input-schema.md # 完整輸入參數定義
│ └── data-sources.md # 數據來源與獲取方式
├── templates/
│ ├── output-json.md # JSON 輸出模板
│ └── output-markdown.md # Markdown 報告模板
├── scripts/
│ ├── spread_forecaster.py # 主計算腳本
│ ├── plot_bloomberg_style.py # Bloomberg 風格視覺化（推薦）
│ └── spread_plotter.py # 基本版圖表腳本（備用）
└── examples/
└── sample-output.json # 範例輸出
</directory_structure>
<reference_index>
方法論: references/methodology.md
- 領先落後關係定義
- 相對報酬計算
- 迴歸模型設定
- 區間估計方法
- 穩定性驗證
資料來源: references/data-sources.md
- 殖利率代理（FRED DGS2/DGS10）
- 資產價格代理（QQQ/XLV）
- 數據對齊原則
輸入參數: references/input-schema.md
</reference_index>
<workflows_index>
| Workflow | Purpose | 使用時機 |
|---|
| analyze.md | 完整情境分析 | 需要自訂參數驗證領先關係與預測 |
| data-research.md | 數據源研究 | 了解如何獲取或替代殖利率/資產數據 |
| </workflows_index> | | |
<templates_index>
| Template | Purpose |
|---|
| output-json.md | JSON 輸出結構定義 |
| output-markdown.md | Markdown 報告模板 |
| </templates_index> | |
<scripts_index>
| Script | Command | Purpose |
|---|
| spread_forecaster.py | --quick | 快速分析 QQQ/XLV, 24m lead |
| spread_forecaster.py | --lead-months 12 --lookback-years 15 | 自訂領先期與回測長度 |
| spread_forecaster.py | --lead-scan --scan-range 6,12,18,24,30,36 | 領先期掃描 |
| plot_bloomberg_style.py | --quick --output output/chart.png | Bloomberg 風格快速圖表 |
| plot_bloomberg_style.py | --lookback-years 18 --lead-months 24 | 完整版圖表（含領先掃描+穩定性） |
| spread_plotter.py | --quick --output-dir output/ | 基本版圖表（備用） |
| </scripts_index> | | |
<input_schema_summary>
核心參數
| 參數 | 類型 | 預設值 | 說明 |
|---|
| risk_ticker | string | QQQ | 代表成長股的標的 |
| defensive_ticker | string | XLV | 代表防禦股的標的 |
| short_tenor | string | 2Y | 短端殖利率期限 |
| long_tenor | string | 10Y | 長端殖利率期限 |
| lead_months | int | 24 | 領先期（月） |
| lookback_years | int | 12 | 回測/估計歷史年數 |
進階參數
| 參數 | 類型 | 預設值 | 說明 |
|---|
| freq | string | weekly | 資料頻率（daily/weekly/monthly） |
| smoothing_window | int | 13 | 平滑視窗（週數） |
| return_horizon_months | int | 24 | 預測的相對報酬視窗 |
| model_type | string | lagged_regression | 模型類型 |
| confidence_level | float | 0.80 | 區間估計信心水準 |
完整參數定義見 references/input-schema.md。
</input_schema_summary>
<output_schema_summary>
{
"skill": "forecast_sector_relative_return_from_yield_spread",
"inputs": {
"risk_ticker": "QQQ",
"defensive_ticker": "XLV",
"lead_months": 24,
"lookback_years": 18
},
"signal_name": "DGS2_minus_DGS10_leads_QQQ_over_XLV",
"current_state": {
"spread": -0.61,
"spread_percentile": 61.1,
"spread_trend": "steepening"
},
"model": {
"type": "lagged_regression",
"coefficients": { "alpha": 0.19, "beta": 0.087 },
"fit_quality": {
"corr_x_y": 0.484,
"r_squared": 0.234,
"notes": "正 beta 意味 spread 越低（曲線正常）→ 未來 QQQ 相對 XLV 越強"
}
},
"forecast": {
"horizon_months": 24,
"future_relative_return_pct": 0.148,
"interval_pct_80": [-0.05, 0.36],
"expected_winner": "QQQ"
},
"diagnostics": {
"lead_scan": {
"best_lead_months": 36,
"correlation_by_lead": {"6": 0.233, "12": 0.360, "18": 0.405, "24": 0.484, "30": 0.502, "36": 0.509}
},
"stability_checks": {
"first_half_corr": -0.087,
"second_half_corr": 0.663,
"consistency": "low"
}
},
"notes": [
"領先關係反映的是『歷史統計規律』，不保證未來成立。",
"子樣本一致性低：前半段（2007-2015）為負相關，後半段（2015-2024）為正相關。",
"這意味著此領先關係可能只是 2015 後 QE 時代的特有現象。",
"建議搭配：景氣指標、估值分位、資金流向做交叉驗證。"
]
}
完整輸出結構見 templates/output-json.md。
重要發現（2026-01-27 驗證結果）：
- 領先關係存在，但 子樣本一致性低（前半段負相關 vs 後半段正相關）
- 最佳領先期為 30-36 個月（非 24 個月），但 24 個月也有 0.484 的相關性
- R² = 23.4%，spread 僅解釋約四分之一的相對報酬變異
</output_schema_summary>
<success_criteria>
執行成功時應產出：
