tradermonty/theme-detector

主題偵測器

概述

此技能透過分析跨產業的動能、成交量與廣度訊號，來偵測並排名熱門市場主題。它能夠識別多頭（上升動能）與空頭（下跌壓力）主題、評估生命週期成熟度（新興/加速/趨勢/成熟/耗盡），並提供結合量化數據與敘事分析的信心中位分數。

三維評分模型：

1. 主題熱度 (0-100)：主題的中立強度（動能、成交量、上升趨勢比率、廣度）
2. 生命週期成熟度：根據持續時間、極端值群聚、估值與 ETF 普及度進行階段分類（新興 / 加速 / 趨勢 / 成熟 / 耗盡）
3. 信心水準 (低 / 中 / 高)：偵測的可靠性，結合量化廣度與敘事確認。腳本輸出上限為「中」；Claude 的 WebSearch 敘事確認步驟可將其提升至「高」。
4. 股票領導力：可選的每日掃描命中證據，來自 5D+20%、EP9M、區間擴張、創新高與高相對強度股票。提供時，此項會整合到主題熱度 v2 中；缺少時，它會降低信心覆蓋率，但不會將領導力強制歸零。
5. 主題匹配品質：透過產業參與度、明確股票籃子命中、代理 ETF 確認與可選的離線敘事分數，來衡量主題匹配的精確度。這是證據品質，而非交易建議。

主要特色：

• 使用 FINVIZ 產業數據進行跨產業主題偵測
• 方向感知評分（多頭與空頭主題）
• 生命週期成熟度評估，以識別擁擠交易 vs. 新興交易
• ETF 普及度評分（ETF 越多 = 主題越成熟/擁擠）
• 與上升趨勢儀表板整合，進行三點評估
• 透過 --scan-hits 提供股票層級的領導力證據
• 透過明確的股票籃子與代理 ETF 確認，提供主題匹配品質
• 根據異常波動/成交量/區間/相對強度指標排序的領導候選證據，市值僅作為風險區塊顯示
• 透過 --history-file 提供主題歷史與加速指標
• 雙模式運作：FINVIZ Elite（快速）或公開爬蟲（較慢，有限制）
• 基於 WebSearch 的頂級主題敘事確認

---

何時使用此技能

明確觸發條件：

• "現在哪個市場主題正在流行？"
• "哪些產業熱門/冷門？"
• "偵測當前市場主題"
• "最強的多頭/空頭敘事是什麼？"
• "AI/清潔能源/國防仍然是強勢主題嗎？"
• "產業輪動正朝哪個方向發展？"
• "顯示主題投資機會"

隱含觸發條件：

• 用戶欲了解廣泛的市場敘事轉變
• 用戶正在尋找主題式 ETF 或產業配置的想法
• 用戶詢問擁擠交易或晚週期主題
• 用戶想知道哪些主題正在新興 vs. 已經耗盡

何時不應使用：

• 個股分析（請改用 us-stock-analysis）
• 特定產業深入分析與圖表解讀（請改用 sector-analyst）
• 投資組合再平衡（請改用 portfolio-manager）
• 股利/收益投資（請改用 value-dividend-screener）

---

先決條件

必要條件：

• Python 3.9+ 與核心依賴套件。

  pip install -r skills/theme-detector/requirements.txt
  

Cron / 混合 Python 備用方案： 如果活躍的 python3 版本低於 3.10，或較新的 Hermes 虛擬環境缺少資料科學依賴套件，可透過 uv 使用明確的現代直譯器與臨時依賴套件來執行偵測器，而無需在 cron 執行中編輯環境：

uv run --python 3.12 \
  --with requests --with beautifulsoup4 --with lxml \
  --with pandas --with numpy --with yfinance \
  --with finvizfinance --with PyYAML \
  python skills/theme-detector/scripts/theme_detector.py \
  --finviz-api-key "$FINVIZ_API_KEY" \
  --fmp-api-key "$FMP_API_KEY" \
  --output-dir reports/

請將此作為設定上的變通方法，而非偵測器損壞的證據；仍應分別回報 FINVIZ/FMP/API 數據的限制。

可選 API Key：

FINVIZ Elite（建議使用，以獲得完整的產業覆蓋率與速度）：

export FINVIZ_API_KEY=your_finviz_elite_api_key_here

FMP API（可選，用於本益比估值數據）：

export FMP_API_KEY=your_fmp_api_key_here

需求清單包含 finvizfinance、PyYAML、pandas/numpy、requests 與 yfinance，因為正常公開模式執行時會匯入或使用它們。

沒有 FINVIZ Elite 時，此技能會使用公開的 FINVIZ 爬蟲（每個產業限制約 20 檔股票，速率限制較慢）。

---

工作流程

第一步：確認環境

檢查 API 金鑰是否已設定（參閱先決條件）：

# 驗證 FINVIZ Elite API 金鑰（可選，但建議）
echo $FINVIZ_API_KEY

