analyze-copper-inventory-rebuild-signal

<essential_principles>

This skill converts "eyeballing charts" into a quantifiable, automatically updatable two-layer signal system:

Layer	Question	Core Indicator	Decision Output
Short-term	Is it "a bit ahead of itself"?	SHFE restocking speed z-score + inventory level	CAUTION / NEUTRAL / SUPPORTIVE
Long-term	Is it "still cheap"?	Copper price historical percentile (10 years)	CHEAP / FAIR / RICH

Key Insight: Rapid SHFE inventory restocking + elevated inventory level → often close to a local price high.

Use Chrome CDP fully automaticto scrape Highcharts chart data; three types of data are required in total:

Data	Source	URL
SHFE copper inventory	MacroMicro (CDP)	https://en.macromicro.me/series/8743/copper-shfe-warehouse-stock
COMEX copper inventory	MacroMicro (CDP)	https://www.macromicro.me/series/8742/copper-comex-warehouse-stock
Copper futures price	Yahoo Finance	`HG=F`(COMEX copper futures continuous front month)

Basis: inventory is deliverable copper inventory (tons), price is closing price (USD/lb)

Convert the subjective "restocking very fast" into an objective, comparable standardized indicator:

rebuild_W = inv_t - inv_{t-W}  (W = 4 週)
z_score = (rebuild_W - μ) / σ   (μ, σ 為 3 年滾動)

z-score > 1.5: restocking speed is "abnormally fast"
z-score > 2.0: restocking speed is "extremely fast"
z-score < -1.5: destocking speed is "abnormally fast"

</essential_principles>

<quick_start>

Fully automatic execution (no need to manually operate Chrome)

Step 1: Install dependencies

pip install requests websocket-client pandas numpy yfinance matplotlib

Step 2: One-click scrape of all data (SHFE + COMEX inventory + copper price)

cd skills/analyze-copper-inventory-rebuild-signal/scripts
python fetch_copper_data.py

The script will automatically:

Launch Chrome in debug mode
Scrape SHFE and COMEX inventory in sequence (~80 seconds)
Scrape copper futures price (Yahoo Finance)
Save to cache/shfe_inventory.csv、cache/comex_inventory.csv、cache/copper_price.csv
Close Chrome

Step 3: Run inventory signal analysis

python inventory_signal_analyzer.py

Step 4: Generate visualization charts

python visualize_inventory_signal.py

Output：{專案根目錄}/output/copper_inventory_signal_YYYY-MM-DD.png

</quick_start>

Quick Check - View the current SHFE inventory restocking signal status
Full Analysis - Run historical validation of restocking signals and price highs
Long-term Percentile - Historical percentile reading of copper prices (10 years)
Visualization - Generate Bloomberg-style analysis charts

Please select or directly provide analysis parameters.

After routing, execute the corresponding command.

<directory_structure>

analyze-copper-inventory-rebuild-signal/
├── SKILL.md                              # 本文件（路由器）
├── manifest.json                         # 技能元資料
├── skill.yaml                            # 前端展示元數據
├── scripts/
│   ├── fetch_copper_data.py              # 全自動 CDP 數據爬蟲（SHFE + COMEX + 價格）
│   ├── fetch_shfe_inventory.py           # SHFE 專用爬蟲（向下相容）
│   ├── inventory_signal_analyzer.py      # 核心分析邏輯
│   └── visualize_inventory_signal.py     # Bloomberg 風格視覺化
├── references/
│   ├── data-sources.md                   # 數據來源說明
│   ├── methodology.md                    # 方法論說明
│   └── historical-episodes.md            # 歷史事件對照
├── templates/
│   ├── output-json.md                    # JSON 輸出格式
│   └── output-markdown.md                # Markdown 輸出格式
├── workflows/
│   ├── quick-check.md                    # 快速檢查流程
│   ├── full-analysis.md                  # 完整分析流程
│   └── visualize.md                      # 視覺化流程
├── cache/
│   ├── shfe_inventory.csv                # SHFE 庫存快取
│   ├── comex_inventory.csv               # COMEX 庫存快取
│   └── copper_price.csv                  # 銅價快取
└── examples/
    └── sample_output.json                # 範例輸出

# 視覺化輸出位置（專案根目錄）
{專案根目錄}/output/
└── copper_inventory_signal_YYYY-MM-DD.png  # 輸出圖表（含日期）

</directory_structure>

<scripts_index>

Script	Command	Purpose
fetch_copper_data.py	`python fetch_copper_data.py`	Fully automatic scrape of all data (SHFE + COMEX + price)
fetch_copper_data.py	`--force-refresh`	Force re-scrape (ignore cache)
fetch_copper_data.py	`--source shfe`	Scrape only SHFE inventory
fetch_copper_data.py	`--source comex`	Scrape only COMEX inventory
fetch_copper_data.py	`--source price`	Scrape only copper price
inventory_signal_analyzer.py	`--quick`	Quick check of current signal status
inventory_signal_analyzer.py	`--full`	Full historical validation analysis
inventory_signal_analyzer.py	`--long-term`	Long-term price percentile analysis
visualize_inventory_signal.py	No parameters	Generate Bloomberg-style charts (output to project root directory output/)
visualize_inventory_signal.py	`-o path.png`	Specify output path
</scripts_index>

<input_parameters>

Analysis Parameters

