claude-trading-skills 抛物线做空交易计划器实战:三阶段筛选、盘前计划与 5 分钟触发状态机解析
claude-trading-skills 抛物线做空交易计划器实战:三阶段筛选、盘前计划与 5 分钟触发状态机解析
本文以 claude-trading-skills 仓库中的 parabolic-short-trade-planner 技能为对象,系统拆解它如何把 Qullamaggie 风格的“抛物线衰竭做空”流程拆成三个可独立运行、可离线回放的阶段:日线 5 因子筛选、盘前条件计划生成、盘中 5 分钟 K 线触发状态机。读完后你能掌握每个 CLI 参数的取值与默认值、A/B/C/D 评级的打分来源、SSR(SEC Rule 201)与借券门槛如何阻断交易、三类触发计划的 entry_hint/stop_hint 语义,以及为什么这个技能在设计上永远不发送订单。
一、技能定位:只做检测,不做下单
文档对该技能的定位只有一句关键约束:“The skill never sends orders.” 它输出 JSON + Markdown,由交易者在自己的券商端人工复核后手动执行。这个边界在源码里反复出现:
- Phase 2 的计划生成器只产出
entry_hint/stop_hint这类公式字符串,不写死股数,股数在触发时刻才由shares_formula求值(size_recipe_builder.py)。 - Phase 3 即使检测到
triggered,也只写出entry_actual、stop_actual、shares_actual三个字段供人读(monitor_intraday_trigger.py)。
适用场景(来自文档第 2 节):
- 从 S&P 500 或自定义 CSV 构建每日抛物线做空观察名单;
- 把观察名单翻译成带借券 / SSR / 状态上限门控的盘前交易计划;
- 在下单前审计某个标的的“阻断型”与“提示型”人工确认原因。
明确不属于本技能的范围:多头动量筛选(用 vcp-screener 或 canslim-screener)、1 分钟或更细粒度的盘中信号(Phase 3 只看 5 分钟 K)、以及实盘下单路由。
二、三阶段架构与数据流
三个脚本构成一条单向流水线,中间产物是文件,而不是内存状态:
| 阶段 | 入口脚本 | 输入 | 输出 |
|---|---|---|---|
| Phase 1 | screen_parabolic.py |
FMP 日线(EOD)+ 公司概况 + 财报日历 | parabolic_short_<date>.json / .md |
| Phase 2 | generate_pre_market_plan.py |
Phase 1 JSON + 券商借券(Alpaca 或手动)+ SSR 状态 | parabolic_short_plan_<date>.json |
| Phase 3 | monitor_intraday_trigger.py |
Phase 2 JSON + 5 分钟 K 线(Alpaca 或 fixture) | parabolic_short_intraday_<date>.json |
三份输出统一带 schema_version: "1.0"、skill: "parabolic-short-trade-planner",并以 phase 字段区分(screen / pre_market_plan / intraday_monitor)。契约由测试固定:Phase 1 与 Phase 2 由 tests/test_schema_contract.py 覆盖,Phase 3 另加 tests/test_monitor_intraday_smoke.py(见 SKILL.md)。
这种“文件即接口”的设计带来两个直接好处:任一阶段可单独重跑;Phase 3 可以用 fixture 完全离线复现,不需要券商账户。
三、前置条件与环境
文档第 3 节列出的最小依赖,在 requirements.txt 中被固化:
pandas-market-calendars==5.2.2
requests>=2.31.0
- FMP API Key 必需:通过环境变量
FMP_API_KEY或--api-key传入。缺失时 Phase 1 会以非零状态退出并提示 “FMP_API_KEY is required (env or --api-key) unless --dry-run is used”(screen_parabolic.py)。 - Alpaca 可选:用于 Phase 2 的借券库存检查和 Phase 3 的实时 5 分钟 K 线。技能不走 Alpaca SDK,而是直接发
requests请求。没有 Alpaca 凭证时,Phase 2 会回落到ManualBrokerAdapter,把每个标的标成borrow_inventory_unavailable且plan_status: watch_only。 - Python 3.9+:
zoneinfo是标准库依赖,Phase 3 的 ET/DST 处理完全依赖它。
日历依赖由 pandas-market-calendars 提供,_market_calendar.py 在缺失时会抛出 CalendarDependencyMissingError,三个 CLI 都把它转换成 exit code 2 并打印安装提示(例如 screen_parabolic.py)。这一点很重要:技能宁可失败退出,也不会把“工作日”当成“交易日”继续算。
四、Phase 1:日线 5 因子筛选
4.1 快速开始
python3 skills/parabolic-short-trade-planner/scripts/screen_parabolic.py \
--mode safe_largecap --as-of 2026-04-30 --output-dir reports/
运行后会写出 reports/parabolic_short_2026-04-30.json 与同名 .md。Markdown 报告按评级 A→D 分组,每个标的给出 5 日涨幅、20DMA 偏离、量比、ATR(14)、关键均线位、状态上限与警告(parabolic_report_generator.py)。
4.2 完整 CLI 参数表
以下默认值全部取自 screen_parabolic.py 的 build_arg_parser。
| 参数 | 默认值 | 作用与说明 |
|---|---|---|
--mode |
safe_largecap |
只能取 safe_largecap / classic_qm,决定失效阈值与 5 日 ROC 下限 |
--universe |
sp500 |
默认拉 S&P 500 成分;另一条路径为 finviz-csv |
--universe-csv |
无 | --universe finviz-csv 时必填,按行取第一列作为代码 |
--lookback-days |
60 |
拉取日线根数;内部至少需要 21 根才能计算 MA/ATR/区间扩张 |
--min-roc-5d |
按模式(30 / 100) | 覆盖 5 日涨幅门槛 |
--min-ma20-extension-pct |
25.0 |
收盘价相对 20DMA 的最小百分比偏离 |
--min-atr-extension |
4.0 |
收盘价相对 20DMA 的最小 ATR 偏离倍数 |
--min-price |
5.00 |
解析但当前未接入筛选逻辑(见 4.7) |
--min-adv-usd / --min-market-cap / --max-market-cap |
None |
同上,解析但当前未接入筛选逻辑 |
--exclude-earnings-within-days |
2 |
日历天;下一个财报落在窗口内即硬性剔除 |
--earnings-catalyst-window-days |
10 |
交易日;上一次财报在窗口内则打软警告 |
--top |
25 |
排序后截断条数 |
--watch-min-grade |
C |
低于该评级直接丢弃 |
--max-api-calls |
800 |
FMP 调用预算,超限即停止并告警 |
--api-key |
无 | 优先于 FMP_API_KEY |
--output-dir |
reports/ |
输出目录,不存在会自动创建 |
--output-prefix |
parabolic_short |
输出文件前缀 |
--as-of |
今天(ET) | 严格 YYYY-MM-DD,非零填充会被拒绝 |
--dry-run / --fixture |
关闭 / 无 | 离线读取 JSON fixture,不访问 FMP |
--verbose |
关闭 | 打开 DEBUG,把逐标的剔除原因打出来 |
两个容易踩的坑:
--as-of用严格校验函数_iso_date_arg,2026-4-30这种非零填充写法会被 argparse 直接拒绝(screen_parabolic.py)。- 历史日期只允许配合
--dry-run。实时模式下如果--as-of不等于今天,程序打印 “the live universe and profile endpoints are not point-in-time” 并返回2(screen_parabolic.py)。这是一个诚实的防回测偏差设计:成分股列表和公司概况接口不是时点数据。
4.3 硬失效规则:先砍掉不该看的图
评分之前先做失效检查,实现在 invalidation_rules.py。两种模式的阈值:
| 规则 | safe_largecap |
classic_qm |
|---|---|---|
| 最小市值 | 20 亿美元 | 3 亿美元 |
| 20 日均成交额(ADV) | 2000 万美元 | 500 万美元 |
| 最小价格 | 5.00 美元 | 5.00 美元 |
| 最少上市天数 | 60 | 60 |
| 财报禁区(日历天) | 2 | 2 |
每条规则都会产出可审计的字符串原因,例如 market_cap_1500000000_below_2000000000、adv_3000000_below_5000000、earnings_within_1d_blackout_2d、listed_only_45d_below_60d。这解释了文档为什么强调“mode-aware”:classic_qm 主动放宽市值和 ADV 下限,是为了保住 Qullamaggie 真正瞄准的小盘爆炒行情,代价是流动性风险显著上升。
check_invalidation 还接受 override 字典。Phase 1 正是用它把 CLI 的 --exclude-earnings-within-days 真正传入硬性财报禁区,否则模式默认值会一直停在 2 天(screen_parabolic.py)。
4.4 5 因子评分:权重与分段映射
综合分由 5 个 0–100 子分加权求和,权重定义在 parabolic_scorer.py:
ma_extension 0.30 / acceleration 0.25 / volume_climax 0.20 / range_expansion 0.15 / liquidity 0.10
子分本身是刻意做成简单的分段线性函数,便于预测和测试(parabolic_score_calculator.py):
- MA 扩张(30%):两个信号各占一半。
ext_20dma_pct在 20%→120% 之间线性映射到 0→100;ext_20dma_atr(以 ATR(14) 为单位的偏离)在 3→10 之间映射。用 ATR 归一化是为了不让高波动小盘股天然吃亏。 - 加速度(25%):4 个子项加权——5 日涨幅(20%→100%,权重 0.4)、连续阳线天数(2→5 根,权重 0.2)、3 日均收益 / 10 日均收益的加速比(1.0→2.0,权重 0.2)、3 日涨幅(10%→50%,权重 0.2)。
- 成交量高潮(20%):最新量 / 20 日均量,1.5x→5.0x 线性映射。
- 区间扩张(15%):最近 5 日平均真实波幅 ÷ 其之前 20 日平均真实波幅,1.2→3.0 映射;两个窗口不重叠(range_expansion_calculator.py)。
- 流动性(10%):先把 20 日 ADV 做 log10 缩放,
$10M → 0、约$316M → 10,再乘以 10 得到 0–100(liquidity_metrics_calculator.py)。
4.5 A/B/C/D 评级与对应操作建议
阈值表与逐级指引都在 parabolic_scorer.py:
| 分数 | 评级 | 描述 | 操作指引 |
|---|---|---|---|
| ≥ 85 | A | 高确信度抛物线衰竭,等待触发 | 建观察仓,规划 ORL / 首次红 5 分钟 / VWAP 失败三种触发,确认借券 |
| ≥ 70 | B | 扎实候选,需要严格触发纪律 | 仅观察;只有在干净的盘中触发 + 阻断原因清空时才交易 |
| ≥ 50 | C | 边缘,默认只观察 | 监控是否进一步走坏;默认不进入盘前计划 |
| ≥ 0 | D | 弱形态,排除 | 不交易,通常是扩张不足或没有加速 |
注意 --watch-min-grade(默认 C)与 Phase 2 的 --tradable-min-grade(默认 B)是两个不同闸门:前者决定“能不能进报告”,后者决定“能不能变成交易计划”。评级比较由 grade_at_or_above 完成,非法字母一律返回 False。
4.6 状态上限与警告:不剔除,但限制交易
state_caps.py 处理一个悖论:抛物线候选按定义就是“创新高 + 强势收盘 + 放量”,这些指标在趋势模板里全是看多信号。
still_in_markup(状态上限):收盘位于当日区间上方 80% 且近期创 52 周新高。它不作为硬性排除,但 Phase 2 会把它变成阻断型原因,强制trade_allowed_without_manual=False。too_early_to_short(警告):同样是强收盘,且量比 ≥ 2.0,但未被still_in_markup覆盖。仅提示,Phase 2 保留计划并让每个触发都带wait_for_trigger=True。wait_for_first_crack(警告):盘前再跳空 ≥ 5%,提醒重点看“首次红 5 分钟”方案。
still_in_markup 与 too_early_to_short 互斥:前者优先,代码里显式跳过后者。
4.7 财报元数据:两种单位不能混
Phase 1 每次运行只调用一次 FMP 财报日历(不是逐标的调用),时间窗为 <a href="https://link.gitcode.com/i/6af82d5390b41a6e963d66de0f8fc653" target="_blank">run_date - (catalyst_window + 7), run_date + (exclude_window + 7)],额外 7 天缓冲吸收窗口边缘的周末与假日([screen_parabolic.py)。
每个候选输出 6 个相关字段,单位刻意分开:
| 字段 | 单位 | 用途 |
|---|---|---|
last_earnings_date / next_earnings_date |
日期 | 展示 |
trading_days_since_earnings |
交易日(XNYS 会话) | 软警告 recent_earnings_catalyst |
earnings_within_days |
日历天(向前) | 硬性禁区 |
earnings_blackout_days |
配置阈值 | 展示配置值 |
earnings_in_blackout_window |
布尔 | 是否落在禁区内 |
earnings_within_2d |
布尔 | 历史遗留字段,固定按 ≤2 日历天计算 |
交易日计数用 count_sessions("XNYS", start, end, include_start=False, include_end=True),即不包含起点、包含终点(screen_parabolic.py)。混用这两种单位会让警告提前或滞后一两天,所以源码把注释写得非常显眼。
4.8 三个日期字段的语义
顶层报告里有 as_of、run_date、market_data_as_of 三个日期,含义不同:
as_of:计划日,Phase 2 用它生成 plan ID 和 SSR 状态文件名,不允许下游改写;run_date:与as_of相同,为向前兼容单独暴露;market_data_as_of:实际用于技术指标的最新 K 线日期。周末运行时它会早于as_of。若多标的日期不一致,顶层会取最大值并加warnings: <a href="https://link.gitcode.com/i/caa87a2b9500d3627e56ace0a91ba313" target="_blank">"mixed_market_data_as_of"]([parabolic_report_generator.py)。
4.9 逐标的流水线与 K 线方向
screen_one_candidate 的顺序是:归一化 K 线 → 检查是否 ≥21 根 → 算 5 因子 → 失效检查 → 三道阈值闸门 → 综合评分 → 状态上限 → 财报软警告 → 渲染(screen_parabolic.py)。
方向问题必须注意:FMP 的历史价格是近的在前,而所有计算函数要求时间正序。normalize_bars(..., output_order="chronological") 负责翻转;_bars_on_or_before 则在消费边界裁掉超过 --as-of 的 K 线(bar_normalizer.py)。
一个值得记录的实现细节:--min-price、--min-adv-usd、--min-market-cap、--max-market-cap 四个参数在当前 screen_parabolic.py 中只出现在 build_arg_parser,未参与筛选逻辑;从源码结构看,实际生效的价格/市值/ADV 门槛来自 invalidation_rules 的模式阈值。使用这组参数时不要假设它们已经改变筛选结果。
4.10 无 API 的离线冒烟
python3 skills/parabolic-short-trade-planner/scripts/screen_parabolic.py \
--dry-run --fixture skills/parabolic-short-trade-planner/scripts/tests/fixtures/dry_run_minimal.json \
--as-of 2026-04-30 --output-dir reports/
fixture 结构在 run_dry_run 的 docstring 里写明:{"symbols": <a href="https://link.gitcode.com/i/706828402650b0663a9bc1221ed0c984" target="_blank">{"ticker", "bars", "quote", "profile", "earnings_within_days", "last_earnings_date", "next_earnings_date", "trading_days_since_earnings", "market_data_as_of"}]},其中财务字段均可省略。若 fixture 显式给出 market_data_as_of 且晚于 --as-of,程序会直接报错,防止“偷看未来”([screen_parabolic.py)。
五、Phase 2:盘前条件计划生成
5.1 快速开始
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_<as_of>.json。若 Alpaca 未配置,请加 --broker none 走手动清单,避免不必要地尝试导入 requests。
5.2 完整 CLI 参数表
来自 generate_pre_market_plan.py:
| 参数 | 默认值 | 说明 |
|---|---|---|
--candidates-json |
必填 | Phase 1 输出路径 |
--tradable-min-grade |
B |
低于该评级不生成计划 |
--account-size |
100000 |
账户权益(美元) |
--risk-bps |
50 |
单笔风险,基点;50 = 0.5% |
--max-position-pct |
5.0 |
单标的市值上限,占账户百分比 |
--max-short-exposure-pct |
20.0 |
空头总敞口上限,占账户百分比 |
--current-short-exposure |
0.0 |
已占用的空头金额 |
--stop-buffer-atr |
0.25 |
ORL 止损在 session HOD 之上追加的 ATR 倍数 |
--reference-r-multiples |
1.0,2.0,3.0 |
参考 R 倍数,写进每个计划 |
--broker |
alpaca |
可选 alpaca / none |
--alpaca-api-key / --alpaca-secret |
无 | 也可用环境变量 |
--alpaca-paper |
true |
字符串形式,内部小写比较 |
--ssr-state-dir |
state/parabolic_short/ |
SSR 状态落盘目录 |
--output-dir / --output-prefix |
reports/ / parabolic_short_plan |
输出位置 |
--as-of |
继承 Phase 1 | 覆盖计划日;用于第二日 SSR 结转冒烟 |
--verbose |
关闭 | DEBUG 日志 |
5.3 借券能力适配层
Phase 2 需要券商回答四个问题:能否开新空、借券费率是多少、费率是否已知、是否需要人工 locate。不同券商 API 差异极大(Alpaca 用 shortable / easy_to_borrow 标志,IB 用 locate API + 费率表),因此技能只依赖一个薄适配层,契约写在 broker_short_inventory_adapter.py:
shortable / easy_to_borrow / can_open_new_short / borrow_fee_apr
borrow_fee_manual_check_required / manual_locate_required / source / checked_at
ManualBrokerAdapter 是 --broker none 或凭证缺失时的哨兵实现,它把所有闸门都标成“需人工核查”,因此每个候选都会被标成 borrow_inventory_unavailable。
5.4 SSR 状态:继承而非重拉
ssr_state_tracker.py 实现 SEC Rule 201 判定:当价格相对前一日常规时段收盘下跌 ≥10% 时触发,当日剩余时间禁止在全国最优买价或以下做空,并延续到下一个交易日。
两个设计决策写得很清楚:
prior_regular_close必须是常规时段 16:00 ET 收盘价,不是盘后报价。Phase 2 从 Phase 1 的key_levels.prior_close继承,绝不用 FMPquote接口重拉,因为那个字段可能漂移到盘后价。- 状态落在
state/parabolic_short/ssr_state_<ticker>_<date>.json,用previous_session_before("XNYS", ...)找上一交易日,从而把昨天的ssr_triggered_today确定性结转成今天的ssr_carryover_from_prior_day。
MVP 阶段没有接入盘前成交价,所以 Phase 2 把收盘价同时当作 prior close 和 “current price”,此时 SSR 只能表达结转,无法判断“今天盘中刚触发”。源码注释明确承认了这一限制。
5.5 阻断型 vs 提示型原因
manual_reasons.py 把原因拆成两组,避免“所有计划看起来一样危险”:
| 来源 | 归入 blocking | 归入 advisory |
|---|---|---|
| 券商库存 | borrow_inventory_unavailable、htb_borrow_fee_unknown |
manual_locate_required |
| SSR | ssr_active_today、ssr_carryover |
— |
| 状态上限 | state_cap:<name> |
— |
| 警告 | — | warning:<name>,如 warning:too_early_to_short、warning:recent_earnings_catalyst |
| 盘前数据 | premarket_high_low_unavailable |
— |
派生两个布尔:trade_allowed_without_manual = not blocking(仅有 advisory 时为真),requires_manual_confirmation = 任一原因为真。
plan_status 的分类由 _HARD_BLOCKERS 决定(generate_pre_market_plan.py):
borrow_inventory_unavailable、ssr_active_today、ssr_carryover属于“今天没有可行路径”,直接watch_only;- HTB 费率未知、盘前高低点缺失、状态上限属于“可以与券商核实后清除”,仍算
actionable,只是被门控。
因此文档第 5 节要求下单前逐票读三个字段:plan_status、blocking_manual_reasons(必须全部清空)、advisory_manual_reasons(只做提醒)。
5.6 三类触发计划
每个候选生成三个 plan_id,格式为 <TICKER>-<YYYYMMDD>-<ORL5|FR5|VWF>(generate_pre_market_plan.py)。
1) 5 分钟开盘区间低点破位(orl_5min_break),见 orl_plan_builder.py:
entry_hint:5min_orl_low - 0.05stop_hint:session_HOD + {stop_buffer_atr} * ATR(默认 0.25)- 结构目标:
dma_10、dma_20
2) 第一根红 5 分钟(first_red_5min),见 first_red_plan_builder.py:
entry_hint:first_red_5min_low - 0.05stop_hint:first_red_5min_high- 适用于开盘一路阳线、追进去风险最高的场景。
3) VWAP 失败(vwap_fail),见 vwap_fail_plan_builder.py:
entry_hint:lower_high_low - 0.05stop_hint:vwap_reclaim_5min_close
三者都带 wait_for_trigger: True,且 size_recipe 是复制进去的同一份配方。
5.7 仓位配方:为什么 Phase 2 不给股数
size_recipe_builder.py 的注释直接说明了动机:ORL / 首红 / VWAP 失败这三种入场在触发前根本不知道真实的 entry 和 stop,Phase 2 若写死 shares: 200 就是拍脑袋。所以它只产出配方:
risk_usd = account_size × risk_bps / 10000(10 万账户、50bps → 500 美元)max_position_value_usd = account_size × max_position_pct / 100(默认 5% → 5000 美元)- 若剩余空头容量(
max_short_exposure_usd - current_short_exposure)小于单标的上限,则把上限压到剩余容量,并置exposure_cap_applied=True;剩余容量 ≤ 0 时上限直接归零。 shares_formula是一段给人读的字符串:floor(min(risk_usd / (stop_actual - entry_actual), max_position_value_usd / entry_actual))
Phase 3 绝不会 eval 这个字符串,而是用代码实现同一公式。
六、Phase 3:5 分钟触发状态机
6.1 快速开始
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 包裹。脚本本身不内建循环,一次运行只评估一次,崩溃恢复就是“再跑一遍”。
6.2 完整 CLI 参数表
来自 monitor_intraday_trigger.py:
| 参数 | 默认值 | 说明 |
|---|---|---|
--plans-json |
必填 | Phase 2 输出路径 |
--bars-source |
必填 | alpaca 或 fixture |
--bars-fixture |
无 | fixture 模式必填,结构为 {ticker: [bars]} |
--state-dir |
state/parabolic_short/ |
逐 plan 状态目录 |
--output-dir / --output-prefix |
reports/ / parabolic_short_intraday |
输出位置 |
--as-of |
由 --now-et 推导的 ET 会话日 |
覆盖会话日期 |
--now-et |
当前 ET 时间 | ISO 8601 且必须带时区偏移,否则退出 |
--stop-buffer-atr |
0.25 |
ORL 止损缓冲 |
--include-watch-only |
关闭 | 默认跳过 watch_only 计划 |
--alpaca-api-key / --alpaca-secret |
无 | 也可用环境变量 |
--alpaca-paper |
true |
纸面/实盘数据端点 |
--alpaca-feed |
iex |
可选 iex / sip |
--verbose |
关闭 | DEBUG 日志 |
market_status 字段由 is_regular_session(now_et) 判定,输出 regular_session 或 closed;日历判定走 XNYS,开盘边界含、收盘边界不含(market_clock.py)。
6.3 幂等性契约:FSM 是纯函数
这是整个技能最重要的工程约束,写在 intraday_state_machine.py 的模块注释里:
FSM 必须是
(plan, bars, atr_14)的纯函数。prior_state不是输入。
每次运行都从开盘第一根 K 线重新左折叠到 now_et(或 --now-et)。因此同一分钟重复运行得到相同状态;prior_state 只被 CLI 用于 diff/通知展示,永不推进状态机。test_one_shot_idempotency.py 专门验证这一点。
唯一的例外是“没有 K 线”的场景:适配器返回空列表时,_no_bars_state 会承载上一轮状态用于展示连续性,但显式标注 evaluation_status="no_bars",且不推进 FSM(monitor_intraday_trigger.py)。
6.4 三种 FSM 的完整迁移
ORL 破位(orl_evaluator.py):
armed → triggered:某根 K 线close < ORL low且volume ≥ 1.2 × ORL 根成交量;- 触发前的收复不作废,计划保持
armed; triggered → invalidated:之后某根 K 线close > ORL low且close > 当前 VWAP(两者必须同时满足);invalidated为终态。- 触发时
entry_actual = close - 0.05,stop_actual = session_high + 0.25 × atr_14。
两个跳过条件:缺 atr_14 时返回 evaluation_status="skipped" + skip_reason="atr_14_unavailable";第一根 K 线不是 09:30 ET 那根时(停牌或前 5 分钟无成交)返回 skip_reason="opening_range_bar_unavailable",宁可不判也不误锚。
首根红 5 分钟(first_red_evaluator.py):
armed → red_marked:第一根close < open;red_marked → triggered:之后某根low < red_low,entry_actual = red_low - 0.05,stop_actual = red_high;red_marked → invalidated:某根high > red_high;triggered → invalidated:触发后high > red_high(触发不是终态);- 同一根 K 线冲突时作废优先:若一根同时打出
high > red_high和low < red_low,判invalidated。理由写得很直白——扫过前高前低两侧的 K 线是失败形态,不是干净的破位。
VWAP 失败(vwap_fail_evaluator.py):
armed → first_crack_seen:首根 5 分钟收盘跌破 VWAP,且价格确实从 session HOD 回落(过滤开盘瞬间的 VWAP 噪声);→ vwap_retest_seen:下一根收盘回到 VWAP 或之上;→ rejection_confirmed:再下一根高点低于回测根且收盘重新跌破 VWAP;→ triggered:之后某根low < 拒绝根 low,entry_actual = 拒绝根 low - 0.05;triggered → invalidated:之后某根收盘重回 VWAP 之上。
VWAP 采用会话累计而非滚动窗口,09:30 ET 重置,用每根 K 线的收盘价参与加权(vwap.py)。注释明确说明:不用 hlc/3 约定,是为了让 FSM 的“5 分钟收盘 vs VWAP”判断与 K 线收盘触发语义一致。
6.5 股数求解:代码实现,绝不 eval
intraday_size_resolver.py 显式禁止 eval / exec / asteval,契约是:
floor(min(risk_usd / (stop_actual - entry_actual), max_position_value_usd / entry_actual))
空头方向要求 stop_actual > entry_actual(止损在入场价上方),否则抛 ValueError。测试 test_intraday_size_resolver.py::test_size_recipe_string_matches_resolver 强制 SHARES_FORMULA 字符串与实现保持同步——这是把“文档字符串”变成可执行契约的一个实用手法。
6.6 状态持久化与输出结构
逐 plan 状态文件名形如 intraday_<plan_id>_<as_of>.json,plan_id 中的 / 会被替换,日期进入文件名以防跨日覆盖(intraday_state_store.py)。
Phase 3 输出顶层字段:schema_version、skill、phase="intraday_monitor"、as_of、evaluated_at、now_et、market_status、data_source(alpaca_v2_stocks_bars 或 fixture)、monitored_plans。每个被监控计划至少包含 state、evaluation_status、skip_reason、armed_at / triggered_at / invalidated_at、invalidation_reason、entry_actual、stop_actual、shares_actual、size_recipe_resolved、session_high / session_low、last_bar_ts。即便没有 K 线,也保证键集合齐全(值为 null),方便下游统一消费。
七、安全边界:三条必须人工确认的事
文档在 Phase 3 之后特意加了一段风险声明,这段内容不是套话:
- 触发检测不是下单指令。
triggered只是一个状态值。 - 入场前必须确认:借券 / locate 可用性、SEC Rule 201 SSR 状态、券商的做空控件、以及券商当前的日内保证金或日内交易控制。
- FINRA 已用日内保证金标准取代旧的 pattern-day-trader 日计数与 25,000 美元最低权益要求,生效日 2026-06-04,允许券商分阶段实施至 2027-10-20。这意味着同一份计划在不同券商、不同时间点的可执行性可能不同,技能无法替你判断。
更完整的规则与券商能力矩阵在参考文档中:short_risk_management.md、broker_capability_matrix.md、short_invalidation_rules.md、intraday_trigger_playbook.md、parabolic_short_methodology.md。
八、离线验证与冒烟测试
不需要任何 API Key 就能跑通全链路,这是该技能可被 CI 验证的关键:
# Phase 1:fixture 驱动
python3 skills/parabolic-short-trade-planner/scripts/screen_parabolic.py \
--dry-run --fixture skills/parabolic-short-trade-planner/scripts/tests/fixtures/dry_run_minimal.json \
--as-of 2026-04-30 --output-dir /tmp/out
# Phase 2:手动借券适配器
python3 skills/parabolic-short-trade-planner/scripts/generate_pre_market_plan.py \
--broker none \
--candidates-json skills/parabolic-short-trade-planner/scripts/tests/fixtures/phase2_plan_smoke.json \
--output-dir /tmp/out
# Phase 3:fixture K 线
python3 skills/parabolic-short-trade-planner/scripts/monitor_intraday_trigger.py \
--plans-json /tmp/out/parabolic_short_plan_<date>.json \
--bars-source fixture \
--bars-fixture skills/parabolic-short-trade-planner/scripts/tests/fixtures/intraday_bars/orl_clean_break.json \
--now-et 2026-05-05T09:45:00-04:00 \
--state-dir /tmp/state --output-dir /tmp/out
intraday_bars/ 下的 fixture 每个都自带 _doc 字段说明预期,例如 orl_clean_break.json 描述了“第 0 根设定 ORL low=149.00 / high=149.85 / vol=2,000,000;第 2 根收 148.50、量 2,800,000(1.4 倍)触发;此后无收复,终态 triggered”。同类 fixture 还覆盖 first_red_same_bar_invalidation_wins、orl_low_volume_no_fire、vwap_full_fsm、vwap_invalidated_after_trigger 等边界。
值得一读的测试文件:test_scorer.py、test_invalidation_rules.py、test_one_shot_idempotency.py、test_schema_contract.py、test_size_recipe.py、test_ssr_state_tracker.py。
九、已知限制与使用建议
- 只处理 5 分钟粒度。想要 1 分钟信号必须改代码,不是参数问题。
- Phase 2 不拉盘前成交数据。
premarket_levels的字段全部为null,并带premarket_source: "not_fetched_in_mvp",因此premarket_high_low_unavailable会稳定出现在阻断原因里,需要人工在券商端补看盘前高低点。 - SSR 只能判断结转。MVP 把收盘价同时当作 prior close 与 current price,所以“今天盘中刚触发”的信息要等盘前数据接入后才准确。
- 历史回放必须走 fixture。实时模式的成分股与公司概况接口不是时点数据,用历史
--as-of会直接退出。 --watch-min-grade与--tradable-min-grade是两个闸门。想把 C 级也做成计划,需要 Phase 2 显式传--tradable-min-grade C。- 状态目录要持久化。
state/parabolic_short/同时承载 SSR 结转与逐 plan 的 FSM 状态;把它放进临时目录会让第二天的结转判断失效,也会丢失 diff 展示所需的prior_state。
把这条流水线当成“带审计痕迹的盘中观察台”而不是“自动交易机器人”,才是它设计的本意:Phase 1 负责把上千只股票压缩成几十个带评级的名字,Phase 2 把名字翻译成带门控的条件单草案,Phase 3 用确定性的状态机告诉你“现在到底有没有触发、具体多少股”。最后的鼠标点击,始终留给人。