market-top-detector

市场顶部探测器技能

用途

使用包含 6 个组成部分的评分系统（0-100）评估启发式市场顶部风险。整合三种市场风险分析方法：

1. O'Neil - 派发日累积（机构抛售）
2. Minervini - 领涨股恶化模式
3. Monty - 防御型行业轮动信号

与泡沫探测器（宏观／多月评估）不同，此技能侧重于预示市场将出现 10-20% 回调的战术性 2-8 周择时信号。

分数解读

将 0-100 的综合分数视为启发式风险分数，而非事件概率估计。分数为 70 并不意味着市场顶部出现的概率为 70%。风险预算百分比是政策启发式指标，而非测得的结果频率。历史模式是回溯估算，并非时点证据。 如果任何组成部分不可用／无效，或最近模式的加权 RMS 超过 15 分，请报告无可比案例。此容差是预先声明的启发式指标，并非经实证验证的相似度阈值。 在提出校准声明前，请遵循时点评估协议。目前未提供任何实测校准结果。

何时使用此技能

英语：

• 用户询问「市场是否正在筑顶？」或「市场是否接近顶部？」
• 用户注意到派发日不断累积
• 用户发现防御型行业表现优于成长型行业
• 用户看到领涨股走弱，但指数仍保持坚挺
• 用户询问何时减少股票敞口
• 用户希望评估未来 2-8 周的回调风险

日语：

• 「天井が近い？」「今は利確すべき？」
• 担心派发日不断累积
• 防御型行业表现优于成长型行业
• 领涨股开始走弱，但指数仍保持坚挺
• 判断缩减敞口的时机
• 希望评估未来 2〜8 周的回调风险

先决条件

必需：

• FMP API Key： 设置 $FMP_API_KEY 环境变量，或传入 --api-key。免费套餐即可满足需求（每次执行约需 33 次 API 调用）。
• WebSearch 访问权限： 收集 S&P 500 广度（50DMA 百分比）和 CBOE Put/Call 比率数据时必需。

可选：

• 保证金债务数据： 可增强情绪评分，但通常滞后 1-2 个月。
• VIX 期限结构： 如果 FMP API 有 VIX3M 报价，则自动检测；也可通过 --vix-term 手动覆盖。

数据时效性： 为确保分析准确，所有手动收集的数据都应来自最近 3 个工作日。

与泡沫探测器的区别

方面	市场顶部探测器	泡沫探测器
时间范围	2-8 周	数月至数年
目标	10-20% 回调	泡沫破裂（30% 以上）
方法	O'Neil／Minervini／Monty	Minsky／Kindleberger
数据	价格／成交量＋广度	估值＋情绪＋社交媒体
分数范围	0-100 综合分数	0-15 分

---

执行工作流

阶段 1：通过 WebSearch 收集数据

运行 Python 脚本前，请使用 WebSearch 收集以下数据。 数据时效性要求： 所有数据必须来自最近 3 个工作日。过时数据会降低分析质量。

1. S&P 500 Breadth (200DMA above %)
   AUTO-FETCHED from TraderMonty CSV (no WebSearch needed)
   The script fetches this automatically from GitHub Pages CSV data.
   Override: --breadth-200dma [VALUE] to use a manual value instead.
   Disable: --no-auto-breadth to skip auto-fetch entirely.

2. [REQUIRED] S&P 500 Breadth (50DMA above %)
   Valid range: 20-100
   Primary search: "S&P 500 percent stocks above 50 day moving average"
   Fallback: "market breadth 50dma site:barchart.com"
   Direct fallback when search snippets are poor: fetch `https://www.barchart.com/stocks/quotes/$S5FI/overview` and extract the embedded `lastPrice` / `tradeTime` for “S&P 500 Stocks Above 50-Day Average”.
   Record the data date

3. [REQUIRED] CBOE Equity Put/Call Ratio
   Valid range: 0.30-1.50
   Primary search: "CBOE equity put call ratio today"
   Fallback: "CBOE total put call ratio current"
   Fallback: "put call ratio site:cboe.com"
   Direct fallback when Cboe CSV endpoints are stale: fetch `https://ycharts.com/indicators/cboe_equity_put_call_ratio` and parse the “Last Value” / “Latest Period” table fields. Treat this as a secondary source and cite it in freshness notes.
   Record the data date

4. [OPTIONAL] VIX Term Structure
   Values: steep_contango / contango / flat / backwardation
   Primary search: "VIX VIX3M ratio term structure today"
   Fallback: "VIX futures term structure contango backwardation"
   Note: Auto-detected from FMP API if VIX3M quote available.
   CLI --vix-term overrides auto-detection.

