hamuna-quant-cli 0.1.1__tar.gz → 0.1.2__tar.gz

{hamuna_quant_cli-0.1.1 → hamuna_quant_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hamuna-quant-cli
-Version: 0.1.1
+Version: 0.1.2
 Summary: Hamuna A 股回测 + 实盘统一 CLI (akquant 0.3.x). 替代 v1 自建 driver + QMT-style 策略规范.
 Author-email: Hamuna Team <team@hamuna.example>
 License: MIT

{hamuna_quant_cli-0.1.1 → hamuna_quant_cli-0.1.2}/hamuna_quant_cli/__init__.py

@@ -12,6 +12,4 @@ server (13-key metrics schema). 全部走 akquant 0.3.x 引擎.
 """
 from __future__ import annotations
 
-# 版本号由 scripts/bump_version.py 每次 build 自动更新 (基于 git 提交数).
-# 格式: 0.1.0.dev<git提交数> (PEP 440). 手动改这里会被下一次 build 覆盖.
-__version__ = "0.1.1"
+__version__ = "0.1.2"

{hamuna_quant_cli-0.1.1 → hamuna_quant_cli-0.1.2}/hamuna_quant_cli/__main__.py

@@ -69,6 +69,35 @@ def cmd_run(args) -> int:
                   f"用 --skip-discipline 显式跳过", file=sys.stderr)
             return 3
 
+    # --params (params.json 固定 schema) → strategy_params 段注入 cfg,
+    # akquant_runner 展开注入 engine kwargs. 与 `live run --params` 同源:
+    # 同一份 params.json 驱动回测 + 实盘, 参数约定不再分裂 (Round 18.13).
+    if getattr(args, "params", None):
+        params_path = Path(args.params)
+        if not params_path.exists():
+            print(f"--params 不存在: {args.params}", file=sys.stderr)
+            return 2
+        import json as _json
+        try:
+            params_doc = _json.loads(params_path.read_text(encoding="utf-8"))
+        except _json.JSONDecodeError as e:
+            print(f"--params 解析失败: {args.params} ({e})", file=sys.stderr)
+            return 2
+        sp = (params_doc or {}).get("strategy_params")
+        if isinstance(sp, dict):
+            cfg["strategy_params"] = sp
+        else:
+            print("[warn] --params 无 strategy_params 段, 忽略 (仅接受固定 schema)", file=sys.stderr)
+        # Round 18.14: risk_config 段 → cfg['risk_config'] → runner 透传
+        # run_backtest(risk_config={"max_position_pct": 0.1}) 原生消费 (账户级风控,
+        # 引擎 hasattr 校验 + 未知字段仅 warning). skill 桌面编辑的实盘风控真正生效.
+        rc = (params_doc or {}).get("risk_config")
+        if isinstance(rc, dict):
+            # 与既有 cfg['risk_config'] 合并 (显式 cfg 优先)
+            merged = dict(cfg.get("risk_config") or {})
+            merged.update(rc)
+            cfg["risk_config"] = merged
+
     if getattr(args, "dataset", None):
         manifest_path = Path(args.dataset)
         if not manifest_path.exists():
@@ -82,7 +111,16 @@ def cmd_run(args) -> int:
             return 2
         cfg["_dataset_manifest"] = manifest
 
-    result = runtime.backtest.run(strategy_path, cfg)
+    try:
+        result = runtime.backtest.run(strategy_path, cfg)
+    except Exception as e:  # noqa: BLE001 — 错误分级: StrategyParamsError → exit 3; 其余 runner 错 → exit 4
+        from .akquant_runner import StrategyParamsError
+        if isinstance(e, StrategyParamsError):
+            # Round 18.13: --params strategy_params 预校验失败 (validate_strategy_params) 走 exit 3,
+            # 与纪律档位一致 — 不带全 Traceback, 一行明确 msg (用户改 params.json).
+            print(f"策略参数校验失败: {e}", file=sys.stderr)
+            return 3
+        raise
 
     if args.output:
         import json
@@ -799,8 +837,9 @@ def cmd_live_run(args) -> int:
         print(f"[error] strategy.py 加载失败: {e}", file=sys.stderr)
         return 3
     try:
+        import json as _json
         symbols = [s.strip() for s in args.symbols.split(",")] if args.symbols else None
-        params = json.loads(Path(args.params).read_text(encoding="utf-8")) if args.params else None
+        params = _json.loads(Path(args.params).read_text(encoding="utf-8")) if args.params else None
         # 只取 strategy_params 段 (schema 顶层: backtest / strategy_params / risk_config / meta)
         sp = (params or {}).get("strategy_params")
         run_live(
@@ -842,6 +881,9 @@ def build_parser() -> argparse.ArgumentParser:
     r.add_argument("--config", required=True, help="CONFIG JSON 路径")
     r.add_argument("--output", help="result 落盘 JSON 路径 (默认 stdout)")
     r.add_argument("--dataset", help="固化 manifest JSON 路径")
+    r.add_argument("--params", default=None,
+                   help="params.json 路径 (固定 schema; strategy_params 段作策略构造参数, "
+                        "与 `live run --params` 同源 — 回测/实盘参数一致)")
     r.add_argument("--skip-discipline", action="store_true",
                    help="跳过 akquant API 静态审查 (qa / 旧策略兼容)")
     r.add_argument("--upload", action="store_true",

{hamuna_quant_cli-0.1.1 → hamuna_quant_cli-0.1.2}/hamuna_quant_cli/akquant_data_adapter.py

@@ -84,14 +84,14 @@ def load_prebuilt_to_akquant(universe: Iterable[str], start: str, end: str,
 
     universe: 标的代码 list, e.g. ['600000.SH', '000001.SZ']
     start/end: 'YYYYMMDD' 字符串
-    period: '1d' (Phase B 仅日线)
+    period: '1d' | '5m' (2026-08-27 打通 5m; 需本地 5m bundle, 见 prefet resolver).
 
     数据源: prebuilt_resolver.resolve (pyarrow filter pushdown, fast-path).
-    prebuilt 找不到 → raise FileNotFoundError + 引导用户跑 `dataset fetch`.
+    prebuilt 找不到 → raise FileNotFoundError + 引导用户跑 `dataset fetch --period 5m`.
     """
-    if period != '1d':
+    if period not in ('1d', '5m'):
         raise NotImplementedError(
-            f'akquant_data_adapter 仅支持 1d (Phase B), period={period} 待 akquant Phase C')
+            f'akquant_data_adapter 仅支持 1d/5m, period={period} 待 akquant Phase C')
     codes = list(universe)
     if not codes:
         raise ValueError('universe 不能为空')
