lithium-supply-demand-gap-radar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<essential_principles> 鋰產業鏈供需雷達核心原則

<principle name="supply_chain_layers"> **供應鏈分層（Supply Chain Layers）**

鋰產業鏈必須分層分析，不可混為一談：

Mining → Processing → Battery
(礦端)   (化學品)    (終端需求)

層級	代表數據	典型延遲
Upstream (礦端)	鋰礦產量、出口量	年度/季度
Midstream (化學品)	碳酸鋰/氫氧化鋰價格	週度/日度
Downstream (電池/EV)	EV 銷量、電池裝機量(GWh)	月度

強制規則：

供給分析需指定層級（礦端 vs 精煉端）
需求 proxy 需明確轉換假設（kWh → kg Li）
價格分析需區分碳酸鋰 vs 氫氧化鋰 </principle>

<principle name="data_level_fallback"> **數據等級與備援策略（Data Level Fallback）**

根據

data_level

參數自動選擇數據源：

data_level	價格數據	供需數據	可靠度
`free_nolimit`	CME 期貨/Proxy 指數	USGS/IEA/澳洲政府	中
`free_limit`	SMM/Fastmarkets 頁面	+ 公司財報	中高
`paid_low`	SMM 完整序列	+ Benchmark 基本	高
`paid_high`	Fastmarkets API	+ S&P/BNEF/WoodMac	最高

強制規則：

價格數據不足時，使用 CME 合約或相關股籃子作為 proxy
需在輸出中標註實際使用的數據等級 </principle>

<principle name="li_content_conversion"> **鋰含量轉換（Li Content Conversion）**

電池需求到鋰需求的轉換必須明確假設：

假設場景	kg Li / kWh	備註
保守估計	0.12	含 LFP 佔比上升假設
中性估計	0.15	混合 NMC/LFP
積極估計	0.18	高鎳 NMC 主導

python

li_demand_kt = battery_gwh * kg_per_kwh * 1000  # 單位: kt LCE

強制規則：

需求估計必須輸出三個情境（保守/中性/積極）
輸出需包含
```
kg_per_kwh_assumption
```
欄位 </principle>

<principle name="regime_classification"> **價格型態分類（Price Regime Classification）**

鋰價週期分為四個階段：

Regime	特徵	交易含義
`downtrend`	12-26 週動能 < 0, 斜率 < 0	空頭主導，避免做多
`bottoming`	動能收斂，波動下降，均值回歸	觀望，等待確認
`uptrend`	動能 > 0, 斜率 > 0	做多視窗開啟
`overheat`	動能極端正值，波動放大	獲利了結風險

指標組合：

12 週 / 26 週動能（ROC）
趨勢斜率（線性回歸）
波動率（ATR / 標準差）
均值回歸強度（距 MA 偏離度） </principle>

<principle name="etf_transmission"> **ETF 傳導敏感度（ETF Transmission）**

ETF 對鋰價的敏感度受持股結構影響：

持股類型	對鋰價 Beta	波動特性
Upstream (礦業)	1.5 - 2.5	高槓桿、高波動
Midstream (精煉)	0.8 - 1.2	跟隨但有加工費緩衝
Downstream (電池)	0.3 - 0.8	受競爭/技術路線影響

計算公式：

python

ETF_beta_li = Σ(weight_i * beta_i_to_lithium)

強制規則：

需計算 rolling beta（建議 52 週滾動）
傳導斷裂判斷：beta < 0.3 且持續 > 8 週 </principle>

</essential_principles>

<intake> **您想要執行什麼操作？**

Full Analysis - 完整供需×價格×傳導整合分析（生成完整報告）
Balance Nowcast - 僅計算供需平衡即時估計（缺口擴大/縮小）
Price Regime - 僅分析價格型態與週期位置
ETF Exposure - 僅分析 ETF 持股結構與鋰價敏感度
Ingest Data - 從各數據源擷取並標準化數據

等待回應後再繼續。 </intake>

<routing> | Response | Workflow | Description | |---------------------------------------------------|------------------------------|----------------------------| | 1, "full", "analyze", "完整", "報告", "LIT" | workflows/full-analysis.md | 完整供需×價格×傳導整合分析 | | 2, "balance", "nowcast", "供需", "缺口", "gap" | workflows/balance-nowcast.md | 供需平衡即時估計 | | 3, "price", "regime", "價格", "週期", "型態" | workflows/price-regime.md | 價格型態與週期分析 | | 4, "etf", "exposure", "holding", "傳導", "敏感度" | workflows/etf-exposure.md | ETF 暴露與傳導分析 | | 5, "ingest", "data", "fetch", "抓取", "擷取" | workflows/ingest.md | 數據擷取與標準化 |

讀取工作流程後，請完全遵循其步驟。 </routing>

