Add watch-only macro indicator coverage

Pigbibi · Pigbibi · commit d62a34f6e698 · 2026-05-29T00:34:37.000+08:00
diff --git a/README.md b/README.md
@@ -35,9 +35,10 @@ send notifications; plugin research and signal generation live here.
   optional external financial-stress fields. The artifact can expose
   `leverage_scalar` and `risk_asset_scalar` to strategy runtimes that explicitly
   opt in through mounted metadata. OSINT-style fields such as a Pentagon pizza
-  index, plus sentiment fields such as Fear & Greed, put/call, and safe-haven
-  demand, are kept as watch-only evidence and do not contribute to the
-  actionable trading score.
+  index, plus sentiment, options-volatility, rates, breadth, funding, and
+  liquidity fields such as Fear & Greed, put/call, VVIX, SKEW, MOVE, yield
+  curves, dollar stress, and safe-haven demand, are kept as watch-only evidence
+  and do not contribute to the actionable trading score.
 - `market_regime_control`: unified deterministic facade for crisis, macro, and
   TACO signals. Only strategies with positive backtest evidence should mount
   position controls for automated consumption; SOXL/SOXX currently receives
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -25,7 +25,7 @@ Brokers、Schwab、LongBridge、Firstrade 等平台仓库只负责加载 artifac
 
 - `crisis_response_shadow`：面向杠杆美股策略的黑天鹅防守观察插件。它只写入 shadow-mode artifact，不调用券商接口。
   可选启用 AI shadow audit：AI 只审计证据一致性和数据缺口，不改写确定性路线、不下单、不改仓位；默认优先尝试本机 Codex，失败后可走 OpenAI-compatible 或 Anthropic fallback endpoint。
-- `macro_risk_governor`：面向 TQQQ 的确定性宏观降杠杆插件。它按价格趋势、实现波动、VIX、信用相对压力和可选外部金融压力字段打分，输出 `leverage_scalar` / `risk_asset_scalar` 给显式 opt-in 的策略运行时消费。五角大楼比萨指数、Fear & Greed、put/call、safe-haven demand 这类 OSINT 或情绪字段只作为 watch-only 证据，不进入可执行分数。
+- `macro_risk_governor`：面向 TQQQ 的确定性宏观降杠杆插件。它按价格趋势、实现波动、VIX、信用相对压力和可选外部金融压力字段打分，输出 `leverage_scalar` / `risk_asset_scalar` 给显式 opt-in 的策略运行时消费。五角大楼比萨指数、Fear & Greed、put/call、VVIX、SKEW、MOVE、收益率曲线、美元压力、safe-haven demand 等 OSINT、情绪或跨资产字段只作为 watch-only 证据，不进入可执行分数。
 - `market_regime_control`：统一确定性 facade，汇总 crisis、macro 和 TACO 信号，输出版本化的 `notification` 和 `position_control`。只有经过回测证明自动消费有效的策略才挂载仓位控制；SOXL/SOXX 这类未通过统一宏观插件复核的高波动行业杠杆策略只接收通用通知，人工决定是否干预。股票/ETF 轮动策略通过本地风险缩放策略消费；TACO 在统一插件里保持通知-only，并会被危机和宏观降风险路线 veto。设计说明见 [Market Regime Control 统一插件方案](docs/market-regime-control-plan.zh-CN.md)。
 - `taco_rebound_shadow`：仅适用于 TQQQ 的事件反弹上下文通知插件。它只写入人工复核 artifact，不给仓位大小建议，也不改动配置或账户分配。缓和/降温事件会先保持 watch-only，只有事件后价格反弹确认通过后才触发人工复核通知，以减少过早抄底提醒。
   该插件也可选启用同样的 shadow-only AI audit，但 AI 只复核事件来源和反弹证据质量。
diff --git a/docs/examples/strategy_plugins.example.toml b/docs/examples/strategy_plugins.example.toml
@@ -17,6 +17,7 @@ event_set = "geopolitical-deescalation"
 benchmark_symbol = "QQQ"
 attack_symbol = "TQQQ"
 vix_symbols = ["VIX", "^VIX", "VIXCLS"]
+vix3m_symbols = ["VIX3M", "^VIX3M", "VXV", "^VXV"]
 credit_pairs = ["HYG:IEF", "LQD:IEF"]
 financial_symbols = ["XLF", "KRE"]
 rate_symbols = ["IEF", "TLT"]
