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

hamuna_quant_cli/runtime/http_client.py

@@ -0,0 +1,209 @@
+"""hamuna_quant_cli.runtime.http_client: apikey HTTPS client → server proxy.
+
+CLI 持 hamuna apikey (ADR-0001 §86), 调 server 端 /api/v1/proxy/data/{endpoint}.
+Server 校验 apikey 后用内部 JWT 调容维接口 (符合 ADR-016 "数据接口全部在 server 端").
+
+server.json 注入优先级 (Round 14 重构):
+  1. HAMUNA_SERVER env (字符串 URL, 跳过 server.json)         — CI / 临时覆盖
+  2. HAMUNA_SERVER_JSON env (完整文件路径)                   — 调试 / 自定义
+  3. ./scripts/server.json (当前 cwd)                        — 项目根 dev 模式 (优先)
+  4. <hamuna_quant_cli 包根>/scripts/server.json              — pip install 后用
+  5. ./server.json (简化, 当前 cwd)                          — 单文件部署
+  6. 默认 http://localhost:8080                                — 兜底
+
+credentials.json 不再含 api_base — 严格分离"部署"与"凭证".
+"""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+from urllib.error import HTTPError
+import json
+
+from . import cache
+
+
+# 默认 server 地址 (ADR-0001 §393)
+_DEFAULT_SERVER = 'http://localhost:8080'
+
+# 默认 apikey 路径 (~/.hamuna/credentials.json), 字段 api_key (含 key_id.key_secret 的整串)
+_CREDS_PATH = Path.home() / '.hamuna' / 'credentials.json'
+
+# server.json 候选路径 — 按优先级第一个存在的生效
+_PACKAGE_ROOT = Path(__file__).resolve().parent.parent  # hamuna_quant_cli/
+_SERVER_CANDIDATES = [
+    Path.cwd() / 'scripts' / 'server.json',                   # dev: 项目根 scripts/
+    _PACKAGE_ROOT / 'scripts' / 'server.json',               # pip install: 包内置 scripts/
+    Path.cwd() / 'server.json',                                # 单文件部署
+]
+
+
+# 证券代码归一 (与后端 rongwei.NormalizeStockCode 同规则):
+#   后缀 ".SH/.sz/.bj" → 剥;  前缀 "SH600000/sz000001" → 剥;  裸 6 位原样。
+_CODE_SUFFIX_RE = re.compile(r'^(.*)\.(sh|sz|bj)$', re.IGNORECASE)
+_CODE_PREFIX_RE = re.compile(r'^(sh|sz|bj)(\d{6})$', re.IGNORECASE)
+
+
+def _normalize_stock_code(code: str) -> str:
+    code = code.strip()
+    m = _CODE_SUFFIX_RE.match(code)
+    if m:
+        code = m.group(1)
+    m = _CODE_PREFIX_RE.match(code)
+    if m:
+        code = m.group(2)
+    return code
+
+
+def _normalize_params(params: dict) -> dict:
+    """StockCode 值归一成裸 6 位(容维上游不接受后缀/前缀)。其他字段不动。
+
+    归一发生在缓存 key 之前, 让 "600000.SH" 与 "600000" 命中同一本地缓存。
+    """
+    out = dict(params)
+    for k, v in list(out.items()):
+        if k == 'StockCode' and isinstance(v, str):
+            out[k] = _normalize_stock_code(v)
+    return out
+
+
+def _resolve_server() -> str:
+    """server 地址解析 (Round 14 多路径 fallback).
+
+    优先级: HAMUNA_SERVER env > HAMUNA_SERVER_JSON env > _SERVER_CANDIDATES > 默认.
+    credentials.json **不**再含 api_base (那是用户凭证, 不该混部署信息); 严格分离
+    "部署" 与 "凭证" 两个关注点. env 仍最高, 适合 CI / 本地临时覆盖.
+    """
+    env = os.environ.get('HAMUNA_SERVER')
+    if env:
+        return env
+    json_path = os.environ.get('HAMUNA_SERVER_JSON')
+    if json_path:
+        try:
+            v = json.loads(Path(json_path).read_text(encoding='utf-8')).get('api_base')
+            if v:
+                return v
+        except Exception:
+            pass
+    for cand in _SERVER_CANDIDATES:
+        if cand.is_file():
+            try:
+                v = json.loads(cand.read_text(encoding='utf-8')).get('api_base')
+                if v:
+                    return v
+            except Exception:
+                continue
+    return _DEFAULT_SERVER
+
+
+_TOKEN_CACHE: str | None = None  # 进程内缓存 (commit 5 步只读一次 credentials.json)
+
+
+def _load_token() -> str:
+    """返回完整 Bearer token 串 (key_id.key_secret).
+
+    ponytail: 进程内缓存; 部署/测试改 api_key 后需重启 CLI. add when: 用户报
+    "频繁读 credentials.json 慢/文件锁" → 改 mtime-based invalidation.
+    """
+    global _TOKEN_CACHE
+    if _TOKEN_CACHE is not None:
+        return _TOKEN_CACHE
+    if not _CREDS_PATH.exists():
+        raise FileNotFoundError(
+            f'没有找到 Hamuna API key 凭证文件: {_CREDS_PATH}\n'
+            f'\n'
+            f'API key 在 Hamuna 平台控制台/账号后台签发(登录平台 → 账户设置/API Keys → 创建)。\n'
+            f'CLI 无 login 子命令; 手动创建凭证文件即可:\n'
+            f'  {_CREDS_PATH}\n'
+            f'  {{ "api_key": "hamuna_xxxxx" }}\n'
+            f'字段名是 api_key(不是 apikey). server 地址在部署方管 scripts/server.json,\n'
+            f'默认 http://localhost:8080(或设 HAMUNA_SERVER env 覆盖)。'
+        )
+    creds = json.loads(_CREDS_PATH.read_text(encoding='utf-8'))
+    if 'api_key' not in creds:
+        raise KeyError(
+            f'{_CREDS_PATH} 缺 api_key 字段。凭证格式: '
+            f'{{ "api_key": "hamuna_xxxxx" }}'
+        )
+    _TOKEN_CACHE = creds['api_key']
+    return _TOKEN_CACHE
+
+
+def verify_credentials() -> tuple[bool, str]:
+    """验证 API key 是否合法: GET /api/v1/cli/whoami (API Key 鉴权)。
+
+    返回 (ok, msg):
+      ok=False + 消息 → 凭证缺失 / 401 非法 / server 不可达, 引导重签。
+      不抛异常 — 验证失败是"该去注册/申请 key"的信号, 不是让流程崩掉。
+    仅当 skii 加载时做一次, 不污染正常 run 的异常路径。
+    """
+    try:
+        token = _load_token()
+    except Exception as e:  # FileNotFoundError / KeyError
+        return False, f'凭证文件缺失: {e}'.split('\n')[0]
+    try:
+        req = Request(f'{_resolve_server()}/api/v1/cli/whoami', headers={
+            'Authorization': f'Bearer {token}',
+            'Accept': 'application/json',
+        })
+        with urlopen(req, timeout=10) as resp:
+            if resp.status != 200:
+                return False, f'whoami 返回 HTTP {resp.status}'
+            return True, 'API key 有效'
+    except HTTPError as e:
+        if e.code == 401:
+            return False, 'API key 无效或已失效 (HTTP 401)'
+        return False, f'whoami 失败: HTTP {e.code} {e.reason}'
+    except Exception as e:
+        return False, f'无法连接 server ({type(e).__name__})'
+
+
+def proxy_get(endpoint: str, params: dict | None = None, *, no_cache: bool = False) -> dict:
+    """GET /api/v1/proxy/data/<endpoint>?<params> (API Key 鉴权).
+
+    `endpoint` 例: "snapshot", "history", "trade_days", "stock_info".
+    缓存语义: 默认走本地 ~/.hamuna/cache/<endpoint>/<key>.json; 写后下次命中。
+    no_cache=True: 跳过读 / 写 — 适合 verify_credentials 这种"必须是最新"的探测。
+    返回 {ok, value} envelope (server 端约定, 与 bridge_server 兼容)。
+    """
+    token = _load_token()
+    params = _normalize_params(params or {})
+    cache_key = cache.make_key(endpoint, params)
+    if not no_cache:
+        hit = cache.read(cache_key)
+        if hit is not None:
+            return hit
+    qs = urlencode(params, doseq=True) if params else ''
+    url = f'{_resolve_server()}/api/v1/proxy/data/{endpoint}'
+    if qs:
+        url = f'{url}?{qs}'
+    req = Request(url, headers={
+        'Authorization': f'Bearer {token}',
+        'Accept': 'application/json',
+    })
+    with urlopen(req, timeout=30) as resp:
+        raw = resp.read().decode('utf-8', errors='replace')
+    payload = json.loads(raw)
+    if not no_cache:
+        cache.write(cache_key, payload)
+    return payload
+
+
+def proxy_post(endpoint: str, body: dict, *, no_cache: bool = False) -> dict:
+    """POST /api/v1/proxy/data/<endpoint> (API Key 鉴权).
+
+    `body` 序列化成 JSON body. 不走本地缓存 (POST 一般是 mutation).
+    """
+    token = _load_token()
+    url = f'{_resolve_server()}/api/v1/proxy/data/{endpoint}'
+    req = Request(url, data=json.dumps(body).encode('utf-8'), headers={
+        'Authorization': f'Bearer {token}',
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+    }, method='POST')
+    with urlopen(req, timeout=30) as resp:
+        raw = resp.read().decode('utf-8', errors='replace')
+    return json.loads(raw)