<reference_index> 參考文件 (

references/

)

文件	內容
data-sources.md	所有數據來源詳細說明與 URL
unit-conversion.md	單位轉換規則（LCE/Li/GWh）
price-methodology.md	價格數據方法學（Fastmarkets/SMM）
etf-holdings-structure.md	LIT 持股結構與產業鏈分段
supply-chain-mapping.md	鋰供應鏈完整映射（礦→化學品→電池）
failure-modes.md	失敗模式與緩解策略
</reference_index>

<workflows_index>

Workflow	Purpose
full-analysis.md	完整供需×價格×傳導整合分析
balance-nowcast.md	供需平衡即時估計
price-regime.md	價格型態與週期分析
etf-exposure.md	ETF 持股暴露與傳導分析
ingest.md	數據擷取與標準化
</workflows_index>

<templates_index>

Template	Purpose
output-json.md	JSON 輸出結構模板
output-markdown.md	Markdown 報告模板
config.yaml	分析參數配置模板
data-schema.yaml	數據 Schema 定義
</templates_index>

<scripts_index>

Script	Purpose
lithium_pipeline.py	核心數據管線
ingest_sources.py	數據來源擷取
compute_balance.py	供需平衡計算
classify_regime.py	價格型態分類
compute_etf_beta.py	ETF 傳導敏感度計算
visualize_analysis.py	分析結果綜合視覺化
inflection_point_chart.py	拐點分析專用視覺化 ⭐
</scripts_index>

<quick_start> CLI 快速開始：

bash

undefined

<essential_principles> Core Principles of Lithium Industry Chain Supply and Demand Radar

<principle name="supply_chain_layers"> **Supply Chain Layers**

The lithium industry chain must be analyzed in layers and cannot be conflated:

Mining → Processing → Battery
(礦端)   (化學品)    (終端需求)

Layer	Representative Data	Typical Delay
Upstream (Mining)	Lithium mine production, export volume	Annual/Quarterly
Midstream (Processing)	Lithium carbonate/hydroxide price	Weekly/Daily
Downstream (Battery/EV)	EV sales, battery installed capacity(GWh)	Monthly

Mandatory Rules：

Supply analysis must specify the layer (mining vs refining)
Demand proxies must clarify conversion assumptions (kWh → kg Li)
Price analysis must distinguish between lithium carbonate and lithium hydroxide </principle>

<principle name="data_level_fallback"> **Data Level Fallback**

Automatically select data sources based on the

data_level

parameter:

data_level	Price Data	Supply and Demand Data	Reliability
`free_nolimit`	CME Futures/Proxy Index	USGS/IEA/Australian Government	Medium
`free_limit`	SMM/Fastmarkets Pages	+ Corporate Financial Reports	Medium-High
`paid_low`	SMM Full Series	+ Benchmark Basic	High
`paid_high`	Fastmarkets API	+ S&P/BNEF/WoodMac	Highest

Mandatory Rules：

When price data is insufficient, use CME contracts or related stock baskets as proxies
The actual data level used must be marked in the output </principle>

<principle name="li_content_conversion"> **Li Content Conversion**

The conversion from battery demand to lithium demand must have clear assumptions:

Assumption Scenario	kg Li / kWh	Remarks
Conservative Estimate	0.12	Including assumption of increasing LFP proportion
Neutral Estimate	0.15	Mixed NMC/LFP
Aggressive Estimate	0.18	High-nickel NMC dominated

python

li_demand_kt = battery_gwh * kg_per_kwh * 1000  # Unit: kt LCE

Mandatory Rules：

Demand estimates must output three scenarios (conservative/neutral/aggressive)
The output must include the
```
kg_per_kwh_assumption
```
field </principle>

<principle name="regime_classification"> **Price Regime Classification**

Lithium price cycles are divided into four phases:

Regime	Characteristics	Trading Implications
`downtrend`	12-26 week momentum < 0, slope < 0	Bearish dominance, avoid going long
`bottoming`	Momentum converges, volatility decreases, mean reversion	Wait and see, wait for confirmation
`uptrend`	Momentum > 0, slope > 0	Long window opens
`overheat`	Extreme positive momentum, amplified volatility	Profit-taking risk

Indicator Combination：

12-week / 26-week momentum (ROC)
Trend slope (linear regression)
Volatility (ATR / standard deviation)
Mean reversion strength (deviation from MA) </principle>

<principle name="etf_transmission"> **ETF Transmission**

The sensitivity of ETFs to lithium prices is affected by their holding structure:

Holding Type	Beta to Lithium Prices	Volatility Characteristics
Upstream (Mining)	1.5 - 2.5	High leverage, high volatility
Midstream (Refining)	0.8 - 1.2	Follows but has processing fee buffer
Downstream (Battery)	0.3 - 0.8	Affected by competition/technology routes

