1. 執行背離偵測 Skill

<essential_principles>

<principle name="divergence_core"> **背離訊號核心邏輯**

背離事件定義：

價格上漲：price_return >= min_price_return_pct（如 +15%）
庫存下滑：inventory_change <= -min_inventory_drawdown_pct（如 -10%）
同時發生：在相同視窗期（如 180 天）內同時滿足

當價格與庫存同向時（同漲同跌）為正常；逆向時（價漲庫跌）才需要警覺。 </principle>

<principle name="dual_hypothesis"> **雙重假設驗證**

不能直接把「庫存下降」解讀為「實物被搶」，需要交叉驗證：

| 假設 | 支持條件 | 反駁條件 | |------|----------|----------| | 實物緊張 | COMEX/LBMA 下降、backwardation、lease rates 上升、零售溢價擴大 | 其他庫存穩定、contango、溢價平穩 | | 資金流/贖回 | ETF 流出但交易所庫存穩定、期貨結構不緊 | 多重庫存同步下降 |

輸出兩種解釋，讓用戶判斷哪個更符合當前數據。 </principle>

<principle name="data_access"> **資料取得方式**

本 skill 優先使用：

ETF 官網庫存：Selenium 模擬人類瀏覽器行為抓取（避免 API 限制）
Yahoo Finance：yfinance 套件取得現貨/期貨價格
交叉驗證：COMEX 庫存、期貨結構等公開數據

腳本位於 scripts/ 目錄，遵循 references/data-sources.md 的反偵測策略。 </principle>

<principle name="stress_scoring"> **壓力分數計算**

stress_score = 100 × min(1.0,
    0.6 × divergence_severity +      # 背離嚴重度
    0.2 × decade_low_bonus +         # 十年低點加成
    0.2 × ratio_extreme_bonus        # 比值極端加成
)

| 分數區間 | 解讀 | |----------|------| | 0-30 | 正常，無明顯背離 | | 30-60 | 輕度背離，值得關注 | | 60-80 | 中度背離，建議深入驗證 | | 80-100 | 重度背離，高度警戒 | </principle>

</essential_principles>

<objective> 監控實物型 ETF（如 SLV、PSLV、GLD）的持倉與商品價格背離現象：

偵測背離：價格上漲但 ETF 庫存下滑
評估嚴重度：計算背離程度、十年低點、比值極端
交叉驗證：使用 COMEX、期貨結構、零售溢價等指標
產出洞察：提供兩種對立假設，避免單一敘事偏誤

輸出：背離狀態、壓力分數、交叉驗證結果、下一步檢查建議。 </objective>

<quick_start>

最快的方式：檢查 SLV 背離狀態

cd skills/monitor-etf-holdings-drawdown-risk
pip install pandas numpy yfinance selenium webdriver-manager beautifulsoup4 matplotlib  # 首次使用
python scripts/divergence_detector.py --etf SLV --quick

輸出範例：

{
  "asof": "2026-01-20",
  "divergence": false,
  "price_return_window": 1.92,
  "inventory_change_window": 0.15,
  "inventory_decade_low": false,
  "stress_score_0_100": 20.0,
  "interpretations": ["Physical Tightness", "ETF Flow Hypothesis"]
}

完整分析 + 視覺化報告：

# 1. 執行背離偵測
python scripts/divergence_detector.py \
  --etf SLV \
  --start 2010-01-01 \
  --end 2026-01-20 \
  --output result.json

# 2. 生成視覺化報告
python scripts/visualize_divergence.py \
  --result result.json \
  --output ../../../output/

輸出：

JSON 分析結果：result.json
視覺化報告：output/SLV_divergence_report_20260120.png
PDF 報告：output/SLV_divergence_report_20260120.pdf

</quick_start>

<intake> 需要進行什麼操作？

快速檢查 - 查看指定 ETF 目前的背離狀態與壓力分數
完整分析 - 執行完整的歷史背離分析
交叉驗證 - 使用多指標驗證背離訊號的真實性
監控模式 - 設定持續監控與背離警報
方法論學習 - 了解背離偵測與雙重假設邏輯

請選擇或直接提供分析參數（如 ETF 代碼）。 </intake>

