Back to Details

theme-detector

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Theme Detector

主题检测器

Overview

概述

This skill detects and ranks trending market themes by analyzing cross-sector momentum, volume, and breadth signals. It identifies both bullish (upward momentum) and bearish (downward pressure) themes, assesses lifecycle maturity (early/mid/late/exhaustion), and provides a confidence score combining quantitative data with narrative analysis.
3-Dimensional Scoring Model:
  1. Theme Heat (0-100): Direction-neutral strength of the theme (momentum, volume, uptrend ratio, breadth)
  2. Lifecycle Maturity: Stage classification (Early / Mid / Late / Exhaustion) based on duration, extremity clustering, valuation, and ETF proliferation
  3. Confidence (Low / Medium / High): Reliability of the detection, combining quantitative breadth with narrative confirmation
Key Features:
  • Cross-sector theme detection using FINVIZ industry data
  • Direction-aware scoring (bullish and bearish themes)
  • Lifecycle maturity assessment to identify crowded vs. emerging trades
  • ETF proliferation scoring (more ETFs = more mature/crowded theme)
  • Integration with uptrend-dashboard for 3-point evaluation
  • Dual-mode operation: FINVIZ Elite (fast) or public scraping (slower, limited)
  • WebSearch-based narrative confirmation for top themes
本技能通过分析跨板块的动量、成交量和广度信号，检测并排名热门市场主题。它会识别看多（上涨动量）和看空（下跌压力）主题，评估生命周期成熟度（早期/中期/晚期/衰竭），并结合量化数据与叙事分析给出置信度评分。
三维评分模型：
  1. 主题热度（0-100）：主题的方向中性强度（动量、成交量、上涨趋势比率、广度）
  2. 生命周期成熟度：基于持续时间、极端值聚类、估值和ETF扩散情况的阶段分类（早期/中期/晚期/衰竭）
  3. 置信度（低/中/高）：检测结果的可靠性，结合量化广度与叙事确认
核心功能：
  • 利用FINVIZ行业数据进行跨板块主题检测
  • 方向感知评分（看多和看空主题）
  • 生命周期成熟度评估，识别拥挤交易与新兴交易
  • ETF扩散评分（ETF数量越多，主题越成熟/拥挤）
  • 与上涨趋势仪表板集成，进行三点评估
  • 双模式运行：FINVIZ Elite（快速）或公开抓取（较慢、受限）
  • 基于WebSearch的热门主题叙事确认

When to Use This Skill

何时使用本技能

Explicit Triggers:
  • "What market themes are trending right now?"
  • "Which sectors are hot/cold?"
  • "Detect current market themes"
  • "What are the strongest bullish/bearish narratives?"
  • "Is AI/clean energy/defense still a strong theme?"
  • "Where is sector rotation heading?"
  • "Show me thematic investing opportunities"
Implicit Triggers:
  • User wants to understand broad market narrative shifts
  • User is looking for thematic ETF or sector allocation ideas
  • User asks about crowded trades or late-cycle themes
  • User wants to know which themes are emerging vs. exhausted
When NOT to Use:
  • Individual stock analysis (use us-stock-analysis instead)
  • Specific sector deep-dive with chart reading (use sector-analyst instead)
  • Portfolio rebalancing (use portfolio-manager instead)
  • Dividend/income investing (use value-dividend-screener instead)
明确触发场景：
  • "当前有哪些热门市场主题？"
  • "哪些板块热门/遇冷？"
  • "检测当前市场主题"
  • "最强的看多/看空叙事有哪些？"
  • "AI/清洁能源/国防仍是强势主题吗？"
  • "板块轮动的方向是什么？"
  • "为我展示主题投资机会"
隐含触发场景：
  • 用户想要了解广泛的市场叙事转变
  • 用户正在寻找主题ETF或板块配置思路
  • 用户询问拥挤交易或周期晚期主题
  • 用户想要了解哪些主题正在兴起哪些已经衰竭
何时不使用：
  • 个股分析（请使用us-stock-analysis）
  • 结合图表阅读的特定板块深度分析（请使用sector-analyst）
  • 投资组合再平衡（请使用portfolio-manager）
  • 股息/收益投资（请使用value-dividend-screener）

