detect-freight-led-inflation-turn

name	detect-freight-led-inflation-turn
description	透過美國卡斯貨運指數 (CASS Freight Index) 的週期轉折，偵測美國通膨壓力是否進入放緩或反轉階段。用於判斷「通膨是否正在降溫」，並驗證市場對降息、通膨回落的宏觀敘事是否有實體經濟數據支撐。

<essential_principles>

**CASS Freight Index 是最權威的貨運指標**

CASS Freight Index 由 Cass Information Systems 編制，追蹤北美地區的貨運出貨量與支出：

指標	說明	用途
Shipments Index	出貨量指數	衡量實體經濟需求強度
Expenditures Index	運費支出指數	衡量物流成本壓力
Shipments YoY	出貨量年增率	偵測週期轉折（主要分析指標）
Expenditures YoY	支出年增率	驗證成本傳導

數據來源：MacroMicro (透過 Highcharts 爬取)

**貨運量是通膨的領先指標**

核心邏輯：

• 貨運量 ≈ 實體經濟需求強度
• 出貨量下降 → 終端需求減弱 → 定價能力下降
• 歷史上 CASS 指標對 CPI 具有約 4-6 個月的領先性

關鍵訊號不是單月變化，而是「週期轉折」：

• 年增率轉負 (turned negative)
• 創週期新低 (new cycle low)

**訊號解讀：通膨緩解而非通縮**

當偵測到 CASS 週期轉折：

• 結論是「通膨壓力緩解」而非「通縮」
• 屬於 inflation easing / disinflation regime
• 支持市場對降息或政策轉向的預期

這是跨週期關係辨識：「物流需求動能 → 通膨方向」

**多指標交叉驗證**

建議同時觀察四個 CASS 指標：

1. Shipments YoY（主要）：需求端訊號
2. Expenditures YoY：成本端訊號
3. Shipments Index：絕對水準
4. Expenditures Index：運費壓力

當 Shipments 和 Expenditures 同時轉負，訊號更為可靠。

</essential_principles>

偵測 CASS Freight Index 的週期轉折，判斷通膨是否正在放緩。

輸出三層訊號：

1. Freight Status: CASS 各指標狀態與週期位置
2. Lead Alignment: 與 CPI YoY 的領先對齊分析
3. Signal Assessment: 通膨緩解訊號判斷與信心水準

<quick_start>

最快的方式：使用 Chrome CDP 抓取數據

Step 1：安裝依賴

pip install requests websocket-client pandas numpy

Step 2：啟動 Chrome 調試模式

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
  --remote-debugging-port=9222 ^
  --remote-allow-origins=* ^
  --user-data-dir="%USERPROFILE%\.chrome-debug-profile" ^
  "https://www.macromicro.me/charts/46877/cass-freight-index"

Step 3：等待頁面完全載入（圖表顯示），然後執行

cd scripts
python fetch_cass_freight.py --cdp

Step 4：執行通膨訊號分析

python freight_inflation_detector.py --quick

Step 5：生成視覺化圖表

python visualize_freight_cpi.py \
  --cache cache/cass_freight_cdp.json \
  --output ../../output/freight_cpi_$(date +%Y-%m-%d).png \
  --start 1995-01-01

輸出範例：

• JSON 分析結果：

{
  "signal": "inflation_easing",
  "confidence": "high",
  "freight_yoy": -7.46,
  "cycle_status": "negative",
  "indicator": "shipments_yoy",
  "macro_implication": "通膨壓力正在放緩，未來 CPI 下行風險上升"
}

• 視覺化圖表：output/freight_cpi_2026-01-23.png

備選方法（Selenium）：

pip install selenium webdriver-manager
python scripts/fetch_cass_freight.py --selenium --no-headless

</quick_start>

需要進行什麼分析？

1. 快速檢查 - 查看最新的 CASS 指標與通膨先行訊號
2. 完整分析 - 執行完整的週期轉折偵測與領先性分析
3. 方法論學習 - 了解 CASS 指標與通膨的領先關係

請選擇或直接提供分析參數。

| Response | Action | |------------------------------|-------------------------------------------------------------| | 1, "快速", "quick", "check" | 執行 `python scripts/freight_inflation_detector.py --quick` | | 2, "完整", "full", "analyze" | 閱讀 `workflows/analyze.md` 並執行 | | 3, "學習", "方法論", "why" | 閱讀 `references/methodology.md` | | 提供參數 (如日期範圍) | 閱讀 `workflows/analyze.md` 並使用參數執行 |

路由後，閱讀對應文件並執行。

<directory_structure>