hamuna_quant_cli/runtime/s3client.py

@@ -0,0 +1,109 @@
+"""hamuna_quant_cli.runtime.s3client: 直连对象存储下载内置数据集整包.
+
+背景: server 的 presign 下载地址在腾讯 COS 反代 (hz.yunvm.com:80) 上 403
+SignatureDoesNotMatch; boto3 全头签名 get_object 正常。所以 CLI 从 server 拉
+【加密的 S3 凭据】 (见 backend/internal/handler/datasets.go::DownloadArtifactCredentials),
+用 raw API key 派生密钥解密后直连对象存储下载。
+
+加密契约 (与 backend/internal/sourcecrypto/encrypt.go 逐参对齐, 改任意一边另一边
+解密必挂):
+  IKM  = raw API key (credentials.json 的 api_key 字段, 与 server 端加密用同一把 —
+         零密钥传输)
+  HKDF = HKDF-SHA256, salt="s3-creds|<datasetID>", info="hamuna-s3-creds-v1", 32 字节
+  AES  = AES-256-GCM, nonce=envelope.iv, aad=envelope.aad (=datasetID)
+  envelope = {v:1, alg:"AES-256-GCM", sid, iv:b64, ct:b64, aad}
+
+来源: skills/hamuna-strategy/strategy_cli/runtime/s3client.py wholesale 移植
+(Round 14 独立分发, 不再依赖 v1 skill PYTHONPATH)。
+依赖: cryptography (HKDF/AES-GCM) + boto3 (S3 签名下载)。
+"""
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+
+import boto3
+from botocore.config import Config
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+_SALT_PREFIX = 's3-creds|'
+_INFO = 'hamuna-s3-creds-v1'
+
+
+def derive_key(ikm: str, dataset_id: str) -> bytes:
+    """HKDF-SHA256(ikm=raw api key, salt=s3-creds|<did>, info=hamuna-s3-creds-v1) → 32B。
+
+    Go 侧 sourcecrypto.DeriveKeyFrom 用同一固定参数 pin 了 base64 key
+    (TestDeriveKeyFromParity), 本模块 _selfcheck 也 pin 同一值 → 跨语言 parity 双端锁死。
+    """
+    salt = (_SALT_PREFIX + dataset_id).encode('utf-8')
+    return HKDF(algorithm=hashes.SHA256(), length=32,
+                salt=salt, info=_INFO.encode('utf-8')).derive(ikm.encode('utf-8'))
+
+
+def decrypt_s3_params(raw_api_key: str, dataset_id: str, env: dict) -> dict:
+    """解密 server 下发的加密 S3 凭据 envelope → {endpoint, region, bucket, access_key, ...}。
+
+    env 必须是 {v:1, alg:'AES-256-GCM', sid, iv:b64, ct:b64, aad}, aad 字段 = dataset_id
+    (server 用 id.Hex() 作 GCM 关联数据)。解密失败 (API key 不匹配 / 参数漂移 / 篡改)
+    → 抛 ValueError 带修复提示, 不静默用坏凭据 (下载必 403)。
+    """
+    key = derive_key(raw_api_key, dataset_id)
+    try:
+        iv = base64.b64decode(env['iv'])
+        ct = base64.b64decode(env['ct'])
+        aad = env.get('aad', dataset_id).encode('utf-8')
+        plaintext = AESGCM(key).decrypt(iv, ct, aad)
+    except Exception as e:
+        raise ValueError(
+            f'解密 S3 凭据失败: {e}. 密钥派生参数 (salt/info) 或 API key 与 server 不匹配, '
+            f'或响应被篡改。'
+        ) from e
+    return json.loads(plaintext.decode('utf-8'))
+
+
+def _client(params: dict):
+    """boto3 S3 client: 全头签名 (s3v4) + path-style 寻址 (COS 反代要求)。"""
+    return boto3.client(
+        's3',
+        endpoint_url=params['endpoint'],
+        region_name=params.get('region', 'us-east-1'),
+        aws_access_key_id=params['access_key'],
+        aws_secret_access_key=params['secret_key'],
+        use_ssl=params.get('endpoint', '').startswith('https'),
+        config=Config(signature_version='s3v4',
+                      s3={'addressing_style': 'path'}),
+    )
+
+
+def download_to(params: dict, dest: Path) -> None:
+    """boto3 全头签名 get_object 下载整包到 dest (分块流式, 不整包进内存)。
+
+    422MB 整包先落盘再经 pyarrow 读盘 (可 mmap), 避免 bytes + DataFrame 内存堆两份。
+    """
+    client = _client(params)
+    resp = client.get_object(Bucket=params['bucket'], Key=params['key'])
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    with resp['Body'] as stream, dest.open('wb') as f:
+        while True:
+            chunk = stream.read(1 << 20)  # 1MB
+            if not chunk:
+                break
+            f.write(chunk)
+
+
+def _selfcheck() -> None:
+    """HKDF 派生跨语言 parity 自检 (不依赖网络 / server)。
+
+    base64 pin 值来自 Go 测试 TestDeriveKeyFromParity 的锚点 — 任一侧改
+    salt/info/长度, 这里即挂。运行:
+      python -c "from hamuna_quant_cli.runtime.s3client import _selfcheck; _selfcheck()"
+    """
+    key = derive_key('hamuna_test_api_key_123456', 'abc123')
+    b64 = base64.b64encode(key).decode('ascii')
+    assert b64 == '5afG4AQFKc5zIxUKLkAh925TQAmROwX2/qXzsAfn2Oo=', (
+        f'HKDF key 与 Go 侧 pin 不符: {b64}')
+    print('[selfcheck] s3client HKDF parity OK')

