theme-detector

主题检测器

概述

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

三维评分模型：

1. 主题热度（0-100）：主题的方向中性强度（动量、成交量、上升趋势比例、广度）
2. 生命周期成熟度：根据持续时间、极值聚集、估值和 ETF 数量判定阶段（早期／中期／后期／衰竭）
3. 置信度（低／中／高）：检测结果的可靠性，结合定量广度与叙事确认

主要功能：

• 使用 FINVIZ 行业数据检测跨行业主题
• 方向感知评分（看涨和看跌主题）
• 评估生命周期成熟度，识别交易是否拥挤或仍在形成
• ETF 数量评分（ETF 越多，主题越成熟／越拥挤）
• 与 uptrend-dashboard 集成，进行三点评估
• 双模式运行：FINVIZ Elite（快速）或公开网页抓取（较慢，功能受限）
• 基于 WebSearch 对热门主题进行叙事确认

---

何时使用此技能

明确触发条件：

• “当前有哪些市场主题很热门？”
• “哪些板块表现强劲／疲软？”
• “检测当前市场主题”
• “最强劲的看涨／看跌叙事是什么？”
• “AI／清洁能源／国防主题仍然强劲吗？”
• “板块轮动的方向是什么？”
• “给我看看主题投资机会”

隐含触发条件：

• 用户想了解广泛的市场叙事变化
• 用户在寻找主题 ETF 或板块配置思路
• 用户询问交易是否拥挤或主题是否处于周期后期
• 用户想知道哪些主题正在形成，哪些已经衰竭

不适用场景：

• 个股分析（改用 us-stock-analysis）
• 读取图表并深入分析特定板块（改用 sector-analyst）
• 投资组合再平衡（改用 portfolio-manager）
• 股息／收益投资（改用 value-dividend-screener）

---

工作流程

第 1 步：确认要求

检查所需的 API 密钥和依赖项：

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

# Check for FMP API key (optional, used for valuation metrics)
echo $FMP_API_KEY

要求：

• Python 3.7+，以及 requests、beautifulsoup4、lxml
• FINVIZ Elite API key（建议使用，以覆盖完整行业数据并提高速度）
• FMP API key（可选，用于 P/E 比率估值数据）
• 如果没有 FINVIZ Elite，此技能会抓取 FINVIZ 公开数据（每个行业约限 20 只股票，且请求速率限制更严格）

安装：

pip install requests beautifulsoup4 lxml

第 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 5 \
  --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/ 目录。

---

资源

脚本目录（scripts/）

主要脚本：

• theme_detector.py - 主协调脚本

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

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

  • 从 cross_sector_themes.md 读取主题定义
  • 计算主题层级的汇总分数
  • 根据成分行业确定方向（看涨/看跌）

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

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

• lifecycle_analyzer.py - 生命周期成熟度评估

  • 持续时间评分、极端程度聚类、估值分析
  • 根据 thematic_etf_catalog.md 对 ETF 数量进行评分
  • 阶段分类：早期 / 中期 / 后期 / 衰竭期

• 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 模式差异

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

方向判定逻辑

主题方向（看涨或看跌）由以下因素决定：

1. 行业加权表现：按市值加权计算成分行业的平均涨跌幅
2. 上升趋势比例：各行业处于技术上升趋势的股票占比（如果有上升趋势数据）
3. 成交量确认：成交量是否支持价格方向（吸筹或派发）

主题分类如下：

• 看涨：加权表现 > 0，且（上升趋势比例 > 50% 或确认有成交量吸筹）
• 看跌：加权表现 < 0，且（上升趋势比例 < 50% 或确认有成交量派发）
• 中性：信号不一或数据不足

已知局限

1. 幸存者偏差：仅分析当前上市的股票和 ETF
2. 延迟：FINVIZ 数据可能比盘中走势延迟 15 分钟（Public 模式）
3. 主题边界：部分股票符合多个主题；分类依据主要行业
4. ETF 数量激增：目录是静态的，可能未收录非常新的 ETF
5. 叙事评分：基于 WebSearch，且本质上带有主观性
6. Public 模式的局限：每个行业约 20 只股票，可能遗漏小盘股信号

免责声明

本分析仅用于教育和提供信息。

• 不构成投资建议
• 过去的主题趋势不保证未来表现
• 主题检测识别的是动量，而非基本面价值
• 做出投资决策前，请自行开展研究

---

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