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

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

安装包：pip install tp-quant

[!TIP] 🌟 多周期协同与自适应契约 (Multi-Timeframe & Adaptation Guide)
核心引擎根据交易定位设计了严谨的周期输入契约与跨周期共振机制：

• 全域机会雷达与趋势跟踪 (Opportunity Radar / Kaufman)：支持传入日线 (Daily) 或 周线 (Weekly) 数据（可通过 timeframe="daily"|"weekly" 指定或由引擎自适应推断），在日线分析时会自动结合周线大趋势进行跨周期共振确认。
• 均值回归策略 (Mean Reversion / Engine 2)：标准设计契约要求传入日线 (Daily) OHLCV 数据，引擎内部会自动将其动态聚合为周线以判定周线布林带超跌与底部反转形态，并在日线级别执行 T+1 开盘撮合与三阶段动态跟踪止损。

---

🎯 核心架构速查与对应关系 (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)
🌟 双核综合引擎 (Combined Engine)	双核同时运行 / 实盘仿真回测 左侧 + 右侧信号一起抓，用于全历史实战回测与多策略综合调度	get_strategy_signal(StrategyEngine.COMBINED, df) run_strategy_engine_simulation()	第 1 章 (1.1, 1.4)
📊 截面板块轮动 (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)

---

目录索引 (Table of Contents)

1. 全域机会雷达综合引擎 (Combined Opportunity Radar)
   • 1.1 统一策略枚举与事件契约 (StrategyEngine)
   • 1.2 单标的雷达信号调用 (get_strategy_signal / evaluate_opportunity_radar_item)
   • 1.3 全市场多周期雷达批量扫描 (analyze_opportunity_radar)
   • 1.4 技术信号层与实盘执行层的核心区别 (get_strategy_signal vs run_strategy_engine_simulation)
   • 1.5 全景回测与实战验证 CLI
2. 技术形态扫描与预筛选管道 (pre_screen_and_scan)
   • 3.1 预筛选与扫描主接口
   • 3.2 Context Package 上下文数据包全字段解析
   • 3.3 威科夫量价供需分析 (detect_wyckoff_context)
3. 市场状态机与多周期趋势评估
   • 4.1 综合唯一主状态机 (detect_side_state)
   • 4.2 做多右侧状态机 (detect_right_side_state)
   • 4.3 底部结构跟踪状态机 (detect_bottom_tracking_state)
   • 4.4 独立周线中期趋势质量评分 (evaluate_weekly_trend)
4. 市场环境与辅助分析工具
   • 5.1 市场情绪温度计 (sentiment_thermometer)
   • 5.2 动态支撑阻力计算 (calculate_support_resistance)
   • 5.3 组合风险平权与相关性去重
5. 均值回归与板块轮动引擎 (mean_reversion & sector_rotation)
   • 6.1 A 股周线均值回归与三阶段跟踪 (get_mean_reversion_signal / MeanReversionSignal)
   • 6.2 TA-Lib 底部反转形态扫描与权重 (scan_talib_patterns)
   • 6.3 均值回归事件驱动回测 (run_mean_reversion_simulation)
   • 6.4 全池截面轮动评估与纯趋势研判 (evaluate_universe)
   • 6.5 四象限坐标体系与动能研判逻辑
   • 6.6 截面状态指标 (SectorMetric / RotationQuadrant)
   • 6.7 截面组合历史回测 (run_sector_rotation_backtest)
6. 美股专属量化系统与机会雷达 (us_macro / us_strategy / us_opportunity_radar)
   • 7.1 宏观绝对动量与体制判别 (us_macro)
   • 7.2 自适应超级趋势与截面双动量策略 (us_strategy / us_weekly_strategy)
   • 7.3 美股专属 0-10 分机会雷达与 5 大状态机 (us_opportunity_radar / us_weekly_opportunity_radar)
   • 7.4 多周期统一门面入口 (run_us_strategy / compute_us_rotation / analyze_us_radar)
   • 7.5 美股专属大类资产均值回归引擎 (us_mean_reversion)
   • 7.6 美股全景回测与雷达扫描 CLI
7. 跨境 QDII ETF 溢价套利与趋势共振引擎 (overseas_premium)
   • 8.1 底层资产映射与盘后时差对齐 (OVERSEAS_UNDERLYING_MAP / align_cn_us_series)
   • 8.2 60日相对比价偏离度计算 (calculate_premium_zscore)
   • 8.3 单标的实时机会与信号评估 (evaluate_overseas_opportunity_item / get_overseas_premium_signal)
   • 8.4 跨境全池机会雷达批量扫描 (analyze_overseas_radar / OverseasRadarSummary)
   • 8.5 双核共振策略回测与绩效寻优 (run_overseas_premium_strategy)
8. 实盘撮合与信号全生命周期追踪 (execution)
   • 9.1 交易所物理约束与涨跌停比例 (get_a_share_price_limit_ratio / ExecutionStatus)
   • 9.2 次日开盘撮合可行性仿真 (ExecutionMatcher)
   • 9.3 未成交信号追踪与生命周期汇总 (UnfilledSignal / compute_execution_summary)
9. 四大经典战术买点与全生命周期形态识别 (tactical_patterns)