# 驗證 FMP API 金鑰（可選）
echo $FMP_API_KEY

第二步：執行主題偵測腳本

執行主要偵測腳本：

python3 skills/theme-detector/scripts/theme_detector.py \
  --output-dir reports/

腳本選項：

# 完整執行（公開 FINVIZ 模式，無需 API 金鑰）
python3 skills/theme-detector/scripts/theme_detector.py \
  --output-dir reports/

# 使用 FINVIZ Elite API 金鑰
python3 skills/theme-detector/scripts/theme_detector.py \
  --finviz-api-key $FINVIZ_API_KEY \
  --output-dir reports/

# 使用 FMP API 金鑰以獲取增強股票數據
python3 skills/theme-detector/scripts/theme_detector.py \
  --fmp-api-key $FMP_API_KEY \
  --output-dir reports/

# 自訂限制
python3 skills/theme-detector/scripts/theme_detector.py \
  --max-themes 5 \
  --max-stocks-per-theme 10 \
  --output-dir reports/

# 明確指定 FINVIZ 模式
python3 skills/theme-detector/scripts/theme_detector.py \
  --finviz-mode public \
  --output-dir reports/

# 加入 Stockbee/Pradeep 風格的領導力證據
python3 skills/theme-detector/scripts/theme_detector.py \
  --scan-hits data/theme_scan_hits_YYYY-MM-DD.json \
  --narrative-scores data/theme_narrative_scores_YYYY-MM-DD.json \
  --history-file reports/theme_detector_history.json \
  --as-of-date YYYY-MM-DD \
  --output-dir reports/

掃描命中輸入合約： --scan-hits 接受 JSON、JSONL 或 CSV 格式。行可以預先標記 scan_type / scan_types，或是包含 symbol、return_5d、change_pct、volume、avg_volume_50d、relative_volume、true_range、atr_20、atr_expansion、close_location、industry、sector 與 theme_guess 等欄位的原始行。當原始行滿足多個規則時，它會擴展為多個命中。

初始掃描規則：

• five_day_20pct：return_5d >= 20
• ep9m：volume >= 9,000,000、relative_volume >= 2.0 且 change_pct >= 4
• range_expansion：change_pct >= 4、true_range / atr_20 >= 1.5 或 atr_expansion >= 1.5，且 close_location >= 0.75
• new_high：明確的 new_high / is_new_high，或 52 週新高證據
• high_rs：rs_rating >= 90 或標準化的 relative_strength >= 0.90

敘事分數輸入合約： --narrative-scores 是離線 JSON 輸入，而非即時 WebSearch 呼叫。它接受 {"Theme Name": 82} 或 {"themes": {"Theme Name": {"narrative_keyword_score": 82}}}。缺少敘事輸入會使 narrative_keyword_score 保持為 null，並降低 theme_match_coverage；它不會導致執行失敗。

預期執行時間：

• FINVIZ Elite 模式：約 2-3 分鐘（14+ 個主題）
• 公開 FINVIZ 模式：約 5-8 分鐘（受速率限制的爬蟲）

第三步：讀取並解析偵測結果

腳本會產生兩個輸出檔案：

• theme_detector_YYYY-MM-DD_HHMMSS.json - 結構化數據，供程式使用
• theme_detector_YYYY-MM-DD_HHMMSS.md - 人類可讀的報告

讀取 JSON 輸出以了解量化結果：

# 尋找最新報告
ls -lt reports/theme_detector_*.json | head -1

# 讀取 JSON 輸出
cat reports/theme_detector_YYYY-MM-DD_HHMMSS.json

第四步：透過 WebSearch 進行敘事確認

針對前 5 大主題（依主題熱度分數排序），執行 WebSearch 查詢以確認敘事強度：

搜尋模式：

"[主題名稱] 股票 市場 [當前月份] [當前年份]"
"[主題名稱] 產業 動能 [當前月份] [當前年份]"

評估敘事訊號：

• 強勢敘事：多家主要媒體報導該主題、分析師上調評級、政策催化劑
• 中等敘事：部分報導，情緒混雜，無明確催化劑
• 弱勢敘事：報導極少，或主要為反向/懷疑論調

根據發現更新信心水準：

• 量化高 + 敘事強 = 高信心
• 量化高 + 敘事弱 = 中信心（可能出現動能背離）
• 量化低 + 敘事強 = 中信心（敘事可能領先價格）
• 量化低 + 敘事弱 = 低信心

第五步：分析結果並提供建議

將偵測結果與知識庫進行交叉比對：

應參考的文件：

1. references/cross_sector_themes.md - 主題定義與組成產業
2. references/thematic_etf_catalog.md - 按主題分類的 ETF 曝險選項
3. references/theme_detection_methodology.md - 評分模型細節
4. references/finviz_industry_codes.md - 產業分類參考

分析框架：

對於熱門多頭主題（熱度 >= 70，方向 = 多頭）：

