analyze-silver-miner-metal-ratio

<essential_principles>

**比率定義與意義**

礦業股/金屬比率（Miner-to-Metal Ratio）：

ratio_t = miner_price_t / metal_price_t

其中：

• miner_price：銀礦股代表（ETF 如 SIL/SILJ，或自建礦業股指數）
• metal_price：白銀價格（期貨 SI=F、現貨 XAGUSD、ETF SLV）

此比率衡量「礦業股相對於金屬本體」的估值水位：

• 比率高：礦業股相對白銀偏貴（可能過度樂觀、槓桿溢價高）
• 比率低：礦業股相對白銀偏便宜（可能被低估、或反映成本/股權稀釋風險）

**分位數解讀邏輯**

使用歷史分位數（Percentile Rank）判斷當前比率位置：

分位數區間	標籤	直覺
≤ 20%	bottom (底部)	礦業股相對白銀歷史上很便宜
20-40%	low (偏低)	礦業股相對估值偏低
40-60%	neutral (中性)	歷史中位區間
60-80%	high (偏高)	礦業股相對估值偏高
≥ 80%	top (頂部)	礦業股相對白銀歷史上很貴

底部區間不等於白銀必漲：可能是礦業股因成本/稀釋被合理定價。

**背離訊號的意義**

當出現「比率低 + 白銀高」的組合：

• 比率處於底部區：礦業股相對白銀偏便宜
• 白銀處於高位：金屬價格已在歷史高檔

此「背離」意味著：

1. 礦業股可能有追趕空間（均值回歸邏輯）
2. 或礦業股正確反映了結構性問題（成本、稀釋、地緣風險）

需結合基本面交叉驗證，而非盲目視為買入訊號。

**情境推演計算**

目標：若比率要回到歷史頂部（或中位），需要什麼條件？

假設當前比率 = 1.14，目標比率（頂部門檻）= 2.45：

情境 A：白銀不變，礦業股需漲多少？

miner_multiplier = target_ratio / current_ratio
                 = 2.45 / 1.14 = 2.15x (需漲 115%)

情境 B：礦業股不變，白銀需跌多少？

metal_multiplier = current_ratio / target_ratio
                 = 1.14 / 2.45 = 0.46 (需跌 54%)

此推演提供「極端情境」的量化參考，非預測。

**數據對齊原則**

• 頻率選擇：長週期訊號建議使用週頻（1wk）或月頻（1mo）
• 平滑視窗：可選 4 週或 3 個月移動平均降低雜訊
• 事件去重：類比事件間隔需 ≥ min_separation_days（如 180 天）

本 skill 使用 yfinance 取得 ETF/期貨數據，預設週頻對齊。

</essential_principles>

實作「銀礦股價 / 銀價比率」分析模型：

1. 數據整合：取得礦業股代理與白銀價格序列
2. 比率計算：計算相對比率並可選平滑
3. 分位數判斷：當前比率在歷史的位置
4. 類比事件：歷史底部區間的事件識別
5. 前瞻驗證：底部事件後白銀的 1/2/3 年表現
6. 情境推演：礦業股需漲多少 / 白銀需跌多少才回到頂部

輸出：當前狀態、歷史類比、情境推演、風險提示。

<quick_start>

最快的方式：執行預設情境分析

cd skills/analyze-silver-miner-metal-ratio
pip install pandas numpy yfinance matplotlib  # 首次使用
python scripts/ratio_analyzer.py --quick

生成視覺化圖表（基本版）

python scripts/ratio_plotter.py --quick --output-dir ../../output

生成完整版圖表（含底部事件、前瞻報酬統計）

python scripts/ratio_plotter.py --comprehensive --start-date 2010-01-01 --output-dir ../../output

圖表輸出路徑：

• 基本版：output/sil_silver_ratio_YYYY-MM-DD.png
• 完整版：output/sil_silver_ratio_comprehensive_YYYY-MM-DD.png

輸出範例：

{
  "skill": "analyze_silver_miner_metal_ratio",
  "current": {
    "ratio": 1.14,
    "ratio_percentile": 18.7,
    "zone": "bottom",
    "bottom_threshold": 1.16,
    "top_threshold": 2.45
  },
  "history_analogs": {
    "bottom_event_dates": ["2010-08-06", "2016-01-29", "2020-03-20"],
    "forward_metal_returns": {
      "252": {"count": 3, "median": 0.42, "win_rate": 1.0}
    }
  },
  "scenarios": {
    "target": "return_to_top",
    "miner_multiplier_if_metal_flat": 2.15,
    "metal_drop_pct_if_miner_flat": 0.54
  }
}

完整情境分析：

python scripts/ratio_analyzer.py \
  --miner-proxy SIL \
  --metal-proxy SI=F \
  --start-date 2008-01-01 \
  --freq 1wk \
  --smoothing-window 4 \
  --bottom-quantile 0.20 \
  --top-quantile 0.80 \
  --output result.json

</quick_start>

需要進行什麼操作？

1. 快速分析 - 使用預設參數（SIL / SI=F）計算當前比率狀態
2. 完整分析 - 自訂參數進行情境分析（可選擇礦業股/金屬代理、分位門檻）
3. 視覺化圖表 - 生成比率走勢圖，標記當前位置與分位數區間
4. 歷史驗證 - 查看底部區間事件的前瞻報酬統計
5. 情境推演 - 計算「回到頂部」需要的礦業股漲幅或白銀跌幅
6. 方法論學習 - 了解比率邏輯與分位數解讀

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

