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

hamuna_quant_cli/akquant_schema_adapter.py

@@ -0,0 +1,443 @@
+"""ADR-0040 Phase B — akquant 结果 schema adapter (v2 自有版本, B1).
+
+把 akquant BacktestResult 折成 hamuna `backtest_result.json` 13-key dict
+(沿 driver.py:113-128 模板, 见 references/backtest-result.md).
+
+来源: 原仓根 `hamuna_quant_cli/references/akquant_schema_adapter.py` (Phase B).
+本文件是 wholesale copy, 算法/字段映射/trades_df→executions_df 改动 与原仓根
+一致 (B 重写不动数值层). 迁移原因: v2 skill 未来独立分发, 不依赖仓根.
+
+字段映射 (15 metrics):
+  total_return ← r.metrics.total_return_pct / 100
+  annual_return ← r.metrics.annual_return_pct / 100  (akquant 直接给)
+  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
+  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)
+  excess_return ← NaN (同上)
+  sortino ← 自算 (沿 metrics.py:161)
+  calmar ← 自算 (沿 metrics.py:176)
+  var_95 ← 自算 (沿 metrics.py:184)
+  profit_factor ← 自算 from trades_df (沿 metrics.py:192)
+  annual_volatility ← alias of volatility
+
+equity_curve: r.equity_curve() Series → [{date:'YYYYMMDD', nav: float}, ...]
+  首日补 initial_capital (driver.py:103-106 同款)
+
+trades: 优先 executions_df (含 buy + sell 单独流水, buy-only 策略也能记 buy);
+  fallback trades_df (FIFO closed pair). metrics 仍用 trades_df 算
+  win_rate / profit_factor (closed pair 才是有效 metric 输入).
+
+universe / period / params: 从 cfg 推
+
+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 末点
+  - avg_holding_period = metrics 内同名字段
+  - suggestions = [] (Phase B 最小化; driver._suggestions 不复用)
+
+NaN 纪律 (backtest-result.md §纪律):
+  NaN/null = 计算 bug, 不是策略. 安全 getter (R1 mitigation) 缺失字段填 NaN
+  而不是 KeyError / AttributeError.
+
+Ponytail ceiling: 不实现 benchmark alpha/beta/IR 单独导出.
+  akquant 多出字段 (exposure_df / attribution_df / capacity_df / cash_curve / orders_df / ...)
+  落到 result['params']['_akquant_extra'] 子键 (optional, UI 不消费).
+"""
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+# hamuna metrics 15 keys (driver.py + metrics.py:218-237, 与 server model.BacktestResult 对齐)
+# v2 自有 _metrics_15 (B2 搬入, 算法与原仓根一致)
+from ._metrics_15 import HAMUNA_METRICS_15  # noqa: E402  re-export
+
+TRADING_DAYS_PER_YEAR = 252
+
+# 单点 metric 实现 (volatility/sortino/calmar/var_95 + 4 trade-derived);
+# 见 `hamuna_quant_cli.references._metrics_15` — 与 v1 `strategy_cli.runtime.metrics` 算法对齐.
+# 这里只 import, 不再独立实现 (R-metrics-dedup).
+from ._metrics_15 import (
+    volatility as _volatility,
+    sortino as _sortino,
+    calmar as _calmar,
+    var_95 as _var_95,
+    win_rate as _win_rate,
+    profit_loss_ratio as _profit_loss_ratio,
+    avg_holding_period as _avg_holding_period,
+    profit_factor as _profit_factor,
+)
+
+
+# ---- safe-getter (R1 mitigation: akquant schema drift 兜底) ----
+def _safe_get(obj: Any, key: str, default: float = float('nan')) -> float:
+    """attr 不存在或为 None → 返回 default (NaN). 数值转 float."""
+    try:
+        v = getattr(obj, key)
+    except AttributeError:
+        return default
+    if v is None:
+        return default
+    try:
+        f = float(v)
+    except (TypeError, ValueError):
+        return default
+    if math.isnan(f) or math.isinf(f):
+        return default
+    return f
+
+
+def _nan() -> float:
+    return float('nan')
+
+
+# ---- 自算函数 (volatility/sortino/calmar/var_95 + 4 trade-derived)
+# 全部从 `hamuna_quant_cli.references._metrics_15` 单点 import (上面 import 块).
+# ----
+
+
+# ---- equity_curve Series → list[{date:'YYYYMMDD', nav}] ----
+def _to_daily(series_or_df: Any, initial_capital: float) -> list[dict]:
+    """akquant r.equity_curve() → list[{date, nav}]. 首点补 initial_capital (driver.py:103-106)."""
+    if series_or_df is None:
+        return []
+    if isinstance(series_or_df, pd.DataFrame):
+        if series_or_df.empty:
+            return []
+        s = series_or_df.iloc[:, 0] if series_or_df.shape[1] == 1 else series_or_df.squeeze()
+    else:
+        s = series_or_df
+    if s is None or len(s) == 0:
+        return []
+    out: list[dict] = []
+    for ts, val in s.items():
+        if pd.isna(val):
+            continue
+        # ts: datetime / str → 'YYYYMMDD'
+        if hasattr(ts, 'strftime'):
+            d = ts.strftime('%Y%m%d')
+        else:
+            d = str(ts)[:8].replace('-', '')
+        try:
+            v = float(val)
+        except (TypeError, ValueError):
+            continue
+        if math.isnan(v) or math.isinf(v):
+            continue
+        out.append({'date': d, 'nav': v})
+    if not out:
+        return out
+    # 首点补 initial_capital (driver.py:103-106 同款)
+    if abs(out[0]['nav'] - initial_capital) > 1e-6:
+        out = [{'date': out[0]['date'], 'nav': initial_capital}] + out
+    return out
+
+
+# ---- trades_df → hamuna 7-field trades ----
+def _trades_df_to_list(trades_df: pd.DataFrame | None,
+                       symbol_names: dict[str, str] | None = None) -> list[dict]:
+    """akquant trades_df → hamuna 7-field trades dict (含 symbol_name).
+
+    symbol_names: 外部注入的 {symbol: stockName} 映射 (从 prebuilt bundle 的
+    stockName 列聚合). hamuna_strategy (QMT 路径) 端 driver._lookup_symbol_name
+    同款行为 — 走本地 dataset → 容维 fallback. 这里只接外部注入, 避免在
+    schema_adapter 里引入跨模块依赖.
+    """
+    if trades_df is None or trades_df.empty:
+        return []
+    out: list[dict] = []
+    for _, row in trades_df.iterrows():
+        ts = row.get('entry_time') or row.get('date') or row.get('time') or row.get('timestamp')
+        if pd.isna(ts):
+            continue
+        if hasattr(ts, 'strftime'):
+            d = ts.strftime('%Y%m%d')
+        else:
+            d = str(ts)[:8].replace('-', '')
+        try:
+            sym = str(row.get('symbol', ''))
+            name = (symbol_names or {}).get(sym) or None
+            out.append({
+                'date': d,
+                'symbol': sym,
+                'side': str(row.get('side', 'buy')),
+                'price': float(row.get('entry_price', row.get('price', 0.0))),
+                'qty': float(row.get('quantity', row.get('qty', 0))),
+                'symbol_name': name,
+            })
+        except (TypeError, ValueError):
+            continue
+    return out
+
+
+# ---- 主入口 ----
+def to_hamuna_result(akquant_r: Any, cfg: dict) -> dict:
+    """akquant BacktestResult → hamuna 13-key dict (driver.py:113 模板)."""
+    initial_capital = float(cfg.get('init_capital', 1_000_000.0))
+    universe = _cfg_universe(cfg)
+    period = {'start': cfg['backtest_start'], 'end': cfg['backtest_end']}
+
+    # trades_df + equity_curve 提取
+    trades_df = getattr(akquant_r, 'trades_df', None)
+    if trades_df is None and hasattr(akquant_r, 'trades'):
+        td = akquant_r.trades
+        trades_df = td if isinstance(td, pd.DataFrame) else None
+    # executions_df 优先 (含 buy + sell 单独流水, buy-only 策略也能记 buy;
+    # trades_df 只含 closed pair, buyhold 之类无 sell → 空). metrics 仍用
+    # trades_df 算 win_rate / profit_factor (closed pair 才是有效 metric 输入).
+    exec_df = getattr(akquant_r, 'executions_df', None)
+    useful_df = exec_df if (exec_df is not None and not exec_df.empty) else trades_df
+    # symbol_names: 优先 cfg 注入, fallback None (trades 里 symbol_name=None)
+    symbol_names = cfg.get('_symbol_names') if isinstance(cfg, dict) else None
+    trades = _trades_df_to_list(useful_df, symbol_names=symbol_names)
+    eq_curve = getattr(akquant_r, 'equity_curve', None)
+    if callable(eq_curve):
+        eq_curve = eq_curve()
+    equity_curve = _to_daily(eq_curve, initial_capital)
+    nav_values = [p['nav'] for p in equity_curve]
+
+    # 15 metrics
+    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()
+    # 自算
+    volatility = _volatility(nav_values) if nav_values else 0.0
+    sortino = _sortino(nav_values) if nav_values else 0.0
+    calmar = _calmar(nav_values) if nav_values else _nan()
+    var_95 = _var_95(nav_values) if nav_values else _nan()
+    profit_loss_ratio = _profit_loss_ratio(trades)
+    avg_holding = _avg_holding_period(trades)
+    profit_factor = _profit_factor(trades)
+
+    metrics = {
+        'total_return': total_return,
+        'annual_return': annual_return,
+        'sharpe': sharpe,
+        'max_drawdown': mdd,
+        'volatility': volatility,
+        'win_rate': win_rate,
+        'profit_loss_ratio': profit_loss_ratio,
+        'avg_holding_period': avg_holding,
+        'benchmark_total_return': _nan(),
+        'excess_return': _nan(),
+        'sortino': sortino,
+        'calmar': calmar,
+        'var_95': var_95,
+        'profit_factor': profit_factor,
+        'annual_volatility': volatility,
+    }
+    # NaN → None 给 JSON (后端 model 拒绝 NaN literal)
+    metrics_clean = {k: (None if isinstance(v, float) and math.isnan(v) else v)
+                     for k, v in metrics.items()}
+
+    # 月度聚合
+    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()
+    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
+
+    # params: cfg 快照 (排除 backtest_start/end)
+    params = {k: v for k, v in cfg.items() if k not in ('backtest_start', 'backtest_end')}
+
+    # akquant 多出字段落到 _akquant_extra (UI 不消费)
+    extra = _extra(akquant_r)
+    if extra:
+        params['_akquant_extra'] = extra
+
+    return {
+        'metrics': metrics_clean,
+        'equity_curve': equity_curve,
+        'benchmark_curve': [],  # akquant 单策略无自动基准 (bench_20260813_201349.json §cons)
+        'trades': trades,
+        'universe': universe,
+        'period': period,
+        'params': params,
+        'monthly_bars': monthly_bars,
+        'monthly_metrics': monthly_metrics,
+        'initial_capital': initial_capital,
+        'final_capital': final_capital,
+        'avg_holding_period': metrics_clean['avg_holding_period'],
+        'suggestions': [],
+    }
+
+
+def normalize_symbol(symbol: str) -> str:
+    """6 位裸码 → 交易所带后缀形态 (bundle stockCode '600000.SH').
+
+    幂等: 已带 .SH/.SZ/.BJ 后缀 / SH600000 前缀形态 → 原样返回.
+    与 __main__._normalize_to_full 同映射 (60/68/11/13 → SH, 其余 → SZ).
+    """
+    s = symbol.strip().upper()
+    if s.endswith(('.SH', '.SZ', '.BJ')):
+        return symbol
+    if len(s) > 2 and s[:2] in ('SH', 'SZ', 'BJ'):
+        s = s[2:]
+    if len(s) != 6 or not s.isdigit():
+        return symbol
+    if s.startswith(('60', '68', '11', '13')):
+        return f'{s}.SH'
+    return f'{s}.SZ'
+
+
+def _cfg_universe(cfg: dict) -> list[str]:
+    """cfg['pool'] / cfg['universe'] → 展开标的代码 list.
+
+    三种形态:
+      - cfg['pool'] = [...]             → 直接 list
+      - cfg['pool'] = {板块: {codes:[]}} → 展开 codes / sub_universe
+      - cfg['universe'] = [...]         → fallback (v2 cfg 主要形态; 与 runner._universe_from_cfg 同语义)
+    输出统一归一为带后缀形态 (与 bundle stockCode / trades.symbol 对齐).
+    """
+    pool = cfg.get('pool')
+    if pool is None:
+        pool = cfg.get('universe') or []
+    if isinstance(pool, list):
+        return [normalize_symbol(s) for s in pool]
+    out: list[str] = []
+    for v in pool.values() if isinstance(pool, dict) else []:
+        if isinstance(v, dict):
+            codes = v.get('codes') or v.get('sub_universe') or []
+            out.extend(codes)
+        elif isinstance(v, list):
+            out.extend(v)
+    return [normalize_symbol(s) for s in sorted(set(out))]
+
+
+def _extra(akquant_r: Any) -> dict:
+    """akquant 多出字段落到 _akquant_extra (Ponytail ceiling: UI 不消费)."""
+    out: dict = {}
+    # exposure_df / attribution_df / capacity_df → dict (records) 或 None
+    for name in ('exposure_df', 'attribution_df', 'capacity_df',
+                 'metrics_df', 'orders_df', 'cash_curve', 'margin_curve'):
+        v = getattr(akquant_r, name, None)
+        if v is None:
+            continue
+        if callable(v):
+            try:
+                v = v()
+            except Exception:  # noqa: BLE001
+                continue
+        if isinstance(v, pd.DataFrame):
+            try:
+                # 限定大小, 避免 params 膨胀
+                v = v.head(200)
+                out[name] = v.to_dict(orient='records')
+            except Exception:  # noqa: BLE001
+                pass
+        elif isinstance(v, (list, dict)):
+            out[name] = v
+    return out
+
+
+def _monthly_bars(nav_curve: list[dict]) -> list[dict]:
+    """委托 `hamuna_quant_cli.references._metrics_15.monthly_bars` (R-metrics-dedup)."""
+    from ._metrics_15 import monthly_bars as _m15_monthly_bars
+    return _m15_monthly_bars(nav_curve)
+
+
+def _monthly_metrics(nav_curve: list[dict]) -> dict:
+    """委托 `hamuna_quant_cli.references._metrics_15.monthly_metrics` (R-metrics-dedup).
+
+    返回 {YYYY: {MM: ret}} — UI 热力图消费. 旧版本返 nested dict 含 sharpe_partial/trades
+    占位 0 字段, 实际未被 UI 消费, 这里统一走单点 (简化数据形状).
+    """
+    from ._metrics_15 import monthly_metrics as _m15_monthly_metrics
+    return _m15_monthly_metrics(nav_curve)
+
+
+def _selfcheck() -> None:
+    """最小冒烟: 模拟 akquant result → 验 15 metrics key + 13 顶层 key.
+
+    🧪 单元测试用 _MockMetrics/_MockEquityCurve/_MockTradesDF. 显式门控: 仅当
+    `HAMUNA_SELFTEST=1` 时执行, 防止 Agent 误调以为是 prod 数据校验. 调用方式:
+        HAMUNA_SELFTEST=1 python -c "from ...akquant_schema_adapter import _selfcheck; _selfcheck()"
+    """
+    import os
+    if os.environ.get("HAMUNA_SELFTEST") != "1":
+        raise RuntimeError(
+            "_selfcheck() 用 _Mock* 验 schema, 不用于 prod 数据校验. "
+            "设置 HAMUNA_SELFTEST=1 显式启用."
+        )
+    class _MockMetrics:
+        total_return_pct = 5.0
+        annual_return_pct = 12.0
+        sharpe_ratio = 1.2
+        max_drawdown_pct = 8.0
+        win_rate = 0.6
+        final_value = 1_050_000.0
+
+    class _MockEquityCurve:
+        def __init__(self):
+            dates = pd.date_range('2024-01-01', periods=10, freq='D')
+            self._s = pd.Series(
+                [100_000.0 + i * 5_000 for i in range(10)],
+                index=dates,
+            )
+
+        def __call__(self):
+            return self._s
+
+    class _MockTradesDF:
+        def __init__(self):
+            self._df = pd.DataFrame([
+                {'symbol': '600000.SH', 'side': 'buy', 'entry_time': pd.Timestamp('2024-01-02'),
+                 'entry_price': 10.0, 'quantity': 100},
+                {'symbol': '600000.SH', 'side': 'sell', 'entry_time': pd.Timestamp('2024-01-05'),
+                 'entry_price': 11.0, 'quantity': 100},
+            ])
+
+    class _MockResult:
+        metrics = _MockMetrics()
+        trades_df = _MockTradesDF()._df
+        equity_curve = _MockEquityCurve()
+
+    cfg = {
+        'backtest_start': '20240101',
+        'backtest_end': '20240110',
+        'pool': {'a': {'codes': ['600000.SH']}},
+        'init_capital': 100_000.0,
+    }
+    result = to_hamuna_result(_MockResult(), cfg)
+
+    # 15 metrics
+    assert set(result['metrics'].keys()) == HAMUNA_METRICS_15, (
+        f'metrics key 缺/多: {set(result["metrics"].keys()) ^ HAMUNA_METRICS_15}')
+    # 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',
+                    'period', 'params', 'monthly_bars', 'monthly_metrics',
+                    'initial_capital', 'final_capital', 'avg_holding_period', 'suggestions'}
+    assert expected_top.issubset(result.keys()), (
+        f'缺顶层 key: {expected_top - set(result.keys())}')
+    # equity_curve 首日 = init_capital
+    assert result['equity_curve'][0]['date'] == '20240101'
+    assert result['equity_curve'][0]['nav'] == 100_000.0
+    # trades 7 字段
+    assert result['trades'] and set(result['trades'][0].keys()) >= {
+        'date', 'symbol', 'side', 'price', 'qty'}
+    # universe 展开
+    assert result['universe'] == ['600000.SH']
+    # initial_capital / final_capital
+    assert result['initial_capital'] == 100_000.0
+    assert result['final_capital'] == 1_050_000.0
+    print('OK: akquant_schema_adapter 15 metrics + 13 顶层 key + 7 trades fields 全对齐')
+
+
+if __name__ == '__main__':
+    _selfcheck()

