lithium-supply-demand-gap-radar

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

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

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

強制規則：

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

根據 data_level 參數自動選擇數據源：

強制規則：

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

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

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

強制規則：

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

鋰價週期分為四個階段：

指標組合：

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

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

計算公式：

ETF_beta_li = Σ(weight_i * beta_i_to_lithium)

強制規則：

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

</essential_principles>

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

等待回應後再繼續。

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

<reference_index> 參考文件 (references/)

<workflows_index>

<templates_index>

<scripts_index>

<quick_start> CLI 快速開始：

# 完整分析 LIT ETF（預設 10 年回看、週度頻率）
python scripts/lithium_pipeline.py analyze --ticker=LIT --lookback=10 --freq=weekly

# 僅計算供需平衡 Nowcast
python scripts/lithium_pipeline.py balance --asof=2026-01-16

# 分析價格型態（碳酸鋰 + 氫氧化鋰）
python scripts/lithium_pipeline.py regime --chem=both

# 計算 ETF 對鋰價的傳導敏感度
python scripts/lithium_pipeline.py etf-beta --ticker=LIT --window=52

# ✨ 生成視覺化圖表（完整儀表板）
python scripts/visualize_analysis.py
# 輸出：output/lithium_analysis_YYYY-MM-DD.png

視覺化輸出：

• 📊 6合1 專業儀表板（18″ × 12″，300 DPI）
• 📁 自動保存至 output/ 目錄
• 📅 檔名包含當天日期
• 🎨 完整中文支持

Library 快速開始：

from lithium_pipeline import LithiumSupplyDemandRadar

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

# 完整分析
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> 輸入參數定義

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

# 範圍參數
region_focus:           # 供應/需求重點區（選填）
  - China
  - Australia
  - Chile
  - Argentina
  - US
  - EU

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

# 數據等級
data_level: string      # free_nolimit | free_limit | paid_low | paid_high

# 數據源開關
sources:
  usgs: boolean
  iea_ev_outlook: boolean
  australia_req: boolean
  abs_exports: boolean
  fastmarkets: boolean
  smm: boolean
  etf_holdings: boolean

# 輸出格式
output_format: string   # markdown | json（預設 markdown）

</input_schema>

<data_pipeline_architecture> 數據流水線架構

[Data Sources]
     |
     v
+--------------------+
|   ingest_sources   |  --> USGS, IEA, Australia REQ/ABS
+--------------------+      Fastmarkets/SMM (方法學/價格)
     |                      Global X LIT factsheet
     v
+--------------------+
|   normalize        |  --> 統一 schema + 單位標註
+--------------------+
     |
     +-------------------+-------------------+
     |                   |                   |
     v                   v                   v
+-----------+    +-----------+    +-----------+
| supply_   |    | price_    |    | etf_      |
| demand    |    | series    |    | holdings  |
+-----------+    +-----------+    +-----------+
     |                   |                   |
     v                   v                   v
+-----------+    +-----------+    +-----------+
| balance_  |    | classify_ |    | compute_  |
| nowcast   |    | regime    |    | etf_beta  |
+-----------+    +-----------+    +-----------+
     |                   |                   |
     +-------------------+-------------------+
                         |
                         v
              +--------------------+
              |   generate_insight |  --> Thesis + Targets + Invalidation
              +--------------------+
                         |
                         v
              +--------------------+
              |   format_output    |  --> JSON + Markdown
              +--------------------+

標準化欄位 Schema：