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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hamuna-quant-cli
-Version: 0.1.1
+Version: 0.1.6
 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.6}/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.6"

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

@@ -7,7 +7,7 @@ Usage:
     hamuna_quant_cli create --name ... --config ...
     hamuna_quant_cli parity [--strategies ...]
     hamuna_quant_cli qmt-translate <strategy.py> <cfg.json>
-    hamuna_quant_cli commit <strategy_id> --strategy ... --result ...
+    hamuna_quant_cli commit <strategy_id> --strategy ... --result ... --config ... --params ...
     hamuna_quant_cli dataset {list|fetch|manifest}
     hamuna_quant_cli live run <strategy.py> --mode paper --broker qmt ...
 
@@ -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
@@ -250,14 +288,20 @@ def cmd_qmt_translate(args) -> int:
     print(f"QMT body saved → {out}", file=sys.stderr)
     import json
     print(json.dumps({"qmt_body_path": str(out), "note":
-                      "本地 stub; cloud export 端点会重新渲染 + 签 cert + 嵌入 embedded API key"},
+                      "本地 stub — Round 18.42 起 cloud 不再渲染 .qmt.py, 实盘由 desktop 落盘原始 .py → bridge_server 执行"},
                      ensure_ascii=False))
     return 0
 
 
 def cmd_commit(args) -> int:
-    """commiter 5 步打包上传 (qmt-translate + bundle + PUT result + POST code + POST export)."""
-    from .qmt_translator import write_qmt_body
+    """commiter 3 步打包上传 (bundle + PUT result + POST code).
+
+    Round 18.42: POST /strategies/:id/export 端点已废, 不再生成 .qmt.py shell —
+    server 仅存策略源码. QMT 实盘由 desktop deploy_strategy 落盘原始 .py →
+    bridge_server 扫描执行; hamuna-quant-cli 下单走 bridge_server HTTP.
+    bundle = 4 文件 (strategy + result + config + params). multipart params 字段
+    = 整个 params.json 内容 (ADR-0025, desktop 实盘配置源).
+    """
     from . import runtime
     import json
     import tarfile
@@ -276,35 +320,26 @@ def cmd_commit(args) -> int:
     if cfg_path and not cfg_path.exists():
         print(f"config.json 不存在: {cfg_path}", file=sys.stderr)
         return 2
-    spec_path = Path(args.spec) if args.spec else None
-    if spec_path and not spec_path.exists():
-        print(f"spec_strategy.json 不存在: {spec_path} (--spec 可选)", file=sys.stderr)
-        spec_path = None
+    params_path = Path(args.params) if args.params else None
+    if params_path and not params_path.exists():
+        print(f"params.json 不存在: {params_path} (--params 可选)", file=sys.stderr)
+        return 2
 
     bundle_out = Path(args.bundle_out) if args.bundle_out else Path(f"runs/{sid}/bundle.tar.gz")
     bundle_out.parent.mkdir(parents=True, exist_ok=True)
 