• 識別生命週期階段（新興 = 機會，成熟/耗盡 = 謹慎）
• 列出該主題中表現最佳的產業
• 推薦代理 ETF 以獲取曝險
• 若 ETF 普及度高，標記為擁擠交易警告

對於熱門空頭主題（熱度 >= 70，方向 = 空頭）：

• 識別承受壓力的產業
• 評估空頭動能正在加速還是減速
• 推薦避險策略或應避免的產業
• 若生命週期為成熟/耗盡階段，則注意潛在的平均回歸機會

對於新興主題（熱度 40-69，生命週期 = 新興）：

• 這些可能代表早期的輪動訊號
• 建議將其加入觀察清單進行監控
• 識別可能加速該主題的催化劑事件

對於耗盡主題（熱度 >= 60，生命週期 = 耗盡）：

• 警告擁擠交易風險
• 高 ETF 數量確認散戶過度參與
• 考慮反向操作或減少曝險

第六步：產生最終報告

使用報告範本結構向用戶呈現最終報告：

# 主題偵測報告
**日期：** YYYY-MM-DD
**模式：** FINVIZ Elite / 公開
**分析主題數：** N
**數據品質：** [備註任何限制]

## 主題儀表板
[頂級主題表格，包含熱度、方向、生命週期、信心水準]

## 今日變化
[新興主題、最大熱度加速、新的 EP9M 群聚、衰退中的主題]

## 領導力證據
[5D+20%、EP9M、區間擴張、創新高、高相對強度計數與領導者股票代碼]

## 多頭主題細節
[按熱度排序的多頭主題詳細分析]

## 空頭主題細節
[按熱度排序的空頭主題詳細分析]

## 所有主題摘要
[完整的主題排名表格]

## 產業排名
[表現最佳與最差的產業]

## 產業上升趨勢比率
[如有上升趨勢數據，則提供產業層級匯總]

## 方法論備註
[評分模型的簡要說明]

將報告儲存至 reports/ 目錄。

---

輸出

此技能會在 reports/ 目錄中產生兩個輸出檔案：

JSON 輸出 (theme_detector_YYYY-MM-DD_HHMMSS.json)：

{
  "report_type": "theme_detector",
  "generated_at": "2026-04-18 10:30:00",
  "metadata": {
    "generated_at": "2026-04-18 10:30:00",
    "data_mode": "full",
    "finviz_mode": "elite",
    "fmp_available": true,
    "max_themes": 14,
    "max_stocks_per_theme": 5,
    "data_sources": {
      "finviz_industries": 152,
      "yfinance_stocks": 68,
      "etf_volume": 24
    }
  },
  "summary": {
    "total_themes": 14,
    "bullish_count": 8,
    "bearish_count": 6,
    "top_bullish": "AI & 機器學習",
    "top_bearish": "區域銀行"
  },
  "themes": {
    "all": [
      {
        "name": "AI & 機器學習",
        "direction": "bullish",
        "heat": 85.3,
        "maturity": 42.1,
        "stage": "加速",
        "confidence": "中",
        "heat_label": "熱門",
        "industries": ["軟體 - 基礎設施", "半導體"],
        "representative_stocks": ["NVDA", "MSFT"],
        "stock_details": [{"symbol": "NVDA"}, {"symbol": "MSFT"}],
        "proxy_etfs": ["BOTZ", "ROBO"],
        "theme_match_score": 78.4,
        "theme_match_components": {
          "industry_match_score": 84.2,
          "static_stock_hit_score": 80.0,
          "proxy_etf_momentum_score": 70.0,
          "narrative_keyword_score": null
        },
        "leader_candidates": [
          {
            "symbol": "NVDA",
            "leader_score": 91.2,
            "scan_types": ["ep9m", "range_expansion"],
            "risk_bucket": "mega"
          }
        ],
        "theme_origin": "seed"
      }
    ],
    "bullish": [...],
    "bearish": [...],
    "match_ranked": [...]
  },
  "industry_rankings": {
    "top": [...],
    "bottom": [...]
  },
  "sector_uptrend": {...},
  "data_quality": {...}
}

Markdown 報告 (theme_detector_YYYY-MM-DD_HHMMSS.md)：

• 可排序的主題儀表板排名
• 多頭/空頭主題細節區段
• 產業表現排名
• 產業上升趨勢比率摘要
• 方法論備註

關鍵輸出欄位（每個主題）：

欄位	描述
heat	0-100 方向中性的主題強度
direction	"bullish"（領先）或 "bearish"（落後）
stage	新興 / 加速 / 趨勢 / 成熟 / 耗盡
confidence	低 / 中 / 高（腳本上限為「中」；WebSearch 可提升）
representative_stocks	該主題的頂級股票代碼
stock_details	所選代表的選擇性股票指標物件
proxy_etfs	主題式 ETF 代碼（長度 = ETF 數量；越高代表越擁擠）