Workflow

工作流程

Step 1: Verify Requirements

步骤1：验证要求

Check for required API keys and dependencies:
bash
undefined
检查所需的API密钥和依赖项：
bash
undefined

Check for FINVIZ Elite API key (optional but recommended)

检查FINVIZ Elite API密钥（可选但推荐）

echo $FINVIZ_API_KEY
echo $FINVIZ_API_KEY

Check for FMP API key (optional, used for valuation metrics)

检查FMP API密钥（可选，用于估值指标）

echo $FMP_API_KEY

**Requirements:**
- **Python 3.7+** with `requests`, `beautifulsoup4`, `lxml`
- **FINVIZ Elite API key** (recommended for full industry coverage and speed)
- **FMP API key** (optional, for P/E ratio valuation data)
- Without FINVIZ Elite, the skill uses public FINVIZ scraping (limited to ~20 stocks per industry, slower rate limits)

**Installation:**
```bash
pip install requests beautifulsoup4 lxml
echo $FMP_API_KEY

**要求：**
- **Python 3.7+**，并安装`requests`、`beautifulsoup4`、`lxml`
- **FINVIZ Elite API密钥**（推荐，用于完整的行业覆盖和更快速度）
- **FMP API密钥**（可选，用于市盈率估值数据）
- 若无FINVIZ Elite，本技能将使用公开FINVIZ抓取（每个行业限约20只股票，速率限制更严格）

**安装：**
```bash
pip install requests beautifulsoup4 lxml

Step 2: Execute Theme Detection Script

步骤2：执行主题检测脚本

Run the main detection script:
bash
python3 skills/theme-detector/scripts/theme_detector.py \
  --output-dir reports/
Script Options:
bash
undefined
运行主检测脚本：
bash
python3 skills/theme-detector/scripts/theme_detector.py \
  --output-dir reports/
脚本选项：
bash
undefined

Full run (public FINVIZ mode, no API key required)

完整运行（公开FINVIZ模式，无需API密钥）

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

With FINVIZ Elite API key

使用FINVIZ Elite API密钥

python3 skills/theme-detector/scripts/theme_detector.py
--finviz-api-key $FINVIZ_API_KEY
--output-dir reports/
python3 skills/theme-detector/scripts/theme_detector.py
--finviz-api-key $FINVIZ_API_KEY
--output-dir reports/

With FMP API key for enhanced stock data

使用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
--fmp-api-key $FMP_API_KEY
--output-dir reports/

Custom limits

自定义限制

python3 skills/theme-detector/scripts/theme_detector.py
--max-themes 5
--max-stocks-per-theme 5
--output-dir reports/
python3 skills/theme-detector/scripts/theme_detector.py
--max-themes 5
--max-stocks-per-theme 5
--output-dir reports/

Explicit FINVIZ mode

明确指定FINVIZ模式

python3 skills/theme-detector/scripts/theme_detector.py
--finviz-mode public
--output-dir reports/

**Expected Execution Time:**
- FINVIZ Elite mode: ~2-3 minutes (14+ themes)
- Public FINVIZ mode: ~5-8 minutes (rate-limited scraping)
python3 skills/theme-detector/scripts/theme_detector.py
--finviz-mode public
--output-dir reports/

**预计执行时间：**
- FINVIZ Elite模式：约2-3分钟（14+个主题）
- 公开FINVIZ模式：约5-8分钟（受速率限制的抓取）

Step 3: Read and Parse Detection Results

步骤3：读取并解析检测结果

The script generates two output files:
  • theme_detector_YYYY-MM-DD_HHMMSS.json
    - Structured data for programmatic use
  • theme_detector_YYYY-MM-DD_HHMMSS.md
    - Human-readable report
Read the JSON output to understand quantitative results:
bash
undefined
脚本会生成两个输出文件：
  • theme_detector_YYYY-MM-DD_HHMMSS.json
    - 供程序使用的结构化数据
  • theme_detector_YYYY-MM-DD_HHMMSS.md
    - 人类可读的报告
读取JSON输出以了解量化结果：
bash
undefined

Find the latest report

查找最新报告

ls -lt reports/theme_detector_*.json | head -1
ls -lt reports/theme_detector_*.json | head -1