@@ -124,9 +124,15 @@ def load_prebuilt_to_akquant(universe: Iterable[str], start: str, end: str,
             f'prebuilt 缺 OHLCV 列 {missing} (R2: schema 不兼容). 实际列: {list(df.columns)[:10]}...')
     for c in _DROP_COLS:
         df = df.drop(columns=[c], errors='ignore')
-    # time 字段兼容 8 位 (YYYYMMDD, 个股) / 14 位 (YYYYMMDDHHMMSS, ETF/可转债) / ISO (YYYY-MM-DD)
-    _date_str = df['date'].astype(str).str[:10].str.replace('-', '', regex=False)
-    df['date'] = pd.to_datetime(_date_str, format='%Y%m%d')
+    # date 列: resolver 已归一 datetime64 (日线 = 当日 00:00, 5m = 已带时分秒).
+    # 若仍是字符串 (老 single 路径), 按 period 粒度解析:
+    #   '5m' 保留时分秒 (YYYYMMDDHHMMSS), '1d' 取 8 位日期.
+    if not pd.api.types.is_datetime64_any_dtype(df['date']):
+        _date_str = df['date'].astype(str).str[:14].str.replace('-', '', regex=False)
+        if period == '5m':
+            df['date'] = pd.to_datetime(_date_str, format='%Y%m%d%H%M%S', errors='coerce')
+        else:
+            df['date'] = pd.to_datetime(_date_str.str[:8], format='%Y%m%d', errors='coerce')
     df = df[['date', 'open', 'high', 'low', 'close', 'volume', 'symbol']]
     return df.reset_index(drop=True)
 
