theme-detector

主题检测器

概述

此技能通过分析跨行业的动量、成交量和广度信号，检测并排列热门市场主题。它既能识别看涨（上行动量）主题，也能识别看跌（下行压力）主题，评估主题的生命周期成熟度（新兴／加速／热门／成熟／衰退），并提供结合定量数据与叙事分析的置信度评分。

三维评分模型：

1. 主题热度（0–100）：主题的方向中性强度（动量、成交量、上升趋势比率、广度）
2. 生命周期成熟度：根据持续时间、极端值聚集、估值和 ETF 扩张情况划分阶段（新兴／加速／热门／成熟／衰退）
3. 置信度（低／中／高）：检测结果的可靠性，结合定量广度与叙事确认。脚本输出的置信度最高为中；Claude 的 WebSearch 叙事确认步骤可将其提升至高。

主要功能：

• 使用 FINVIZ 行业数据检测跨行业主题
• 方向感知型评分（看涨和看跌主题）
• 评估生命周期成熟度，以识别拥挤交易与新兴交易
• ETF 扩张评分（ETF 越多，主题越成熟／越拥挤）
• 集成 uptrend-dashboard，进行三点评估
• 双模式运行：FINVIZ Elite（快速）或公开抓取（较慢且有限）
• 基于 WebSearch 的热门主题叙事确认

---

何时使用此技能

明确触发条件：

• “当前有哪些市场主题正在走热？”
• “哪些行业热门／遇冷？”
• “检测当前市场主题”
• “最强的看涨／看跌叙事是什么？”
• “AI／清洁能源／国防仍然是强势主题吗？”
• “行业轮动将走向何方？”
• “为我展示主题投资机会”

隐式触发条件：

• 用户想了解更广泛的市场叙事变化
• 用户正在寻找主题 ETF 或行业配置思路
• 用户询问拥挤交易或周期后期主题
• 用户想知道哪些主题正在兴起，哪些已经衰退

不适用场景：

• 个股分析（改用 us-stock-analysis）
• 结合图表解读的特定行业深度分析（改用 sector-analyst）
• 投资组合再平衡（改用 portfolio-manager）
• 股息／收益型投资（改用 value-dividend-screener）

---

先决条件

必需：

• Python 3.7+ 及核心依赖：

  pip install requests beautifulsoup4 lxml pandas numpy yfinance
  

可选 API 密钥：

FINVIZ Elite（建议使用，以覆盖全部行业并提高速度）：

export FINVIZ_API_KEY=your_finviz_elite_api_key_here

FMP API（可选，用于获取市盈率估值数据）：

export FMP_API_KEY=your_fmp_api_key_here

可选 Python 软件包：

• finvizfinance - FINVIZ Elite 模式所需
• PyYAML - 使用自定义主题 --themes-config 所需

如果没有 FINVIZ Elite，此技能将使用 FINVIZ 公开页面抓取数据（每个行业仅限约 20 只股票，且速率限制更严格）。

---

工作流

步骤 1：验证环境

检查是否已配置 API 密钥（参见先决条件）：

# Verify FINVIZ Elite API key (optional but recommended)
echo $FINVIZ_API_KEY

# Verify FMP API key (optional)
echo $FMP_API_KEY

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

运行主检测脚本：

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

脚本选项：

# Full run (public FINVIZ mode, no API key required)
python3 skills/theme-detector/scripts/theme_detector.py \
  --output-dir reports/

# With FINVIZ Elite API key
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
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 10 \
  --output-dir reports/

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

预计执行时间：

• FINVIZ Elite 模式：约 2–3 分钟（14 个以上主题）
• FINVIZ 公开模式：约 5–8 分钟（受速率限制的页面抓取）

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

脚本会生成两个输出文件：

• theme_detector_YYYY-MM-DD_HHMMSS.json - 供程序使用的结构化数据
• theme_detector_YYYY-MM-DD_HHMMSS.md - 便于阅读的报告

读取 JSON 输出以了解定量结果：

# Find the latest report
ls -lt reports/theme_detector_*.json | head -1

# Read the JSON output
cat reports/theme_detector_YYYY-MM-DD_HHMMSS.json

步骤 4：通过 WebSearch 确认叙事强度

针对热度得分排名前 5 的主题，执行 WebSearch 查询以确认叙事强度：

搜索模式：

"[theme name] stocks market [current month] [current year]"
"[theme name] sector momentum [current month] [current year]"

评估叙事信号：

• 强叙事：多家主流媒体报道该主题，分析师上调评级，存在政策催化因素
• 中等叙事：有一些报道，市场情绪不一，没有明确的催化因素
• 弱叙事：报道较少，或整体基调以逆势、怀疑为主

根据调查结果更新置信度：

• 量化结果为高 + 叙事强 = 高置信度
• 量化结果为高 + 叙事弱 = 中置信度（可能出现动能背离）
• 量化结果为低 + 叙事强 = 中置信度（叙事可能领先于价格）
• 量化结果为低 + 叙事弱 = 低置信度

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

将检测结果与知识库交叉比对：

需要查阅的参考文档：

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 数量较多证实散户参与过度
• 考虑采取逆势仓位或减少敞口

步骤 6：生成最终报告

