ibd-distribution-day-monitor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

IBD Distribution Day Monitor

IBD派发日监控器

Purpose

目的

Detect IBD-style Distribution Days for major market ETFs (QQQ as Nasdaq proxy, SPY as S&P 500 proxy) and produce a daily market deterioration signal plus a TQQQ/QQQ exposure recommendation. Designed for post-market review.

针对主流市场ETF（QQQ作为纳斯达克指数代理、SPY作为标普500指数代理）检测IBD风格派发日，生成每日市场恶化信号及TQQQ/QQQ敞口建议。专为盘后复盘设计。

When to Use

使用场景

Invoke this skill:

Daily after the US market close.
Before increasing TQQQ exposure or rebalancing leveraged positions.
When evaluating whether an uptrend is becoming vulnerable to a correction.
As an upstream input to FTD (Follow-Through Day) detection or other market-state frameworks.

Do NOT use this skill to:

Execute trades or modify orders.
Generate discretionary market predictions outside of the IBD ruleset.

在以下场景调用该技能：

美国股市每日收盘后。
增加TQQQ敞口或调整杠杆头寸前。
评估上涨趋势是否易出现回调时。
作为FTD（跟进日）检测或其他市场状态框架的上游输入。

请勿将该技能用于：

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

Inputs

输入参数

Symbols (default: QQQ, SPY) and lookback (default 80 trading sessions).
Optional
```
--as-of YYYY-MM-DD
```
for backtesting against a historical session.
Strategy context: instrument (TQQQ or QQQ), current exposure %, base trailing stop %.
FMP API key via
```
--api-key
```
,
```
config.data.api_key
```
, or
```
FMP_API_KEY
```
env var (in that priority order).

标的代码（默认：QQQ、SPY）和回溯周期（默认80个交易日）。
可选参数
```
--as-of YYYY-MM-DD
```
，用于针对历史交易日进行回测。
策略上下文：工具类型（TQQQ或QQQ）、当前敞口百分比、基准跟踪止损百分比。
FMP API密钥，可通过
```
--api-key
```
、
```
config.data.api_key
```
或
```
FMP_API_KEY
```
环境变量传入（优先级依次降低）。

Core Rules

核心规则

A Distribution Day is detected when:

Today's close is at least 0.2% below yesterday's close.
Today's volume is greater than yesterday's volume.

A Distribution Day is removed from the active count when either:

More than 25 trading sessions have elapsed since the DD.
The index has gained 5% from the DD close (using post-DD high by default; configurable to close-source).

Today's DD is never invalidated immediately because there are no post-DD sessions to evaluate the 5% gain against.

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

当日收盘价较前一日收盘价至少下跌0.2%。
当日成交量高于前一日成交量。

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

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

当日的派发日不会立即失效，因为尚无派发日后的交易日数据来评估5%涨幅条件。

Counting Conventions

计数约定

d5_count

d15_count

d25_count

count active records with

age_sessions <= N

This means N+1 sessions are inspected (age 0..N inclusive). Reports therefore say "within N elapsed sessions" rather than "直近 N 取引日" to avoid ambiguity.

d5_count

d15_count

d25_count

统计

age_sessions <= N

的活跃记录。

这意味着会检查N+1个交易日（包含年龄0到N的记录）。因此报告中会使用“在N个过往交易日内”而非“直近N取引日”，以避免歧义。

Risk Classification

风险分类

