market-breadth-analyzer

市场广度分析器技能

用途

使用数据驱动的 6 项评分系统（0-100）量化市场广度健康状况。使用 TraderMonty 公开提供的 CSV 数据，衡量市场有多大范围参与上涨或下跌。

**评分方向：**100 = 健康状况最佳（广泛参与），0 = 严重疲弱。

无需 API 密钥——使用 GitHub Pages 上免费提供的 CSV 数据。

何时使用此技能

英语：

• 用户询问“市场上涨是否具有广泛基础？”或“市场广度有多健康？”
• 用户想评估市场参与率
• 用户询问涨跌线指标或广度突发行情
• 用户想了解市场是否正在收窄（参与的股票越来越少）
• 用户询问基于广度状况的股票敞口水平

日语：

• 「市场广度如何？」「市场参与率是多少？」
• 「涨势是否正在扩散？」「是不是只有部分股票在上涨？」
• 基于广度指标判断敞口
• 想通过数据确认市场健康状况

前置条件

• Python 3.9+，并安装 requests 库（用于获取 CSV 数据）
• 互联网访问，以连接 GitHub Pages URL
• 无需 API 密钥——使用免费提供的公共 CSV 数据

与 Breadth Chart Analyst 的区别

方面	Market Breadth Analyzer	Breadth Chart Analyst
数据来源	CSV（自动）	图表图片（手动）
是否需要 API	无	无
输出	0-100 定量评分	定性图表分析
组成部分	6 个评分维度	视觉模式识别
可重复性	完全可复现	取决于分析师

---

执行工作流

第 1 阶段：运行 Python 脚本

运行分析脚本。如果在 cron 运行中使用嵌套或带日期的 --output-dir，请先创建该目录；历史记录写入器要求目录已存在。

mkdir -p reports/<routine-or-date>
python3 skills/market-breadth-analyzer/scripts/market_breadth_analyzer.py \
  --detail-url "https://tradermonty.github.io/market-breadth-analysis/market_breadth_data.csv" \
  --summary-url "https://tradermonty.github.io/market-breadth-analysis/market_breadth_summary.csv" \
  --output-dir reports/<routine-or-date>

对于简单的临时运行，可以省略 --output-dir，或使用已存在的目录。从仓库根目录运行定时 cron 任务时，建议使用相对于仓库的输出目录，例如 reports/after-close-YYYY-MM-DD，而不是绝对路径。如果绝对路径形式的嵌套 --output-dir 在历史记录写入步骤意外失败，即使目录已存在，也应先使用对应的相对仓库路径重试一次，再判定广度分析不可用。

脚本将：

1. 获取详细 CSV（约 2,500 行，2016 年至今）和摘要 CSV（8 项指标）
2. 验证数据时效性（超过 5 天时发出警告）
3. 计算全部 6 项组成评分（任何组成部分缺少数据时，自动重新分配权重）
4. 生成综合评分并划分区间
5. 跟踪评分历史并计算趋势（改善／恶化／稳定）
6. 输出 JSON 和 Markdown 报告

第 2 阶段：呈现结果

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

• 综合评分和健康区间
• 最强和最弱的组成部分
• 建议的股票敞口水平
• 需要关注的关键广度水平
• 任何数据时效性警告

---

6 项评分系统

#	组成部分	权重	关键信号
1	广度水平与趋势	25%	当前 8MA 水平 + 200MA 趋势方向 + 8MA 方向修正
2	8MA 与 200MA 交叉	20%	通过 MA 差值和方向衡量动能
3	峰值／谷值周期	20%	广度周期中的位置
4	看跌信号	15%	经回测的看跌信号标记
5	历史百分位	10%	当前值与完整历史分布的比较
6	标普 500 背离	10%	多时间窗口（20 天 + 60 天）价格与广度背离

**权重重新分配：**如果任何组成部分的数据不足（例如，未检测到峰值／谷值标记），则将其排除，并按比例将其权重重新分配给其余组成部分。报告会同时显示原始权重和有效权重。

**评分历史：**综合评分会在每次运行后持久保存（以数据日期为键）。有多条观测数据时，报告会包含趋势摘要（改善／恶化／稳定）。

健康状况映射（100 = 健康）

评分	区域	股票敞口	操作
80-100	强劲	90-100%	满仓，优先考虑增长/动量
60-79	健康	75-90%	正常操作
40-59	中性	60-75%	选择性配置，收紧止损
20-39	走弱	40-60%	获利了结，提高现金比例
0-19	危急	25-40%	保全资本，关注谷底

---

数据来源

详细 CSV： market_breadth_data.csv

• 约 2,500 行，数据从 2016-02 至今
• 列：Date、S&P500_Price、Breadth_Index_Raw、Breadth_Index_200MA、Breadth_Index_8MA、Breadth_200MA_Trend、Bearish_Signal、Is_Peak、Is_Trough、Is_Trough_8MA_Below_04

汇总 CSV： market_breadth_summary.csv

• 8 项汇总指标（平均峰值、平均谷值、计数、分析周期）

两者均托管在 GitHub Pages 上并公开访问，无需身份验证。

输出文件

• JSON：market_breadth_YYYY-MM-DD_HHMMSS.json
• Markdown：market_breadth_YYYY-MM-DD_HHMMSS.md
• 历史记录：market_breadth_history.json（在多次运行间保留，最多 20 条记录）

参考文档

references/breadth_analysis_methodology.md

• 完整方法论及各组成部分的评分细节
• 阈值说明和区域定义
• 历史背景和解读指南

加载参考文档的时机

• 首次使用： 加载方法论参考文档以了解框架
• 定期执行： 无需参考文档，脚本会处理评分

同次运行来源信息

向两个必需的 market-regime-daily 生成程序传入 --run-id daily-20261017-unique。如果不传入，每个生成程序都会生成自己的唯一 ID。JSON 包含 schema 1.0 data_provenance，其中记录了实际主要时间序列的业务日期、UTC 检索时间、来源和运行 ID。未知的调整、时点、幸存者偏差和公司行动标志均为 false。辅助汇总日期未经验证；这并不代表已确认每项综合输入都是最新的。主要日期缺失或格式错误时，将停止生成报告。

将这些调用输出的准确 JSON 路径传递给 Exposure Coach 的 --require-provenance --run-id … --as-of … 模式。运行 ID 是由调用方提供的一致性标记，不代表真实性证明或时点证明。