hamuna-quant-cli 0.1.0.dev93__tar.gz → 0.1.2__tar.gz

{hamuna_quant_cli-0.1.0.dev93 → hamuna_quant_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hamuna-quant-cli
-Version: 0.1.0.dev93
+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
@@ -25,6 +25,8 @@ Requires-Dist: numpy>=1.23
 Requires-Dist: pyarrow>=10
 Requires-Dist: pyyaml>=6
 Requires-Dist: requests>=2.28
+Requires-Dist: boto3>=1.34
+Requires-Dist: cryptography>=41
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: pytest-cov>=4; extra == "dev"

{hamuna_quant_cli-0.1.0.dev93 → 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.0.dev93"
+__version__ = "0.1.2"

{hamuna_quant_cli-0.1.0.dev93 → 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,7 +837,11 @@ 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
+        # 只取 strategy_params 段 (schema 顶层: backtest / strategy_params / risk_config / meta)
+        sp = (params or {}).get("strategy_params")
         run_live(
             spec,
             mode=args.mode,
@@ -812,6 +854,7 @@ def cmd_live_run(args) -> int:
             log_file=args.log_file,
             market_broker=args.market_broker,
             replay_days=args.replay_days,
+            params=sp if isinstance(sp, dict) else None,
         )
     except LiveRunError as e:
         print(f"[error] live run 失败: {e}", file=sys.stderr)
@@ -838,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",
@@ -950,6 +996,8 @@ def build_parser() -> argparse.ArgumentParser:
                        help="独立行情 broker (e.g. qmt_market)")
     run_p.add_argument("--symbols", default=None,
                        help="标的列表, 逗号分隔")
+    run_p.add_argument("--params", default=None,
+                       help="params.json 路径 (固定 schema, strategy_params 段作策略构造参数)")
     run_p.add_argument("--duration", default="1h",
                        help="运行时长 (akquant 解析)")
     run_p.add_argument("--class-name", default="Strategy",

{hamuna_quant_cli-0.1.0.dev93 → 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,7 +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')
-    df['date'] = pd.to_datetime(df['date'].astype(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)
 
@@ -186,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.0.dev93 → 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) →
@@ -203,14 +280,54 @@ def run_akquant_backtest(strategy_path: str, cfg: dict) -> dict:
         '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.
+    # strategy_params 注入 (0.3.x ParamModel 字段):
+    #   - universe: 多标/横截面策略必需, cfg['universe']/['pool'] 归一化后注入.
+    #   - exclude_symbols: 策略声明 `exclude_symbols = ListParam(default=[])` 时,
+    #     cfg['exclude_symbols'] (裸码 list) 归一化后并列注入. 策略在 on_bar 里
+    #     拿 self.params.exclude_symbols 和 bar.symbol 比对 (两者同带后缀形态).
+    #     只有策略声明该字段才注入 — 未声明注入 = 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)
+    if 'universe' in accepted_fields:
+        kwargs['universe'] = universe
+    if 'exclude_symbols' in accepted_fields:
+        exclude_codes = cfg.get('exclude_symbols') or []
+        kwargs['exclude_symbols'] = [
+            normalize_symbol(s) for s in exclude_codes]
+    # 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']
@@ -393,34 +510,44 @@ 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 字段.
+def _strategy_param_fields(strat_cls: type) -> set[str]:
+    """返回 strategy 声明的 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 跳过.
+    0.3.x: `universe: list = ListParam(default=[])` 类字段 → model_fields.
+    0.2.x: `__init__(self, universe=None)` — 无 model_fields, 返空集 (runner 跳过注入).
 
-    ponytail: 仅检测 'universe' 字段. 其它字段 (lots/fast/slow 等) 走 ParamModel 自身规则,
-    runner 不替用户策略注入; grid/WFO 子命令会单独处理.
+    空集 = 策略没用 ParamModel (老 __init__ 风格), 不是「豁免」— 0.3.x 严格拒收.
     """
     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
+            return set()
         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
+        fields = getattr(params_obj, 'model_fields', None)  # pydantic v2
+        if fields:
+            return set(fields)
+        fields_v1 = getattr(params_obj, '__fields__', None)  # pydantic v1 fallback
+        if fields_v1:
+            return set(fields_v1)
+        return set()
     except Exception:  # noqa: BLE001
-        return False
+        return set()
+
+
+def _strategy_accepts_universe_param(strat_cls: type) -> bool:
+    """检测 strategy 是否声明 `universe` 为 0.3.x 的 ParamModel 字段."""
+    return 'universe' in _strategy_param_fields(strat_cls)
+
+
+def _strategy_accepts_exclude_symbols_param(strat_cls: type) -> bool:
+    """检测 strategy 是否声明 `exclude_symbols` 为 0.3.x 的 ParamModel 字段.
+
+    仅当策略显式声明才注入 — 未声明字段注入会在 strict_strategy_params=True 下
+    被 engine 判 unknown key → TypeError (用户 2026-08-25 实际踩过).
+    """
+    return 'exclude_symbols' in _strategy_param_fields(strat_cls)
 
 
 def _selfcheck() -> None:
@@ -489,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
@@ -504,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()
@@ -523,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 拒收).
@@ -535,7 +663,87 @@ 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(...)` 才注入; 未声明注入 =
+            # engine strict 模式 unknown key → TypeError. 注入值归一化为带后缀形态.
+            strat4 = Path(tmp) / 'uses_exclude.py'
+            strat4.write_text('''
+from akquant import Strategy, ListParam
+
+class UsesExclude(Strategy):
+    """0.3.x 新 ParamModel 风格: universe + exclude_symbols 双字段."""
+    universe = ListParam(item_type=str, default=[])
+    exclude_symbols = ListParam(item_type=str, default=[])
+    def on_bar(self, bar):
+        pass
+''', encoding='utf-8')
+            captured.clear()
+            _akq.run_backtest = _capture
+            try:
+                cfg_ex = {**cfg, 'exclude_symbols': ['600036']}
+                _ = run_akquant_backtest(strat4, cfg_ex)
+                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 模式会崩
+            captured.clear()
+            _akq.run_backtest = _capture
+            try:
+                _ = run_akquant_backtest(strat_path, cfg_ex)   # MACross 走 0.2 __init__ 风格
+                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)
+            assert _strategy_accepts_exclude_symbols_param(_uses_excl), (
+                'UsesExclude (ListParam) 应 _strategy_accepts_exclude_symbols_param=True')
+            assert not _strategy_accepts_exclude_symbols_param(_macross_cls), (
+                '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