@@ -188,8 +194,6 @@ def _try_prebuilt_parquet(universe: Iterable[str], start: str, end: str,
 
     返回 None 表示无 prebuilt 命中 (调用方 fallback: 报错 + 引导下载).
     """
-    if period != '1d':
-        return None
     from .prebuilt_resolver import resolve  # B5 搬入同包
     df, _src = resolve(list(universe), start, end, period=period)
     return df

{hamuna_quant_cli-0.1.1 → hamuna_quant_cli-0.1.2}/hamuna_quant_cli/akquant_runner.py

@@ -36,7 +36,79 @@ from pathlib import Path
 from typing import Any
 
 
+class StrategyParamsError(RuntimeError):
+    """--params strategy_params 预校验失败 (validate_strategy_params).
+
+    cmd_run 用此类型区分 exit 3 (参数错, 改 params.json) 与 runner 其它 RuntimeError (exit 4).
+    Round 18.13.
+    """
+
+
 # ---- strategy loader (沿 driver._load_strategy 模式, 但导 Strategy 类不导 handlebar) ----
+def _with_backtest_timer_rebalance(cls: type) -> type:
+    """回测端周五 schedule + on_timer 注入 — 与实盘 replay 同触发路径.
+
+    Round 18.32: 之前回测横截面策略走 `on_cross_section`, 实盘 replay 走
+    `on_timer` (runner 外部日历注入 schedule) — 两端路径不同, 可比性差 (实盘丢
+    07-03 批 / 因子一次性 vs 逐 bar 演进). 本 wrapper 让**回测也走 on_timer**:
+
+    - `on_start` 时 `_trading_days` 未注入 (engine.py:3107 on_start 在 :3502 注入
+      之前), `self.trading_days` 恒空 — 所以**延迟到首个 on_bar** 再注册.
+    - 首个 bar 时从 `self.trading_days` 筛周五, 逐周注册 `schedule(周五14:55, 'rebalance')`
+      → 引擎按 bar 边界触发 `on_timer('rebalance')`, ctx.current_time 即该周五.
+    - 策略已定义 on_timer 处理 'rebalance' → 与实盘完全同路径; 未定义 → base no-op, 无害.
+    - 只包有 on_timer 的策略 (无 on_timer 时 on_cross_section 仍是唯一回测调仓钩子,
+      注入 schedule 白费且可能引发无预期 on_timer 调用).
+
+    ponytail: 与 live 端 `_with_live_history_depth` 互补 — live 用外部日历注入
+    (replay bars / bridge 历史), 回测用引擎 trading_days. 两端最终都注册
+    `schedule(周五14:55, 'rebalance')` → `on_timer`, 真正同机制.
+    """
+    import datetime as _dt
+
+    if cls is None or "on_timer" not in getattr(cls, "__dict__", {}):
+        return cls
+    from akquant.strategy_scheduler import schedule as _schedule
+
+    class _BacktestTimerRebalance(cls):
+        _bt_timer_registered = False
+
+        def on_bar(self, bar) -> Any:
+            ret_val = super().on_bar(bar)
+            if not type(self)._bt_timer_registered:
+                type(self)._bt_timer_registered = True
+                try:
+                    fridays = [ts for ts in self.trading_days if ts.weekday() == 4]
+                    for ts in fridays:
+                        _schedule(self, ts.replace(hour=14, minute=55), "rebalance")
+                    print(
+                        f"[info] 回测周五 schedule+on_timer 注入: {len(fridays)} 个 "
+                        f"({[ts.strftime('%m-%d') for ts in fridays]})",
+                        file=sys.stderr,
+                    )
+                except Exception as e:  # noqa: BLE001 — 注入失败不崩, 回测走原路径
+                    print(
+                        f"[warn] 回测周五 schedule 注入失败: {e}",
+                        file=sys.stderr,
+                    )
+            return ret_val
+
+        def on_cross_section(self, trading_date, timestamp) -> Any:
+            """吞掉 on_cross_section — schedule 定时器已接管调仓 (Round 18.32).
+
+            策略类同时有 on_cross_section (回测旧路径) 和 on_timer (实盘新路径) 时,
+            同一个周五**两个钩子都会触发** → 重复下单 (实测: 07-06 批 20→22 trades,
+            000006/000035 各重复买一次). 本 wrapper 把 on_cross_section 变 no-op,
+            让回测统一走 schedule+on_timer, 与实盘完全同路径. 若策略没有
+            on_cross_section, 本方法不干扰 (未重写 → 走父类 no-op, 同样无害).
+            """
+            return None
+
+    _BacktestTimerRebalance.__name__ = cls.__name__
+    _BacktestTimerRebalance.__qualname__ = cls.__qualname__
+    return _BacktestTimerRebalance
+
+
 def _load_akquant_strategy(strategy_path: str) -> Any:
     """加载 strategy .py, 提取第一个 akquant.Strategy 子类.
 
@@ -101,13 +173,15 @@ def run_akquant_backtest(strategy_path: str, cfg: dict) -> dict:
         pass
 
     # data — Q1 兜底默认开 (cfg['price_limit_clamp']=False 可关)
+    # period: cfg['period'] 支持 '1d'|'5m' (2026-08-27) — 5m 走 __bundle__*_5m
     use_clamp = bool(cfg.get('price_limit_clamp', True))
+    _period = cfg.get('period', '1d')
     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'])
+            universe, cfg['backtest_start'], cfg['backtest_end'], period=_period)
     else:
