theme-detector

主题检测器

概览

此技能通过分析跨行业动能、成交量和广度信号，检测并排序热门市场主题。它既能识别看涨（向上动能）主题，也能识别看跌（下行压力）主题，评估主题所处的生命周期阶段（新兴/加速/趋势形成/成熟/衰竭），并结合量化数据与叙事分析给出置信度评分。

三维评分模型：

1. 主题热度（0-100）：主题的方向中性强度（动能、成交量、上升趋势比例、广度）
2. 生命周期成熟度：根据持续时间、极值聚集、估值和 ETF 增多情况划分阶段（新兴/加速/趋势形成/成熟/衰竭）
3. 置信度（低/中/高）：检测结果的可靠性，结合量化广度与叙事确认。脚本输出的置信度最高为中；Claude 的 WebSearch 叙事确认步骤可将其提升至高。
4. 股票领涨情况：可选的每日扫描命中证据，来自 5D+20%、EP9M、区间扩张、创新高和高 RS 股票。提供这些数据时，会将其纳入主题热度 v2；未提供时，会降低置信度覆盖度，但不会强制将领涨情况归零。
5. 主题匹配质量：根据行业参与度、明确的股票篮子命中情况、代理 ETF 确认以及可选的离线叙事评分，评估主题匹配的具体程度。这反映的是证据质量，而非交易建议。

主要功能：

• 使用 FINVIZ 行业数据检测跨行业主题
• 方向感知评分（看涨和看跌主题）
• 评估生命周期成熟度，识别拥挤交易与新兴交易
• ETF 增多情况评分（ETF 越多，主题越成熟/越拥挤）
• 与 uptrend-dashboard 集成，进行三点式评估
• 通过 --scan-hits 提供个股层面的领涨证据
• 通过明确的股票篮子和代理 ETF 确认评估主题匹配质量
• 根据异常走势/成交量/区间/RS 指标排序领涨候选股，市值仅显示为风险类别
• 通过 --history-file 获取主题历史和加速指标
• 双模式运行：FINVIZ Elite（快速）或公开抓取（较慢，受限）
• 基于 WebSearch 对热门主题进行叙事确认

---

何时使用此技能

明确触发条件：

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

隐含触发条件：

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

不适用场景：

• 个股分析（改用 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 venv 缺少数据科学依赖项，请通过 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 密钥：

FINVIZ Elite（建议使用，以获得完整的行业覆盖和更快的速度）：

export FINVIZ_API_KEY=your_finviz_elite_api_key_here

FMP API（可选，用于 P/E 比率估值数据）：

export FMP_API_KEY=your_fmp_api_key_here

依赖项包括 finvizfinance、PyYAML、pandas/numpy、requests 和 yfinance，因为普通公开模式的执行会导入或使用这些依赖项。

如果没有 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/

# Add Stockbee/Pradeep-style leadership evidence
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 分钟（受速率限制的抓取）

步骤 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 的主题（按 Theme Heat 评分），执行 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]

## What Changed Today
[Newly emerging themes, largest heat acceleration, new EP9M clusters, fading themes]

## Leadership Evidence
[5D+20%, EP9M, range expansion, new highs, high-RS counts and leader symbols]

## 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": ["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 数量；数量越多越拥挤）
theme_match_score	0-100 的证据质量分数，依据行业、股票组合命中、代理 ETF 确认及可选叙述输入计算
theme_match_components	可检查的子分数，用于说明主题匹配情况
leader_candidates	按证据排名的主题相关代码；不提供入场/止损/失效指导
fresh_leadership_symbols	当前运行中具有 EP9M、区间扩张或创新高证据的代码
extended_symbols	当前运行中具有 5D+20% 证据的代码；仅用作过度延伸证据
theme_origin	"seed"（来自 YAML 配置）或 "discovered"（自动聚类）

---

资源

Scripts 目录（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 行业数据

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

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

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

• report_generator.py - 生成报告输出

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

References 目录（references/）

知识库：

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

Assets 目录（assets/）

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

---

交易所日历与回放

运行检测器前，请先安装 requirements.txt。--as-of-date 是严格的 YYYY-MM-DD 截止日期，上升趋势新鲜度检查和提供方历史数据窗口都会使用该日期。由于 FINVIZ、报价、简介和上升趋势输入均为实时数据，而非 PIT 快照，因此非当前的 --as-of-date 会导致操作失败关闭。新鲜度计算会统计 XNYS 交易时段，并排除日期在未来的数据行。

重要说明

FINVIZ 模式差异

特性	Elite 模式	Public 模式
行业覆盖范围	全部约 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 分钟（Public 模式）
3. 主题边界：某些股票符合多个主题；分类采用其主要行业
4. ETF 普及度：目录为静态数据，可能未收录非常新的 ETF
5. 叙事评分：基于 WebSearch，且本质上带有主观性
6. Public 模式的局限：每个行业约 20 只股票，可能遗漏小盘股信号

免责声明

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

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

---

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