hamuna-quant-cli 0.1.11__tar.gz → 0.1.13__tar.gz

{hamuna_quant_cli-0.1.11 → hamuna_quant_cli-0.1.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hamuna-quant-cli
-Version: 0.1.11
+Version: 0.1.13
 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.11 → hamuna_quant_cli-0.1.13}/hamuna_quant_cli/__init__.py

@@ -12,4 +12,4 @@ server (13-key metrics schema). 全部走 akquant 0.3.x 引擎.
 """
 from __future__ import annotations
 
-__version__ = "0.1.11"
+__version__ = "0.1.13"

{hamuna_quant_cli-0.1.11 → hamuna_quant_cli-0.1.13}/hamuna_quant_cli/__main__.py

@@ -332,9 +332,8 @@ def cmd_commit(args) -> int:
     bundle = 4 文件 (strategy + result + config + params). multipart params 字段
     = 整个 params.json 内容 (ADR-0025, desktop 实盘配置源).
 
-    Round 18.62 P0-1: 新增 step 1.5 replay diff gate — `--replay-result` 必填,
-    与 `--result` 算 sharpe diff, 超阈值 (HAMUNA_REPLAY_GATE_PCT 缺省 0.20) → exit 5.
-    server `UpdateStrategyResult` handler 二次校验防绕过.
+    Round 18.63: replay gate (P0-1) 移除 (用户决策) — 上传不再要求 replay_result,
+    `--replay-result` / `--skip-replay-gate` 参数已删.
 
     Round 18.62 P1-1: 新增 step 1.4 version bump — `GET /strategies/{id}` 拿
     `latest_version` (无 → "0.0.0"); 默认 patch 自动 bump (`0.0.0 → 0.0.1`),
@@ -345,7 +344,6 @@ def cmd_commit(args) -> int:
     from .runtime.server_client import ServerError
     import io
     import json
-    import os
     import re
     import tarfile
 
@@ -367,16 +365,6 @@ def cmd_commit(args) -> int:
     if params_path and not params_path.exists():
         print(f"params.json 不存在: {params_path} (--params 可选)", file=sys.stderr)
         return 2
-    # Round 18.62 P0-1: replay_result.json 必填 (除非 --skip-replay-gate qa 通道).
-    replay_path = Path(args.replay_result) if args.replay_result else None
-    if not args.skip_replay_gate:
-        if replay_path is None:
-            print("ERROR: P0-1: 必须传 --replay-result, 先跑 live run --broker replay 拿 metrics "
-                  "(或 --skip-replay-gate qa 通道)", file=sys.stderr)
-            return 2
-        if not replay_path.exists():
-            print(f"replay_result.json 不存在: {args.replay_result}", file=sys.stderr)
-            return 2
 
     # ----- Round 18.62 P1-1 step 1.4: version bump -----
     # cli 先 GET /strategies/{id} 拿 latest_version (无 → "0.0.0"); 默认 patch 自动 bump,
@@ -407,7 +395,7 @@ def cmd_commit(args) -> int:
     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/3: 打包 bundle (strategy + result + config + params + replay + version) ===",
+    print("=== Step 1/3: 打包 bundle (strategy + result + config + params + version) ===",
           file=sys.stderr)
     with tarfile.open(bundle_out, "w:gz") as tar:
         tar.add(strategy_path, arcname=strategy_path.name)
@@ -416,9 +404,6 @@ def cmd_commit(args) -> int:
             tar.add(cfg_path, arcname=cfg_path.name)
         if params_path:
             tar.add(params_path, arcname=params_path.name)
-        # Round 18.62 P0-1: replay_result.json 也打进去, 方便回溯 / 审计.
-        if replay_path:
-            tar.add(replay_path, arcname=replay_path.name)
         # Round 18.62 P1-1: version.json 内存写, audit 用 (server 不读, 仅本地回溯).
         ver_bytes = json.dumps({"version": new_version}, ensure_ascii=False).encode("utf-8")
         ver_info = tarfile.TarInfo(name="version.json")
@@ -426,40 +411,7 @@ def cmd_commit(args) -> int:
         tar.addfile(ver_info, io.BytesIO(ver_bytes))
     print(f"  ✓ bundle = {bundle_out} ({bundle_out.stat().st_size} bytes)", file=sys.stderr)
 
-    # ----- Round 18.62 P0-1 step 1.5: replay diff gate -----
-    # 必在 step 2 (PUT) 之前 — gate fail 后 step 2-3 都不跑, 不留半上传状态.
-    replay_metrics: dict | None = None
-    if not args.skip_replay_gate:
-        try:
-            bt = json.loads(result_path.read_text(encoding="utf-8"))
-            rp = json.loads(replay_path.read_text(encoding="utf-8"))  # type: ignore[union-attr]
-        except json.JSONDecodeError as e:
-            print(f"  ✗ result/replay JSON 解析失败: {e}", file=sys.stderr)
-            return 2
-        bt_sharpe = float(bt.get("metrics", {}).get("sharpe", 0.0))
-        rp_sharpe = float(rp.get("metrics", {}).get("sharpe", 0.0))
-        diff_pct = abs(rp_sharpe - bt_sharpe) / max(abs(bt_sharpe), 0.01)
-        try:
-            threshold = float(os.environ.get("HAMUNA_REPLAY_GATE_PCT", "0.20"))
-        except ValueError:
-            threshold = 0.20
-        if diff_pct > threshold:
-            print(f"ERROR: replay gate diff={diff_pct:.2%} > {threshold:.0%} "
-                  f"(backtest.sharpe={bt_sharpe:.4f} vs replay.sharpe={rp_sharpe:.4f})",
-                  file=sys.stderr)
-            return 5
-        replay_metrics = {
-            "sharpe": rp_sharpe,
-            "total_return": float(rp.get("metrics", {}).get("total_return", 0.0)),
-            "win_rate": float(rp.get("metrics", {}).get("win_rate", 0.0)),
-            "trades": len(rp.get("trades", [])),
-            "diff_pct": diff_pct,
-            "run_at": (rp.get("period") or {}).get("end"),
-        }
-        print(f"  ✓ replay gate pass (diff={diff_pct:.2%} <= {threshold:.0%}, "
-              f"replay.sharpe={rp_sharpe:.4f})", file=sys.stderr)
-
-    print("=== Step 2/3: PUT /strategies/:id/result (metrics + replay_metrics + version) ===",
+    print("=== Step 2/3: PUT /strategies/:id/result (metrics + version) ===",
           file=sys.stderr)
     try:
         result = json.loads(result_path.read_text(encoding="utf-8"))
@@ -468,7 +420,7 @@ def cmd_commit(args) -> int:
         return 2
     try:
         resp = runtime.server_client.upload_backtest_result(
-            sid, result, replay_metrics=replay_metrics, version=new_version,
+            sid, result, version=new_version,
         )
     except runtime.server_client.ServerError as e:
         print(f"  ✗ 上传 metrics 失败: {e}", file=sys.stderr)
@@ -646,7 +598,7 @@ def _bridge_kline(server: str, symbols: list[str], days: int) -> list[dict]:
     for sym in symbols:
         url = (
             f"{server}/data/history?security={urllib.parse.quote(sym)}"
-            f"&period=1d&count={days}&fq=None"
+            f"&period=1d&count={days}&fq=None&subscribe=false"
         )
         try:
             with urllib.request.urlopen(url, timeout=8) as resp:
@@ -1036,12 +988,6 @@ def build_parser() -> argparse.ArgumentParser:
     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 路径")
-    # Round 18.62 P0-1: replay gate. --replay-result 必填 (除非 --skip-replay-gate).
-    cm.add_argument("--replay-result", default=None,
-                    help="replay_result.json 路径 (P0-1 必填; 先跑 live run --broker replay 拿 metrics, "
-                         "或 --skip-replay-gate 跳过)")
-    cm.add_argument("--skip-replay-gate", action="store_true",
-                    help="[qa 临时] 跳过 replay diff gate (非 dev 默认)")
     # Round 18.62 P1-1: version bump. 默认 patch 自动 (从 server latest_version +0.0.1),
     # 显式 --major / --minor opt-in. 互斥.
     cm.add_argument("--major", action="store_true",

{hamuna_quant_cli-0.1.11 → hamuna_quant_cli-0.1.13}/hamuna_quant_cli/akquant_runner.py

@@ -46,63 +46,23 @@ class StrategyParamsError(RuntimeError):
 
 # ---- 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
+    """回测端 on_cross_section 调仓路径 — 与实盘 schedule_daily+on_timer 配对.
+
+    Round 24 真相修正 (前 Round 18.32 wrapper 声称 schedule+on_timer 注入, 但
+    `akquant.collect_cross_section_timer_entries` 只查 strategy 上
+    `_trading_day_cross_section_timestamps` 字段, 完全不消费 `strategy_scheduler`
+    里的 _schedule 注册 — 实测 0 trade). 真触发路径只有 on_cross_section.
 