-        df = load_prebuilt_to_akquant(universe, cfg['backtest_start'], cfg['backtest_end'])
+        df = load_prebuilt_to_akquant(universe, cfg['backtest_start'], cfg['backtest_end'], period=_period)
     if df.empty:
         raise FileNotFoundError(
             f'未取到 bar 数据 (universe={universe}, {cfg["backtest_start"]}-{cfg["backtest_end"]})')
@@ -119,6 +193,9 @@ def run_akquant_backtest(strategy_path: str, cfg: dict) -> dict:
 
     # strategy class
     strat_cls = _load_akquant_strategy(strategy_path)
+    # Round 18.32: 回测也走 schedule+on_timer (与实盘 replay 同触发路径) — 在 class
+    # 层面 wrap, 必须在此处 (kwargs['strategy'] 在下方构建, wrap 需在构建前生效).
+    strat_cls = _with_backtest_timer_rebalance(strat_cls)
 
     # ===== 0.3 架构变更 (2026-08-18 简化): compute_factors / filter_symbols 接入引擎 =====
     # 流程: 实例化 → compute_factors (直接传 prebuilt df, 引擎不包装 BacktestContext) →
@@ -211,16 +288,46 @@ def run_akquant_backtest(strategy_path: str, cfg: dict) -> dict:
     #     只有策略声明该字段才注入 — 未声明注入 = engine strict 模式 unknown key 崩溃.
     #     ponytail: 回测侧 exclude_symbols 仅来自 cfg; 实盘 QMT「排除已持仓」需策略在
     #     on_bar 里自己调 broker query_positions() (runner 不透传持仓, 那是动态状态).
+    # ===== strategy 调参展开注入 (0.3.x 原生 kwargs 路径, Round 18.13) =====
+    # 之前把 universe/exclude_symbols 打包成 kwargs['strategy_params'] dict — 但
+    # akquant.run_backtest 签名原生**没有** strategy_params (只有 **kwargs + strict_strategy_params=True),
+    # engine 把 kwargs 里未知 key 拼进 strategy(**kwargs) 构造. 现在把参数**展开**进 kwargs:
+    #   - universe/exclude_symbols: cfg 归一化后直接展开 (engine 经 **kwargs → strategy(**merged) 注入)
+    #   - strategy_params 段: cmd_run --params 读 params.json 的 strategy_params (Round 18.13),
+    #     与 live run --params 同源, 回测/实盘参数完全一致
+    # engine strict_strategy_params=True 会对未声明字段抛 TypeError (老 __init__ 风格已有 _strategy_param_fields 豁免).
     accepted_fields = _strategy_param_fields(strat_cls)
-    strategy_params: dict[str, Any] = {}
     if 'universe' in accepted_fields:
-        strategy_params['universe'] = universe
+        kwargs['universe'] = universe
     if 'exclude_symbols' in accepted_fields:
         exclude_codes = cfg.get('exclude_symbols') or []