Calculation Formula：

python

ETF_beta_li = Σ(weight_i * beta_i_to_lithium)

Mandatory Rules：

Must calculate rolling beta (recommended 52-week rolling)
Transmission break judgment: beta < 0.3 and lasts > 8 weeks </principle>

</essential_principles>

<intake> **What operation do you want to perform?**

Full Analysis - Complete supply-demand × price × transmission integrated analysis (generate full report)
Balance Nowcast - Only calculate real-time supply-demand balance estimate (gap expansion/contraction)
Price Regime - Only analyze price patterns and cycle position
ETF Exposure - Only analyze ETF holding structure and lithium price sensitivity
Ingest Data - Extract and standardize data from various data sources

Please respond to continue. </intake>

<routing> | Response | Workflow | Description | |---------------------------------------------------|------------------------------|----------------------------| | 1, "full", "analyze", "完整", "報告", "LIT" | workflows/full-analysis.md | Complete supply-demand × price × transmission integrated analysis | | 2, "balance", "nowcast", "供需", "缺口", "gap" | workflows/balance-nowcast.md | Real-time supply-demand balance estimate | | 3, "price", "regime", "價格", "週期", "型態" | workflows/price-regime.md | Price pattern and cycle analysis | | 4, "etf", "exposure", "holding", "傳導", "敏感度" | workflows/etf-exposure.md | ETF exposure and transmission analysis | | 5, "ingest", "data", "fetch", "抓取", "擷取" | workflows/ingest.md | Data extraction and standardization |

After reading the workflow, please follow its steps completely. </routing>

<reference_index> Reference Documents (

references/

)

Document	Content
data-sources.md	Detailed description and URLs of all data sources
unit-conversion.md	Unit conversion rules (LCE/Li/GWh)
price-methodology.md	Price data methodology (Fastmarkets/SMM)
etf-holdings-structure.md	LIT holding structure and industry chain segmentation
supply-chain-mapping.md	Complete lithium supply chain mapping (mining → chemicals → batteries)
failure-modes.md	Failure modes and mitigation strategies
</reference_index>

<workflows_index>

Workflow	Purpose
full-analysis.md	Complete supply-demand × price × transmission integrated analysis
balance-nowcast.md	Real-time supply-demand balance estimate
price-regime.md	Price pattern and cycle analysis
etf-exposure.md	ETF exposure and transmission analysis
ingest.md	Data extraction and standardization
</workflows_index>

<templates_index>

Template	Purpose
output-json.md	JSON output structure template
output-markdown.md	Markdown report template
config.yaml	Analysis parameter configuration template
data-schema.yaml	Data Schema definition
</templates_index>

<scripts_index>

Script	Purpose
lithium_pipeline.py	Core data pipeline
ingest_sources.py	Data source extraction
compute_balance.py	Supply-demand balance calculation
classify_regime.py	Price regime classification
compute_etf_beta.py	ETF transmission sensitivity calculation
visualize_analysis.py	Comprehensive visualization of analysis results
inflection_point_chart.py	Specialized visualization for inflection point analysis ⭐
</scripts_index>

<quick_start> CLI Quick Start:

bash

undefined

完整分析 LIT ETF（預設 10 年回看、週度頻率）

Complete analysis of LIT ETF (default 10-year lookback, weekly frequency)

python scripts/lithium_pipeline.py analyze --ticker=LIT --lookback=10 --freq=weekly

僅計算供需平衡 Nowcast

Only calculate supply-demand balance Nowcast

python scripts/lithium_pipeline.py balance --asof=2026-01-16

分析價格型態（碳酸鋰 + 氫氧化鋰）

Analyze price regimes (lithium carbonate + lithium hydroxide)

python scripts/lithium_pipeline.py regime --chem=both

計算 ETF 對鋰價的傳導敏感度

Calculate ETF transmission sensitivity to lithium prices

python scripts/lithium_pipeline.py etf-beta --ticker=LIT --window=52

✨ 生成視覺化圖表（完整儀表板）

✨ Generate visualization charts (complete dashboard)

python scripts/visualize_analysis.py

輸出：output/lithium_analysis_YYYY-MM-DD.png

Output: output/lithium_analysis_YYYY-MM-DD.png


**視覺化輸出**：
- 📊 6合1 專業儀表板（18" × 12"，300 DPI）
- 📁 自動保存至 `output/` 目錄
- 📅 檔名包含當天日期
- 🎨 完整中文支持

**Library 快速開始：**

```python
from lithium_pipeline import LithiumSupplyDemandRadar

radar = LithiumSupplyDemandRadar(
    etf_ticker="LIT",
    lookback_years=10,
    price_freq="weekly",
    chem_focus="both",
    data_level="free_nolimit"
)


**Visualization Output**：
- 📊 6-in-1 professional dashboard (18" × 12", 300 DPI)
- 📁 Automatically saved to `output/` directory
- 📅 File name includes current date
- 🎨 Full Chinese support

**Library Quick Start:**

```python
from lithium_pipeline import LithiumSupplyDemandRadar