Read the JSON output

读取JSON输出

cat reports/theme_detector_YYYY-MM-DD_HHMMSS.json
undefined
cat reports/theme_detector_YYYY-MM-DD_HHMMSS.json
undefined

Step 4: Perform Narrative Confirmation via WebSearch

步骤4：通过WebSearch进行叙事确认

For the top 5 themes (by Theme Heat score), execute WebSearch queries to confirm narrative strength:
Search Pattern:
"[theme name] stocks market [current month] [current year]"
"[theme name] sector momentum [current month] [current year]"
Evaluate narrative signals:
  • Strong narrative: Multiple major outlets covering the theme, analyst upgrades, policy catalysts
  • Moderate narrative: Some coverage, mixed sentiment, no clear catalyst
  • Weak narrative: Little coverage, or predominantly contrarian/skeptical tone
Update Confidence levels based on findings:
  • Quantitative High + Narrative Strong = High confidence
  • Quantitative High + Narrative Weak = Medium confidence (possible momentum divergence)
  • Quantitative Low + Narrative Strong = Medium confidence (narrative may lead price)
  • Quantitative Low + Narrative Weak = Low confidence
对于前5个主题（按主题热度评分），执行WebSearch查询以确认叙事强度：
搜索模式：
"[主题名称] stocks market [当前月份] [当前年份]"
"[主题名称] sector momentum [当前月份] [当前年份]"
评估叙事信号：
  • 强叙事：多个主流媒体报道该主题，分析师上调评级，存在政策催化剂
  • 中等叙事：有一定报道，情绪混杂，无明确催化剂
  • 弱叙事：报道极少，或主要为反向/怀疑论调
根据发现更新置信度等级：
  • 量化高 + 叙事强 = 高置信度
  • 量化高 + 叙事弱 = 中置信度（可能存在动量背离）
  • 量化低 + 叙事强 = 中置信度（叙事可能引领价格）
  • 量化低 + 叙事弱 = 低置信度

Step 5: Analyze Results and Provide Recommendations

步骤5：分析结果并提供建议

Cross-reference detection results with knowledge bases:
Reference Documents to Consult:
  1. references/cross_sector_themes.md
    - Theme definitions and constituent industries
  2. references/thematic_etf_catalog.md
    - ETF exposure options by theme
  3. references/theme_detection_methodology.md
    - Scoring model details
  4. references/finviz_industry_codes.md
    - Industry classification reference
Analysis Framework:
For Hot Bullish Themes (Heat >= 70, Direction = Bullish):
  • Identify lifecycle stage (Early = opportunity, Late/Exhaustion = caution)
  • List top-performing industries within the theme
  • Recommend proxy ETFs for exposure
  • Flag if ETF proliferation is high (crowded trade warning)
For Hot Bearish Themes (Heat >= 70, Direction = Bearish):
  • Identify industries under pressure
  • Assess if bearish momentum is accelerating or decelerating
  • Recommend hedging strategies or sectors to avoid
  • Note potential mean-reversion opportunities if lifecycle is Late/Exhaustion
For Emerging Themes (Heat 40-69, Lifecycle = Early):
  • These may represent early rotation signals
  • Recommend monitoring with watchlist
  • Identify catalyst events that could accelerate the theme
For Exhausted Themes (Heat >= 60, Lifecycle = Exhaustion):
  • Warn about crowded trade risk
  • High ETF count confirms excessive retail participation
  • Consider contrarian positioning or reducing exposure
将检测结果与知识库交叉参考：
需查阅的参考文档：
  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数量证实散户参与过度
  • 考虑反向仓位或减少敞口

Step 6: Generate Final Report

步骤6：生成最终报告

Present the final report to the user using the report template structure:
markdown
undefined
使用报告模板结构向用户呈现最终报告：
markdown
undefined

Theme Detection Report

主题检测报告

Date: YYYY-MM-DD Mode: FINVIZ Elite / Public Themes Analyzed: N Data Quality: [note any limitations]
日期： YYYY-MM-DD 模式： FINVIZ Elite / 公开 分析主题数量： N 数据质量： [注明任何限制]

Theme Dashboard

