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

hamuna_quant_cli/qmt_translator.py

@@ -0,0 +1,609 @@
+"""akquant Strategy → QMT body 转换器 (本地 stub, 真值由 cloud export endpoint 渲染).
+
+设计意图 (per `skills/hamuna-strategy-v2/references/qmt-export.md` §转换):
+  - body 用 QMT 原生签名 (`def init(C)` + `def handlebar(C)` + `passorder`/`C.get_market_data_ex`)
+  - CLI 端 driver / Context 适配 (v2 时代由 akquant 适配) — 双跑靠 "body 零翻译 + shim 状态代理"
+  - 本地 translator **仅产出 audit/对照版 QMT body**, 真值由 server 端
+    `POST /api/v1/strategies/:id/export` 重新渲染 shell + 嵌入 embedded API key + 签 cert
+
+**支持的 API 映射** (8 类, 够覆盖 BuyHold / DualMA / LowVolTopK / CrossSection 主流形态):
+  - `self.subscribe(sym)` → `C.subscribe(sym)`
+  - `self.buy(sym, qty)` / `self.sell(sym, qty)` → `passorder(23|24, 1101, "", sym, 11, -1, qty, "", 0, "buy|sel", C)`
+  - `self.get_position(sym)` → `C.holdings.get(sym, {}).get('qty', 0)`
+  - `self.get_history(n, sym, field)` → `C.get_market_data_ex(...)` + iloc 取 numpy
+  - `self.order_target_percent(pct, symbol=s)` → 计算 qty + 双向 passorder (helper function)
+  - `self.add_daily_timer('HH:MM:SS', 'name')` → `C.run_time('name', '1d', 'HH:MM:SS')`
+  - `bar.timestamp` → `timetag_to_datetime(C.get_bar_timetag(C.barpos), '%Y%m%d%H%M%S')`
+  - `bar.symbol` → `bar.code` (QMT Bar 字段差异)
+
+**不支持的形态** → raise NotImplementedError (exit 3):
+  - on_order / on_trade / on_stop (复杂事件 hook)
+  - lambda / starred args / kwargs spread / walrus operator
+  - get_history 之外的 akquant 数据 API (e.g. get_history_df)
+
+**designer-spec 驱动 CONFIG**:
+  - `_build_config_py` 从 spec_strategy.json 的 state_attrs / data_dependencies 启发式
+    提取默认值 (`默认 X` / `default X` / `= X` / `top X` 等)
+  - CONFIG 块含 audit trail (perf_arch.mode / direction_id) — QMT 端不用, 仅 diff 对照
+
+**py3.6 硬约束** (per qmt-export.md §QMT runtime):
+  - 头部 `# -*- coding: gbk -*-`
+  - 不写 f-string 3.7+ 特性
+  - 不写 `list[...]`/`dict[...]` 注解 (3.9+; 改 typing.List / typing.Dict)
+  - 不写 walrus `:=` / 3.8+ positional-only / 3.10+ match
+
+ADR-0023 (cloud QMT export shell) + ADR-0025 (CONFIG block) 契约:
+  - body 顶部 `CONFIG = {...}` 由 spec_strategy.json + config.json 拼
+  - 顶部 `# === HAMUNA_APIV1 === <api_key> === END ===` 由 cloud 端 export endpoint 注入, 本地不加
+"""
+from __future__ import annotations
+
+import ast
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+# ===== 模板片段 =====
+
+QMT_HEADER = '''# -*- coding: gbk -*-
+# Auto-generated by strategy_cli qmt-translate (本地 stub; 真值由 cloud hamuna export 渲染).
+# ADR-0023: cloud QMT shell 是 source of truth, body 由 cloud 端 init() 时拉取.
+# 本文件 = audit/对照版. 不要直接放入 QMT (无 embedded API key + cert, init() 会失败).
+CONFIG = {config_py}
+
+
+'''
+
+QMT_INIT_TEMPLATE = '''def init(C):
+    C = _wrap_context(C) if globals().get("_wrap_context") else C
+    # ===== init body (translated from akquant on_start) =====
+{init_body}
+
+'''
+
+
+QMT_HANDLEBAR_TEMPLATE = '''def handlebar(C):
+    if not C.is_last_bar():
+        return
+    # ===== handlebar body (translated from akquant on_bar) =====
+{handlebar_body}
+
+'''
+
+
+# ===== API 映射规则 =====
+
+# akquant self.<method> → QMT <expression> (lambda 形式, 接受 self + args)
+API_MAP: dict[str, str] = {
+    "subscribe": "C.subscribe({args[0]!r})",
+    # buy/sell 在 handlebar 上下文里要拆 qty + price, 见 _translate_call 特殊处理
+}
+
+
+def _walk_call(node: ast.Call) -> tuple[str, list[tuple[str, bool]]]:
+    """递归把 ast.Call 转成 ('func_name', [(arg_repr, is_literal), ...]).
+
+    is_literal=True 表示原 arg 是 ast.Constant (字符串/数字/None); caller 用 !r quote.
+    is_literal=False 表示 arg 是 Name / Attribute / Call (e.g. 变量 sym); caller 直插.
+
+    只支持简单形: f(a, b, ...) 其中 f 是名字 / 简单 attribute, a/b 是常量 / 名字 / attribute.
+    """
+    func = node.func
+    if isinstance(func, ast.Name):
+        name = func.id
+    elif isinstance(func, ast.Attribute):
+        name = func.attr  # e.g. self.buy → 'buy' (caller already routed by method)
+    else:
+        raise NotImplementedError(
+            f'QMT 转换器不支持嵌套调用: {ast.unparse(func)!r} ('
+            f'用户手写 QMT body 或简化)'
+        )
+    args: list[tuple[str, bool]] = []
+    for arg in node.args:
+        if isinstance(arg, ast.Constant):
+            args.append((repr(arg.value), True))
+        else:
+            args.append((ast.unparse(arg), False))
+    return name, args
+
+
+def _q(arg: tuple[str, bool]) -> str:
+    """透传: literal 在 _walk_call 里已用 repr() quote, expr 直接 unparse."""
+    return arg[0]
+
+
+def _translate_buy_sell(node: ast.Call, action: str) -> str:
+    """self.buy(sym, qty) / self.sell(sym, qty) → passorder 行.
+
+    QMT passorder(op, orderType, accountid, code, prType, price, qty, strategyName, quickTrade, remark, C)
+      op=23 buy / op=24 sell
+      orderType=1101 (限价) / 1102 (市价) — 用 1101 + prType=11 LATEST
+      prType=11 (最新价) — QMT 自动取最新成交价, 不需算 price
+      quickTrade=0 (handlebar 末根生效) — 与 CLI T+1 settle 对齐
+      remark < 24 chars
+    """
+    _, args = _walk_call(node)
+    if len(args) != 2:
+        raise NotImplementedError(
+            f'buy/sell 仅支持 (sym, qty) 形式; 当前 args={args}'
+        )
+    sym_expr, qty_expr = args[0][0], args[1][0]
+    op = 23 if action == "buy" else 24
+    return (
+        f'passorder({op}, 1101, "", {sym_expr}, 11, -1, '
+        f'{qty_expr}, "", 0, "{action[:3]}", C)'
+    )
+
+
+def _translate_get_position(node: ast.Call) -> str:
+    """self.get_position(sym) → C.holdings.get(sym, {}).get('qty', 0)."""
+    _, args = _walk_call(node)
+    if len(args) != 1:
+        raise NotImplementedError(f'get_position 仅 (sym); 当前 args={args}')
+    sym_expr = args[0][0]
+    return f"C.holdings.get({sym_expr}, {{}}).get('qty', 0)"
+
+
+def _translate_get_history(node: ast.Call) -> str:
+    """self.get_history(n, sym, field) → _hamuna_get_history(n, sym, field).
+
+    输出调用 helper (QMT body 顶部生成 _hamuna_get_history 函数):
+      from akquant-style signature → C.get_market_data_ex → iloc 取 numpy 数组.
+
+    QMT 端 get_market_data_ex 返 {sym: DataFrame}; iloc[-n:] 取最后 n 行; .values 返 numpy —
+    兼容 akquant np.mean / np.std 等.
+    """
+    _, args = _walk_call(node)
+    if len(args) != 3:
+        raise NotImplementedError(
+            f'get_history 仅支持 (n, sym, field); 当前 args={args}'
+        )
+    n_expr, sym_expr = args[0][0], args[1][0]
+    field_expr = _q(args[2])
+    return (
+        f'_hamuna_get_history({n_expr}, {sym_expr}, {field_expr}, '
+        f'CONFIG["period"], CONFIG["backtest_start"], CONFIG["backtest_end"])'
+    )
+
+
+def _translate_order_target_percent(node: ast.Call) -> str:
+    """self.order_target_percent(pct, symbol=s) → _hamuna_order_target_percent.
+
+    QMT body 顶部生成 _hamuna_order_target_percent helper: 算 target_value + last price
+    + qty (100 股取整) + 双向 passorder (qty>0 buy / qty<0 sell).
+
+    Args 解析:
+      pct  = positional[0]
+      symbol = kwargs['symbol']  (或 positional[1])
+    """
+    if not node.args:
+        raise NotImplementedError(f'order_target_percent 缺 pct; 当前 {ast.unparse(node)}')
+    pct_expr = ast.unparse(node.args[0])
+    sym_kw = next((kw for kw in node.keywords if kw.arg == "symbol"), None)
+    if sym_kw is None:
+        raise NotImplementedError(
+            f'order_target_percent 缺 symbol= kwarg; 当前 {ast.unparse(node)}'
+        )
+    sym_expr = ast.unparse(sym_kw.value)
+    return (
+        f'_hamuna_order_target_percent({pct_expr}, {sym_expr}, '
+        f'C, CONFIG["init_capital"])'
+    )
+
+
+def _translate_add_daily_timer(node: ast.Call) -> str:
+    """self.add_daily_timer('HH:MM:SS', 'name') → C.run_time('name', '1d', 'HH:MM:SS').
+
+    QMT run_time 是日级定时器 (per qmt_coding_spec §11 / §10): 第三个参 'HH:MM:SS'.
+    akquant add_daily_timer 第一参是时间, 第二参是 name (回调 key) — 翻译时换位.
+    """
+    _, args = _walk_call(node)
+    if len(args) != 2:
+        raise NotImplementedError(
+            f'add_daily_timer 仅支持 (time_str, name); 当前 args={args}'
+        )
+    time_quoted = _q(args[0])
+    name_quoted = _q(args[1])
+    return f'C.run_time({name_quoted}, "1d", {time_quoted})'
+
+
+def _translate_call(node: ast.Call) -> str:
+    """translate 一个 ast.Call 节点到 QMT 代码片段."""
+    func = node.func
+    # 非 self.<method> 调用 (numpy array.mean() / pd.Series() / print(...) 等) →
+    # 递归翻译 value, 保留 method 链. numpy/pandas 自带 API QMT 端兼容.
+    if isinstance(func, ast.Attribute) and not (
+        isinstance(func.value, ast.Name) and func.value.id == "self"
+    ):
+        receiver = _translate_expr(func.value)
+        args_str = ", ".join(_translate_expr(a) for a in node.args)
+        kwargs_str = ", ".join(
+            f"{kw.arg}={_translate_expr(kw.value)}" for kw in node.keywords
+        )
+        all_args = ", ".join(filter(None, [args_str, kwargs_str]))
+        return f"{receiver}.{func.attr}({all_args})"
+    if not isinstance(func, ast.Attribute):
+        raise NotImplementedError(f'不支持非 attribute 调用: {ast.unparse(node.func)}')
+    method = func.attr
+    if method == "buy":
+        return _translate_buy_sell(node, "buy")
+    if method == "sell":
+        return _translate_buy_sell(node, "sell")
+    if method == "get_position":
+        return _translate_get_position(node)
+    if method == "subscribe":
+        _, args = _walk_call(node)
+        sym_expr = args[0][0]
+        return f"C.subscribe({sym_expr})"
+    if method == "get_history":
+        return _translate_get_history(node)
+    if method == "order_target_percent":
+        return _translate_order_target_percent(node)
+    if method == "add_daily_timer":
+        return _translate_add_daily_timer(node)
+    raise NotImplementedError(
+        f'QMT 转换器未实现 self.{method}(...) ('
+        f'用户手写 QMT body 或等 cloud export endpoint 完整渲染)'
+    )
+
+
+def _translate_expr(node: ast.AST) -> str:
+    """递归 translate 一个表达式节点 (含 self.xxx 调用替换 + 其它原样)."""
+    if isinstance(node, ast.Call):
+        return _translate_call(node)
+    if isinstance(node, ast.Constant):
+        return repr(node.value)
+    if isinstance(node, ast.Name):
+        # self / bar / C / CONFIG → 直译 (handlebar 内 C 已是参数名)
+        return node.id
+    if isinstance(node, ast.Attribute):
+        # bar.symbol / bar.close 等 — QMT Bar 字段名一致, 直译
+        return ast.unparse(node)
+    if isinstance(node, ast.Compare):
+        # left op1 cmp1 op2 cmp2 ... — 递归翻译 left + comparators
+        left = _translate_expr(node.left)
+        parts = [left]
+        for op, comp in zip(node.ops, node.comparators):
+            op_str = {ast.Eq: '==', ast.NotEq: '!=', ast.Lt: '<', ast.LtE: '<=',
+                      ast.Gt: '>', ast.GtE: '>='}.get(type(op), ast.unparse(op))
+            parts.append(op_str)
+            parts.append(_translate_expr(comp))
+        return ' '.join(parts)
+    if isinstance(node, ast.BoolOp):
+        op_str = 'and' if isinstance(node.op, ast.And) else 'or'
+        return f" {op_str} ".join(_translate_expr(v) for v in node.values)
+    if isinstance(node, ast.BinOp):
+        return ast.unparse(node)
+    if isinstance(node, ast.Subscript):
+        return ast.unparse(node)
+    raise NotImplementedError(f'QMT 转换器不支持表达式: {ast.unparse(node)}')
+
+
+def _translate_stmt(stmt: ast.stmt, indent: int = 0) -> str:
+    """translate 一个 statement (if / for / expr / assign / return / pass).
+
+    indent = 当前 statement 所在层的首行缩进. 复合语句 (if/for) 内 body 按 indent+4 继续.
+    caller 给 init/handlebar 顶层 stmt 传 4, 嵌套 _translate_stmt 内部 indent+4.
+    """
+    pad = " " * indent
+    body_pad = " " * (indent + 4)
+    if isinstance(stmt, ast.If):
+        test = _translate_expr(stmt.test)
+        body_strs = [_translate_stmt(s, indent + 4) for s in stmt.body]
+        body = "\n".join(body_strs)
+        else_body = ""
+        if stmt.orelse:
+            else_body_strs = [_translate_stmt(s, indent + 4) for s in stmt.orelse]
+            else_body_inner = "\n".join(else_body_strs)
+            else_body = f"\n{pad}else:\n{else_body_inner}"
+        return f"{pad}if {test}:\n{body}{else_body}"
+    if isinstance(stmt, ast.For):
+        target = ast.unparse(stmt.target)
+        if isinstance(stmt.iter, ast.List):
+            iter_expr = "[" + ", ".join(_translate_expr(e) for e in stmt.iter.elts) + "]"
+        elif isinstance(stmt.iter, ast.Name) and stmt.iter.id == "self":
+            iter_expr = ast.unparse(stmt.iter)
+        else:
+            iter_expr = _translate_expr(stmt.iter)
+        body_strs = [_translate_stmt(s, indent + 4) for s in stmt.body]
+        body = "\n".join(body_strs)
+        return f"{pad}for {target} in {iter_expr}:\n{body}"
+    if isinstance(stmt, ast.Expr):
+        return f"{pad}{_translate_expr(stmt.value)}"
+    if isinstance(stmt, ast.Assign):
+        tgt = ast.unparse(stmt.targets[0])
+        val = _translate_expr(stmt.value)
+        return f"{pad}{tgt} = {val}"
+    if isinstance(stmt, ast.Return):
+        if stmt.value is None:
+            return f"{pad}return"
+        return f"{pad}return {_translate_expr(stmt.value)}"
+    if isinstance(stmt, ast.Pass):
+        return f"{pad}pass"
+    raise NotImplementedError(f'QMT 转换器不支持语句: {ast.unparse(stmt)}')
+
+
+def _class_body_attrs(tree: ast.Module, class_name: str) -> dict[str, Any]:
+    """抽 class 的类属性 (warmup_period 等) + 方法体."""
+    out: dict[str, Any] = {"attrs": {}, "methods": {}}
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef) and node.name == class_name:
+            for item in node.body:
+                if isinstance(item, ast.Assign) and len(item.targets) == 1 and isinstance(item.targets[0], ast.Name):
+                    try:
+                        out["attrs"][item.targets[0].id] = ast.literal_eval(item.value)
+                    except Exception:
+                        out["attrs"][item.targets[0].id] = ast.unparse(item.value)
+                elif isinstance(item, ast.FunctionDef):
+                    out["methods"][item.name] = item
+    return out
+
+
+def _build_config_py(spec: dict, cfg: dict) -> str:
+    """从 spec_strategy.json + config.json 拼 CONFIG = {...} 块.
+
+    designer-spec 驱动启发式:
+      - state_attrs._qty 注释里 `默认 X` / `default X` / `= X` → 取整数
+      - state_attrs._top_k 注释里 `top X` / `默认 X` / `= X` → 取整数
+      - state_attrs._rebalance_time 注释里 `'HH:MM:SS'` → 取字符串
+      - state_attrs._period 注释里 `'1d'/'5m'/...` → 取字符串
+      - data_dependencies.history_window.length → history_window int
+      - data_dependencies.history_window.field → history_field str
+      - perf_arch.mode → _audit.perf_arch_mode (QMT 端不用)
+
+    ADR-0025 CONFIG 必含: stocks / stock / period / init_capital / backtest_start /
+    backtest_end / qty + history_window / history_field / warmup_period.
+    """
+    pool = cfg.get("pool", {})
+    stocks: list[str] = []
+    for _universe, body in pool.items():
+        codes = body.get("codes", []) if isinstance(body, dict) else []
+        stocks.extend(codes)
+    warmup = spec.get("warmup_period", 1)
+    state = spec.get("state_attrs", {})
+    data_dep = spec.get("data_dependencies", {})
+
+    # 启发式: state_attrs 注释里 grep 默认值 (int / str)
+    def _gauge_int(comment: str, default: int) -> int:
+        m = re.search(r'(?:默认|default)\s*[:=]?\s*(\d+)', str(comment), re.IGNORECASE)
+        if m:
+            return int(m.group(1))
+        m = re.search(r'(?:top\s+)(\d+)', str(comment), re.IGNORECASE)
+        if m:
+            return int(m.group(1))
+        m = re.search(r'=\s*(\d+)', str(comment))
+        if m:
+            return int(m.group(1))
+        return default
+
+    def _gauge_str(comment: str, default: str, pattern: str) -> str:
+        m = re.search(pattern, str(comment))
+        return m.group(1) if m else default
+
+    qty = _gauge_int(state.get("_qty", ""), 100)
+    top_k = _gauge_int(state.get("_top_k", ""), 5)
+    rebalance_time = _gauge_str(state.get("_rebalance_time", ""), "14:55:00",
+                                r"['\"](\d{2}:\d{2}:\d{2})['\"]")
+    period_cfg = _gauge_str(state.get("_period", ""), "1d",
+                            r"['\"](\d+[dm])['\"]")
+
+    # data_dependencies 取数契约
+    history_window = 1
+    history_field = "close"
+    hw = data_dep.get("history_window") if isinstance(data_dep, dict) else None
+    if isinstance(hw, dict):
+        history_window = int(hw.get("length", 1))
+        history_field = str(hw.get("field", "close"))
+
+    cfg_dict = {
+        # === ADR-0025: 用户可在 QMT 编辑器顶部改这些值, cert 仍有效 ===
+        "stocks": stocks or ["600000.SH"],
+        "stock": (stocks or ["600000.SH"])[0],
+        "period": period_cfg,
+        "init_capital": cfg.get("init_capital", 1_000_000.0),
+        "backtest_start": cfg.get("backtest_start", "20240101"),
+        "backtest_end": cfg.get("backtest_end", "20241231"),
+        "qty": qty,
+        "top_k": top_k,
+        "rebalance_time": rebalance_time,
+        "history_window": history_window,
+        "history_field": history_field,
+        "warmup_period": warmup,
+        # === _audit: QMT 端不用, 仅为 audit trail (跟 designer spec diff 对照) ===
+        "_audit": {
+            "direction_id": spec.get("direction_id", ""),
+            "perf_arch_mode": spec.get("perf_arch", {}).get("mode", ""),
+            "scenario": spec.get("scenario", "")[:80],
+        },
+    }
+    return json.dumps(cfg_dict, ensure_ascii=False, separators=(", ", ": "))
+
+
+# ===== QMT body 顶部注入的 helper functions =====
+
+HELPER_FUNCTIONS = '''
+# ===== _hamuna_helpers (translated from akquant API surface) =====
+
+def _hamuna_get_history(n, sym, field, period, start, end):
+    """akquant self.get_history(n, sym, field) → numpy 数组.
+
+    QMT get_market_data_ex 返 {sym: DataFrame}; iloc[-n:] 取最后 n 行; .values 返 numpy
+    兼容 akquant np.mean / np.std 调用.
+    """
+    import pandas as _pd
+    _df = C.get_market_data_ex([field], [sym], period, start, end, subscribe=False)
+    if not _df:
+        return _pd.Series([], dtype=float).values
+    _data = _df.get(sym)
+    if _data is None or len(_data) < n:
+        return _pd.Series([], dtype=float).values
+    return _data[field].iloc[-n:].values
+
+
+def _hamuna_order_target_percent(pct, sym, _C, init_capital):
+    """akquant self.order_target_percent(pct, symbol=s) → passorder 双向调仓.
+
+    算法:
+      target_value = pct * 总权益 (默认 init_capital; 真值用 C.account.total_asset)
+      current_value = C.holdings.get(sym, {}).get('market_value', 0)
+      delta = target_value - current_value
+      last = 取最新一根 close
+      qty = int(abs(delta) / last / 100) * 100 (100 股取整)
+      delta > 0: buy; delta < 0: sell
+    """
+    _total = getattr(_C, "account", {}).get("total_asset", init_capital) if hasattr(_C, "account") else init_capital
+    _target = pct * _total
+    _current = _C.holdings.get(sym, {}).get("market_value", 0)
+    _delta = _target - _current
+    if abs(_delta) < init_capital * 0.001:
+        return  # 阈值防抖动
+    _bar_date = timetag_to_datetime(_C.get_bar_timetag(_C.barpos), "%Y%m%d")
+    _df = _C.get_market_data_ex(["close"], [sym], CONFIG["period"], _bar_date, _bar_date, subscribe=False)
+    _last = float(_df[sym]["close"].iloc[-1]) if _df and _df.get(sym) is not None and len(_df[sym]) else 0
+    if _last <= 0:
+        return
+    _qty = int(abs(_delta) / _last / 100) * 100
+    if _qty == 0:
+        return
+    if _delta > 0:
+        passorder(23, 1101, "", sym, 11, -1, _qty, "", 0, "buy", _C)
+    else:
+        passorder(24, 1101, "", sym, 11, -1, _qty, "", 0, "sel", _C)
+
+
+'''
+
+
+def translate(
+    akquant_path: str | Path,
+    config_path: str | Path,
+    spec_path: str | Path | None,
+) -> str:
+    """读 akquant strategy.py → QMT body 字符串.
+
+    错误: akquant 写法不支持时 → raise NotImplementedError (含具体不支持的 API).
+    """
+    akquant_src = Path(akquant_path).read_text(encoding="utf-8")
+    cfg = json.loads(Path(config_path).read_text(encoding="utf-8"))
+    spec: dict[str, Any] = {}
+    if spec_path and Path(spec_path).exists():
+        spec = json.loads(Path(spec_path).read_text(encoding="utf-8"))
+
+    tree = ast.parse(akquant_src, filename=str(akquant_path))
+    # 找 class Foo(akquant.Strategy) 子类 (or Strategy)
+    class_name = None
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef):
+            bases = [ast.unparse(b) for b in node.bases]
+            if any("Strategy" in b for b in bases):
+                class_name = node.name
+                break
+    if class_name is None:
+        raise NotImplementedError(
+            "未找到 akquant.Strategy 子类 (期望 `class Foo(akquant.Strategy)`)"
+        )
+
+    info = _class_body_attrs(tree, class_name)
+    on_start = info["methods"].get("on_start")
+    on_bar = info["methods"].get("on_bar")
+    on_timer = info["methods"].get("on_timer")
+    # 至少要 on_bar 或 on_timer — QMT body 形态不同
+    if on_bar is None and on_timer is None:
+        raise NotImplementedError(
+            "akquant Strategy 必须有 on_bar(self, bar) 或 on_timer(self, payload) (QMT body 缺调度入口)"
+        )
+
+    # init body = translate on_start + subscribe / init 声明 (空时只保留空行)
+    init_lines: list[str] = []
+    if on_start is not None:
+        try:
+            init_lines = [_translate_stmt(s, 4) for s in on_start.body]
+        except NotImplementedError as e:
+            raise NotImplementedError(f'on_start 不支持: {e}') from e
+    init_body = "\n".join(init_lines) if init_lines else "    pass"
+
+    # handlebar body — on_bar 翻译; 若只有 on_timer (无 on_bar) → handlebar 仅调度闸
+    if on_bar is not None:
+        try:
+            handlebar_lines = [_translate_stmt(s, 4) for s in on_bar.body]
+        except NotImplementedError as e:
+            raise NotImplementedError(f'on_bar 不支持: {e}') from e
+        handlebar_body = "\n".join(handlebar_lines) if handlebar_lines else "    pass"
+    else:
+        handlebar_body = "    pass  # on_timer 策略: handlebar 仅调度闸"
+
+    # on_timer body → 翻译成 callback 函数 (QMT run_time 注册 'rebalance' 默认;
+    # 用户改 CONFIG["rebalance_time"] + 函数名同步). 仅 on_timer-only 策略生成.
+    callback_body = ""
+    if on_timer is not None and on_bar is None:
+        try:
+            timer_lines = [_translate_stmt(s, 4) for s in on_timer.body]
+        except NotImplementedError as e:
+            raise NotImplementedError(f'on_timer 不支持: {e}') from e
+        timer_str = "\n".join(timer_lines) if timer_lines else "    pass"
+        callback_body = (
+            "\n\n"
+            "def rebalance(C):\n"
+            '    """on_timer 翻译产物 (callback 名 \'rebalance\' 默认; 用户改 CONFIG["rebalance_time"] 同步)"""\n'
+            f"{timer_str}\n"
+        )
+
+    config_py = _build_config_py(spec, cfg)
+
+    body = (
+        QMT_HEADER.format(config_py=config_py)
+        + HELPER_FUNCTIONS
+        + QMT_INIT_TEMPLATE.format(init_body=init_body)
+        + QMT_HANDLEBAR_TEMPLATE.format(handlebar_body=handlebar_body)
+        + callback_body
+    )
+
+    # ===== post-pass: akquant Bar 字段 / timestamp → QMT 字段差异 =====
+    # akquant 用 bar.symbol / bar.timestamp; QMT 原生 Bar 用 bar.code (无 timestamp —
+    # 用 C.get_bar_timetag(C.barpos) + timetag_to_datetime 拼日期).
+    body = body.replace("bar.symbol", "bar.code")
+    body = body.replace(
+        "bar.timestamp",
+        'timetag_to_datetime(C.get_bar_timetag(C.barpos), "%Y%m%d%H%M%S")'
+    )
+    # bar.time / bar.date 在 akquant 是 REPR ALIAS (getattr 返 None) — 不替换, 让用户手改.
+    return body
+
+
+def write_qmt_body(
+    akquant_path: str | Path,
+    config_path: str | Path,
+    spec_path: str | Path | None,
+    output_path: str | Path | None = None,
+) -> Path:
+    """translate + 落盘. 返回输出路径."""
+    body = translate(akquant_path, config_path, spec_path)
+    if output_path is None:
+        stem = Path(akquant_path).stem
+        output_path = Path(akquant_path).parent / f"_qmt_{stem}.py"
+    out = Path(output_path)
+    out.write_text(body, encoding="utf-8")  # 落盘 utf-8 (gbk 仅 QMT 加载时解码)
+    return out
+
+
+if __name__ == "__main__":
+    # CLI 入口: `hamuna_quant_cli qmt-translate <akquant.py> <cfg.json> [spec.json]`
+    # Round 14 前: `python -m strategy_cli.references.qmt_translate ...` (仓内 v2 skill 子目录)
+    # Round 14 后: 走顶层独立 pip 包 `hamuna-quant-cli`, qmt-translate 子命令统一入口
+    if len(sys.argv) < 3:
+        print(
+            "usage: hamuna_quant_cli qmt-translate "
+            "<akquant_strategy.py> <config.json> [spec_strategy.json]",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    spec_arg = sys.argv[3] if len(sys.argv) > 3 else None
+    try:
+        out = write_qmt_body(sys.argv[1], sys.argv[2], spec_arg)
+        print(f"QMT body saved → {out}")
+    except NotImplementedError as e:
+        print(f"QMT 转换不支持: {e}", file=sys.stderr)
+        sys.exit(3)

hamuna_quant_cli/runtime/__init__.py

@@ -0,0 +1,2 @@
+"""hamuna_quant_cli.runtime — discipline / backtest / server / http / cache."""
+from . import discipline, backtest, server_client, http_client, cache  # noqa: F401

hamuna_quant_cli/runtime/backtest.py

@@ -0,0 +1,38 @@
+"""v2 backtest — 委托 hamuna_quant_cli.references.akquant_runner.run_akquant_backtest.
+
+单入口: run_akquant_backtest(strategy_path, cfg) → hamuna 13-key dict (同 v1 driver schema).
+v2 不重复实现 akquant 引擎 / 数据加载 / metrics 计算 / schema 折叠.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def run(strategy_path: Path, cfg: dict) -> dict:
+    """跑 akquant backtest, 落 hamuna 13-key dict (与 v1 driver.run_backtest 输出同 schema).
+
+    strategy_path: 含 akquant.Strategy 子类的 .py 路径 (on_bar API, NOT QMT handlebar).
+    cfg: 同 v1 run 的 CONFIG dict (backtest_start/end, pool / universe, init_capital, ...).
+
+    失败模式 / 已知坑 → hamuna_quant_cli.references.akquant_runner.run_akquant_backtest:
+      FileNotFoundError: 数据集缺失 (universe 在 prebuilt 不存在, 或 start/end 在 window 外)
+      ImportError: akquant 未安装 (pip install akquant)
+      ValueError: cfg 缺必需 key / akquant.run_backtest 报参数错
+    """
+    from ..akquant_runner import run_akquant_backtest  # Round 14: 同包 (从 strategy_cli 命名空间退出)
+    return run_akquant_backtest(str(strategy_path), cfg)
+
+
+def _selfcheck() -> None:
+    """v2 backtest._selfcheck: 验 import + 调通 hamuna_quant_cli runner.
+
+    实跑 BuyHold 2 标的 6mo 已在 cmd_run smoke 覆盖 (smoke step 3b 通过).
+    这里只验: from .backtest import run 在 v2 路径下能 import.
+    """
+    from . import backtest as m
+    assert callable(m.run), 'backtest.run not callable'
+    print('OK: backtest._selfcheck (import + run callable)')
+
+
+if __name__ == '__main__':
+    _selfcheck()