radar = LithiumSupplyDemandRadar(
    etf_ticker="LIT",
    lookback_years=10,
    price_freq="weekly",
    chem_focus="both",
    data_level="free_nolimit"
)

完整分析

Complete analysis

result = radar.full_analysis() print(f"Balance Index: {result['balance_index']:.2f}") print(f"Price Regime: {result['price_regime']}") print(f"ETF Beta to Li: {result['etf_beta_li']:.2f}") print(f"Thesis: {result['thesis']}")

</quick_start>

<success_criteria>
Skill 成功執行時：
- [ ] 正確識別數據等級並使用對應來源
- [ ] 供需平衡指數計算正確（含三情境）
- [ ] 價格型態分類明確（downtrend/bottoming/uptrend/overheat）
- [ ] ETF 傳導敏感度計算正確（rolling beta）
- [ ] 輸出包含完整的失效條件（invalidation）
- [ ] 數據來源可追溯（source_id, data_level）
- [ ] 單位轉換假設明確標註
- [ ] **視覺化圖表已生成且符合規格**（300 DPI, PNG, 檔名含日期）
- [ ] **報告與圖表在 output/ 目錄下一起輸出**
</success_criteria>

<input_schema>
**輸入參數定義**

```yaml

</quick_start>

<success_criteria>
**When the Skill is executed successfully:**
- [ ] Correctly identify data levels and use corresponding sources
- [ ] Supply-demand balance index calculated correctly (including three scenarios)
- [ ] Clear price regime classification (downtrend/bottoming/uptrend/overheat)
- [ ] ETF transmission sensitivity calculated correctly (rolling beta)
- [ ] Output includes complete invalidation conditions
- [ ] Data sources are traceable (source_id, data_level)
- [ ] Unit conversion assumptions are clearly marked
- [ ] **Visualization charts are generated and meet specifications** (300 DPI, PNG, file name includes date)
- [ ] **Reports and charts are output together in the output/ directory**
</success_criteria>

<input_schema>
**Input Parameter Definition**

```yaml

必要參數

Required parameters

etf_ticker: string # 目標 ETF（預設 LIT） lookback_years: int # 回看年限（建議 10-15） price_freq: string # weekly | daily（建議 weekly）

etf_ticker: string # Target ETF (default LIT) lookback_years: int # Lookback years (recommended 10-15) price_freq: string # weekly | daily (recommended weekly)

範圍參數

Range parameters

region_focus: # 供應/需求重點區（選填）

China
Australia
Chile
Argentina
US
EU

chem_focus: string # carbonate | hydroxide | both（預設 both）

region_focus: # Key regions for supply/demand (optional)

China
Australia
Chile
Argentina
US
EU

chem_focus: string # carbonate | hydroxide | both (default both)

數據等級

Data level

data_level: string # free_nolimit | free_limit | paid_low | paid_high

數據源開關

Data source switches

sources: usgs: boolean iea_ev_outlook: boolean australia_req: boolean abs_exports: boolean fastmarkets: boolean smm: boolean etf_holdings: boolean

輸出格式

Output format

output_format: string # markdown | json（預設 markdown）

</input_schema>

<data_pipeline_architecture>
**數據流水線架構**


**標準化欄位 Schema：**

| 欄位        | 類型   | 說明                         |
|-------------|--------|------------------------------|
| date        | date   | 數據日期                     |
| metric_type | string | supply/demand/price/etf      |
| metric_name | string | 具體指標名稱                 |
| value       | float  | 數值                         |
| unit        | string | kt_LCE/USD_per_kg/GWh/pct    |
| region      | string | 國家/區域                    |
| source_id   | string | USGS/IEA/SMM/Fastmarkets/etc |
| data_level  | string | 數據等級                     |
| confidence  | float  | 來源品質評分 (0-1)           |
</data_pipeline_architecture>

output_format: string # markdown | json (default markdown)

</input_schema>

<data_pipeline_architecture>
**Data Pipeline Architecture**


**Standardized Field Schema:**

| Field        | Type   | Description                         |
|-------------|--------|-------------------------------------|
| date        | date   | Data date                           |
| metric_type | string | supply/demand/price/etf             |
| metric_name | string | Specific metric name                |
| value       | float  | Numeric value                       |
| unit        | string | kt_LCE/USD_per_kg/GWh/pct           |
| region      | string | Country/region                      |
| source_id   | string | USGS/IEA/SMM/Fastmarkets/etc        |
| data_level  | string | Data level                          |
| confidence  | float  | Source quality score (0-1)          |
</data_pipeline_architecture>