hamuna_quant_cli/runtime/server_client.py

@@ -0,0 +1,285 @@
+"""strategy_cli.runtime.server_client (hamuna-strategy-v2): CLI → server 上传 (backtest result).
+
+v2 精简底座: 仅保留 _api_call + upload_backtest_result + create_strategy;
+扩展部分 (commiter 5 步打包上传需要):
+  - upload_strategy_code  POST /strategies/{id}/code   (multipart body + params)
+  - export_strategy       POST /strategies/{id}/export  (拉 server 端 .qmt.py shell)
+
+不进 server_client 的 (不在 skill 端做): pyarmor / embedded API key / cert / QMT
+shell 渲染 — 这些都跑在 server 端 (ADR-0023 + ADR-0025), cloud 是 single source
+of truth. 本地仅做 multipart 拼 + 提交, 不碰加密 / 不读 cert.
+
+底层鉴权 / envelope 解构 / NaN 清洗与 v1 完全一致 (wholesale copy → 极简裁剪, 见 v1
+server_client.py git blame); 服务端契约 backend/internal/model/model.go::BacktestResult
+仍 13 顶层 key + metrics 15 key 不变 (v1 / v2 同 schema)。
+"""
+from __future__ import annotations
+
+import json
+import math
+import mimetypes
+import uuid
+from pathlib import Path
+from urllib.request import Request, urlopen
+from urllib.error import HTTPError
+
+from .http_client import _load_token, _resolve_server, _CREDS_PATH
+
+
+class ServerError(RuntimeError):
+    """server 端非 2xx 响应。"""
+
+
+def _api_call(method: str, path: str, body: dict | None = None) -> dict:
+    """通用 HTTPS 调用: 返 server 端 envelope.DataValue; 非 2xx / Result=false raise.
+
+    server 所有响应都是容维 envelope {Result, Error, Message, DataValue}
+    (backend/pkg/response/response.go), 此处解构出 DataValue 给 caller.
+    """
+    token = _load_token()
+    url = f'{_resolve_server()}{path}'
+    data = json.dumps(body).encode('utf-8') if body is not None else None
+    headers = {
+        'Authorization': f'Bearer {token}',
+        'Accept': 'application/json',
+    }
+    if data is not None:
+        headers['Content-Type'] = 'application/json'
+    req = Request(url, data=data, method=method, headers=headers)
+    try:
+        with urlopen(req, timeout=60) as resp:
+            raw = resp.read().decode('utf-8')
+    except HTTPError as e:
+        resp_body = e.read().decode('utf-8', errors='replace')[:500]
+        if e.code == 401:
+            raise ServerError(
+                f'{method} {path} 失败: HTTP 401 — API key 无效或已失效.\n'
+                f'请在 Hamuna 平台控制台/账号后台重新签发 API key, 更新 {_CREDS_PATH} 的 api_key 字段。'
+            ) from e
+        raise ServerError(
+            f'{method} {path} 失败: HTTP {e.code} {e.reason}; body={resp_body}'
+        ) from e
+    envelope = json.loads(raw) if raw else {}
+    if isinstance(envelope, dict) and 'DataValue' in envelope:
+        if not envelope.get('Result', False):
+            raise ServerError(
+                f'{method} {path} 业务失败: Error={envelope.get("Error")} '
+                f'Message={envelope.get("Message")}'
+            )
+        return envelope['DataValue']
+    return envelope
+
+
+def upload_backtest_result(strategy_id: str, result: dict) -> dict:
+    """PUT /api/v1/strategies/{id}/result → 上传 BacktestResult-shape dict.
+
+    兼容 akquant_runner.run_akquant_backtest() 输出 (13 顶层 key + metrics 子 dict 15 key + ...),
+    先做轻清洗: NaN/Inf → None (json 标准不允许), 后传给 server.
+    """
+    payload = _sanitize_for_json(result)
+    return _api_call('PUT', f'/api/v1/strategies/{strategy_id}/result', payload)
+
+
+def create_strategy(name: str, code: str = '', params: dict | None = None) -> dict:
+    """POST /api/v1/strategies → 新建 strategy (供 _upload_after_run --name auto-create 用).
+
+    name 必填 (id 一致性锚点, 与 v1 server_client 同); code 可选 (后端落库 +
+    /source envelope 加密用, v2 --upload --code 路径才填); params 默认 {} (作
+    BacktestResult.params 落库). 返 server DataValue (含 _id / id / name).
+    """
+    body: dict = {'name': name, 'code': code}
+    if params is not None:
+        body['params'] = params
+    return _api_call('POST', '/api/v1/strategies', body)
+
+
+def upload_strategy_code(
+    strategy_id: str,
+    strategy_path: str,
+    params: dict | None = None,
+) -> dict:
+    """POST /api/v1/strategies/{id}/code (multipart) → 上传策略源码 + params.
+
+    ADR-0023: 后端存 code_obfuscated = body bytes (GBK 编码); cert + subscription gate
+    是真保护, 不在 skill 端做加密/pyminifier.
+    ADR-0025: multipart 含 `params` 字段 (JSON 字符串), server 落库覆盖 strategies.params
+    (CONFIG 块渲染源).
+
+    body bytes = UTF-8 源 → GBK (per `backend/internal/handler/qmt_export.go::storeBody`
+    注释 "Strategy files are GBK-encoded, server reads GBK first fall back UTF-8");
+    无法 GBK 编码的字符 → errors='replace' (不阻断上传).
+
+    返 {body_hash, ok} (per handler::UploadStrategyCode 响应 shape).
+    """
+    code = Path(strategy_path).read_text(encoding='utf-8')
+    gbk = code.encode('gbk', errors='replace')
+    boundary = f'----hamuna-{uuid.uuid4().hex}'
+    filename = Path(strategy_path).name
+    ctype = mimetypes.guess_type(filename)[0] or 'application/octet-stream'
+
+    parts: list[bytes] = [
+        (f'--{boundary}\r\n'
+         f'Content-Disposition: form-data; name="file"; filename="{filename}"\r\n'
+         f'Content-Type: {ctype}\r\n\r\n').encode('utf-8'),
+        gbk,
+    ]
+    if params is not None:
+        # multipart 表单字段: params = JSON 字符串 (per ADR-0025 + handler::storeBody)
+        parts.append(
+            (f'\r\n--{boundary}\r\n'
+             f'Content-Disposition: form-data; name="params"\r\n\r\n').encode('utf-8')
+        )
+        parts.append(json.dumps(params, ensure_ascii=False).encode('utf-8'))
+    parts.append(f'\r\n--{boundary}--\r\n'.encode('utf-8'))
+    data = b''.join(parts)
+
+    token = _load_token()
+    url = f'{_resolve_server()}/api/v1/strategies/{strategy_id}/code'
+    req = Request(
+        url, data=data, method='POST',
+        headers={
+            'Authorization': f'Bearer {token}',
+            'Content-Type': f'multipart/form-data; boundary={boundary}',
+        },
+    )
+    try:
+        with urlopen(req, timeout=60) as resp:
+            raw = resp.read().decode('utf-8')
+    except HTTPError as e:
+        resp_body = e.read().decode('utf-8', errors='replace')[:500]
+        if e.code == 401:
+            raise ServerError(
+                f'上传源码失败: HTTP 401 — API key 无效或已失效.\n'
+                f'请在 Hamuna 平台控制台/账号后台重新签发 API key, 更新 {_CREDS_PATH} 的 api_key 字段。'
+            ) from e
+        raise ServerError(
+            f'上传源码失败: HTTP {e.code} {e.reason}; body={resp_body}'
+        ) from e
+    envelope = json.loads(raw) if raw else {}
+    if isinstance(envelope, dict) and 'DataValue' in envelope:
+        if not envelope.get('Result', False):
+            raise ServerError(
+                f'上传源码业务失败: Error={envelope.get("Error")} '
+                f'Message={envelope.get("Message")}'
+            )
+        return envelope['DataValue']
+    return envelope
+
+
+def list_datasets() -> list:
+    """GET /api/v1/datasets → server 内置数据集列表 (含 builtin/enabled 标记)。
+
+    CLI 取数 miss 时先查这里, 匹配到内置数据集就整包下载 (s3_credentials 路径)。
+    """
+    out = _api_call('GET', '/api/v1/datasets')
+    if isinstance(out, list):
+        return out
+    if isinstance(out, dict) and 'DataValue' in out:
+        return out.get('DataValue', [])
+    return []
+
+
+def s3_credentials(dataset_id: str, key: str) -> dict:
+    """GET /api/v1/datasets/{id}/artifacts/credentials?key= → 加密 S3 凭据 envelope。
+
+    server 用 raw API key 派生密钥加密 S3 连接参数 (handler::DownloadArtifactCredentials),
+    返回【bare AES-GCM envelope】(不带 DataValue 包装)。由 s3client.decrypt_s3_params
+    用同一 raw key 解密 → boto3 直连下载。presign 在 COS 反代上 403, 这是替代路径。
+    """
+    import urllib.parse
+    qs = urllib.parse.urlencode({'key': key})
+    out = _api_call('GET', f'/api/v1/datasets/{dataset_id}/artifacts/credentials?{qs}')
+    if isinstance(out, dict) and out.get('ct'):
+        return out
+    raise ServerError(
+        f'artifacts/credentials 响应非加密 envelope: {out}'
+    )
+
+
+def export_strategy(strategy_id: str, output_path: str | None = None) -> dict:
+    """POST /api/v1/strategies/{id}/export → 拉 cloud 渲染的 .qmt.py shell.
+
+    ADR-0023: cloud 是 single source of truth — shell 渲染 (CONFIG 块 + embedded
+    API key + cert 签) 全在 server 端. 本函数仅下载 + 落盘, 不读 shell 内容.
+
+    返 dict: {shell_path, shell_bytes} (shell_path = output_path 或 None).
+    """
+    token = _load_token()
+    url = f'{_resolve_server()}/api/v1/strategies/{strategy_id}/export'
+    req = Request(
+        url, data=b'', method='POST',
+        headers={
+            'Authorization': f'Bearer {token}',
+            'Accept': 'application/octet-stream, application/json',
+        },
+    )
+    try:
+        with urlopen(req, timeout=60) as resp:
+            # server 既可返 raw .qmt.py 也可返 JSON envelope — 读 Content-Type 判
+            ctype = resp.headers.get('Content-Type', '')
+            raw = resp.read()
+            if 'json' in ctype.lower():
+                envelope = json.loads(raw.decode('utf-8'))
+                if isinstance(envelope, dict) and 'DataValue' in envelope:
+                    if not envelope.get('Result', False):
+                        raise ServerError(
+                            f'QMT export 业务失败: Error={envelope.get("Error")} '
+                            f'Message={envelope.get("Message")}'
+                        )
+                    # DataValue 可能是 base64 编码的 shell 字节
+                    import base64
+                    shell_bytes = base64.b64decode(envelope['DataValue'])
+                else:
+                    shell_bytes = raw
+            else:
+                shell_bytes = raw
+    except HTTPError as e:
+        resp_body = e.read().decode('utf-8', errors='replace')[:500]
+        if e.code == 401:
+            raise ServerError(
+                f'QMT export 失败: HTTP 401 — API key 无效或已失效'
+            ) from e
+        if e.code == 402:
+            raise ServerError(
+                f'QMT export 失败: HTTP 402 — 订阅未激活 (subscription gate)'
+            ) from e
+        raise ServerError(
+            f'QMT export 失败: HTTP {e.code} {e.reason}; body={resp_body}'
+        ) from e
+
+    if output_path:
+        Path(output_path).write_bytes(shell_bytes)
+        return {'shell_path': str(output_path), 'shell_bytes': len(shell_bytes)}
+    return {'shell_path': None, 'shell_bytes': len(shell_bytes)}
+
+
+def _sanitize_for_json(obj):
+    """递归把 NaN/Inf → None + Timestamp/datetime → ISO 字符串 (json 标准不允许).
+
+    akquant runner 输出含 pd.Timestamp / datetime / numpy 标量 (e.g. equity_curve.date
+    列是 Timestamp; period.start/end 可能是 datetime); 不转换就 TypeError.
+    """
+    # datetime / pd.Timestamp 优先 (避免落入 numpy 标量分支)
+    try:
+        import datetime as _dt
+        if isinstance(obj, _dt.datetime):
+            return obj.isoformat()
+        if isinstance(obj, _dt.date):
+            return obj.isoformat()
+        if isinstance(obj, _dt.timedelta):
+            return obj.total_seconds()
+    except ImportError:
+        pass
+    if isinstance(obj, dict):
+        return {k: _sanitize_for_json(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_sanitize_for_json(x) for x in obj]
+    if isinstance(obj, float):
+        return None if (math.isnan(obj) or math.isinf(obj)) else obj
+    # numpy / pandas 标量 → 标 Python 类型
+    if hasattr(obj, 'item') and callable(obj.item):
+        try:
+            return obj.item()
+        except (ValueError, TypeError):
+            pass
+    return obj

hamuna_quant_cli/scripts/server.json

@@ -0,0 +1,4 @@
+{
+  "api_base": "http://localhost:8080",
+  "_comment": "部署配置层 — Round 14 注入方式: pip install hamuna-quant-cli 后, http_client.py 自动按优先级 1) HAMUNA_SERVER env 2) HAMUNA_SERVER_JSON env 3) ./scripts/server.json 4) <包根>/scripts/server.json (本文件) 5) ./server.json 6) 默认 localhost:8080 解析. 部署方只需改这一个文件 + 重装包即可切 server."
+}