Python API 接口参考文档 (API Reference)

本文档面向需要在下游系统（如 LLM AI Agent、量化自动化交易流水线、复盘看板）中直接集成 tp-quant 的开发者。

安装包：pip install tp-quant

🎯 核心架构速查与对应关系 (Architecture & Quick Navigation)

tp-quant 的核心能力由 全雷达体系 (Opportunity Radar) 与 交易执行双核体系 (Dual-Core Strategy Engines) 组成，各自解决不同场景的需求：

体系 / 核心概念 解决什么问题 外部调用 Python API 对应文档章节
🌐 全雷达体系
(Opportunity Radar)		 全市场/全池选品与四栏异动扫描
四栏式全域互斥去重归类（量化异动/预警观察/潜在机会/风险提示），计算动态防守线与双距离		 analyze_opportunity_radar()
evaluate_opportunity_radar_item()
OpportunityRadarConfig		 第 1 章 (1.2, 1.3)
🧭 核心 1：右侧趋势突破
(Engine 1 / Trend Breakout)		 交易执行：右侧主升浪做多
抓放量结构突破 + EMA20 回踩确认 + EMA53 移动跟踪		 get_strategy_signal(StrategyEngine.ENGINE1_TREND, df) 第 1 章 (1.1, 1.2)
⚡ 核心 2：左侧均值回归
(Engine 2 / Mean Reversion)		 交易执行：左侧大波段抄底
抓周线布林超跌 + K线底部反转 + 3阶段跟踪止盈 (Stage 1/2/3) + 熊市冷却		 get_mean_reversion_signal()
或 get_strategy_signal(StrategyEngine.ENGINE2_REVERSAL, df)		 第 6 章 (6.1)
🔄 超跌企稳独立引擎
(Oversold & Stabilized，不经 get_strategy_signal 分发)		 周线超跌筑底质量评估与左侧早期埋伏
波动率自适应回撤门禁 + TA-Lib 底部形态矩阵 + 周线筑底质量 0-10 分，输出 OVERSOLD_ALERT / WAITING_DAILY / TRIGGERED 三档		 check_oversold_stabilized()
get_extreme_reversal_signal()		 第 6 章 (6.8)
🌟 双核综合引擎
(Combined Engine)		 双核同时运行 / 实盘仿真回测
左侧 + 右侧信号一起抓，用于全历史实战回测与多策略综合调度		 get_strategy_signal(StrategyEngine.COMBINED, df)
run_strategy_engine_simulation()		 第 1 章 (1.1, 1.4)
🔎 雷达辅助筛选层
(Radar Selectors)		 从雷达结果中提纯目标清单
通用筛选原语 + 超跌族/买点族/观察族/风险族共 20 个纯函数，不重算引擎		 filter_radar_items()
get_high_quality_oversold_stabilized()
get_oversold_watchlist()
get_golden_pullback_second_buys()		 第 1 章 (1.6)
📊 截面板块轮动
(Sector Rotation)		 多标的资产配置与强弱轮动
以沪深300为基准，计算 RS 相对强弱与 4 象限分布 (领涨/复苏/衰退/滞后)		 SectorRotationEngine
run_sector_rotation_backtest()		 第 6 章 (6.4~6.7)
🗽 美股专属量化双核
(US Quantitative System)		 美股自适应超级趋势与截面双动量
宏观 SPY SMA200/10月动量体制判别、KAMA 吊灯超级趋势、截面行业轮动、0-10 分 5 大态机会雷达（支持统一门面 timeframe="D"/"W"）		 run_us_strategy()
compute_us_rotation()
analyze_us_radar()		 第 7 章 (7.1~7.5)
🌏 跨境溢价共振
(Overseas Premium)		 跨境 QDII ETF 溢价风控与套利
盘后时差对齐 (国内T日锚定美股T-1日)，60日比价偏离度 Z-Score 门禁 + 美股周线强趋势共振 + 全池机会雷达		 evaluate_overseas_opportunity_item()
analyze_overseas_radar()
run_overseas_premium_strategy()		 第 8 章 (8.1~8.5)
🛡️ 交易撮合与执行生命周期
(Execution Matcher)		 A 股实盘仿真与未成交追踪
开盘一字涨跌停拦截、停牌检测、滑点佣金仿真、未成交信号生命周期归档与成交率统计		 ExecutionMatcher
compute_execution_summary()
get_a_share_price_limit_ratio()		 第 9 章 (9.1~9.3)
🗓️ 机会生命周期跟踪
(Opportunity Lifecycle)		 纵向时间演变跟踪与滚动回放
雷达标的入池双门禁（质量 Top-N + 看涨形态确认）、5 阶段推进、主动止盈 / 破位双确认出池、逐日进池出池流转日志		 select_trackable_opportunities()
confirm_bullish_formation()
track_opportunity_lifecycle()
track_radar_report()		 第 11 章 (11.1~11.6)
📈 统一行情获取与标准化
(Unified Market Data)		 股票/ETF/指数/美股统一行情拉取
标的类型自动路由、前缀规整自愈（如 000300 自动规整为 sh.000300）、异常自愈重试与标准化全小写 DatetimeIndex OHLCV 数据输出		 get_any_ohlc()
is_likely_index()
normalize_index_symbol()		 第 12 章 (12.1~12.4)

目录索引 (Table of Contents)

  1. 全域机会雷达综合引擎 (Combined Opportunity Radar)
  2. 技术形态扫描与预筛选管道 (pre_screen_and_scan)
  3. 市场状态机与多周期趋势评估
  4. 市场环境与辅助分析工具
  5. 均值回归与板块轮动引擎 (mean_reversion & sector_rotation)
  6. 美股专属量化系统与机会雷达 (us_macro / us_strategy / us_opportunity_radar)
  7. 跨境 QDII ETF 溢价套利与趋势共振引擎 (overseas_premium)
  8. 实盘撮合与信号全生命周期追踪 (execution)
  9. 四大经典战术买点与全生命周期形态识别 (tactical_patterns)
  1. 机会生命周期跟踪与滚动回放 (opportunity_lifecycle)
  1. 统一行情数据获取与标准化接口 (get_any_ohlc)

1. 全域机会雷达综合引擎 (Combined Opportunity Radar)

全域机会雷达综合引擎 (Combined Radar) 采用“交易执行双核 (Dual Cores) + 选品形态雷达 (Pattern Radar) + 截面板块轮动 (Sector Rotation)”分层架构。

它将复杂的形态发现、宏观截面与严谨的量化执行解耦：

  1. 📊 经典形态雷达层 (Pattern Radar)：负责 10+ 经典几何形态（头肩底、双底、杯柄、三角形突破）识别、0-10 综合技术评分与自媒体图文可视化；
  2. ⚡ 左侧均值回归核 (Left-Side Core - Engine 2 / Mean Reversion)：周线布林超跌 + TA-Lib K 线底部形态 + 三阶段跟踪止盈 (Stage 1/2/3) + 熊市止损冷却与假摔快速重入保护；
  3. 🧭 右侧趋势突破核 (Right-Side Core - Engine 1 / Trend Breakout)：右侧放量突破结构 + EMA20 回踩确认 + EMA53 防守跟踪主升浪；
  4. 🌐 截面板块轮动与全天候自适应：四象限相对强度软打分赋能雷达；同时独立提供 Kaufman KAMA 自适应趋势引擎 (Engine 3)。
                  ┌────────────────────────────────────────────────────────────┐
                  │              StrategySignalEvent 统一信号契约              │
                  │  (buy_signal, sell_signal, stop_loss, take_profit, reason) │
                  └─────────────────────────────┬──────────────────────────────┘
                                                │
                          【Combined Opportunity Radar 综合雷达】
                       StrategyEngine.COMBINED / analyze_opportunity_radar
                                                │
         ┌──────────────────────────────────────┴──────────────────────────────────────┐
         ▼                                                                             ▼
【⚡ 左侧均值回归核 (Engine 2 / MR)】                          【🧭 右侧趋势突破核 (Engine 1 / Trend)】
  周线布林超跌 + TA-Lib底部形态 + 三阶段止盈                      右侧放量突破 + EMA20回踩 + EMA53动态跟踪
         ▲                                                                             ▲
         └──────────────────────────────┬──────────────────────────────────────────────┘
                                        │ 选品形态赋能 & 截面轮动加权
              【📊 经典形态雷达 (Pattern Radar) & 🌐 板块轮动四象限 (Sector Rotation)】
                       头肩底 / 双底 / 杯柄 / 三角形 / 0-10综合评分 / 领涨-复苏-衰退-滞后

1.1 统一策略枚举与事件契约

from tradingpatterns import (
    StrategyEngine,                 # 核心策略枚举类 (COMBINED, MEAN_REVERSION, ENGINE1_TREND, ENGINE2_REVERSAL, ENGINE3_KAUFMAN)
    EngineType,                     # StrategyEngine 别名
    get_strategy_signal,            # 顶层统一单策略信号分发器 (E1/E2/E3/MR)
    evaluate_opportunity_radar_item,# 单标的全维度雷达评估
    analyze_opportunity_radar,      # 全池多周期雷达批量扫描 (内嵌板块轮动)
    OpportunityRadarConfig,         # 雷达扫描配置类 (门槛、钝化周期、防追高、技术面 cutoff)
    StrategySignalEvent,            # 统一信号事件基类
    deduce_exit_metadata,           # 标准化平仓元数据与标签推断
    run_strategy_engine_simulation, # 单标的纯量化撮合回测仿真
)

策略引擎枚举 (StrategyEngine)：

  • ENGINE1_TREND / ENGINE1: 右侧趋势突破引擎 (放量突破 + EMA20 回踩 + EMA53 移动跟踪)。
  • ENGINE2_REVERSAL / MEAN_REVERSION: A 股周线均值回归与三阶段跟踪引擎 (周线布林超跌 + TA-Lib K 线底部形态 + 3-Stage 跟踪止盈 + 熊市止损冷却与假摔快速重入)。
  • ENGINE3_KAUFMAN / ENGINE3: Kaufman KAMA 全天候自适应趋势引擎。
  • COMBINED: 全域机会雷达双核综合引擎 (Engine 1 + Engine 2，用于全池雷达与组合回测)。

统一返回对象 (StrategySignalEvent 标准契约)：

支持属性访问（sig.buy_signal）与字典键访问（sig["buy_signal"]）：

字段/属性 类型 说明
buy_signal bool 是否触发次日开盘买入信号。
sell_signal bool 是否触发次日开盘卖出/离场信号。
stop_loss float 建议的量化止损防守线（破位即走；具体保护幅度按策略与周期自适应）。
take_profit float 建议的目标止盈价/关键阻力位（到达考虑减仓止盈）。
signal_tier str | None 信号确定性分级 ("L3" 强信号 | "L2" 中等/接力 | "L1" 预警关注 | None)。
reason str 信号触发的详细原因说明。
state str 策略内部状态机状态 / 体制（如 "RIGHT_CONFIRMED", "TREND_BULL", "TRIGGERED", "COOLDOWN"）。
symbol str 标的代码。
date str 信号产生的 K 线日期 (YYYY-MM-DD)。
details dict 包含底层指标、KAMA 生命线、周线宏观状态与形态元数据的完整字典。

1.2 单标的雷达信号调用

方式一：调用单策略引擎信号接口 (get_strategy_signal)

get_strategy_signal 用于提取具体单一策略引擎在第 T 日收盘后的执行决策：

import tradingpatterns as tp
import kdata

# 抓取日线 OHLCV 数据
df = kdata.get_ohlc("513120", "2024-01-01", "2026-08-19")

# 1. 获取左侧均值回归信号 (Engine 2 / Mean Reversion)
sig_mr = tp.get_strategy_signal(
    tp.StrategyEngine.MEAN_REVERSION, # 或 tp.StrategyEngine.ENGINE2_REVERSAL
    df, 
    symbol="513120"
)

# 2. 获取右侧趋势突破信号 (Engine 1)
sig_trend = tp.get_strategy_signal(
    tp.StrategyEngine.ENGINE1_TREND,
    df,
    symbol="513120"
)

# 3. 获取 Kaufman 自适应趋势信号 (Engine 3)
sig_kaufman = tp.get_strategy_signal(
    tp.StrategyEngine.ENGINE3_KAUFMAN,
    df,
    symbol="513120",
    use_multitimeframe=True
)

if sig_mr.buy_signal:
    print(f"【🔥均值回归买入】({sig_mr.signal_tier}) | 建议止损: {sig_mr.stop_loss:.3f} | 原因: {sig_mr.reason}")

方式二：调用单标的全维度雷达评估 (evaluate_opportunity_radar_item)

一站式计算形态扫描、状态机、多引擎信号、截面板块轮动属性与防追高过滤：

from tradingpatterns import evaluate_opportunity_radar_item

item_res = evaluate_opportunity_radar_item(
    df=df,
    symbol="515880",
    name="通信ETF",
    frequency="weekly",      # "weekly" (周频) 或 "daily" (日频)
    min_amount_ea=None,      # 异动成交额门槛 (亿)，None 时自动取默认
    min_vol_ratio=1.5,       # 放量倍数门槛 (默认 1.5 倍)
    min_pct_change=1.5,      # 涨跌幅门槛 (默认 1.5%)
    weekly_mode="early",     # 周线模式
)

print(f"机会来源: {item_res['primary_opp_source']}")
print(f"状态变迁: {item_res['prev_state_cn']} ━━➔ {item_res['curr_state_cn']}")
print(f"建议防守线: {item_res['stop_loss']}")
print(f"板块轮动象限: {item_res['quadrant_cn']} (分位数: {item_res['rs_percentile']}%, 斜率: {item_res['rs_slope']})")

核心输出字段：

  • has_buy_signal (bool): 是否触发任一核心买点。
  • has_sell_signal (bool): 是否触发离场/移动止损/止盈信号。
  • opp_sources (List[str]): 机会来源组合（包含 "ENGINE2" 左侧均值回归, "ENGINE1" 右侧趋势突破, "ENGINE3" Kaufman 趋势）。
  • primary_opp_source (str): 主导机会来源中文说明。
  • signal_tier: 最高信号级别 ("L3" 强信号 | "L2" 中等/接力 | "L1" 预警关注)。
  • is_opportunity (bool): 是否归入【潜在机会】。
  • is_vol_abnormal (bool): 是否归入【量化异动】。
  • vol_anomaly_type (str): 量化异动微观结构分类枚举。取值：
    • "BREAKOUT_EXPANSION": 突破推进放量（大阳线 + 实体比例高 + 空间 ATR 扩张）。
    • "STOPPING_VOLUME": 底部恐慌承接（超跌区域暴量 + 长下影线/探底大长腿，机构接盘）。
    • "CHURNING_STAGNATION": 高位巨量滞涨（高位暴量但涨幅极小或长上影，努力无结果）。
    • "PANIC_BREAKDOWN": 破位恐慌杀跌（大阴线跌幅深 + 暴量光脚破位）。
    • "VOLUME_DRY_UP": 极致地量变盘（成交量深度缩水达 55% 以上且处于历史低分位，筹码锁仓）。
    • "REGULAR_SURGE": 常规放量（满足基础放量门槛，非极端结构）。
    • "NONE": 正常量能。
  • vol_anomaly_cn (str): 异动微观结构标准纯文本中文标签（如 "突破推进放量", "底部恐慌承接", "高位巨量滞涨", "破位恐慌杀跌", "极致地量变盘"）。
  • vol_zscore (float): 成交量对数标准分（Log-Volume Z-Score，反映相对 20 日历史均量的统计显著度）。
  • vol_percentile (float): 成交量在近 120 日中的历史百分位分位数（0.0 ~ 100.0%）。
  • range_atr_ratio (float): 当日真实波幅相对于前 20 日 ATR 的扩张倍数（$TR / ATR_{20}$）。
  • body_ratio (float): K 线实体高度占全日总振幅的比例（0.0 ~ 1.0）。
  • is_risk (bool): 是否归入【风险提示】。
  • quadrant / quadrant_cn (str): 所属板块轮动四象限（LEADING 领涨区 / RECOVERING 复苏区 / WEAKENING 衰退区 / LAGGING 滞后区）。
  • rs_percentile (float): 相对基准的 60 日历史分位数 (0~100%)。
  • rs_slope (float): 相对基准的 10 日线性回归斜率。
  • oversold_status (str): 超跌企稳独立引擎的真实状态。取值 "NONE" / "OVERSOLD_ALERT" / "WAITING_DAILY" / "TRIGGERED"，以及覆盖态 "WAITING_BEAR_MARKET_DIP" / "WAITING_MARKET_STABILIZATION" / "EXTENDED_WAITING_PULLBACK" / "REJECTED_BY_BEARISH"（三档状态与覆盖态的语义见 6.8 节）。
  • oversold_drawdown (float): 距周线近 52 周最高点的回撤（小数，负值，如 -0.42 表示跌 42%）。
  • oversold_bottom_score (float): 周线筑底质量评分 0.0 ~ 10.0。
  • oversold_tier (str | None): 超跌引擎自身的信号层级（"L1" 超跌预警 / "L2" 企稳观察 / "L3" 右侧确认）。注意：它不参与 signal_tier 的合成，需单独读取。
  • oversold_entry_mode (str): "EARLY_BIRD"（左侧早鸟抢跑通道）/ "STANDARD"。
  • oversold_weekly_signals / oversold_daily_signals (List[str]): 周线 / 执行级别的命中原语（如 "BOTTOM_CONSOLIDATION", "TALIB_HAMMER_PINBAR", "BREAK_EMA20"）。
  • sig_oversold_stabilized (bool): 超跌企稳引擎是否已触发买入（等价 oversold_status == "TRIGGERED"）。

    ⚠️ 勿混淆：sig_oversold / has_oversold_buy_signal 两字段由 Engine 2（周线均值回归） 驱动，语义与上表不同。

1.3 全市场多周期雷达批量扫描 (analyze_opportunity_radar)

analyze_opportunity_radar 是面向标的池（ETF 或股票池）的全域多周期雷达批量扫描入口。它集成了多策略引擎聚合 (Engine 1/2/3)、截面板块轮动计算 (4 象限加权)、经典形态与状态机识别、防追高与时效性钝化过滤 (Staleness Check)，并按照全域四栏互斥去重规则将标的归类到强类型报表对象 OpportunityRadarReport（别名 RadarReport）中。

1. 函数签名与参数说明

def analyze_opportunity_radar(
    etf_pool: Dict[str, Tuple[str, pd.DataFrame]],
    frequency: str = "weekly",
    market: str = "auto",
    min_amount_ea: Optional[float] = None,
    min_vol_ratio: Optional[float] = None,
    min_pct_change: Optional[float] = None,
    weekly_mode: Optional[str] = None,
    market_context_df: Optional[pd.DataFrame] = None,
    include_alerts: bool = True,
    config: Optional[OpportunityRadarConfig] = None,
) -> OpportunityRadarReport:
参数 类型 默认值 说明
etf_pool Dict[str, Tuple[str, pd.DataFrame]] 必填 标的池字典，格式为 {"标的代码": ("标的名称", df), ...}，其中 df 为包含 open, high, low, close, volume 的 K 线 DataFrame。
frequency str "weekly" 扫描频率。"weekly"（周频：以近 5 日为当周、近 100 日为 20 周均额基准）或 "daily"（日频：以当日为窗口、近 20 日为均量基准）。状态机与评分基于日 K 粒度计算，量额窗口随之切换。
market str "auto" 市场模式。"auto"（默认，根据标的代码自适应推断：纯数字如 510050 为 A 股，英文如 SPY 为美股）、"CN"（强制 A 股超跌反转与二买白名单，突破防追高）或 "US"（美股顺势双动量）。
min_amount_ea Optional[float] None 异动成交额门槛（亿元）。为 None 时根据 config/frequency 自动取默认值（周频 2.5 亿 / 日频 0.5 亿）。
min_vol_ratio Optional[float] None 异动放量倍数门槛（实际成交量 / 基准均量）。为 None 时从 config 获取（默认 1.5 倍）。
min_pct_change Optional[float] None 异动涨跌幅绝对值门槛 (%)。为 None 时从 config 获取（默认 1.5%）。
weekly_mode Optional[str] None 周线筛选模式（"early" / "balanced" / "strict"）。为 None 时日频默认为 "early"，周频默认为 "balanced"。
market_context_df Optional[pd.DataFrame] None 市场大盘/基准指数日 K 数据（可选）。若未提供且标的池中包含 510300 / SPY / QQQ，会自动提取作为基准进行大盘环境与截面板块轮动计算。
include_alerts bool True 是否开启四栏输出模式。设为 True 时报告包含预警观察池 alert_list（并自动细分为高质量蓄势与常规观察），元组解包兼容 4 元组与 3 元组。
config Optional[OpportunityRadarConfig] None 雷达配置对象（可选，为 None 时使用全局默认配置 DEFAULT_RADAR_CONFIG）。

