parabolic-short-trade-planner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Overview

概述

Generate Qullamaggie-style Parabolic Short watchlists and conditional pre-market plans for US equities. The skill never sends orders. It emits JSON + Markdown that a human reviews against their broker before entry.

Three phases:

Phase 1 (
screen_parabolic.py
): pulls EOD bars + company profile from FMP, applies hard invalidation rules (mode-aware), scores survivors on 5 factors (weights 30/25/20/15/10), and assigns A/B/C/D grades.
Phase 2 (
generate_pre_market_plan.py
): takes the Phase 1 JSON, filters by
```
--tradable-min-grade
```
(default
```
B
```
), checks Alpaca short inventory (or
```
ManualBrokerAdapter
```
), evaluates SEC Rule 201 SSR state from the inherited prior-day close, and renders three trigger plans per candidate.
Phase 3 (
monitor_intraday_trigger.py
): reads the Phase 2 plan, fetches 5-min bars (Alpaca live or fixture), walks each plan's FSM forward by one step, persists per-plan state, and writes an
```
intraday_monitor
```
JSON with
```
state
```
,
```
entry_actual
```
,
```
stop_actual
```
, and
```
shares_actual
```
(when triggered). One-shot — trader runs it every 1–5 min via
```
watch
```
or cron; replay-deterministic so re-runs are byte-identical.

生成Qullamaggie风格的美股抛物线卖空观察列表和带条件的盘前交易计划。本工具不会发送订单，仅输出JSON和Markdown格式内容，供用户参考券商信息后手动执行交易。

三个阶段：

阶段1（
screen_parabolic.py
）：从FMP获取日线数据（EOD bars）和公司概况，应用模式感知的硬性失效规则，对筛选后的标的按5个因子（权重30/25/20/15/10）评分，并给出A/B/C/D等级。
阶段2（
generate_pre_market_plan.py
）：导入阶段1生成的JSON文件，通过
```
--tradable-min-grade
```
参数筛选标的（默认等级为B），检查Alpaca融券库存（或使用
```
ManualBrokerAdapter
```
），根据前一交易日收盘价评估SEC Rule 201 SSR状态，为每个标的生成三个触发计划。
阶段3（
monitor_intraday_trigger.py
）：读取阶段2生成的计划，获取5分钟K线数据（Alpaca实时数据或测试用例），按步骤推进每个计划的FSM，保存每个计划的状态，并生成
```
intraday_monitor
```
JSON文件，包含
```
state
```
、
```
entry_actual
```
、
```
stop_actual
```
和触发时的
```
shares_actual
```
。本阶段为单次运行模式——交易者通过
```
watch
```
命令或定时任务每1-5分钟执行一次；具备重放确定性，重复运行会生成完全一致的结果。

When to Use

使用场景

Invoke this skill when the user wants to:

Build a daily Parabolic Short watchlist from S&P 500 (or a custom CSV).
Translate a watchlist into pre-market trade plans with explicit borrow / SSR / state-cap gating.
Audit a candidate's blocking vs advisory manual-confirmation reasons before placing an order at Alpaca.

Do NOT invoke for:

Long-side momentum screening — use vcp-screener or canslim-screener.
1-minute / sub-minute intraday signals — Phase 3 evaluates 5-min bars only.
Live order routing — this skill is detection-only by design; Phase 3 emits a
```
triggered
```
state with concrete entry/stop/share count, but the trader fires the order manually.

当用户有以下需求时调用本工具：

从标普500（或自定义CSV）生成每日抛物线卖空观察列表。
将观察列表转换为包含明确融券/SSR/状态上限限制的盘前交易计划。
在Alpaca下单前，审核标的的强制/建议手动确认理由。

请勿在以下场景调用：

做多动量筛选——请使用vcp-screener或canslim-screener。
1分钟/亚分钟级盘中信号——阶段3仅评估5分钟K线。
实时订单路由——本工具仅负责检测；阶段3会输出
```
triggered
```
状态及具体入场/止损/持仓数量，但需交易者手动下单。

