用途：检测并排定当前市场趋势主题，识别看涨（LEAD）与看跌（LAG）方向，评估生命周期成熟度，输出置信度与主题匹配质量，用于理解市场叙事轮动与拥挤度，而非个股或组合建议。
主要能力：基于 FINVIZ 行业数据做跨行业主题检测；三维评分（Theme Heat 0-100、生命周期成熟度、置信度 Low/Medium/High）；方向感知评分；ETF 扩散度评分（ETF 越多越成熟/拥挤）；可选 --scan-hits 引入 5D+20%、EP9M、区间扩张、新高、高 RS 等领导力证据并融入 Theme Heat v2；通过显式股票篮与代理 ETF 确认主题匹配质量；--history-file 提供主题历史与加速指标；双模式运行（FINVIZ Elite 快，公共抓取慢且受限）；对头部主题做 WebSearch 叙事确认（脚本置信度上限为 Medium，可提升至 High）。
使用方式：需 Python 3.9+，先执行 pip install -r skills/theme-detector/requirements.txt。可选设置环境变量 FINVIZ_API_KEY、FMP_API_KEY。运行主脚本 python3 skills/theme-detector/scripts/theme_detector.py --output-dir reports/，支持 --finviz-api-key、--fmp-api-key、--max-themes、--max-stocks-per-theme、--finviz-mode、--scan-hits、--narrative-scores、--history-file、--as-of-date 等选项；若 python3 低于 3.10 或依赖缺失，可用 uv run --python 3.12 --with requests --with beautifulsoup4 --with lxml --with pandas --with numpy --with yfinance --with finvizfinance --with PyYAML 方式运行。输出 JSON 与 Markdown 报告，含主题看板、看涨/看跌明细、行业排名、板块上升比例与方法说明。--scan-hits 接受 JSON/JSONL/CSV；--narrative-scores 为离线 JSON。
适用场景：查询当前热门主题、冷热行业、叙事强弱、主题轮动方向、主题 ETF 或板块配置思路、拥挤交易与晚期主题判断。
限制：不用于个股分析、单板块深读、组合再平衡或股息投资。无 FINVIZ Elite 时走公共抓取，每行业约限 20 只股票且限速，耗时约 5-8 分钟。--as-of-date 为严格日期上限，因输入为实时数据而非时点快照，非当前日期会失败关闭。WebSearch 叙事确认依赖外部搜索，缺失叙事输入时 narrative_keyword_score 为空并降低覆盖率，不会使运行失败。