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

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

安装包：pip install tp-quant

[!TIP] 🌟 全频段自适应特性 (Timeframe-Agnostic Adaptation)
核心引擎（包括各大策略与形态机）内置了自动频率推断。你可以自由传入日线 (Daily) 或 周线 (Weekly) DataFrame：

• 内部参数自适应：算法会自动探测 df 的物理间隔（如 1天 vs 7天），并将所有硬编码的 K 线阈值（如横盘 15 天）智能折算（如变更为横盘 3 周）。
• 多周期共振升维：涉及“跨周期共振”的策略，输入日线时会自动参考周线，而输入周线时则会自动升维参考月线 (Monthly)！无需人工指定参数，实现无缝的小图进场、大图顺势。

目录索引 (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 全景回测与实战验证 CLI
2. 网格交易与组合资产顾问 (grid & grid_advisor)
   • 2.1 单标的网格计划 (build_grid_plan)
   • 2.2 ETF 网格严选评估 (evaluate_strict_grid_candidate)
   • 2.3 网格事件驱动轻量回测 (simulate_grid_strategy)
   • 2.4 多标的组合网格与 8 步调仓换仓 (build_etf_grid_advice)
3. 技术形态扫描与预筛选管道 (pre_screen_and_scan)
   • 3.1 预筛选与扫描主接口
   • 3.2 Context Package 上下文数据包全字段解析
   • 3.3 威科夫量价供需分析 (detect_wyckoff_context)
4. 市场状态机与多周期趋势评估
   • 4.1 综合唯一主状态机 (detect_side_state)
   • 4.2 做多右侧状态机 (detect_right_side_state)
   • 4.3 底部结构跟踪状态机 (detect_bottom_tracking_state)
   • 4.4 独立周线中期趋势质量评分 (evaluate_weekly_trend)
5. 市场环境与辅助分析工具
   • 5.1 市场情绪温度计 (sentiment_thermometer)
   • 5.2 动态支撑阻力计算 (calculate_support_resistance)
   • 5.3 组合风险平权与相关性去重
6. 均值回归与板块轮动引擎 (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)
7. 美股专属量化系统与机会雷达 (us_macro / us_strategy / us_opportunity_radar)
   • 7.1 宏观绝对动量与体制判别 (us_macro)
   • 7.2 自适应超级趋势与截面双动量策略 (us_strategy)
   • 7.3 美股专属 0-10 分机会雷达与 5 大状态机 (us_opportunity_radar)
   • 7.4 美股全景回测与雷达扫描 CLI

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,      # 全池多周期雷达批量扫描 (内嵌板块轮动)
    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"]）：

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 全市场多周期雷达批量扫描

雷达模块负责全市场标的实时扫描、内嵌板块轮动截面计算、多引擎信号聚合、时效性降级 (Staleness Check) 以及多栏目去重归类，可直接作为自媒体每日内容生产工具与选品大漏斗：

from tradingpatterns import analyze_opportunity_radar

# 批量扫描标的池 (内置自动计算截面相对强弱与四象限轮动)
vol_list, opp_list, risk_list = analyze_opportunity_radar(
    etf_pool={"515880": ("通信ETF", df1), "512880": ("证券ETF", df2), "513120": ("港股创新药", df3)},
    frequency="weekly",   # "weekly" 或 "daily"
    min_amount_ea=None,
    min_vol_ratio=1.5,
    min_pct_change=1.5,
)

# 自动格式化输出自媒体复盘日报
print(f"📊 【量化机会雷达 | 今日全市场扫描】\n")

print("🔥 【核心策略引擎触发】")
for item in opp_list:
    if item["opp_sources"]:
        print(f"• [{item['primary_opp_source']}] {item['symbol']} {item['name']}: 建议防守位 {item['stop_loss']:.3f} | 板块象限: {item['quadrant_cn']}")

print("\n👀 【蓄势预热池】")
for item in opp_list:
    if not item["opp_sources"] and item["curr_state_cn"] in ["筑底成熟", "启动预热", "蓄势待发"]:
        print(f"• {item['symbol']} {item['name']}: 状态【{item['curr_state_cn']}】, 均线贴近支撑")

print("\n⚠️ 【风险预警】")
for item in risk_list:
    print(f"• {item['symbol']} {item['name']}: 状态【{item['curr_state_cn']}】, 警惕回调风险")

1.4 全景回测与实战验证 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 动态换仓组合回测。

2. 网格交易与组合资产顾问

网格模块提供震荡市均值回归套利的完整量化解决方案，包括单标的几何 ATR 网格构建、ETF 专属最优参数池、事件驱动回测引擎与组合层 8 步调仓换仓顾问。

2.1 单标的网格计划：build_grid_plan

from tradingpatterns import build_grid_plan

plan = build_grid_plan(
    df,
    symbol="510300",
    capital=100000.0,
    grid_count=8,
    min_step_pct=0.008,
    max_step_pct=0.035,
    base_position_pct=0.30,
    max_position_pct=0.80,
    allocation_style="equal",    # "equal" 等额 或 "pyramid" 金字塔加权
    weekly=False,                # True 时按周线自适应
)

返回值核心字段：

• state: 网格状态枚举（GRID_ACTIVE 适合开网, PAUSED_TREND_UP 向上突破暂停买入, FAILED_BREAKDOWN 跌破止损, RESET_REQUIRED 需要重置, WAIT_RANGE 等待区间）。
• is_grid_tradeable (bool): 当前是否满足开网条件。
• orders (list[dict]): 包含具体买卖挂单价格与份额的委托计划。
• next_triggers (dict): 最近的下一买入与卖出触发价位。

2.2 ETF 网格严选评估：evaluate_strict_grid_candidate

一站式评估标的是否符合开启网格的严苛风控标准（包含趋势形态过滤、区间位置与收益率下限）：

from tradingpatterns import evaluate_strict_grid_candidate, get_etf_optimal_grid_params

res = evaluate_strict_grid_candidate(
    df,
    symbol="515880",
    capital=100000.0,
    grid_count=8,
    name="通信ETF",
    is_weekly_grid=True          # 启用周线大网格模式
)

if res["is_strict_pass"]:
    print("通过严选，可开启网格交易！")
else:
    print(f"未通过原因: {res['strict_fail_reasons']}")

• 内置最优参数表 (ETF_WEEKLY_OPTIMAL_PARAMS)：系统内置 44 只核心 ETF 的周线实证最优参数，启用 is_weekly_grid=True 时会自动覆盖为最优配置。

2.3 网格事件驱动轻量回测：simulate_grid_strategy

基于“收盘确认、次日开盘成交”原则的轻量事件驱动回测引擎：

from tradingpatterns import simulate_grid_strategy

backtest = simulate_grid_strategy(
    df,
    symbol="510300",
    capital=100000.0,
    grid_count=8,
    max_loss_pct=0.12            # 账户最大亏损强制止损阈值 (12%)
)

print(f"总收益率: {backtest['summary']['return_pct']}%")
print(f"最大回撤: {backtest['summary']['max_drawdown_pct']}%")
print(f"网格往返套利次数: {backtest['summary']['grid_roundtrips']}")

2.4 多标的组合网格与 8 步调仓换仓：build_etf_grid_advice

针对大容量 ETF 池在固定持仓上限（如 max_active_symbols = 10）下的组合网格交易与资金统筹调度：

from tradingpatterns import build_etf_grid_advice, compute_candidate_score

advice = build_etf_grid_advice(
    pool=etf_dfs_dict,
    asof_date="2026-08-19",
    max_active_symbols=10,
    capital=1000000.0,
    min_holding_days=20,
    min_switch_score_gap=15.0    # 候补第一名分差领先 15 分触发调仓
)

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 上下文数据包全字段解析

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

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

将筑底状态与右侧趋势合并为全局唯一主状态：

from tradingpatterns import detect_side_state, SideState

res = detect_side_state(df, weekly_mode="balanced")
print(f"主状态: {res['state']} | 来源: {res['state_source']}")

4.2 做多右侧状态机：detect_right_side_state

from tradingpatterns import detect_right_side_state, RightSideState

rs = detect_right_side_state(df, weekly_mode="balanced")
# 状态包括: BASE, CANDIDATE, RIGHT_CONFIRMED, RIGHT_ACTIVE, RIGHT_EXTENDED, FAILED

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

from tradingpatterns import detect_bottom_tracking_state, BottomTrackingState

bt = detect_bottom_tracking_state(df)
# 状态包括: DECLINING, BOTTOM_WATCH, BOTTOM_BUILDING, BOTTOM_MATURE, STARTUP_PREHEAT, BOTTOM_FAILED

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

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

5.1 市场情绪温度计：sentiment_thermometer

提供 A 股市场整体情绪温度（0~100）的计算、自适应历史分位数归一化及情绪状态分级：

from tradingpatterns import (
    compute_sentiment_snapshot,
    compute_sentiment_series,
    DEFAULT_CONFIG,
    SentimentConfig
)

# 1. 单日情绪快照 (推荐使用周频 freq="W" 进行波段择时)
snapshot = compute_sentiment_snapshot(date="2026-08-19", config=SentimentConfig(freq="W"))
print(f"情绪温度: {snapshot['temperature']} | 状态: {snapshot['state']} | 趋势: {snapshot['direction']}")

# 状态包含: ICE_COLD (≤15 极佳中线左侧区), COLD (15~35), NEUTRAL (35~65), HOT (65~85), OVERHEAT (≥85 止盈防守区)

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，判定为主力诱空假摔，触发快速纠错重入。

6.2 TA-Lib 底部反转形态扫描与权重 (scan_talib_patterns)

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

from tradingpatterns import scan_talib_patterns, BOTTOM_PATTERNS

# 扫描并获取当天命中的底部形态及综合权重
detected_patterns, total_weight = scan_talib_patterns(df_daily)
print("命中形态:", detected_patterns) # 如 ['CDLMORNINGSTAR', 'CDLENGULFING_BULL']
print("综合形态得分:", total_weight)      # 权重加权分

• 形态权重表 (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)

evaluate_universe 返回的 List[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,
    run_us_super_trend_strategy,
    compute_us_rotation_metrics,
    USTrendBacktestResult,
    USRotationMetric,
    USRotationQuadrant,
)

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

# 2. 单标的美股超级趋势策略回测 (内嵌宏观风控与动态吊灯止损)
result: USTrendBacktestResult = run_us_super_trend_strategy(
    df=qqq_df,
    symbol="QQQ",
    macro_series=macro_df,
    initial_capital=100000.0
)

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 美股专属 0-10 分机会雷达与 5 大状态机 (us_opportunity_radar)

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 美股全景回测与雷达扫描 CLI

使用内置的 CLI 工具对美股全池（data/etf/us.yaml）或自定义标的进行批量回测与最新雷达扫描：

# 全池回测与雷达扫描 (默认标的池 data/etf/us.yaml)
uv run python scripts/backtest_us_etfs.py --start 2024-01-01

# 指定单标的或重点行业组合
uv run python scripts/backtest_us_etfs.py -s SPY,QQQ,SMH,XLK,XLE,GLD --start 2022-01-01 --end 2022-12-31

# 输出 JSON 格式
uv run python scripts/backtest_us_etfs.py -s SPY,QQQ --json