-        strategy_params['exclude_symbols'] = [
+        kwargs['exclude_symbols'] = [
             normalize_symbol(s) for s in exclude_codes]
-    if strategy_params:
-        kwargs['strategy_params'] = strategy_params
+    # params.json strategy_params 段 → 展开注入 (仅声明字段; 未声明 → strict 模式 engine 拒收)
+    user_params = (cfg.get('strategy_params') or {}).get('strategy_params') \
+        if isinstance(cfg.get('strategy_params'), dict) and \
+           isinstance((cfg.get('strategy_params') or {}).get('strategy_params'), dict) \
+        else (cfg.get('strategy_params') if isinstance(cfg.get('strategy_params'), dict) else None)
+    user_params = user_params if isinstance(user_params, dict) else None
+    if user_params:
+        # 先 validate_strategy_params 预校验 (与 live run --params 同语义) — 未声明字段/
+        # 越界值在回测启动前抛明确错误, 而不是 engine 深处 TypeError.
+        try:
+            from akquant import validate_strategy_params
+            validated = validate_strategy_params(strat_cls, user_params)
+        except Exception as e:
+            raise StrategyParamsError(
+                f"params.json strategy_params 校验失败 (与 IntParam/ListParam 字段不符): {e}"
+            ) from e
+        if validated:
+            for k, v in validated.items():
+                if k not in accepted_fields:
+                    continue
+                # 不覆盖 runner 已注入的 universe/exclude_symbols (它们来自 cfg, 与
+                # params.json 的 backtest 段同源; validate 返回的默认 [] 会误覆盖).
+                if k in kwargs:
+                    continue
+                kwargs[k] = v
 
     # ===== 0.3.x 加速原语 (自动启用, strategy 不用改) =====
     # 1) history_depth — 推断: scan __init__ 默认值 + warmup_period + cfg['history_depth']
@@ -509,9 +616,10 @@ class MACross(Strategy):
             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 在.
+            # 把 universe 注入 (否则 on_start 空订阅 → 0 trades, 高胜率策略实际踩过).
+            # Round 18.13: 注入从 strategy_params dict 改为**展开进 kwargs 顶层** —
+            # run_backtest 签名无 strategy_params (只有 **kwargs + strict_strategy_params),
+            # engine 把未知 key 拼进 strategy(**kwargs). 断言 universe 直接展开.
             import akquant as _akq
             captured: dict = {}
             _orig_run = _akq.run_backtest
@@ -524,9 +632,9 @@ class MACross(Strategy):
             _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")}')
+                # MACross 不收 universe → kwargs 顶层不应有 universe / strategy_params
+                assert 'universe' not in captured and 'strategy_params' not in captured, (
+                    f'MACross 不应注入 universe: {captured.get("universe")!r}')
             finally:
                 _akq.run_backtest = _orig_run
             captured.clear()
@@ -543,8 +651,8 @@ class UsesUniverse(Strategy):
         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")}')
+                assert captured.get('universe') == ['600000.SH'], (
+                    f'UsesUniverse (0.3 ParamModel) 展开注入错: {captured.get("universe")!r}')
             finally:
                 _akq.run_backtest = _orig_run
             # 0.2.x 旧 __init__ 风格 → 检测返 False, runner 跳过注入 (0.3 strict 拒收).
@@ -555,7 +663,7 @@ class UsesUniverse(Strategy):
                 '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__ 风格跳过)')
+            print(f'OK: universe 注入路径生效 (0.3 ParamModel → kwargs 展开; 旧 __init__ 风格跳过)')
 
             # ===== exclude_symbols 注入 (2026-08-25, 用户实战踩坑): =====
             # 仅当策略声明 `exclude_symbols = ListParam(...)` 才注入; 未声明注入 =
@@ -576,10 +684,10 @@ class UsesExclude(Strategy):
             try:
                 cfg_ex = {**cfg, 'exclude_symbols': ['600036']}
                 _ = run_akquant_backtest(strat4, cfg_ex)
-                assert captured.get('strategy_params') == {
-                    'universe': ['600000.SH'],
-                    'exclude_symbols': ['600036.SH'],
-                }, f'UsesExclude 注入错 (应归一化为带后缀): {captured.get("strategy_params")}'
+                assert captured.get('universe') == ['600000.SH'] and \
+                    captured.get('exclude_symbols') == ['600036.SH'], (
+                        f'UsesExclude 展开注入错 (应归一化带后缀 + 顶层 key): '
+                        f'u={captured.get("universe")!r} ex={captured.get("exclude_symbols")!r}')
             finally:
                 _akq.run_backtest = _orig_run
             # MACross (无 ParamModel) 不应注入 exclude_symbols — strict 模式会崩