主题仪表板

[Top themes table with Heat, Direction, Lifecycle, Confidence]
[包含热度、方向、生命周期、置信度的热门主题表格]

Bullish Themes Detail

看多主题详情

[Detailed analysis of bullish themes sorted by Heat]
[按热度排序的看多主题详细分析]

Bearish Themes Detail

看空主题详情

[Detailed analysis of bearish themes sorted by Heat]
[按热度排序的看空主题详细分析]

All Themes Summary

所有主题摘要

[Complete theme ranking table]
[完整的主题排名表格]

Industry Rankings

行业排名

[Top performing and worst performing industries]
[表现最佳和最差的行业]

Sector Uptrend Ratios

板块上涨趋势比率

[Sector-level aggregation if uptrend data available]
[若有上涨趋势数据，展示板块层面的汇总]

Methodology Notes

方法说明

[Brief explanation of scoring model]

Save the report to `reports/` directory.

---
[评分模型的简要解释]

将报告保存到`reports/`目录。

---

Resources

资源

Scripts Directory (
scripts/
)

脚本目录（
scripts/
）

Main Scripts:
  • theme_detector.py
    - Main orchestrator script
    • Coordinates industry data collection, theme classification, and scoring
    • Generates JSON + Markdown output
    • Usage: 
      python3 theme_detector.py [options]
  • theme_classifier.py
    - Maps industries to cross-sector themes
    • Reads theme definitions from 
      cross_sector_themes.md
    • Calculates theme-level aggregated scores
    • Determines direction (bullish/bearish) from constituent industries
  • finviz_industry_scanner.py
    - FINVIZ industry data collection
    • Elite mode: CSV export with full stock data per industry
    • Public mode: Web scraping with rate limiting
    • Extracts: performance, volume, change%, avg volume, market cap
  • lifecycle_analyzer.py
    - Lifecycle maturity assessment
    • Duration scoring, extremity clustering, valuation analysis
    • ETF proliferation scoring from thematic_etf_catalog.md
    • Stage classification: Early / Mid / Late / Exhaustion
  • report_generator.py
    - Report output generation
    • Markdown report from template
    • JSON structured output
    • Theme dashboard formatting
主要脚本：
  • theme_detector.py
    - 主协调脚本
    • 协调行业数据收集、主题分类和评分
    • 生成JSON + Markdown输出
    • 使用方式：
      python3 theme_detector.py [选项]
  • theme_classifier.py
    - 将行业映射到跨板块主题
    • 从
      cross_sector_themes.md
      读取主题定义
    • 计算主题层面的汇总评分
    • 根据成分行业确定方向（看多/看空）
  • finviz_industry_scanner.py
    - FINVIZ行业数据收集
    • Elite模式：导出包含每个行业完整股票数据的CSV
    • 公开模式：带速率限制的网页抓取
    • 提取数据：表现、成交量、涨跌幅、平均成交量、市值
  • lifecycle_analyzer.py
    - 生命周期成熟度评估
    • 持续时间评分、极端值聚类、估值分析
    • 从thematic_etf_catalog.md获取ETF扩散评分
    • 阶段分类：早期/中期/晚期/衰竭
  • report_generator.py
    - 报告输出生成
    • 基于模板生成Markdown报告
    • JSON结构化输出
    • 主题仪表板格式化

References Directory (
references/
)

参考目录（
references/
）

Knowledge Bases:
  • cross_sector_themes.md
    - Theme definitions with industries, ETFs, stocks, and matching criteria
  • thematic_etf_catalog.md
    - Comprehensive thematic ETF catalog with counts per theme
  • finviz_industry_codes.md
    - Complete FINVIZ industry-to-filter-code mapping
  • theme_detection_methodology.md
    - Technical documentation of the 3D scoring model
知识库：
  • cross_sector_themes.md
    - 主题定义，包含行业、ETF、股票和匹配标准
  • thematic_etf_catalog.md
    - 全面的主题ETF目录，按主题统计数量
  • finviz_industry_codes.md
    - 完整的FINVIZ行业与筛选代码映射
  • theme_detection_methodology.md
    - 三维评分模型的技术文档

Assets Directory (
assets/
)

