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）判斷當前比率位置：

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

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

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

此「背離」意味著：

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. 方法論學習 – 了解比率邏輯與分位數解讀

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

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

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

<templates_index>

<scripts_index>

<input_schema_summary>

核心參數

進階參數

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