• 10.1 威科夫量化生命周期四大战术形态契约 (TacticalPatternType / TacticalPatternSignal)
• 10.2 单买点独立判定函数 (detect_bottom_reversal / detect_ma_startup / detect_volume_breakout / detect_pullback_low_absorb)
• 10.3 全量战术买点扫描与自适应仓位建议 (scan_tactical_patterns)

---

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): 是否归入【量化异动】。
• is_risk (bool): 是否归入【风险提示】。
• quadrant / quadrant_cn (str): 所属板块轮动四象限（LEADING 领涨区 / RECOVERING 复苏区 / WEAKENING 衰退区 / LAGGING 滞后区）。
• rs_percentile (float): 相对基准的 60 日历史分位数 (0~100%)。
• rs_slope (float): 相对基准的 10 日线性回归斜率。

---

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,        # 技术评分准入门槛
)

---

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	是否触发任一核心策略买入信号。	全列表通用
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 (极限反转)"）。	vol_abnormal_list
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

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. 单日/当期动能奖惩 (防追高机制)：
   • 追高重罚：单日涨幅 > 5.0% 扣除 5.0 分（严禁接盘）；
   • 追高轻罚：单日涨幅 > 3.0% 扣除 2.5 分；
   • 温和奖励：单日涨幅在 0.0% ~ 3.0% 之间，奖励 +1.0 分（鼓励温和蓄势）；
3. 动能象限加权：LEADING (领涨) +2.0 分、RECOVERING (改善) +1.5 分、WEAKENING (衰退) -1.0 分、LAGGING (滞后) -2.0 分；
4. 买点与层级加权：
   • A 股双核心买点加成：左侧极限超跌反转 (sig_oversold) 或右侧黄金二买 (is_pullback) 享满额 +3.0 分；普通顺势突破克制加 +1.5 分；
   • 美股模式：顺势突破与回踩均享满额加成；
   • L2 临界观察 +1.5 分，L1 初选预警 +0.5 分；
5. 均线偏离安全垫与防追高硬门禁：
   • $-1.0% \le \text{dist_to_ema20} \le +1.5%$ (支撑位附近) +1.0 分；
   • $\text{dist_to_ema20} > 2.5%$ (过度偏离) 扣除 1.5 ~ 2.0 分；
   • A 股先锋硬门禁：A 股模式下若非缩量回踩或超跌反转，单日涨幅 > 2.5% 或偏离 EMA20 > 2.5% 的标的一票否决、严禁入选 Top-N 核心买入先锋！

---

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") 实施“双核心白名单机制”：仅允许左侧超跌逆转（Engine 2 周线布林超跌底分型）与右侧缩量回踩二买（EMA20 附近缩量企稳 is_pullback）进入机会池！若当天出现放量大阳线突破（即使触发 L3），一律安全降级踢入【预警观察池】（2.1 高质量蓄势），贴上 ⏳ 突破确立·等回踩 标签，坚决杜绝任何诱导空仓追高。
   • 美股市场 (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 动态换仓组合回测。

---

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": "流动性不足"
}

[!TIP] 集成安全建议：下游消费端解析返回结果时，建议先检查 if result.get("pre_screen_passed"): 或使用 .get() 进行字段安全读取，避免直接索引深层嵌套字段引发 KeyError。

字段路径	说明
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 15.0$	ICE_COLD	🥶 冰点极寒区	绝佳的左侧中线击球区，不要盲目割肉，逢低收集带血筹码！
$15.0 \sim 35.0$	COLD	❄️ 偏冷寻底区	市场处于左侧探底阶段，控制仓位，耐心等待右侧放量信号。
$35.0 \sim 65.0$	NEUTRAL	☁️ 中性震荡区	情绪平稳，重个股轻大盘，聚焦结构性机会。
$65.0 \sim 85.0$	HOT	🔥 偏热狂飙区	市场处于主升浪，持筹待涨。如果遇到降速回踩，通常是空中加油。
$\ge 85.0$	OVERHEAT	🌋 极度过热区	最高级别风控预警：中线面临均值回归压力，严禁追高，右侧破位坚决止盈！

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

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

常用核心基准标的池 (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. 信号延迟特性与中间态预警（纯信号观察者指南）：
   • 超跌企稳信号属于左侧偏确认型信号，从价格见底到最终 buy_signal=True 触发，典型延迟为 2~3 周（10~20 个交易日），距底部涨幅约 5%15%。早鸟通道（强反转形态 + 放量阳线 + 底背离）可将延迟缩短至约 1 周（68 个交易日），距底部涨幅约 3%~8%。
   • 防追高硬限保证信号触发时价格距近期低点涨幅不超过 max(10%, min(18%, 0.5 × 年化波动率))，超出则信号被阻断（当日放量 $\ge 1.8\times$ MA20 时豁免）。
   • 纯信号观察者实操建议：如果觉得最终 TRIGGERED 状态延迟偏长，可关注状态机的中间态 WAITING_DAILY（周线已完成超跌企稳确认、等待日线精确触发）——该状态比最终买入信号早出现 1~5 个交易日，可作为预警提前布局。雷达 alert_list 中已展示该中间态（signal_tier="L1"，curr_state="超跌观察"），下游系统可据此提前纳入自选跟踪。

---

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"]) # 返回详尽的买卖时间线

---

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}")