@@ -587,8 +695,8 @@ class UsesExclude(Strategy):
             _akq.run_backtest = _capture
             try:
                 _ = run_akquant_backtest(strat_path, cfg_ex)   # MACross 走 0.2 __init__ 风格
-                assert 'strategy_params' not in captured, (
-                    f'MACross 不应注入 exclude_symbols: {captured.get("strategy_params")}')
+                assert 'exclude_symbols' not in captured and 'strategy_params' not in captured, (
+                    f'MACross 不应注入 exclude_symbols: {captured.get("exclude_symbols")!r}')
             finally:
                 _akq.run_backtest = _orig_run
             _uses_excl = _load_akquant_strategy(strat4)
@@ -598,6 +706,45 @@ class UsesExclude(Strategy):
                 'MACross (无 exclude_symbols 字段) 应 False')
             print('OK: exclude_symbols 注入 (仅声明注入 + 归一化带后缀 + 未声明跳过)')
 
+            # ===== Round 18.13: params.json strategy_params 展开注入 (回测 --params) =====
+            # cmd_run --params 读 params.json 的 strategy_params 段注入 cfg['strategy_params'],
+            # runner 展开进 kwargs 顶层 (红线: 必须 validate_strategy_params 预校验).
+            strat5 = Path(tmp) / 'params_poly.py'
+            strat5.write_text('''
+from akquant import Strategy, IntParam, ListParam
+
+class ParamsPoly(Strategy):
+    fast = IntParam(10, ge=2, le=200)
+    slow = IntParam(20, ge=3, le=500)
+    universe: list = ListParam(default=[])
+    def on_bar(self, bar):
+        pass
+''', encoding='utf-8')
+            captured.clear()
+            _akq.run_backtest = _capture
+            try:
+                cfg_p = {**cfg, 'strategy_params': {'fast': 5, 'slow': 33}}
+                _ = run_akquant_backtest(strat5, cfg_p)
+                assert captured.get('fast') == 5 and captured.get('slow') == 33, (
+                    f'params strategy_params 应展开注入 kwargs 顶层: '
+                    f'fast={captured.get("fast")!r} slow={captured.get("slow")!r}')
+                assert captured.get('universe') == ['600000.SH'], (
+                    f'universe 应继续展开注入: {captured.get("universe")!r}')
+            finally:
+                _akq.run_backtest = _orig_run
+            # 未知字段 → StrategyParamsError 启动前抛 (cmd_run 转 exit 3), 不是 engine 深处 TypeError
+            captured.clear()
+            _akq.run_backtest = _capture
+            try:
+                try:
+                    _ = run_akquant_backtest(strat5, {**cfg_p, 'strategy_params': {'bogus': 1}})
+                    raise AssertionError('未知字段应被 validate_strategy_params 拦')
+                except StrategyParamsError as e:
+                    assert '校验失败' in str(e), f'应报校验失败: {e}'
+            finally:
+                _akq.run_backtest = _orig_run
+            print('OK: params strategy_params 展开注入 (validate 预校验 + 未知字段拦在启动前)')
+
             # ===== 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 默认)

{hamuna_quant_cli-0.1.1 → hamuna_quant_cli-0.1.2}/hamuna_quant_cli/akquant_schema_adapter.py

@@ -52,6 +52,7 @@ Ponytail ceiling: 不实现 benchmark alpha/beta/IR 单独导出.
 from __future__ import annotations
 
 import math
+from pathlib import Path
 from typing import Any
 
 import numpy as np