2. 雷达配置对象 (OpportunityRadarConfig)

可以通过传入自定义 OpportunityRadarConfig 精细调优雷达的门槛参数：

from tradingpatterns import OpportunityRadarConfig, analyze_opportunity_radar

# 自定义雷达门槛配置
custom_config = OpportunityRadarConfig(
    min_amount_ea_daily=0.8,       # 日频成交额门槛 (0.8亿)
    min_amount_ea_weekly=3.0,      # 周频成交额门槛 (3.0亿)
    min_vol_ratio=2.0,             # 放量倍数门槛 (2.0倍)
    min_pct_change=2.0,            # 涨跌幅门槛 (2.0%)
    stale_breakout_max_bars=3,     # 突破信号最大有效天数 (>3天判定为钝化)
    stale_ema20_atr_dist_max=2.5,  # 偏离 EMA20 最大 ATR 倍数 (>2.5倍判定为发散)
    chasing_ema20_dist_max=0.05,   # 距 EMA20 偏离度上限 (+5% 判定为追高)
    tech_score_cutoff=-5.0,        # 技术评分准入门槛
    anomaly_zscore_threshold=1.8,  # 触发放量统计异常的对数 Z-Score 门槛 (约超 96.4% 分位)
    anomaly_dry_up_zscore=-1.8,    # 触发极致地量的对数 Z-Score 门槛 (约低于 3.6% 分位)
    anomaly_dry_up_ratio=0.45,     # 极致地量与基准均量比率上限 (成交量萎缩 55% 以上)
    anomaly_atr_expansion_min=1.3, # 突破推进时真实波幅扩张倍数门槛 (TR / ATR20 >= 1.3)
)

3. 返回数据结构 (OpportunityRadarReport 与 OpportunityRadarItem)

analyze_opportunity_radar 返回强类型报表对象 OpportunityRadarReport（可简写为 RadarReport），包含完整的列表、分流指标与 DataFrame 导出支持，同时 100% 向后兼容元组解包。

3.1 OpportunityRadarReport 属性与方法
report = analyze_opportunity_radar(etf_pool, frequency="weekly", include_alerts=True)

# 1. 强类型属性访问
print(report.vol_list)           # 一、量化异动 (List[OpportunityRadarItem])
print(report.alert_list)         # 二、预警观察池全量 (List[OpportunityRadarItem])
print(report.hq_alert_list)      # 2.1 🌟 高质量蓄势机会 (非钝化/高分/领涨复苏象限)
print(report.routine_alert_list) # 2.2 ⚠️ 常规跟踪与钝化观察 (钝化/追高/弱势初选)
print(report.opp_list)           # 三、潜在机会池 (L3 确定性策略机会)
print(report.risk_list)          # 四、风险提示池 (破位失效/卖出信号)
print(report.all_items)          # 全池扫描标的清单

# 2. 智能提纯 Top-N 核心先锋机会 (基于复合优先级打分模型)
top_picks = report.get_top_actionable(top_n=3, from_pool="hq_alerts")
for pick in top_picks:
    print(f"🔥 先锋标的: {pick.name}({pick.symbol}) | 动作: {pick.action_advice}")

# 3. 导出为 Pandas DataFrame
df_opps = report.to_df("opportunities") # 导出机会池表格
df_alerts = report.to_df("alerts")      # 导出预警池表格
df_all = report.to_df("all")            # 导出全池扫描总表

# 4. 100% 兼容传统元组解包
vol_list, alert_list, opp_list, risk_list = report
3.2 OpportunityRadarItem 标的条目核心字段

列表中的元素均为强类型 OpportunityRadarItem（别名 RadarItem），同时支持属性访问与字典键访问（item.tech_score 与 item["tech_score"]）：

字段/属性名 类型 说明 适用列表
symbol str 标的代码。 全列表通用
name str 标的中文名称。 全列表通用
frequency str 扫描频率（"weekly" / "daily"）。 全列表通用
tech_score float 0-10 综合技术评分（量价、均线、动量、形态综合得分）。 全列表通用
curr_state str 当前状态机中文名称（如 "右侧确认", "筑底成熟", "超跌企稳" 等；字典访问亦兼容 curr_state_cn）。 全列表通用
prev_state str 前序状态推演中文名称（如 "筑底成熟", "超跌观察" 等；字典访问亦兼容 prev_state_cn）。 全列表通用
vol_ratio float 放量倍数（实际周期成交量 / 基准均量）。 全列表通用
change_pct float 周期涨跌幅（%）。 全列表通用
market str 市场归属（"CN" A股防御与反转哲学 / "US" 美股顺势双动量哲学）。 全列表通用
priority_score float 池内专属优先级评分 (0.0 ~ 10.0)：机会池衡量可操作性 (actionability)、预警池衡量蓄势质量 (quality)、风险池衡量健康程度 (severity，分越低越危险)、异动池衡量异动显著度 (significance)。 全列表通用
grade str 标准化综合评级 ("A" / "B" / "C" / "D")：全池统一方向映射（A 级最优，D 级最弱/最危险）。 全列表通用
grade_dimension str 评级所依托的业务语义维度（"actionability" / "quality" / "severity" / "significance"）。 全列表通用
has_buy_signal bool 是否触发任一核心策略买入信号。 全列表通用
has_sell_signal bool 是否触发任一核心策略卖出/离场信号（由 Engine 1 趋势突破与 Engine 3 Kaufman 合成）。 全列表通用
is_pullback bool 是否属于缩量回踩 EMA20 支撑买点（$-1.5% \le \text{dist_to_ema20} \le +1.5%$ 且量比 $\le 1.25$）。 全列表通用
is_chasing bool 是否属于均线过度发散/连阳形态的追高标的。 全列表通用
action_advice str 详细实操动作建议（约 30~40 字，结合均线乖离、轮动象限与买点生成的交易动作，适合控制台表格、图卡及自媒体文案）。 全列表通用
action_tag str 简明动作标签（10 字以内，如 🟢 首发突破买点, 🌟 回踩企稳买点, ⏳ 趋势在途·等回踩, 👀 领涨蓄势·等突破, ⏳ 弱势磨底·多观望, 🛑 风险破位·坚决避）。 全列表通用
cash_advice str 面向空仓视角的实操指引文案（防追高提示、挂单买入目标价、持股待涨说明）。 全列表通用
ema20_price float 当前 EMA20 价格参考线。 全列表通用
dist_to_ema20 float 距 EMA20 偏离度比例（收盘价 / EMA20 - 1）。 全列表通用
signal_tier str | None 信号确定性分级（"L3" 强信号 / "L2" 企稳突破观察 / "L1" 超跌预警 / None）。 全列表通用
signal_tier_cn str 信号分级中文描述（"右侧/策略确认", "企稳/突破观察", "超跌/候选预警", "无信号"）。 全列表通用
opp_sources List[str] 机会来源策略列表（如 ["ENGINE1"], ["ENGINE2"], ["ENGINE3"]）。 vol_abnormal_list
primary_opp_source str 主导机会来源中文说明（如 "Engine 1 (右侧突破)" / "Engine 2 (周线均值回归)" / "Engine 3 (Kaufman趋势)"）。 vol_abnormal_list
oversold_status str 超跌企稳独立引擎状态（取值与三档语义见 6.8 节；注意 sig_oversold 属于 Engine 2 均值回归，二者不同）。 全列表通用
oversold_drawdown float 距周线近 52 周最高点回撤（小数负值）。 全列表通用
oversold_bottom_score float 周线筑底质量评分 0.0 ~ 10.0。 全列表通用
oversold_tier str | None 超跌引擎自身层级（"L1" / "L2" / "L3" / None），不参与 signal_tier 合成。 全列表通用
oversold_entry_mode str "EARLY_BIRD" 左侧早鸟抢跑 / "STANDARD"。 全列表通用
sig_oversold_stabilized bool 超跌企稳引擎是否触发买入（等价 oversold_status == "TRIGGERED"）。 全列表通用
stop_loss float 建议的量化防守止损价。 vol_abnormal_list
dist_to_support float 距下方支撑位的偏离比例。 全列表通用
dist_to_anchor float 距底部/突破启动锚点的涨幅比例。 全列表通用
quadrant str 板块轮动四象限编码（"LEADING" / "RECOVERING" / "WEAKENING" / "LAGGING" / "UNKNOWN"）。 全列表通用
quadrant_cn str 板块轮动四象限中文标签（"领涨象限" / "改善象限" / "衰退象限" / "落后象限" / "未分类"）。 全列表通用
rs_percentile float 相对基准的 60 日历史相对强弱分位数 (0.0 ~ 100.0%)。 全列表通用
rs_slope float 相对基准的 10 日线性回归斜率。 全列表通用
risk_reason str 风险触发原因（如 "触发卖出信号", "结构失效/破位"）。 risk_list
observation_reason str 观察原因（如 "右侧候选，等待突破确认", "趋势过度延伸，避免追高"）。 vol_abnormal_list / alert_list
is_stale / stale_reason bool / str 信号是否钝化及钝化原因（如突破已超 3 天、ATR 偏离过大等）。 alert_list
vol_anomaly_type str 量价微观异动行为枚举（"BREAKOUT_EXPANSION" 突破推进 / "STOPPING_VOLUME" 底部恐慌承接 / "CHURNING_STAGNATION" 高位巨量滞涨 / "PANIC_BREAKDOWN" 破位杀跌 / "VOLUME_DRY_UP" 极致地量变盘 / "REGULAR_SURGE" 常规放量 / "NONE" 正常量能）。 全列表通用
vol_anomaly_cn str 量价微观异动纯中文定性标签（如 "突破推进放量", "底部恐慌承接", "高位巨量滞涨", "破位恐慌杀跌", "极致地量变盘", "常规放量", "正常量能"，不含 Emoji）。 全列表通用
vol_zscore float 成交量对数 Z-Score（基于 $x_t = \ln(V_t + 1)$，对比前 20 期对数均值与波动标准差计算偏离度，超越 $\pm 1.8$ 具有极强统计显著性）。 全列表通用
vol_percentile float 120 日历史成交量分位数百分比（$0.0% \sim 100.0%$，标准化刻画历史相对量能位置）。 全列表通用
range_atr_ratio float 真实波幅空间扩张倍数（$\text{TR} / \text{ATR}_{20}$，$> 1.3$ 表明突破或异动伴随价格空间有效推进）。 全列表通用
body_ratio float K 线实体占全日振幅比例（$0.0 \sim 1.0$，刻画多空推进纯度与阻力大小）。 全列表通用
3.3 Top-N 核心先锋机会智能提纯 (select_top_actionable_opportunities)

在多达数十只标的的高质量蓄势池或全池中，为帮助下游系统或自媒体读者一键获取最具爆发力、盈亏比最优的 Top-3 核心买入先锋标的，系统提供了复合优先级打分提纯算法：

from tradingpatterns import (
    select_top_actionable_opportunities,
    filter_top_actionable_candidates,  # 别名
)

# 方式一：直接从 OpportunityRadarReport 对象中一键提纯 (推荐)
# from_pool="auto" (默认值) 开启两阶段瀑布流：优先取 opp_list，不足 top_n 从 hq_alerts 补齐
top_3_hq = report.get_top_actionable(top_n=3)

# 方式二：传入任意 OpportunityRadarItem 列表或字典列表进行过滤
top_3 = select_top_actionable_opportunities(
    items=report.hq_alert_list,
    top_n=3,
    min_tech_score=4.5,
    allow_stale=False,
    allow_chasing=False,
)

💡 API 设计说明 (别名说明) filter_top_actionable_candidates 是 select_top_actionable_opportunities 的完全等价别名，两者底层指向同一块逻辑。 之所以导出两个名字，是为了满足下游调用方在不同场景下的语义偏好：

  • 当调用侧重于“排除劣质/破位/钝化标的”时，可以使用 filter_；
  • 当调用侧重于“截取排名前 N 位的高分标的”时，可以使用 select_。请根据自身代码可读性习惯任选其一。

优先级打分模型设计 (Actionable Priority Scoring)：

  1. 硬性排除：自动过滤结构破位 (is_risk)、信号钝化 (is_stale)、追高过热 (is_chasing) 及低于门槛 (tech_score < min_tech_score) 的标的；
  2. 单日/当期动能奖惩 (防追高机制)：
    • A 股：追高重罚——单日涨幅 > 5.0% 扣除 6.0 分（严禁接盘）；追高轻罚——> 3.0% 扣除 3.5 分；温和奖励——0.0% ~ 3.0% 奖励 +1.0 分；超跌机会逆势下跌 > 2.0% 时额外扣除 1.5 分；
    • 美股：> 6.0% 扣除 3.0 分；0.0% ~ 4.0% 奖励 +1.0 分；超跌机会逆势下跌 > 3.0% 时扣除 1.5 分；
  3. 动能象限加权：LEADING (领涨) +2.0 分、RECOVERING (改善) +1.5 分、WEAKENING (衰退) -1.0 分、LAGGING (滞后) -2.0 分；
  4. 买点与层级加权：
    • A 股双核心买点加成：超跌企稳买点（sig_oversold_stabilized == True，即 oversold_status == "TRIGGERED"）或右侧黄金二买 (is_pullback) 享满额 +3.0 分；普通顺势突破克制加 +1.5 分；
    • 美股模式：顺势突破与回踩均享满额加成，且多头排列额外 +2.0 分、相对强度分位 $\ge 80$ 额外 +1.5 分；
    • L2 临界观察 +1.5 分，L1 初选预警 +0.5 分；
  5. 均线偏离安全垫与防追高硬门禁：
    • A 股：$-1.0% \le \text{dist_to_ema20} \le +1.5%$ (支撑位附近) +1.0 分；$\text{dist_to_ema20} > 2.5%$ (过度偏离) 扣除 2.0 分；
    • 美股：$-1.5% \le \text{dist_to_ema20} \le +2.0%$ +1.0 分；$\text{dist_to_ema20} > 4.5%$ 扣除 2.0 分；
    • A 股先锋硬门禁：A 股模式下若非缩量回踩或超跌企稳反转，单日涨幅 > 2.5% 或偏离 EMA20 > 2.5% 的标的一票否决、严禁入选 Top-N 核心买入先锋！
    • 美股趋势门禁：单日涨幅 > 6.5% 或偏离 EMA20 > 5.5% 的标的直接排除。

    ⚠️ 已知差异：该门禁还包含 is_above_sma200 == False 则排除的条件，但通用雷达条目 OpportunityRadarItem 并不携带 is_above_sma200 / is_bull_align / er_val / adx_val 字段，因此这几个字段在通用雷达中恒取默认值（is_above_sma200=True、其余 False / 0.0），对应的加分与排除分支实际不生效。美股 200 日均线多空防线由美股专属机会雷达独立实现（其条目自带 is_above_sma200，见 7.3 节）。

4. 四栏全域互斥去重与排序规则

雷达采用严格的单标的全域唯一归类机制，优先级如下：

  1. 风险提示 (risk_list)：准入标准为**“结构破位/持仓卖出防守”**。若触发核心策略卖出信号或结构破位失效（FAILED、BOTTOM_FAILED，is_risk == True），优先归入风险提示池，防止放量下跌掩盖离场信号。按 tech_score 升序排列（最弱破位标的置顶）。

    ⚠️ 重要边界区分（防守风险 vs 追高风险）：
    右侧过度延伸（RIGHT_EXTENDED，即乖离透支/极致过热）虽然属于“高风险区间”，但其做多大趋势依然完好（in_right_side == True），持仓者应依托移动止盈跟踪利润；它属于针对买方的“追高风险”，因此绝不归入 risk_list（避免误导持仓者恐慌清仓），而是严格分流至 alert_list（预警观察栏） 并标注 observation_reason="趋势过度延伸，避免追高"。

  2. 量化异动 (vol_abnormal_list)：非风险标的中满足放量与涨跌幅门槛的标的（is_vol_abnormal == True）。按异动显著度 priority_score 降序、放量倍数 vol_ratio 降序、涨跌幅绝对值降序排列。
  3. 潜在机会 (opportunity_list)：
    • A 股市场 (market="CN") 实施“双核心白名单机制”：进入机会池需命中 ① 右侧缩量回踩二买（EMA20 附近缩量企稳 is_pullback）或 ② 左侧均值回归买点（Engine 2 周线布林超跌底分型，即 sig_oversold / has_oversold_buy_signal）。若当天出现放量大阳线突破（即使触发 L3），一律安全降级踢入【预警观察池】（2.1 高质量蓄势），贴上 ⏳ 突破确立·等回踩 标签，坚决杜绝任何诱导空仓追高。

      ⚠️ 与 Top-N 阶段的差异（有意为之）：本白名单认的是 Engine 2 均值回归买点；而 Top-N 精选阶段的"防追高硬门禁豁免"认的是 超跌企稳独立引擎买点（sig_oversold_stabilized / oversold_status == "TRIGGERED"，见 6.8 节）。因此一只"超跌企稳已 TRIGGERED、但均值回归未触发"的标的会落在 alert_list 而非 opp_list——这不影响使用：report.all_items 与 alert_list 均携带完整超跌字段，辅助筛选层（见 1.6 节）可正常选取。

    • 美股市场 (market="US") 保持“顺势超级趋势特权”：保留大阳线放量突破直接进机会池、鼓励顺势骑浪（Super Trend）。
    • 按可操作性 priority_score 降序 ➔ 信号分层 (L3) ➔ 策略买点 ➔ 放量倍数降序排列。
  4. 预警观察 (alert_list)：承接 L1/L2 预警、观察态以及钝化标的（包含 A 股大阳线突破确立重点自选标的、CANDIDATE 候选观察、RIGHT_EXTENDED 避免追高预警、技术面偏弱待修复等）。按蓄势质量 priority_score 降序 ➔ L2 优先于 L1 ➔ 放量倍数降序排列。
    • 自动细分为 2.1 🌟 高质量蓄势机会 (hq_alert_list)（包含 A 股突破确立优质自选、高分/强势象限非钝化标的）与 2.2 ⚠️ 常规跟踪与钝化观察 (routine_alert_list)（钝化防追、追高过热、弱势初选）。

5. 完整代码调用示例

from tradingpatterns import analyze_opportunity_radar, OpportunityRadarConfig

# 1. 批量扫描标的池（四栏输出）
vol_list, alert_list, opp_list, risk_list = analyze_opportunity_radar(
    etf_pool={
        "515880": ("通信ETF", df_comm),
        "512880": ("证券ETF", df_sec),
        "513120": ("港股创新药", df_hk),
    },
    frequency="weekly",      # "weekly" (周频) 或 "daily" (日频)
    include_alerts=True,     # 开启四栏模式 (默认开启)
    min_amount_ea=None,      # None 时周频默认 2.5 亿 / 日频默认 0.5 亿
    min_vol_ratio=1.5,
    min_pct_change=1.5,
)

print(f"📊 【量化机会雷达 | 全市场四栏扫描复盘】\n")

# 栏目一：潜在机会池 (L3 确定性策略机会)
print("🎯 【潜在机会池 (L3 策略确认)】")
for item in opp_list:
    print(
        f"• {item['symbol']} {item['name']}: "
        f"状态【{item['curr_state']}】 | 评分: {item['tech_score']:.1f} | "
        f"板块象限: {item['quadrant_cn']} | 动作: {item['action_advice']}"
    )

# 栏目二：预警与蓄势观察池 (L1/L2 观察与超跌企稳)
print("\n👀 【预警观察池 (L1/L2 蓄势/超跌)】")
for item in alert_list:
    obs_info = f" | 观察: {item['observation_reason']}" if item.get("observation_reason") else ""
    stale_info = f" | 钝化: {item['stale_reason']}" if item.get("is_stale") else ""
    print(
        f"• [{item['signal_tier_cn']}] {item['symbol']} {item['name']}: "
        f"状态【{item['curr_state']}】 | 评分: {item['tech_score']:.1f} | 动作: {item['action_advice']}{obs_info}{stale_info}"
    )

# 栏目三：量化异动池 (放量/异动)
print("\n🌊 【量化异动池】")
for item in vol_list:
    print(
        f"• {item['symbol']} {item['name']}: "
        f"放量 {item['vol_ratio']:.2f} 倍 | 涨跌幅 {item['change_pct']:+.2f}% | "
        f"状态【{item['curr_state']}】 | 动作: {item['action_advice']}"
    )

# 栏目四：风险提示池 (破位/卖出)
print("\n⚠️ 【风险预警池】")
for item in risk_list:
    print(
        f"• {item['symbol']} {item['name']}: "
        f"状态【{item['curr_state']}】 | 评分: {item['tech_score']:.1f} | "
        f"风险原因: {item['risk_reason']} | 动作: {item['action_advice']}"
    )