5. [OPTIONAL] Margin Debt YoY %
   Primary search: "FINRA margin debt latest year over year percent"
   Fallback: "NYSE margin debt monthly"
   Note: Typically 1-2 months lagged. Record the reporting month.

阶段 2：执行 Python 脚本

将收集的数据作为 CLI 参数传入脚本并运行：

python3 skills/market-top-detector/scripts/market_top_detector.py \
  --api-key $FMP_API_KEY \
  --breadth-50dma [VALUE] --breadth-50dma-date [YYYY-MM-DD] \
  --put-call [VALUE] --put-call-date [YYYY-MM-DD] \
  --vix-term [steep_contango|contango|flat|backwardation] \
  --margin-debt-yoy [VALUE] --margin-debt-date [YYYY-MM-DD] \
  --output-dir reports/ \
  --context "Consumer Confidence=[VALUE]" "Gold Price=[VALUE]"
# 200DMA breadth is auto-fetched from TraderMonty CSV.
# Override with --breadth-200dma [VALUE] if needed.
# Disable with --no-auto-breadth to skip auto-fetch.

脚本将：

1. 从 FMP API 获取 S&P 500、QQQ、VIX 报价及历史数据
2. 获取领涨 ETF（ARKK、WCLD、IGV、XBI、SOXX、SMH、KWEB、TAN）数据
3. 获取行业 ETF（XLU、XLP、XLV、VNQ、XLK、XLC、XLY）数据
4. 计算全部 6 个组成部分
5. 生成综合分数和报告

阶段 3：呈现结果

向用户呈现生成的 Markdown 报告，并重点说明：

• 综合分数和风险区间
• 数据时效性警告（若有数据超过 3 天）
• 最强警告信号（分数最高的组成部分）
• 历史对比（最接近的过往顶部模式）
• 假设情景（对关键变化的敏感度）
• 根据风险区间提出的建议行动
• 跟进日状态（如适用）
• 与上次运行相比的变化（若存在此前的报告）

---

6 项评分体系

#	组成部分	权重	数据来源	关键信号
1	派发日计数	25%	FMP API	过去 25 个交易日内的机构抛售
2	领涨股健康状况	20%	FMP API	成长型 ETF 组合走弱
3	防御型板块轮动	15%	FMP API	防御型板块与成长型板块的相对表现
4	市场广度背离	15%	自动（CSV）+ WebSearch	市场广度与指数水平的对比：200DMA（自动）/ 50DMA（WebSearch）
5	指数技术状况	15%	FMP API	均线结构、反弹失败、峰值降低
6	市场情绪与投机	10%	FMP + WebSearch	VIX、看跌/看涨期权比率、期限结构

风险区间映射

分数	区间	风险预算	操作
0-20	绿色（正常）	100%	正常操作
21-40	黄色（早期预警）	80-90%	收紧止损，减少新建仓位
41-60	橙色（风险升高）	60-75%	对疲弱仓位获利了结
61-80	红色（高风险）	40-55%	积极获利了结
81-100	危急（极高风险）	20-35%	全面防御，对冲风险

---

交易所日历与回放

运行检测器前，请先安装 requirements.txt。新鲜度判断依据 XNYS 交易时段，而非工作日。可使用 --as-of YYYY-MM-DD 指定实时 评估日期，但由于当前报价接口并非时点数据源，历史实时回放会安全失败。

API 要求

必需： FMP API 密钥（免费套餐即可：每次执行约 33 次调用） 可选： 用于市场广度和情绪的数据 WebSearch（可提高准确性）

输出文件

• JSON：market_top_YYYY-MM-DD_HHMMSS.json
• Markdown：market_top_YYYY-MM-DD_HHMMSS.md

参考文档

references/market_top_methodology.md

• 完整方法论，涵盖 O'Neil、Minervini 和 Monty 框架
• 组成部分的评分详情与阈值
• 历史验证说明

references/distribution_day_guide.md

• O'Neil 派发日规则详解
• 停滞日识别
• 跟进日（FTD）机制

references/historical_tops.md

• 对 2000、2007、2018、2022 年市场顶部的分析
• 历史市场顶部期间的组成部分分数模式
• 经验教训与回顾性示例估算

何时加载参考文档

• 首次使用： 加载 market_top_methodology.md，全面了解框架
• 有关派发日的问题： 加载 distribution_day_guide.md
• 历史背景： 加载 historical_tops.md
• 常规执行： 无需参考文档——脚本会处理评分