monitor-etf-holdings-drawdown-risk

<essential_principles>

**背离信号核心逻辑**

背离事件定义：

• 价格上涨：price_return >= min_price_return_pct（如 +15%）
• 库存下滑：inventory_change <= -min_inventory_drawdown_pct（如 -10%）
• 同时发生：在相同窗口期（如 180 天）内同时满足

当价格与库存同向时（同涨同跌）属于正常；反向时（价涨库跌）才需要警惕。

**双重假设验证**

不能直接把“库存下降”解读为“实物被抢”，需要交叉验证：

假设	支持条件	反驳条件
实物紧张	COMEX/LBMA 下降、backwardation、lease rates 上升、零售溢价扩大	其他库存稳定、contango、溢价平稳
资金流/赎回	ETF 流出但交易所库存稳定、期货结构不紧	多重库存同步下降

输出两种解释，让用户判断哪种更符合当前数据。

**数据获取方式**

本 skill 优先使用：

• ETF 官网库存：使用 Selenium 模拟人类浏览器行为抓取（避免 API 限制）
• Yahoo Finance：使用 yfinance 套件获取现货/期货价格
• 交叉验证：COMEX 库存、期货结构等公开数据

脚本位于 scripts/ 目录，遵循 references/data-sources.md 中的反侦测策略。

**压力分数计算**

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	重度背离，高度警戒

</essential_principles>

监控实物型 ETF（如 SLV、PSLV、GLD）的持仓与商品价格背离现象：

1. 检测背离：价格上涨但 ETF 库存下滑
2. 评估严重程度：计算背离程度、十年低点、比值极端情况
3. 交叉验证：使用 COMEX、期货结构、零售溢价等指标
4. 产出洞察：提供两种对立假设，避免单一叙事偏差

输出：背离状态、压力分数、交叉验证结果、下一步检查建议。

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

需要执行什么操作？

1. 快速检查 - 查看指定 ETF 当前的背离状态与压力分数
2. 完整分析 - 执行完整的历史背离分析
3. 交叉验证 - 使用多项指标验证背离信号的真实性
4. 监控模式 - 设置持续监控与背离警报
5. 方法论学习 - 了解背离检测与双重假设逻辑

请选择或直接提供分析参数（如 ETF 代码）。

| 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` 并使用参数执行 |

路由后，阅读对应文件并执行。

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