Risk	Trigger
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` )

When both QQQ and SPY are loaded, QQQ-weighted overall logic applies (TQQQ-aware): a single SEVERE escalates to SEVERE; QQQ HIGH escalates to overall HIGH; QQQ NORMAL + SPY HIGH still escalates to HIGH (broad-market spillover).

风险等级	触发条件
NORMAL	`d25 <= 2`
CAUTION	`d25 >= 3`
HIGH	`d25 >= 5` 或 `d15 >= 3` 或 `d5 >= 2`
SEVERE	`d25 >= 6` 或 `d15 >= 4` 或 ( `market_below_21ema_or_50ma` 且 `d25 >= 5` )

同时加载QQQ和SPY数据时，将采用QQQ加权的整体逻辑（适配TQQQ）：单一标的触发SEVERE则整体风险为SEVERE；QQQ触发HIGH则整体风险为HIGH；QQQ为NORMAL但SPY为HIGH时，整体风险仍升级为HIGH（市场传导效应）。

TQQQ Exposure Policy

TQQQ敞口政策

Risk	Action	Target Exposure	Trailing Stop
NORMAL	HOLD_OR_FOLLOW_BASE_STRATEGY	100%	base
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 uses a less aggressive policy (HIGH=75%, SEVERE=50%) since it lacks 3x leverage.

风险等级	操作建议	目标敞口	跟踪止损
NORMAL	HOLD_OR_FOLLOW_BASE_STRATEGY	100%	基准值
CAUTION	AVOID_NEW_ADDS	75%	min(基准值, 7%)
HIGH	REDUCE_EXPOSURE	50%	min(基准值, 5%)
SEVERE	CLOSE_TQQQ_OR_HEDGE	25%	min(基准值, 3%)

QQQ采用相对保守的政策（HIGH=75%，SEVERE=50%），因其无3倍杠杆。

Workflow

工作流程

Load OHLCV for the configured symbols via FMP (
```
get_historical_prices
```
).
Validate data quality; record skipped sessions in audit.

Rebase via

prepare_effective_history

effective_history[0]

is the evaluation session.

Detect raw Distribution Days; enrich with
```
high_since
```
, invalidation event, and status.
Count
```
d5
```
/
```
d15
```
/
```
d25
```
active records.
Compute 21EMA and 50SMA filters; flag
```
market_below_21ema_or_50ma
```
(None if data insufficient).
Classify each index, then combine using QQQ-weighted policy.
Generate portfolio action for the configured instrument.
Write JSON + Markdown reports to
```
--output-dir
```
with API keys redacted.

通过FMP加载配置标的的OHLCV数据（调用
```
get_historical_prices
```
）。
验证数据质量；在审计记录中标记跳过的交易日。
通过
```
prepare_effective_history
```
重新校准数据，使
```
effective_history[0]
```
为评估交易日。
检测原始派发日；补充
```
high_since
```
、失效事件及状态信息。
统计
```
d5
```
/
```
d15
```
/
```
d25
```
的活跃记录数量。
计算21EMA和50SMA过滤条件；标记
```
market_below_21ema_or_50ma
```
（数据不足时为None）。
对每个指数进行风险分类，再通过QQQ加权政策合并结果。
为配置的工具生成投资组合操作建议。
将JSON和Markdown报告写入
```
--output-dir
```
，并自动脱敏API密钥。

Outputs

输出结果

Saved to

reports/

(or

--output-dir

ibd_distribution_day_monitor_YYYY-MM-DD_HHMMSS.json

ibd_distribution_day_monitor_YYYY-MM-DD_HHMMSS.md

JSON is UTF-8 with

ensure_ascii=False

(Japanese explanations preserved). Sensitive keys (

api_key

fmp_api_key

token

, etc.) are redacted automatically.

保存至

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

等）会自动脱敏。

Operating Principles

操作原则

Do not override the IBD rule definitions unless
```
config/default.yaml
```
is changed deliberately.
Always explain which dates contributed to the active count.
Treat missing or unreliable volume data as a warning (audit_flag), not as a Distribution Day.
Do not place trades. The portfolio action is a risk-management suggestion, not an execution instruction.

除非有意修改
```
config/default.yaml
```
，否则不得覆盖IBD规则定义。
始终说明哪些交易日计入了活跃计数。
将缺失或不可靠的成交量数据视为警告（audit_flag），而非判定为派发日。
不执行交易。投资组合操作建议仅为风险管理参考，而非交易执行指令。

CLI

CLI命令

bash

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/