| Response | Action | |-------------------------------|---------------------------------------------------------------------| | 1, "快速", "quick", "分析" | 執行 `python scripts/ratio_analyzer.py --quick` | | 2, "完整", "full", "自訂" | 閱讀 `workflows/analyze.md` 並執行 | | 3, "圖表", "chart", "視覺化" | 執行 `python scripts/ratio_plotter.py --quick --output-dir output/` | | 4, "歷史", "驗證", "backtest" | 閱讀 `workflows/analyze.md` 並聚焦歷史類比 | | 5, "情境", "scenario", "推演" | 閱讀 `workflows/analyze.md` 並聚焦情境推演 | | 6, "學習", "方法論", "why" | 閱讀 `references/methodology.md` | | 提供參數 (如礦業股/金屬代理) | 閱讀 `workflows/analyze.md` 並使用參數執行 |

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

<directory_structure>

analyze-silver-miner-metal-ratio/
├── 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/
│   ├── ratio_analyzer.py              # 主計算腳本
│   └── ratio_plotter.py               # 視覺化圖表腳本
└── examples/
    └── sample-output.json             # 範例輸出

</directory_structure>

<reference_index>

方法論: references/methodology.md

• 比率定義與直覺
• 分位數解讀邏輯
• 背離訊號的意義
• 情境推演數學
• 歷史驗證方法

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

• 礦業股代理（ETF/指數）
• 白銀價格代理
• 數據對齊原則

輸入參數: 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
ratio_analyzer.py	--quick	快速分析 SIL/SI=F
ratio_analyzer.py	--miner-proxy SILJ --freq 1mo	自訂礦業股與頻率
ratio_analyzer.py	--scenario-target return_to_median	回到中位數情境
ratio_plotter.py	--quick --output-dir ../../output	快速生成基本版圖表
ratio_plotter.py	--comprehensive --start-date 2010-01-01 --output-dir ...	完整版圖表（含底部事件、前瞻報酬統計）
</scripts_index>

<input_schema_summary>

核心參數

參數	類型	預設值	說明
miner_proxy	string	SIL	銀礦股代表（ETF/指數代號）
metal_proxy	string	SI=F	白銀價格代表（期貨/現貨/ETF）
start_date	string	10 年前	歷史回溯起點（YYYY-MM-DD）
end_date	string	today	分析終點
freq	string	1wk	取樣頻率（1d/1wk/1mo）

進階參數

參數	類型	預設值	說明
smoothing_window	int	4	比率平滑視窗（週數/月數）
bottom_quantile	float	0.20	底部估值區分位數門檻
top_quantile	float	0.80	頂部估值區分位數門檻
min_separation_days	int	180	類比事件去重間隔
forward_horizons	list	[52, 104, 156]	前瞻期（週數，對應 1/2/3 年）
scenario_target	string	return_to_top	情境目標（return_to_top/median）

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

</input_schema_summary>

<output_schema_summary>

{
  "skill": "analyze_silver_miner_metal_ratio",
  "inputs": {
    "miner_proxy": "SIL",
    "metal_proxy": "SI=F",
    "start_date": "2010-01-01",
    "freq": "1wk"
  },
  "current": {
    "ratio": 1.14,
    "ratio_percentile": 18.7,
    "zone": "bottom",
    "bottom_threshold": 1.16,
    "top_threshold": 2.45
  },
  "history_analogs": {
    "bottom_event_dates": ["2010-08-06", "2016-01-29", "2020-03-20"],
    "forward_metal_returns": {
      "252": {"count": 3, "median": 0.42, "mean": 0.39, "win_rate": 1.0, "worst": 0.18},
      "504": {"count": 3, "median": 0.71, "mean": 0.66, "win_rate": 1.0, "worst": 0.31}
    }
  },
  "scenarios": {
    "target": "return_to_top",
    "target_ratio": 2.45,
    "miner_multiplier_if_metal_flat": 2.15,
    "metal_multiplier_if_miner_flat": 0.46,
    "metal_drop_pct_if_miner_flat": 0.54
  },
  "summary": "銀礦股價 / 銀價比率落在歷史低分位，顯示礦業股相對白銀偏便宜...",
  "notes": [
    "比率訊號衡量的是『相對估值』，不是單邊價格保證。",
    "礦業股與金屬可能同漲，但礦業股也可能因成本上升、地緣/政策風險、增發稀釋而落後。",
    "建議搭配：礦業股獲利率(成本曲線)、白銀實質利率/美元、投機部位(COT)、ETF 流量等做交叉驗證。"
  ]
}

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

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

• 當前比率與歷史分位數
• 估值區間判定（bottom/low/neutral/high/top）
• 歷史底部事件列表與去重
• 底部事件後的前瞻報酬統計（平均/中位/勝率/最差）
• 情境推演（礦業股需漲多少 / 白銀需跌多少）
• 結果輸出為指定格式（JSON 或 Markdown）
• 視覺化圖表輸出（若需要）
• 風險提示與後續研究建議 </success_criteria>