hamuna_quant_cli/base_strategy.py

@@ -0,0 +1,80 @@
+"""v2 skill 策略基类 (2026-08-18 简化版, akquant 0.3.x).
+
+背景:
+  v2 skill 不再负责 QMT 格式代码导出。策略直接继承 akquant.Strategy,
+  v2 runner 自动 wire compute_factors / filter_symbols 钩子 (回测侧).
+  实盘接入在 desktop/app/src-tauri/resources/hamuna_strategy.py (独立, 不在本 skill 范畴);
+  akquant 0.3.x `Strategy` 是双引擎一等公民 — 同一份策略代码天然兼容两边,
+  本 skill 主线仍是离线回测.
+
+策略类推荐形态 (0.3.x 内联参数字段 + 钩子):
+    from akquant import Strategy, IntParam
+    import pandas as pd
+
+    class MyStrategy(Strategy):
+        fast = IntParam(5, ge=2, le=200)
+        slow = IntParam(20, ge=3, le=500)
+        universe = ListParam(item_type=str, default=[])
+
+        def on_start(self):
+            for s in self.params.universe:
+                self.subscribe(s)
+
+        def compute_factors(self, df: pd.DataFrame) -> dict[str, pd.DataFrame]:
+            \"\"\"可选 — 向量化预计算因子。引擎加载 df 后调用一次。
+            回测传 prebuilt cache; 实盘传构造的 {sym: df} 字典或拼接 DataFrame (列含 symbol)。
+            \"\"\"
+            return {}
+
+        def filter_symbols(self, factors: dict[str, pd.DataFrame]) -> list[str]:
+            \"\"\"可选 — 基于 factors 过滤最终 universe。df 进入引擎前调用。\"
+\"\"
+            return list(factors.keys())
+
+        def on_bar(self, bar):
+            closes = self.get_history(count=self.params.slow, symbol=bar.symbol, field="close")
+            if len(closes) < self.params.slow:
+                return
+            if closes[-1] > closes[-self.params.fast]:
+                self.buy(bar.symbol, 100)
+
+v2 runner 引擎行为 (回测侧, 实盘见 desktop):
+  1. strat_inst = cls()                                    # 实例化 (走 params 校验)
+  2. hasattr(strat_inst, "compute_factors") → 调一次喂 df (回测: prebuilt DataFrame)
+  3. hasattr(strat_inst, "filter_symbols") → 调一次喂 factors, 限定 universe
+  4. akquant.run_backtest(strategy=strat_cls, data=df_filtered, symbols=filtered, ...)
+
+Ponytail ceiling: compute_factors 在引擎加载 df 后调一次 (startup 一次性)。
+on_bar 内通过 self.get_history (akquant 内置 API) 拿历史, 不再触发 compute_factors — 跟 0.3.x
+get_history 纳秒级快照拷贝契合. 后续若要每 bar 重算因子, 走 register_indicator + on_bar.
+"""
+from __future__ import annotations
+
+import pandas as pd
+
+from akquant import Strategy as _AkquantStrategy
+
+
+class HamunaStrategy(_AkquantStrategy):
+    """v2 skill 推荐基类 (可选 — 用户直接继承 akquant.Strategy 也兼容).
+
+    默认实现 = no-op, 老策略 (无 compute_factors / filter_symbols) 走默认 no-op,
+    直接用 cfg.universe 跑. 引擎通过 hasattr 检测 — 没这俩方法 = 走 fallback.
+    """
+
+    def compute_factors(self, df: pd.DataFrame) -> dict[str, pd.DataFrame]:
+        """向量式预计算因子 (回测 / 实盘启动期各调一次).
+
+        Args:
+            df: 回测 = prebuilt DataFrame (列含 symbol, open, high, low, close, volume);
+                实盘 = bridge_server 拉 N sym 历史拼成的 dict[sym, DataFrame] (或拼接 DataFrame).
+
+        Returns:
+            {sym: DataFrame (含原始 OHLCV + 自定义 factor 列)}.
+            返回 {} = 引擎退到 cfg.universe / --symbols.
+        """
+        return {}
+
+    def filter_symbols(self, factors: dict[str, pd.DataFrame]) -> list[str]:
+        """基于 factors 过滤最终 universe (df 进入回测 / 实盘前调用)."""
+        return list(factors.keys())