-    if cls is None or "on_timer" not in getattr(cls, "__dict__", {}):
+    本 wrapper 改为: 不再吞 on_cross_section, 让策略层的 on_cross_section 自由
+    处理调仓 (用户策略层用 weekday/dedup 判定周频, Round 24 DIR-003 同型).
+    策略层若无 on_cross_section, 不 wrap (直接返回 cls, 让 engine 走 on_cross_section
+    默认 no-op, 不影响).
+    """
+    if cls is None or "on_cross_section" 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
+        pass
 
     _BacktestTimerRebalance.__name__ = cls.__name__
     _BacktestTimerRebalance.__qualname__ = cls.__qualname__

{hamuna_quant_cli-0.1.11 → hamuna_quant_cli-0.1.13}/hamuna_quant_cli/akquant_schema_adapter.py

@@ -8,12 +8,13 @@
 一致 (B 重写不动数值层). 迁移原因: v2 skill 未来独立分发, 不依赖仓根.
 
 字段映射 (15 metrics):
-  total_return ← r.metrics.total_return_pct / 100
-  annual_return ← r.metrics.annual_return_pct / 100  (akquant 直接给)
+  total_return ← r.metrics.total_return_pct / 100          (% → ratio)
+  annual_return ← r.metrics.annualized_return (0.3.52, 小数)
+                 或 r.metrics.annual_return_pct / 100      (0.3.41 legacy, %)
   sharpe ← r.metrics.sharpe_ratio
   max_drawdown ← r.metrics.max_drawdown_pct / 100
   volatility ← 自算 (np.std(daily_ret) * sqrt(252), 沿 metrics.py:63)
-  win_rate ← r.metrics.win_rate
+  win_rate ← r.metrics.win_rate / 100                      (% → 0~1; 0 平仓 → None)
   profit_loss_ratio ← 自算 from trades_df (FIFO pair, 沿 metrics.py:104)
   avg_holding_period ← 自算 calendar days (沿 metrics.py:155)
   benchmark_total_return ← NaN (akquant 单策略无自动基准, 见 bench_20260813_201349.json)
@@ -24,6 +25,11 @@
   profit_factor ← 自算 from trades_df (沿 metrics.py:192)
   annual_volatility ← alias of volatility
 
+> ⚠ 0.3.41 → 0.3.52 键名漂移 (2026-09-02 真回测校准):
+>   `annual_return_pct` → `annualized_return` (且单位从 % 变为小数);
+>   `final_value` → `end_market_value`; `win_rate` 两版都是 %, 需 /100.
+>   读取统一走 `_metric(obj, _METRIC_ALIASES[i])`, 两版兼容.
+
 equity_curve: r.equity_curve() Series → [{date:'YYYYMMDD', nav: float}, ...]
   首日补 initial_capital (driver.py:103-106 同款)
 
@@ -37,7 +43,8 @@ monthly_bars / monthly_metrics: 自算 (沿 metrics.py:242+)
 
 initial_capital / final_capital / avg_holding_period / suggestions:
   - initial_capital = cfg['init_capital']
-  - final_capital = r.metrics.final_value (若 akquant 给) 或 equity_curve 末点
+  - final_capital = r.metrics.end_market_value (0.3.52) / final_value (0.3.41),
+                    或 equity_curve 末点 (fallback)
   - avg_holding_period = metrics 内同名字段
   - suggestions = [] (Phase B 最小化; driver._suggestions 不复用)
 
@@ -97,6 +104,36 @@ def _safe_get(obj: Any, key: str, default: float = float('nan')) -> float:
     return f
 
 
+# akquant 0.3.41 → 0.3.52 键名漂移 (2026-09-02 真回测校准):
+#   0.3.41 用 `annual_return_pct` (%, /100) / `final_value`;
+#   0.3.52 改为 `annualized_return` (小数, 直接取) / `end_market_value`.
+# `win_rate` 两个版本都是 % (有平仓时 70.0 = 70%), Hamuna 契约要 0~1 → /100.
+_METRIC_ALIASES: list[tuple[tuple[str, float], ...]] = [
+    # (候选键名, 换算 scale) — 键存在即取, scale 对齐 Hamuna ratio 契约
+    (('total_return_pct', 1.0 / 100.0),),                                  # % → ratio
+    (('annualized_return', 1.0), ('annual_return_pct', 1.0 / 100.0)),      # 0.3.52 小数 | 0.3.41 %
+    (('sharpe_ratio', 1.0),),
+    (('max_drawdown_pct', 1.0 / 100.0),),                                  # % → ratio
+    (('win_rate', 1.0 / 100.0),),                                          # % → ratio (0~1)
+    (('end_market_value', 1.0), ('final_value', 1.0)),                     # 0.3.52 | 0.3.41
+]
+
+
+def _metric(obj: Any, aliases: tuple[tuple[str, float], ...],
+            default: float = float('nan')) -> float:
+    """按候选键名读取 metric, 兼容版本键名漂移.
+
+    aliases: ((键名, scale), ...) 按优先序; 取第一个在 obj 上真实存在的键,
+    返回值 = 原值 × scale. 全部缺失 → default (NaN). 与 _safe_get 的
+    "missing 与 0.0 不混淆" 语义一致 (float 转换失败/NaN/Inf 也返回 default).
+    """
+    for key, scale in aliases:
+        v = _safe_get(obj, key, default=float('nan'))
+        if not math.isnan(v):
+            return v * scale
+    return default
+
+
 def _nan() -> float:
     return float('nan')
 
@@ -206,13 +243,19 @@ def to_hamuna_result(akquant_r: Any, cfg: dict) -> dict:
     equity_curve = _to_daily(eq_curve, initial_capital)
     nav_values = [p['nav'] for p in equity_curve]
 
-    # 15 metrics
+    # 15 metrics — 键名走 `_metric` 别名 (0.3.41/0.3.52 兼容, 见 _METRIC_ALIASES)
     m = getattr(akquant_r, 'metrics', None)
-    total_return = _safe_get(m, 'total_return_pct', 0.0) / 100.0 if m else _nan()
-    annual_return = _safe_get(m, 'annual_return_pct', _nan()) / 100.0 if m else _nan()
-    sharpe = _safe_get(m, 'sharpe_ratio', _nan()) if m else _nan()
-    mdd = _safe_get(m, 'max_drawdown_pct', _nan()) / 100.0 if m else _nan()
-    win_rate = _safe_get(m, 'win_rate', _nan()) if m else _nan()
+    total_return = _metric(m, _METRIC_ALIASES[0], 0.0) if m else _nan()
+    annual_return = _metric(m, _METRIC_ALIASES[1]) if m else _nan()
+    sharpe = _metric(m, _METRIC_ALIASES[2]) if m else _nan()
+    mdd = _metric(m, _METRIC_ALIASES[3]) if m else _nan()
+    win_rate = _metric(m, _METRIC_ALIASES[4]) if m else _nan()
+    # 0 closed pair (trades_df 空) 时 AKQuant metrics.win_rate 为 0.0, 但 Hamuna 契约
+    # 要 None (backtest-result.md: 0 trades → win_rate=None). trades_df 才是 closed
+    # pair 源 (executions_df 含 buy-only 流水, 不能用来判"有无已平仓交易").
+    closed_pair_empty = trades_df is None or trades_df.empty
+    if closed_pair_empty:
+        win_rate = _nan()
     # 自算
     volatility = _volatility(nav_values) if nav_values else 0.0
     sortino = _sortino(nav_values) if nav_values else 0.0
@@ -247,8 +290,8 @@ def to_hamuna_result(akquant_r: Any, cfg: dict) -> dict:
     monthly_bars = _monthly_bars(equity_curve)
     monthly_metrics = _monthly_metrics(equity_curve)
 
-    # final_capital
-    final_capital = _safe_get(m, 'final_value', float('nan')) if m else _nan()
+    # final_capital: end_market_value (0.3.52) / final_value (0.3.41) → fallback equity 末点
+    final_capital = _metric(m, _METRIC_ALIASES[5], float('nan')) if m else _nan()
     if math.isnan(final_capital) and equity_curve:
         final_capital = equity_curve[-1]['nav']
     final_capital = None if isinstance(final_capital, float) and math.isnan(final_capital) else final_capital
@@ -434,14 +477,29 @@ def _json_safe(o: Any) -> Any:
     场景: akquant orders_df 等原始曲面的 limit_price/stop_price 常见 NaN
     (市价单/未触发单). 直接进 result 会让后端 json.loads 崩.
     Round 18.16 真数据验证抓到的真实泄漏 (Round 3 NaN 待办真载体).
+    Round 18.62+ 实测补漏: DataFrame.to_dict 会把 DatetimeIndex/时间列转成
+    pandas.Timestamp / datetime — json.dumps 抛 TypeError, 一并转 ISO 字符串.
     """