Parameter	Type	Default Value	Description
`start_date`	string	2015-01-01	Backtest start date
`end_date`	string	today	Backtest end date
`price_ticker`	string	HG=F	Copper futures ticker (Yahoo Finance)
`price_freq`	string	weekly	Price frequency (daily/weekly)
`fast_rebuild_window_weeks`	int	4	"Fast restock" observation window (weeks)
`fast_rebuild_z`	float	1.5	Restock speed z-score threshold
`high_inventory_mode`	string	percentile	Inventory-elevated determination mode (absolute/percentile)
`high_inventory_percentile`	float	0.85	Inventory-elevated percentile threshold
`peak_match_window_weeks`	int	2	Allowed window for signal-corresponding price highs (±N weeks)
`long_term_window_years`	int	10	Long-term percentile calculation window (years)
`cheap_percentile`	float	0.35	"Long-term cheap" threshold

</input_parameters>

Visualization output: Bloomberg-style copper inventory restock signal dashboard

Designed following the thoughts/shared/guide/bloomberg-style-chart-guide.md specification.

Contains three sections (arranged top to bottom):

Copper price + total inventory comparison(dual-axis chart)
- R1 right axis: copper price (orange-red line)
- L2 left axis: total inventory area chart (SHFE + COMEX stacked)
- Mark CAUTION signal trigger points
- Latest price annotation
Restock speed z-score(time series chart)
- SHFE z-score: area fill (red/cyan distinguishes restocking/destocking)
- COMEX z-score: dashed line overlay
- Threshold lines (z=1.5, z=2.0, z=-1.5)
Signal status dashboard
- Short-term signal section (CAUTION/NEUTRAL/SUPPORTIVE)
- Long-term assessment section (CHEAP/FAIR/RICH)
- SHFE/COMEX z-score real-time values

Color scheme: Bloomberg dark theme (according to bloomberg-style-chart-guide.md)

Background: #1a1a2e(dark navy black)
Grid: #2d2d44(dark gray-purple)
Copper price (primary): #ff6b35(orange-red)
SHFE inventory (secondary): #ffaa00(orange-yellow)
COMEX inventory (tertiary): #ffff00(yellow)
CAUTION signal: #ff4444(red)
SUPPORTIVE: #00ff88(green)
Neutral: #888888(gray)

Quick plotting：

cd scripts
python visualize_inventory_signal.py

Output path：{專案根目錄}/output/copper_inventory_signal_YYYY-MM-DD.png

Charts are automatically output to the output/ folder in the project root directory, with the file name containing the current date.

<output_example>

Markdown output example

# 銅：庫存回補訊號（SHFE / COMEX）

## 最新狀態
- 數據日期：2026-01-26
- SHFE 庫存：235,000 噸
- SHFE 4 週回補速度 z-score：+1.9（異常快）
- COMEX 庫存：18,500 噸
- COMEX 4 週回補速度 z-score：+0.5（正常）
- 總庫存（SHFE + COMEX）：253,500 噸
- 銅期貨價格：4.52 USD/lb

## 短期判斷（是否「有點超前」）
- 訊號：**⚠️ CAUTION**
- 原因：SHFE 庫存「水位偏高」且「回補速度異常快」
- 歷史驗證：過去同類訊號在 ±2 週內對應局部高點的命中率約 **62%**
- 解讀：短線更容易出現「漲勢喘口氣 / 回檔」而不是一路順風

## 長期判斷（是否仍「偏便宜」）
- 銅價 10 年歷史分位數：0.32（低於 0.35）
- 結論：**💚 長期偏便宜**（但不代表短線不會先整理）

---
### 數據來源
- SHFE 庫存：MacroMicro (CDP)
- COMEX 庫存：MacroMicro (CDP)
- 銅價：Yahoo Finance (HG=F)

JSON output example

{
  "asof": "2026-01-26",
  "near_term_signal": "CAUTION",
  "long_term_view": "CHEAP",
  "latest": {
    "shfe_inventory_tonnes": 235000,
    "shfe_rebuild_z": 1.9,
    "comex_inventory_tonnes": 18500,
    "comex_rebuild_z": 0.5,
    "total_inventory_tonnes": 253500,
    "copper_price": 4.52,
    "price_percentile": 0.32
  },
  "backtest": {
    "peak_match_window_weeks": 2,
    "signal_to_local_peak_hit_rate": 0.62,
    "signal_count": 21
  }
}

</output_example>

<success_criteria> A successful analysis should produce:

SHFE and COMEX inventory data fully automatically scraped and cached from MacroMicro fully automaticallyscraped and cached
Copper futures price data scraped from Yahoo Finance
Current SHFE and COMEX restock speed z-scores and inventory percentiles
Short-term signal (CAUTION / NEUTRAL / SUPPORTIVE)
Historical signal hit rate backtest results
Long-term price percentile and assessment (CHEAP / FAIR / RICH)
Bloomberg-style visualization charts
Clearly annotate data sources and calculation methods </success_criteria>

<references_index>

Document	Content
references/data-sources.md	SHFE inventory and copper price data sources, CDP scraping explanation
references/methodology.md	Restock speed z-score, percentile calculation methodology
references/historical-episodes.md	Historical signal trigger event comparison
</references_index>

<workflows_index>

Workflow	Purpose
workflows/quick-check.md	Quickly check current signal status
workflows/full-analysis.md	Complete historical verification analysis
workflows/visualize.md	Visualization chart generation
</workflows_index>

<templates_index>

Template	Purpose
templates/output-json.md	JSON output format specification
templates/output-markdown.md	Markdown output format specification
</templates_index>

About this skill