<routing> | Response | Action | |---------------------------------|-----------------------------------------------| | 1, "快速", "quick", "check" | 執行 `scripts/divergence_detector.py --quick` | | 2, "分析", "analyze", "full" | 閱讀 `workflows/analyze.md` 並執行 | | 3, "驗證", "validate", "cross" | 閱讀 `workflows/cross-validate.md` 並執行 | | 4, "監控", "monitor", "alert" | 閱讀 `workflows/monitor.md` 並執行 | | 5, "學習", "方法論", "why" | 閱讀 `references/methodology.md` | | 提供 ETF 代碼 (如 SLV, GLD) | 閱讀 `workflows/analyze.md` 並使用參數執行 |

路由後，閱讀對應文件並執行。 </routing>

<directory_structure>

monitor-etf-holdings-drawdown-risk/
├── SKILL.md                           # 本文件（路由器）
├── skill.yaml                         # 前端展示元數據
├── manifest.json                      # 技能元數據
├── workflows/
│   ├── analyze.md                     # 完整背離分析工作流
│   ├── monitor.md                     # 持續監控工作流
│   └── cross-validate.md              # 交叉驗證工作流
├── references/
│   ├── data-sources.md                # ETF 庫存與價格資料來源
│   ├── methodology.md                 # 背離偵測方法論
│   └── input-schema.md                # 完整輸入參數定義
├── templates/
│   ├── output-json.md                 # JSON 輸出模板
│   └── output-markdown.md             # Markdown 報告模板
└── scripts/
    ├── divergence_detector.py         # 主偵測腳本
    ├── fetch_etf_holdings.py          # ETF 庫存抓取（Selenium）
    └── fetch_prices.py                # 價格數據抓取

</directory_structure>

<reference_index>

方法論: references/methodology.md

背離偵測邏輯
雙重假設驗證框架
壓力分數計算

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

ETF 官網庫存抓取（Selenium）
Yahoo Finance 價格數據
交叉驗證數據源（COMEX、LBMA）

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

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

</reference_index>

<workflows_index> | Workflow | Purpose | 使用時機 | |-------------------|------------------|------------------------| | analyze.md | 完整背離分析 | 需要完整歷史分析時 | | monitor.md | 持續監控狀態 | 日常監控或警報 | | cross-validate.md | 交叉驗證背離訊號 | 確認背離真實性時 | </workflows_index>

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

<scripts_index> | Script | Command | Purpose | |-------------------------|-----------------------------------------|----------------------| | divergence_detector.py | --etf SLV --quick | 快速檢查背離狀態 | | divergence_detector.py | --start DATE --end DATE --output FILE | 完整歷史分析 | | visualize_divergence.py | --result result.json --output DIR | 生成視覺化報告 | | fetch_etf_holdings.py | --etf SLV --output holdings.csv | 抓取 ETF 庫存 | | fetch_prices.py | --symbol SI=F --output prices.csv | 抓取商品價格 | </scripts_index>

<input_schema_summary>

核心參數

| 參數 | 類型 | 預設值 | 說明 | |------------------------|--------|------------|----------------------------| | etf_ticker | string | (必填) | ETF/信託代碼（如 SLV） | | commodity_price_symbol | string | (必填) | 商品價格代碼（如 XAGUSD） | | start_date | string | 10Y 前 | 分析起始日 | | end_date | string | today | 分析結束日 |

背離參數

| 參數 | 類型 | 預設值 | 說明 | |----------------------------|-------|--------|------------------------| | divergence_window_days | int | 180 | 背離計算視窗（天） | | decade_low_window_days | int | 3650 | 十年低點視窗（天） | | min_price_return_pct | float | 0.15 | 價格上漲門檻 | | min_inventory_drawdown_pct | float | 0.10 | 庫存下滑門檻 |

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

</input_schema_summary>

<output_schema_summary>

{
  "skill": "monitor-etf-holdings-drawdown-risk",
  "asof": "2026-01-16",
  "inputs": {
    "etf_ticker": "SLV",
    "commodity_price_symbol": "XAGUSD"
  },
  "result": {
    "divergence": true,
    "price_return_window": 0.32,
    "inventory_change_window": -0.18,
    "inventory_decade_low": true,
    "inventory_to_price_ratio_z": -2.4,
    "stress_score_0_100": 78.5
  },
  "interpretations": [...],
  "next_checks": [...]
}

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

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

[ ] 背離狀態判定（divergence: true/false）
[ ] 價格變化與庫存變化數值
[ ] 十年低點判定
[ ] 庫存/價格比值 Z 分數
[ ] 壓力分數（0-100）
[ ] 兩種對立假設解釋
[ ] 下一步驗證建議清單 </success_criteria>

Agent Skills: 1. 執行背離偵測

Install this agent skill to your local

Skill Files