detect-shanghai-silver-stock-drain

<essential_principles>

The three-dimensional framework of inventory analysis:

Direction: Is inventory rising or falling
Speed: Weekly outflow volume drain_rate(t) = -Δ1(t)
Acceleration: Change in outflow speed Δ2(t) = drain_rate(t) - drain_rate(t-1)

When drain_rate > 0 and Δ2 > 0 , it indicates "inventory is flowing out, and the outflow speed is accelerating"—this is the core characteristic of a late-stage supply signal.

Use a historical window (recommended 3–5 years) to calculate the Z-score:

z_drain(t) = (drain_rate(t) - mean) / std
z_accel(t) = (Δ2(t) - mean) / std

Threshold determination:

Indicator	Threshold	Meaning
z_drain	≤ -1.5	Outflow speed is significantly greater than normal
z_accel	≥ +1.0	Outflow is accelerating
level_percentile	≤ 0.20	Inventory is at a historically low level

Convert the tweet narrative into executable rules:

Condition	Description	Standalone	Combined effect
A. Level	Inventory level < 20% historical percentile	WATCH	-
B. Speed	z_drain ≤ -1.5	WATCH	B+C → MEDIUM
C. Acceleration	z_accel ≥ +1.0	WATCH	A+B+C → HIGH

Signal classification：

HIGH_LATE_STAGE_SUPPLY_SIGNAL: A+B+C simultaneously true
MEDIUM_SUPPLY_TIGHTENING: (B+C) or (A+B) true
WATCH: Any condition true
NO_SIGNAL: No anomaly

Main data sources:

CEIC Data: Shanghai Futures Exchange silver warrant data
- URL: https://www.ceicdata.com/zh-hans/china/shanghai-futures-exchange-commodity-futures-stock/cn-warehouse-stock-shanghai-future-exchange-silver
- Data range: 2012-07-02 to present (approximately 3,300+ observations)
- Update frequency: Daily
- Historical high: 3,091 tonnes (2021-01-12)

Important note：

This is the "exchange deliverable/warrant" caliber, and is not equal to all of China's social inventory
Single-week jumps may reflect changes in warehousing rules or warehouse transfers, and require smoothing
Use Selenium to simulate a human browser to scrape SVG charts, following anti-detection strategies

</essential_principles>

Data collection: Scrape SGE/SHFE weekly report inventory data
Three-dimensional quantification: Calculate direction, speed, and acceleration
Standardized judgment: Use Z-scores to determine anomalies
Signal generation: Output late-stage supply signal classification
Market cross-validation(optional): COMEX, ETF, spot premium

Output: inventory level, depletion speed, acceleration, Z-score, signal classification, narrative interpretation.

<quick_start>

Fastest way: Check Shanghai silver inventory depletion status

cd skills/detect-shanghai-silver-stock-drain

# 首次使用：安裝依賴
pip install pandas numpy selenium webdriver-manager matplotlib

# 1. 抓取最新數據（5 年歷史，約 200+ 週）
python scripts/fetch_shfe_stock.py --force-update

# 2. 執行快速檢查
python scripts/drain_detector.py --quick

Output example:

{
  "as_of": "2026-01-16",
  "signal": "MEDIUM_SUPPLY_TIGHTENING",
  "latest_combined_stock_tonnes": 1133.3,
  "level_percentile": 0.12,
  "z_drain_rate": -2.1,
  "z_acceleration": 1.4
}

Full analysis + visualization report：

# 1. 執行完整分析
python scripts/drain_detector.py \
  --start 2020-01-01 \
  --end 2026-01-16 \
  --output result.json

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

</quick_start>

Quick check - View the current Shanghai silver inventory depletion status and signal
Full analysis - Run a complete historical inventory analysis and trend calculation
Data update - Scrape the latest SGE/SHFE inventory data
Cross-validation - Use indicators such as COMEX and ETF for cross-validation
Methodology learning - Understand the three-dimensional quantification and signal determination logic

Please choose or directly provide analysis parameters.

After routing, read the corresponding file and execute.

<directory_structure>