-    import math
+    import datetime as _dt
     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]
+    # pandas.Timestamp 是 datetime 子类 → 先判 Timestamp 再判 datetime, 顺序无所谓
+    if isinstance(o, _dt.datetime):
+        return o.isoformat()
+    if isinstance(o, _dt.date):
+        return o.isoformat()
+    if isinstance(o, _dt.timedelta):
+        # orders_df.duration = exit - entry (timedelta) — JSON 无原生类型, 转秒
+        return o.total_seconds()
+    if hasattr(o, 'isoformat'):  # 兜底: np.datetime64 等
+        try:
+            return o.isoformat()
+        except Exception:  # noqa: BLE001
+            pass
     return o
 
 
@@ -475,12 +533,19 @@ def _selfcheck() -> None:
             "设置 HAMUNA_SELFTEST=1 显式启用."
         )
     class _MockMetrics:
+        """0.3.52 真实键 (2026-09-02 实测校准):
+        - total_return_pct = % (5.0 表示 5%) → ratio 0.05
+        - annualized_return = 小数 (0.12 表示 12%), 无 annual_return_pct
+        - max_drawdown_pct = % (8.0 表示 8%) → ratio 0.08
+        - win_rate = % (60.0 表示 60%) → ratio 0.6; 无 closed pair 时为 0.0
+        - end_market_value (金额), 无 final_value
+        """
         total_return_pct = 5.0