1.4 技术信号层与实盘执行层的核心区别 (get_strategy_signal vs run_strategy_engine_simulation)

在量化交易系统设计中，“技术形态/指标满足触发条件”（Signal）并不等同于“真实交易账户可执行买卖”（Execution）。

tp-quant 提供了两套定位鲜明、相互协同的核心接口：

┌────────────────────────────────────────────────────────────────────────┐
│                   【技术信号层】 get_strategy_signal                   │
│   • 无状态计算 (Stateless) | 依赖数据: 截至目标日的历史 K 线序列       │
│   • 核心关注: "当天技术指标、均线与形态是否符合开仓/平仓触发标准？"   │
│   • 输出产物: 当日信号事件 (buy_signal / sell_signal / 静态止损位)     │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ 驱动并输入
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│               【实盘执行层】 run_strategy_engine_simulation             │
│   • 有状态仿真 (Stateful)  | 依赖数据: 账户资金、真实持仓与历史交易流水 │
│   • 核心关注: "当前账户是否已有持仓？实际成本是多少？浮盈是否激活移动锁利？"│
│   • 输出产物: 仿真持仓状态、实际撮合成交单、3阶段移动止损、历史累计收益│
└────────────────────────────────────────────────────────────────────────┘

1. 核心差异对照矩阵

对比维度 get_strategy_signal (技术信号层) run_strategy_engine_simulation (实盘执行层)
状态机机制 无状态 (Stateless)：单次独立纯函数运算，无外部账户记忆。 有状态 (Stateful)：维护连续运行的资金、持仓成本与成交流水。
持仓排他性 不考虑已有持仓：若行情持续走强，连续多日均会输出 buy_signal = True。 严格排他过滤：若已建仓，后续重复买点会被标记为 SKIPPED_ALREADY_IN_POSITION 跳过。
出场/止损机制 静态规则防守：输出初始锚定止损价（如跌破前低或跌破 EMA53）。 3阶段动态跟踪：根据实际持仓浮盈自动切换 Stage 1 硬止损 $\rightarrow$ Stage 2 保本/KAMA 生命线 $\rightarrow$ Stage 3 EMA10 紧锁利润。
防飞刀与纠错 无历史记忆：无法感知前几日是否刚被止损。 全闭环风控：熊市止损后触发 10~20 根 K 线强制禁买冷却期；止损后 6 根 K 线内大阳线收复触发假摔洗盘快速纠错重入。
主要应用场景 全池机会雷达扫描、盘后自媒体选品初筛、单日技术形态全息诊断。 策略回测验证、实盘账户盯盘、头寸管理与动态止盈止损跟踪。

2. 代码调用与协同示例

import kdata
from tradingpatterns import StrategyEngine, get_strategy_signal, run_strategy_engine_simulation

symbol = "510050"
target_date = "2024-05-20"

# 获取历史数据 (建议预热 300+ 交易日)
df = kdata.get_ohlc(symbol, "2023-01-01", target_date)

# 1. 诊断当天形态信号 (技术信号层)
sig_today = get_strategy_signal(StrategyEngine.COMBINED, df, symbol=symbol)
print(f"当天技术买入信号: {sig_today.buy_signal}, 建议初始止损: {sig_today.stop_loss:.3f}")

# 2. 仿真账户执行与持仓状态 (实盘执行层)
sim_res = run_strategy_engine_simulation(
    engine_type=StrategyEngine.COMBINED,
    df=df,
    symbol=symbol,
    start_date="2023-01-01",
    initial_capital=100000.0,
)

# 查看截至当天的账户真实状态
last_trade = sim_res.trades[-1] if sim_res.trades else None
if last_trade and not last_trade.get("exit_date"):
    print(f"账户状态: 【持仓中】 开仓价: {last_trade['entry_price']:.3f}, 移动止损: {last_trade['stop_loss']:.3f}")
else:
    print(f"账户状态: 【空仓观望】 累计策略收益: {sim_res.total_return_pct:+.2f}%")

1.5 全景回测与实战验证 CLI

包内置了多周期与多策略批量回测命令行工具与 Python 标准调用接口：

# 1. 单标的策略回测 (支持 pattern / sma / combined)
tp backtest -s 510050 --engine combined --start 2024-01-01

# 2. 标的池文件批量快速扫描
tp scan -f pool.yaml --json-simple

对于需要在 Python 代码中执行纯量化仿真回测的开发者，推荐直接调用顶层回测 API：

  • run_strategy_engine_simulation(...): 单标的策略引擎（双核 Combined / 趋势突破 Engine 1 / Kaufman Engine 3）标准撮合回测；
  • run_mean_reversion_simulation(...): 单标的周线均值回归与三阶段跟踪专用撮合回测；
  • run_sector_rotation_backtest(...): 多标的截面板块轮动与 Top-K 动态换仓组合回测。

1.6 雷达辅助筛选层 (Radar Selectors)

设计定位：analyze_opportunity_radar 只负责产出完整结果；所有"挑选/提纯"逻辑下沉到雷达辅助筛选层的一组纯函数。这些函数只读已有条目字段，不重算任何引擎，因此可对同一份 report 反复组合筛选。

所有函数首个参数统一为 source，接受三种形态：OpportunityRadarReport（自动合并各池并去重）、List[OpportunityRadarItem]、List[dict]。返回值一律为 List[OpportunityRadarItem]（未命中返回空列表）。

1. 通用原语

函数 说明
iter_radar_items(source) 归一化输入：Report → 各池合并去重；list → 原样；None → []
filter_radar_items(items, **criteria) 唯一通用筛选实现，见下方参数表
sort_radar_items(items, by=("priority_score","tech_score"), reverse=True) 多键排序，键缺失时回退默认值
take_top_n(items, n) 截断前 N 个
to_symbols(items) 提取代码列表

filter_radar_items 支持的筛选条件：

参数 说明
symbols / markets 代码白名单 / 市场（"CN"、"US"）
oversold_stages 超跌状态白名单（如 ("WAITING_DAILY",)）
tiers signal_tier 白名单（"L1"/"L2"/"L3"）
quadrants 板块轮动象限白名单
sources opp_sources 引擎来源白名单（如 ("ENGINE2",)）
min_tech_score / max_tech_score 技术评分区间
min_vol_ratio 最小放量倍数
min_change_pct / max_change_pct 涨跌幅区间（%）
dist_to_ema20_range EMA20 偏离区间（如 (-0.015, 0.015)）
min_bottom_score / min_drawdown 超跌筑底分下限 / 回撤深度要求（传负数，如 -0.30 表示只保留回撤不浅于 30% 的标的）
entry_modes oversold_entry_mode 白名单（如 ("EARLY_BIRD",)）
min_rs_percentile 相对强度分位下限
exclude_risk / exclude_stale / exclude_chasing 默认全部为 False（通用原语保持宽容，严格口径请用下方领域选择器）
require_buy 仅保留 has_buy_signal == True

2. 领域选择器（按族划分）

超跌族

函数 语义
filter_oversold(items, *, oversold_stages=("OVERSOLD_ALERT","WAITING_DAILY","TRIGGERED"), min_bottom_score=None, min_drawdown=None, entry_modes=None, **kw) 超跌基础筛选
get_high_quality_oversold_stabilized(items, top_n=3, min_bottom_score=4.0, min_drawdown=None, exclude_risk=False) TRIGGERED 优质超跌企稳机会，按 (筑底分, tech_score, 回撤深度) 降序
get_oversold_watchlist(items, top_n=None, min_bottom_score=3.0, min_drawdown=None, exclude_risk=False) WAITING_DAILY 早鸟清单（周线已企稳，只差日线确认）
get_oversold_alerts(items, top_n=None, min_drawdown=None, exclude_risk=False) OVERSOLD_ALERT 最早预警（胜率最低）
get_oversold_early_birds(items, top_n=None, exclude_risk=False) oversold_entry_mode == "EARLY_BIRD" 左侧抢跑

🔎 为什么超跌族默认 exclude_risk=False？ 实测 51 只 A 股 ETF：19 只 WAITING_DAILY 中有 10 只 is_risk=True，risk_reason 全部是"触发卖出信号"——而那是趋势引擎（Engine 1 / Kaufman）的卖出，深跌品种本就位于 EMA53 下方，卖压是结构性必然，与左侧抄底的前提并不矛盾。若默认剔除，会把筑底分最高的几只一并藏掉。超跌引擎本身已内置熊市回撤门禁 / 大盘企稳门禁 / 防追高三重风控。需要严格口径时显式传 exclude_risk=True。 对比：get_golden_pullback_second_buys 与 get_launch_breakouts 属右侧买点，上升趋势中出现卖出信号是真否决，故它们默认 exclude_risk=True。

买点族

函数 语义
get_oversold_early_birds(items, top_n=None) oversold_entry_mode == "EARLY_BIRD" 左侧抢跑
get_golden_pullback_second_buys(items, top_n=None) is_pullback 缩量回踩 EMA20 二买
get_launch_breakouts(items, top_n=None, market=None) L3 + has_buy_signal + 非 stale/chasing 首发突破
get_engine_opportunities(items, sources=("ENGINE1","ENGINE2","ENGINE3"), top_n=None) 按 opp_sources 指定引擎来源
get_actionable_watchlist(items, top_n=None) 潜在机会 + 高质量蓄势合并去重（对齐生命周期入池口径）

观察族

函数 语义
get_high_quality_setups(items, top_n=None, min_tech_score=4.5) L1/L2 蓄势 + 强势象限（LEADING/RECOVERING）+ 非钝化非追高
get_relative_strength_leaders(items, min_rs_percentile=80.0, top_n=None) 截面相对强度领涨
get_volume_surges(items, min_vol_ratio=1.5, top_n=None) 放量异动榜，按 (量比, 涨幅绝对值) 降序

风险族

函数 语义
get_breakdown_risks(items, top_n=None) is_risk 或 has_sell_signal 的结构破位清单
get_overextended_warnings(items, dist_threshold=0.05) is_chasing 或乖离超阈值的追高过热清单
get_stale_signals(items) is_stale 信号钝化清单

量化异动微观结构族

函数 语义
select_breakout_anomalies(items, top_n=None) 突破推进放量 (BREAKOUT_EXPANSION)：带量大阳线 + 创 10 日新高 + 真实波幅显著扩张
select_stopping_volume_candidates(items, top_n=None) 底部恐慌承接 (STOPPING_VOLUME)：超跌深幅回撤位置暴量释放 + 探底长下影 (Selling Climax)
select_churning_risk_items(items, top_n=None) 高位巨量滞涨 (CHURNING_STAGNATION)：高位大发散 + 暴量涨幅极小/长上影 (努力无结果排雷)
select_dry_up_coiling_items(items, top_n=None) 极致地量变盘 (VOLUME_DRY_UP)：对数 Z-score 深度负向 + 成交量极端萎缩 + 筹码沉淀变盘前夜
filter_actionable_anomalies(items, top_n=None) 可操作多头异动池：仅包含突破推进与底部承接，并排除滞涨与破位风险 
from tradingpatterns import analyze_opportunity_radar
from tradingpatterns.radar_selectors import (
    get_high_quality_oversold_stabilized, get_oversold_watchlist,
    get_golden_pullback_second_buys, get_launch_breakouts,
    get_relative_strength_leaders, get_breakdown_risks,
    select_breakout_anomalies, select_stopping_volume_candidates,
    select_churning_risk_items, select_dry_up_coiling_items,
    filter_actionable_anomalies,
)

report = analyze_opportunity_radar(pool, frequency="daily", include_alerts=True)

print([i.symbol for i in get_high_quality_oversold_stabilized(report, top_n=5)])
print([i.symbol for i in get_oversold_watchlist(report)])
print([i.symbol for i in get_golden_pullback_second_buys(report)])
print([i.symbol for i in get_launch_breakouts(report, market="US")])
print([i.symbol for i in get_breakdown_risks(report)])
print([i.symbol for i in select_breakout_anomalies(report)])
print([i.symbol for i in select_churning_risk_items(report)])

1.7 机会雷达战法专题看板体系 (3+1 实战击球与 11 大战法)

全域机会雷达经过引擎计算后，会产出包含海量量化特征的 OpportunityRadarReport。在面对繁杂技术数据（如评分、乖离率、象限、状态机、多空信号、对数 Z-Score 等）时，交易员容易产生**“认知过载”与“难以快速决策”**的痛点。

为此，系统构建了战法专题提纯体系，基于 tradingpatterns.radar_selectors 纯函数层，形成了**“3+1 实战击球决策看板”（精简实操版）与“四大族群 11 大战法看板”（全景诊断版）**，并已在 CLI 控制台终端 和 独立 Web 前端 (/radar) 中完整工程化落地。

┌──────────────────────────────────────────────────────────────────────────────────┐
│              底座：全域机会雷达 OpportunityRadarReport (全量数据源)                  │
└────────────────────────────────────────┬─────────────────────────────────────────┘
                                         │ 纯函数只读提纯 (0 毫秒级开销)
                                         ▼
┌──────────────────────────────────────────────────────────────────────────────────┐
│               【3+1 实战击球决策框架】 (Radar Selectors 3+1 Decision)              │
│                                                                                  │
│  🔥 1. 今日核心先锋 (Top-3) ──► 复合打分 + 瀑布流 + 严惩 A 股盲目追高             │
│  🎯 2. 核心战法击球点       ──► 稳健二买 (右侧低吸) vs 精品抄底 (左侧反转) vs 顺势突破│
│  👀 3. 强势跟踪与自选       ──► 领涨龙头 (RS 截面) + 临界蓄势 (非钝化) + 微观异动   │
│  🛑 4. 风险排雷与避险       ──► 结构破位 + 巨量滞涨 (防出货) + 均线发散 (防追高)    │
└────────────────────────────────────────┬─────────────────────────────────────────┘
                                         │ 业务分发与渲染
                    ┌────────────────────┴────────────────────┐
                    ▼                                         ▼
   【终端一：CLI 控制台终端】                 【终端二：独立量化 Web 控制台 (/radar)】
    • 默认 3+1 实战看板 (compact)             • /api/radar_selectors_scan 结构化输出
    • --full-selectors 展开 11 大战法         • ECharts 5 K 线图 (EMA20/MA60/支撑/买卖点)
    • 支持灵活日期与生命周期按需滚动回放       • 下方 3+1 决策看板点击秒级联动

1. 3+1 实战击球决策框架设计

该框架按照**“先锋决策 ➔ 核心击球 ➔ 强势自选 ➔ 避险排雷”**的实盘推演动线组织信息，拒绝杂乱平铺：