detect-shanghai-silver-stock-drain/
├── SKILL.md                           # 本文件（路由器）
├── skill.yaml                         # 前端展示元數據
├── manifest.json                      # 技能元數據
├── workflows/
│   ├── analyze.md                     # 完整庫存分析工作流
│   ├── fetch-data.md                  # 數據抓取工作流
│   └── cross-validate.md              # 交叉驗證工作流
├── references/
│   ├── data-sources.md                # SGE/SHFE 資料來源說明
│   ├── methodology.md                 # 三維度量化方法論
│   └── input-schema.md                # 完整輸入參數定義
├── templates/
│   ├── output-json.md                 # JSON 輸出模板
│   └── output-markdown.md             # Markdown 報告模板
└── scripts/
    ├── drain_detector.py              # 主偵測腳本
    ├── fetch_sge_stock.py             # SGE 庫存抓取（PDF）
    ├── fetch_shfe_stock.py            # SHFE 庫存抓取
    └── visualize_drain.py             # 視覺化報告生成

</directory_structure>

<reference_index>

Methodology: references/methodology.md

Three-dimensional quantification logic (direction, speed, acceleration)
Z-score standardization
Three-stage signal determination

Data sources: references/data-sources.md

SGE market weekly report PDF scraping
SHFE warehouse receipt/inventory weekly report scraping
Selenium anti-detection strategy

Input parameters: references/input-schema.md

Complete parameter definitions
Default values and recommended ranges

</reference_index>

<workflows_index>

Workflow	Purpose	When to use
analyze.md	Complete inventory analysis	When complete historical analysis is needed
fetch-data.md	Data scraping	Update SGE/SHFE inventory data
cross-validate.md	Cross-validate signals	When confirming the authenticity of supply tightening signals
</workflows_index>

<templates_index>

Template	Purpose
output-json.md	JSON output structure definition
output-markdown.md	Markdown report template
</templates_index>

<scripts_index>

Script	Command	Purpose
drain_detector.py	`--quick`	Quickly check depletion status
drain_detector.py	`--start DATE --end DATE --output FILE`	Complete historical analysis
fetch_sge_stock.py	`--output sge_stock.csv`	Scrape SGE inventory
fetch_shfe_stock.py	`--output shfe_stock.csv`	Scrape SHFE inventory
visualize_drain.py	`--result result.json --output DIR`	Generate visualization report
</scripts_index>

<input_schema_summary>

Core parameters

Parameter	Type	Default value	Description
start_date	string	3Y ago	Analysis start date (YYYY-MM-DD)
end_date	string	today	Analysis end date (YYYY-MM-DD)
frequency	string	weekly	Data frequency (weekly/daily)
include_sources	array	["SGE","SHFE"]	Included inventory sources
unit	string	tonnes	Unit (tonnes/kg/troy_oz)

Analysis parameters

Parameter	Type	Default value	Description
smoothing_window_weeks	int	4	Smoothing window (weeks)
drain_threshold_z	float	-1.5	Abnormal depletion Z-score threshold
accel_threshold_z	float	+1.0	Depletion acceleration Z-score threshold
confirm_with_markets	bool	true	Whether to perform market-side cross-validation

See complete parameter definitions in references/input-schema.md。

</input_schema_summary>

<output_schema_summary>

{
  "skill": "detect_shanghai_silver_stock_drain",
  "as_of": "2026-01-16",
  "unit": "tonnes",
  "sources": ["SGE", "SHFE"],
  "latest_combined_stock": 1133.3,
  "level_percentile": 0.12,
  "recent_4w_avg_drawdown": 58.4,
  "drawdown_acceleration": 9.7,
  "z_scores": {
    "z_drain_rate": -2.1,
    "z_acceleration": 1.4
  },
  "signal": "HIGH_LATE_STAGE_SUPPLY_SIGNAL",
  "narrative": [...],
  "caveats": [...]
}

See complete output structure in templates/output-json.md。 </output_schema_summary>

<success_criteria> Successful execution should produce:

Shanghai combined inventory level (SGE + SHFE)
Historical percentile of inventory level
Average outflow rate over the past N weeks
Outflow acceleration
z_drain_rate and z_acceleration
Signal grading (HIGH/MEDIUM/WATCH/NO_SIGNAL)
Narrative interpretation (Chinese)
Data scope and limitation notes </success_criteria>

About this skill