@@ -281,20 +282,102 @@ def normalize_symbol(symbol: str) -> str:
     """6 位裸码 → 交易所带后缀形态 (bundle stockCode '600000.SH').
 
     幂等: 已带 .SH/.SZ/.BJ 后缀 / SH600000 前缀形态 → 原样返回.
-    与 __main__._normalize_to_full 同映射 (60/68/11/13 → SH, 其余 → SZ).
+    与 __main__._normalize_to_full 同映射.
+
+    用户硬约束 (2026-08-29 "统一实盘回测市场代码, 所有股票必须带市场代码避免错误"):
+      config/CLI 的 universe / --symbols **必须带 .SH/.SZ/.BJ 后缀** (e.g. "600000.SH"),
+      禁止裸 6 位码。裸码虽然兼容 (走探测/静态回退), 但**发告警** — 探测靠本地 prebuilt
+      bundle, 无 bundle 或静态回退对 51/15/88 等会误判交易所 → 静默少标的 / 归错市场.
+      新写策略/配置一律带后缀, 别依赖补全.
+
+    映射优先级 (2026-08-27 真 bug 修复):
+      1) 数据驱动: 探本地 prebuilt bundle (__bundle__etf_D / __bundle__all_a_D 等),
+         code.SH / code.SZ / code.BJ 哪个实际存在就用哪个. 静态规则曾把 510050
+         (沪市 ETF, bundle 里是 510050.SH) 归成 .SZ → 血亏: 回测静默少 1 标的.
+      2) 探不到 → 静态回退: 60/68/11/13/51/58/56 → SH, 15/16 → SZ, 8/4 → BJ
+         (2026-08-29 补 ETF/北交所前缀, 关死裸码误判窗口).
     """
     s = symbol.strip().upper()
     if s.endswith(('.SH', '.SZ', '.BJ')):
         return symbol
     if len(s) > 2 and s[:2] in ('SH', 'SZ', 'BJ'):
-        s = s[2:]
+        s = s[2:]  # 前缀形态 (SH600000) 也视为已带市场代码 — 先剥, 不告警
     if len(s) != 6 or not s.isdigit():
         return symbol
-    if s.startswith(('60', '68', '11', '13')):
+    import warnings as _w
+    if not _has_market_code_prefix(symbol):
+        _w.warn(
+            f"裸码 {symbol!r} 未带市场代码 — 探测本地 bundle 补后缀, 可能误判. "
+            "用户规范: 所有股票必须带 .SH/.SZ/.BJ (e.g. '600000.SH'), 别依赖补全.",
+            stacklevel=2,
+        )
+    probed = _probe_exchange_suffix(s)
+    if probed:
+        return f'{s}{probed}'
+    if s.startswith(('60', '68', '11', '13', '51', '58', '56')):
         return f'{s}.SH'
+    if s.startswith(('15', '16')):
+        return f'{s}.SZ'
+    if s.startswith(('43', '83', '87', '88', '889', '8', '4', '92')):
+        return f'{s}.BJ'
     return f'{s}.SZ'
 
 
