主题检测器
概述
此技能通过分析跨行业的动量、成交量和宽度信号，检测并排名热门市场主题。它不仅能识别看涨（上行动量）和看跌（下行压力）主题，还会评估生命周期成熟度（新兴/加速/趋势/成熟/衰竭），并提供一个结合定量数据与叙事分析的信心分数。
三维评分模型：
- 主题热度 (0-100)：主题的方向中性强度（动量、成交量、上升趋势比率、宽度）
- 生命周期成熟度：基于持续时间、极端聚集、估值和 ETF 普及度的阶段分类（新兴 / 加速 / 趋势 / 成熟 / 衰竭）
- 信心 (低 / 中 / 高)：检测的可靠性，结合定量宽度与叙事确认。脚本输出上限为“中”；Claude 的 WebSearch 叙事确认步骤可将其提升至“高”。
- 股票领导力：来自 5日+20%、EP9M、区间扩张、新高和相对强度高股票的每日扫描命中证据。当提供时，会融入主题热度 v2；当缺失时，会降低信心覆盖率，但不会强制领导力为零。
- 主题匹配质量：来自行业参与度、明确股票篮子命中、代理 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 密钥：
FINVIZ Elite（推荐，以获得完整的行业覆盖和速度）：
export FINVIZ_API_KEY=你的_finviz_elite_api_key_在这里
FMP API（可选，用于市盈率估值数据）：
export FMP_API_KEY=你的_fmp_api_key_在这里
依赖项包括 finvizfinance、PyYAML、pandas/numpy、requests 和 yfinance，因为正常的公共模式执行会导入或使用它们。
没有 FINVIZ Elite 的情况下，该技能将使用公共 FINVIZ 抓取（每个行业约 20 只股票，速度限制更严格）。
工作流程
步骤 1：验证环境
检查 API 密钥是否已配置（参见先决条件）：
# 验证 FINVIZ Elite API 密钥（可选但推荐）
echo $FINVIZ_API_KEY
# 验证 FMP API 密钥（可选）
echo $FMP_API_KEY
步骤 2：执行主题检测脚本
运行主检测脚本：
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 >= 20ep9m：volume >= 9,000,000、relative_volume >= 2.0和change_pct >= 4range_expansion：change_pct >= 4、true_range / atr_20 >= 1.5或atr_expansion >= 1.5，并且close_location >= 0.75new_high：显式的new_high/is_new_high，或 52 周新高证据high_rs：rs_rating >= 90或归一化的relative_strength >= 0.90
叙事分数输入合约： --narrative-scores 是一个离线 JSON 输入，而非实时的 WebSearch 调用。它接受 {"主题名称": 82} 或 {"themes": {"主题名称": {"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 输出以了解定量结果：
# 查找最新报告
ls -lt reports/theme_detector_*.json | head -1
# 读取 JSON 输出
cat reports/theme_detector_YYYY-MM-DD_HHMMSS.json
步骤 4：通过 WebSearch 执行叙事确认
对于前 5 个主题（按主题热度排序），执行 WebSearch 查询以确认叙事强度：
搜索模式：
"[主题名称] 股票 市场 [当前月份] [当前年份]"
"[主题名称] 板块 动量 [当前月份] [当前年份]"
评估叙事信号：
- 强叙事：多家主要媒体在报道该主题，分析师上调评级，政策催化剂
- 中等叙事：有一些报道，情绪混杂，没有明确的催化剂
- 弱叙事：报道很少，或者主要是逆向/怀疑语气
根据发现更新信心水平：
- 定量高 + 叙事强 = 高 信心
- 定量高 + 叙事弱 = 中 信心（可能存在动量背离）
- 定量低 + 叙事强 = 中 信心（叙事可能领先于价格）
- 定量低 + 叙事弱 = 低 信心
步骤 5：分析结果并提供建议
将检测结果与知识库交叉引用：
要参考的文档：
references/cross_sector_themes.md- 主题定义和组成行业references/thematic_etf_catalog.md- 按主题划分的 ETF 敞口选项references/theme_detection_methodology.md- 评分模型细节references/finviz_industry_codes.md- 行业分类参考
分析框架：
对于 热门看涨主题（热度 >= 70，方向 = 看涨）：
- 确定生命周期阶段（新兴 = 机会，成熟/衰竭 = 谨慎）
- 列出主题内表现最佳的行业
- 推荐代理 ETF 以获取敞口
- 如果 ETF 普及率很高，则标记（拥挤交易警告）
对于 热门看跌主题（热度 >= 70，方向 = 看跌）：
- 确定承受压力的行业
- 评估看跌动量是在加速还是减速
- 推荐对冲策略或应避免的行业
- 如果生命周期为成熟/衰竭，则注意潜在的均值回归机会
对于 新兴主题（热度 40-69，生命周期 = 新兴）：
- 这些可能代表早期轮动信号
- 建议通过自选股列表进行监控
- 识别可能加速该主题的催化剂事件
对于 衰竭主题（热度 >= 60，生命周期 = 衰竭）：
- 警告拥挤交易风险
- 高 ETF 数量确认了过多的散户参与
- 考虑逆向定位或减少敞口
步骤 6：生成最终报告
使用报告模板结构向用户呈现最终报告：
# 主题检测报告
**日期：** YYYY-MM-DD
**模式：** FINVIZ Elite / 公共
**分析的主题数量：** N
**数据质量：** [注明任何限制]
## 主题仪表板
[主题表格，包含热度、方向、生命周期、信心]
## 今日变化
[新出现主题、最大热度加速、新 EP9M 集群、消退主题]
## 领导力证据
[5日+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": "Accelerating",
"confidence": "Medium",
"heat_label": "Hot",
"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 数量；越高 = 越拥挤...） |
附录
理解主题起源
主题可以通过以下方式起源：
- 种子主题：预定义的主题，如 "AI 与机器学习"，其组成行业已映射
- 检测到的主题：基于当前行业动量聚类自动发现的
- 用户定义的主题：通过
--custom-themes选项由用户明确指定
示例：公共模式快速运行
# 无需任何 API 密钥的最简运行
python3 skills/theme-detector/scripts/theme_detector.py \
--output-dir reports/
限制
- 公共 FINVIZ 模式：每个行业约 20 只股票，行业覆盖率有限，速度较慢
- 没有 FINVIZ Elite：某些行业可能具有不完整的动量数据
- 信心上限：没有 WebSearch 叙事确认时，脚本生成的信心上限为“中”
- 主题匹配覆盖率：如果没有提供叙事分数或现货股票篮子数据，可能会降低