板块名称 实战核心逻辑 底层驱动函数 核心准入条件 / 特征
🔥 1. 今日核心先锋
(Today's Top Picks)		 买入可行性最高决策：复合优先级打分，结合自动瀑布流；A 股模式下对大阳线及过度偏离均线实施重罚与一票否决，唯有真正具备低吸安全垫或确定性突破标的方可入选。 select_top_actionable_opportunities(report, top_n=3) 排除破位、钝化与追高；A 股单日涨幅 > 2.5% 或偏离 EMA20 > 2.5% 直接排除（非回踩/抄底不可入选）。
🎯 2. 核心战法击球点
(Actionable Entry Points)		 立刻可落地的击球动作：
• 🌟 稳健二买：右侧上升趋势中缩量回踩 EMA20 支撑企稳，A 股胜率最高战法；
• 🧊 精品抄底：深跌后周线筑底高分 + 日线底分型确立触发 (TRIGGERED)；
• 🚀 顺势突破：放量突破重要颈线或中枢（美股首发买入，A 股提示确立等回踩）。		 • get_golden_pullback_second_buys
• get_high_quality_oversold_stabilized
• get_launch_breakouts		 • 偏离 EMA20 处于 $[-1.5%, +1.5%]$ 且量比 $\le 1.25$x；
• 筑底评分 $\ge 4.0$ 且状态为 TRIGGERED；
• L3 突破且排除过热与钝化。
👀 3. 强势跟踪与自选
(Strong Watchlist & Setups)		 机构主线抱团与临界变盘储备：
• 🏆 领涨龙头：相对大盘走势极其强劲的抱团核心；
• 💎 临界蓄势：排除钝化与追高的高分蓄势品种，处于变盘前夜；
• 🔬 微观量价异动：突破推进放量 ($Z_{vol} > 1.8$)、极致地量变盘沉淀 ($Z_{vol} < -1.2$) 与底部恐慌承接 (Selling Climax)。		 • get_relative_strength_leaders
• get_high_quality_setups
• select_breakout_anomalies
• select_dry_up_coiling_items
• select_stopping_volume_candidates		 • 截面 RS 分位数 $\ge 75%$ 且位于领涨/复苏象限；
• $L1/L2$ 状态且技术分 $\ge 4.5$，非钝化非追高；
• 微观量价对数 $Z$-Score 结合振幅 ATR 扩张/萎缩定性。
🛑 4. 风险排雷与避险
(Risk Defense & Warnings)		 坚决不接飞刀与保护利润：
• 🛑 结构破位：触发卖出信号或跌破关键防守位，必须减防或离场；
• ⚠️ 巨量滞涨：高位暴量滞涨（努力无结果），警惕主力派发出货；
• ♨️ 均线发散：偏离 EMA20 过远（乖离率 $> 5%$），超温过热严禁追高。		 • get_breakdown_risks
• select_churning_risk_items
• get_overextended_warnings		 • 命中核心卖点或 is_risk == True；
• 高位发散且量比高但涨幅极小或长上影；
• $\text{dist_to_ema20} > 5%$ 且处于连阳过热区间。

2. 四大族群 11 大量化战法全景架构

对于需要更精细化投研分类的场景，系统支持全量展开四大族群 11 大战法清单：

族群分类 战法编号与名称 核心接口函数 核心量化逻辑与特征
🧊 左侧超跌族
(Oversold Family)		 战法 ①：优质超跌企稳 get_high_quality_oversold_stabilized 52 周深跌后，筑底评分 $\ge 4.0$，日线底分型确立触发 TRIGGERED。
战法 ②：超跌早鸟清单 get_oversold_watchlist 周线级别筑底良好，处于 WAITING_DAILY 阶段，等待日线点火确认。
战法 ③：左侧抢跑通道 get_oversold_early_birds 极度深跌后首次止跌企稳的早鸟抢跑标的 (EARLY_BIRD)。
🎯 买点执行族
(Actionable Family)		 战法 ④：黄金第二买点 get_golden_pullback_second_buys 稳健低吸之王：右侧均线上方缩量回踩 EMA20（偏离在 $\pm 1.5%$ 且量比 $\le 1.25$）。
战法 ⑤：顺势首发突破 get_launch_breakouts $L3$ 状态且 has_buy_signal，放量大阳线突破中枢或防守线。
战法 ⑥：核心先锋精选 select_top_actionable_opportunities 融合自动瀑布流，自适应 A 股/美股哲学排名的买入先锋 (Top-3 / Top-5)。
👀 观察蓄势族
(Watch Family)		 战法 ⑦：RS 领涨龙头 get_relative_strength_leaders 截面相对大盘强弱分位数 $\ge 75%$，主线板块领涨。
战法 ⑧：高质量临界蓄势 get_high_quality_setups $L1/L2$ 状态，技术评分 $\ge 4.5$，排除钝化和追高，即将点火。
战法 ⑨：量价微观异动 select_breakout_anomalies
select_stopping_volume_candidates
select_dry_up_coiling_items		 突破放量推进、底部恐慌承接 (Selling Climax)、极致地量沉淀变盘。
⚠️ 风险排雷族
(Risk Family)		 战法 ⑩：巨量滞涨排雷 select_churning_risk_items 暴量但实体极小或长上影，努力无结果，警惕派发。
战法 ⑪：结构破位离场 get_breakdown_risks 跌破动态支撑线或触发策略离场，坚决不接下坠飞刀。

3. 数据源准备与调度流程 (How Data Sources Flow In)

战法专题看板是纯函数只读提纯层，其上游依赖标准化的标的行情与大盘基准：

┌────────────────────────────────────────────────────────────────────────┐
│                        【1. 标的池输入数据准备】                        │
│   pool_data: Dict[str, Tuple[str, pd.DataFrame]]                       │
│   - key: 标的代码 (如 "510300", "SPY")                                 │
│   - value: (标的中文名, OHLCV DataFrame)                                │
│   - DataFrame 要求: 包含 open, high, low, close, volume; 时间升序排列   │
│   - 数据长度: 建议至少 60 根 K 线 (预热 EMA20, MA60, ATR 等指标)         │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        【2. 大盘基准上下文】                            │
│   market_context_df: pd.DataFrame (可选但强烈推荐)                       │
│   - A 股: 沪深300指数 / ETF (510300) 行情                              │
│   - 美股: 标普500 ETF (SPY) 行情                                       │
│   - 作用: 驱动截面相对强弱 (RS 分位数/斜率) 及大盘顺逆势风控            │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                 【3. 全域雷达批量分析 (调度核心入口)】                 │
│   report = analyze_opportunity_radar(                                  │
│       pool=pool_data,                                                  │
│       frequency="daily" | "weekly",                                    │
│       market_context_df=market_context_df,                             │
│       include_alerts=True,                                             │
│   )                                                                    │
│   - 产物: OpportunityRadarReport 强类型报表对象                        │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│             【4. 战法提取与多维分类 (纯函数零开销提纯)】               │
│   直接消费 report 对象，调用 tradingpatterns.radar_selectors 函数:    │
│   - select_top_actionable_opportunities(report, top_n=3)               │
│   - get_golden_pullback_second_buys(report)                            │
│   - get_high_quality_oversold_stabilized(report)                       │
│   - get_launch_breakouts(report)                                       │
│   - get_relative_strength_leaders(report)                              │
│   - get_high_quality_setups(report)                                    │
│   - select_breakout_anomalies(report) / select_dry_up_coiling_items    │
│   - get_breakdown_risks(report) / select_churning_risk_items           │
└────────────────────────────────────────────────────────────────────────┘

4. 下游消费规范与输出数据结构契约 (How Results Are Structured)

所有战法筛选函数均返回 List[OpportunityRadarItem]。当需要将战法分类结果序列化（如提供给 REST API、CLI 工具、LLM Agent 或数据推送管道）时，推荐采用标准字典转换方法 item.to_dict()。

4.1 标准输出数据字典规范
def extract_radar_showcase_payload(report: OpportunityRadarReport) -> dict:
    """提取 3+1 实战决策与战法专题结构化数据包（供任何下游服务消费）"""
    from tradingpatterns.radar_selectors import (
        select_top_actionable_opportunities,
        get_golden_pullback_second_buys,
        get_high_quality_oversold_stabilized,
        get_launch_breakouts,
        get_relative_strength_leaders,
        get_high_quality_setups,
        select_breakout_anomalies,
        select_dry_up_coiling_items,
        select_stopping_volume_candidates,
        get_breakdown_risks,
        select_churning_risk_items,
        get_overextended_warnings,
        get_stale_signals,
    )

    def _to_dicts(items):
        return [item.to_dict() if hasattr(item, "to_dict") else item for item in items]

    return {
        "as_of_date": report.as_of_date,
        "frequency": report.frequency,
        "total_scanned": len(report.all_items),
        "selectors_3plus1": {
            # 1. 🔥 今日核心先锋 (Top-3 击球决策 - 优先级复合模型 & 防追高重罚)
            "top_picks": _to_dicts(select_top_actionable_opportunities(report, top_n=3)),

            # 2. 🎯 核心战法击球点 (右侧低吸 vs 左侧抄底)
            "pullbacks": _to_dicts(get_golden_pullback_second_buys(report, top_n=5)),
            "oversold_triggered": _to_dicts(get_high_quality_oversold_stabilized(report, top_n=5)),
            "breakouts": _to_dicts(get_launch_breakouts(report, top_n=5)),

            # 3. 👀 强势跟踪与自选 (机构主线龙头 & 临界蓄势变盘)
            "rs_leaders": _to_dicts(get_relative_strength_leaders(report, min_rs_percentile=75.0, top_n=5)),
            "hq_setups": _to_dicts(get_high_quality_setups(report, top_n=5)),
            "breakout_anomalies": _to_dicts(select_breakout_anomalies(report, top_n=5)),
            "dry_up_anomalies": _to_dicts(select_dry_up_coiling_items(report, top_n=5)),
            "stopping_anomalies": _to_dicts(select_stopping_volume_candidates(report, top_n=5)),

            # 4. 🛑 风险排雷与避险预警 (坚决不接飞刀 / 严禁盲目追高)
            "breakdowns": _to_dicts(get_breakdown_risks(report, top_n=5)),
            "churning_anomalies": _to_dicts(select_churning_risk_items(report, top_n=5)),
            "overextended": _to_dicts(get_overextended_warnings(report, dist_threshold=0.05)),
            "stale_items": _to_dicts(get_stale_signals(report)),
        },
    }
4.2 四大族群 11 大量化战法全景看板数据包规范与函数用法

当业务需要展示全景量化战法矩阵（例如投研报表导出、看板聚合服务或自动化任务）时，可直接通过 tradingpatterns 顶层导出的纯函数，将 OpportunityRadarReport 归类聚合为四大族群 11 大战法结构化数据包：

from tradingpatterns import (
    analyze_opportunity_radar,
    # 族群一：核心击球
    get_golden_pullback_second_buys,
    get_high_quality_oversold_stabilized,
    get_launch_breakouts,
    get_engine_opportunities,
    # 族群二：超跌博弈
    get_oversold_watchlist,
    get_oversold_alerts,
    get_oversold_early_birds,
    # 族群三：强势跟踪
    get_relative_strength_leaders,
    get_high_quality_setups,
    # 族群四：风险排雷
    get_breakdown_risks,
    get_overextended_warnings,
    get_stale_signals,
)

def extract_full_11_tactics_dashboard_payload(report: OpportunityRadarReport) -> dict:
    """提取四大族群 11 大量化战法全景看板数据包（只读纯函数提纯，零副作用）"""
    def _to_dicts(items):
        return [item.to_dict() if hasattr(item, "to_dict") else item for item in items]

    return {
        "as_of_date": report.as_of_date,
        "market": report.market,
        "tactical_matrix": {
            # 族群一：🎯 核心击球族群 (立刻执行/击球点)
            "actionable_family": {
                "golden_pullback_second_buys": _to_dicts(get_golden_pullback_second_buys(report)),
                "high_quality_oversold_stabilized": _to_dicts(get_high_quality_oversold_stabilized(report)),
                "launch_breakouts": _to_dicts(get_launch_breakouts(report)),
                "engine_opportunities": _to_dicts(get_engine_opportunities(report)),
            },
            # 族群二：🧊 超跌博弈族群 (左侧潜伏/逆向观察)
            "oversold_family": {
                "oversold_watchlist": _to_dicts(get_oversold_watchlist(report)),
                "oversold_alerts": _to_dicts(get_oversold_alerts(report)),
                "oversold_early_birds": _to_dicts(get_oversold_early_birds(report)),
            },
            # 族群三：👀 强势跟踪族群 (主线抱团/蓄势储备)
            "watch_family": {
                "relative_strength_leaders": _to_dicts(get_relative_strength_leaders(report, min_rs_percentile=75.0)),
                "high_quality_setups": _to_dicts(get_high_quality_setups(report)),
            },
            # 族群四：🛑 风险排雷族群 (避险减防/严禁追高)
            "risk_family": {
                "breakdown_risks": _to_dicts(get_breakdown_risks(report)),
                "overextended_warnings": _to_dicts(get_overextended_warnings(report, dist_threshold=0.05)),
                "stale_signals": _to_dicts(get_stale_signals(report)),
            },
        },
    }
4.3 下游消费场景说明
  • CLI 终端展示：直接遍历 selectors_3plus1 各列表，格式化输出对齐表格；
  • HTTP/REST API 接口：将上述字典作为 JSON 直接响应返回，如 Web 服务的 GET /api/radar_selectors_scan；
  • AI Agent / 交易机器人：仅读取 top_picks 与 breakdowns，由 Agent 针对买入先锋评估执行条件，针对破位标的生成防守提示。

3. 技术形态扫描与预筛选管道 (pre_screen_and_scan)

3.1 预筛选与扫描主接口

一体化的预筛选与形态扫描管道 (v2.4)，结合生命周期、趋势环境与量价配合度，对标的进行严格漏斗过滤并生成详尽的 Context Package。

from tradingpatterns import pre_screen_and_scan

# 单标的诊断/扫描
result = pre_screen_and_scan(df, symbol="sh.600519", min_score=6.0)

# 批量扫描
results = pre_screen_and_scan(jobs, min_score=6.0, max_workers=8)

3.2 Context Package 上下文数据包全字段解析

pre_screen_and_scan 返回的数据结构遵循分层契约：

1. 完整扫描数据包 (预筛选通过 pre_screen_passed == True)

{
  "symbol": "sh.600519",
  "name": "贵州茅台",
  "total_score": 8.5,
  "pre_screen_passed": true,
  "rejection_reason": null,
  "pre_screen": {
    "strategy_hint": "趋势跟随",
    "priority_score": 0.88,
    "urgency": "MEDIUM",
    "signal_age_days": 2,
    "stale": false,
    "stop_infeasible": false
  },
  "trend_structure": {
    "ema_alignment": "bullish_aligned",
    "adx": 28.5
  },
  "volume": {
    "vr": 1.1,
    "vr_type": "正常",
    "obv_accumulation": true
  },
  "wyckoff": {
    "phase": "accumulation",
    "event": "spring",
    "bias": "demand"
  },
  "weekly_context": {
    "weekly_trend_direction": "bullish"
  },
  "calculated_constraints": {
    "max_position_pct": 30,
    "min_rrr": 1.2
  }
}

2. 早期硬过滤拦截返回 (早期阻断 pre_screen_passed == False)

当标的在数据长度校验（< 60 根 K 线）、流动性硬门禁（20日均成交额/换手率不足）或价格结构门禁（异常停牌/价格过低）被物理拦截时，系统将提前快速返回轻量字典，避免无效计算：

{
  "symbol": "sh.600519",
  "pre_screen_passed": false,
  "pre_screen_summary": "流动性拦截: 20日日均成交额不足5000万",
  "rejection_reason": "流动性不足"
}
字段路径 说明
pre_screen_passed 是否通过预筛选硬门禁与基础过滤 (bool)。
pre_screen_summary 预筛选诊断摘要或拦截归因描述。
rejection_reason 若被硬过滤拦截，记录具体阻断原因（如 流动性不足、价格结构异常、数据不足 等）；通过时为 null。
total_score 日线预筛选 0~10 排序总分（仅在通过预筛选时生成）。
pre_screen.strategy_hint 建议策略框架（趋势跟随, 底部反转, 区间震荡, 等待突破, 观望）。
pre_screen.stop_infeasible 止损不可行硬标记（价格偏离技术位超过允许的 ATR 上限）。
wyckoff 威科夫供需分析结果 (phase, event, bias, score)。
calculated_constraints 系统预计算的风控约束（建议最大仓位比例、最小盈亏比、最大止损宽容度）。

3.3 威科夫量价供需分析：detect_wyckoff_context

from tradingpatterns import detect_wyckoff_context

wyckoff = detect_wyckoff_context(df)
print(wyckoff["phase"], wyckoff["event"], wyckoff["bias"])

4. 市场状态机与多周期趋势评估

4.1 综合唯一主状态机：detect_side_state

将左侧筑底状态机（BottomTrackingState）与右侧做多状态机（RightSideState）合并为全局唯一的单一主状态，并输出标准化的筑底观察阶段、右侧交易计划与风控防守线：

from tradingpatterns import (
    detect_side_state,
    SideState,
    STATE_LABELS,
    BOTTOM_OBSERVATION_LABELS,
    RIGHT_SIDE_PLAN_LABELS,
    STATE_EMOJIS,
    get_state_label_cn,
    get_bottom_observation_cn,
    get_right_side_plan_cn,
    get_state_emoji,
)

res = detect_side_state(df, weekly_mode="balanced")

print(f"主状态编码: {res['state']}")
print(f"主状态中文: {get_state_label_cn(res['state'])} ({get_state_emoji(res['state'])})")
print(f"筑底观察: {get_bottom_observation_cn(res['bottom_observation'])}")
print(f"右侧计划: {get_right_side_plan_cn(res['right_side_plan'])}")
print(f"刚跨入右侧: {res['entered_right_side']} | 处于右侧趋势: {res['in_right_side']}")

标准中文状态映射表 (STATE_LABELS)：

英文枚举值 (State) 标准中文标签 (STATE_LABELS) 视觉图标 业务语义与交易指导
BASE 底部蓄势 ⚪ 下跌/回撤/底部构筑阶段，尚未形成有效反转
CANDIDATE 右侧候选 🟡 出现止跌回升证据，正等待关键结构突破
RIGHT_CONFIRMED 右侧确认 🟢 突破确认成立（收盘突破前高阻力 + 辅助确认成立，entered_right_side=True）
RIGHT_ACTIVE 右侧延续 🔵 突破后趋势持续有效，守在防守失效线上方（HOLD_AND_TRACK）
RIGHT_EXTENDED 右侧过度延伸 🟠 趋势仍有效但乖离过大，极致过热追高风险（AVOID_CHASING，雷达分流归入 alert_list）
FAILED 结构失效 🔴 候选或已确认结构跌破防守线，结构破坏（STAND_ASIDE）
DECLINING 左侧下跌 ⚪ 处于左侧单边下行通道中，未见止跌迹象
BOTTOM_WATCH 筑底观察 🟡 初步探底，开始跟踪底部锚点
BOTTOM_BUILDING 筑底构建 🟠 在底部箱体内反复震荡夯实底部（Higher Lows 形成中）
BOTTOM_MATURE 筑底成熟 🟠 底部构筑充分（持续超 20 根 K 线），蓄势待发
STARTUP_PREHEAT 启动预热 🟢 均线与 MACD 出现向上拐头共振，准备向右侧突破
BOTTOM_FAILED 筑底失败 🔴 跌破前期底部支撑锚点，底部形态破坏

筑底观察与右侧计划映射表：

  • BOTTOM_OBSERVATION_LABELS：
    • "RIGHT_SIDE_ACTIVE": 已转入右侧，不再跟踪筑底
    • "BOTTOM_READY": 底部结构就绪，等待右侧突破
    • "BOTTOM_TRACKING": 底部观察中
    • "BOTTOM_FAILED": 当前底部结构失效
    • "NO_BOTTOM_SETUP": 暂无有效筑底结构
  • RIGHT_SIDE_PLAN_LABELS：
    • "WAIT_BREAKOUT": 等待结构突破
    • "HOLD_AND_TRACK": 持有并跟踪失效位
    • "AVOID_CHASING": 避免追高，等待回撤
    • "STAND_ASIDE": 观望，等待新结构
    • "NONE": 暂无右侧计划

状态生命周期流转轨迹（Lifecycle Flow）：

【左侧下跌】(DECLINING) 
     │ (触底企稳)
     ▼
【筑底构建】(BOTTOM_BUILDING) ➔ 【筑底成熟】(BOTTOM_MATURE) ➔ 【启动预热】(STARTUP_PREHEAT) / 【右侧候选】(CANDIDATE)
     │ (收盘突破前20日高点阻力位 + 周线共振)
     ▼
【右侧确认】(RIGHT_CONFIRMED, 触发入场信号 entered_right_side=True)
     │ (次日及后续站稳突破位)
     ▼
【右侧延续】(RIGHT_ACTIVE, 跟踪持有 HOLD_AND_TRACK)
     ├── (涨幅过大 / 偏离EMA20过大) ──➔ 【右侧过度延伸】(RIGHT_EXTENDED)
     └── (跌破动态失效防守位) ────────➔ 【结构失效】(FAILED) ──➔ 【底部蓄势】(BASE)

4.2 做多右侧状态机：detect_right_side_state

from tradingpatterns import detect_right_side_state, RightSideState

rs = detect_right_side_state(df, weekly_mode="balanced")
# 输出字典包含: state, entered_right_side, in_right_side, is_tradeable, breakout_level, invalidation_level, confidence_score

4.3 底部结构跟踪状态机：detect_bottom_tracking_state

from tradingpatterns import detect_bottom_tracking_state, BottomTrackingState

bt = detect_bottom_tracking_state(df)
# 输出字典包含: state, in_bottom_tracking, bottom_mature, ready_for_right_side, anchor_low, support_level, resistance_level

4.4 独立周线中期趋势质量评分：evaluate_weekly_trend

独立的中期周线质量评分系统（0~100 分），不参与日线预筛选总分合成：

from tradingpatterns import evaluate_weekly_trend, evaluate_weekly_trends

res = evaluate_weekly_trend(df, symbol="512880")
print(f"周线评分: {res['weekly_trend_score']} | 评级: {res['rating']}")

4.5 终端宽字符排版对齐工具 (wc_len / wc_pad)

用于在开发命令行 CLI、控制台对齐输出包含中文、Emoji 等宽字符的 Markdown 表格与报告：

from tradingpatterns import wc_len, wc_pad

# 中文字符占 2 个显示宽度，英文占 1 个
print(wc_len("右侧确认"))  # 输出 8

# 对齐排版
header = f"{wc_pad('标的代码', 10)} | {wc_pad('标的名称', 12)} | {wc_pad('当前主状态', 14)}"
print(header)

5. 市场环境与辅助分析工具

5.1 市场情绪温度计：sentiment_thermometer

提供 A 股市场整体情绪温度（0~100）的计算、自适应历史分位数归一化、情绪状态分级与 5 大温区操作总方针：

from tradingpatterns import (
    compute_sentiment_snapshot,
    compute_sentiment_series,
    DEFAULT_CONFIG,
    SentimentConfig,
    SENTIMENT_ZONES,
    get_sentiment_zone_desc,
    CORE_BENCHMARK_ETFS,
)

# 1. 单日情绪快照 (推荐使用周频 freq="W" 进行波段择时，日频 freq="D" 进行短线监控)
snapshot = compute_sentiment_snapshot(date="2026-08-19", config=SentimentConfig(freq="W"))
temp = snapshot["temperature"]

# 2. 获取当前温度的标准战术操作建议
zone_title, action_advice, full_desc = get_sentiment_zone_desc(temp)

print(f"情绪温度: {temp:.1f} / 100.0 | 状态: {snapshot['state']} | 趋势: {snapshot['direction']}")
print(f"当前温区: {zone_title}")
print(f"战术总方针: {action_advice}")
print(f"底层因子分位: {snapshot['factors']}")
# 输出示例: {'breadth': 88.0, 'momentum': 94.0, 'turnover': 5.0, 'volatility': 50.0, 'positioning': 96.0}

情绪温区划分与战术指南 (SENTIMENT_ZONES)：

温度区间 状态代码 温区标识 市场特征与战术操作方针
$\le 20.0$ ICE_COLD 🥶 极寒冰点区 (恐慌极值) 【左侧分批布局】市场处于极限非理性杀跌，风险出清彻底。严禁恐慌割肉，可按网格/定投逢低分批吸筹优质核心资产。
$20.0 \sim 40.0$ COLD ❄️ 筑底蓄势区 (左侧探底) 【轻仓防守观察】底部结构酝酿中，主跌浪趋缓但尚未放量。维持2~3成底仓，多看少动，耐心等待右侧突破信号。
$40.0 \sim 60.0$ NEUTRAL ☁️ 中性平衡区 (结构轮动) 【聚焦结构个股】宏观多空相对平衡，指数大概率宽幅震荡。重个股与细分板块轮动，遵循“缩量低吸、放量冲高不追”。
$60.0 \sim 80.0$ HOT 🔥 趋势主升区 (右侧强势) 【顺势持筹待涨】市场处于明确右侧主升浪，增量资金进场。坚定跟随均线趋势，回踩生命线（MA20）视为良性买点。
$\ge 80.0$ OVERHEAT 🌋 极度过热区 (盛极而衰) 最高级别风控预警：【逢高分批兑现】短期情绪严重透支，乖离率过大，均值回归压力剧增。严禁盘中追高，主动分批止盈，破位坚决离场。

核心机制与量化解读要点：

  1. 高温度与极度过热（$\ge 80.0$）是“逆向风控预警”，绝非追高做多信号：
    • 情绪温度计衡量的是全市场的拥挤度与透支程度。实证显示，处于 OVERHEAT 时未来一季度的平均收益极低、胜率不足 46%，面临强烈的均值回归回撤压力。
  2. 大盘缩量时温度为何依然可能走高（量价背离与虚热机制）：
    • 量能因子如实归零：缩量时，turnover（量能因子，权重 20%）单项分会跌至接近 0 分，如实反映增量资金枯竭；
    • 价格因子绝对主导：若全市场普涨（广度 F1 占 35%）、动量向上（动量 F2 占 25%）且持仓均处于近期高位无套牢盘（位置 F5 占 20%），合占 80% 权重的价格因子会合力拉高初始加权分；
    • 二次分位数拉伸：在历史 1 年参照系下，加权分排在前 5% 以内，直接触发 80+ 度的 OVERHEAT 警报；
    • 实战意义：缩量上涨反映的是“筹码锁仓、下方无买盘承接”的脆弱形态（空中楼阁）。系统打出极高温度，正是精确量化出这种“量价背离的极端脆弱性”，提示必须启动防守减仓。
  3. 温度方向（direction）语义消歧：
    • 低位 warming（$\le 40$ 度）：【良性企稳 / 冰点回暖】。恐慌出清后的右侧高胜率进场点。
    • 中位 warming（$40 \sim 80$ 度）：【动量升温 / 趋势延续】。
    • 高位 warming（$\ge 80$ 度）：【加速发烧 / 冲顶透支】。如同人体体温升至 40.5℃，属于极度危险的危险脉冲，切忌误读为“行情转好继续追高”。

4. 周频与日频温度计实战选型与平滑参数指南 (freq & smooth_span)

针对实战中不同维度的择时需求（如大波段定投抄底 vs 短线突发催化脉冲追踪），必须根据周期尺度与滤波平滑参数进行针对性配置：

应用场景 推荐周期 (freq) 平滑参数 (smooth_span) 战术定位与核心价值 适用时机与实战案例
大周期定乾坤
(中长线底顶/定投)		 周频 W 默认 2 过滤日线级所有高频杂波与假突破。
直接反映周线级别宏观流动性与筹码沉淀结构。		 熊市大底探底：如 2024 年 89 月漫长阴跌磨底期间，周线温度连续数周被压制在 2030°C 极限蓄势区，出现显著底背离，是指数大波段建仓的核心定性锚。
短线趋势顺势跟踪
(持仓防守/防追高)		 日频 D 推荐 3 ~ 5 兼顾趋势平滑性与抗噪能力。
过滤单日上影线或偶发脉冲，保持均线与温度方向的连续性。		 右侧波段持筹：适合右侧主升浪中的动态持仓观察与回踩生命线（MA20）判定，防止频繁假信号干扰交易节奏。
突发脉冲与拐点探测
(重大政策/突变预警)		 日频 D 强制设为 1
(关闭滤波)		 零滞后纯单日原始加权脉冲。
彻底消除 EWMA 历史权重滞后，捕捉由强外部催化导致的单日跳空跃迁。		 历史级突变捕捉：面对类似 2024-09-19（降息异动）与 2024-09-24（国新办史诗级政策落地）等突发事件，平滑温度会被前序阴跌拖累；而 smooth=1 时单日温度可瞬间跳涨超 +30°C，第一时间触发点火警报。

常用核心基准标的池 (CORE_BENCHMARK_ETFS)：

包含 A 股主流宽基与大行业 ETF 代码字典（"510300": "沪深300ETF", "510500": "中证500ETF", "512100": "中证1000ETF", "159915": "创业板ETF", "512880": "证券ETF", "512800": "银行ETF", "518880": "黄金ETF", "513100": "纳指ETF"）。

5.2 动态支撑阻力计算：calculate_support_resistance

from tradingpatterns import calculate_support_resistance

sr_df = calculate_support_resistance(df, window=3)
current_support = sr_df["support"].dropna().iloc[-1]

5.3 组合风险平权与相关性去重

from tradingpatterns import filter_correlated_assets, volatility_adjusted_position_sizing

# 1. 过滤高相关性同质化标的 (相关系数 > 0.8)
kept_symbols = filter_correlated_assets(returns_df, scores_dict, threshold=0.80)

# 2. 基于 ATR 倒数的风险平权资金分配 (Risk Parity)
weights = volatility_adjusted_position_sizing(atr_dict, total_capital=100000.0)

6. 均值回归与板块轮动引擎 (mean_reversion & sector_rotation)

该模块针对 A 股高波动、易超跌反弹与板块快速轮动的特征，提供 A 股周线均值回归与三阶段跟踪引擎 与 截面相对强度四象限板块轮动引擎。

6.1 A 股周线均值回归与三阶段跟踪 (get_mean_reversion_signal)

专门针对 A 股市场设计的周线大级别均值回归策略（Engine 2 核心）。采用“周线定大方向环境，日线形态/动量抓精准买点，三阶段移动止盈让利润奔跑”的设计：

from tradingpatterns import (
    get_mean_reversion_signal,
    MeanReversionSignal,
    BOTTOM_PATTERNS
)

# 计算日线收盘后的均值回归信号 (供次日开盘执行)
sig = get_mean_reversion_signal(
    df_daily=df,
    symbol="510050",
    is_holding=False,             # 是否处于持仓状态
    entry_price=0.0,              # 若持仓，传入成本价
    holding_stage=1,              # 若持仓，传入当前跟踪阶段 (1, 2, 3)
    holding_weeks=0,              # 若持仓，传入已持仓周数
    current_stop_loss=0.0,        # 当前动态止损价
    trade_history=[]              # 传入历史交易记录用于单边熊市止损冷却判断
)

if sig.buy_signal:
    print(f"触发均值回归买入: 止损价={sig.stop_loss:.3f}, 原因={sig.reason}")
elif sig.sell_signal:
    print(f"触发平仓离场: 原因={sig.reason}")

核心机制与三阶段动态跟踪止盈：

  1. 周线超跌门禁：周线触及布林下轨 (BBANDS 20, 2.0)、周线 RSI(14) $\le 38$、周线 CCI(14) $\le -90$ 多重共振。
  2. 日线精准触发：
    • 组合 A: TA-Lib 底部 K 线反转形态加权分 $\ge 0.8$ 且日 RSI $< 48$；
    • 组合 B: 日 RSI $< 35$ 拐头回升且 KD 低位金叉；
    • 组合 C: 资金流向 MFI $< 25$ 回升且收实体真阳线；
    • 周线 MACD 底背离（额外提供强信号加权）。
  3. 三阶段跟踪止盈 (3-Stage Trailing Stop)：
    • Stage 1 (回归等待期)：建仓后等待价格向周线中轨 (SMA20) 回归。执行近 3 周最低点 $\times 0.985$ 与日线 ATR 止损；若超 16 周未回归中轨触发时间止损。
    • Stage 2 (回归确认期)：价格有效突破周线中轨后，自动升级至 Stage 2，切换为 Weekly EMA10 动态跟踪止盈。
    • Stage 3 (趋势延续期)：价格突破周线布林上轨后，自动升级至 Stage 3，切换为 Weekly EMA20 动态跟踪止盈，全程护航大牛浪。
  4. 风控保护机制：
    • 单边熊市止损冷却 (Bear Market Cooldown)：在价格低于 EMA53 的弱势格局下，若发生止损，触发 10 根 K 线（连续止损为 20 根）冷却期，禁止在同一深跌浪中频繁抄底，除非价格创出新低（$< 0.97 \times \text{前次止损价}$）或收复 EMA53。
    • 假摔快速重入 (Shakeout Re-entry)：若止损后 6 根 K 线内快速以实体阳线收复 EMA20，判定为主力诱空假摔，触发快速纠错重入。
  5. 状态出口：WAITING_WEEKLY_OVERSOLD（周线超跌等待）/ WAITING_DAILY_TRIGGER（日线等待触发）/ TRIGGERED_BUY（已触发买入）/ HOLDING_STAGE_N（持仓第 N 阶段）/ COOLDOWN（熊市冷却中）/ NO_DATA / NO_WEEKLY_DATA。

    ⚠️ 边界提醒：上述状态名与超跌企稳独立引擎的 OVERSOLD_ALERT / WAITING_DAILY / TRIGGERED 形似而不同，不可互相匹配。关于"信号延迟特性、早鸟通道、防追高硬限、中间态提前布局"，均属于超跌企稳引擎的行为，请见 6.8 超跌企稳独立引擎。

6.2 TA-Lib 底部与顶部反转形态扫描 (scan_talib_patterns / BOTTOM_PATTERNS)

内置 11 种经典 TA-Lib 底部反转形态与 7 种顶部形态的向量化扫描与置信度权重评分：

from tradingpatterns import scan_talib_patterns, BOTTOM_PATTERNS

# 方式一：传入 OHLC numpy 数组 (float64) 进行高速形态扫描
bottom_hits, bottom_weight, top_severe, top_warning = scan_talib_patterns(
    open_p=df_daily["open"].to_numpy(dtype=float),
    high_p=df_daily["high"].to_numpy(dtype=float),
    low_p=df_daily["low"].to_numpy(dtype=float),
    close_p=df_daily["close"].to_numpy(dtype=float)
)

# 方式二：直接传入包含 open/high/low/close 列的 DataFrame
# bottom_hits, bottom_weight, top_severe, top_warning = scan_talib_patterns(df_daily)

print("命中底部形态:", bottom_hits)       # 如 ['CDLMORNINGSTAR', 'CDLENGULFING_BULL']
print("综合底部形态得分:", bottom_weight) # 权重加权分
print("命中严重顶部形态:", top_severe)
print("命中预警顶部形态:", top_warning)
  • 形态权重表 (BOTTOM_PATTERNS)：包含晨星 (CDLMORNINGSTAR: 1.5)、看涨吞没 (CDLENGULFING_BULL: 1.5)、三白兵 (CDL3WHITESOLDIERS: 1.5)、看涨弃婴 (CDLABANDONEDBABY_BULL: 1.2)、十字晨星 (CDLMORNINGDOJISTAR: 1.2)、锤头线 (CDLHAMMER: 1.0)、刺透形态 (CDLPIERCING: 1.0)、倒锤头线 (CDLINVERTEDHAMMER: 0.8)、看涨孕线 (CDLHARAMI_BULL: 0.8)、蜻蜓十字 (CDLDRAGONFLYDOJI: 0.8)、看涨踢脚 (CDLKICKING_BULL: 1.0)。

6.3 均值回归事件驱动回测 (run_mean_reversion_simulation)

from tradingpatterns import run_mean_reversion_simulation

res = run_mean_reversion_simulation(
    df=df_daily,
    symbol="510050",
    name="上证50ETF",
    initial_capital=100000.0,
    start_date="2024-01-01",
    min_window=40
)

print(f"累计收益率: {res.total_return_pct:.2f}%")
print(f"最大回撤: {res.max_drawdown_pct:.2f}%")
print(f"胜率: {res.win_rate_pct:.2f}% | 盈亏比: {res.profit_loss_ratio:.2f}")

6.4 全池截面轮动评估与纯趋势研判 (evaluate_universe)

SectorRotationEngine 的核心截面评级计算器。如果仅用于日常盯盘、自媒体复盘、板块热点研判而不进行自动化交易与回测，只需传入全池标的截至当天的历史 K 线数据，即可一次性计算出所有标的当前所属的轮动四象限、相对大盘强度 (RS) 历史分位数以及 10 日动能斜率。

import kdata
from tradingpatterns import SectorRotationEngine

# 1. 准备待观察的板块/ETF 列表与对标基准 (默认 510300 沪深300ETF)
symbols = ["515880", "512800", "512690", "588000", "516160"]
names = {"515880": "通信", "512800": "银行", "512690": "酒", "588000": "科创50", "516160": "新能源"}
bench_sym = "510300"

# 2. 抓取近期 OHLCV 数据 (建议包含最近 >=60 根 K 线用于计算分位数与斜率)
dfs = {s: kdata.get_ohlc(s, "2025-01-01", "2026-08-22") for s in symbols}
bench_df = kdata.get_ohlc(bench_sym, "2025-01-01", "2026-08-22")

# 3. 初始化轮动引擎并计算最新截面
engine = SectorRotationEngine(
    symbols=symbols,
    names=names,
    benchmark_symbol=bench_sym
)

# current_date_idx 指定目标评估日在 DataFrame 中的索引 (最新一天取 len-1)
metrics = engine.evaluate_universe(
    universe_dfs=dfs,
    benchmark_df=bench_df,
    current_date_idx=len(bench_df) - 1,
    prev_quadrants={}          # 用于迟滞防抖 (单点截面快照可置空)
)

# 4. 打印板块趋势与动能分布
for m in metrics:
    print(f"[{m.quadrant.value:<10}] {m.symbol} {m.name:<6} | "
          f"相对强度分位数: {m.rs_percentile:>5.1f}% | "
          f"10日动能斜率: {m.rs_slope:>+7.4f} | "
          f"综合评分: {m.composite_score:.1f}")

6.5 四象限坐标体系与动能研判逻辑

板块轮动模型构建在 “相对强弱 (RS Percentile) - 动能方向 (RS Slope)” 二维坐标系上，用于定性识别资金在不同行业间的宏观转移规律：

                    RS 斜率向上 (资金持续流入 / 走强)
                                   ▲
                                   │
           【🌱 潜伏复苏区】        │      【🚀 强势领涨区】
             (RECOVERING)          │        (LEADING)
        • RS 分位 < 30%            │   • RS 分位 >= 30%
        • 斜率 > 0 (左侧拐头向上)   │   • 斜率 > 0 (顺势主升浪)
                                   │
 ──────────────────────────────────┼──────────────────────────────────► RS 相对强度历史分位数
                                   │                                    (基准线 30% 区分强弱)
           【❄️ 弱势持续区】        │      【🍂 高位衰退区】
             (LAGGING)             │        (WEAKENING)
        • RS 分位 < 30%            │   • RS 分位 >= 30%
        • 斜率 <= 0 (持续阴跌)     │   • 斜率 <= 0 (高位动能衰竭)
                                   │
                    RS 斜率向下 (资金持续抽离 / 走弱)

纯趋势研判实操准则：

  1. 🚀 寻找主线主升浪 (LEADING)：处于领跑区，相对大盘走强且动能加速，代表当前全市场最确定的强势主线。
  2. 🌱 捕捉低位反转潜伏 (RECOVERING)：处于超跌复苏区，虽然过去 60 天表现弱于大盘，但 10 日回归斜率已向上拐头，通常对应主力左侧建仓的超跌修复期。
  3. 🍂 识别高位出货风险 (WEAKENING)：虽然过去强势（RS 高位），但动能斜率已掉头向下，表明资金开始分歧流出，警惕补跌风险。
  4. ❄️ 规避弱势下行深坑 (LAGGING)：低位且动能继续下行，资金持续抽离，坚决规避。

6.6 截面状态指标 (SectorMetric / RotationQuadrant / QUADRANT_META)

evaluate_universe 返回的 List[SectorMetric] 包含完整的量化截面指标与标准化象限元数据：

from tradingpatterns import (
    SectorMetric,
    RotationQuadrant,
    QUADRANT_META,
    get_quadrant_meta,
)

# 获取任一象限的标准元数据
meta = get_quadrant_meta(RotationQuadrant.LEADING)
print(meta["title"])  # 输出: 🔥 领涨区 (LEADING)
print(meta["desc"])   # 输出: 强势上涨，强者恒强，建议持仓或顺势加仓

四象限标准元数据与操作建议 (QUADRANT_META)：

象限枚举 (RotationQuadrant) 象限名称 标识 业务语义与实战建议
LEADING 领涨区 🔥 强势上涨，强者恒强，建议持仓或顺势加仓
RECOVERING 复苏区 🌱 低位拐头向上，动能正在积聚，建议关注或潜伏
WEAKENING 衰退区 ⚠️ 高位动能衰竭，相对走弱，建议减仓或防守
LAGGING 滞后区 ❄️ 弱势下行通道，未见企稳，建议规避

SectorMetric 核心字段：

  • quadrant (Enum: RotationQuadrant): 标的当前所属的轮动四象限（LEADING, RECOVERING, WEAKENING, LAGGING）。
  • rs_value / rs_smooth: 标的相对基准的 20 日收益比率及经 EMA(5) 平滑后的相对强度序列。
  • rs_percentile: 相对强度 (RS) 在过去 60 个交易日内的历史分位数排名（100% 代表当前处于 60 日最强极点，0% 为最弱极点）。
  • rs_slope: RS 近 10 日的线性回归斜率（talib.LINEARREG_SLOPE）。大于 0 代表动能正在走强向上。
  • composite_score: 0~10 的软加权综合打分（包含象限基础加权分与均值回归底背离加分）。
  • reversion_signal: 若当天同时触发了日周双级别均值回归买点，携带对应的 MeanReversionSignal 信号事件。

6.7 截面组合历史回测 (run_sector_rotation_backtest)

将上述横截面评估能力放入时间轴，自动撮合多标的换仓，生成宏观资产组合的回测报告。

from tradingpatterns import run_sector_rotation_backtest

portfolio_res = run_sector_rotation_backtest(
    universe_dfs=universe_dfs,
    benchmark_df=bench_df,
    symbols=symbols,
    names=names,
    benchmark_symbol="510300",
    start_date="2024-01-01",
    initial_capital=1000000.0,
    max_positions=4,           # 动态组合最大同时持仓数 (Top K)
    min_window=60              # 历史指标预热期
)

# 打印宏观绩效
print("组合累计收益率:", portfolio_res["total_return_pct"])
print("组合最大回撤:", portfolio_res["max_drawdown_pct"])
print("调仓明细:", portfolio_res["trades"]) # 返回详尽的买卖时间线

6.8 超跌企稳独立引擎 (Oversold & Stabilized)

🔑 与 Engine 2 的关系：本引擎是独立于执行双核的左侧引擎。核心函数为 check_oversold_stabilized（底层检测）与 get_extreme_reversal_signal（策略信号包装）。 它不经 get_strategy_signal 分发 —— get_strategy_signal(StrategyEngine.ENGINE2_REVERSAL) 路由到的是周线均值回归（见 6.1 节）。因此 ENGINE2_REVERSAL / "engine2" / "oversold" / "reversal" 这些 key 取不到本引擎的状态，必须直接调用 get_extreme_reversal_signal。

1. 三档状态出口（真值语义）

状态 含义 可否买入
OVERSOLD_ALERT 周线超跌条件成立，但尚未企稳（L1） 否（仅预警）
WAITING_DAILY 周线已完成企稳确认，等待日线精确触发（L2） 否（观察，可提前布局）
TRIGGERED 右侧确认完成，买入信号成立（L3） 是
NONE 未满足超跌条件 否

2. 状态覆盖态（风控降级，均不可买入）

get_extreme_reversal_signal 会在原始 status 之上覆盖出：WAITING_BEAR_MARKET_DIP（标的自身上方 EMA53 且回撤未达 -25%，拒绝左侧抄底）、WAITING_MARKET_STABILIZATION（大盘跌破 EMA20 × 0.985）、EXTENDED_WAITING_PULLBACK（距 EMA20 > 12% 或距结构低点 > 18%，防追高）、REJECTED_BY_BEARISH（日线看跌拒绝形态）、NO_DATA（K 线不足）。

3. 超跌门槛（L1 判定）

  • 默认：-coef × annual_vol，ETF coef = 0.8、个股 coef = 1.0；区间夹紧——ETF $[-35%, -12%]$、个股 $[-50%, -20%]$。
  • 固定标的池覆盖：按标的分档覆盖——高弹性科技/半导体/医药 ETF -30%、红利/价值 ETF -15%、宽基指数 -22%。
  • 替代通路：周线 BIAS20 ≤ $-12%$(ETF)/$-20%$(个股) 且 周线 RSI 最低 ≤ 35。
  • 硬约束：须位于周线 EMA60 下方（5% 容差）。

4. 信号延迟特性与中间态预警（纯信号观察者指南）

  • 超跌企稳属于左侧偏确认型信号，从价格见底到最终 buy_signal=True（TRIGGERED），典型延迟 2~3 周（10~20 个交易日），距底部涨幅约 5%15%。早鸟通道（oversold_entry_mode == "EARLY_BIRD"：强反转形态或底背离 + 放量真阳线）可把延迟缩短至约 1 周（68 个交易日），距底部涨幅约 3%~8%。
  • 防追高硬限：信号触发时价格距近期低点涨幅不得超过 $\max(10%, \min(18%, 0.5 \times annual_vol))$，超出则阻断（当日放量 $\ge 1.8\times$ MA20 可豁免）。
  • 提前布局建议：若不希望等待 TRIGGERED，可关注中间态 WAITING_DAILY（周线已完成超跌企稳确认）——它比最终买入信号早出现 1~5 个交易日。

5. 在机会雷达中的取值方式

雷达以旁路方式单独调用一次 get_extreme_reversal_signal，把本引擎结果挂到每个标的上，对应字段为 oversold_status / oversold_drawdown / oversold_bottom_score / oversold_tier / oversold_entry_mode / sig_oversold_stabilized / oversold_weekly_signals / oversold_daily_signals（见 1.3 节的返回字段表）。

from tradingpatterns import analyze_opportunity_radar
from tradingpatterns.radar_selectors import (
    get_oversold_watchlist,                 # WAITING_DAILY：早鸟，比 TRIGGERED 早一步
    get_high_quality_oversold_stabilized,   # TRIGGERED：优质超跌企稳机会
    get_oversold_alerts,                    # OVERSOLD_ALERT：最早、胜率最低
)

report = analyze_opportunity_radar(pool, frequency="daily", include_alerts=True)

for it in get_oversold_watchlist(report, min_bottom_score=3.0):
    print(it.symbol, it.oversold_status, f"{it.oversold_drawdown:.1%}",
          f"筑底分={it.oversold_bottom_score:.1f}", it.oversold_tier, it.curr_state)

⚠️ 修正说明：早期版本文档曾写"雷达 alert_list 中该中间态为 signal_tier="L1""。实际上超跌引擎自身的层级是 oversold_tier（WAITING_DAILY 对应 "L2"），它不参与 signal_tier（该字段由均值回归/趋势突破/Kaufman 三引擎取最高层级合成）。中间态可通过 oversold_status="WAITING_DAILY" + curr_state="超跌观察" 可靠识别。

7. 美股专属量化系统与机会雷达 (US ETF Quantitative System & Radar)

为了适配美股市场的长牛强趋势（High Efficiency Ratio）、T+0 交易机制、行业动量效应与宏观利率敏感性，系统提供了独立于 A 股体系的美股专属量化层。

                          【SPY 宏观绝对动量与体制判别 (us_macro)】
                            (SMA200 / 10月绝对动量 / 建议总仓位)
                                              │
                     ┌────────────────────────┴────────────────────────┐
                     ▼                                                 ▼
        【自适应超级趋势策略 (us_strategy)】               【美股机会雷达 5 大状态机 (us_opportunity_radar)】
         - KAMA 自适应均线 + Donchian 通道突破              - SUPER_TREND / MOMENTUM_LEADER
         - EMA20 / SMA50 缩量回踩优质低吸                    - PULLBACK_BUY / DEFENSIVE_HOLD / LAGGING
         - 动态 Chandelier ATR 吊灯止损                     - 0-10 分多维加权技术评分

7.1 宏观绝对动量与体制判别 (us_macro)

from tradingpatterns import (
    USMarketRegime,
    USMacroSnapshot,
    compute_us_macro_series,
    get_latest_us_macro_snapshot,
)

# 1. 计算 SPY 宏观体制时间序列
macro_df = compute_us_macro_series(spy_df, cash_df=shy_df)

# 2. 获取最新宏观快照
snapshot: USMacroSnapshot = get_latest_us_macro_snapshot(spy_df, cash_df=shy_df)

print("市场体制:", snapshot.regime.value)               # RISK_ON / RISK_OFF / VOL_PANIC
print("站上200日均线:", snapshot.is_above_sma200)      # True / False
print("10月绝对动量:", snapshot.momentum_10m)          # float
print("宏观安全得分 (0-10):", snapshot.risk_score)     # 0.0 ~ 10.0
print("建议股票总仓位:", snapshot.suggested_equity_ratio) # 0.0 ~ 1.0 (例如 0.2 或 1.0)

7.2 自适应超级趋势与截面双动量策略 (us_strategy)

from tradingpatterns import (
    calculate_kama,
    calculate_er,
    run_us_super_trend_strategy,
    compute_us_rotation_metrics,
    USTrendBacktestResult,
    USRotationMetric,
    USRotationQuadrant,
)

# 1. Kaufman 自适应均线与效率比 (ER) 计算
er_series = calculate_er(df["close"], period=10)
kama_series = calculate_kama(df["close"], timeperiod=10)

# 2. 单标的美股超级趋势策略回测 (内嵌宏观风控与动态吊灯止损)
result: USTrendBacktestResult = run_us_super_trend_strategy(
    df=qqq_df,
    symbol="QQQ",
    macro_series=macro_df,
    initial_capital=100000.0,
    # 可选显式参数配置 (USTrendParams 杜绝硬编码魔法数字，可配置 enable_rs_filter 相对强度过滤)
    # params=USTrendParams(donchian_period=20, trailing_atr_mult=3.0, cooldown_bars_tier1=8, enable_rs_filter=False)
)

print(f"累计收益: {result.total_return_pct:+.2f}% | 年化CAGR: {result.cagr:+.2f}%")
print(f"夏普比率: {result.sharpe_ratio:.2f} | 最大回撤: {result.max_drawdown_pct:.2f}%")
print(f"胜率: {result.win_rate:.1f}% | 盈亏比: {result.profit_factor:.2f}")

# 3. 截面双动量与行业相对强度 (RS) 轮动评估
rotation_metrics = compute_us_rotation_metrics(
    target_dfs={"XLK": xlk_df, "XLE": xle_df, "SMH": smh_df},
    benchmark_df=spy_df
)
for sym, metric in rotation_metrics.items():
    print(f"{sym}: 象限={metric.quadrant.value}, 复合动量={metric.composite_momentum:.3f}, RS百分位={metric.rs_percentile:.1f}%")

7.3 美股截面双动量机会雷达 (us_opportunity_radar)

美股机会雷达是顶层的**“全池选品与板块强弱体检引擎”**，与底层的“双核买卖执行引擎”协同分工：

  • 双核策略 (Dual-Core) 解决微观买卖点执行：哪一天该挂单建仓、加减仓、止盈或止损；
  • 机会雷达 (Opportunity Radar) 解决宏观与中观选品：每天盘后全自动扫描全美股池，识别当前资金主线、哪类资产处于领头羊强势象限、谁出现黄金低吸回踩。

核心原理：“双动量 (Dual Momentum)”模型：

  1. 绝对动量 (Absolute Momentum / 宏观守门员)：以 SPY 200 日线与 10 个月动量过滤牛熊大势。若大盘处于 RISK_OFF 破位或 VOL_PANIC 恐慌踩踏，系统压低股票 ETF 评级并激活防守资产提示；
  2. 截面相对动量 (Cross-Sectional Relative Momentum)：计算各行业相对 SPY 的相对强度（$RS = P_{\text{ETF}} / P_{\text{SPY}}$），在四象限（领头羊 Leading、衰退区 Weakening、滞后区 Lagging、修复区 Recovering）中定位资金流向；
  3. 0-10 分多维加权评分体系：
    • 趋势强度 (4.0 分)：均线多头排列 + KAMA 效率比 ER + ADX(14)；
    • 相对动量 (3.0 分)：相对 SPY 的 RS 象限与全池复合动量百分位；
    • 回踩结构 (2.0 分)：EMA20/SMA50 支撑位缩量企稳与反转形态；
    • 宏观安全 (1.0 分)：大盘体制与波动率健康度；
  4. 5 大美股专属雷达机会状态机：
    • SUPER_TREND：超级主升浪狂飙；
    • MOMENTUM_LEADER：全市场领跑领头羊 ETF；
    • PULLBACK_BUY：强势趋势下缩量回踩 EMA20 优质低吸点；
    • DEFENSIVE_HOLD：大盘震荡时的债券/黄金独立避险状态；
    • LAGGING：走弱跑输大盘，提示观望。
from tradingpatterns import (
    USRadarState,
    USRadarItem,
    USRadarSummary,
    evaluate_us_opportunity_item,
    analyze_us_opportunity_radar,
)

# 1. 单标的雷达打分与状态评估
item: USRadarItem = evaluate_us_opportunity_item(
    symbol="NVDA",
    df=nvda_df,
    benchmark_df=spy_df,
    name="NVIDIA Corp",
    rank_percentile=95.0
)
print("雷达状态:", item.radar_state.value)       # SUPER_TREND / MOMENTUM_LEADER / PULLBACK_BUY / DEFENSIVE_HOLD / LAGGING
print("综合得分:", item.composite_score)        # 0.0 ~ 10.0 (趋势40% + 动量30% + 回踩20% + 宏观10%)
print("关键支撑位:", item.key_support)          # float
print("操作建议:", item.action_suggestion)     # 专家行动指南

# 2. 全池批量机会雷达分析
summary: USRadarSummary = analyze_us_opportunity_radar(
    target_dfs=target_dfs,
    benchmark_df=spy_df,
    cash_df=shy_df
)
print(f"扫描标的数: {summary.total_scanned}")
print("超级主升标的:", [x.symbol for x in summary.super_trend_items])
print("动量领跑标的:", [x.symbol for x in summary.momentum_leaders])
print("优质回踩低吸:", [x.symbol for x in summary.pullback_buys])
print("避险防守标的:", [x.symbol for x in summary.defensive_holds])

7.4 多周期统一门面入口 (run_us_strategy / compute_us_rotation / analyze_us_radar)

系统提供了支持日线 ('D') 与周线 ('W') 自动调度的统一顶层门面 API，内置自适应降采样 (auto_resample=True 时自动将日线转为 'W-FRI' 周线)：

from tradingpatterns import (
    run_us_strategy,
    compute_us_rotation,
    analyze_us_radar,
    run_us_weekly_super_trend_strategy,
    compute_us_weekly_rotation_metrics,
    analyze_us_weekly_opportunity_radar,
    USWeeklyTrendSignalType,
    USWeeklyRotationQuadrant,
    USWeeklyTrendTrade,
    USWeeklyTrendBacktestResult,
    USWeeklyRotationMetric,
)

# 1. 统一入口：运行美股趋势策略 (支持日频 'D' 或周频 'W'，内置自动重采样)
res_daily: USTrendBacktestResult = run_us_strategy(
    df=qqq_df,
    symbol="QQQ",
    macro_series=macro_df,
    initial_capital=100000.0,
    timeframe="D",
)

res_weekly: USWeeklyTrendBacktestResult = run_us_strategy(
    df=qqq_df,
    symbol="QQQ",
    macro_series=macro_df,
    initial_capital=100000.0,
    timeframe="W",
    auto_resample=True,
)

print(f"周线策略累计收益: {res_weekly.total_return_pct:+.2f}% | 夏普: {res_weekly.sharpe_ratio:.2f}")

# 2. 统一入口：计算截面行业双动量与相对强度 (支持 'D' / 'W')
rotation_daily = compute_us_rotation(
    target_dfs={"XLK": xlk_df, "XLE": xle_df, "SMH": smh_df},
    benchmark_df=spy_df,
    timeframe="D",
)

rotation_weekly = compute_us_rotation(
    target_dfs={"XLK": xlk_df, "XLE": xle_df, "SMH": smh_df},
    benchmark_df=spy_df,
    cash_df=shy_df,
    timeframe="W",
    auto_resample=True,
)

# 3. 统一入口：运行全池机会雷达批量扫描 (支持 'D' / 'W')
weekly_radar_summary = analyze_us_radar(
    target_dfs=target_dfs_dict,
    benchmark_df=spy_df,
    cash_df=shy_df,
    timeframe="W",
    auto_resample=True,
)
print(f"周线机会雷达扫描完成: 共 {weekly_radar_summary.total_scanned} 标的")

7.5 美股专属大类资产均值回归引擎 (us_mean_reversion)

专为美股 ETF 设计的左侧大波段均值回归策略（Engine 2），与右侧超级趋势（Engine 1）构成双核互补体系。

核心特征与设计原则：

  1. 大类资产超跌分级：宽基指数（SPY/QQQ/IWM 等）触及 $\text{BBANDS}(20, 2.0)$ 下轨或 $\text{RSI}(14) \le 35$；科技高贝塔（XLK/SMH/SOXX/XBI 等）强制双重深度确认 $\text{BBANDS}(20, 2.2)$ 且 $\text{RSI}(14) \le 30$；防守固收/商品（TLT/GLD/XLU 等）触及 $\text{BBANDS}(20, 1.8)$ 或 $\text{RSI}(14) \le 40$。
  2. 严格前向因果与 As-of 对齐：周线指标基于上一周已完整闭合的周 K 线计算并 shift(1) 前向对齐，周中未闭合周不进入计算，杜绝未来数据泄露与 .bfill()。
  3. Next-Open 开盘撮合：收盘判定信号，次日以开盘价挂单撮合入场与离场，支持跳空防穿仓保护。
  4. 三阶段阶梯出场：
    • Stage 1（回归期）：守初始硬止损，反弹触及周线中轨（SMA20）强制**平半仓（50%）**锁定确定性利润，并将剩余仓位止损平移抬升至保本价（Breakeven Stop）；
    • Stage 2（动量期）：有效突破中轨后，切换至日线 EMA10 动态单调递增跟踪止盈；
    • Stage 3（趋势期）：突破周线布林上轨后，升级为 EMA20/KAMA 趋势骑浪跟踪；
    • 时间止损：Stage 1 潜伏期超过 40 个交易日（约 8 周）仍未回归中轨，强制 Next-Open 平仓。
  5. 宏观与连亏风控：大盘处于 VOL_PANIC（极度恐慌）时，股票类 ETF 强制禁开均值回归（防守类 TLT/GLD 豁免）；单次止损冷却 10 日，连续亏损 $\ge 2$ 次强制冷却 20 日。
from tradingpatterns import (
    USAssetTier,
    USMeanReversionStage,
    USMeanReversionSignal,
    USMeanReversionTrade,
    USMeanReversionBacktestResult,
    generate_us_mean_reversion_signals,
    evaluate_us_mean_reversion_backtest,
    compute_us_macro_series,
)

# 1. 准备行情与宏观序列
macro_series = compute_us_macro_series(spy_df)

# 2. 生成均值回归信号与 Next-Open 撮合记录
signals, trades = generate_us_mean_reversion_signals(
    df=tlt_df,
    symbol="TLT",
    asset_tier=USAssetTier.DEFENSIVE_BOND,
    macro_series=macro_series,
    min_score_threshold=6.0,
)

# 3. 统计回测量化绩效
result: USMeanReversionBacktestResult = evaluate_us_mean_reversion_backtest(
    symbol="TLT",
    trades=trades,
    initial_capital=100000.0,
)

print(f"标的: {result.symbol} | 交易次数: {result.total_trades} | 胜率: {result.win_rate:.1f}%")
print(f"累计收益: {result.total_return_pct:+.2f}% | 盈亏比: {result.profit_factor:.2f} | 最大回撤: {result.max_drawdown_pct:.2f}%")

7.6 美股全景回测与雷达扫描 CLI

支持通过包自带的 CLI 命令行工具或 Python API 对美股全池或自定义标的进行批量回测与最新雷达扫描：

# 全池或多标的批量策略回测
tp backtest -s SPY,QQQ,SMH,XLK,XLE,GLD --engine combined --start 2024-01-01

# 标的池 YAML 文件批量快速扫描
tp scan -f us_pool.yaml --json-simple

8. 跨境 QDII ETF 溢价套利与趋势共振引擎 (overseas_premium)

跨境 QDII ETF 溢价双核共振引擎 (Overseas Premium Engine) 专为国内挂牌的海外指数/行业 ETF（如标普500 ETF、纳指100 ETF、纳指科技 ETF、标普油气 ETF、日经225 ETF等）设计。

它解决了跨境 ETF 常见的两大核心痛点：

  1. 防范高位溢价泡沫接盘：美股走牛或国内情绪过热时，国内 QDII ETF 溢价率经常飙升至 10%~20%。引擎通过**“盘后相对比价偏离度 (Z-Score)”**进行硬性阻断，并在溢价泡沫破裂时提前止盈；
  2. 美股超级趋势与周线强共振：仅在美股底层资产（SPY/QQQ/XOP/EWJ）确认周线及日线多头强趋势、且国内溢价健康时才触发买入；同时在极端恐慌错杀（折价率极深）时触发左侧套利。
                      【国内 QDII ETF 行情 + 美股底层资产行情】
                                         │
                                         ▼
                           【align_cn_us_series 盘后对齐】
                           (国内 T 日 锚定 美股 T-1 日收盘)
                                         │
                                         ▼
                       【calculate_premium_zscore 溢价偏离度】
                        (60日滚动比价偏离度 Z-Score 计算)
                                         │
                   ┌─────────────────────┴─────────────────────┐
                   ▼                                           ▼
       【底层美股趋势与动能判定】                       【溢价风控门禁与极值判别】
   • KAMA 上行 + Donchian 通道突破              • 正常安全区: Z < 1.0 (允许买入)
   • EMA20 强势回踩企稳 (Pullback)              • 追高阻断区: Z >= 1.0 (阻断开仓)
   • 周线 EMA20 多头强趋势共振                   • 泡沫风险区: Z > 2.5 (止盈预警)
                   │                                           │
                   └─────────────────────┬─────────────────────┘
                                         │
                                         ▼
          【evaluate_overseas_opportunity_item / analyze_overseas_radar】
      输出：TREND_BUY (趋势共振买点) / DISCOUNT_BUY (折价套利买点) /
            BLOCKED (高溢价阻断) / PREMIUM_BUBBLE_SELL (泡沫风险卖点) / WATCH (观望)

8.1 底层资产映射与盘后时差对齐

from tradingpatterns import (
    OVERSEAS_UNDERLYING_MAP,
    get_underlying_for_symbol,
    align_cn_us_series,
)

# 1. 查询国内跨境 ETF 对应的底层海外代码
us_symbol = get_underlying_for_symbol("513100")  # 返回 "QQQ"
us_symbol_oil = get_underlying_for_symbol("159518")  # 返回 "XOP"

# 2. 盘后离线交易日时差严格对齐 (国内 T 日白盘收盘价锚定美股 T-1 日收盘价)
cn_aligned, us_aligned = align_cn_us_series(cn_df, us_df)

8.2 60日相对比价偏离度计算 (calculate_premium_zscore)

无需获取实时汇率或 IOPV，算法通过滚动统计比价的比值来规避长期汇率漂移：

$$Ratio_t = \frac{Close_{CN, t}}{Close_{US, t-1}}$$ $$Z_t = \frac{Ratio_t - Mean_{60}}{\max(Std_{60}, 1e-6)}$$

from tradingpatterns import calculate_premium_zscore

# 计算 60 日相对比价、滚动均值及偏离度 Z-Score
ratio_arr, mean_arr, zscore_arr = calculate_premium_zscore(
    cn_close=cn_df["close"].to_numpy(),
    us_close_aligned=us_aligned["close"].to_numpy(),
    window=60
)
print("最新溢价偏离度 Z-Score:", zscore_arr[-1])

8.3 单标的实时机会与信号评估 (evaluate_overseas_opportunity_item / get_overseas_premium_signal)

用于每日收盘后对单个跨境 ETF 进行实时机会发现与风控决策（例如次日是否开仓、是否被高溢价阻断、是否需要止盈止损）：

from tradingpatterns import evaluate_overseas_opportunity_item, compute_us_macro_series

# 1. 计算宏观背景序列 (以 SPY 为基准)
macro_df = compute_us_macro_series(spy_df)

# 2. 评估单标的最新机会与决策
item = evaluate_overseas_opportunity_item(
    cn_df=cn_df,                        # 国内 ETF 日线 (如 513100)
    us_df=qqq_df,                       # 对应底层美股日线 (如 QQQ)
    symbol="513100",
    name="纳指ETF",
    macro_series=macro_df,
    max_buy_zscore=1.0,                 # 溢价门禁 (Z-Score < 1.0 允许买入)
    bubble_sell_zscore=2.5,             # 泡沫止盈阈值 (Z-Score > 2.5)
    discount_buy_zscore=-2.5,           # 极端折价套利阈值 (Z-Score < -2.5)
    require_weekly_bull=True,           # 开启周线多头强趋势门禁
    is_holding=False,                   # 当前是否持仓
)

if item:
    print(f"标的: {item.name}({item.symbol}) -> 底层: {item.underlying_symbol}")
    print(f"最新收盘: 国内 {item.close_cn} | 底层美股 {item.close_us}")
    print(f"溢价偏离 Z-Score: {item.zscore:+.2f} (溢价安全={item.is_premium_safe}, 泡沫风险={item.is_bubble_risk})")
    print(f"美股动能: 突破={item.is_us_breakout}, 回踩={item.is_us_pullback}, 周线多头={item.is_weekly_bull}")
    print(f"执行行动: 【{item.action}】 (买入信号={item.buy_signal}, 卖出信号={item.sell_signal})")
    print(f"建议防守止损位: {item.stop_loss:.3f}")
    print(f"决策原因: {item.reason}")

决策行动分类 (item.action)：

  • BUY: 触发买点！底层美股趋势突破/回踩确认且溢价健康（TREND_BUY），或国内极端恐慌错杀折价（DISCOUNT_BUY）。
  • BLOCKED: 高溢价风控阻断！ 底层美股虽然走牛，但国内 ETF 溢价偏离度过高（Z-Score >= 1.0），坚决禁止追高。
  • SELL: 触发离场！包含高溢价泡沫破裂防范（PREMIUM_BUBBLE_SELL）、底层美股破位吊灯移动止损（US_TRAILING_STOP）或宏观极速恐慌（US_MACRO_RISK_OFF）。
  • WATCH: 观望蓄势或处于无买点震荡区间。
  • HOLD: 若传入 is_holding=True 且未触发卖点，处于正常持仓保护状态。

8.4 跨境全池机会雷达批量扫描 (analyze_overseas_radar / OverseasRadarSummary)

一键对全市场所有跨境 QDII ETF 进行批量扫描与分类归档，可直接作为每日跨境机会复盘看板与自动化监控工具：

from tradingpatterns import analyze_overseas_radar, compute_us_macro_series

# 准备国内标的池字典与海外底层资产字典
# cn_pool: {"513100": cn_df1, "159518": cn_df2, "513880": cn_df3, ...}
# us_pool: {"QQQ": qqq_df, "XOP": xop_df, "EWJ": ewj_df, "SPY": spy_df}

macro_df = compute_us_macro_series(us_pool["SPY"])

# 批量扫描跨境全池机会雷达
radar: OverseasRadarSummary = analyze_overseas_radar(
    cn_dfs=cn_pool,
    us_dfs=us_pool,
    macro_series=macro_df,
    names={"513100": "纳指ETF", "159518": "油气ETF", "513880": "日经225ETF"},
    max_buy_zscore=1.0,
    bubble_sell_zscore=2.5,
    discount_buy_zscore=-2.5,
)

print(f"📊 【跨境 QDII ETF 机会雷达 | 日报】(共扫描 {radar.total_scanned} 只标的)\n")

print("🔥 【核心买入机会 (趋势共振 / 折价套利)】")
for opp in radar.opportunities:
    print(f"• [{opp.signal_type.value}] {opp.name}({opp.symbol}): Z-Score={opp.zscore:+.2f} | 建议防守位: {opp.stop_loss:.3f} | 原因: {opp.reason}")

print("\n🚫 【美股走强但高溢价阻断 (严禁追高)】")
for blk in radar.blocked_items:
    print(f"• {blk.name}({blk.symbol}): Z-Score={blk.zscore:+.2f} (偏离过大) | 底层美股: {blk.underlying_symbol}")

print("\n⚠️ 【高溢价泡沫风险预警】")
for risk in radar.bubble_risks:
    print(f"• {risk.name}({risk.symbol}): Z-Score={risk.zscore:+.2f} (高位滞涨/泡沫破裂风险)")

print("\n👀 【跟踪观察池】")
for w in radar.watches:
    print(f"• {w.name}({w.symbol}): Z-Score={w.zscore:+.2f} | 美股突破={w.is_us_breakout}")

8.5 双核共振策略回测与绩效寻优 (run_overseas_premium_strategy)

对特定标的或全池进行事件驱动历史回测，检验趋势共振与溢价风控的综合实战收益：

from tradingpatterns import (
    OverseasSignalType,
    OverseasTrade,
    OverseasBacktestResult,
    run_overseas_premium_strategy,
    compute_us_macro_series,
)

# 1. 计算美股大盘宏观状态 (以 SPY 为基准)
macro_df = compute_us_macro_series(spy_df)

# 2. 运行单标的跨境 ETF 溢价双核共振策略回测
result: OverseasBacktestResult = run_overseas_premium_strategy(
    cn_df=cn_df,                        # 国内 ETF 日线行情 (如 513100)
    us_df=qqq_df,                       # 对应底层海外日线行情 (如 QQQ)
    symbol="513100",
    underlying_symbol="QQQ",
    macro_series=macro_df,
    initial_capital=100000.0,
    max_buy_zscore=1.0,                 # 买入溢价上限 (Z-Score < 1.0)
    bubble_sell_zscore=2.5,             # 溢价泡沫防范卖出阈值 (Z-Score > 2.5)
    discount_buy_zscore=-2.5,           # 极端折价错杀套利买入阈值 (Z-Score < -2.5)
    require_weekly_bull=True            # 启用底层周线强趋势过滤
)

print(f"累计收益: {result.total_return_pct:+.2f}% | 年化CAGR: {result.cagr:+.2f}%")
print(f"夏普比率: {result.sharpe_ratio:.2f} | 最大回撤: {result.max_drawdown_pct:.2f}%")
print(f"胜率: {result.win_rate:.1f}% | 盈亏比: {result.profit_factor:.2f}")
print(f"成功阻断高溢价接盘次数: {result.blocked_high_premium_buys} 次")

# 3. 遍历交易明细
for trade in result.trades:
    print(f"买入: {trade.entry_date} ({trade.entry_price:.3f}, Z={trade.entry_zscore:+.2f}) -> "
          f"卖出: {trade.exit_date} ({trade.exit_price:.3f}, Z={trade.exit_zscore:+.2f}) | "
          f"收益: {trade.return_pct:+.2f}% | 原因: {trade.exit_reason}")

9. 实盘撮合与信号全生命周期追踪 (execution)

实盘撮合与执行模块遵循“策略信号触发 (Alpha Firing)”与“交易所物理执行约束 (Execution Constraints)”严格解耦的设计原则。

策略引擎只根据量化形态与技术面输出纯粹的买卖信号，撮合层则负责在 T+1 开盘时判定信号的物理可行性（一字涨停/跌停拦截、停牌检测、滑点/费率损耗仿真、已有持仓去重），并精确记录所有未成交信号及其物理归因。

                          ┌────────────────────────┐
                          │   策略引擎输出纯买卖信号   │
                          │ (StrategySignalEvent)  │
                          └───────────┬────────────┘
                                      │
                                      ▼
                      【ExecutionMatcher 撮合仿真器】
             (次日开盘物理约束校验：一字涨跌停 / 停牌 / 滑点手续费)
                                      │
                 ┌────────────────────┴────────────────────┐
                 ▼                                         ▼
         【✅ 成功撮合成交】                        【❌ 物理阻断 / 未成交归档】
       (成交价 = 开盘价 ± 滑点)                  (LIMIT_UP_LOCKED, SUSPENDED...)
                 │                                         │
                 └────────────────────┬────────────────────┘
                                      │
                                      ▼
                        【compute_execution_summary】
                    (全生命周期执行汇总与成交率统计报表)

9.1 交易所物理约束与涨跌停比例 (get_a_share_price_limit_ratio / ExecutionStatus)

系统内置了各板块交易规则的涨跌停比例自适应解析函数 get_a_share_price_limit_ratio：

from tradingpatterns import get_a_share_price_limit_ratio, ExecutionStatus

# 板块涨跌幅上限自动识别
limit_main = get_a_share_price_limit_ratio("600519")      # 主板 10% (0.10)
limit_cyb = get_a_share_price_limit_ratio("300750")       # 创业板 20% (0.20)
limit_kcb = get_a_share_price_limit_ratio("688981")       # 科创板 20% (0.20)
limit_bj = get_a_share_price_limit_ratio("832000")        # 北交所 30% (0.30)
limit_st = get_a_share_price_limit_ratio("600000", "ST浦发") # ST 股票 5% (0.05)
limit_us = get_a_share_price_limit_ratio("AAPL")          # 美股无涨跌停限制 (1.00)

执行状态枚举 (ExecutionStatus)：

  • FILLED: 正常撮合成交（按次日开盘价 + 滑点成交）。
  • LIMIT_UP_LOCKED: 次日开盘一字涨停封死，买入挂单无法撮合。
  • LIMIT_DOWN_LOCKED: 次日开盘一字跌停封死，卖出挂单无法撮合。
  • SUSPENDED: 标的次日停牌或无成交量。
  • SKIPPED_ALREADY_IN_POSITION: 已处于持仓状态，跳过重复开仓买点。
  • INSUFFICIENT_LIQUIDITY: 流动性不足。
  • EXPIRED: 信号超时失效。

9.2 次日开盘撮合可行性仿真 (ExecutionMatcher)

from tradingpatterns import ExecutionMatcher, UnfilledSignal

matcher = ExecutionMatcher(
    slippage_rate=0.0005,      # 单边滑点率 (默认万 5)
    fee_rate=0.0002,           # 佣金/经手费费率 (默认万 2)
    strict_limit_check=True    # 启用严格涨跌停与停牌物理拦截
)

# 1. 评估次日买入信号撮合可行性
can_buy, buy_price, unfilled_buy = matcher.check_buy_feasibility(
    symbol="510050",
    signal_date="2026-08-20",
    engine="ENGINE2_REVERSAL",
    signal_close_price=2.850,
    next_open=2.855,
    next_high=2.870,
    next_low=2.845,
    next_close=2.860,
    next_volume=1500000.0,
    name="上证50ETF"
)

if can_buy:
    print(f"买入成功撮合，实际成交价 (含滑点): {buy_price:.3f}")
else:
    print(f"买入未能成交: [{unfilled_buy.status.value}] {unfilled_buy.reason}")

# 2. 评估次日卖出信号撮合可行性
can_sell, sell_price, unfilled_sell = matcher.check_sell_feasibility(
    symbol="510050",
    signal_date="2026-08-25",
    engine="ENGINE2_REVERSAL",
    signal_close_price=2.950,
    next_open=2.945,
    next_high=2.960,
    next_low=2.940,
    next_close=2.955,
    next_volume=1200000.0,
    name="上证50ETF"
)

9.3 未成交信号追踪与生命周期汇总 (UnfilledSignal / compute_execution_summary)

from tradingpatterns import compute_execution_summary

# 模拟成交历史与未成交拦截记录
executed_trades = [
    {"entry_date": "2026-08-01", "exit_date": "2026-08-15", "symbol": "510050", "return_pct": 5.2}
]
unfilled_records = [unfilled_buy.to_dict()] if unfilled_buy else []

# 生成信号全生命周期统计分析报告
summary = compute_execution_summary(
    trades=executed_trades,
    unfilled_signals=unfilled_records
)

print(f"总触发信号数: {summary['total_signals']}")
print(f"实际成交笔数: {summary['filled_trades']}")
print(f"综合撮合成交率: {summary['fill_rate_pct']}%")
print(f"未成交物理归因分布: {summary['reason_stats']}")

10. 四大经典战术买点与全生命周期形态识别 (tactical_patterns)

该模块将经典的量化形态识别标准化为从 跌透 $\to$ 筑底 $\to$ 点火 $\to$ 主升浪 全生命周期的四大战术买点，并彻底打通雷达准入与策略引擎的分级赋权：

战术买点类型 阶段定位 量化核心特征 止损逻辑 建议仓位
🧱 底部反转
(BOTTOM_REVERSAL)		 恐慌末期
左侧抄底		 超跌筑底打分 $\ge 3.0$ 或形态旁路触发，当日收出止跌反转 K 线（实体阳线或下影线 $\ge 40%$） 近 3 日最低点 $\times 0.99$ 50% 试探底仓
✨ 均线启动
(MOVING_AVERAGE_STARTUP)		 筑底完成
初动先行		 EMA10 与 EMA20 粘合度 $\le 1.5%$ 且 EMA20 拐头向上，价格站上 EMA20，量比 $0.95 \sim 2.0$ 启动平台近 5 日低点与 EMA20 $\times 0.985$ 较大者 30% 观察底仓
🚀 放量突破
(VOLUME_BREAKOUT)		 箱体突破
主升点火		 突破 Donchian 20 前高，实体涨幅 $\ge 2.0%$，上影线 $\le 35%$，成交量比 $\ge 1.45$ 爆发 突破大阳线实体中轴预警，跌破大阳线最低点止损 30% 突破防踏空
🎯 缩量回踩
(PULLBACK_LOW_ABSORB)		 趋势确认
黄金二买		 顺势站上 EMA53 生命线，回抽 EMA20 支撑区间 ($[-1.8%, +1.8%]$)，量比 $\le 1.05$ 极度地量萎缩，收十字星或企稳阳线 跌破 EMA20 $\times 0.985$ 窄止损 (试错成本通常 $\le 2.5%$) 70% 重仓加码

10.1 威科夫量化生命周期四大战术形态契约

from tradingpatterns import (
    TacticalPatternType,
    TacticalPatternSignal,
    detect_bottom_reversal,
    detect_ma_startup,
    detect_volume_breakout,
    detect_pullback_low_absorb,
    scan_tactical_patterns,
)

# 查看支持的四大战术类型
for p_type in TacticalPatternType:
    print(p_type.value)
# 输出:
# BOTTOM_REVERSAL
# MOVING_AVERAGE_STARTUP
# VOLUME_BREAKOUT
# PULLBACK_LOW_ABSORB

10.2 单买点独立判定函数

每个战术形态均提供纯函数接口，输入单标的 OHLCV DataFrame，返回 (is_triggered, entry_price, stop_loss, reasons) 四元组：

# 1. 🧱 底部反转识别 (超跌极值点)
is_btm, btm_price, btm_sl, btm_reasons = detect_bottom_reversal(df)

# 2. ✨ 均线启动识别 (均线粘合初动)
is_start, start_price, start_sl, start_reasons = detect_ma_startup(df)

# 3. 🚀 放量突破识别 (主升浪点火)
is_brk, brk_price, brk_sl, brk_reasons = detect_volume_breakout(df)

# 4. 🎯 缩量回踩识别 (黄金第二买点)
is_pb, pb_price, pb_sl, pb_reasons = detect_pullback_low_absorb(df)

10.3 全量战术买点扫描与自适应仓位建议 (scan_tactical_patterns)

支持一键扫描当前交易日前向触发的全部战术买点并输出标准信号列表：

signals = scan_tactical_patterns(
    df=df,
    symbol="510050",
    oversold_score=0.0,       # 若外部已计算超跌分可直接传入，未传入时自动自驱计算
    has_pattern_bypass=False
)

for sig in signals:
    print(f"【{sig.label}】 触发级别: {sig.signal_tier}")
    print(f"推荐开仓价: {sig.entry_price:.3f} | 初始窄止损位: {sig.stop_loss:.3f}")
    print(f"建议战术仓位: {sig.suggested_weight_pct * 100:.0f}% | 技术综合打分: {sig.score}")
    print(f"形态判定依据: {sig.reasons}")

11. 机会生命周期跟踪与滚动回放 (opportunity_lifecycle)

该模块把雷达的「当日截面切片」升级为纵向时间演变跟踪：标的被雷达捕获后建档入池，逐日推进五阶段生命周期，触发主动止盈 / 破位止损 / 沉寂超时后淘汰出池，并输出结构化账本与「进池 / 出池」流转日志。

11.1 生命周期阶段与准入/退出枚举

五阶段生命周期 (LifecycleStage) —— 由 tradingpatterns 顶层直接导出：

阶段枚举 中文标签 业务含义
STAGE_0_SPROUT 🔥 异动萌芽 当日/当周出现放量异动（主力放量打桩）
STAGE_1_SETUP 👀 蓄势磨底 缩量洗盘蓄势或前瞻潜伏
STAGE_2_BREAKOUT 🚀 突破击球 策略引擎确认的首发买点
STAGE_3_PULLBACK 🎯 黄金回踩 缩量回踩 EMA20 的第二买点
STAGE_4_RIDING 🌊 趋势延续 主升浪顺势持有（含防追高标记）
STAGE_X_INVALID 🛑 退出出池 止盈结案 / 破位止损 / 沉寂超时

准入通道 (EntryChannel) 与退出原因 (ExitReason) —— 均由 tradingpatterns 顶层直接导出：

from tradingpatterns import LifecycleStage, ExitReason, EntryChannel, PoolEventType

# 五级阶梯式准入通道
[e.value for e in EntryChannel]
# ['LEVEL_0_PRE_INCUBATION', 'LEVEL_1_VOLUME_SURGE', 'LEVEL_2_BREAKOUT',
#  'LEVEL_3_PULLBACK', 'LEVEL_4_TREND_RIDING']

# 四大退出原因
[e.value for e in ExitReason]
# ['NONE', 'PROFIT_TAKEN', 'BREAKDOWN_STOP', 'TIME_EXPIRED']

# 两大流转事件类型
[e.value for e in PoolEventType]
# ['ENTRY', 'EXIT']
退出原因 中文 说明
NONE 跟踪中 仍在活跃池内
PROFIT_TAKEN 止盈结案 主动止盈（硬目标或动态吊灯）
BREAKDOWN_STOP 破位止损 价格真跌破结构防守线 / EMA53
TIME_EXPIRED 沉寂超时 横盘超期且资金退潮

11.2 入池双门禁

为什么要门禁：仅凭放量异动入池会把钝化、追高、纯放量标的全部纳入，导致跟踪名单噪声极大。入池需同时通过两道门禁——质量提纯 与 看涨形态确认。

confirm_bullish_formation(df, lookback=5, min_strength=2) -> Tuple[bool, str]

校验标的在最近 lookback 根 K 线内是否存在经确认的看涨图表形态。

参数 类型 默认 说明
df pd.DataFrame — as-of 切片后的 OHLCV，禁止传含未来数据的全量 df
lookback int 5 形态回溯 K 线根数
min_strength int 2 形态确认最低强度门槛

返回：(是否确认, 命中的看涨形态名)；未确认时形态名为空串。

行为约定：

  • 内部调用 get_recent_bullish_patterns(..., enable_confirmation=True, min_strength=...)；
  • 对称三角形 (SYMMETRICAL_TRIANGLE) 被显式排除——其突破方向待定，不属于看涨形态；
  • 数据不足（len(df) < 20）或检测抛异常时一律安全降级为 (False, "")，不向上抛错。

select_trackable_opportunities(radar_report, pool_dict, top_n=3, pattern_lookback=5, pattern_min_strength=2, min_tech_score=4.5)

多轨差异化入池门禁与可操作性 Top-N 选拔：四大准入通道分轨驱动、差异化形态门禁校验与可操作性综合提纯。

四大准入通道与差异化门禁规范：

  1. 🟣 黄金回踩轨 (LEVEL_3_PULLBACK)：由 get_golden_pullback_second_buys 检出，必须通过 confirm_bullish_formation 看涨几何形态确认，初始阶段为 STAGE_3_PULLBACK；
  2. 🔴 首发突破轨 (LEVEL_2_BREAKOUT)：由 get_launch_breakouts 检出，必须通过 confirm_bullish_formation 看涨几何形态确认，初始阶段为 STAGE_2_BREAKOUT；
  3. 🟡 放量异动轨 (LEVEL_1_VOLUME_SURGE)：由 get_volume_surges 检出，豁免几何形态强确认，以均线健康底线（close >= ema20 * 0.985 且 tech_score >= 4.0）与非追高温和正向涨幅（change_pct >= +1.5%，is_chasing=False）为硬门禁，初始阶段为 STAGE_0_SPROUT；
  4. 🟢 超跌企稳轨 (LEVEL_0_PRE_INCUBATION)：由 get_high_quality_oversold_stabilized 检出，豁免几何形态确认，严守周线筑底质量评分门禁（bottom_score >= 4.0 且排除陷阱级），初始阶段为 STAGE_1_SETUP。

多轨冲突仲裁优先级： $$\text{黄金回踩 (PULLBACK)} \succ \text{首发突破 (BREAKOUT)} \succ \text{放量异动 (VOLUME_SURGE)} \succ \text{超跌企稳 (OVERSOLD)}$$

参数 类型 默认 说明
radar_report OpportunityRadarReport — analyze_opportunity_radar() 的返回报表
pool_dict Dict[str, Tuple[str, pd.DataFrame]] — {"510050": ("上证50ETF", as_of_df), ...}，必须是 as-of 切片
top_n int 3 每日最多入池标的数
pattern_lookback int 5 形态回溯 K 线根数
pattern_min_strength int 2 形态确认最低强度
min_tech_score float 4.5 可操作性筛选的最低技术评分

返回：List[Tuple[OpportunityRadarItem, str]]，即 [(雷达条目, 命中的形态名或准入描述), ...]，按可操作性优先级降序，且条目上附加 entry_channel、initial_stage 与 trigger_selector 元数据。

from tradingpatterns import analyze_opportunity_radar
from tradingpatterns.opportunity_lifecycle import (
    select_trackable_opportunities,
    confirm_bullish_formation,
)

radar = analyze_opportunity_radar(pool, frequency="daily", market_context_df=mctx)

# 单标的形态校验
is_bullish, pattern = confirm_bullish_formation(pool["510050"][1], lookback=5, min_strength=2)

# 当日入池名单（每日最多 3 只）
for item, pattern in select_trackable_opportunities(radar, pool, top_n=3):
    print(f"入池: {item.name}({item.symbol}) 形态={pattern} 技术分={item.tech_score:.1f}")

11.3 出池三通道与阈值

出池判定在 track_opportunity_lifecycle() 内部完成，三大通道语义如下：

通道 ExitReason 触发条件 需价格确认
① 主动止盈 PROFIT_TAKEN 累计涨幅 ≥ 3.0% 硬目标；或持有期峰值浮盈 ≥ 2.0% 后收盘跌破 峰值 − 2.2 × ATR14 动态吊灯线（且收盘仍高于入池价） 是
② 破位止损 BREAKDOWN_STOP 收盘 < 防守位 × 0.985；或（收盘 < EMA53 且 EMA20 乖离 < −3%）；吊灯线击穿但已跌破入池价 是
③ 沉寂超时 TIME_EXPIRED spotted_bars_ago ≥ max_setup_bars 且未处右侧、无买点、量能萎缩至 ≤ 0.65x 否

可调阈值常量（从子模块导入，修改前请确认与回测口径一致）：

from tradingpatterns.opportunity_lifecycle import (
    PROFIT_TAKEN_HARD_TARGET_PCT,   # 3.0  主动止盈硬目标（累计涨幅 %）
    CHANDELIER_ACTIVATION_PCT,      # 2.0  吊灯跟踪止盈激活阈值（峰值浮盈 %）
    CHANDELIER_ATR_MULT,            # 2.2  吊灯跟踪回撤倍数（ATR）
    CHANDELIER_ATR_WINDOW,          # 14   吊灯 ATR 周期
    DEFAULT_ADMISSION_TOP_N,        # 3    每日入池上限
    DEFAULT_PATTERN_LOOKBACK,       # 5    形态回溯 K 线根数
    DEFAULT_PATTERN_MIN_STRENGTH,   # 2    形态确认最低强度
    VOLUME_SURGE_FAST_DECAY_BARS,   # 5    异动快速衰减检验窗口 (5 根 K 线)
    VOLUME_SURGE_DECAY_VOL_RATIO,   # 0.7  异动衰减量能阈值 (量比 <= 0.7)
)

出池增强三大机制：

  1. 破位止损 (BREAKDOWN_STOP) 双重确认：跌破防守线 0.985，或命中结构破位/卖出风险且跌破 EMA20；
  2. 沉寂超时 (TIME_EXPIRED) 加速淘汰：蓄势期达 max_setup_bars 超时，或钝化满 3 根 K 线加速超时，或放量异动标的满 5 根 K 线未突破且量比萎缩至 0.7 以下快速衰减出池；
  3. 主动止盈 (PROFIT_TAKEN) 动态吊灯：浮盈达 2.0% 激活 ATR 吊灯线，并在短线严重超买（偏离 EMA20 > 5.0%）时自适应收紧回撤容忍倍数至 1.5 ATR 锁定利润。

11.4 单标的生命周期推导

track_opportunity_lifecycle(...) -> TrackedOpportunityItem

对单只标的做完整的生命周期量化推导（纯函数、无状态）。

参数 类型 默认 说明
df pd.DataFrame — as-of 切片后的 OHLCV
symbol / name str "" 标的代码与名称
frequency str "daily" "daily" 或 "weekly"
market str "auto" "auto" / "CN" / "US"
lookback_bars Optional[int] None 回溯异动窗口；仅在未传入入池档案时生效（日频默认 30 / 周频默认 4）
max_setup_bars Optional[int] None 蓄势超时出池阈值（日频默认 15 / 周频默认 4）
config Optional[OpportunityRadarConfig] None 雷达配置，缺省用 DEFAULT_RADAR_CONFIG
market_context_df Optional[pd.DataFrame] None 大盘基准上下文
first_spotted_date Optional[str] None 入池档案：首次入池日期
spotted_bars_ago Optional[int] None 入池档案：已跟踪 K 线根数
spotted_price Optional[float] None 入池档案：入池价（cumulative_return 的基准）
entry_channel Optional[Union[str, EntryChannel]] None 准入通道：标的入池轨道 (如 LEVEL_1_VOLUME_SURGE)

返回：TrackedOpportunityItem 强类型数据对象，支持 .to_dict() 序列化。核心字段：

字段 说明
stage / stage_cn / stage_age_bars 当前生命周期阶段、中文标签、持续 K 线根数
first_spotted_date / spotted_bars_ago 首次入池日期、已跟踪 K 线根数
cumulative_return 自入池价以来的累计涨跌幅（%）
exit_reason / exit_reason_cn 退出原因枚举与中文
support_price / ema20_price / dist_to_ema20 核心防守位、EMA20、乖离率
invalidation_condition 失效判定条件描述（含卖出信号降级提示）
headline / media_tag / action_advice 一句话摘要、状态标签、大白话操作指引
is_radar_spotted / radar_type / has_execution_signal / signal_tier 雷达前哨与交易引擎信号的解耦标记 
from tradingpatterns import track_opportunity_lifecycle

item = track_opportunity_lifecycle(
    df=df.iloc[:t + 1],              # as-of 切片，杜绝未来函数
    symbol="510050",
    name="上证50ETF",
    frequency="daily",
    max_setup_bars=15,
    first_spotted_date="2026-08-31",
    spotted_bars_ago=3,
    spotted_price=3.041,
)

print(f"[{item.stage_cn}] {item.name} 累计 {item.cumulative_return:+.1f}% | 防守 {item.support_price:.3f}")
print(f"退出原因: {item.exit_reason_cn} | 提示: {item.media_tag}")
print(f"失效条件: {item.invalidation_condition}")

11.5 全池跟踪账本与逐日滚动回放

replay_opportunity_pool(pool_dict, frequency="daily", track_days=7, top_n=3, ...) -> Tuple[OpportunityTrackingBook, List[OpportunityFlowEvent]]

核心滚动跟踪与回放引擎（纯函数、无状态、无未来函数）。

该函数为全池标的执行逐日截面切片与五阶段生命周期流转推演：

  1. 逐日推进：在回放窗口内模拟时间流逝（每一步严格只切片到当日收盘 iloc[:t+1]）；
  2. 入池双门禁：当日触发的新机会经「形态确认 + 质量提纯 Top-N」双门禁审核后建档，生成 ENTRY 流转事件；
  3. 在池演化：对已在池标的按五阶段状态机推进，动态计算浮盈、核心防守位与移动吊灯止盈位；
  4. 淘汰出池：触发主动止盈、破位止损或沉寂超时后生成 EXIT 事件，移出活跃池并归入结案名单；
  5. 纯数据输出：返回最终的 OpportunityTrackingBook 结构化账本对象与 List[OpportunityFlowEvent] 流转事件列表，便于 API / Web / 外部管道直接消费。
参数 类型 默认 说明
pool_dict Dict[str, Tuple[str, pd.DataFrame]] — 全池标的字典：{"代码": ("名称", full_df)}
frequency str "daily" 扫描频率："daily" 或 "weekly"
track_days int 7 滚动回放窗口期（交易日根数）
top_n int 3 每日入池上限（入池质量门禁 Top-N）
max_setup_bars Optional[int] None 横盘蓄势超时淘汰阈值（缺省跟随 track_days）
market_context_df Optional[pd.DataFrame] None 大盘基准 K 线 DataFrame（可选）
final_report Optional[OpportunityRadarReport] None 末步已算好的雷达报表（可选，省去末步重复计算）
include_alerts bool True 是否允许高质量预警标的参与入池门禁

返回：(OpportunityTrackingBook, List[OpportunityFlowEvent])

from tradingpatterns import (
    replay_opportunity_pool,
    OpportunityTrackingBook,
    OpportunityFlowEvent,
    PoolEventType,
)

# 1. 传入全池行情 DataFrame 字典进行多日滚动跟踪
book, events = replay_opportunity_pool(
    pool_dict=pool,
    frequency="daily",
    track_days=7,
    top_n=3,
)

# 2. 消费进出池流转事件 (纯结构化数据，无 print 侵入)
for evt in events:
    action = "入池" if evt.event_type == PoolEventType.ENTRY else "出池"
    print(f"[{evt.date}] {action}: {evt.name}({evt.symbol}) 现价 {evt.price:.3f} | {evt.message}")

# 3. 消费当前账本中的活跃跟踪池与结案名单
print(f"\n当前活跃标的 ({len(book.all_active_items())} 只):")
for it in book.all_active_items():
    print(f"  [{it.stage_cn}] {it.name}({it.symbol}) 累计 {it.cumulative_return:+.1f}% | 防守位: {it.support_price:.3f}")

print(f"\n本期结案退出 ({len(book.invalidated)} 只):")
for it in book.invalidated:
    print(f"  [{it.exit_reason_cn}] {it.name}({it.symbol}) 累计 {it.cumulative_return:+.1f}%")

# 4. 结构化 JSON 导出 (供下游 Web / API 服务直接使用)
payload = book.to_dict()

track_radar_report(radar_report, pool_dict, ...) -> OpportunityTrackingBook

接收单期雷达报表，对雷达发现的标的做纵向生命周期跟踪并归类汇总。

scan_and_track_opportunities(pool_dict, frequency="daily", market="auto", ...) -> OpportunityTrackingBook

内部自动完成「雷达扫描发现 → 生命周期跟踪」全链路的便捷入口。

返回：OpportunityTrackingBook 账本对象，按阶段分桶存放：

属性 说明
sprouts / setups / breakouts / pullbacks / ridings 阶段 0~4 的活跃标的
invalidated 阶段 X：本期结案退出名单
newly_admitted / current_exited 本期新纳入 / 本期移出
active_pre_incubations() 活跃中的前瞻潜伏池（激进/耐心读者）
active_right_side_confirmations() 活跃中的右侧确认池（稳健读者）
all_active_items() 全部活跃标的（排除已出池）
total_count() 活跃 + 已出池总数
to_dict() 序列化为字典（含各分桶计数 counts）

11.6 逐日滚动回放实战范式与窗口调优

逐日滚动回放基于公有顶层 API replay_opportunity_pool()，对目标标的池进行纵向时间推演：从窗口起点起逐交易日推演全池雷达切片，当日通过质量与形态双门禁的机会首次入池建档；已在池中的标的按五阶段状态机推进并动态计算浮盈与防守线；触发主动止盈、破位止损或沉寂超时的标的淘汰出池，最终输出结构化账本 OpportunityTrackingBook 与全量流转日志 List[OpportunityFlowEvent]。

核心调优参数与行为约定

参数 类型 默认 说明
pool_dict Dict[str, Tuple[str, pd.DataFrame]] — 全池标的行情字典：{"代码": ("名称", df)}
frequency str "daily" 扫描频率："daily" 或 "weekly"
track_days int 7 回放窗口交易日数：往回推演几个交易日（日频推荐 10~20，周频推荐 20）
top_n int 3 每日入池上限（入池质量门禁 Top-N）
max_setup_bars Optional[int] None 横盘蓄势超时淘汰阈值（缺省跟随 track_days；建议独立设为 15~20）
market_context_df Optional[pd.DataFrame] None 大盘基准行情，提供宏观择时上下文
include_alerts bool True 是否允许高质量预警标的参与入池门禁

快速推演代码范式

from tradingpatterns import (
    replay_opportunity_pool,
    PoolEventType,
    OpportunityTrackingBook,
)

# 1. 启动逐日滚动回放推演 (以日频 15 个交易日窗口、每日最多入池 3 只为例)
book, events = replay_opportunity_pool(
    pool_dict=pool_dict,
    frequency="daily",
    track_days=15,
    top_n=3,
    max_setup_bars=15,
)

# 2. 消费逐日流转日志
for evt in events:
    action = "入池" if evt.event_type == PoolEventType.ENTRY else "出池"
    print(f"[{evt.date}] {action}: {evt.name}({evt.symbol}) 现价 {evt.price:.3f} | {evt.message}")

# 3. 统计最终账本
print(f"累计活跃标的: {len(book.all_active_items())} 只，已结案标的: {len(book.invalidated)} 只")

12. 统一行情数据获取与标准化接口 (get_any_ohlc)

12.1 设计背景与数据源规整原则

在量化策略与机会雷达系统中，标的代码涵盖股票、A 股 ETF、大盘指数、行业指数以及美股 ETF 等多种异构类型。底层数据源 kdata-quant 2.0 规范对不同标的设有明确的接口分流与代码校验规则：

  1. 股票与 ETF 接口 (kdata.get_ohlc)：用于常规股票、ETF、LOF 及美股标的，若误传大盘指数会抛出 ValueError；
  2. 大盘指数接口 (kdata.get_index_ohlc)：专用于大盘指数，强制要求指数代码包含交易所市场前缀（如 sh.000300、sz.399001）或传入 MarketIndex 枚举，若传入无前缀的纯数字（如 000300）会抛出参数错误；
  3. 输出标准化要求：不同接口返回的数据在列名大小写、时间索引类型及空值格式上存在细微差异。

为消除调用方的认知负担与代码冗余，tradingpatterns 提供了高内聚的统一行情获取函数 get_any_ohlc：

  • 智能自动路由：根据代码特征前缀及指数清单，自动识别股票/ETF 与大盘指数并分流调用相应底层接口；
  • 前缀自动规整：自动将纯数字指数代码规整为标准带前缀格式，同时支持 MarketIndex 枚举直接穿透；
  • 双向自愈降级：捕获接口因标的类型误判产生的异常并自动切换回退重试，保障数据流水线健壮不中断；
  • 输出格式标准化：统一输出全小写列名 ['open', 'high', 'low', 'close', 'volume']，索引强制转为 pd.DatetimeIndex 且按时间升序排列，空数据安全返回标准空 DataFrame。

12.2 标的代码智能路由与格式规整

is_likely_index(symbol_or_index: Union[str, MarketIndex]) -> bool

判断传入的代码是否为大盘或行业指数标的。

  • 判定规则：
    1. 若传入 MarketIndex 枚举实例，直接返回 True；
    2. 明确匹配已知核心大盘指数（如 000001, 000300, 399001, 000905, 932000, 000688, us.GSPC 等）；
    3. 属于 A 股 ETF/LOF 专属号段（51, 56, 58, 15, 16 开头）时，必定返回 False（确保进入个股/ETF 通道）；
    4. 具备典型指数前缀特征（399、sh.000、sz.399 等）或包含 index 关键词时，返回 True。

normalize_index_symbol(symbol_or_index: Union[str, MarketIndex]) -> Union[str, MarketIndex]

将纯数字指数代码自动规整为带交易所前缀的标准代码格式，支持枚举类型直接穿透。

  • 映射规整范例：
    • '000300' $\to$ 'sh.000300'
    • '000001' $\to$ 'sh.000001'
    • '399001' $\to$ 'sz.399001'
    • '399006' $\to$ 'sz.399006'
    • 'sh000300' $\to$ 'sh.000300'
    • MarketIndex.HS300 $\to$ MarketIndex.HS300（保持枚举对象不变）

12.3 核心统一获取函数 (get_any_ohlc)

get_any_ohlc(...) -> pd.DataFrame

统一获取股票、ETF 或大盘指数的标准化 OHLCV K 线数据。

def get_any_ohlc(
    symbol: Union[str, MarketIndex],
    start_date: Optional[Union[str, pd.Timestamp, datetime]] = None,
    end_date: Optional[Union[str, pd.Timestamp, datetime]] = None,
    period: Optional[object] = None,
    **extra_parameters: object,
) -> pd.DataFrame:
参数 类型 默认值 说明
symbol Union[str, MarketIndex] — 标的代码或指数枚举（如 '510300', 'sh.000300', '000300', '600519', 'us.SPY', MarketIndex.SH）
start_date Optional[Union[str, pd.Timestamp, datetime]] None 起始日期，支持字符串 'YYYY-MM-DD' 或时间对象
end_date Optional[Union[str, pd.Timestamp, datetime]] None 结束日期，支持字符串 'YYYY-MM-DD' 或时间对象
period Optional[object] None K 线周期，默认为日线（如 Period.DAILY）
**extra_parameters object — 透传给底层行情驱动的可选参数

返回值：

  • pd.DataFrame：清洗规范化后的标准 OHLCV 数据，列名小写，时间升序，索引为 pd.DatetimeIndex。标的无数据或为空时，返回包含标准列名的空 DataFrame。

12.4 标准化 OHLCV 输出结构与实战调用范式

标准数据结构

无论调用何种标的，返回的 DataFrame 均具备以下一致的形态：

  • 索引：pd.DatetimeIndex，按时间由远及近严格升序排序；
  • 标准列：['open', 'high', 'low', 'close', 'volume']，全小写字母，数值类型统一。若存在成交额字段则标准化为 'amount'。

实战调用范式

from tradingpatterns import get_any_ohlc
from kdata.markets import MarketIndex

# 1. 获取 A 股行业 ETF 数据 (自动路由至 get_ohlc)
df_etf = get_any_ohlc("510300", start_date="2024-01-01", end_date="2024-12-31")
print("ETF 数据尾部:")
print(df_etf.tail(2))

# 2. 获取大盘指数数据 (带前缀代码，自动路由至 get_index_ohlc)
df_index = get_any_ohlc("sh.000300", start_date="2024-01-01", end_date="2024-12-31")
print("指数数据尾部:")
print(df_index.tail(2))

# 3. 获取大盘指数数据 (纯数字代码，自动规整补齐前缀 sh.000300)
df_auto_norm = get_any_ohlc("000300", start_date="2024-01-01", end_date="2024-12-31")

# 4. 使用官方 MarketIndex 枚举获取
df_enum = get_any_ohlc(MarketIndex.SH, start_date="2024-01-01", end_date="2024-12-31")

# 5. 获取美股 ETF 数据 (自动路由至 get_ohlc)
df_us = get_any_ohlc("us.SPY", start_date="2024-01-01", end_date="2024-12-31")

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.6.9)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for huzhe2020 from gravatar.com huzhe2020

