Claude Trading Skills 抛物线做空方法论解析:Qullamaggie 三触发框架如何落地为可回放的日内状态机
Claude Trading Skills 抛物线做空方法论解析:Qullamaggie 三触发框架如何落地为可回放的日内状态机
本文以 claude-trading-skills 仓库中的抛物线做空(Parabolic Short)方法论文档为主线,逐条拆解"抛物线标的认定条件 → 三类日内触发 → 失效规则 → 状态上限(state cap)"这套框架,并把它与仓库中的选股器、计划生成器、日内有限状态机(FSM)源码逐项对齐。读完后你能明确掌握每个阈值在代码里对应哪个参数、哪种情况会被硬性剔除、哪种情况只是被降级为 watch_only,以及如何用三条命令行完成从日线筛选到日内触发检测的完整流程。
方法论的第一性命题:延迟入场
原文档开篇给出了整套框架的立论:抛物线行情最终会以均值回归的方式崩塌,但在行情仍在爬升时提前做空,是最快的亏钱方式。因此本文档里的所有条件——5 日涨幅、均线延伸、连阳、量比——都不是入场信号,而是"观察名单过滤器"(watchlist filter)。真正的入场只发生在日内三类触发之一被确认之后。
这一点在仓库实现中体现得非常彻底:Phase 1 的 screen_parabolic.py 只产出带评级的候选清单,Phase 2 的 generate_pre_market_plan.py 只产出条件式计划(带 entry_hint / stop_hint 公式字符串,甚至不写死股数),Phase 3 的 monitor_intraday_trigger.py 才是唯一会输出 triggered 状态的程序,而它依然不下单。参见 SKILL.md 中 "The skill never sends orders" 的定位说明。
抛物线认定:五个必须同时成立的日线前置条件
原文档列出的门槛是"全部为真"才算合格,逐条对照源码后可以看清哪些是硬门槛、哪些进入了评分。
| 条件 | safe_largecap |
classic_qm |
仓库实现位置 |
|---|---|---|---|
| 5 日涨幅 | ≥ +30% | ≥ +100% | screen_parabolic.py DEFAULT_MIN_ROC_5D |
| 最新收盘距 20 日 SMA | ≥ +25% 且 ≥ 4 个 ATR 单位 | 同左 | --min-ma20-extension-pct / --min-atr-extension |
| 连续阳线数 + 加速比 | ≥ 3 根,且 3 日/10 日均值比 > 1.0 | 同左 | acceleration_calculator.py |
| 最新量比(对 20 日均量) | ≥ 1.5× | 同左 | liquidity_metrics_calculator.py |
| 20 日平均成交额下限 | ≥ $20M | ≥ $5M | invalidation_rules.py |
均线延伸为什么要做 ATR 归一化
原文档特别强调"波动率归一化——高 ATR 的小盘股不会被惩罚"。这个设计在 ma_extension_calculator.py 中有直接对应:除了 ext_20dma_pct(百分比距离),还输出 ext_20dma_atr = (close - dma_20) / atr_14。百分比距离会把一只日均波动 15% 的小盘股误判为"延伸过度",而 ATR 单位距离表达的是"离均线几个标准波动",跨标的可比。
两个判断必须同时满足,这是源码里少见的"双重门槛"而非"取其一":
if ext_pct < args.min_ma20_extension_pct: # 默认 25.0
return None
ext_atr = raw_metrics.get("ext_20dma_atr")
if ext_atr is None or ext_atr < args.min_atr_extension: # 默认 4.0
return None
注意 ext_atr is None 也会被剔除:历史不足 21 根 K 线时 ATR 无法计算,候选直接出局,这与 normalize_bars 之后 len(bars) < 21 的前置检查互为兜底。
加速比的定义细节
acceleration_ratio_3_over_10 用"近 3 日日均简单收益率 ÷ 近 10 日日均简单收益率"计算,源码里有一个关键的反向保护:当长窗口均值为非正(行情走平或下跌)时返回 None,即"没有加速可谈",而不是返回一个负数或极大值去污染排序。
short_avg = _avg_daily_return(closes, 3)
long_avg = _avg_daily_return(closes, 10)
if short_avg is None or long_avg is None or long_avg <= 0:
return None
return short_avg / long_avg
连阳计数 consecutive_green_days 用的是 close > open 自最新一根向前回溯,遇到第一根非阳线即停止,这也解释了为什么文档要求"3 根以上连续阳线"——它是抛物线末段最直观的形状特征。
需要留意的实现差异:硬门槛 vs 评分输入
方法论文档把五条都写成"必须为真",但从源码结构看,真正构成准入拦截的是四类:5 日 ROC、20 日 SMA 百分比延伸、ATR 延伸、以及失效规则里的大小盘/成交额/股价/上市天数/财报窗口。而连阳数与加速比、量比 1.5× 并未作为独立布尔门槛,它们进入的是 5 因子评分:acceleration 分量占 25% 权重,volume_climax 分量占 20%。量比映射为 _linear(volume_ratio, 1.5, 5.0),所以 1.5× 只是"该分量从 0 分起步"的起点,而不是"低于 1.5× 即出局"。读文档时把这一层区分清楚,能避免在调参时误判行为。
三类触发:从文字规则到状态机
原文档列的三类触发,在仓库里各自对应一个纯函数评估器,全部位于 intraday_evaluators/ 目录,共享同一套行为约定:以 5 分钟 K 线收盘判定(不用影线触碰)、只消费已确认的 K 线、时间戳为 America/New_York 的开盘瞬间语义。
1. 5 分钟开盘区间低点(ORL)破位
文档描述:标记开盘首根 5 分钟 K 线的低点,若后续某根 5 分钟 K 线在成交量 ≥ 1.2× 该首根 K 线量能的情况下收于 ORL 下方,则做空破位;止损放在盘中最高点(HOD)上方加 0.25 ATR。
orl_evaluator.py 的实现把这段话拆成三段硬逻辑:
- 触发:
bar["c"] < orl_low且bar["v"] >= 1.2 * orl_volume,两个条件必须同时成立(量能条件由常量ORL_VOLUME_MULTIPLIER = 1.2固定)。 - 入场价:
entry_actual = round(bar["c"] - 0.05, 4),即跌破 K 线收盘价再减 5 美分,与 Phase 2 的entry_hint: "5min_orl_low - 0.05"对应。 - 止损价:
stop_actual = round(session_high + stop_buffer_atr * atr_14, 4),其中session_high是截至当前 bar 的运行最高价,stop_buffer_atr默认 0.25。
这里有个容易踩的坑:ORL 必须锚定 09:30 ET 那根 K 线。Alpaca 在开盘无量或停牌时会跳过该区间,源码因此显式校验首根 bar 的小时/分钟:
first_bar_ts = datetime.fromisoformat(bars[0]["ts_et"])
if (first_bar_ts.hour, first_bar_ts.minute) != (OPENING_BAR_HOUR, OPENING_BAR_MINUTE):
out["evaluation_status"] = "skipped"
out["skip_reason"] = "opening_range_bar_unavailable"
return out
宁可 skipped 也不错误锚定到 09:35 之后的 bar——这是"失效安全"而非"尽力而为"的设计取向。同理,若 atr_14 缺失,输出 skip_reason="atr_14_unavailable" 并保持 armed。
另一处细节:触发前重新站回 ORL 不会让计划失效(状态保持 armed),只有触发后某根 K 线同时满足"收盘 > ORL"和"收盘 > 当前 VWAP"两个条件才转为 invalidated。用测试可以验证这一点,见 test_orl_evaluator.py 中的断言:entry_actual == 148.45(148.50 − 0.05)、stop_actual == 150.35(149.85 + 0.25 × 2.0)。
2. 首根红色 5 分钟 K 线
文档描述:当开盘后一路连阳、抛物线持续延伸时,等待第一根红色 5 分钟 K 线,做空其低点破位,止损放在该 K 线高点之上。文档称这是"开盘跳空撞到阻力位时最安全的变体"。
first_red_evaluator.py 用两段状态实现:armed → red_marked(首根 close < open 的 bar,记录 red_low / red_high)→ triggered(后续某根 bar 的 low < red_low)。
这里最值得单独讲的是一条同 bar 冲突裁决规则:当同一根 K 线既上破 red_high(本该失效)又下破 red_low(本该触发)时,失效优先。源码在 red_marked 分支里把 invalidates 判断放在 triggers 之前,注释也写明了理由:"一根同时扫掉前结构两侧的 K 线是一次失败的形态,而不是干净的破位。"这种"做空侧保守主义"在实盘中意味着你会放弃一些边缘信号,换取规则可预测性。
止损直接取 red_high,不加 ATR 缓冲——因为首根红 K 线的高点本身就是结构位,这点与 ORL 的 ATR 缓冲形成有意的不对称。
3. VWAP 失败(VWAP fail)
文档描述:等待"first crack"(价格从盘中高点向 VWAP 塌陷),让它回测 VWAP,随后"5 分钟收盘重回 VWAP 下方 + 下破更低高点"即为入场;一旦 5 分钟收盘重新站上 VWAP(VWAP reclaim)立即失效。
vwap_fail_evaluator.py 是三者中最复杂的一个,实现为六状态链:
armed → first_crack_seen → vwap_retest_seen → rejection_confirmed → triggered → invalidated
各转移条件:
armed → first_crack_seen:某根 bar 收盘 < 当前 VWAP,且 该 bar 之前的运行最高价高于该 bar 收盘价。后半个条件是关键——它过滤掉"开盘就在 VWAP 下方"的假信号,确保这确实是"从 HOD 跌下来"的第一次裂口。源码为此专门维护prior_session_high变量。first_crack_seen → vwap_retest_seen:后续某根 bar 收盘 ≥ VWAP,同时记录该 bar 的高点为retest_bar_high。vwap_retest_seen → rejection_confirmed:再下一根 bar 的高点低于retest_bar_high(更低的高点)且 收盘回到 VWAP 下方,同时记录rejection_bar_low。rejection_confirmed → triggered:某根 bar 的low < rejection_bar_low,入场为rejection_bar_low - 0.05。triggered → invalidated:某根 bar 收盘 > 当前 VWAP(VWAP reclaim)。
VWAP 本身采用会话累积口径而非滚动窗口,由 vwap.py 的 vwap_for_each_bar() 统一计算:以每根 bar 的收盘价乘成交量累加后除以累计成交量,09:30 ET 重新起算。源码注释里明确了两个约定:使用 close 而非 hlc/3,因为 FSM 的所有判定都是"5 分钟收盘 vs VWAP";成交量为 0 的 bar 不参与分子分母,运行值直接沿用前值。此外 intraday_state_machine.py 会在一次运行中对同一份 bar 列表只算一次 VWAP,再共享给 ORL 与 VWAP fail 两个评估器。
需要留意的实现细节:Phase 2 生成的 stop_hint 是 "vwap_reclaim_5min_close",而回放代码实际把 stop_actual 取为 retest_bar_high。两者语义接近(都是"VWAP 被重新夺回则形态失败"的位置),但数值口径不同。读计划文件时以代码取值为准更稳妥。
硬性失效规则:先剔除,再评分
原文档把"hard skips"单列一节,并指向完整清单。对应 short_invalidation_rules.md 与 invalidation_rules.py 的 MODE_THRESHOLDS:
| 规则 | safe_largecap |
classic_qm |
|---|---|---|
| 市值下限 | < $2B 剔除 | < $300M 剔除 |
| 20 日平均成交额 | < $20M 剔除 | < $5M 剔除 |
| 最新收盘价 | < $5.00 剔除 | < $5.00 剔除 |
| 上市天数 | < 60 个交易日剔除 | < 60 个交易日剔除 |
| 财报窗口 | ≤ 2 自然日(前瞻)剔除 | 同左 |
| 用户 CSV 催化剂标记 | 标记即剔除 | 同左 |
每条规则都输出可审计的原因字符串,例如 earnings_within_1d_blackout_2d、adv_8000000_below_20000000、listed_only_31d_below_60d,便于在 --verbose 下定位剔除原因。财报窗口不是写死的 2 天:screen_parabolic.py 会把 --exclude-earnings-within-days 作为 override 传入 check_invalidation,否则模式默认值会吞掉 CLI 参数。
为什么要硬性剔除财报?原文档的理由是"财报风险是二元且不对称的"——即使图形极度抛物线,一次超预期的 beat-and-raise 也能隔夜跳空 +30%,越过任何止损。因此选股器不提供"穿过财报交易"的开关,财报后形态属于 earnings-trade-analyzer 或 pead-screener 的领域。
为什么要为一个更宽松的模式单独开口子?Qullamaggie 的典型目标是小盘股在数周内上涨 300%–1000%,这类标的过不了 safe_largecap。classic_qm 把市值与成交额门槛降下来让它们进入universe,代价是这些标的在券商侧更容易 borrow_inventory_unavailable,最终落到 plan_status: watch_only。
为什么需要 state cap:目标图形与"看涨图形"是同一张图
原文档最后一段是整套方法论中最容易被忽略、也最体现设计者经验的洞见:抛物线候选按定义就是不断创新高、强势收盘、放量——这些恰恰是趋势模板里的看涨特征。如果把它们当利空信号直接过滤掉,观察名单就空了。
仓库用 state_caps.py 把这类"软信号"与硬性剔除分开,输出三个标记:
still_in_markup:收盘处于当日区间上 20%(range_pos >= 0.80)且近 2 个交易日内创 52 周新高。这是 state cap(状态上限),不是死刑——A/B 级候选依然展示,但 Phase 2 会通过manual_reasons强制trade_allowed_without_manual=False,即必须先看到日内走弱。too_early_to_short:收盘同样在区间上 20%,但量比 ≥ 2.0(volume_ratio_threshold),且未被still_in_markup覆盖。这是纯咨询性警告,Phase 2 保留计划,只在每个入场方案上标wait_for_trigger=True。wait_for_first_crack:盘前再跳空 5% 以上(premarket_gap_threshold_pct)。Phase 2 据此强调首根红 K 线方案。
源码里有一个顺序细节:too_early_to_short 只在 still_in_markup 未命中时才追加,因为前者是更弱的信号,"已被更强的上限覆盖时不再重复标注"。
五因子评分与 A/B/C/D 分级
评分把前述原始指标压成 5 个 0–100 的子分,再按固定权重加权,见 parabolic_score_calculator.py 与 parabolic_scorer.py。
| 分量 | 权重 | 映射区间 |
|---|---|---|
ma_extension |
0.30 | 0.5 × linear(20DMA 百分比, 20→120) + 0.5 × linear(ATR 单位, 3→10) |
acceleration |
0.25 | 0.4 × 5 日涨幅(20→100) + 0.2 × 连阳数(2→5) + 0.2 × 加速比(1.0→2.0) + 0.2 × 3 日涨幅(10→50) |
volume_climax |
0.20 | linear(量比, 1.5→5.0) |
range_expansion |
0.15 | linear(近 5 日 ATR / 前 20 日 ATR, 1.2→3.0) |
liquidity |
0.10 | log10 标度,$10M → 0 分,约 $316M → 10 分,再 ×10 |
分档与指引:
- A(≥ 85):高确信度衰竭形态,等待触发;构建观察仓,规划三类触发,确认可借券。
- B(≥ 70):合格候选,必须严格执行触发纪律;仅当干净触发成立且
blocking_manual_reasons为空才可交易。 - C(≥ 50):边缘形态,默认被排除出盘前计划(
DEFAULT_WATCH_MIN_GRADE = "C",DEFAULT_TRADABLE_MIN_GRADE = "B")。 - D(< 50):不入场,通常是延伸不足或无加速。
ma_extension 分量 50/50 混合百分比与 ATR 单位,源码注释给出理由:ATR 单位负责波动率调整,原始百分比负责绝对拥挤度,两个信号都重要。range_expansion 的分子分母按构造不重叠——近 5 根真实波幅 vs 之前 20 根真实波幅,比值 > 2 即"日波动区间大约翻倍",这是最典型的 blow-off 签名。
从方法论到可执行计划:Phase 2 与 Phase 3
一个方案不写死股数,只写"配方"
plan_builders/ 里三个计划构造器输出的都是公式字符串而非具体数字:entry_hint、stop_hint、structural_targets(默认 dma_10 / dma_20)、reference_r_multiples(1.0 / 2.0 / 3.0)、size_recipe、wait_for_trigger: True。
原因写在 size_recipe_builder.py 的模块注释里:三类触发都要等到日内触发后才知道 entry 与 stop,Phase 2 只能交付一个配方,由 Phase 3 在触发时刻求值:
shares_formula = floor(min(risk_usd / (stop_actual - entry_actual),
max_position_value_usd / entry_actual))
配方参数与默认值:--account-size 100000、--risk-bps 50(0.5%)、--max-position-pct 5.0(单票上限占账户 5%)、--max-short-exposure-pct 20.0(空头总敞口上限)。当剩余空头容量小于单票上限时,max_position_value_usd 会被收紧到剩余容量并置 exposure_cap_applied=True;若剩余容量 ≤ 0,则直接压到 0,避免生成一个物理上无法执行的规模。
blocking 与 advisory 的分离
manual_reasons.py 把人工确认原因拆成两类,使 trade_allowed_without_manual 真正有意义(只存在 advisory 时它保持 True):
- blocking:
borrow_inventory_unavailable、htb_borrow_fee_unknown、ssr_active_today、ssr_carryover、state_cap:*、premarket_high_low_unavailable。 - advisory:
manual_locate_required(总是设置)、warning:too_early_to_short、warning:recent_earnings_catalyst、warning:wait_for_first_crack。
SSR(SEC Rule 201)判定在 ssr_state_tracker.py:当日相对前一交易日 4:00 PM ET 常规收盘跌幅 ≥ 10% 即触发,且规则要求把状态结转至下一个交易日,因此 prior_day_state.ssr_triggered_today 为真时今日直接继承 ssr_carryover_from_prior_day=True。源码特别注明前收盘必须来自 Phase 1 的 key_levels.prior_close(取自 historical-price-eod/full),不能让 Phase 2 重新从 quote 端点取值,否则该字段可能漂移到盘后价。
回放确定性:为什么重跑不会推进状态
Phase 3 的幂等契约是整套设计里最硬的一条约束:FSM 是 (plan, bars, atr_14) 的纯函数,每次运行都从开盘重放全部 bar 直至 now_et。prior_state 只用于展示与通知差异,不参与状态推进。这带来两个直接好处:同一分钟内重跑输出一致(字节级可复现);--now-et 可以精确复现历史某一时刻的判定结果。
配套的 bar 时间语义是:ts_et 表示 bar 开盘瞬间,一根 ts_et = T 的 bar 覆盖 [T, T+5min) 并在 T+5min 确认;适配器只返回已确认的 bar(bar_open + 5min <= until_et),FSM 永远看不到进行中的未完成 bar,因此不会出现"用未收盘的影线误触发"的问题。
实操:三阶段命令与参数
前置依赖:Python 3.9+,pandas-market-calendars==5.2.2、requests>=2.31.0(见 requirements.txt)。Phase 1 必须有 FMP_API_KEY(或 --api-key);Phase 2/3 的 Alpaca 密钥可选,缺失时 Phase 2 回落到 ManualBrokerAdapter 并把候选标为 watch_only。
Phase 1:日线筛选
python3 skills/parabolic-short-trade-planner/scripts/screen_parabolic.py \
--mode safe_largecap --as-of 2026-04-30 --output-dir reports/
常用参数(默认值来自源码 build_arg_parser):
--mode:safe_largecap(默认)/classic_qm--universe:默认sp500;--universe-csv在--universe finviz-csv时使用--lookback-days:默认 60--min-roc-5d:默认由模式决定(30 / 100)--min-ma20-extension-pct:默认 25.0;--min-atr-extension:默认 4.0--min-price5.00、--min-adv-usd、--min-market-cap、--max-market-cap--exclude-earnings-within-days2(前瞻,硬剔除)、--earnings-catalyst-window-days10(后视,软警告)--top25、--watch-min-gradeC、--max-api-calls800- 离线验证:
--dry-run --fixture <path>(样例见scripts/tests/fixtures/dry_run_minimal.json)
输出 reports/parabolic_short_<as_of>.md / .json(schema_version 1.0),观察名单按 A→D 分组。
--as-of 只接受严格 YYYY-MM-DD,会过滤掉该日期之后的 bar,并用 XNYS 交易日计算财报年龄。历史日期仅允许在 --dry-run fixture 模式下使用——实盘的 universe 与 profile 端点不是 point-in-time 数据,非当前日期会 fail closed 而非给出错误结果。
Phase 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/
关键参数:--tradable-min-grade(默认 B)、--max-position-pct 5.0、--max-short-exposure-pct 20.0、--current-short-exposure 0.0、--stop-buffer-atr 0.25、--reference-r-multiples "1.0,2.0,3.0"、--broker alpaca|none、--ssr-state-dir state/parabolic_short/。
输出 reports/parabolic_short_plan_<as_of>.json,每个候选含三个入场方案与 plan_status、blocking_manual_reasons、advisory_manual_reasons。
Phase 3:日内触发监测
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/
典型节奏是开盘 30 分钟内每 60 秒一次、之后每 5 分钟一次,可外包 watch -n 60 '...' 或 cron。离线回放用 --bars-source fixture --bars-fixture <path>。其他参数:--now-et(覆盖当前时间以复现历史判定)、--include-watch-only、--alpaca-feed iex|sip(默认 iex)、--stop-buffer-atr。
输出 reports/parabolic_short_intraday_<as_of>.json,逐计划给出 state、bar 派生的时间戳、以及触发时的 entry_actual / stop_actual / shares_actual。
触发之后仍然不是下单指令
Phase 3 的 triggered 只代表形态条件满足。文档明确要求:任何手动做空之前,必须自行确认可借券/可定位(locate)情况、SEC Rule 201 的 SSR 状态、券商做空控制开关,以及券商当前的日内保证金或日内交易控制。SKILL.md 还提到 FINRA 已用日内保证金标准替换旧的 pattern-day-trader 日计数与 $25,000 最低权益要求,该变更自 2026-06-04 生效,允许券商分阶段实施至 2027-10-20——具体执行口径请以你所用券商的现行规则为准。
边界与适用前提
把方法论读完并对照源码,可以清楚划出这套框架的能力边界:
- 只做 5 分钟粒度:Phase 3 评估 5 分钟 bar,1 分钟或更细的信号不在范围内。
- 只做检测,不做路由:仓库内没有任何下单路径,这是刻意的设计约束而非待办项。
- 只做美股:依赖 XNYS 交易日历,Phase 3 使用真实节假日与提前收盘,收盘边界为开区间。
- 港股/日股/加密不适用:日历与借券模型都与美股券商接口绑定,broker_capability_matrix.md 描述的是各家券商通过 API 暴露做空库存的差异。
- 多头动量筛选请另找工具:VCP 或 CANSLIM 类筛选属于 vcp-screener / canslim-screener。
小结
这份方法论的价值不在于那五个数字阈值,而在于它把"看涨图形即做空目标"这个反直觉事实工程化了:用硬性失效规则挡掉不该碰的标的(财报、微盘、流动性不足),用五因子评分把"最像衰竭"的排到前面,用 state cap 承认"现在可能还太早",最后用三类日内触发器强制把入场时机推迟到衰竭被看见的那一刻。仓库的三阶段实现则在工程层面加了三重保障——计划只给公式不给股数、FSM 是纯函数可字节级回放、触发是 skipped 优于错误锚定——这些都与原文档"宁可晚进,不可早进"的立论严格一致。