+def _has_market_code_prefix(symbol: str) -> bool:
+    """原始输入是否已带市场代码 (后缀 .SH/.SZ/.BJ 或前缀 SH600000).
+
+    决定 normalize_symbol 是否发裸码告警 — 前缀形态也是合法写法, 不告警.
+    """
+    s = (symbol or '').strip().upper()
+    if not s:
+        return False
+    if s.endswith(('.SH', '.SZ', '.BJ')):
+        return True
+    return len(s) > 2 and s[:2] in ('SH', 'SZ', 'BJ')
+
+
+_CACHE_ROOT: str | None = None   # 缓存目录 (测试可注入)
+_BUNDLE_SUFFIX_BY_CODE: dict[str, str] | None = None   # {裸码: '.SH'} session 级一次性缓存
+
+
+def _probe_exchange_suffix(code: str) -> str | None:
+    """查本地 prebuilt bundle 里 code 实际挂哪个交易所后缀. 无 bundle / 无命中 → None.
+
+    性能: 每个 bundle 只读一次 stockCode 列 (session 级 _BUNDLE_SUFFIX_BY_CODE 缓存),
+    config 解析 5004 syms 也就扫一趟, 不会 5004 次读盘.
+    """
+    global _BUNDLE_SUFFIX_BY_CODE
+    if _BUNDLE_SUFFIX_BY_CODE is None:
+        _BUNDLE_SUFFIX_BY_CODE = _scan_bundle_suffixes()
+    return _BUNDLE_SUFFIX_BY_CODE.get(code)
+
+
+def _scan_bundle_suffixes() -> dict[str, str]:
+    """扫所有 __bundle__*D* parquet 的 stockCode 列, 建 {裸码: 后缀} 全表."""
+    root = _CACHE_ROOT or (Path.home() / '.hamuna' / 'data_cache' / 'datasets')
+    out: dict[str, str] = {}
+    try:
+        bundles = sorted(root.glob('__bundle__*'))
+    except Exception:
+        return out
+    for bundle in bundles:
+        if not bundle.name.endswith('.parquet'):
+            continue
+        try:
+            import pyarrow.parquet as pq
+            f = pq.ParquetFile(bundle)
+            if 'stockCode' not in f.schema.names:
+                continue
+            codes = f.read(columns=['stockCode']).column('stockCode').to_pylist()
+            for code in codes:
+                code, dot, suf = code.partition('.')
+                if dot and code not in out:
+                    out[code] = '.' + suf
+        except Exception:
+            continue
+    return out
+
+
 def _cfg_universe(cfg: dict) -> list[str]:
     """cfg['pool'] / cfg['universe'] → 展开标的代码 list.
 
@@ -336,15 +419,32 @@ def _extra(akquant_r: Any) -> dict:
         if isinstance(v, pd.DataFrame):
             try:
                 # 限定大小, 避免 params 膨胀
-                v = v.head(200)
-                out[name] = v.to_dict(orient='records')
+                v = v.head(200).to_dict(orient='records')
             except Exception:  # noqa: BLE001
                 pass
-        elif isinstance(v, (list, dict)):
-            out[name] = v
+        if isinstance(v, (list, dict)):
+            # 多分支都过 NaN 清理 —— orders_df 常是 list[dict], 不走 DataFrame 分支
+            out[name] = _json_safe(v)
     return out
 
 
+def _json_safe(o: Any) -> Any:
+    """递归把 NaN/Inf 归一成 None — JSON 标准不允许 NaN/Inf 字面量.
+
+    场景: akquant orders_df 等原始曲面的 limit_price/stop_price 常见 NaN
+    (市价单/未触发单). 直接进 result 会让后端 json.loads 崩.
+    Round 18.16 真数据验证抓到的真实泄漏 (Round 3 NaN 待办真载体).
+    """
+    import math
+    if isinstance(o, float):
+        return None if (math.isnan(o) or math.isinf(o)) else o
+    if isinstance(o, dict):
+        return {k: _json_safe(v) for k, v in o.items()}
+    if isinstance(o, list):
+        return [_json_safe(x) for x in o]
+    return o
+
+
 def _monthly_bars(nav_curve: list[dict]) -> list[dict]:
     """委托 `hamuna_quant_cli.references._metrics_15.monthly_bars` (R-metrics-dedup)."""
     from ._metrics_15 import monthly_bars as _m15_monthly_bars
@@ -406,6 +506,9 @@ def _selfcheck() -> None:
         metrics = _MockMetrics()
         trades_df = _MockTradesDF()._df
         equity_curve = _MockEquityCurve()
+        # NaN 泄漏回归: orders_df 的 limit_price 常态 NaN (市价单), 必须被 _json_safe 清掉
+        orders_df = [{'symbol': '600000.SH', 'limit_price': float('nan'),
+                      'stop_price': float('nan'), 'filled': 100}]
 
     cfg = {
         'backtest_start': '20240101',
@@ -436,7 +539,13 @@ def _selfcheck() -> None:
     # initial_capital / final_capital
     assert result['initial_capital'] == 100_000.0
     assert result['final_capital'] == 1_050_000.0
-    print('OK: akquant_schema_adapter 15 metrics + 13 顶层 key + 7 trades fields 全对齐')
+    # NaN 泄漏回归 (Round 18.16): _akquant_extra 内 NaN/Inf 必须清理为 None
+    odf = result['params']['_akquant_extra']['orders_df']
+    assert odf[0]['limit_price'] is None, f'limit_price 应 None, got {odf[0]["limit_price"]!r}'
+    assert odf[0]['stop_price'] is None
+    import json
+    json.dumps(result)  # strict JSON 序列化 — NaN 会 raise ValueError
+    print('OK: akquant_schema_adapter 15 metrics + 13 顶层 key + 7 trades fields + NaN 清理 全对齐')
 
 
 if __name__ == '__main__':