parabolic-short-trade-planner

概述

生成 Qullamaggie 风格的抛物线式做空观察名单，以及有条件的美股盘前计划。此技能绝不会发送订单。它会生成 JSON + Markdown，供人工在下单前对照经纪商进行审核。

分为三个阶段：

• 阶段 1（screen_parabolic.py）：从 FMP 获取 EOD K 线和公司简介，应用硬性失效规则（感知模式），对通过筛选的标的按 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 向前推进一步，持久化每个计划的状态，并写入包含 state、entry_actual、stop_actual 和 shares_actual（触发时）的 intraday_monitor JSON。单次运行——交易者每隔 1–5 分钟通过 watch 或 cron 运行；支持确定性重放，因此重复运行会得到逐字节相同的结果。

适用场景

用户希望执行以下操作时，请调用此技能：

• 基于 S&P 500（或自定义 CSV）生成每日抛物线式做空观察名单。
• 将观察名单转换为盘前交易计划，并明确设置借券 / SSR / 状态上限门控。
• 在通过 Alpaca 下单之前，审查候选标的需要人工确认的阻止性与建议性原因。

以下情况请勿调用：

• 多头动量筛选——请使用 vcp-screener 或 canslim-screener。
• 1 分钟或更短周期的日内信号——阶段 3 仅评估 5 分钟 K 线。
• 实时订单路由——此技能按设计仅用于检测；阶段 3 会输出包含具体入场价、止损价和股数的 triggered 状态，但交易者需手动下单。

工作流

阶段 1 — 每日筛选器

1. 确认已设置 FMP_API_KEY（环境变量或通过 --api-key 设置）。
2. 使用默认更安全的模式运行：

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

3. 检查 reports/parabolic_short_<date>.md——观察名单按评级分组（A→D）。
4. 将感兴趣的标的纳入阶段 2。

对于小盘股暴涨回落行情，请切换至 --mode classic_qm（市值和 ADV 下限更宽松，5 日 ROC 阈值更高）。

如需在不使用 API 的情况下测试，请使用 --dry-run --fixture <path> 运行，并指定 JSON 测试夹具（项目附带的夹具位于 scripts/tests/fixtures/dry_run_minimal.json）。

阶段 2 — 盘前计划生成器

1. 可选：设置 ALPACA_API_KEY / ALPACA_SECRET_KEY 以执行实时借券检查。未设置时，计划生成器会回退到 ManualBrokerAdapter，并将每个候选标的标记为 borrow_inventory_unavailable / plan_status: watch_only。
2. 运行：

   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/
   

3. 输出：reports/parabolic_short_plan_<date>.json。每个计划包含三个入场方案（5 分钟 ORL 突破、首根红色 5 分钟 K 线、VWAP 失守），并带有 entry_hint / stop_hint 公式字符串（不预设股数——交易者根据 shares_formula 在触发时计算股数）。

第 3 阶段 — 日内触发监控

1. 确认已设置 ALPACA_API_KEY / ALPACA_SECRET_KEY（第 3 阶段使用 Alpaca 市场数据；data.alpaca.markets 适用于模拟和实盘账户）。
2. 在美国常规交易时段内，按设定频率运行单次任务——通常在前 30 分钟每 60 s 运行一次，之后每 5 min 运行一次：

   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 ...' / cron 包装运行。
3. 输出：reports/parabolic_short_intraday_<date>.json 会列出每个受监控计划及其 state（armed / triggered / invalidated / FSM 专属状态）、基于 K 线的状态转换时间戳，以及触发时的 size_recipe_resolved（实际的 shares_actual）。
4. 如需在没有 API 的情况下进行测试，请使用 --bars-source fixture --bars-fixture <path>，并提供 JSON 测试数据（scripts/tests/fixtures/intraday_bars/）。

第 3 阶段的触发检测不是下单指令。手动做空之前，请确认借券/定位可用、SEC Rule 201 SSR 状态、券商的卖空管控，以及券商当前的日内保证金或日内交易管控。FINRA 已于 2026-06-04 起以日内保证金标准取代旧有的模式日内交易者交易日数和 25,000 美元最低净资产要求；券商可在 2027-10-20 前分阶段实施。

第 3 阶段是幂等的：每次运行都会从开盘到 now_et（或 --now-et 覆盖值）重放整个交易时段的 K 线，因此在同一分钟内重复运行会产生相同状态。prior_state 仅用于差异/通知显示，绝不会推进 FSM。

入场前检查计划

请读取每只股票的三个顶层字段：

• 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 个交易日——应将此走势标记为事件驱动，而非纯技术性暴涨）。

考虑财报因素的筛选

第 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 与其保持一致；market_data_as_of 是技术指标所用的最新 K 线日期（周末运行时可能与 as_of 不同）。

交易所日历与回放

运行计划器前请安装 requirements.txt。第 1 阶段的 --as-of 使用严格的 YYYY-MM-DD 格式，会过滤晚于该日期上限的 K 线，并按 XNYS 交易时段计算财报距今时间。第 3 阶段会考虑实际节假日和提前收盘；收盘边界不包含在内。历史日期仅在第 1 阶段使用 --dry-run 测试数据时接受；实时市场范围和公司概况接口不支持 PIT，因此对于非当前的 --as-of 会安全失败。

输出格式

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）。 契约由 tests/test_schema_contract.py 和 Phase 3 的 tests/test_monitor_intraday_smoke.py 固定。

资源

• references/parabolic_short_methodology.md — Qullamaggie 的 3 种触发条件 框架与衰竭信号。
• references/short_invalidation_rules.md — 按模式区分的排除规则。
• references/short_risk_management.md — Rule 201、ETB 与 HTB、借券。
• references/intraday_trigger_playbook.md — 各触发类型的详细说明、 Phase 3 实现的 FSM 转换，以及同一根 K 线的平局判定语义。
• references/broker_capability_matrix.md — 各经纪商通过其 API 提供的 卖空库存信息。