-    print("=== Step 1/5: akquant → QMT body 翻译 (本地 stub) ===", file=sys.stderr)
-    try:
-        qmt_body_path = write_qmt_body(strategy_path, cfg_path, spec_path)
-    except NotImplementedError as e:
-        print(f"  ✗ 不支持: {e}", file=sys.stderr)
-        return 3
-    print(f"  ✓ qmt_body = {qmt_body_path}", file=sys.stderr)
-
-    print("=== Step 2/5: 打包 bundle (strategy + qmt_body + metrics + spec) ===",
+    print("=== Step 1/3: 打包 bundle (strategy + result + config + params) ===",
           file=sys.stderr)
     with tarfile.open(bundle_out, "w:gz") as tar:
         tar.add(strategy_path, arcname=strategy_path.name)
-        tar.add(qmt_body_path, arcname=qmt_body_path.name)
         tar.add(result_path, arcname=result_path.name)
-        if spec_path:
-            tar.add(spec_path, arcname=spec_path.name)
         if cfg_path:
             tar.add(cfg_path, arcname=cfg_path.name)
+        if params_path:
+            tar.add(params_path, arcname=params_path.name)
     print(f"  ✓ bundle = {bundle_out} ({bundle_out.stat().st_size} bytes)", file=sys.stderr)
 
-    print("=== Step 3/5: PUT /strategies/:id/result (metrics) ===", file=sys.stderr)
+    print("=== Step 2/3: PUT /strategies/:id/result (metrics) ===", file=sys.stderr)
     try:
         result = json.loads(result_path.read_text(encoding="utf-8"))
     except json.JSONDecodeError as e:
@@ -317,47 +352,27 @@ def cmd_commit(args) -> int:
         return 4
     print(f"  ✓ metrics uploaded (resp keys: {sorted(resp.keys())[:5]})", file=sys.stderr)
 
-    print("=== Step 4/5: POST /strategies/:id/code (multipart body + params) ===",
+    print("=== Step 3/3: POST /strategies/:id/code (multipart body + params) ===",
           file=sys.stderr)
-    params: dict = {}
-    if spec_path:
-        params["spec_strategy"] = json.loads(spec_path.read_text(encoding="utf-8"))
-    if cfg_path:
-        params["config"] = json.loads(cfg_path.read_text(encoding="utf-8"))
+    params: dict | None = None
+    if params_path:
+        params = json.loads(params_path.read_text(encoding="utf-8"))
     try:
-        resp_code = runtime.server_client.upload_strategy_code(sid, str(qmt_body_path),
-                                                              params=params or None)
+        resp_code = runtime.server_client.upload_strategy_code(sid, str(strategy_path),
+                                                              params=params)
     except runtime.server_client.ServerError as e:
         print(f"  ✗ 上传源码失败: {e}", file=sys.stderr)
         return 4
     print(f"  ✓ body uploaded (body_hash={resp_code.get('body_hash', '?')[:16]})",
           file=sys.stderr)
 
-    export_path = None
-    if not args.skip_export:
-        print("=== Step 5/5: POST /strategies/:id/export (拉 .qmt.py shell) ===",
-              file=sys.stderr)
-        export_out = Path(args.export_out) if args.export_out else Path(
-            f"runs/{sid}/{sid}.qmt.py"
-        )
-        export_out.parent.mkdir(parents=True, exist_ok=True)
-        try:
-            resp_exp = runtime.server_client.export_strategy(sid, str(export_out))
-        except runtime.server_client.ServerError as e:
-            print(f"  ✗ QMT export 失败: {e}", file=sys.stderr)
-            return 4
-        export_path = str(export_out)
-        print(f"  ✓ shell saved → {export_path} "
-              f"({resp_exp.get('shell_bytes', '?')} bytes)", file=sys.stderr)
-    else:
-        print("=== Step 5/5: SKIPPED (--skip-export) ===", file=sys.stderr)
+    # Round 18.42: step 4 (POST /strategies/:id/export) 已废. QMT shell 不再
+    # server 渲染, 无 export_path 产出. 实盘落盘由 desktop 负责.
 
     print('', file=sys.stderr)
     print(json.dumps({
         "strategy_id": sid,
         "bundle_path": str(bundle_out),
-        "qmt_body_path": str(qmt_body_path),
-        "export_path": export_path,
         "verdict": "OK",
     }, ensure_ascii=False, indent=2))
     return 0
@@ -799,8 +814,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 +858,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",
@@ -886,16 +905,14 @@ def build_parser() -> argparse.ArgumentParser:
     qt.add_argument("--output", help="QMT body 落盘路径")
     qt.set_defaults(func=cmd_qmt_translate)
 
-    cm = sub.add_parser("commit", help="commiter 5 步打包上传")
+    cm = sub.add_parser("commit", help="commiter 3 步打包上传 (bundle + PUT result + POST code)")
     cm.add_argument("strategy_id", help="server 端 strategy_id")
     cm.add_argument("--strategy", help="akquant strategy .py 路径 (默认 <id>.py)")
     cm.add_argument("--result", required=True, help="metrics result.json 路径")
     cm.add_argument("--config", help="config.json 路径")
-    cm.add_argument("--spec", help="spec_strategy.json 路径")
+    cm.add_argument("--params", default=None,
+                    help="params.json 路径 (固定 schema; 整个内容作 multipart params 字段, desktop 实盘配置源)")
     cm.add_argument("--bundle-out", help="bundle tar.gz 落盘路径")
-    cm.add_argument("--skip-export", action="store_true",
-                    help="跳过 step 5 (POST /strategies/:id/export)")
-    cm.add_argument("--export-out", help="step 5 输出 .qmt.py 路径")
     cm.set_defaults(func=cmd_commit)
 
     d = sub.add_parser("dataset", help="构建/列出 prebuilt 数据集")

{hamuna_quant_cli-0.1.1 → hamuna_quant_cli-0.1.6}/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.6}/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,48 @@ 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 返回的默认 [] 会误覆盖).
+                # 空 list 时允许 params.json 覆盖 — 否则 --params strategy_params.exclude_symbols
+                # 永远被 cfg 空注入跳过, 隔离参数静默失效 (Round 18.35 真回测踩坑).
+                if kwargs.get(k):
+                    continue
+                kwargs[k] = v
 
     # ===== 0.3.x 加速原语 (自动启用, strategy 不用改) =====
     # 1) history_depth — 推断: scan __init__ 默认值 + warmup_period + cfg['history_depth']
@@ -509,9 +618,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 +634,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 +653,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 +665,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 +686,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 +697,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 +708,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 默认)