detect-freight-led-inflation-turn/
├── SKILL.md                           # 本文件（路由器）
├── skill.yaml                         # 前端展示元數據
├── manifest.json                      # 技能元資料
├── workflows/
│   ├── analyze.md                     # 完整分析工作流
│   └── quick-check.md                 # 快速檢查工作流
├── references/
│   ├── data-sources.md                # CASS 數據來源與爬蟲說明
│   ├── methodology.md                 # 領先性方法論解析
│   └── historical-episodes.md         # 歷史案例對照
├── templates/
│   ├── output-json.md                 # JSON 輸出模板
│   └── output-markdown.md             # Markdown 報告模板
├── scripts/
│   ├── fetch_cass_freight.py          # MacroMicro CASS 爬蟲
│   ├── fetch_via_cdp.py               # Chrome CDP 爬蟲模組
│   ├── freight_inflation_detector.py  # 主分析腳本
│   └── visualize_freight_cpi.py       # CASS vs CPI 領先性視覺化
└── examples/
    └── sample_output.json             # 範例輸出

</directory_structure>

<reference_index>

方法論: references/methodology.md

• CASS Freight Index 與 CPI 的領先性關係
• 週期轉折偵測邏輯
• 訊號強度評估標準

資料來源: references/data-sources.md

• MacroMicro Highcharts 爬蟲說明
• CASS 四個指標定義
• 快取策略與更新頻率

歷史案例: references/historical-episodes.md

• 2008 金融危機前後
• 2020 疫情期間
• 2022 通膨高峰期

</reference_index>

<workflows_index>

Workflow	Purpose	使用時機
analyze.md	完整週期轉折分析	需要深度分析時
quick-check.md	快速檢查訊號	日常監控或快速回答
</workflows_index>

<templates_index>

Template	Purpose
output-json.md	JSON 輸出結構定義
output-markdown.md	Markdown 報告模板
</templates_index>

<scripts_index>

Script	Command	Purpose
fetch_cass_freight.py	--cdp	使用 CDP 爬取（推薦）
fetch_cass_freight.py	--selenium --no-headless	使用 Selenium 爬取（備選）
freight_inflation_detector.py	--quick	快速檢查最新訊號
freight_inflation_detector.py	--start DATE --indicator X	完整分析
visualize_freight_cpi.py	--lead-months 6 --start DATE	繪製 CASS vs CPI 領先圖
</scripts_index>

視覺化輸出：CASS vs CPI 領先性對比圖

核心特徵（參考 Bloomberg/Refinitiv 風格）：

1. CASS 6M Forward：將 CASS Freight Index 向前移動 6 個月，直觀展示領先關係
2. 雙軸對比：CPI YoY（左軸藍線）vs CASS Shipments YoY（右軸灰線）
3. 衰退區間標記：NBER 官方衰退期以淺色陰影標示
4. Bloomberg 深色風格：深藍背景、高對比度配色

快速繪圖：

cd scripts
python visualize_freight_cpi.py \
  --cache cache/cass_freight_cdp.json \
  --output ../../output/freight_cpi_YYYY-MM-DD.png \
  --start 1995-01-01 \
  --lead-months 6

輸出路徑：output/freight_cpi_YYYY-MM-DD.png（根目錄）

圖表解讀：

• 當 CASS（灰線）先行轉負/創新低，而 CPI（藍線）仍在高位 → 通膨放緩訊號
• 當 CASS 與 CPI 走勢同步 → 領先關係暫時失效，需謹慎解讀

<input_schema>

**Type**: string (ISO YYYY-MM-DD) **Description**: 分析起始日期 **Example**: "2010-01-01" **Type**: string (ISO YYYY-MM-DD) **Description**: 分析結束日期 **Type**: string **Options**: `shipments_index` | `expenditures_index` | `shipments_yoy` | `expenditures_yoy` **Description**: CASS 指標選擇 - `shipments_yoy`: 出貨量年增率（推薦，主要分析指標） - `expenditures_yoy`: 支出年增率 - `shipments_index`: 出貨量指數 - `expenditures_index`: 支出指數 **Type**: integer **Description**: 領先 CPI 的月份數 **Range**: 3-12 **Type**: float **Description**: 年增率警戒門檻（如 0 表示轉負）

</input_schema>

<output_schema> 參見 templates/output-json.md 的完整結構定義。

摘要：

{
  "signal": "inflation_easing | inflation_rising | neutral",
  "confidence": "high | medium | low",
  "freight_yoy": -2.9,
  "cycle_status": "new_cycle_low | negative | positive",
  "indicator": "shipments_yoy",
  "macro_implication": "通膨壓力正在放緩，未來 CPI 下行風險上升",
  "all_indicators": {
    "shipments_index": {...},
    "expenditures_index": {...},
    "shipments_yoy": {...},
    "expenditures_yoy": {...}
  }
}

</output_schema>

<success_criteria> 分析成功時應產出：

• CASS 四個指標的最新數值
• 選定指標的 YoY 與週期狀態
• 與 CPI 的領先對齊驗證
• 通膨緩解訊號與信心水準
• CASS vs CPI 領先性對比圖（output/freight_cpi_YYYY-MM-DD.png）
• 可操作的宏觀解讀
• 明確標註資料限制與假設 </success_criteria>