hamuna-quant-cli 0.1.0.dev93__py3-none-any.whl

hamuna_quant_cli/akquant_runner.py

@@ -0,0 +1,620 @@
+"""ADR-0040 Phase B — akquant runner 单入口 (v2 自有版本, B7).
+
+来源: 原仓根 `hamuna_quant_cli/references/akquant_runner.py`.
+本文件是 wholesale copy, 算法/CFG 不变. 迁移原因: v2 skill 独立分发.
+唯一改动: 所有 `from references.X` → `from .X` (同包 import).
+
+公开 API:
+  run_akquant_backtest(strategy_path, cfg) -> dict
+
+strategy_path: 含 `akquant.Strategy` 子类的 .py 文件路径 (on_bar API, NOT QMT handlebar).
+cfg: 同 `hamuna_quant_cli run` 用的 CONFIG dict (backtest_start/end, pool, init_capital, ...).
+
+返回: hamuna `backtest_result.json` 形状 dict (13 顶层 key, 15 metrics; 见
+  strategy_cli/runtime/driver.py:113-128 + references/backtest-result.md).
+
+锁定 akquant 0.3.x schema (bench_20260813_201349.json). 升级前先跑
+references/_test_akquant_parity.py 验证 5 strategy 容差在阈值内.
+
+失败模式:
+  FileNotFoundError: 数据集缺失 (universe 在 prebuilt 不存在, 或 start/end 在 window 外)
+  ImportError: akquant 未安装 (pip install akquant)
+  ValueError: cfg 缺必需 key / akquant.run_backtest 报参数错
+
+Ponytail ceiling: 当前只支持日线 + 单标 / 命名池.
+  5m/tick 走 v1 driver 路径 (`strategy_cli run`).
+  多 symbol 走循环跑 (R3 mitigation, 但 runner 入口暂不阻断 — 等 _probe_multi_symbol 测).
+"""
+from __future__ import annotations
+
+import importlib.util
+import inspect
+import os
+import sys
+import warnings
+from pathlib import Path
+from typing import Any
+
+
+# ---- strategy loader (沿 driver._load_strategy 模式, 但导 Strategy 类不导 handlebar) ----
+def _load_akquant_strategy(strategy_path: str) -> Any:
+    """加载 strategy .py, 提取第一个 akquant.Strategy 子类.
+
+    不复用 driver._load_strategy — 那是 QMT 路径 (mod.init / mod.handlebar / mod.CONFIG),
+    akquant 是类化 strategy (class MyStrategy(akquant.Strategy): on_bar(bar)).
+
+    ad-hoc 加载: spec_from_file_location, sys.path.insert 父目录 (兼容同目录 helper).
+    """
+    p = Path(strategy_path).resolve()
+    parent = str(p.parent)
+    if parent not in sys.path:
+        sys.path.insert(0, parent)
+    spec = importlib.util.spec_from_file_location('_hamuna_akquant_strat', strategy_path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f'cannot load strategy at {strategy_path}')
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules['_hamuna_akquant_strat'] = mod
+    spec.loader.exec_module(mod)
+
+    # 找 akquant.Strategy 子类 (用户可能放 class MyStrategy(akquant.Strategy) 或 (Strategy))
+    try:
+        import akquant
+    except ImportError as e:
+        raise ImportError(f'akquant 未安装: {e}. pip install akquant>=0.3.41,<0.4') from e
+    base_cls = akquant.Strategy
+
+    found = None
+    for name in dir(mod):
+        obj = getattr(mod, name)
+        if isinstance(obj, type) and issubclass(obj, base_cls) and obj is not base_cls:
+            found = obj
+            break
+    if found is None:
+        raise ValueError(
+            f'{strategy_path} 未找到 akquant.Strategy 子类 (期望 `class Xxx(akquant.Strategy): on_bar(...)`)')
+    return found
+
+
+# ---- main entry ----
+def run_akquant_backtest(strategy_path: str, cfg: dict) -> dict:
+    """跑 akquant 回测, 返回 hamuna `backtest_result.json` 形状 dict.
+
+    0.3.x 加速: 见 SKILL.md 顶部 / engine-and-data.md §6 — runner 自动接
+    history_depth / start_time / lot_size / commission_policy, 用户 strategy 不用改.
+    """
+    import akquant
+
+    # cfg 必需 keys
+    for k in ('backtest_start', 'backtest_end'):
+        if k not in cfg:
+            raise ValueError(f'cfg 缺必需 key: {k}')
+
+    # universe 展开 (与 schema_adapter._cfg_universe 一致)
+    from .akquant_data_adapter import load_prebuilt_to_akquant  # B4
+    from .akquant_schema_adapter import to_hamuna_result, HAMUNA_METRICS_15, normalize_symbol  # B1
+    universe = [normalize_symbol(s) for s in _universe_from_cfg(cfg)]  # 裸码 → 带后缀 (bundle stockCode 形态)
+    if not universe:
+        raise ValueError(f'cfg.universe / cfg.pool 为空: {cfg.get("pool")}')
+    if len(universe) > 1:
+        # R3 mitigation: akquant 多 symbol 实测前先 warn + 跑循环. parity test 会实测.
+        # 暂时让 akquant.run_backtest 自己决定 (实测接受 multi-symbol DataFrame).
+        pass
+
+    # data — Q1 兜底默认开 (cfg['price_limit_clamp']=False 可关)
+    use_clamp = bool(cfg.get('price_limit_clamp', True))
+    if use_clamp:
+        from .akquant_data_adapter import load_prebuilt_to_akquant_with_limits  # B4
+        df = load_prebuilt_to_akquant_with_limits(
+            universe, cfg['backtest_start'], cfg['backtest_end'])
+    else:
+        df = load_prebuilt_to_akquant(universe, cfg['backtest_start'], cfg['backtest_end'])
+    if df.empty:
+        raise FileNotFoundError(
+            f'未取到 bar 数据 (universe={universe}, {cfg["backtest_start"]}-{cfg["backtest_end"]})')
+
+    # symbol_names: 从 prebuilt bundle 聚合 {stockCode: stockName}, 注入 cfg
+    # 让 schema_adapter.trades 填 symbol_name (对齐 hamuna_strategy driver._lookup_symbol_name)
+    if not cfg.get('_symbol_names'):
+        cfg['_symbol_names'] = _load_symbol_names_from_bundle(df)
+
+    # strategy class
+    strat_cls = _load_akquant_strategy(strategy_path)
+
+    # ===== 0.3 架构变更 (2026-08-18 简化): compute_factors / filter_symbols 接入引擎 =====
+    # 流程: 实例化 → compute_factors (直接传 prebuilt df, 引擎不包装 BacktestContext) →
+    #       filter_symbols → 修整 df + symbols 喂 akquant.run_backtest.
+    # 老策略 (无 compute_factors / filter_symbols) 走默认 no-op, 行为不变 — 有 hasattr 检测.
+    # akquant 0.3.x 已一等支持 DataFrame/polars/pyarrow/dict 输入 — 不下沉 sub-adapter.
+    import pandas as _pd  # noqa: F401
+    try:
+        strat_inst = strat_cls()
+    except Exception as e:
+        raise RuntimeError(f"实例化策略 {strat_cls.__name__} 失败: {e}") from e
+
+    factors: dict[str, _pd.DataFrame] = {}
+    if hasattr(strat_inst, "compute_factors"):
+        try:
+            factors = strat_inst.compute_factors(df) or {}
+        except Exception as e:
+            raise RuntimeError(
+                f"compute_factors 异常: {e} (用户原话: 策略出错直接报错停止, 不走 mock 兜底)"
+            ) from e
+        if not isinstance(factors, dict):
+            raise TypeError(
+                f"compute_factors 应返 dict[str, DataFrame], 实得 {type(factors).__name__}"
+            )
+
+    filtered: list[str] = list(universe)
+    if hasattr(strat_inst, "filter_symbols"):
+        try:
+            user_filtered = strat_inst.filter_symbols(factors)
+        except Exception as e:
+            raise RuntimeError(f"filter_symbols 异常: {e}") from e
+        if not isinstance(user_filtered, (list, tuple)):
+            raise TypeError(
+                f"filter_symbols 应返 list[str], 实得 {type(user_filtered).__name__}"
+            )
+        user_filtered = [str(s) for s in user_filtered]
+        if not user_filtered:
+            warnings.warn(f"filter_symbols 返空, 退到 cfg.universe ({len(universe)} syms)")
+        else:
+            # 校验: filter_symbols 返的 sym 必须 universe 子集
+            known = set(universe)
+            bad = [s for s in user_filtered if s not in known]
+            if bad:
+                warnings.warn(
+                    f"filter_symbols 返了 universe 外的 sym {bad[:5]}{'...' if len(bad) > 5 else ''}, 已剔除"
+                )
+                user_filtered = [s for s in user_filtered if s in known]
+            filtered = user_filtered
+            print(
+                f"[v2-architecture] filter_symbols: {len(universe)} → {len(filtered)} symbols",
+                file=sys.stderr,
+            )
+
+    # 切 df 到 filtered universe (空 df 立即报错, 不让 akquant 引擎跑出空结果)
+    if filtered != universe:
+        df = df[df["symbol"].isin(filtered)] if "symbol" in df.columns else df
+        if df.empty:
+            raise ValueError(
+                f"filter_symbols 限定后 df 为空 (filtered={filtered[:5]}...)"
+            )
+        universe = filtered
+
+    # run_backtest kwargs (锁定 akquant 0.3.x schema; 见 SKILL.md 顶部 0.3 加速原语段)
+    initial_cash = float(cfg.get('init_capital', 1_000_000.0))
+    # slippage: akquant 0.3 已 deprecate bare float, 强制 dict 形态
+    # 接受 cfg['slippage']=float 或 cfg['slippage']={'type':..., 'value':...}
+    _raw_slip = cfg.get('slippage', 0.001)
+    if isinstance(_raw_slip, dict):
+        slippage_kwarg = _raw_slip
+    else:
+        slippage_kwarg = {'type': 'percent', 'value': float(_raw_slip)}
+    kwargs: dict[str, Any] = {
+        'strategy': strat_cls,
+        'data': df,
+        'symbols': universe,
+        'initial_cash': initial_cash,
+        'commission_rate': float(cfg.get('commission_rate', 0.0003)),
+        'stamp_tax_rate': float(cfg.get('stamp_tax_rate', 0.001)),
+        'min_commission': float(cfg.get('min_commission', 5.0)),
+        'slippage': slippage_kwarg,
+        'volume_limit_pct': float(cfg.get('volume_limit_pct', 0.25)),
+        't_plus_one': bool(cfg.get('t_plus_one', True)),
+        'show_progress': False,
+    }
+    # universe 注入 (Q1: 多标/横截面策略必需):
+    #   - 0.3.x 新 API: strategy 用 `universe = ListParam(default=[])` 类字段, runner 通过
+    #     `strategy_params={'universe': universe}` 注入 (引擎走 .params.universe).
+    #   - 0.2.x 旧 API: strategy `__init__(self, universe=None)`, runner 通过 kwargs 注入.
+    #     **0.3.x 严格拒收** (raise TypeError), 所以检测到旧风格时只能跳过, 让用户迁移.
+    if _strategy_accepts_universe_param(strat_cls):
+        kwargs['strategy_params'] = {'universe': universe}
+    # 不再 fallback 到 0.2 旧路径 — 见上方注释; 旧 strategy 走 0.3 必须先迁移到 ParamModel.
+
+    # ===== 0.3.x 加速原语 (自动启用, strategy 不用改) =====
+    # 1) history_depth — 推断: scan __init__ 默认值 + warmup_period + cfg['history_depth']
+    #    长窗策略 (lookback > 30) 实测 -20~40% elapsed; 短窗无害.
+    hd = _infer_history_depth(strat_cls, cfg)
+    if hd is not None and hd > 0:
+        kwargs['history_depth'] = hd
+
+    # 2) start_time / end_time — 引擎内切片, 比 Python 端 iloc 省内存且正确处理 warmup.
+    #    cfg['backtest_start'] 是 'YYYYMMDD' (legacy v1 格式), akquant 0.3 期望 ISO 'YYYY-MM-DD'.
+    #    兼容 cfg 显式 start_time/end_time (优先级更高).
+    if 'start_time' not in cfg:
+        cfg['start_time'] = _ymd_to_iso(cfg['backtest_start'])
+    if 'end_time' not in cfg:
+        cfg['end_time'] = _ymd_to_iso(cfg['backtest_end'])
+    kwargs['start_time'] = cfg['start_time']
+    kwargs['end_time'] = cfg['end_time']
+
+    # 3) lot_size — A 股默认 100 整手. 老 akquant (<0.3.30) 不接受 (会被 TypeError) → 启动期探测.
+    #    接受 cfg['lot_size']=int (统一) 或 dict (per-symbol); 默认 100.
+    ls = cfg.get('lot_size', 100)
+    if _akquant_supports_lot_size() and ls:
+        kwargs['lot_size'] = ls
+
+    # 4) commission_policy — 0.3+ 推荐 dict 形态; 若 cfg 显式给 commission_policy 优先.
+    #    否则从 commission_rate 构造成 dict (行为等价但走 0.3+ 内部 commission pipeline).
+    #    commission_rate 与 commission_policy 二选一 (0.3 strict 模式同时传会报错, 所以
+    #    构造 commission_policy 后立刻从 kwargs 里 pop commission_rate).
+    if _akquant_supports_commission_policy():
+        cp = cfg.get('commission_policy')
+        if cp is None:
+            cp = {
+                'type': 'percent',
+                'value': float(cfg.get('commission_rate', 0.0003)),
+            }
+        cfg['commission_policy'] = cp
+        kwargs.pop('commission_rate', None)
+        kwargs['commission_policy'] = cp
+    # 0.2.x 老路径: 只 commission_rate, 不动.
+
+    # 可选 kwargs (存在性探测后再传; 防老 akquant 跑 0.3 only kwargs 抛 TypeError)
+    for optional in ('analyzer_plugins', 'risk_config'):
+        if optional in cfg and _akquant_kwarg_supported(optional):
+            kwargs[optional] = cfg[optional]
+
+    akquant_r = akquant.run_backtest(**kwargs)
+
+    return to_hamuna_result(akquant_r, cfg)
+
+
+def _universe_from_cfg(cfg: dict) -> list[str]:
+    """从 cfg['pool'] 展开标的代码 list. 与 schema_adapter._cfg_universe 同语义."""
+    pool = cfg.get('pool') or cfg.get('universe') or []
+    if isinstance(pool, list):
+        return list(pool)
+    out: list[str] = []
+    for v in pool.values() if isinstance(pool, dict) else []:
+        if isinstance(v, dict):
+            codes = v.get('codes') or v.get('sub_universe') or []
+            out.extend(codes)
+        elif isinstance(v, list):
+            out.extend(v)
+    return sorted(set(out))
+
+
+def _load_symbol_names_from_bundle(df: pd.DataFrame) -> dict[str, str]:
+    """从 input df 聚合 {symbol: stockName}, 失败/缺列 → {} (trades 端 fallback None).
+
+    备选: 直读 prebuilt parquet 的 stockName 列 (data_adapter 已 drop).
+    这里走 df 自身: data_adapter._DROP_COLS 含 stockName, 但 _PRICE_LIMIT 路径
+    仍带 stockName; 若上游已 drop → 空 dict.
+    """
+    try:
+        if 'stockName' not in df.columns:
+            return {}
+        names = df.dropna(subset=['stockName']).drop_duplicates('symbol').set_index('symbol')['stockName'].to_dict()
+        return {k: str(v) for k, v in names.items() if k}
+    except Exception:  # noqa: BLE001
+        return {}
+
+
+# ---- 0.3.x 加速原语 helper (Round 1) ----
+
+# window-like 参数名启发式: __init__ 默认值取 max + warmup_period.
+# 不取 lot_size / universe / period (它们不是窗口).
+_WINDOW_PARAM_HINTS = (
+    'window', 'lookback', 'slow', 'fast', 'long', 'short',
+    'period', 'span', 'length', 'n_', '_n', 'days', 'periods',
+    'ma', 'sma', 'ema', 'rsi', 'atr', 'roc',
+)
+
+
+def _infer_history_depth(strat_cls: type, cfg: dict) -> int | None:
+    """从 strategy.__init__ 默认值 + warmup_period + cfg['history_depth'] 推断 history_depth.
+
+    返回 None = 留空, akquant 走引擎默认 (0, 不预分配).
+    返回 int > 0 = 预分配 Rust history buffer, 长窗策略 -20~40% elapsed.
+
+    启发式:
+      1) cfg['history_depth'] 显式值 (最高优先级)
+      2) strategy.__init__ 默认值里匹配 window 关键字 + 数值 → 取 max
+      3) 类属性 warmup_period
+      4) 加 10 padding 防 off-by-one (rolling-N 在第 N+1 bar 才完整)
+    """
+    explicit = cfg.get('history_depth')
+    if explicit is not None:
+        try:
+            return max(0, int(explicit))
+        except (TypeError, ValueError):
+            pass  # 显式值非法 → 走推断
+
+    try:
+        sig = inspect.signature(strat_cls.__init__)
+    except (TypeError, ValueError):
+        sig = None
+
+    candidates: list[int] = []
+    if sig is not None:
+        for pname, param in sig.parameters.items():
+            if param.default is inspect.Parameter.empty:
+                continue
+            v = param.default
+            # 跳过 None / bool / 非数值
+            if not isinstance(v, (int, float)):
+                continue
+            if isinstance(v, bool):
+                continue
+            iv = int(v)
+            if iv <= 0:
+                continue
+            # 启发式: 名字命中 window-like 才采纳 (避免 lot_size=100 / universe_size=500 误判)
+            plower = pname.lower()
+            if any(h in plower for h in _WINDOW_PARAM_HINTS):
+                candidates.append(iv)
+
+    # 类属性 warmup_period
+    wp = getattr(strat_cls, 'warmup_period', None)
+    if isinstance(wp, (int, float)) and not isinstance(wp, bool) and wp > 0:
+        candidates.append(int(wp))
+
+    if not candidates:
+        return None
+    return max(candidates) + 10
+
+
+def _ymd_to_iso(ymd: str) -> str:
+    """'YYYYMMDD' (v1 cfg 格式) → 'YYYY-MM-DD' (akquant 0.3 start_time 格式).
+
+    已是 ISO 形态直接透传, 避免破坏既有 cfg['start_time'] 用法.
+    """
+    s = str(ymd).strip()
+    if len(s) == 8 and s.isdigit():
+        return f'{s[:4]}-{s[4:6]}-{s[6:8]}'
+    return s
+
+
+# akquant 版本探测: 启动期一次性 inspect 签名, 防 <0.3.30 / 0.3.x 行为差异.
+_AKQUANT_SUPPORT_CACHE: dict[str, bool] = {}
+
+
+def _akquant_kwarg_supported(name: str) -> bool:
+    """查 akquant.run_backtest 是否接受给定 kwarg (避免老版本抛 TypeError)."""
+    if name in _AKQUANT_SUPPORT_CACHE:
+        return _AKQUANT_SUPPORT_CACHE[name]
+    try:
+        import akquant
+        sig = inspect.signature(akquant.run_backtest)
+        ok = name in sig.parameters
+    except Exception:  # noqa: BLE001
+        ok = False
+    _AKQUANT_SUPPORT_CACHE[name] = ok
+    return ok
+
+
+def _akquant_supports_lot_size() -> bool:
+    return _akquant_kwarg_supported('lot_size')
+
+
+def _akquant_supports_commission_policy() -> bool:
+    return _akquant_kwarg_supported('commission_policy')
+
+
+def _strategy_accepts_universe_param(strat_cls: type) -> bool:
+    """检测 strategy 是否声明 `universe` 为 0.3.x 的 ParamModel 字段.
+
+    0.3.x: `universe: list = ListParam(default=[])` 类字段, 通过 strategy_params 注入.
+    0.2.x: `__init__(self, universe=None)` — 0.3.x 严格拒收 (TypeError), 这里返 False 跳过.
+
+    ponytail: 仅检测 'universe' 字段. 其它字段 (lots/fast/slow 等) 走 ParamModel 自身规则,
+    runner 不替用户策略注入; grid/WFO 子命令会单独处理.
+    """
+    try:
+        # pydantic-based ParamModel: 实例化后 inst.params.<name> 存在
+        with warnings.catch_warnings():
+            warnings.simplefilter('ignore')  # 0.3.x 对老 __init__ 形参的 UserWarning
+            inst = strat_cls()
+        if not hasattr(inst, 'params'):
+            return False
+        params_obj = getattr(inst, 'params')
+        # pydantic v2: model_fields 是 dict[str, FieldInfo]
+        fields = getattr(params_obj, 'model_fields', None)
+        if fields and 'universe' in fields:
+            return True
+        # pydantic v1 fallback
+        fields_v1 = getattr(params_obj, '__fields__', None)
+        if fields_v1 and 'universe' in fields_v1:
+            return True
+        return False
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _selfcheck() -> None:
+    """端到端冒烟: 写 tmpfile 含 akquant.Strategy 子类 → 跑最小 backtest.
+
+    失败模式:
+      akquant 未装 → SKIP.
+      数据缺 (no prebuilt) → SKIP, 不 fail.
+      数据有 → 跑通, 验 15 metrics key + Q1 兜底已启用.
+    """
+    if os.environ.get('AKQUANT_AVAILABLE', '1') != '1':
+        print('SKIP: akquant self-check (env AKQUANT_AVAILABLE=0)')
+        return
+    try:
+        import akquant  # noqa: F401
+    except ImportError:
+        print('SKIP: akquant not installed')
+        return
+
+    import tempfile
+    with tempfile.TemporaryDirectory() as tmp:
+        old = os.environ.get('HAMUNA_STRATEGIES_ROOT')
+        os.environ['HAMUNA_STRATEGIES_ROOT'] = tmp
+        try:
+            strat_path = Path(tmp) / 'ma_strategy.py'
+            strat_path.write_text('''
+from akquant import Strategy
+
+class MACross(Strategy):
+    warmup_period = 5
+    def __init__(self, fast=3, slow=5):
+        self.fast = fast
+        self.slow = slow
+    def on_bar(self, bar):
+        closes = self.get_history(self.slow, bar.symbol, "close")
+        if len(closes) < self.slow:
+            return
+        fast_ma = float(sum(closes[-self.fast:]) / self.fast)
+        slow_ma = float(sum(closes[-self.slow:]) / self.slow)
+        pos = self.get_position(bar.symbol)
+        if fast_ma > slow_ma and pos == 0:
+            self.buy(bar.symbol, 100)
+        elif fast_ma < slow_ma and pos > 0:
+            self.sell(bar.symbol, pos)
+''', encoding='utf-8')
+
+            cfg = {
+                'backtest_start': '20240701',
+                'backtest_end': '20241231',
+                'pool': {'a': {'codes': ['600000.SH']}},
+                'init_capital': 100_000.0,
+            }
+            try:
+                r = run_akquant_backtest(strat_path, cfg)
+            except FileNotFoundError:
+                print('SKIP: prebuilt dataset 缺失 (无 600000.SH 数据); runner 入口已通, 装数据后可跑')
+                return
+            except NotImplementedError as e:
+                print(f'SKIP: {e}')
+                return
+
+            from .akquant_schema_adapter import HAMUNA_METRICS_15  # B1
+            assert set(r['metrics'].keys()) == HAMUNA_METRICS_15, (
+                f'15 metrics key 不齐: 差 {set(r["metrics"].keys()) ^ HAMUNA_METRICS_15}')
+            n_eq = len(r['equity_curve'])
+            print(f'OK: akquant_runner 端到端通 (15 metrics, trades={len(r["trades"])}, eq_points={n_eq})')
+
+            # Q1 regression: 0.3.x 新 API — 收 `universe` ParamModel 字段的策略, runner 必须
+            # 把 universe 注入 strategy_params (否则 on_start 空订阅 → 0 trades, 高胜率
+            # 策略实际踩过). 0.3.x 严格拒收老 __init__ 形参, 所以检测 → 注入路径改了.
+            # monkeypatch akquant.run_backtest 捕获 kwargs, 断言 strategy_params 在.
+            import akquant as _akq
+            captured: dict = {}
+            _orig_run = _akq.run_backtest
+
+            def _capture(**kw):
+                captured.update(kw)
+                # 真实跑 (返回真 BacktestResult), 让 to_hamuna_result 也走通
+                return _orig_run(**kw)
+
+            _akq.run_backtest = _capture
+            try:
+                _ = run_akquant_backtest(strat_path, cfg)   # MACross 不收 universe
+                # MACross 不收 universe → 不注入 strategy_params (0.2.x 旧路径已被 0.3 移除)
+                assert 'strategy_params' not in captured, (
+                    f'MACross 不应注入 strategy_params: {captured.get("strategy_params")}')
+            finally:
+                _akq.run_backtest = _orig_run
+            captured.clear()
+            _akq.run_backtest = _capture
+            try:
+                strat3 = Path(tmp) / 'uses_universe.py'
+                strat3.write_text('''
+from akquant import Strategy, ListParam
+
+class UsesUniverse(Strategy):
+    """0.3.x 新 ParamModel 风格: universe 字段声明为 ListParam."""
+    universe: list = ListParam(default=[])
+    def on_bar(self, bar):
+        pass
+''', encoding='utf-8')
+                _ = run_akquant_backtest(strat3, cfg)      # UsesUniverse 收 universe
+                assert captured.get('strategy_params') == {'universe': ['600000.SH']}, (
+                    f'UsesUniverse (0.3 ParamModel) 注入错: {captured.get("strategy_params")}')
+            finally:
+                _akq.run_backtest = _orig_run
+            # 0.2.x 旧 __init__ 风格 → 检测返 False, runner 跳过注入 (0.3 strict 拒收).
+            # 加载临时类 (用 _load_akquant_strategy, 沿用 selfcheck 已写好的 tmpfile).
+            _macross_cls = _load_akquant_strategy(strat_path)
+            _uses_cls = _load_akquant_strategy(strat3)
+            assert not _strategy_accepts_universe_param(_macross_cls), (
+                'MACross (无 universe 字段) 应 _strategy_accepts_universe_param=False')
+            assert _strategy_accepts_universe_param(_uses_cls), (
+                'UsesUniverse (ListParam) 应 _strategy_accepts_universe_param=True')
+            print(f'OK: universe 注入路径生效 (0.3 ParamModel → strategy_params; 旧 __init__ 风格跳过)')
+
+            # ===== Round 1: history_depth 推断 + 0.3 kwarg 探测 ——
+            # 1) history_depth 推断: 用 MACross(fast=3, slow=5, ...), 预期 max(3,5)+10=15
+            #    (注意: 这里 fast=3 / slow=5 是 selfcheck 里写死的, 不是 user 默认)
+            hd = _infer_history_depth(_macross_cls, cfg)
+            assert hd == 15, f'history_depth 推断应 15 (max(fast=3, slow=5) + 10), 实际 {hd}'
+            # 类属性 warmup_period 单独存在时也应采纳
+            class _WarmupOnly(akquant.Strategy):
+                warmup_period = 42
+                def on_bar(self, bar): pass
+            assert _infer_history_depth(_WarmupOnly, cfg) == 52, 'warmup_period 单独推断失败'
+            # cfg 显式覆盖
+            assert _infer_history_depth(_macross_cls, {**cfg, 'history_depth': 80}) == 80, (
+                'cfg[history_depth] 显式覆盖失败')
+            # 非法值 → 走推断
+            assert _infer_history_depth(_macross_cls, {**cfg, 'history_depth': 'xxx'}) == 15, (
+                '非法 history_depth 应 fallthrough 到推断')
+            # 无窗口 / 无 warmup → None (留空, 走引擎默认)
+            class _Empty(akquant.Strategy):
+                def __init__(self, foo='bar', flag=True):
+                    self.foo = foo
+                def on_bar(self, bar): pass
+            assert _infer_history_depth(_Empty, cfg) is None, '无窗口应 None'
+            print(f'OK: history_depth 推断 (max+10 padding + warmup + cfg override + fallthrough)')
+
+            # 2) _ymd_to_iso: legacy YYYYMMDD → ISO, 已 ISO → 透传
+            assert _ymd_to_iso('20240701') == '2024-07-01'
+            assert _ymd_to_iso('2024-07-01') == '2024-07-01'  # 透传
+            assert _ymd_to_iso('  20240701  ') == '2024-07-01'  # 容错 trim
+            assert _ymd_to_iso('') == ''
+            print('OK: _ymd_to_iso 边界 (YYYYMMDD/ISO/trim/empty)')
+
+            # 3) akquant 版本探测: lot_size / commission_policy 在 0.3.41 存在; <0.3.30 不存在.
+            #    selfcheck 跑在 0.3.41 环境下, 期望 True; 若用户跑 <0.3.30, 仍可加载 (False 走老路径).
+            assert _akquant_supports_lot_size(), (
+                f'当前 akquant={akquant.__version__} 不支持 lot_size; 升 >=0.3.41 拿到自动整手约束')
+            assert _akquant_supports_commission_policy(), (
+                f'当前 akquant={akquant.__version__} 不支持 commission_policy; 升 >=0.3 拿推荐写法')
+            assert _akquant_kwarg_supported('history_depth'), 'history_depth 应是 0.3 标配'
+            assert not _akquant_kwarg_supported('nonexistent_kwarg_xxx'), '不存在的 kwarg 应 False'
+            print(f'OK: akquant {akquant.__version__} 0.3 加速 kwarg 探测 (lot_size/commission_policy/history_depth)')
+
+            # 4) 端到端: 跑一次真 backtest, 验 kwargs 真传过去且 metrics 不回归.
+            #    monkeypatch 拿 kwargs, 验 history_depth/start_time/end_time 在 (0.3+).
+            captured2: dict = {}
+            _orig2 = _akq.run_backtest
+            def _cap2(**kw):
+                captured2.update(kw)
+                return _orig2(**kw)
+            _akq.run_backtest = _cap2
+            try:
+                _ = run_akquant_backtest(strat_path, cfg)
+            finally:
+                _akq.run_backtest = _orig2
+            # history_depth 应被自动算出 (≥15, 视 MACross 默认值)
+            assert captured2.get('history_depth', 0) >= 15, (
+                f'history_depth 未自动传: {captured2.get("history_depth")}')
+            # start_time / end_time 应是 ISO 格式
+            assert captured2.get('start_time') == '2024-07-01', (
+                f'start_time ISO 转换错: {captured2.get("start_time")}')
+            assert captured2.get('end_time') == '2024-12-31', (
+                f'end_time ISO 转换错: {captured2.get("end_time")}')
+            # commission_policy 应替代 commission_rate
+            assert 'commission_policy' in captured2, (
+                f'0.3+ commission_policy 未传: keys={list(captured2.keys())[:15]}...')
+            assert 'commission_rate' not in captured2, (
+                'commission_policy 与 commission_rate 不应同时传')
+            # lot_size 应传 100 (A 股整手)
+            assert captured2.get('lot_size') == 100, (
+                f'lot_size 应默认 100, 实际 {captured2.get("lot_size")}')
+            print(f'OK: 端到端 kwargs 注入 (history_depth={captured2["history_depth"]}, '
+                  f'start={captured2["start_time"]}, end={captured2["end_time"]}, '
+                  f'lot_size={captured2["lot_size"]}, commission_policy={captured2["commission_policy"]})')
+        finally:
+            if old is None:
+                os.environ.pop('HAMUNA_STRATEGIES_ROOT', None)
+            else:
+                os.environ['HAMUNA_STRATEGIES_ROOT'] = old
+
+
+if __name__ == '__main__':
+    _selfcheck()