@@ -47,6 +48,7 @@ event_set = "full"
 benchmark_symbol = "SOXX"
 attack_symbol = "SOXL"
 vix_symbols = ["VIX", "^VIX", "VIXCLS"]
+vix3m_symbols = ["VIX3M", "^VIX3M", "VXV", "^VXV"]
 credit_pairs = ["HYG:IEF", "LQD:IEF"]
 financial_symbols = ["XLF", "KRE"]
 rate_symbols = ["IEF", "TLT"]
@@ -93,6 +95,7 @@ external_context = "data/output/macro_risk_governor/input/external_context.csv"
 benchmark_symbol = "QQQ"
 attack_symbol = "TQQQ"
 vix_symbols = ["VIX", "^VIX", "VIXCLS"]
+vix3m_symbols = ["VIX3M", "^VIX3M", "VXV", "^VXV"]
 credit_pairs = ["HYG:IEF", "LQD:IEF"]
 
 [strategy_plugins.outputs]
diff --git a/docs/market-regime-control-plan.zh-CN.md b/docs/market-regime-control-plan.zh-CN.md
@@ -26,7 +26,7 @@
 - `crisis_response_shadow`
   负责硬危机防守。`true_crisis` 和泡沫脆弱性触发后，统一插件输出 `risk_off` / `defend`，仓位目标交给策略侧 opt-in 执行。
 - `macro_risk_governor`
-  负责宏观降杠杆。它看价格趋势、实现波动、VIX、信用相对压力和可选金融压力字段，输出 `risk_reduced` 或 `risk_off`。Fear & Greed、put/call、safe-haven demand 和五角大楼比萨指数只作为 watch-only 证据，先用于通知和回测观察。
+  负责宏观降杠杆。它看价格趋势、实现波动、VIX、信用相对压力和可选金融压力字段，输出 `risk_reduced` 或 `risk_off`。Fear & Greed、put/call、safe-haven demand、VVIX、SKEW、MOVE、收益率曲线、美元压力、市场宽度、AAII/NAAIM 和五角大楼比萨指数只作为 watch-only 证据，先用于通知和回测观察。
 - `taco_rebound_shadow`
   负责 TQQQ 事件反弹通知。它输出人工复核通知和本地 veto 线索，不直接提高仓位。
 
@@ -80,6 +80,12 @@
 
 SOXL/SOXX 不出现在 `market_regime_control` 的策略级消费 registry 中；它通过 `market_regime_notification` 接收通用通知，避免配置误用把通知信号升级成自动调仓。
 
+当前观察指标分层：
+
+- 已可执行打分：价格趋势、63/252 日回撤、实现波动、VIX 水平/尖峰、信用 ETF 相对压力、高收益 OAS、金融压力指数。
+- 已接入 watch-only：五角大楼比萨指数、Fear & Greed、put/call、safe-haven demand、VIX/VIX3M 期限结构、VVIX、SKEW、MOVE、IG OAS、资金压力利差、10Y-2Y/10Y-3M 曲线、DXY 21 日压力、50/200 日市场宽度、新高新低、涨跌线回撤、AAII bearish-bullish spread、NAAIM exposure。
+- 未进入自动仓位：所有 watch-only 指标。它们只用于通知、证据归档和后续历史回测。
+
 ## 版本管理
 
 当前对外契约是：
diff --git a/src/quant_strategy_plugins/macro_risk_governor_plugin.py b/src/quant_strategy_plugins/macro_risk_governor_plugin.py
@@ -18,6 +18,7 @@
 DEFAULT_BENCHMARK_SYMBOL = "QQQ"
 DEFAULT_ATTACK_SYMBOL = "TQQQ"
 DEFAULT_VIX_SYMBOLS = ("VIX", "^VIX", "VIXCLS")
+DEFAULT_VIX3M_SYMBOLS = ("VIX3M", "^VIX3M", "VXV", "^VXV")
 DEFAULT_CREDIT_PAIRS = (("HYG", "IEF"), ("LQD", "IEF"))
 DEFAULT_OUTPUT_DIR = "data/output/macro_risk_governor"
 DEFAULT_MAX_PRICE_AGE_DAYS = 4
@@ -179,6 +180,35 @@ def _add_check(
     }
 
 
