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

hamuna_quant_cli/live/runner.py

@@ -0,0 +1,570 @@
+"""hamuna_quant_cli.live.runner — 实盘运行 (akquant.run_live 薄壳 wrapper).
+
+不引入新业务逻辑 — 撮合 / 下单 / 风控 全部在 akquant 内.
+本模块只做:
+  1. CLI 参数 → akquant.run_live kwargs 翻译
+  2. 实盘 startup: 拉 N sym × N bar 历史 (走 bridge_server /data/history) 拼 {sym: df} 喂 compute_factors
+  3. broker=qmt 时触发 hamuna_qmt_broker / hamuna_qmt_market 注册
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+from .loader import StrategySpec
+
+
+class LiveRunError(Exception):
+    """live run 启动 / 配置失败."""
+
+
+def parse_kv_pairs(raw: str | None) -> dict[str, str]:
+    """CLI 通用: `--gateway-options k1=v1,k2=v2` → dict.
+
+    值不解析类型 — akquant 自己做类型转换 (gateway_options 多数是字符串字段).
+    """
+    if not raw:
+        return {}
+    out: dict[str, str] = {}
+    for pair in raw.split(","):
+        pair = pair.strip()
+        if not pair:
+            continue
+        if "=" not in pair:
+            raise LiveRunError(f"--gateway-options 项 '{pair}' 不是 k=v 形式")
+        k, v = pair.split("=", 1)
+        out[k.strip()] = v.strip()
+    return out
+
+
+def _fetch_bridge_history(bridge_url: str, sym: str, period: str, count: int,
+                          timeout: float = 30.0) -> list[dict[str, Any]]:
+    """GET /data/history?security=<sym>&period=<p>&count=<n>&fq=None → list of bar dict (旧→新).
+
+    bridge 不通 / 超时 / 非 200 直接 raise LiveRunError, 不静默退化 (用户原话:
+    策略出错直接报错停止, 不走 mock 兜底).
+    """
+    from urllib.parse import urlencode
+    from urllib.request import urlopen, Request
+    # bridge_server 对 sh/sz 前缀不识别, strip 到 6 位 canonical
+    canonical = sym.split(".")[0]
+    if canonical.lower().startswith(("sh", "sz")):
+        canonical = canonical[2:]
+    q = urlencode({
+        "security": canonical, "period": period, "count": str(count), "fq": "None",
+    })
+    url = f"{bridge_url.rstrip('/')}/data/history?{q}"
+    try:
+        with urlopen(Request(url), timeout=timeout) as resp:
+            if resp.status != 200:
+                raise LiveRunError(f"bridge /data/history HTTP {resp.status}: {url}")
+            raw = resp.read().decode("utf-8", errors="replace")
+    except Exception as e:
+        raise LiveRunError(
+            f"bridge /data/history 失败 ({sym}): {type(e).__name__}: {e} "
+            f"(url={url}, timeout={timeout}s). 用户原话: 实盘出错直接报错停止, 不走 mock 兜底"
+        ) from e
+    try:
+        import json as _json
+        payload = _json.loads(raw)
+    except Exception as e:
+        raise LiveRunError(
+            f"bridge /data/history 响应非 JSON ({sym}): {e}. body 头 200 字: {raw[:200]!r}"
+        ) from e
+    # envelope {ok, value} 或裸 dict — 兼容两种
+    if isinstance(payload, dict) and "value" in payload:
+        payload = payload["value"]
+    # QMT bridge 常见 dataframe 形态: {dtype: "dataframe", columns: [...], records: [[...], ...]}
+    # 转成 list[dict] 供上层 DataFrame 消费.
+    if isinstance(payload, dict) and payload.get("dtype") == "dataframe":
+        cols = payload.get("columns") or []
+        recs = payload.get("records") or []
+        payload = [dict(zip(cols, row)) for row in recs]
+    if not isinstance(payload, list):
+        raise LiveRunError(
+            f"bridge /data/history 响应 shape 异常 ({sym}): 期望 list[bar] 或 dataframe dict, "
+            f"实得 {type(payload).__name__}"
+        )
+    return payload
+
+
+def _fetch_bridge_history_batch(bridge_url: str, symbols: list[str], period: str = "1d",
+                                  count: int = 30, timeout: float = 45.0) -> dict[str, list[dict[str, Any]]]:
+    """GET /data/history?securities=...&multi=true → {sym: [bar dict]} 批量获取.
+
+    优先使用 bridge_server 的批量 multi 接口 (一次 HTTP 拉多只), 大幅减少
+    逐只 HTTP 开销 (300 只从 ~27s 降到 ~1s). 失败时返回 {} 让调用方回退逐只.
+    """
+    from urllib.parse import urlencode
+    from urllib.request import urlopen, Request
+    import json as _json
+    # 裸码 (bridge 不识别 .SH/.SZ 后缀)
+    qmt_codes = []
+    for sym in symbols:
+        c = sym.split(".")[0]
+        if c.lower().startswith(("sh", "sz")):
+            c = c[2:]
+        qmt_codes.append(c)
+    q = urlencode({
+        "securities": ",".join(qmt_codes),
+        "period": period, "count": str(count), "fq": "None", "multi": "true",
+    })
+    url = f"{bridge_url.rstrip('/')}/data/history?{q}"
+    try:
+        with urlopen(Request(url), timeout=timeout) as resp:
+            if resp.status != 200:
+                return {}
+            raw = resp.read().decode("utf-8", errors="replace")
+        payload = _json.loads(raw)
+    except Exception:
+        return {}
+    # envelope {ok, value}
+    if isinstance(payload, dict) and "value" in payload:
+        payload = payload["value"]
+    # multi 结构: {dtype: "multi", symbols: {sym: dataframe}}
+    if isinstance(payload, dict) and payload.get("dtype") == "multi":
+        out: dict[str, list[dict[str, Any]]] = {}
+        for sym, df_payload in (payload.get("symbols") or {}).items():
+            cols = df_payload.get("columns") or []
+            recs = df_payload.get("records") or []
+            out[sym] = [dict(zip(cols, row)) for row in recs]
+        return out
+    return {}
+
+
+# 分片并发批量拉取: 每片最多 50 只标的 (避免单次 HTTP 过大 + 并发提速)
+_BATCH_CHUNK_SIZE = 50
+
+def _fetch_live_factors(bridge_url: str, universe: list[str], period: str = "1d",
+                        count: int = 30, timeout: float = 45.0,
+                        chunk_size: int = _BATCH_CHUNK_SIZE,
+                        max_workers: int | None = None) -> dict[str, Any]:
+    """实盘 startup: 拉 N sym × N bar 历史, 拼成 {sym: DataFrame} 喂 compute_factors.
+
+    实盘只支持日线 (1d) — QMT 5m/1m/tick 走 market_broker=qmt_market 的实时 tick,
+    不在 compute_factors 启动期预计算范围.
+
+    策略:
+      1. 大量标的按每片最多 chunk_size (默认 50) 分片
+      2. 每片用批量 multi 接口 (一次 HTTP 拉 ≤50 只)
+      3. 多片 ThreadPoolExecutor 并发执行 (默认 min(32, 片数))
+      4. 单只失败的片回退逐只 (兼容旧 bridge_server)
+    """
+    import pandas as _pd
+    from concurrent.futures import ThreadPoolExecutor, as_completed
+
+    if not universe:
+        return {}
+
+    # 分片: 每片最多 chunk_size
+    chunks = [universe[i:i + chunk_size] for i in range(0, len(universe), chunk_size)]
+    if max_workers is None:
+        max_workers = min(32, len(chunks))
+
+    def _norm_sym(sym: str) -> str:
+        """裸码 → 标准 symbol (批量返回可能是 000001 而非 000001.SZ)."""
+        s = str(sym)
+        if "." not in s and len(s) == 6 and s.isdigit():
+            return f"{s}.SH" if s.startswith(("6", "9")) else f"{s}.SZ"
+        return s
+
+    def _fetch_chunk(chunk: list[str]) -> dict[str, _pd.DataFrame]:
+        """拉一片: 批量优先, 失败逐只. 批量返回的裸码 key 会归一化到标准 symbol."""
+        out: dict[str, _pd.DataFrame] = {}
+        batch = _fetch_bridge_history_batch(bridge_url, chunk, period, count, timeout=timeout)
+        if batch:
+            # 归一化批量返回的 key (裸码 → 标准), 并只保留本片请求的
+            wanted = set(chunk)
+            for sym, bars in batch.items():
+                std = _norm_sym(sym)
+                if std in wanted and std not in out:
+                    out[std] = _pd.DataFrame(bars) if bars else                         _pd.DataFrame(columns=["open", "high", "low", "close", "volume", "amount"])
+            # 批量可能漏掉部分 (返回不足), 漏的逐只补
+            missing = [s for s in chunk if s not in out]
+        else:
+            missing = chunk
+        for sym in missing:
+            bars = _fetch_bridge_history(bridge_url, sym, period, count, timeout=timeout)
+            out[sym] = _pd.DataFrame(bars) if bars else                 _pd.DataFrame(columns=["open", "high", "low", "close", "volume", "amount"])
+        return out
+
+    factors: dict[str, _pd.DataFrame] = {}
+    if len(chunks) == 1:
+        factors.update(_fetch_chunk(chunks[0]))
+        return factors
+
+    with ThreadPoolExecutor(max_workers=max_workers) as pool:
+        futures = {pool.submit(_fetch_chunk, c): c for c in chunks}
+        for fut in as_completed(futures):
+            try:
+                factors.update(fut.result())
+            except Exception as e:
+                # 片内失败: 逐只兜底 (不阻塞整体)
+                chunk = futures[fut]
+                for sym in chunk:
+                    try:
+                        bars = _fetch_bridge_history(bridge_url, sym, period, count, timeout=timeout)
+                        factors[sym] = _pd.DataFrame(bars) if bars else                             _pd.DataFrame(columns=["open", "high", "low", "close", "volume", "amount"])
+                    except Exception:
+                        factors[sym] = _pd.DataFrame(columns=["open", "high", "low", "close", "volume", "amount"])
+    return factors
+
+
+def _build_instruments(symbols: list[str] | None, normalize: bool = False) -> list[Any] | None:
+    """symbols 列表 → akquant.Instrument 列表. None → None (全市场, 让策略自行 subscribe).
+
+    normalize=True: 裸码 → 带后缀 (replay 数据来自 prebuilt, stockCode 是 '600000.SH'
+    形态, instrument symbol 必须一致才匹配 ReplayMarketGateway 的订阅过滤).
+    """
+    if not symbols:
+        return None
+    # 延迟 import akquant — 让 loader 在 akquant 未装环境也能跑通
+    from akquant import AssetType, Instrument
+
+    def _sym(s: str) -> str:
+        if normalize:
+            from ..akquant_schema_adapter import normalize_symbol
+            return normalize_symbol(s)
+        return s
+
+    return [Instrument(symbol=_sym(s), asset_type=AssetType.Stock) for s in symbols if s.strip()]
+
+
+def _recent_real_bars(symbols: list[str], days: int = 30) -> tuple[Any, str]:
+    """最近 N 天真实日线 → replay bars DataFrame (akquant dataframe_to_bars 格式).
+
+    数据源 = 本地 prebuilt bundle (真实历史, 与回测同源; bundle 覆盖到最新交易日).
+    返 (df, src): df 列 = date/open/high/low/close/volume/symbol + "股票代码" (多标的
+    识别必需, dataframe_to_bars normalize.py 只认这个列名).
+
+    Raises:
+        LiveRunError: 无 --symbols / 数据不可达 (提示先 dataset fetch).
+    """
+    from datetime import datetime, timedelta
+
+    from ..prebuilt_resolver import resolve
+
+    if not symbols:
+        raise LiveRunError(
+            "broker=replay 需要 --symbols 限定回放标的 (从本地 prebuilt 取最近真实数据)"
+        )
+    end = datetime.now().strftime("%Y%m%d")
+    start = (datetime.now() - timedelta(days=days)).strftime("%Y%m%d")
+    df, src = resolve(symbols, start, end)
+    if df is None or len(df) == 0:
+        raise LiveRunError(
+            f"最近 {days} 天无 bar 数据 (universe={symbols}, {start}~{end}, src={src}). "
+            f"先 `hamuna_quant_cli dataset fetch --symbols {','.join(symbols)}` 下载 prebuilt"
+        )
+    out = df.copy()
+    out["股票代码"] = out["symbol"]
+    return out, src
+
+
+def configure_logging(level: str, log_file: Path | None) -> None:
+    """调 akquant.configure_logging — profile=live 让 on_order/on_trade/网关 warning 进同一套输出."""
+    try:
+        import akquant
+        from akquant import LogConfig
+    except ImportError:
+        # 没装 akquant 也不致命 — 子命令会在 run_live 处抛更具体的 ImportError,
+        # 用户能从那条错误知道装包; 这里只警告
+        print(f"[warn] akquant 未安装, 跳过日志配置 (level={level})", flush=True)
+        return
+    cfg_kwargs: dict[str, Any] = {"profile": "live", "level": level, "console": True}
+    if log_file:
+        cfg_kwargs["file_json"] = True
+        cfg_kwargs["filename"] = str(log_file)
+    akquant.configure_logging(LogConfig(**cfg_kwargs))
+
+
+def _with_live_history_depth(cls: type) -> type:
+    """class mode 注入 set_history_depth — live 引擎不像回测 (engine.py:4637) 那样
+    自动开 history tracking, 策略 on_bar 里 get_history 直接抛
+    "History tracking is not enabled" (2026-08-19 实测). depth 取策略 on_start 设的
+    warmup_period, 未设默认 120.
+
+    ponytail: 只包 class mode; functional mode 用户自己管 get_history (ctx 侧).
+    """
+    from typing import Any as _Any
+
+    class _Wrapped(cls):
+        def on_start(self) -> _Any:
+            ret = super().on_start()
+            depth = getattr(self, "warmup_period", None) or 120
+            try:
+                self.set_history_depth(depth)
+            except Exception as e:  # noqa: BLE001 — depth 失败不应让 on_start 崩
+                print(f"[warn] set_history_depth({depth}) 失败: {e}", flush=True)
+            return ret
+
+    _Wrapped.__name__ = cls.__name__
+    _Wrapped.__qualname__ = cls.__qualname__
+    return _Wrapped
+
+
+def _live_safety_defaults(
+    mode: str,
+    broker: str,
+    gateway_options: dict[str, str],
+    duration: str,
+) -> str:
+    """P0-1/P0-2 实盘安全默认: broker_live+qmt 强制真实下单 + 永久运行.
+
+    原地改 gateway_options (注入 qmt_paper=0 或报错), 返回修正后的 duration.
+    """
+    if mode == "broker_live" and broker == "qmt":
+        paper_val = gateway_options.get("qmt_paper")
+        if paper_val is None:
+            gateway_options["qmt_paper"] = "0"
+            print("[info] broker_live 未显式 qmt_paper → 强制 0 (真实下单)", flush=True)
+        elif str(paper_val).strip().lower() in ("1", "true", "yes", "on"):
+            raise LiveRunError(
+                "broker_live + qmt_paper=1 矛盾: 真实盘模式不能 paper 下单. "
+                "要去掉 qmt_paper=1 或改用 --mode paper."
+            )
+
+        if duration == "1h":  # CLI 默认值 — 替换为永久
+            print("[info] broker_live 默认 duration=0 (永久运行); 如需限时显式传 --duration", flush=True)
+            return "0"
+        print(f"[warn] broker_live 使用显式 duration={duration} — 到期自动停止", flush=True)
+    return duration
+
+
+def run_live(
+    spec: StrategySpec,
+    *,
+    mode: str,
+    broker: str,
+    symbols: list[str] | None,
+    duration: str,
+    gateway_options_raw: str | None,
+    initial_cash: float | None,
+    log_level: str,
+    log_file: Path | None,
+    market_broker: str | None,
+    replay_days: int = 30,
+) -> None:
+    """翻译 + 转发到 akquant.run_live.
+
+    spec:        loader 加载出的 StrategySpec (class 或 functional)
+    mode:        "paper" / "broker_live"
+    broker:      "ctp" / "qmf" / "replay" / 自定义 broker 名字
+    market_broker: 独立行情 broker id (e.g. "qmt_market"); None=单 broker
+                   当 market_broker 设了, akquant 要求 trader_broker 也设 (二者成对, broker 字段被忽略).
+                   我们固定配对: market_broker="qmt_market" + trader_broker="qmt".
+    symbols:     CLI --symbols 拆分后的字符串列表, None = 全市场
+    duration:    字符串 ("30s" / "1h" / "2d"), akquant 自己解析
+    gateway_options_raw:  CLI 字符串, parse 成 dict 后透传
+    initial_cash: 回传给 run_live (None = akquant 默认)
+    """
+    gateway_options = parse_kv_pairs(gateway_options_raw)
+    duration = _live_safety_defaults(mode, broker, gateway_options, duration)
+    # replay broker 的 bars 数据 — 供 v2 architecture compute_factors 复用
+    replay_bars_df = None
+
+    # replay broker 必须配 trading_mode="paper" — 提前给出清晰错误, 而不是让 akquant 在深处抛
+    if broker == "replay" and mode == "broker_live":
+        raise LiveRunError(
+            "broker=replay + trading_mode=broker_live 不兼容 — replay 只有行情, "
+            "无交易通道, 用 broker_live 会抛 ValueError. 改用 mode=paper 或换 broker."
+        )
+
+    # broker=replay → 自动注入最近 N 天真实数据 (本地 prebuilt), paper 撮合走引擎.
+    # bounded_event_total 让回放完自动停, 不依赖 --duration 墙钟.
+    if broker == "replay":
+        bars_df, replay_src = _recent_real_bars(symbols, days=replay_days)
+        replay_bars_df = bars_df  # 供 v2 architecture compute_factors 复用
+        instruments = _build_instruments(sorted(bars_df["symbol"].unique()), normalize=True)
+        gateway_options["bars"] = bars_df
+        print(
+            f"[info] replay 数据: {replay_src} · {len(bars_df)} bars · "
+            f"{sorted(bars_df['symbol'].unique())} (最近 {replay_days} 天)",
+            flush=True,
+        )
+        if len(bars_df) < 60:
+            print(
+                f"[warn] bars < 60 — 有 warmup 的策略可能全程不触发 on_bar (0 交易). "
+                f"可加 --replay-days 扩大窗口 (e.g. --replay-days 180)",
+                flush=True,
+            )
+    else:
+        instruments = _build_instruments(symbols)
+        # run_live 始终要求至少 1 个 instrument (不是可选) — 不传 --symbols 时
+        # 用占位 sh600000, paper 模式 broker=qmt 不真下单, smoke 能跑通.
+        if not instruments:
+            instruments = _build_instruments(["sh600000"])
+    configure_logging(log_level, log_file)
+
+    # broker="qmt" → import 触发 register_broker("qmt", ...), 校验 qmt_account_id 必填.
+    # qmt_* 配置已经在 gateway_options dict 里 — akquant.run_live 会展开 dict 给 builder,
+    # 不要把 qmt_* 当成顶层 kwarg (run_live 显式签名, 会 TypeError).
+    if broker == "qmt":
+        try:
+            from . import qmt_broker  # noqa: F401  — 触发 register_broker("qmt")
+        except ImportError as e:
+            raise LiveRunError(
+                f"broker=qmt 需要 hamuna_quant_cli.live.qmt_broker (包内自带). 原因: {e}"
+            ) from e
+        if "qmt_account_id" not in gateway_options:
+            raise LiveRunError(
+                "broker=qmt 需要 qmt_account_id — 透传 --gateway-options "
+                "'qmt_account_id=8888888888,qmt_base_url=http://127.0.0.1:9000'"
+            )
+
+    # market_broker=qmt_market → import 触发 register_broker("qmt_market", ...).
+    # 自动配对 trader_broker=qmt: 我们约定 qmt_market + qmt 是 v2 QMT 行情+交易对 (行情
+    # 走 /data/snapshot+history, 交易走 5 交易端点, 同 bridge_server 同进程).
+    if market_broker == "qmt_market":
+        try:
+            from . import qmt_market  # noqa: F401  — 触发 register_broker("qmt_market")
+        except ImportError as e:
+            raise LiveRunError(
+                f"--market-broker=qmt_market 需要 hamuna_quant_cli.live.qmt_market (包内自带). 原因: {e}"
+            ) from e
+
+    # 延迟 import — 让 CLI 能在 akquant 未装环境跑 --help
+    try:
+        from akquant import run_live as _akquant_run_live
+    except ImportError as e:
+        raise LiveRunError(
+            f"akquant 未安装 — `pip install 'akquant>=0.3.41'`. 原因: {e}"
+        ) from e
+
+    # ===== v2 architecture (2026-08-18 简化): class mode 接入 compute_factors / filter_symbols =====
+    # 仅 class mode + 有 qmt_base_url (走 bridge_server /data/history) 时启用.
+    # functional mode / 无 bridge_url 跳过 (兼容老策略).
+    if spec.mode == "class" and spec.strategy_cls is not None:
+        qmt_base_url = gateway_options.get("qmt_base_url")
+        # replay (paper trading) 用本地 bars 数据; qmt 用 bridge /data/history.
+        # 两者都走 compute_factors / filter_symbols (v2 architecture).
+        has_replay_data = replay_bars_df is not None
+        if qmt_base_url or has_replay_data:
+            try:
+                strat_inst = spec.strategy_cls()
+            except Exception as e:
+                raise LiveRunError(
+                    f"实例化策略 {spec.strategy_cls.__name__} 失败: {e}"
+                ) from e
+
+            # 只有策略真有 compute_factors / filter_symbols 才需要 --symbols 限定 universe;
+            # 无因子 hook 的策略 (e.g. 双均线 on_bar 直算) 直接跑, 不拦 (desktop 启动器不传
+            # --symbols, 2026-08-19 实测: 无因子策略被误拦 → LiveRunError).
+            wants_precompute = (
+                hasattr(strat_inst, "compute_factors")
+                or hasattr(strat_inst, "filter_symbols")
+            )
+            if wants_precompute and not symbols:
+                raise LiveRunError(
+                    "实盘 compute_factors 必须传 --symbols 限定 universe (避免全市场 N×HTTP 超时). "
+                    "如不需要预计算因子, 走 functional mode 兼容路径."
+                )
+
+            if not wants_precompute:
+                print(
+                    f"[info] class mode 无 compute_factors/filter_symbols — 跳过预计算, "
+                    f"instrument={symbols or '<占位 sh600000>'}",
+                    flush=True,
+                )
+            else:
+                factors: dict[str, Any] = {}
+                if hasattr(strat_inst, "compute_factors"):
+                    # 实盘 startup: 拉 N sym × N bar 历史, 拼 {sym: DataFrame} 喂 compute_factors
+                    # qmt: bridge /data/history; replay: 本地 prebuilt bars (paper trading).
+                    try:
+                        if has_replay_data:
+                            raw_factors = replay_bars_df
+                        else:
+                            raw_factors = _fetch_live_factors(qmt_base_url, symbols)
+                    except LiveRunError:
+                        raise
+                    except Exception as e:
+                        raise LiveRunError(
+                            f"实盘拉历史失败: {type(e).__name__}: {e} "
+                            f"(用户原话: 出错直接报错停止, 不走 mock 兜底)"
+                        ) from e
+                    try:
+                        factors = strat_inst.compute_factors(raw_factors) or {}
+                    except Exception as e:
+                        raise LiveRunError(
+                            f"实盘 compute_factors 异常: {e} (用户原话: 出错直接报错停止, 不走 mock 兜底)"
+                        ) from e
+                    if not isinstance(factors, dict):
+                        raise LiveRunError(
+                            f"compute_factors 应返 dict[str, DataFrame], 实得 {type(factors).__name__}"
+                        )
+
+                filtered: list[str] = list(symbols)
+                if hasattr(strat_inst, "filter_symbols"):
+                    try:
+                        user_filtered = strat_inst.filter_symbols(factors)
+                    except Exception as e:
+                        raise LiveRunError(f"filter_symbols 异常: {e}") from e
+                    if not isinstance(user_filtered, (list, tuple)):
+                        raise LiveRunError(
+                            f"filter_symbols 应返 list[str], 实得 {type(user_filtered).__name__}"
+                        )
+                    user_filtered = [str(s) for s in user_filtered]
+                    if not user_filtered:
+                        import warnings as _w
+                        _w.warn(f"filter_symbols 返空, 退到 --symbols ({len(symbols)} syms)")
+                    else:
+                        known = set(symbols)
+                        bad = [s for s in user_filtered if s not in known]
+                        if bad:
+                            import warnings as _w
+                            _w.warn(
+                                f"filter_symbols 返了 --symbols 外的 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-live] filter_symbols: {len(symbols)} → {len(filtered)} symbols",
+                            flush=True,
+                        )
+
+                instruments = _build_instruments(filtered)
+        else:
+            print(
+                "[info] class mode 无 qmt_base_url / replay bars; 跳过 compute_factors / filter_symbols",
+                flush=True,
+            )
+    elif spec.mode == "functional":
+        print(
+            "[info] functional mode 跳过 compute_factors / filter_symbols (兼容路径)",
+            flush=True,
+        )
+
+    kwargs: dict[str, Any] = {
+        "broker": broker,
+        "trading_mode": mode,
+        "instruments": instruments,
+        "gateway_options": gateway_options,
+        "duration": duration,
+        "show_progress": False,
+    }
+    if initial_cash is not None:
+        kwargs["cash"] = initial_cash  # akquant 0.3.x run_live 参数名是 cash
+
+    # 行情/交易分家 — 必须成对: market_broker + trader_broker 同时给, akquant 忽略 broker.
+    if market_broker:
+        kwargs["market_broker"] = market_broker
+        # qmt_market 自动配对 trader_broker=qmt (v2 约定); 其它行情 broker 用户自己负责
+        kwargs["trader_broker"] = broker if market_broker == "qmt_market" else broker
+
+    # class mode vs functional mode — run_live 入参不同
+    if spec.mode == "class":
+        kwargs["strategy_cls"] = _with_live_history_depth(spec.strategy_cls)
+    else:
+        cbs = spec.callbacks or {}
+        kwargs["strategy_cls"] = cbs["on_bar"]
+        for hook in ("initialize", "on_order", "on_trade", "on_timer", "on_broker_connected"):
+            if hook in cbs:
+                kwargs[hook] = cbs[hook]
+
+    print(f"[info] hamuna_quant_cli live run: mode={mode} broker={broker} "
+          f"market_broker={market_broker or '<single>'} "
+          f"symbols={symbols or '<all>'} duration={duration}", flush=True)
+    print(f"[info] gateway_options={gateway_options}", flush=True)
+    _akquant_run_live(**kwargs)