-        annual_return_pct = 12.0
+        annualized_return = 0.12
         sharpe_ratio = 1.2
         max_drawdown_pct = 8.0
-        win_rate = 0.6
-        final_value = 1_050_000.0
+        win_rate = 60.0
+        end_market_value = 1_050_000.0
 
     class _MockEquityCurve:
         def __init__(self):
@@ -509,6 +574,9 @@ def _selfcheck() -> None:
         # NaN 泄漏回归: orders_df 的 limit_price 常态 NaN (市价单), 必须被 _json_safe 清掉
         orders_df = [{'symbol': '600000.SH', 'limit_price': float('nan'),
                       'stop_price': float('nan'), 'filled': 100}]
+        # Timestamp 泄漏回归 (Round 18.62+ 实测): exposure_df 的 date 列 to_dict
+        # 后是 pandas.Timestamp, json.dumps 会 TypeError — 必须转 ISO 字符串.
+        exposure_df = [{'date': pd.Timestamp('2024-01-05'), 'gross': 1.2}]
 
     cfg = {
         'backtest_start': '20240101',
@@ -521,6 +589,14 @@ def _selfcheck() -> None:
     # 15 metrics
     assert set(result['metrics'].keys()) == HAMUNA_METRICS_15, (
         f'metrics key 缺/多: {set(result["metrics"].keys()) ^ HAMUNA_METRICS_15}')
+    # 单位转换断言 (0.3.52 键名/单位校准, 2026-09-02):
+    # total_return_pct=5.0(%) → 0.05; annualized_return=0.12(小数) → 0.12;
+    # max_drawdown_pct=8.0(%) → 0.08; win_rate=60.0(%) → 0.6.
+    mt = result['metrics']
+    assert abs(mt['total_return'] - 0.05) < 1e-9, mt['total_return']
+    assert abs(mt['annual_return'] - 0.12) < 1e-9, mt['annual_return']
+    assert abs(mt['max_drawdown'] - 0.08) < 1e-9, mt['max_drawdown']
+    assert abs(mt['win_rate'] - 0.6) < 1e-9, mt['win_rate']
     # 13 顶层 key (driver.py:113-128: metrics/equity_curve/benchmark_curve/trades/universe/
     # period/params/monthly_bars/monthly_metrics/initial_capital/final_capital/avg_holding_period/suggestions)
     expected_top = {'metrics', 'equity_curve', 'benchmark_curve', 'trades', 'universe',
@@ -543,10 +619,30 @@ def _selfcheck() -> 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
+    # Timestamp 泄漏回归 (Round 18.62+): 时间值必须转 ISO 字符串, 否则 json.dumps TypeError
+    edf = result['params']['_akquant_extra']['exposure_df']
+    assert edf[0]['date'] == '2024-01-05T00:00:00', f'Timestamp 应转 ISO, got {edf[0]["date"]!r}'
     import json
-    json.dumps(result)  # strict JSON 序列化 — NaN 会 raise ValueError
+    json.dumps(result)  # strict JSON 序列化 — NaN 会 raise ValueError, Timestamp 会 TypeError
     print('OK: akquant_schema_adapter 15 metrics + 13 顶层 key + 7 trades fields + NaN 清理 全对齐')
 
+    # 0.3.41 legacy 键兼容 (annual_return_pct=12.0 % → 0.12; final_value=1050000):
+    class _LegacyMetrics:
+        total_return_pct = 5.0
+        annual_return_pct = 12.0
+        sharpe_ratio = 1.2
+        max_drawdown_pct = 8.0
+        win_rate = 60.0
+        final_value = 1_050_000.0
+
+    class _LegacyResult(_MockResult):
+        metrics = _LegacyMetrics()
+
+    legacy = to_hamuna_result(_LegacyResult(), cfg)
+    assert abs(legacy['metrics']['annual_return'] - 0.12) < 1e-9, legacy['metrics']['annual_return']
+    assert legacy['final_capital'] == 1_050_000.0, legacy['final_capital']
+    print('OK: 0.3.41 legacy 键 (annual_return_pct / final_value) 兼容')
+
 
 if __name__ == '__main__':
     _selfcheck()

{hamuna_quant_cli-0.1.11 → hamuna_quant_cli-0.1.13}/hamuna_quant_cli/live/qmt_broker.py

@@ -66,6 +66,7 @@ def _import_akquant_gateway():
 # (transient failure 自动重试; 4xx/业务错误不重试)
 # ============================================================
 import json
+import time
 from typing import Any
 
 import requests
@@ -383,6 +384,19 @@ def _make_trader_gateway():
             if order_id:
                 self.record_broker_order(order_id, req.client_order_id)
             # 即便 order_id 空 (bridge 的 submit_unknown), 也返回它拿到的 ref, 让上层知道.
+            if not order_id:
+                # Round 26 修复: bridge passorder_return=0 时 order_id/order_ref 都空,
+                # 但 bridge 已经把 qmt_user_order_id 写到了 QMT m_strRemark (Round 27 后
+                # bridge 会主动 poll 找真 order_id 并写到响应里). 此处 fallback:
+                #   1) qmt_user_order_id 优先 (bridge 内的稳定 key, 跨重启也保留)
+                #   2) passorder_return 兜底 (xtquant passorder 返回值, 0/正整数都允许)
+                # 任一非空都 record_broker_order, 让 akquant _sync_order_id_mapping
+                # (line 2072 of akquant/_runner.py) 不会因 broker_order_id 空而跳过.
+                fallback_id = (str(data.get("qmt_user_order_id") or "")
+                               or str(data.get("passorder_return") or ""))
+                if fallback_id and fallback_id not in ("0", "0.0"):
+                    self.record_broker_order(fallback_id, req.client_order_id)
+                    return fallback_id
             return order_id or str(data.get("passorder_return") or "")
 
         # ----- 撤单 -----
@@ -511,6 +525,92 @@ def _make_trader_gateway():
             except BrokerHTTPError:
                 return False
 
+        # ----- Round 26 补齐: akquant Protocol sync_* 方法 -----
+        # akquant BrokerRecovery (live/_runner.py:1800) 每 30s 调 sync_open_orders /
+        # sync_today_trades, 期望返回 UnifiedOrderSnapshot / UnifiedTrade 列表.
+        # qmt 路径默认 TraderGatewayBase.sync_* 返 [], 导致 on_order/on_trade 永远
+        # 收不到回报 (Round 26 0 trade 主因之一). 这里 override 走 query_* + 反查表.
+        #
+        # Round 28+ — bridge ensure_cache 同步阻塞老问题 cascade:
+        #   bridge _QMT_EXECUTOR 4 线程被 download_history_data 占满 → /orders HTTP hang
+        #   → sync_open_orders 每 30s 触发 query_order 累积 5s×N → on_order 永远收不到.
+        # Fix: TTL local cache (30s 内复用, 不重复 HTTP) + HTTP 失败返 last known good
+        # (不抛, 降级). 配合 bridge ensure_cache 异步化 (Round 28+ 改动 #1).
+        _sync_cache_ttl: float = 30.0
+        _sync_orders_cache: tuple = (0.0, [])  # (monotonic_ts, result_list)
+        _sync_trades_cache: tuple = (0.0, [])
+
+        def sync_open_orders(self):  # type: ignore[override]
+            """调 query_order per known broker_order_id, 聚合未完成订单.
+
+            Round 28+: TTL cache + 失败降级返 last known good.
+
+            已知 broker_order_id 来源:
+              1) self._client_id_by_broker (record_broker_order 写入, TraderGatewayBase)
+              2) self._broker_to_client_order_ids (akquant 内部维护)
+            任一找不到的 fallback 调 query_order(client_order_id=client_oid).
+            """
+            if not self._connected:
+                return []
+            # Round 28+: TTL cache — 30s 内复用避免 bridge hang 时重复 HTTP
+            now = time.monotonic()
+            ts, cached = self._sync_orders_cache
+            if cached and (now - ts) < self._sync_cache_ttl:
+                return cached
+            ak = _import_akquant_gateway()
+            UnifiedOrderSnapshot = ak["UnifiedOrderSnapshot"]
+            known_ids: set[str] = set()
+            client_map = getattr(self, "_client_id_by_broker", {})
+            known_ids.update(str(k) for k in client_map.keys() if k)
+            snapshots: list = []
+            seen: set[str] = set()
+            any_success = False
+            for bid in known_ids:
+                if not bid or bid in seen:
+                    continue
+                seen.add(bid)
+                try:
+                    snap = self.query_order(bid)
+                    if snap is not None:
+                        snapshots.append(snap)
+                        any_success = True
+                except Exception as e:  # noqa: BLE001
+                    print(f"[qmt-broker] sync_open_orders {bid} error: "
+                          f"{type(e).__name__}: {e}", flush=True)
+            # Round 28+: 全失败且有 cache → 降级返 cache (桥 hang 时不抛, 保 fire 不死)
+            if not any_success and cached:
+                print(f"[qmt-broker] sync_open_orders 全失败, 降级返 cache "
+                      f"({len(cached)} 条, age={now - ts:.1f}s)", flush=True)
+                return cached
+            # 成功 → 更新 cache
+            self._sync_orders_cache = (now, snapshots)
+            return snapshots
+
+        def sync_today_trades(self):  # type: ignore[override]
+            """调 query_trades (无 since) 拉当日所有成交, 30s 周期.
+
+            Round 28+: TTL cache + 失败降级.
+            """
+            if not self._connected:
+                return []
+            now = time.monotonic()
+            ts, cached = self._sync_trades_cache
+            if cached and (now - ts) < self._sync_cache_ttl:
+                return cached
+            try:
+                result = self.query_trades(since=None)
+                self._sync_trades_cache = (now, list(result))
+                return result
+            except Exception as e:  # noqa: BLE001
+                if cached:
+                    print(f"[qmt-broker] sync_today_trades HTTP 失败, 降级返 cache "
+                          f"({len(cached)} 条, age={now - ts:.1f}s): "
+                          f"{type(e).__name__}: {e}", flush=True)
+                    return cached
+                print(f"[qmt-broker] sync_today_trades error: "
+                      f"{type(e).__name__}: {e}", flush=True)
+                return []
+
     return QmtTraderGateway