+def _add_external_watch_check(
+    checks: dict[str, dict[str, Any]],
+    external_row: pd.Series,
+    name: str,
+    aliases: Sequence[str],
+    *,
+    threshold: float,
+    direction: str,
+    weight: float = 1.0,
+) -> float | None:
+    value = _external_float(external_row, *aliases)
+    if direction == "lte":
+        active = value is not None and value <= float(threshold)
+    elif direction == "gte":
+        active = value is not None and value >= float(threshold)
+    else:
+        raise ValueError(f"unsupported watch direction: {direction!r}")
+    _add_check(
+        checks,
+        name,
+        active,
+        weight=float(weight),
+        value=value,
+        threshold=float(threshold),
+        actionable=False,
+    )
+    return value
+
+
 def _score_checks(checks: Mapping[str, Mapping[str, Any]], *, actionable_only: bool) -> float:
     score = 0.0
     for check in checks.values():
@@ -238,6 +268,7 @@ def build_macro_risk_governor_signal(
     benchmark_symbol: str = DEFAULT_BENCHMARK_SYMBOL,
     attack_symbol: str = DEFAULT_ATTACK_SYMBOL,
     vix_symbols: Sequence[str] = DEFAULT_VIX_SYMBOLS,
+    vix3m_symbols: Sequence[str] = DEFAULT_VIX3M_SYMBOLS,
     credit_pairs: Sequence[tuple[str, str]] = DEFAULT_CREDIT_PAIRS,
     max_price_age_days: int = DEFAULT_MAX_PRICE_AGE_DAYS,
     max_external_context_age_days: int = DEFAULT_MAX_EXTERNAL_CONTEXT_AGE_DAYS,
@@ -261,6 +292,21 @@ def build_macro_risk_governor_signal(
     fear_greed_extreme_fear_level: float = 25.0,
     put_call_watch_level: float = 1.20,
     safe_haven_demand_watch_level: float = 1.0,
+    vix_term_structure_watch_level: float = 1.0,
+    vvix_watch_level: float = 110.0,
+    skew_watch_level: float = 150.0,
+    move_watch_level: float = 130.0,
+    ig_oas_watch_level: float = 2.0,
+    ig_oas_delta_threshold: float = 0.5,
+    funding_stress_watch_level: float = 0.5,
+    yield_curve_inversion_watch_level: float = -0.50,
+    dollar_stress_return_threshold: float = 0.03,
+    pct_above_200d_watch_level: float = 0.35,
+    pct_above_50d_watch_level: float = 0.30,
+    new_high_new_low_spread_watch_level: float = -0.10,
+    advance_decline_drawdown_watch_level: float = -0.10,
+    aaii_bear_bull_spread_watch_level: float = 0.25,
+    naaim_exposure_watch_level: float = 40.0,
     watch_score_threshold: float = 3.0,
     delever_score_threshold: float = 5.0,
     crisis_score_threshold: float = 7.0,
@@ -345,6 +391,8 @@ def build_macro_risk_governor_signal(
     vix_symbol = _first_available_symbol(close, vix_symbols)
     vix_level = None
     vix_spike = None
+    vix3m_level = None
+    vix_term_structure = None
     if vix_symbol is not None:
         vix = pd.to_numeric(close[vix_symbol], errors="coerce")
         vix_level = _as_float(vix.loc[signal_date])
@@ -355,6 +403,21 @@ def build_macro_risk_governor_signal(
         vix_spike = _external_float(external_row, "vix_5d_change", "vix_spike_5d")
         if vix_level is not None:
             evidence["vix_symbol"] = "external_context"
+    vix3m_symbol = _first_available_symbol(close, vix3m_symbols)
+    if vix3m_symbol is not None:
+        vix3m = pd.to_numeric(close[vix3m_symbol], errors="coerce")
+        vix3m_level = _as_float(vix3m.loc[signal_date])
+    else:
+        vix3m_level = _external_float(external_row, "vix3m", "vix_3m", "vix3m_level", "vxv", "vxv_level")
+    vix_term_structure = _external_float(
+        external_row,
+        "vix_term_structure",
+        "vix_vix3m_ratio",
+        "vix3m_ratio",
+        "vix_to_vix3m",
+    )
+    if vix_term_structure is None and vix_level is not None and vix3m_level is not None and vix3m_level > 0:
+        vix_term_structure = vix_level / vix3m_level
     _add_check(
         checks,
         "vix_watch_level",
@@ -379,7 +442,23 @@ def build_macro_risk_governor_signal(
         value=vix_spike,
         threshold=float(vix_spike_threshold),
     )
-    evidence["metrics"].update({"vix_level": vix_level, "vix_spike": vix_spike})
+    _add_check(
+        checks,
+        "vix_term_structure_inverted_watch",
+        vix_term_structure is not None and vix_term_structure >= float(vix_term_structure_watch_level),
+        weight=1.0,
+        value=vix_term_structure,
+        threshold=float(vix_term_structure_watch_level),
+        actionable=False,
+    )
+    evidence["metrics"].update(
+        {
+            "vix_level": vix_level,
+            "vix_spike": vix_spike,
+            "vix3m_level": vix3m_level,
+            "vix_term_structure": vix_term_structure,
+        }
+    )
 
     credit_returns: dict[str, float | None] = {}
     credit_context_available = False
@@ -498,6 +577,175 @@ def build_macro_risk_governor_signal(
         threshold=float(safe_haven_demand_watch_level),
         actionable=False,
     )
+    vvix = _add_external_watch_check(
+        checks,
+        external_row,
+        "vvix_high_watch",
+        ("vvix", "vvix_index", "cboe_vvix"),
+        threshold=float(vvix_watch_level),
+        direction="gte",
+    )
+    skew = _add_external_watch_check(
+        checks,
+        external_row,
+        "skew_high_watch",
+        ("skew", "skew_index", "cboe_skew"),
+        threshold=float(skew_watch_level),
+        direction="gte",
+    )
+    move = _add_external_watch_check(
+        checks,
+        external_row,
+        "move_high_watch",
+        ("move", "move_index", "ice_bofaml_move", "bond_volatility_index"),
+        threshold=float(move_watch_level),
+        direction="gte",
+    )
+    ig_oas = _add_external_watch_check(
+        checks,
+        external_row,
+        "ig_oas_watch_level",
+        ("ig_oas", "investment_grade_oas", "bamLC0A0CM", "bam_lc0a0cm"),
+        threshold=float(ig_oas_watch_level),
+        direction="gte",
+        weight=1.0,
+    )
+    ig_oas_delta = _external_float(external_row, "ig_oas_delta_63d", "investment_grade_oas_delta_63d")
+    if ig_oas_delta is None:
+        ig_oas_delta = _external_delta(
+            external_context,
+            signal_date,
+            ("ig_oas", "investment_grade_oas", "bamLC0A0CM", "bam_lc0a0cm"),
+            int(hy_oas_delta_lookback_days),
+        )
+    _add_check(
+        checks,
+        "ig_oas_widening_watch",
+        ig_oas_delta is not None and ig_oas_delta >= float(ig_oas_delta_threshold),
+        weight=1.0,
+        value=ig_oas_delta,
+        threshold=float(ig_oas_delta_threshold),
+        actionable=False,
+    )
+    funding_stress = _add_external_watch_check(
+        checks,
+        external_row,
+        "funding_stress_watch",
+        (
+            "ted_spread",
+            "libor_ois_spread",
+            "sofr_ois_spread",
+            "fra_ois_spread",
+            "funding_stress",
+            "funding_stress_index",
+        ),
+        threshold=float(funding_stress_watch_level),
+        direction="gte",
+    )
+    yield_curve_10y2y = _external_float(
+        external_row,
+        "yield_curve_10y2y",
+        "10y2y",
+        "t10y2y",
+        "us10y2y",
+        "treasury_10y2y",
+    )
+    yield_curve_10y3m = _external_float(
+        external_row,
+        "yield_curve_10y3m",
+        "10y3m",
+        "t10y3m",
+        "us10y3m",
+        "treasury_10y3m",
+    )
+    yield_curve_min = min(
+        (value for value in (yield_curve_10y2y, yield_curve_10y3m) if value is not None),
+        default=None,
+    )
+    _add_check(
+        checks,
+        "yield_curve_inversion_watch",
+        yield_curve_min is not None and yield_curve_min <= float(yield_curve_inversion_watch_level),
+        weight=1.0,
+        value=yield_curve_min,
+        threshold=float(yield_curve_inversion_watch_level),
+        actionable=False,
+    )
+    dollar_return_21d = _add_external_watch_check(
+        checks,
+        external_row,
+        "dollar_stress_watch",
+        ("dxy_return_21d", "dollar_index_return_21d", "usd_return_21d", "dxy_21d_return"),
+        threshold=float(dollar_stress_return_threshold),
+        direction="gte",
+    )
+    pct_above_200d = _add_external_watch_check(
+        checks,
+        external_row,
+        "market_breadth_pct_above_200d_watch",
+        (
+            "pct_above_200d",
+            "percent_above_200d",
+            "spx_pct_above_200d",
+            "nasdaq_100_pct_above_200d",
+        ),
+        threshold=float(pct_above_200d_watch_level),
+        direction="lte",
+    )
+    pct_above_50d = _add_external_watch_check(
+        checks,
+        external_row,
+        "market_breadth_pct_above_50d_watch",
+        (
+            "pct_above_50d",
+            "percent_above_50d",
+            "spx_pct_above_50d",
+            "nasdaq_100_pct_above_50d",
+        ),
+        threshold=float(pct_above_50d_watch_level),
+        direction="lte",
+    )
+    new_high_new_low_spread = _add_external_watch_check(
+        checks,
+        external_row,
+        "new_high_new_low_spread_watch",
+        (
+            "new_high_new_low_spread",
+            "nh_nl_spread",
+            "new_highs_new_lows_spread",
+            "new_high_new_low_ratio",
+        ),
+        threshold=float(new_high_new_low_spread_watch_level),
+        direction="lte",
+    )
+    advance_decline_drawdown = _add_external_watch_check(
+        checks,
+        external_row,
+        "advance_decline_drawdown_watch",
+        (
+            "advance_decline_drawdown",
+            "ad_line_drawdown",
+            "advance_decline_line_drawdown",
+        ),
+        threshold=float(advance_decline_drawdown_watch_level),
+        direction="lte",
+    )
+    aaii_bear_bull_spread = _add_external_watch_check(
+        checks,
+        external_row,
+        "aaii_bear_bull_spread_watch",
+        ("aaii_bear_bull_spread", "aaii_bears_minus_bulls", "aaii_bearish_bullish_spread"),
+        threshold=float(aaii_bear_bull_spread_watch_level),
+        direction="gte",
+    )
+    naaim_exposure = _add_external_watch_check(
+        checks,
+        external_row,
+        "naaim_exposure_low_watch",
+        ("naaim_exposure", "naaim_exposure_index", "naaim_manager_exposure"),
+        threshold=float(naaim_exposure_watch_level),
+        direction="lte",
+    )
     realized_vol_confirmed_for_action = None
     realized_vol_check = checks.get("benchmark_realized_volatility_high")
     if realized_vol_check is not None:
@@ -529,6 +777,22 @@ def build_macro_risk_governor_signal(
             "fear_greed_index": fear_greed_index,
             "put_call_ratio": put_call_ratio,
             "safe_haven_demand": safe_haven_demand,
+            "vvix": vvix,
+            "skew": skew,
+            "move": move,
+            "ig_oas": ig_oas,
+            "ig_oas_delta_63d": ig_oas_delta,
+            "funding_stress": funding_stress,
+            "yield_curve_10y2y": yield_curve_10y2y,
+            "yield_curve_10y3m": yield_curve_10y3m,
+            "yield_curve_min": yield_curve_min,
+            "dollar_return_21d": dollar_return_21d,
+            "pct_above_200d": pct_above_200d,
+            "pct_above_50d": pct_above_50d,
+            "new_high_new_low_spread": new_high_new_low_spread,
+            "advance_decline_drawdown": advance_decline_drawdown,
+            "aaii_bear_bull_spread": aaii_bear_bull_spread,
+            "naaim_exposure": naaim_exposure,
             "benchmark_realized_volatility_requires_confirmation": bool(realized_vol_requires_confirmation),
             "benchmark_realized_volatility_confirmed_for_action": realized_vol_confirmed_for_action,
         }
diff --git a/src/quant_strategy_plugins/strategy_plugin_runner.py b/src/quant_strategy_plugins/strategy_plugin_runner.py
diff --git a/tests/test_macro_risk_governor_plugin.py b/tests/test_macro_risk_governor_plugin.py
