mcpField
M
market-top-detector

market-top-detector

github.com/mphinance数据与数据库3284 次安装5 天前更新
代码仓库

关于 market-top-detector

Market Top Detector 是一项 skill，通过六项量化指标评估近期市场见顶的概率。它结合价格、成交量、市场广度、板块轮动和情绪信号，评估未来 2–8 周的战术风险。

主要功能

  1. 01六项指标合成 0–100 分
  2. 02结合 O’Neil、Minervini 和 Monty 信号
  3. 03采集 FMP 市场数据
  4. 04映射风险区间
  5. 05生成 JSON 和 Markdown 报告
  6. 06历史比较与假设分析

适用场景

  1. 01评估未来 2–8 周的回调风险
  2. 02调整股票敞口前检查预警信号
  3. 03将当前信号模式与历史市场顶部对照

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mphinance/alpha-skills --skill market-top-detector

安装后在 Claude Code 中输入/market-top-detector确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
references/
distribution_day_guide.md
historical_tops.md
market_top_methodology.md
scripts/
breadth_csv_client.py
fmp_client.py
historical_comparator.py
market_top_detector.py
report_generator.py
scenario_engine.py
scorer.py
scripts/calculators/
__init__.py
breadth_calculator.py
defensive_rotation_calculator.py
distribution_day_calculator.py
index_technical_calculator.py
leading_stock_calculator.py
math_utils.py
sentiment_calculator.py
scripts/tests/
conftest.py
helpers.py
test_breadth_csv_client.py
test_breadth.py
test_defensive_rotation.py
test_delta.py
test_distribution_day.py
test_fmp_client.py
test_freshness.py
test_historical_comparator.py
test_index_technical.py

详细介绍

市场顶部检测技能

用途

使用量化的 6 项评分系统（0-100），检测市场形成顶部的概率。整合三种经过验证的市场顶部检测方法：

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

与 Bubble Detector（宏观／数月周期评估）不同，本技能侧重于战术性的 2-8 周择时信号，这些信号通常先于 10-20% 的市场回调出现。

何时使用此技能

英语：

  • 用户询问“市场是否正在筑顶？”或“市场顶部是否将近？”
  • 用户注意到派发日正在累积
  • 用户观察到防御性板块表现优于成长板块
  • 用户看到领涨股走弱，而指数仍然坚挺
  • 用户询问何时应降低股票敞口
  • 用户想评估未来 2-8 周的回调概率

日语：

  • 「天井が近い？」「今は利確すべき？」
  • 担心派发日累积
  • 防御性板块表现优于成长板块
  • 领涨股开始走弱，但指数仍然坚挺
  • 判断缩减敞口的时机
  • 想评估未来 2〜8 周的回调概率

前提条件

必需：

  • **FMP API Key：**设置 $FMP_API_KEY 环境变量或传入 --api-key。免费套餐即可满足需求（每次执行约调用 33 次 API）。
  • **WebSearch 访问权限：**收集标普 500 市场广度（50DMA 百分比）和 CBOE 看跌／看涨期权比率数据时必需。

可选：

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

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

与 Bubble Detector 的区别

方面市场顶部检测器Bubble Detector
时间范围2-8 周数月至数年
目标10-20% 回调泡沫破裂（30% 以上）
方法O'Neil/Minervini/MontyMinsky/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"
   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"
   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 获取标普 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 天）
  • 最强警告信号（分数最高的指标）
  • 历史对比（最接近的过往顶部模式）
  • 假设情景（对关键变化的敏感度）
  • 根据风险区间提出的建议
  • Follow-Through Day 状态（如适用）
  • 与上次运行结果的差值（如有先前报告）

6 项评分系统

#指标权重数据来源关键信号
1派发日计数25%FMP API最近 25 个交易日内的机构抛售
2领涨股健康状况20%FMP API成长型 ETF 组合恶化
3防御性板块轮动15%FMP API防御性板块相对成长板块的表现
4市场广度背离15%自动（CSV）+ WebSearch200DMA（自动）／50DMA（WebSearch）市场广度与指数水平的对比
5指数技术状况15%FMP API均线结构、反弹失败、更低的高点
6情绪与投机10%FMP + WebSearchVIX、看跌／看涨期权比率、期限结构

风险区域划分

分数区域风险预算操作
0-20绿色（正常）100%正常操作
21-40黄色（早期预警）80-90%收紧止损，减少新的入场操作
41-60橙色（风险升高）60-75%对表现较弱的持仓止盈
61-80红色（顶部概率较高）40-55%积极止盈
81-100危急（顶部形成）20-35%全面防御，对冲

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
  • 常规执行： 无需参考文档，脚本会处理评分

评论

支持 Markdown