以全球鎳供給結構為核心，量化各國的主導程度（例如印尼）、主要礦區供給量、以及政策配額/減產情境對全球供需平衡與價格非對稱的影響。
<essential_principles> 鎳供給集中度分析 核心原則
<principle name="unit_enforcement"> **口徑先行（Unit Enforcement）**所有分析必須先確定口徑，不同口徑會導致數量級差異：
| 口徑 | 說明 | 典型數值差異 |
|---|---|---|
t_Ni_content | 鎳金屬含量（本 Skill 預設） | 基準值 |
t_ore_wet | 礦石濕噸 | 可達 50-100x |
t_NPI_product | NPI 產品噸 | 約 10-15% Ni |
t_matte | 鎳鋶噸 | 約 75% Ni |
強制規則：
model_estimateunit 欄位
</principle>
鎳供給鏈各階段必須分開計算：
Mine Production (mined) → Intermediate (NPI/Matte/MHP) → Refined (class1/class2)
| Tier | 特性 | 來源 | 用途 |
|---|---|---|---|
| 0 | 免費、穩定、口徑一致 | USGS MCS, INSG | Baseline 主幹 |
| 1 | 免費但分散、需整合 | 公司年報、財報 | Mine-level 錨點 |
| 2 | 付費、更即時完整 | S&P Global MI | 精度驗證、對齊口徑 |
| 3 | 政策/配額近期訊息 | 新聞、官方公告 | 情境輸入 |
優先順序：Tier 0 建立 baseline → Tier 1 補充 mine-level → Tier 2 驗證精度 </principle>
政策減產不需 100% 執行即可造成衝擊。預設模型：
expected_cut = cut_value * execution_prob # 預設 execution_prob = 0.5
三層輸出：
| 指標 | 公式 | 解讀 |
|---|---|---|
| Country Share | country_prod / global_prod | 單國佔比 |
| CR_n | Σ top_n_share | 前 N 國/礦集中度 |
| HHI | Σ share² | 市場集中度（0-10000） |
| Policy Leverage | cut_amount / global_prod | 政策可撬動的全球供給比例 |
HHI 判讀：< 1500 低集中、1500-2500 中等、> 2500 高集中 </principle> </essential_principles>
等待回應後再繼續。 </intake>
讀取工作流程後，請完全遵循其步驟。 </routing>
<reference_index>
參考文件 (references/)
| 文件 | 內容 |
|---|---|
| data-sources.md | 所有數據來源詳細說明與 URL |
| unit-conversion.md | 單位轉換規則與假設 |
| concentration-metrics.md | 集中度指標詳細計算方法 |
| indonesia-supply-structure.md | 印尼鎳供給結構與關鍵園區 |
| mine-level-anchors.md | 主要礦區/園區產量錨點 |
| failure-modes.md | 失敗模式與緩解策略 |
| </reference_index> |
<workflows_index>
| Workflow | Purpose |
|---|---|
| analyze.md | 供給結構與集中度分析（CR_n, HHI, share） |
| scenario-engine.md | 政策情境衝擊模擬 |
| validate-sources.md | 數據來源與口徑驗證 |
| 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 |
|---|---|
| nickel_pipeline.py | 核心數據管線 |
| ingest_sources.py | 數據來源擷取 |
| compute_concentration.py | 集中度指標計算 |
| scenario_impact.py | 情境衝擊模擬 |
| visualize_concentration.py | 集中度分析視覺化圖表 |
| visualize_scenario.py | 情境衝擊視覺化圖表 |
| </scripts_index> |
<quick_start> CLI 快速開始：
# 分析當前全球鎳供給集中度
python scripts/nickel_pipeline.py analyze --asof=2026-01-16 --scope=mined
# 生成集中度視覺化圖表（輸出到 output/ 目錄，檔名包含日期）
python scripts/visualize_concentration.py
# 模擬印尼減產 20% 的情境衝擊
python scripts/nickel_pipeline.py scenario --cut=20 --target=Indonesia --exec-prob=0.5
# 生成情境衝擊視覺化圖表
python scripts/visualize_scenario.py
# 驗證「印尼 60% 市佔」的數據來源
python scripts/nickel_pipeline.py validate --claim="Indonesia 60% share"
Library 快速開始：
from nickel_pipeline import NickelConcentrationAnalyzer
analyzer = NickelConcentrationAnalyzer(
asof_date="2026-01-16",
scope={"supply_type": "mined", "unit": "t_Ni_content"},
data_level="free_nolimit"
)
# 計算集中度指標
result = analyzer.compute_concentration()
print(f"Indonesia share: {result['indonesia_share_2024']:.1%}")
print(f"HHI: {result['hhi_2024']:.0f}")
</quick_start>
<success_criteria> Skill 成功執行時：
<input_schema> 輸入參數定義
# 必要參數
asof_date: string (ISO) # 分析基準日