Credits

Author: Preetam Sharma

License

CC BY-NC-SA 4.0

Requires

Python ==3.12.*

Provides Extra

backtest

Report project as malware

Release files for tp-quant 1.6.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for tp-quant 1.6.1
File Interpreter ABI Platform
tp_quant-1.6.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl 6.2 MB CPython 3.12 CPython 3.12 Linux glibc 2.17+ x86-64 Details
tp_quant-1.6.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl 5.5 MB CPython 3.12 CPython 3.12 Linux glibc 2.17+ ARM64 Details
tp_quant-1.6.1-cp312-cp312-macosx_11_0_arm64.whl 4.6 MB CPython 3.12 CPython 3.12 macOS 11.0+ ARM64 Details

Total release size: 16.3 MB

Release files / tp_quant-1.6.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL tp_quant-1.6.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 6.2 MB
Tags CPython 3.12 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums 		c9d6783fc2e915c1ee7a6d1835b50c36162fe12d99f581e16605896906a84f4c
BLAKE2b-256 checksum
How to use checksums 		dc9107bd9cb20846a6422560da38b4966e1301d5f07f35a7ad9b190b382ed61c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via uv/0.9.15 {"installer":{"name":"uv","version":"0.9.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / tp_quant-1.6.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL tp_quant-1.6.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 5.5 MB
Tags CPython 3.12 Linux glibc 2.17+ ARM64
SHA-256 checksum
How to use checksums 		43d760753ecde06a11c0c082f6e24cafbfc9cc41e04fd7c3e5037e13487eae5d
BLAKE2b-256 checksum
How to use checksums 		f983cd81810d5f44a59c63d76afbe441840c2f58ffc0bbb577bccb42c611a9fd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via uv/0.9.15 {"installer":{"name":"uv","version":"0.9.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / tp_quant-1.6.1-cp312-cp312-macosx_11_0_arm64.whl

Download URL tp_quant-1.6.1-cp312-cp312-macosx_11_0_arm64.whl
Size 4.6 MB
Tags CPython 3.12 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums 		2e2556d7b6d098429518f77ff2d9a4c58e67fa7b295cb8420d8497dea74bed22
BLAKE2b-256 checksum
How to use checksums 		066c3f50bf8c0c68914e7d0a2a065a963a95e50a458959cd67ceeb54ec8487cd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via uv/0.9.15 {"installer":{"name":"uv","version":"0.9.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release history Release notifications | RSS feed

1.6.9

3 release files

1.6.8

3 release files

1.6.7

3 release files

1.6.6

3 release files

1.6.5

4 release files

1.6.4

3 release files

1.6.2

3 release files

This release

1.6.1 This release

3 release files

1.6.0

3 release files

1.5.6

3 release files

1.5.5

3 release files

1.5.4

3 release files

1.5.3

3 release files

1.5.1

3 release files

1.5.0

3 release files

1.4.3

3 release files

1.4.2

3 release files

1.4.1

3 release files

1.4.0

3 release files

1.3.0

3 release files

1.2.6

3 release files

1.2.5

3 release files

1.2.4

3 release files

1.2.3

3 release files

1.2.2

3 release files

1.2.1

3 release files

1.2.0

3 release files

1.1.4

3 release files

1.1.3

3 release files

1.1.2

3 release files

1.1.1

3 release files

1.1.0

3 release files

1.0.4

3 release files

1.0.3

3 release files

1.0.2

3 release files

1.0.1

1 release file

1.0.0

3 release files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page