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

hamuna_quant_cli/__main__.py

@@ -0,0 +1,978 @@
+"""hamuna_quant_cli CLI 入口 — 合并回测 + 实盘子命令.
+
+Usage:
+    hamuna_quant_cli run <strategy.py> --config <cfg.json> --output result.json
+    hamuna_quant_cli check <strategy.py> --config <cfg.json>
+    hamuna_quant_cli upload <strategy_id> --result result.json
+    hamuna_quant_cli create --name ... --config ...
+    hamuna_quant_cli parity [--strategies ...]
+    hamuna_quant_cli qmt-translate <strategy.py> <cfg.json>
+    hamuna_quant_cli commit <strategy_id> --strategy ... --result ...
+    hamuna_quant_cli dataset {list|fetch|manifest}
+    hamuna_quant_cli live run <strategy.py> --mode paper --broker qmt ...
+
+PYTHONPATH: 不需要 (pip install hamuna-quant-cli 后全局可用).
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+
+
+# ============================================================
+# 回测子命令 (从原 v2 skill `skills/hamuna-strategy-v2/strategy_cli/__main__.py` 搬, runtime/ 已搬进 hamuna_quant_cli.runtime; Round 14 后 v2 skill 不再带代码)
+# ============================================================
+def _load_config(path: str) -> dict:
+    import json
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def _parse_symbols(s: str) -> list[str]:
+    """CSV symbols → 裸码 list (A 股 dataset stockCode 不带 .SH/.SZ/.BJ 后缀)."""
+    out: list[str] = []
+    for raw in s.split(","):
+        x = raw.strip()
+        if not x:
+            continue
+        if x[:2].lower() in ("sh", "sz", "bj"):
+            x = x[2:]
+        x = x.split(".")[0]
+        if x.isdigit() and len(x) == 6:
+            out.append(x)
+        else:
+            print(f"  ⚠ 跳过非法 symbol: {raw!r} (期望 6 位数字裸码)", file=sys.stderr)
+    return out
+
+
+def _now_iso() -> str:
+    from datetime import datetime, timezone
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def cmd_run(args) -> int:
+    """跑 akquant backtest → result.json."""
+    from . import runtime
+
+    cfg = _load_config(args.config)
+    strategy_path = Path(args.strategy).resolve()
+
+    if not getattr(args, "skip_discipline", False):
+        source = strategy_path.read_text(encoding="utf-8")
+        errs = runtime.discipline.check_discipline(source, cfg)
+        if errs:
+            for e in errs:
+                print(str(e), file=sys.stderr)
+            print(f"纪律 self-check 未通过 ({len(errs)} 条); "
+                  f"用 --skip-discipline 显式跳过", file=sys.stderr)
+            return 3
+
+    if getattr(args, "dataset", None):
+        manifest_path = Path(args.dataset)
+        if not manifest_path.exists():
+            print(f"--dataset manifest 不存在: {args.dataset}", file=sys.stderr)
+            return 2
+        import json as _json
+        try:
+            manifest = _json.loads(manifest_path.read_text(encoding="utf-8"))
+        except _json.JSONDecodeError as e:
+            print(f"manifest 解析失败: {args.dataset} ({e})", file=sys.stderr)
+            return 2
+        cfg["_dataset_manifest"] = manifest
+
+    result = runtime.backtest.run(strategy_path, cfg)
+
+    if args.output:
+        import json
+        Path(args.output).write_text(
+            json.dumps(result, indent=2, ensure_ascii=False, default=str),
+            encoding="utf-8",
+        )
+        print(f"result saved → {args.output}", file=sys.stderr)
+    else:
+        import json
+        print(json.dumps(result, indent=2, ensure_ascii=False, default=str))
+
+    if getattr(args, "upload", False):
+        return _upload_after_run(args, cfg, result)
+    return 0
+
+
+def _upload_after_run(args, cfg: dict, result: dict) -> int:
+    from . import runtime
+    strategy_id = getattr(args, "strategy_id", None)
+    name = getattr(args, "name", None)
+    code = getattr(args, "code", None)
+    if not strategy_id and name:
+        from .runtime.server_client import create_strategy, ServerError
+        try:
+            code_str = Path(code).read_text(encoding="utf-8") if code else ""
+            rec = create_strategy(name=name, code=code_str, params=cfg)
+            strategy_id = rec.get("_id") or rec.get("id")
+            if not strategy_id:
+                raise ServerError(f"create_strategy 返没 _id: {rec}")
+            print(f"  ✓ 新建 strategy: {name} → _id={strategy_id}", file=sys.stderr)
+        except ServerError as e:
+            print(f"  ✗ create_strategy 失败: {e}", file=sys.stderr)
+            return 4
+    if not strategy_id:
+        print("  ✗ --upload 需 strategy_id (位置) 或 --name (auto-auto-create)",
+              file=sys.stderr)
+        return 2
+    try:
+        resp = runtime.server_client.upload_backtest_result(strategy_id, result)
+    except runtime.server_client.ServerError as e:
+        print(f"  ✗ 上传失败: {e}", file=sys.stderr)
+        return 4
+    import json
+    print(json.dumps(resp, indent=2, ensure_ascii=False))
+    return 0
+
+
+def cmd_check(args) -> int:
+    from . import runtime
+
+    source = Path(args.strategy).read_text(encoding="utf-8")
+    cfg = _load_config(args.config)
+    errs = runtime.discipline.check_discipline(source, cfg)
+    if errs:
+        for e in errs:
+            print(str(e), file=sys.stderr)
+        print(f"纪律 self-check 未通过 ({len(errs)} 条)", file=sys.stderr)
+        return 3
+    print("纪律 self-check 通过 (0 条)", file=sys.stderr)
+    return 0
+
+
+def cmd_upload(args) -> int:
+    """PUT 已跑通的 result.json 到 strategy_id (auto-auto-create 若无 strategy_id)."""
+    from . import runtime
+    import json
+
+    result_path = Path(args.result)
+    if not result_path.exists():
+        print(f"本地回测结果不存在: {args.result} — "
+              f"请先跑 `hamuna_quant_cli run` 产出 result.json, 再上传", file=sys.stderr)
+        return 2
+    try:
+        result = json.loads(result_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        print(f"result.json 解析失败: {args.result} ({e})", file=sys.stderr)
+        return 2
+
+    strategy_id = getattr(args, "strategy_id", None)
+    name = getattr(args, "name", None)
+    cfg_path = getattr(args, "config", None)
+
+    if not strategy_id:
+        if not name or not cfg_path:
+            print("upload 缺 strategy_id: 必填 --name + --config (auto-create) "
+                  "或 strategy_id (位置) 直接上传", file=sys.stderr)
+            return 2
+        cfg = _load_config(cfg_path)
+        code_str = ""
+        if getattr(args, "code", None):
+            code_path = Path(args.code)
+            if not code_path.exists():
+                print(f"--code 文件不存在: {args.code}", file=sys.stderr)
+                return 2
+            code_str = code_path.read_text(encoding="utf-8")
+        try:
+            rec = runtime.server_client.create_strategy(name=name, code=code_str, params=cfg)
+        except runtime.server_client.ServerError as e:
+            print(f"create_strategy 失败: {e}", file=sys.stderr)
+            return 4
+        strategy_id = rec.get("_id") or rec.get("id")
+        if not strategy_id:
+            print(f"create_strategy 返没 _id: {rec}", file=sys.stderr)
+            return 4
+        print(f"  ✓ 新建 strategy: {name} → _id={strategy_id}", file=sys.stderr)
+
+    try:
+        resp = runtime.server_client.upload_backtest_result(strategy_id, result)
+    except runtime.server_client.ServerError as e:
+        print(f"上传失败: {e}", file=sys.stderr)
+        return 4
+    print(json.dumps(resp, indent=2, ensure_ascii=False))
+    return 0
+
+
+def cmd_create(args) -> int:
+    """新建 strategy 拿 strategy_id."""
+    from . import runtime
+    import json
+
+    name = args.name
+    cfg = _load_config(args.config)
+    code_str = ""
+    if getattr(args, "code", None):
+        code_path = Path(args.code)
+        if not code_path.exists():
+            print(f"--code 文件不存在: {args.code}", file=sys.stderr)
+            return 2
+        code_str = code_path.read_text(encoding="utf-8")
+
+    try:
+        rec = runtime.server_client.create_strategy(name=name, code=code_str, params=cfg)
+    except runtime.server_client.ServerError as e:
+        print(f"create_strategy 失败: {e}", file=sys.stderr)
+        return 4
+
+    sid = rec.get("_id") or rec.get("id")
+    if not sid:
+        print(f"create_strategy 返没 _id: {rec}", file=sys.stderr)
+        return 4
+
+    print(json.dumps(rec, indent=2, ensure_ascii=False))
+    print(f"\n  → strategy_id={sid}", file=sys.stderr)
+    print(f"  → 用此 id 跑: "
+          f"hamuna_quant_cli upload {sid} --result result.json",
+          file=sys.stderr)
+    return 0
+
+
+def cmd_qmt_translate(args) -> int:
+    """akquant Strategy → QMT body 翻译 (本地 stub; 真值由 cloud render)."""
+    from .qmt_translator import write_qmt_body
+
+    spec_arg = getattr(args, "spec", None)
+    output = getattr(args, "output", None)
+    try:
+        out = write_qmt_body(args.strategy, args.config, spec_arg, output)
+    except FileNotFoundError as e:
+        print(f"输入文件不存在: {e}", file=sys.stderr)
+        return 2
+    except NotImplementedError as e:
+        print(f"QMT 转换不支持 (本地 stub 范围): {e}", file=sys.stderr)
+        return 3
+    print(f"QMT body saved → {out}", file=sys.stderr)
+    import json
+    print(json.dumps({"qmt_body_path": str(out), "note":
+                      "本地 stub; cloud export 端点会重新渲染 + 签 cert + 嵌入 embedded API key"},
+                     ensure_ascii=False))
+    return 0
+
+
+def cmd_commit(args) -> int:
+    """commiter 5 步打包上传 (qmt-translate + bundle + PUT result + POST code + POST export)."""
+    from .qmt_translator import write_qmt_body
+    from . import runtime
+    import json
+    import tarfile
+
+    sid = args.strategy_id
+
+    result_path = Path(args.result)
+    if not result_path.exists():
+        print(f"result.json 不存在: {args.result}", file=sys.stderr)
+        return 2
+    strategy_path = Path(args.strategy) if args.strategy else Path(f"{sid}.py")
+    if not strategy_path.exists():
+        print(f"strategy .py 不存在: {strategy_path}", file=sys.stderr)
+        return 2
+    cfg_path = Path(args.config) if args.config else None
+    if cfg_path and not cfg_path.exists():
+        print(f"config.json 不存在: {cfg_path}", file=sys.stderr)
+        return 2
+    spec_path = Path(args.spec) if args.spec else None
+    if spec_path and not spec_path.exists():
+        print(f"spec_strategy.json 不存在: {spec_path} (--spec 可选)", file=sys.stderr)
+        spec_path = None
+
+    bundle_out = Path(args.bundle_out) if args.bundle_out else Path(f"runs/{sid}/bundle.tar.gz")
+    bundle_out.parent.mkdir(parents=True, exist_ok=True)
+
+    print("=== Step 1/5: akquant → QMT body 翻译 (本地 stub) ===", file=sys.stderr)
+    try:
+        qmt_body_path = write_qmt_body(strategy_path, cfg_path, spec_path)
+    except NotImplementedError as e:
+        print(f"  ✗ 不支持: {e}", file=sys.stderr)
+        return 3
+    print(f"  ✓ qmt_body = {qmt_body_path}", file=sys.stderr)
+
+    print("=== Step 2/5: 打包 bundle (strategy + qmt_body + metrics + spec) ===",
+          file=sys.stderr)
+    with tarfile.open(bundle_out, "w:gz") as tar:
+        tar.add(strategy_path, arcname=strategy_path.name)
+        tar.add(qmt_body_path, arcname=qmt_body_path.name)
+        tar.add(result_path, arcname=result_path.name)
+        if spec_path:
+            tar.add(spec_path, arcname=spec_path.name)
+        if cfg_path:
+            tar.add(cfg_path, arcname=cfg_path.name)
+    print(f"  ✓ bundle = {bundle_out} ({bundle_out.stat().st_size} bytes)", file=sys.stderr)
+
+    print("=== Step 3/5: PUT /strategies/:id/result (metrics) ===", file=sys.stderr)
+    try:
+        result = json.loads(result_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        print(f"  ✗ result.json 解析失败: {e}", file=sys.stderr)
+        return 2
+    try:
+        resp = runtime.server_client.upload_backtest_result(sid, result)
+    except runtime.server_client.ServerError as e:
+        print(f"  ✗ 上传 metrics 失败: {e}", file=sys.stderr)
+        return 4
+    print(f"  ✓ metrics uploaded (resp keys: {sorted(resp.keys())[:5]})", file=sys.stderr)
+
+    print("=== Step 4/5: POST /strategies/:id/code (multipart body + params) ===",
+          file=sys.stderr)
+    params: dict = {}
+    if spec_path:
+        params["spec_strategy"] = json.loads(spec_path.read_text(encoding="utf-8"))
+    if cfg_path:
+        params["config"] = json.loads(cfg_path.read_text(encoding="utf-8"))
+    try:
+        resp_code = runtime.server_client.upload_strategy_code(sid, str(qmt_body_path),
+                                                              params=params or None)
+    except runtime.server_client.ServerError as e:
+        print(f"  ✗ 上传源码失败: {e}", file=sys.stderr)
+        return 4
+    print(f"  ✓ body uploaded (body_hash={resp_code.get('body_hash', '?')[:16]})",
+          file=sys.stderr)
+
+    export_path = None
+    if not args.skip_export:
+        print("=== Step 5/5: POST /strategies/:id/export (拉 .qmt.py shell) ===",
+              file=sys.stderr)
+        export_out = Path(args.export_out) if args.export_out else Path(
+            f"runs/{sid}/{sid}.qmt.py"
+        )
+        export_out.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            resp_exp = runtime.server_client.export_strategy(sid, str(export_out))
+        except runtime.server_client.ServerError as e:
+            print(f"  ✗ QMT export 失败: {e}", file=sys.stderr)
+            return 4
+        export_path = str(export_out)
+        print(f"  ✓ shell saved → {export_path} "
+              f"({resp_exp.get('shell_bytes', '?')} bytes)", file=sys.stderr)
+    else:
+        print("=== Step 5/5: SKIPPED (--skip-export) ===", file=sys.stderr)
+
+    print('', file=sys.stderr)
+    print(json.dumps({
+        "strategy_id": sid,
+        "bundle_path": str(bundle_out),
+        "qmt_body_path": str(qmt_body_path),
+        "export_path": export_path,
+        "verdict": "OK",
+    }, ensure_ascii=False, indent=2))
+    return 0
+
+
+def cmd_parity(args) -> int:
+    """跑 akquant parity test (5 内置 strategy × 1 universe × 1 period)."""
+    from datetime import datetime as _dt
+    from . import _test_akquant_parity as _pt  # type: ignore
+    import json
+
+    strategies = None
+    if getattr(args, "strategies", None):
+        strategies = [s.strip() for s in args.strategies.split(",") if s.strip()]
+
+    universe_raw = getattr(args, "universe", None)
+    universe = None
+    if universe_raw:
+        universe = [_normalize_to_full(x) for x in _parse_symbols(universe_raw)]
+
+    start = getattr(args, "start", None) or "20230101"
+    end = getattr(args, "end", None) or "20251231"
+
+    out = _pt.run_parity_test(strategies=strategies, universe=universe,
+                               start=start, end=end)
+    import akquant
+    out["_engine"] = f"akquant-{akquant.__version__}"
+    out["_invoked_by"] = "hamuna_quant_cli parity"
+
+    if getattr(args, "report", None):
+        report_path = Path(args.report)
+        report_path.parent.mkdir(parents=True, exist_ok=True)
+        report_path.write_text(
+            json.dumps(out, indent=2, ensure_ascii=False, default=str),
+            encoding="utf-8",
+        )
+        print(f"parity report saved → {report_path}", file=sys.stderr)
+    else:
+        print(f"akquant parity @ {_dt.now().isoformat(timespec='seconds')}", file=sys.stderr)
+        print(f"  strategies: {[s['name'] for s in _pt.STRATEGY_DEFS]}", file=sys.stderr)
+        print(f"summary:", file=sys.stderr)
+        for r in out["runs"]:
+            status = "OK" if not r.get("error") else f"FAIL ({r.get('error','')[:60]})"
+            n = r.get("trades_count", 0)
+            print(f"  {r['strategy']:24s} {r['engine']:10s} {status:20s} "
+                  f"trades={n:3d} ({r.get('elapsed_sec',0)}s)",
+                  file=sys.stderr)
+
+    return 0 if all(not r.get("error") for r in out["runs"]) else 4
+
+
+def _normalize_to_full(bare: str) -> str:
+    """6 位裸码 → 容维 stockCode (带 .SH/.SZ/.BJ 后缀)."""
+    from .akquant_schema_adapter import normalize_symbol
+    return normalize_symbol(bare)
+
+
+def cmd_dataset(args) -> int:
+    """构建 / 列出 prebuilt 数据集."""
+    if args.subcmd == "list":
+        from .prebuilt_downloader import main as pd_main  # type: ignore
+        return pd_main(["list"])
+
+    if args.subcmd == "fetch":
+        if not args.symbols:
+            print("cmd_dataset fetch --symbols 必填 (逗号分隔裸码 e.g. 600000,600036)",
+                  file=sys.stderr)
+            return 2
+        syms = _parse_symbols(args.symbols)
+        from .prebuilt_downloader import download_single  # type: ignore
+        ok, fail = [], []
+        for sym in syms:
+            try:
+                p = download_single(sym, period=args.period,
+                                    start=args.start, end=args.end)
+                ok.append({"symbol": sym, "path": str(p)})
+                print(f"  ✓ {sym} → {p}", file=sys.stderr)
+            except Exception as e:
+                fail.append({"symbol": sym, "error": str(e)})
+                print(f"  ✗ {sym}: {e}", file=sys.stderr)
+        out = {"fetched": ok, "failed": fail,
+               "count_ok": len(ok), "count_fail": len(fail)}
+        import json
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+        return 0 if not fail else 4
+
+    if args.subcmd == "manifest":
+        if not args.symbols or not args.start or not args.end:
+            print("cmd_dataset manifest --symbols/--start/--end 必填",
+                  file=sys.stderr)
+            return 2
+        syms = _parse_symbols(args.symbols)
+        if not syms:
+            print("cmd_dataset manifest --symbols 解析后为空 (非法输入)",
+                  file=sys.stderr)
+            return 2
+        from .akquant_data_adapter import (  # type: ignore
+            load_prebuilt_to_akquant_with_limits,
+        )
+        try:
+            df = load_prebuilt_to_akquant_with_limits(syms, args.start, args.end)
+        except FileNotFoundError as e:
+            print(f"manifest 构建失败: {e}", file=sys.stderr)
+            return 4
+        if df is None or df.empty:
+            print(f"manifest 数据空: symbols={syms} window={args.start}-{args.end}",
+                  file=sys.stderr)
+            return 4
+        actual_symbols = sorted(set(df["symbol"].tolist())) if "symbol" in df.columns else []
+        manifest = {
+            "symbols":   actual_symbols,
+            "start":     args.start,
+            "end":       args.end,
+            "rows":      int(len(df)),
+            "columns":   sorted(df.columns.tolist()),
+            "created_at": _now_iso(),
+            "schema":    "hamuna_quant_cli/v1",
+        }
+        if args.output:
+            import json
+            Path(args.output).write_text(
+                json.dumps(manifest, indent=2, ensure_ascii=False),
+                encoding="utf-8",
+            )
+            print(f"manifest saved → {args.output} "
+                  f"({manifest['rows']} rows, {len(actual_symbols)} symbols)",
+                  file=sys.stderr)
+        else:
+            import json
+            print(json.dumps(manifest, indent=2, ensure_ascii=False))
+        return 0
+
+    print(f"未知 dataset subcmd: {args.subcmd}", file=sys.stderr)
+    return 2
+
+
+def _bridge_kline(server: str, symbols: list[str], days: int) -> list[dict]:
+    """QMT bridge /data/history 日线 → kline JSON 列表 (本地 bundle 无数据时回退).
+
+    columns: [amount, close, high, low, open, ..., time(ms 时间戳), volume].
+    """
+    import json
+    import urllib.parse
+    import urllib.request
+    from datetime import datetime
+
+    out: list[dict] = []
+    for sym in symbols:
+        url = (
+            f"{server}/data/history?security={urllib.parse.quote(sym)}"
+            f"&period=1d&count={days}&fq=None"
+        )
+        try:
+            with urllib.request.urlopen(url, timeout=8) as resp:
+                p = json.load(resp)
+        except Exception as exc:  # noqa: BLE001
+            raise RuntimeError(f"bridge 不可达 ({url}): {exc}") from exc
+        if not p.get("ok"):
+            raise RuntimeError(f"bridge: {p.get('message') or p.get('error') or p}")
+        value = p.get("value") or {}
+        cols = value.get("columns") or []
+        recs = value.get("records") or []
+        if not cols:
+            continue
+        idx = {c: i for i, c in enumerate(cols)}
+        for r in recs:
+            ts = r[idx["time"]]
+            date = datetime.fromtimestamp(ts / 1000).strftime("%Y-%m-%d")
+            out.append(
+                {
+                    "date": date,
+                    "open": round(float(r[idx["open"]]), 4),
+                    "high": round(float(r[idx["high"]]), 4),
+                    "low": round(float(r[idx["low"]]), 4),
+                    "close": round(float(r[idx["close"]]), 4),
+                    "volume": float(r[idx["volume"]]),
+                }
+            )
+    out.sort(key=lambda b: b["date"])
+    return out
+
+
+def cmd_kline(args) -> int:
+    """最近 N 天日线 OHLCV → stdout JSON (详情页 K 线图数据源).
+
+    优先本地 prebuilt bundle (与回测同源真实数据, 离线可用); 本地无该标的
+    (ETF/可转债/新股等不在 bundle) 时回退 QMT bridge /data/history —
+    2026-08-19 标的池全量改 QMT 后 K 线也要能覆盖 QMT 标的.
+    """
+    import json
+    from datetime import datetime, timedelta
+
+    from .prebuilt_resolver import resolve
+
+    syms = [s.strip() for s in args.symbols.split(",") if s.strip()]
+    if not syms:
+        print("[error] kline 需要 --symbols", file=sys.stderr)
+        return 2
+    end = datetime.now().strftime("%Y%m%d")
+    start = (datetime.now() - timedelta(days=args.days)).strftime("%Y%m%d")
+    df, src = resolve(syms, start, end)
+    if df is None or len(df) == 0:
+        # 回退 QMT bridge (本地 bundle 无此标的)
+        try:
+            bars = _bridge_kline(args.server, syms, args.days)
+        except RuntimeError as exc:
+            print(
+                f"[error] 本地 bundle 无数据 (universe={syms}, src={src}) 且 bridge 回退失败: {exc}",
+                file=sys.stderr,
+            )
+            return 5
+        if not bars:
+            print(
+                f"[error] 无 bar 数据 (universe={syms}, {start}~{end}, src={src}) — "
+                f"先 `hamuna_quant_cli dataset fetch --symbols {','.join(syms)}` 或确认 QMT bridge 在线",
+                file=sys.stderr,
+            )
+            return 4
+        print(json.dumps(bars, ensure_ascii=False))
+        return 0
+    df = df.copy()
+    df["date"] = df["date"].astype(str)  # datetime64 → 'YYYY-MM-DD'
+    bars = [
+        {
+            "date": r.date,
+            "open": round(float(r.open), 4),
+            "high": round(float(r.high), 4),
+            "low": round(float(r.low), 4),
+            "close": round(float(r.close), 4),
+            "volume": float(r.volume),
+        }
+        for r in df.itertuples()
+    ]
+    print(json.dumps(bars, ensure_ascii=False))
+    return 0
+
+
+def _resolve_names(codes: list[str], server: str, cache_key: str) -> dict[str, str]:
+    """bridge /data/stock_name 逐个补证券名称 + 本地缓存 (全类别统一走 QMT).
+
+    返回 {code: name}。缺名 (沪市可转债 get_instrument_detail 返回空) 留 ""。
+    缓存 ~/.hamuna/data_cache/universe_names_<cache_key>.json, 首次并发 16 查,
+    之后秒出。
+    """
+    import json
+    import urllib.parse
+    import urllib.request
+    from concurrent.futures import ThreadPoolExecutor
+    from pathlib import Path
+
+    cache_dir = Path.home() / ".hamuna" / "data_cache"
+    path = cache_dir / f"universe_names_{cache_key}.json"
+    names: dict[str, str] = {}
+    if path.exists():
+        try:
+            names = json.loads(path.read_text(encoding="utf-8"))
+        except Exception:  # noqa: BLE001
+            names = {}
+    missing = [c for c in codes if c not in names]
+    if missing:
+
+        def fetch(c: str) -> tuple[str, str]:
+            try:
+                url = f"{server}/data/stock_name?security={urllib.parse.quote(c)}"
+                with urllib.request.urlopen(url, timeout=6) as resp:
+                    p = json.load(resp)
+                return c, (p.get("value") or {}).get("name") or ""
+            except Exception:  # noqa: BLE001
+                return c, ""
+
+        with ThreadPoolExecutor(max_workers=16) as ex:
+            for c, n in ex.map(fetch, missing):
+                names[c] = n
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(names, ensure_ascii=False), encoding="utf-8")
+    return names
+
+
+def cmd_universe(args) -> int:
+    """列 universe 标的列表 [code, name] → stdout JSON — 全部从 QMT bridge 拉取.
+
+    2026-08-19 用户要求"都从 QMT 拉": 成分列表走 /data/index_stocks
+    (all_a→沪深A股板块 / index→指数成分 / etf→双基金过滤 / cb→沪深转债),
+    名称走 /data/stock_name (并发 + ~/.hamuna/data_cache 缓存).
+    依赖 QMT bridge 在线 (离线不可用, 报错提示).
+    """
+    import json
+
+    if args.type == "index":
+        if not args.index:
+            print("[error] --type index 需要 --index (指数代码, 如 000300)", file=sys.stderr)
+            return 2
+        pool = args.index
+        cache_key = f"index_{args.index}"
+    else:
+        pool = {"all_a": "all_a", "etf": "etf", "convertible_bond": "cb"}[args.type]
+        cache_key = args.type
+    try:
+        codes = _fetch_pool_codes(args.server, pool)
+    except RuntimeError as exc:
+        # bridge 不可达 → 用落盘缓存降级 (QMT 之前拉过的池秒出; 从未拉过才报错)
+        cached = _read_pool_cache("items", pool)
+        if cached:
+            print(json.dumps(cached, ensure_ascii=False))
+            print(
+                f"[warn] bridge 不可达, 使用缓存标的池 ({len(cached)} 个) — 启动 QMT 后刷新",
+                file=sys.stderr,
+            )
+            return 0
+        print(
+            f"[error] {exc} — 标的池数据来自 QMT bridge, 请确认 QMT 已启动 (bridge 在线)",
+            file=sys.stderr,
+        )
+        return 5
+    names = _resolve_names(codes, args.server, cache_key)
+    items = [{"code": c, "name": names.get(c, "")} for c in codes]
+    _write_pool_cache("items", pool, items)
+    print(json.dumps(items, ensure_ascii=False))
+    return 0
+
+
+_ETF_PREFIXES = (
+    "510", "511", "512", "513", "515", "516", "517", "518",
+    "560", "561", "562", "563", "588", "589",  # 沪市 ETF
+    "159",  # 深市 ETF
+)
+# QMT 板块名 (get_stock_list_in_sector): 沪深A股 / 沪深转债 / 沪市基金 / 深市基金
+_POOL_SECTORS = {"all_a": "沪深A股", "cb": "沪深转债", "etf": None}
+
+
+def _pool_cache_path(kind: str, pool: str):
+    """标的池列表落盘缓存 — ~/.hamuna/data_cache/universe_{kind}_{pool}.json.
+    QMT 拉取成功后写, bridge 不可达时读缓存降级 (标的池是低频静态数据).
+    kind: items (universe 带名称) / codes (index-stocks 裸码).
+    """
+    from pathlib import Path
+
+    return Path.home() / ".hamuna" / "data_cache" / f"universe_{kind}_{pool}.json"
+
+
+def _write_pool_cache(kind: str, pool: str, data) -> None:
+    import json
+
+    try:
+        p = _pool_cache_path(kind, pool)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
+    except Exception:  # noqa: BLE001 — 缓存失败不影响主流程
+        pass
+
+
+def _read_pool_cache(kind: str, pool: str):
+    import json
+
+    try:
+        p = _pool_cache_path(kind, pool)
+        if p.exists():
+            return json.loads(p.read_text(encoding="utf-8"))
+    except Exception:  # noqa: BLE001
+        pass
+    return None
+
+
+def _fetch_pool_codes(server: str, pool: str) -> list[str]:
+    """读 bridge 股票池 → 6 位裸码列表 (与 cmd_index_stocks 共用).
+
+    pool: 指数代码 / all_a / cb (板块直查) / etf (沪市+深市基金合并后代码段过滤).
+    Raises: RuntimeError — bridge 不可达或返回错误.
+    """
+    import json
+    import urllib.parse
+    import urllib.request
+
+    def fetch(params: str) -> list[str]:
+        url = f"{server}/data/index_stocks?{params}"
+        try:
+            with urllib.request.urlopen(url, timeout=8) as resp:
+                payload = json.load(resp)
+        except Exception as exc:  # noqa: BLE001
+            raise RuntimeError(f"bridge 不可达 ({url}): {exc}") from exc
+        if not payload.get("ok"):
+            raise RuntimeError(f"bridge: {payload.get('message') or payload.get('error') or payload}")
+        stocks = payload.get("value", {}).get("stocks") or []
+        codes: list[str] = []
+        for s in stocks:
+            c = str(s).split(".")[0]
+            if c and c not in codes:
+                codes.append(c)
+        return codes
+
+    if pool in _POOL_SECTORS:
+        sector = _POOL_SECTORS[pool]
+        if sector is None:  # etf: 合并沪/深基金 + 代码段过滤
+            raw = fetch("sector=" + urllib.parse.quote("沪市基金"))
+            raw += fetch("sector=" + urllib.parse.quote("深市基金"))
+            return [c for c in raw if c.startswith(_ETF_PREFIXES)]
+        return fetch("sector=" + urllib.parse.quote(sector))
+    return fetch("index_symbol=" + urllib.parse.quote(pool))
+
+
+def cmd_index_stocks(args) -> int:
+    """读 QMT bridge 股票池 → stdout JSON (6 位裸码列表).
+
+    池标识 --pool: 指数代码 (000016/000300/000905/000852 等, 走 index_symbol)
+    或预置池: all_a (沪深A股全部) / cb (沪深转债) / etf (场内 ETF,
+    沪市基金+深市基金合并后按代码段过滤, 排除 LOF/REITs/分级).
+    """
+    import json
+
+    try:
+        codes = _fetch_pool_codes(args.server, args.pool)
+    except RuntimeError as exc:
+        # bridge 不可达 → 落盘缓存降级 (与 universe 共用 pool 标识)
+        cached = _read_pool_cache("codes", args.pool)
+        if cached:
+            print(json.dumps(cached, ensure_ascii=False))
+            print(
+                f"[warn] bridge 不可达, 使用缓存标的池 ({len(cached)} 个) — 启动 QMT 后刷新",
+                file=sys.stderr,
+            )
+            return 0
+        print(f"[error] {exc}", file=sys.stderr)
+        return 5
+    _write_pool_cache("codes", args.pool, codes)
+    print(json.dumps(codes, ensure_ascii=False))
+    return 0
+
+
+# ============================================================
+# 实盘子命令 (从 desktop hamuna_strategy.py 搬)
+# ============================================================
+def cmd_live_run(args) -> int:
+    """实盘 / 仿真运行策略 (包装 akquant.run_live)."""
+    from .live import load_strategy, run_live, StrategyLoadError, LiveRunError
+
+    try:
+        spec = load_strategy(Path(args.strategy), class_name=args.class_name)
+    except StrategyLoadError as e:
+        print(f"[error] strategy.py 加载失败: {e}", file=sys.stderr)
+        return 3
+    try:
+        symbols = [s.strip() for s in args.symbols.split(",")] if args.symbols else None
+        run_live(
+            spec,
+            mode=args.mode,
+            broker=args.broker,
+            symbols=symbols,
+            duration=args.duration,
+            gateway_options_raw=args.gateway_options,
+            initial_cash=args.initial_cash,
+            log_level=args.log_level,
+            log_file=args.log_file,
+            market_broker=args.market_broker,
+            replay_days=args.replay_days,
+        )
+    except LiveRunError as e:
+        print(f"[error] live run 失败: {e}", file=sys.stderr)
+        return 4
+    return 0
+
+
+# ============================================================
+# argparse 路由 + main()
+# ============================================================
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="hamuna_quant_cli",
+        description="Hamuna 回测 + 实盘统一 CLI (akquant 0.3.x) — "
+                    "`hamuna_quant_cli run <strategy.py>` 或 `live run <strategy.py>`",
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    # —— 回测 ——
+    r = sub.add_parser("run", help="跑 akquant backtest → result.json")
+    r.add_argument("strategy", help="strategy .py 路径 (含 akquant.Strategy 子类)")
+    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("--skip-discipline", action="store_true",
+                   help="跳过 akquant API 静态审查 (qa / 旧策略兼容)")
+    r.add_argument("--upload", action="store_true",
+                   help="跑完直接上传 server (与 --name 联用 auto-create)")
+    r.add_argument("--strategy-id", help="--upload 时直接给 strategy_id")
+    r.add_argument("--name", help="--upload auto-create 时的策略名")
+    r.add_argument("--code", help="--upload auto-create 时的策略源码 (.py 路径)")
+    r.set_defaults(func=cmd_run)
+
+    k = sub.add_parser("check", help="纯静态纪律 self-check (不跑回测)")
+    k.add_argument("strategy", help="strategy .py 路径")
+    k.add_argument("--config", required=True, help="CONFIG JSON 路径")
+    k.set_defaults(func=cmd_check)
+
+    u = sub.add_parser("upload", help="PUT 本地 result.json → server")
+    u.add_argument("strategy_id", nargs="?",
+                   help="server 端 strategy_id (缺则 --name + --config 必填)")
+    u.add_argument("--result", required=True, help="本地 result.json 路径")
+    u.add_argument("--name", help="auto-create 时的策略名")
+    u.add_argument("--config", help="auto-create 时的 CONFIG JSON")
+    u.add_argument("--code", help="auto-create 时的策略源码 (.py 路径)")
+    u.set_defaults(func=cmd_upload)
+
+    c = sub.add_parser("create", help="新建 strategy 拿 strategy_id")
+    c.add_argument("--name", required=True, help="策略名")
+    c.add_argument("--config", required=True, help="CONFIG JSON 路径")
+    c.add_argument("--code", help="策略源码 .py 路径")
+    c.set_defaults(func=cmd_create)
+
+    pa = sub.add_parser("parity", help="跑 akquant parity test")
+    pa.add_argument("--strategies", help="CSV strategy 名 (默认全跑)")
+    pa.add_argument("--universe", help="6 位裸码 CSV (默认 600000)")
+    pa.add_argument("--start", help="YYYYMMDD (默认 20230101)")
+    pa.add_argument("--end", help="YYYYMMDD (默认 20251231)")
+    pa.add_argument("--report", help="落盘 JSON 路径 (默认 stdout 摘要)")
+    pa.set_defaults(func=cmd_parity)
+
+    qt = sub.add_parser("qmt-translate", help="akquant Strategy → QMT body 翻译 (本地 stub)")
+    qt.add_argument("strategy", help="akquant strategy .py 路径")
+    qt.add_argument("config", help="CONFIG JSON 路径")
+    qt.add_argument("--spec", help="spec_strategy.json 路径 (可选)")
+    qt.add_argument("--output", help="QMT body 落盘路径")
+    qt.set_defaults(func=cmd_qmt_translate)
+
+    cm = sub.add_parser("commit", help="commiter 5 步打包上传")
+    cm.add_argument("strategy_id", help="server 端 strategy_id")
+    cm.add_argument("--strategy", help="akquant strategy .py 路径 (默认 <id>.py)")
+    cm.add_argument("--result", required=True, help="metrics result.json 路径")
+    cm.add_argument("--config", help="config.json 路径")
+    cm.add_argument("--spec", help="spec_strategy.json 路径")
+    cm.add_argument("--bundle-out", help="bundle tar.gz 落盘路径")
+    cm.add_argument("--skip-export", action="store_true",
+                    help="跳过 step 5 (POST /strategies/:id/export)")
+    cm.add_argument("--export-out", help="step 5 输出 .qmt.py 路径")
+    cm.set_defaults(func=cmd_commit)
+
+    d = sub.add_parser("dataset", help="构建/列出 prebuilt 数据集")
+    dsub = d.add_subparsers(dest="subcmd", required=True)
+    dsub.add_parser("list", help="列 server 内置预构建池")
+    df = dsub.add_parser("fetch", help="下载 prebuilt")
+    df.add_argument("--symbols", required=True,
+                    help="逗号分隔 6 位裸码 (后缀自动剥)")
+    df.add_argument("--period", default="1d")
+    df.add_argument("--start", help="YYYYMMDD")
+    df.add_argument("--end", help="YYYYMMDD")
+    dm = dsub.add_parser("manifest", help="固化 manifest JSON")
+    dm.add_argument("--symbols", required=True)
+    dm.add_argument("--start", required=True)
+    dm.add_argument("--end", required=True)
+    dm.add_argument("--output", help="manifest 落盘路径")
+    d.set_defaults(func=cmd_dataset)
+
+    # —— K 线数据 (详情页图表) ——
+    kl = sub.add_parser("kline", help="最近 N 天日线 OHLCV → stdout JSON (本地 prebuilt, 缺失回退 QMT bridge)")
+    kl.add_argument("--symbols", required=True, help="逗号分隔 6 位裸码")
+    kl.add_argument("--days", type=int, default=90, help="最近 N 个自然日 (默认 90)")
+    kl.add_argument("--server", default="http://127.0.0.1:9000",
+                    help="bridge 地址 (回退时用, 默认 http://127.0.0.1:9000)")
+    kl.set_defaults(func=cmd_kline)
+
+    # —— 标的池批量添加 (详情页) ——
+    uv = sub.add_parser("universe", help="列 universe 标的列表 → stdout JSON (代码+名称)")
+    uv.add_argument("--type", required=True,
+                    choices=["all_a", "etf", "convertible_bond", "index"],
+                    help="类别: all_a / etf / convertible_bond / index (指数成分)")
+    uv.add_argument("--index", default=None,
+                    help="--type index 时的指数代码 (000300/000905 等; 名称用本地 bundle 补)")
+    uv.add_argument("--server", default="http://127.0.0.1:9000",
+                    help="bridge 地址 (本地无 bundle 回退时用, 默认 http://127.0.0.1:9000)")
+    uv.set_defaults(func=cmd_universe)
+
+    # —— 股票池 (指数/板块成分, 详情页一键导入) ——
+    ix = sub.add_parser("index-stocks", help="读 QMT bridge 股票池 → stdout JSON (6 位裸码)")
+    ix.add_argument("--pool", required=True,
+                    help="池标识: 指数代码 (000016 上证50 / 000300 沪深300 / 000905 中证500 / "
+                         "000852 中证1000) 或 all_a (沪深A股) / cb (沪深转债) / etf (场内ETF)")
+    ix.add_argument("--server", default="http://127.0.0.1:9000", help="bridge 地址 (默认 http://127.0.0.1:9000)")
+    ix.set_defaults(func=cmd_index_stocks)
+
+    # —— 实盘 ——
+    live_p = sub.add_parser("live", help="实盘 / 仿真运行策略 (包装 akquant.run_live)")
+    live_sub = live_p.add_subparsers(dest="subcmd", required=True)
+    run_p = live_sub.add_parser("run", help="运行一个 strategy.py")
+    run_p.add_argument("strategy", type=Path, help="strategy.py 路径")
+    run_p.add_argument("--mode", choices=["paper", "broker_live"], default="paper",
+                       help="trading_mode (default: paper)")
+    run_p.add_argument("--broker", default="replay",
+                       help="broker 名称: ctp / qmf / replay / qmt (default: replay)")
+    run_p.add_argument("--market-broker", default=None,
+                       help="独立行情 broker (e.g. qmt_market)")
+    run_p.add_argument("--symbols", default=None,
+                       help="标的列表, 逗号分隔")
+    run_p.add_argument("--duration", default="1h",
+                       help="运行时长 (akquant 解析)")
+    run_p.add_argument("--class-name", default="Strategy",
+                       help="strategy.py 里的类名")
+    run_p.add_argument("--gateway-options", default=None,
+                       help="k=v 字典, 透传给 run_live")
+    run_p.add_argument("--replay-days", type=int, default=30,
+                       help="broker=replay 时取最近 N 天真实日线 (默认 30; "
+                            "策略 warmup 超窗口需加大, e.g. 90)")
+    run_p.add_argument("--initial-cash", type=float, default=None)
+    run_p.add_argument("--log-level", default="INFO",
+                       choices=["DEBUG", "INFO", "WARNING", "ERROR"])
+    run_p.add_argument("--log-file", type=Path, default=None)
+    run_p.set_defaults(func=cmd_live_run)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())