Workflow

工作流程

Phase 1 — daily screener

阶段1——每日筛选器

Confirm
```
FMP_API_KEY
```
is set (env var or
```
--api-key
```
).

Run with the safer-by-default mode:

bash

python3 skills/parabolic-short-trade-planner/scripts/screen_parabolic.py \
  --mode safe_largecap --as-of 2026-04-30 --output-dir reports/

Inspect
```
reports/parabolic_short_<date>.md
```
— the watchlist is grouped by grade (A→D).
Promote interesting names to Phase 2.

For small-cap blow-offs, switch to

--mode classic_qm

(looser market cap and ADV floors, higher 5-day ROC threshold).

For testing without the API, run

--dry-run --fixture <path>

against a JSON fixture (one is shipped at

scripts/tests/fixtures/dry_run_minimal.json

确认已设置
```
FMP_API_KEY
```
（环境变量或
```
--api-key
```
参数）。

使用默认安全模式运行：

bash

python3 skills/parabolic-short-trade-planner/scripts/screen_parabolic.py \
  --mode safe_largecap --as-of 2026-04-30 --output-dir reports/

查看
```
reports/parabolic_short_<date>.md
```
文件——观察列表按等级从A到D分组。
将感兴趣的标的推进至阶段2。

若需筛选小盘股暴涨标的，切换至

--mode classic_qm

模式（放宽市值和ADV下限，提高5日ROC阈值）。

若需无API测试，运行

--dry-run --fixture <path>

命令，使用JSON测试用例（工具内置测试用例路径为

scripts/tests/fixtures/dry_run_minimal.json

）。

Phase 2 — pre-market plan generator

阶段2——盘前计划生成器

Optional: set
```
ALPACA_API_KEY
```
/
```
ALPACA_SECRET_KEY
```
for live borrow checks. Without them the planner falls back to
```
ManualBrokerAdapter
```
, which marks every candidate as
```
borrow_inventory_unavailable
```
/
```
plan_status: watch_only
```
.

Run:

bash

python3 skills/parabolic-short-trade-planner/scripts/generate_pre_market_plan.py \
  --candidates-json reports/parabolic_short_2026-04-30.json \
  --account-size 100000 --risk-bps 50 --output-dir reports/

Output:
```
reports/parabolic_short_plan_<date>.json
```
. Each plan contains three entry plans (5min ORL break, first red 5-min, VWAP fail) with
```
entry_hint
```
/
```
stop_hint
```
formula strings (no baked-in shares — the trader computes shares at trigger time from the
```
shares_formula
```
).

可选：设置
```
ALPACA_API_KEY
```
/
```
ALPACA_SECRET_KEY
```
以实时检查融券库存。若未设置，计划器将自动切换至
```
ManualBrokerAdapter
```
，标记所有标的为
```
borrow_inventory_unavailable
```
/
```
plan_status: watch_only
```
。

运行命令：

bash

python3 skills/parabolic-short-trade-planner/scripts/generate_pre_market_plan.py \
  --candidates-json reports/parabolic_short_2026-04-30.json \
  --account-size 100000 --risk-bps 50 --output-dir reports/

输出文件：
```
reports/parabolic_short_plan_<date>.json
```
。每个计划包含三个入场方案（5分钟ORL突破、首根5分钟阴线、VWAP跌破），并附带
```
entry_hint
```
/
```
stop_hint
```
公式字符串（未预设持仓数量——交易者需在触发时通过
```
shares_formula
```
计算持仓量）。

Phase 3 — intraday trigger monitor

阶段3——盘中触发监控器

Confirm
```
ALPACA_API_KEY
```
/
```
ALPACA_SECRET_KEY
```
are set (Phase 3 uses Alpaca market data;
```
data.alpaca.markets
```
works for both paper and live accounts).

During US regular session, run one-shot per cadence — typical is every 60 s during the first 30 min, then every 5 min:

bash

python3 skills/parabolic-short-trade-planner/scripts/monitor_intraday_trigger.py \
  --plans-json reports/parabolic_short_plan_2026-05-05.json \
  --bars-source alpaca \
  --state-dir state/parabolic_short/ \
  --output-dir reports/

Or wrap in

watch -n 60 'python3 ...'

/ cron.

Output:
```
reports/parabolic_short_intraday_<date>.json
```
lists every monitored plan with
```
state
```
(
```
armed
```
/
```
triggered
```
/
```
invalidated
```
/ FSM-specific), bar-derived transition timestamps, and
```
size_recipe_resolved
```
(concrete
```
shares_actual
```
) when triggered.

For testing without the API, use

--bars-source fixture --bars-fixture <path>

against a JSON fixture (

scripts/tests/fixtures/intraday_bars/

Phase 3 is idempotent: each run replays the full session bars from open up to

now_et

(or

--now-et

override), so re-running during the same minute produces the same state.

prior_state

is used only for diff/notification display; it never advances the FSM.

确认已设置
```
ALPACA_API_KEY
```
/
```
ALPACA_SECRET_KEY
```
（阶段3使用Alpaca市场数据；
```
data.alpaca.markets
```
适用于模拟和实盘账户）。

美股常规交易时段内，按周期单次运行——通常开盘后30分钟内每60秒运行一次，之后每5分钟运行一次：

bash

python3 skills/parabolic-short-trade-planner/scripts/monitor_intraday_trigger.py \
  --plans-json reports/parabolic_short_plan_2026-05-05.json \
  --bars-source alpaca \
  --state-dir state/parabolic_short/ \
  --output-dir reports/

或通过

watch -n 60 'python3 ...'

命令或定时任务封装运行。

输出文件：
```
reports/parabolic_short_intraday_<date>.json
```
列出所有监控计划的
```
state
```
（
```
armed
```
/
```
triggered
```
/
```
invalidated
```
/FSM特定状态）、基于K线的转换时间戳，以及触发时的
```
size_recipe_resolved
```
（具体
```
shares_actual
```
）。

若需无API测试，使用

--bars-source fixture --bars-fixture <path>

命令，调用JSON测试用例（路径为

scripts/tests/fixtures/intraday_bars/

）。

阶段3具备幂等性：每次运行都会重放从开盘到

now_et

（或

--now-et

参数指定时间）的完整时段K线，因此同一分钟内重复运行会生成相同状态。

prior_state

仅用于差异/通知展示，不会推进FSM。

Reviewing a plan before entry

入场前计划审核

Read three top-level fields per ticker:

```
plan_status
```
:
```
actionable
```
(manual gates can be cleared) or
```
watch_only
```
(hard blockers — borrow unavailable or SSR active).
```
blocking_manual_reasons
```
: must all be resolved before pulling the trigger.
```
advisory_manual_reasons
```
: heads-up only, e.g.
```
manual_locate_required
```
(always set),
```
warning:too_early_to_short
```
,
```
warning:recent_earnings_catalyst
```
(last earnings within
```
--earnings-catalyst-window-days
```
, default 10 trading days — flag the move as event-driven rather than pure technical blow-off).

查看每个标的的三个顶级字段：

```
plan_status
```
：
```
actionable
```
（可解除手动限制）或
```
watch_only
```
（存在硬性限制——融券不可用或SSR生效）。
```
blocking_manual_reasons
```
：必须全部解决后方可触发交易。
```
advisory_manual_reasons
```
：仅为提示信息，例如
```
manual_locate_required
```
（始终存在）、
```
warning:too_early_to_short
```
、
```
warning:recent_earnings_catalyst
```
（最近财报发布于
```
--earnings-catalyst-window-days
```
范围内，默认10个交易日——标记行情为事件驱动而非纯技术面暴涨）。

Earnings-aware screening

财报感知筛选

Phase 1 fetches the FMP earnings calendar once per run (single call, not per-symbol) and emits two earnings-aware checks:

```
--exclude-earnings-within-days
```
(default 2 calendar days, forward) — hard invalidation when next earnings is within the window. Matches the legacy
```
earnings_blackout_days
```
semantic.
```
--earnings-catalyst-window-days
```
(default 10 trading days, backward) — soft warning
```
recent_earnings_catalyst
```
when last earnings is within the window. Routes to Phase 2 as an advisory manual reason without forcing
```
trade_allowed_without_manual: false
```
.

Per-candidate output exposes

last_earnings_date

next_earnings_date

trading_days_since_earnings

(TRADING days),

earnings_within_days

(CALENDAR days, forward),

earnings_blackout_days

(configured threshold), and

earnings_in_blackout_window

. The legacy

earnings_within_2d

is kept for backward compatibility.

Top-level dates:

as_of

is the planning date (Phase 2 contract — never mutate);

run_date

mirrors it;

market_data_as_of

is the latest bar date used for technical metrics (differs from

as_of

on weekend runs).

阶段1每次运行时会调用一次FMP财报日历接口（单接口调用，非逐标的调用），并执行两项财报感知检查：

```
--exclude-earnings-within-days
```
（默认2个自然日，未来）：若下一财报发布时间在该窗口内，直接判定为失效。与旧版
```
earnings_blackout_days
```
语义一致。
```
--earnings-catalyst-window-days
```
（默认10个交易日，过去）：若上一财报发布时间在该窗口内，触发软警告
```
recent_earnings_catalyst
```
。该信息会传递至阶段2作为建议手动理由，不会强制设置
```
trade_allowed_without_manual: false
```
。

每个标的的输出包含

last_earnings_date

、

next_earnings_date

、

trading_days_since_earnings

（交易日天数）、

earnings_within_days

（自然日天数，未来）、

earnings_blackout_days

（配置阈值）和

earnings_in_blackout_window

。旧版

earnings_within_2d

字段保留以兼容历史版本。

顶级日期字段：

as_of

为计划日期（阶段2约定——不可修改）；

run_date

与

as_of

一致；

market_data_as_of

为技术指标使用的最新K线日期（周末运行时与

as_of

不同）。

Output Format

输出格式

Phase 1 JSON:

parabolic_short_<as_of>.json

(schema_version 1.0). Phase 2 JSON:

parabolic_short_plan_<as_of>.json

(schema_version 1.0). Phase 3 JSON:

parabolic_short_intraday_<as_of>.json

(schema_version 1.0, phase =

intraday_monitor

). The contract is pinned by

tests/test_schema_contract.py

plus

tests/test_monitor_intraday_smoke.py

for Phase 3.

阶段1 JSON：

parabolic_short_<as_of>.json

（schema_version 1.0）。阶段2 JSON：

parabolic_short_plan_<as_of>.json

（schema_version 1.0）。阶段3 JSON：

parabolic_short_intraday_<as_of>.json

（schema_version 1.0，phase =

intraday_monitor

）。格式约定由

tests/test_schema_contract.py

及阶段3的

tests/test_monitor_intraday_smoke.py

保障。

Resources

参考资源

```
references/parabolic_short_methodology.md
```
— Qullamaggie's 3-trigger framework and exhaustion signals.
```
references/short_invalidation_rules.md
```
— mode-aware exclusion rules.
```
references/short_risk_management.md
```
— Rule 201, ETB vs HTB, locate.
```
references/intraday_trigger_playbook.md
```
— detail on each trigger type, the FSM transitions Phase 3 implements, and same-bar tie-break semantics.
```
references/broker_capability_matrix.md
```
— what each broker exposes through its API for short inventory.

```
references/parabolic_short_methodology.md
```
——Qullamaggie的三触发框架及衰竭信号说明。
```
references/short_invalidation_rules.md
```
——模式感知的排除规则。
```
references/short_risk_management.md
```
——Rule 201、ETB与HTB、融券定位说明。
```
references/intraday_trigger_playbook.md
```
——各触发类型细节、阶段3实现的FSM转换逻辑、同K线平局处理规则。
```
references/broker_capability_matrix.md
```
——各券商API暴露的融券库存信息说明。