资源目录（
assets/
）

  • report_template.md
    - Markdown template for report generation with placeholder format
  • report_template.md
    - 用于生成报告的Markdown模板，包含占位符格式

Important Notes

重要说明

FINVIZ Mode Differences

FINVIZ模式差异

FeatureElite ModePublic Mode
Industry coverageAll ~145 industriesAll ~145 industries
Stocks per industryFull universe~20 stocks (page 1)
Rate limiting0.5s between requests2.0s between requests
Data freshnessReal-time15-min delayed
API key requiredYes ($39.99/mo)No
Execution time~2-3 minutes~5-8 minutes
特性Elite模式公开模式
行业覆盖全部约145个行业全部约145个行业
每个行业的股票数量全市场股票约20只股票（第一页）
速率限制请求间隔0.5秒请求间隔2.0秒
数据新鲜度实时延迟15分钟
是否需要API密钥是（39.99美元/月）否
执行时间约2-3分钟约5-8分钟

Direction Detection Logic

方向检测逻辑

Theme direction (bullish vs. bearish) is determined by:
  1. Weighted industry performance: Average change% across constituent industries, weighted by market cap
  2. Uptrend ratio: Percentage of stocks in each industry that are in technical uptrends (if uptrend data available)
  3. Volume confirmation: Whether volume supports the price direction (accumulation vs. distribution)
A theme is classified as:
  • Bullish: Weighted performance > 0 AND (uptrend ratio > 50% OR volume accumulation confirmed)
  • Bearish: Weighted performance < 0 AND (uptrend ratio < 50% OR volume distribution confirmed)
  • Neutral: Mixed signals or insufficient data
主题方向（看多 vs 看空）由以下因素决定：
  1. 加权行业表现：成分行业的平均涨跌幅，按市值加权
  2. 上涨趋势比率：每个行业中处于技术上涨趋势的股票占比（若有上涨趋势数据）
  3. 成交量确认：成交量是否支持价格方向（吸筹 vs 派发）
主题分类规则：
  • 看多：加权表现>0 且（上涨趋势比率>50% 或 确认吸筹成交量）
  • 看空：加权表现<0 且（上涨趋势比率<50% 或 确认派发成交量）
  • 中性：信号混杂或数据不足

Known Limitations

已知限制

  1. Survivorship bias: Only analyzes currently listed stocks and ETFs
  2. Lag: FINVIZ data may lag intraday moves by 15 minutes (public mode)
  3. Theme boundaries: Some stocks fit multiple themes; classification uses primary industry
  4. ETF proliferation: Catalog is static and may not capture very new ETFs
  5. Narrative scoring: WebSearch-based and inherently subjective
  6. Public mode limitation: ~20 stocks per industry may miss small-cap signals
  1. 幸存者偏差：仅分析当前上市的股票和ETF
  2. 延迟：FINVIZ数据可能延迟盘中走势15分钟（公开模式）
  3. 主题边界：部分股票可归入多个主题；分类使用主要行业
  4. ETF扩散：目录为静态，可能未收录最新的ETF
  5. 叙事评分：基于WebSearch，本质上具有主观性
  6. 公开模式限制：每个行业约20只股票，可能遗漏小盘股信号

Disclaimer

免责声明

This analysis is for educational and informational purposes only.
  • Not investment advice
  • Past thematic trends do not guarantee future performance
  • Theme detection identifies momentum, not fundamental value
  • Conduct your own research before making investment decisions
Version: 1.0 Last Updated: 2026-02-16 API Requirements: FINVIZ Elite (recommended) or public mode (free); FMP API optional Execution Time: ~2-8 minutes depending on mode Output Formats: JSON + Markdown Themes Covered: 14+ cross-sector themes
本分析仅用于教育和信息目的。
  • 不构成投资建议
  • 过往主题趋势不代表未来表现
  • 主题检测识别的是动量，而非基本面价值
  • 做出投资决策前请自行研究
版本： 1.0 最后更新： 2026-02-16 API要求： FINVIZ Elite（推荐）或公开模式（免费）；FMP API可选 执行时间： 约2-8分钟，取决于运行模式 输出格式： JSON + Markdown 覆盖主题： 14+个跨板块主题