hamuna_quant_cli/cross_sectional_helpers.py

@@ -0,0 +1,118 @@
+"""cross-sectional 选股 helper — vol 排序 + 周频日历 (v2 自有版本, B3).
+
+来源: 原仓根 `hamuna_quant_cli/references/cross_sectional_helpers.py`.
+本文件是 wholesale copy, 算法不变. 迁移原因: v2 skill 未来独立分发.
+
+API:
+  compute_vol_calendar(df, lookback=20, rebalance_weekday=4) -> dict[date_str, dict[sym, vol]]
+    输入 df: long format [date, symbol, close, ...]
+    输出: {'20240105': {'600000.SH': 0.012, ...}, '20240112': {...}}
+        - key = 调仓日 (周五, 默认) YYYYMMDD
+        - value = 该日截面所有标的的 realized_vol (rolling N 日 std)
+        - vol 越小越稳 (low-vol 选股用)
+
+注: cross-sectional ranking 在 strategy 端做 (用 akquant 原生 rebalance_to_topn,
+   score = -vol), helper 只算 vol 表 (不挑 top_k, 让 strategy 调 `top_n` 参数即可).
+
+Ponytail: 当前只支持日线 (1d) + close-derived vol. 5m/tick 走 strategy_cli run.
+升级: 加多因子 (momentum / EP) → score 合成.
+"""
+from __future__ import annotations
+
+import pandas as pd
+
+
+def compute_vol_calendar(
+    df: pd.DataFrame,
+    lookback: int = 20,
+    rebalance_weekday: int = 4,  # 0=Mon ... 4=Fri ... 6=Sun
+    min_history: int = 30,
+) -> dict[str, dict[str, float]]:
+    """rolling N 日 vol → 周频调仓日 → {sym: vol}.
+
+    df schema: [date(datetime64), symbol(str), open, high, low, close, volume]
+    返回: 调仓日 (e.g. Friday) 的 {YYYYMMDD: {sym: realized_vol}}
+        realized_vol = past N 日 (含当日) 收益率 std (扣当日 pct_change 后 rolling std)
+    """
+    if df.empty:
+        return {}
+    if 'date' not in df.columns or 'symbol' not in df.columns or 'close' not in df.columns:
+        raise ValueError(f'df 缺必需列 (date/symbol/close), 实际: {list(df.columns)}')
+
+    df = df.copy().sort_values(['symbol', 'date']).reset_index(drop=True)
+    # 日收益率
+    df['ret'] = df.groupby('symbol', sort=False)['close'].pct_change()
+    # rolling N 日 std (扣当日: shift(1) 后 rolling N, 包含 lookback 个过去值)
+    # groupby + rolling 需 reset_index(level=0, drop=True) 把 sym index 降下来
+    df['vol'] = (
+        df.groupby('symbol', sort=False)['ret']
+        .apply(lambda s: s.shift(1).rolling(lookback, min_periods=lookback).std())
+        .reset_index(level=0, drop=True)
+    )
+
+    # 调仓日 (周五默认) 的截面
+    df['d_key'] = df['date'].dt.strftime('%Y%m%d')
+    rebal_mask = df['date'].dt.weekday == rebalance_weekday
+    rebal_dates = df.loc[rebal_mask, 'd_key'].unique()
+
+    calendar: dict[str, dict[str, float]] = {}
+    for d in rebal_dates:
+        today = df[(df['d_key'] == d) & df['vol'].notna() & (df['vol'] > 0)]
+        if len(today) < min_history:  # 至少 N 只票有 vol, 否则跳过 (新股密集周)
+            continue
+        # 用 float vol, jsonable
+        calendar[d] = {row['symbol']: float(row['vol']) for _, row in today.iterrows()}
+    return calendar
+
+
+def _selfcheck() -> None:
+    """mock df: 2 只标的 × 40 日, 期望周五 (假设有) 输出 2 只票的 vol.
+
+    🧪 单元测试用 mock DataFrame. 显式门控: 仅当 `HAMUNA_SELFTEST=1` 时执行,
+    防止 Agent 误调以为是 prod 数据校验. 调用方式:
+        HAMUNA_SELFTEST=1 python -c "from ...cross_sectional_helpers import _selfcheck; _selfcheck()"
+    """
+    import os
+    if os.environ.get("HAMUNA_SELFTEST") != "1":
+        raise RuntimeError(
+            "_selfcheck() 用 mock df 验 vol calendar 算法, 不用于 prod 数据校验. "
+            "设置 HAMUNA_SELFTEST=1 显式启用."
+        )
+    import numpy as np
+    dates = pd.date_range('2024-01-01', periods=60, freq='B')  # 60 营业日才有 rolling(20) std
+    np.random.seed(42)
+    df = pd.DataFrame({
+        'date': np.tile(dates, 2),
+        'symbol': ['600000.SH'] * 60 + ['000001.SZ'] * 60,
+        'open': 10.0, 'high': 10.5, 'low': 9.5,
+        'close': np.concatenate([
+            10 + np.cumsum(np.random.normal(0, 0.01, 60)),
+            10 + np.cumsum(np.random.normal(0, 0.02, 60)),  # 更高 vol
+        ]),
+        'volume': 1000,
+    })
+    cal = compute_vol_calendar(df, lookback=20, rebalance_weekday=4, min_history=2)
+    assert cal, 'calendar 应非空'
+    # 至少一个 rebal day
+    first_d, vols = next(iter(cal.items()))
+    assert '600000.SH' in vols and '000001.SZ' in vols
+    # 000001 波动更大 → vol 应 > 600000 (sanity check)
+    assert vols['000001.SZ'] > vols['600000.SH'], (
+        f'预期 000001 vol > 600000 vol, 实际 {vols}')
+    print(f'OK: compute_vol_calendar ({len(cal)} rebal days, e.g. {first_d}: '
+          f'600000={vols["600000.SH"]:.4f}, 000001={vols["000001.SZ"]:.4f})')
+
+    # 边界: 空 df
+    assert compute_vol_calendar(pd.DataFrame()) == {}
+    print('OK: 空 df → 空 calendar')
+
+    # 边界: 列缺失
+    try:
+        compute_vol_calendar(pd.DataFrame({'a': [1], 'b': [2]}))
+        raise AssertionError('应 raise ValueError')
+    except ValueError:
+        print('OK: 缺列 raise ValueError')
+
+
+if __name__ == '__main__':
+    _selfcheck()

hamuna_quant_cli/live/__init__.py

@@ -0,0 +1,25 @@
+"""hamuna_quant_cli.live — 实盘 CLI (akquant.run_live 薄壳).
+
+子命令: hamuna_quant_cli live run <strategy.py>
+"""
+from .loader import (
+    StrategyLoadError,
+    StrategySpec,
+    load_strategy,
+    FUNCTIONAL_HOOKS,
+)
+from .runner import (
+    LiveRunError,
+    run_live,
+    parse_kv_pairs,
+)
+
+__all__ = [
+    "StrategyLoadError",
+    "StrategySpec",
+    "load_strategy",
+    "FUNCTIONAL_HOOKS",
+    "LiveRunError",
+    "run_live",
+    "parse_kv_pairs",
+]