ibd-distribution-day-monitor

IBD 派发日监控

用途

检测主要市场 ETF 的 IBD 风格派发日（QQQ 作为纳斯达克代理，SPY 作为标普 500 代理），并生成每日市场走弱信号以及 TQQQ/QQQ 持仓建议。适用于收盘后的复盘。

使用时机

在以下情况下调用此技能：

• 每个美国交易日收盘后。
• 增加 TQQQ 持仓或调整杠杆头寸前。
• 评估上升趋势是否正变得容易受到回调影响。
• 作为 FTD（Follow-Through Day）检测或其他市场状态框架的上游输入。

请勿将此技能用于：

• 执行交易或修改订单。
• 生成 IBD 规则集之外的主观市场预测。

输入

• 代码（默认：QQQ、SPY）和回溯区间（默认 80 个交易日）。
• 可选参数 --as-of YYYY-MM-DD，用于基于历史交易日进行回测。
• 策略背景：标的（TQQQ 或 QQQ）、当前持仓比例 %、基础跟踪止损 %。
• 通过 --api-key、config.data.api_key 或 FMP_API_KEY 环境变量提供 FMP API 密钥（优先级依次递减）。

核心规则

满足以下条件时，判定为派发日：

1. 当日收盘价至少低于前一日收盘价 0.2%。
2. 当日成交量高于前一日成交量。

出现以下任一情况时，派发日将从有效计数中移除：

• 自该派发日起已过去超过 25 个交易日。
• 指数从派发日收盘价起上涨了 5%（默认使用派发日后的最高价；可配置为使用收盘价）。

当日的派发日不会立即失效，因为没有派发日之后的交易日可用于评估 5% 的涨幅。

计数约定

• d5_count / d15_count / d25_count 统计 age_sessions <= N 的有效记录。
• 这意味着会检查 N+1 个交易日（年龄为 0..N，含首尾）。因此，报告会使用“在过去 N 个已过去的交易日内”，而不是“最近 N 个交易日”，以避免歧义。

风险分类

风险	触发条件
NORMAL	d25 <= 2
CAUTION	d25 >= 3
HIGH	d25 >= 5 OR d15 >= 3 OR d5 >= 2
SEVERE	d25 >= 6 OR d15 >= 4 OR (market_below_21ema_or_50ma AND d25 >= 5)

同时加载 QQQ 和 SPY 时，采用以 QQQ 加权的整体判断逻辑（考虑 TQQQ）：任一标的达到 SEVERE，整体风险即升至 SEVERE；QQQ 达到 HIGH，整体风险即升至 HIGH；QQQ 为 NORMAL 而 SPY 为 HIGH 时，整体风险仍升至 HIGH（广泛市场的连带影响）。

TQQQ 持仓政策

风险	操作	目标持仓	跟踪止损
NORMAL	HOLD_OR_FOLLOW_BASE_STRATEGY	100%	基础值
CAUTION	AVOID_NEW_ADDS	75%	min(base, 7%)
HIGH	REDUCE_EXPOSURE	50%	min(base, 5%)
SEVERE	CLOSE_TQQQ_OR_HEDGE	25%	min(base, 3%)

由于 QQQ 不带有 3 倍杠杆，因此采用较温和的政策（HIGH=75%，SEVERE=50%）。

工作流

1. 通过 FMP（get_historical_prices）加载已配置代码的 OHLCV 数据。
2. 验证数据质量，并在审计记录中记录跳过的交易日。
3. 通过 prepare_effective_history 重新设定基准，使 effective_history[0] 为评估交易日。
4. 检测原始派发日，并补充 high_since、失效事件和状态。
5. 统计有效记录的 d5 / d15 / d25。
6. 计算 21EMA 和 50SMA 筛选条件；标记 market_below_21ema_or_50ma（数据不足时为 None）。
7. 对每个指数进行风险分类，然后依据 QQQ 加权政策合并结果。
8. 为已配置的标的生成投资组合操作建议。
9. 将 JSON 和 Markdown 报告写入 --output-dir，并对 API 密钥进行脱敏处理。

输出

保存至 reports/（或 --output-dir）：

• ibd_distribution_day_monitor_YYYY-MM-DD_HHMMSS.json
• ibd_distribution_day_monitor_YYYY-MM-DD_HHMMSS.md

JSON 使用 UTF-8 编码和 ensure_ascii=False（保留日文说明）。敏感密钥（api_key、fmp_api_key、token 等）会自动脱敏。

操作原则

• 除非有意修改 config/default.yaml，否则不要覆盖 IBD 规则定义。
• 始终说明哪些日期计入了当前计数。
• 将缺失或不可靠的成交量数据视为警告（audit_flag），而非分布日。
• 不要下单。投资组合操作建议是风险管理建议，而非执行指令。

CLI

python3 skills/ibd-distribution-day-monitor/scripts/ibd_monitor.py \
  --symbols QQQ,SPY \
  --lookback-days 80 \
  --instrument TQQQ \
  --current-exposure 100 \
  --base-trailing-stop 10 \
  --output-dir reports/

API 要求

需要 FMP API 密钥。免费套餐（每天 250 次调用）足以满足每日运行 QQQ + SPY 的需求。

相关技能

• ftd-detector：通过跟进日提供底部确认（与此顶部信号相对应）。
• market-top-detector：使用奥尼尔分布日及其他组成部分，计算 0–100 的综合顶部概率分数。
• position-sizer：将风险管理建议转换为股数。