使用报告模板结构向用户呈现最终报告：

# Theme Detection Report
**Date:** YYYY-MM-DD
**Mode:** FINVIZ Elite / Public
**Themes Analyzed:** N
**Data Quality:** [note any limitations]

## 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]

将报告保存到 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 & Machine Learning",
    "top_bearish": "Regional Banks"
  },
  "themes": {
    "all": [
      {
        "name": "AI & Machine Learning",
        "direction": "bullish",
        "heat": 85.3,
        "maturity": 42.1,
        "stage": "Accelerating",
        "confidence": "Medium",
        "heat_label": "Hot",
        "industries": ["Software - Infrastructure", "Semiconductors"],
        "representative_stocks": [{"symbol": "NVDA"}, {"symbol": "MSFT"}],
        "proxy_etfs": ["BOTZ", "ROBO"],
        "theme_origin": "seed"
      }
    ],
    "bullish": [...],
    "bearish": [...]
  },
  "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	该主题的代表性股票（含 symbol 和指标的对象列表）
proxy_etfs	主题 ETF 代码（数量 = ETF 数量；越多表示交易越拥挤）
theme_origin	"seed"（来自 YAML 配置）或 "discovered"（自动聚类发现）

---

资源

脚本目录（scripts/）

主要脚本：

• theme_detector.py - 主协调脚本

  • 协调行业数据收集、主题分类和评分
  • 生成 JSON + Markdown 输出
  • 用法：python3 theme_detector.py [options]

• theme_classifier.py - 将行业映射到跨行业主题

  • 从 cross_sector_themes.md 读取主题定义
  • 计算主题级汇总分数
  • 根据所属行业确定方向（看涨 / 看跌）
  • 显示映射：“bullish” → “LEAD”，“bearish” → “LAG”（参见 report_generator.py::_direction_label()）

• finviz_industry_scanner.py - FINVIZ 行业数据收集

  • 精英模式：导出包含各行业完整股票数据的 CSV
  • 公共模式：进行网页抓取并限制请求频率
  • 提取：表现、成交量、涨跌幅、平均成交量、市值

• calculators/lifecycle_calculator.py - 生命周期成熟度评估

  • 持续时间评分、极端程度聚类、估值分析
  • 根据 thematic_etf_catalog.md 进行 ETF 普及度评分
  • 阶段分类：Emerging / Accelerating / Trending / Mature / Exhausting

• report_generator.py - 报告输出生成

  • 根据模板生成 Markdown 报告
  • 生成 JSON 结构化输出
  • 格式化主题仪表板

参考资料目录（references/）

知识库：

• cross_sector_themes.md - 主题定义，包含行业、ETF、股票和匹配条件
• thematic_etf_catalog.md - 全面的主题 ETF 目录，包含各主题的数量
• finviz_industry_codes.md - 完整的 FINVIZ 行业到筛选代码映射
• theme_detection_methodology.md - 3D 评分模型的技术文档

资源目录（assets/）

• report_template.md - 用于生成报告的 Markdown 模板，包含占位符格式

---

重要说明

FINVIZ 模式差异

功能	精英模式	公共模式
行业覆盖范围	全部约 145 个行业	全部约 145 个行业
每个行业的股票数	完整范围	约 20 只股票（第 1 页）
请求频率限制	请求间隔 0.5 秒	请求间隔 2.0 秒
数据时效性	实时	延迟 15 分钟
是否需要 API 密钥	是（$39.50/月）	否
执行时间	约 2–3 分钟	约 5–8 分钟

方向检测逻辑

主题方向由所属行业的相对排名进行多数表决确定：

1. 行业排名：根据多时间范围动量分数对全部约 145 个行业进行排名
2. 基于排名的方向：排名列表前半部分的行业归类为“看涨”，后半部分归类为“看跌”
3. 主题多数表决：_majority_direction() 统计各主题中的看涨与看跌行业；得票较多的一方胜出

显示映射：“bullish” → LEAD，“bearish” → LAG（参见 report_generator.py::_direction_label()）

LEAD 主题表示其所属行业表现相对优异。LAG 主题仍可能有正的绝对回报——它表示相对表现不佳，并非做空信号。

已知限制

1. 幸存者偏差：仅分析当前上市的股票和 ETF
2. 延迟：FINVIZ 数据可能比盘中变动延迟 15 分钟（公共模式）
3. 主题边界：部分股票适合归入多个主题；分类时采用其主要行业
4. ETF 普及度：目录为静态内容，可能未涵盖非常新的 ETF
5. 叙事评分：基于 WebSearch，具有固有的主观性
6. 公共模式限制：每个行业约 20 只股票，可能遗漏小盘股信号

免责声明

本分析仅用于教育和信息参考。

• 不构成投资建议
• 过去的主题趋势不保证未来表现
• 主题识别用于发现动能，而非基本面价值
• 做出投资决策前，请自行进行研究

---

版本： 1.0 最后更新： 2026-02-16 API 要求： FINVIZ Elite（推荐）或公共模式（免费）；FMP API 可选 执行时间： 约 2-8 分钟，具体取决于模式 输出格式： JSON + Markdown 涵盖主题： 14 个以上跨行业主题