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

hamuna_quant_cli/runtime/cache.py

@@ -0,0 +1,255 @@
+"""strategy_cli.runtime.cache: 本地缓存 (ADR-015 ~/.hamuna/data_cache)。
+
+格式:
+- K 线 (大体积, 频繁): parquet
+- 其他 (基本面/股本/股东/StockCode): JSON
+
+TTL 按 endpoint 粒度; 文件 mtime 超 TTL 视为 miss。
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+# 默认缓存根: ~/.hamuna/data_cache (符合 ADR-015 §303)
+_CACHE_ROOT = Path.home() / '.hamuna' / 'data_cache'
+
+# endpoint 粒度 TTL (秒)
+# K 线 = 准实时 (5min); 财务 = 当日有效 (1d); StockCode = 当日有效 (1d)
+_TTL: dict[str, int] = {
+    'StockBars':     300,        # 5 min
+    'RealTime':      60,         # 1 min
+    'StockHq':       300,
+    'StockFinancial': 86400,     # 1 day
+    'StockAnnualReport': 86400,
+    'StockQuarterlyReport': 86400,
+    'StockShareholder': 86400,
+    'StockShareCapital': 86400,
+    'StockBasicInfo': 86400,
+    'StockBond':     86400,
+    'ETFInfo':       86400,
+    'StockCode':     86400,
+}
+
+_PARQUET_ENDPOINTS = {'StockBars', 'RealTime', 'StockHq'}
+
+
+def cache_dir(endpoint: str) -> Path:
+    p = _CACHE_ROOT / endpoint
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def cache_key(params: dict[str, Any]) -> str:
+    """参数 dict → 稳定 hash (sorted keys, urlencoded-style)."""
+    items = sorted((k, str(v)) for k, v in params.items() if v is not None)
+    raw = '&'.join(f'{k}={v}' for k, v in items)
+    return hashlib.sha256(raw.encode()).hexdigest()[:16]
+
+
+def is_fresh(path: Path, endpoint: str) -> bool:
+    if not path.exists():
+        return False
+    ttl = _TTL.get(endpoint, 3600)
+    return (time.time() - path.stat().st_mtime) < ttl
+
+
+def read(endpoint: str, params: dict[str, Any]) -> dict | list | None:
+    """命中返回解析后 dict/list; miss/过期返回 None。"""
+    key = cache_key(params)
+    if endpoint in _PARQUET_ENDPOINTS:
+        path = cache_dir(endpoint) / f'{key}.parquet'
+        if not is_fresh(path, endpoint):
+            return None
+        return _read_parquet(path)
+    path = cache_dir(endpoint) / f'{key}.json'
+    if not is_fresh(path, endpoint):
+        return None
+    with path.open(encoding='utf-8') as f:
+        return json.load(f)
+
+
+def write(endpoint: str, params: dict[str, Any], data: dict | list) -> None:
+    key = cache_key(params)
+    if endpoint in _PARQUET_ENDPOINTS and isinstance(data, list):
+        path = cache_dir(endpoint) / f'{key}.parquet'
+        _write_parquet(path, data)
+    else:
+        path = cache_dir(endpoint) / f'{key}.json'
+        path.write_text(json.dumps(data, ensure_ascii=False, indent=2),
+                        encoding='utf-8')
+
+
+def clear(endpoint: str | None = None) -> int:
+    """清除缓存; endpoint=None 清除全部。返回删除文件数。"""
+    n = 0
+    targets = [_CACHE_ROOT / endpoint] if endpoint else [_CACHE_ROOT]
+    for d in targets:
+        if not d.exists():
+            continue
+        for p in d.glob('**/*'):
+            if p.is_file():
+                p.unlink()
+                n += 1
+    return n
+
+
+# ---- 回测数据集 (无 TTL, 历史数据不变) ----
+
+# 数据集根: ~/.hamuna/data_cache/datasets/<code>_<DateType>_fq<FuQuanType>.parquet
+# 与 5min 缓存 (StockBars/<hash>.parquet) 分开 — 数据集是"回测专用完整历史",
+# 不随单次请求 TTL 过期。key 只含 (code, DateType, FuQuanType), 窗口内切片由读取方做。
+_DATASET_DIR = _CACHE_ROOT / 'datasets'
+
+# 回测数据集最小 bar 数 — 用户规约 "至少 3 年 1000 根"。A 股年约 240 交易日,
+# 3 年 ≈ 750 根, 到不了 1000; 故以 1000 根为硬门槛 (约 4.1 年), 自然覆盖 3 年。
+# 转债例外: 历史天然短 (2017 后起量, 多数上市 1-2 年), 硬套 1000 根会让几乎
+# 全部转债每次回测都重建数据集 (慢到不可用)。转债用 240 根 (约 1 年)。
+DATASET_MIN_BARS = 1000
+DATASET_MIN_BARS_CB = 240
+
+# 短样本数据集 TTL (秒): 次新股/新转债历史天然不足 DATASET_MIN_BARS, 若"不足即 miss"
+# 会导致每次回测都重建 (实测 889 只转债里 296 只 <240 根, 反复重建 ~74s)。
+# 构建过一次就临时复用, TTL 到期重建以拉取新累积的历史 — 短样本数据在上市初期
+# 会变长, 不能像达标样本那样无 TTL 永久复用。
+DATASET_SHORT_TTL = 7 * 86400  # 7 天
+
+
+def _is_convertible(stock_code: str) -> bool:
+    bare = stock_code.split('.')[0]
+    return bare.startswith(('11', '12'))
+
+
+def _min_bars(stock_code: str, date_type: str = 'D') -> int:
+    """按品种+周期取最小 bar 门槛。
+
+    分钟 (DateType M*) 不走根数门槛 — 分钟 dataset 构建目标 = 回测窗口本身,
+    存在即用, 窗口切片由调用方做。日线才用根数门槛 (保证"至少3年/1年"样本)。
+    """
+    if date_type.startswith('M'):
+        return 1
+    if _is_convertible(stock_code):
+        return DATASET_MIN_BARS_CB
+    return DATASET_MIN_BARS
+
+
+def _dataset_path(stock_code: str, date_type: str, fu_quan_type: int) -> Path:
+    """code 含后缀 → 剥 (dataset 内部统一裸 6 位, 与容维一致)。"""
+    bare = stock_code.split('.')[0]
+    return _DATASET_DIR / f'{bare}_{date_type}_fq{fu_quan_type}.parquet'
+
+
+def bundle_path(universe_code: str, date_type: str = 'D') -> Path:
+    """server 内置数据集整包落盘缓存 (无 TTL, 历史不变)。
+
+    布局: <data_cache>/datasets/__bundle__<universe>_<DateType>.parquet
+    与单股 dataset (裸 6 位前缀) 区分 — __bundle__ 前缀不会撞股票代码。
+    整包下载一次, 同进程内多只股票从同一份抽取, 不重复下载/解析。
+    """
+    return _DATASET_DIR / f'__bundle__{universe_code}_{date_type}.parquet'
+
+
+def read_dataset(stock_code: str, date_type: str, fu_quan_type: int,
+                 start: str, end: str) -> list[dict] | None:
+    """读取数据集切片。数据集根数足够 → 返升序窗口切片;否则 None (视为 miss, 重建)。
+
+    "存在"判定只看数据集根数 >= DATASET_MIN_BARS。切片过滤后为空 (如 start/end
+    恰为非交易日) 是正常结果, 不代表数据集缺失 — 若把空切片当 miss, 回测逐 bar
+    调非交易日窗口会反复触发重建 (每次卡几秒网络)。
+
+    无 TTL — 历史 K 线不变。性能: 全量 parquet 用 lru_cache 进程内缓存,
+    切片在内存做 — 回测逐 bar 请求不再反复读盘/pyarrow 加载。
+    """
+    path = _dataset_path(stock_code, date_type, fu_quan_type)
+    if not path.exists():
+        return None
+    rows = list(_read_dataset_full(stock_code, date_type, fu_quan_type))
+    if len(rows) < _min_bars(stock_code, date_type):
+        # 短样本 (次新股/新转债历史不足) 不立即重建: 用 TTL 临时复用,
+        # 避免每次回测都重新翻页构建 (296 只转债反复重建 ~74s)。到期重建拉新历史。
+        if _is_convertible(stock_code) and time.time() - path.stat().st_mtime < DATASET_SHORT_TTL:
+            pass  # 临时复用短样本
+        else:
+            return None
+    if start:
+        # 日线 bar 有 date (YYYYMMDD); 分钟 bar 有 datetime (YYYYMMDDHHMM), 切片按前 8 位
+        date_of = lambda r: r.get('date') or r.get('datetime', '')[:8]  # noqa: E731
+        # 覆盖检查: 缓存最末日期 < 请求 start → 缓存陈旧 (e.g. 之前构建时只拉到旧数据,
+        # 后来回测窗口更新), 视为 miss 重建。次新/停更标的例外: 上游日线已到尽头
+        # (历史只到某日后停更, e.g. 转债摘牌/退市), 构建拉到最早一根后上游无更多数据,
+        # last < start 是正常结果, 每次重建只会拉到同样的旧数据 — 若不放行会死循环重建。
+        if _dataset_is_complete(stock_code, date_type, fu_quan_type, rows):
+            pass  # 已拉满上游 (最早根就是 dataset 首根) → 放行, 不再重建
+        else:
+            last = date_of(rows[-1])
+            if last < start:
+                return None
+        rows = [r for r in rows if start <= date_of(r) <= end]
+    return rows  # 可为空 list (非交易日切片); 调用方不应据此重建
+
+
+# 上游已拉满标记: dataset 构建拉到最早一根 (次新/停更标的) 时写一个侧车文件。
+# 若无此标记, 覆盖检查对这类标的永远 last < start → 死循环重建 (实测 128044 8x)。
+_COMPLETE_SUFFIX = '.complete'
+
+
+def _complete_path(stock_code: str, date_type: str, fu_quan_type: int) -> Path:
+    return Path(str(_dataset_path(stock_code, date_type, fu_quan_type)) + _COMPLETE_SUFFIX)
+
+
+def _dataset_is_complete(stock_code: str, date_type: str, fu_quan_type: int,
+                         rows: list[dict]) -> bool:
+    """数据集是否已拉满上游 (构建时翻页无更早数据即视为完整)。
+
+    无 complete 标记 → False (回落旧覆盖检查)。标记由 build_bars_dataset 在
+    翻页 `not fresh: break` (上游无更早数据) 时写入。
+    """
+    if not rows:
+        return False
+    return _complete_path(stock_code, date_type, fu_quan_type).exists()
+
+
+from functools import lru_cache  # noqa: E402  (import 放函数后, 保持文件顶部简洁)
+
+
+@lru_cache(maxsize=64)
+def _read_dataset_full(stock_code: str, date_type: str, fu_quan_type: int) -> tuple:
+    """读全量数据集 parquet → tuple (可 hash, 供 lru_cache)。调用方转回 list。"""
+    path = _dataset_path(stock_code, date_type, fu_quan_type)
+    rows = _read_parquet(path)
+    return tuple(rows)
+
+
+def write_dataset(stock_code: str, date_type: str, fu_quan_type: int,
+                  rows: list[dict]) -> None:
+    """写入/覆盖数据集 (升序 bars)。"""
+    _DATASET_DIR.mkdir(parents=True, exist_ok=True)
+    path = _dataset_path(stock_code, date_type, fu_quan_type)
+    _write_parquet(path, rows)
+
+
+# ---- parquet (依赖 pyarrow/pandas, 可选) ----
+
+def _read_parquet(path: Path) -> list[dict]:
+    try:
+        import pandas as pd
+    except ImportError:
+        return []
+    if not path.exists() or path.stat().st_size == 0:
+        # 0 字节/不存在 → 损坏或半截写入 (build 中断/磁盘满) → 当 miss, 调用方重建。
+        # 若让 pd.read_parquet 抛 ArrowInvalid, 回测逐 bar 读同一文件会硬崩 (实测 001358)。
+        return []
+    return pd.read_parquet(path).to_dict(orient='records')
+
+
+def _write_parquet(path: Path, data: list[dict]) -> None:
+    try:
+        import pandas as pd
+    except ImportError:
+        path.write_text(json.dumps(data, ensure_ascii=False, indent=2),
+                        encoding='utf-8')
+        return
+    pd.DataFrame(data).to_parquet(path)

hamuna_quant_cli/runtime/discipline.py

@@ -0,0 +1,359 @@
+"""strategy_cli.discipline (v2) — akquant API 静态审查.
+
+v1 discipline.py 检查 QMT-style (passorder / handlebar / m_strRemark / quickTrade / is_last_bar / init+ContextInfo 形参).
+v2 改检查 akquant 0.3.x 风格, 共 8 条 rule:
+  - 必继承 akquant.Strategy 或 (Strategy) 或 (HamunaStrategy) — HamunaStrategy 是 v2 推荐基类
+    (自身继承 akquant.Strategy, 默认 no-op compute_factors/filter_symbols, 见 base_strategy.py)
+  - 文件编码 # coding: utf-8 (v1 走 QMT 的 GBK, v2 走 UTF-8)
+  - 无 QMT globals (passorder / set_basket / get_basket / m_strRemark / quickTrade /
+    is_last_bar / subscribe_quote / run_time / after_init / XtQuantTrader / xttrader / xtdata / ContextInfo)
+  - 不混 def handlebar(...) (QMT 形态) — v2 走 akquant def on_bar(self, bar: Bar)
+  - 不混 def init(ContextInfo) (QMT 形态) — v2 走 akquant def __init__(self)
+  - bar.<field> 不取 bar.time / bar.date (akquant 0.3.x REPR ALIAS, getattr 返 None;
+    真实字段是 bar.timestamp, int ns) — 实战踩过的 bug
+  - Round 1 (0.3.x 加速原语): 同 (count, sym) 多次 get_history 不同字段应合并 get_history_multi
+  - Round 1 (0.3.x 强制): __init__ 形参含 universe 走老注入风格应改 ListParam 内联字段
+
+调用方: __main__.py cmd_run 在 backtest.run 之前 source = strategy.py.read_text()
+        然后 check_discipline(source, cfg) → 若 list 非空, abort 退出码 3.
+"""
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+
+
+@dataclass
+class DisciplineError:
+    rule: str            # 短代码 (e.g. "bar_field_alias_trap")
+    line: int            # 触发处行号 (1-indexed)
+    msg: str             # 人读错误信息
+
+    def __str__(self) -> str:
+        return f'ERROR: rule={self.rule} line={self.line} {self.msg}'
+
+
+# QMT 残留标识符 (出现即报 — v2 走 akquant, 任何 QMT-specific 调用都该走 v1)
+_QMT_GLOBALS: dict[str, str] = {
+    'passorder':              'QMT 报单函数 (akquant 用 self.buy / self.sell)',
+    'set_basket':             'QMT 组合函数 (akquant 用 self 内部状态)',
+    'get_basket':             'QMT 组合函数 (akquant 用 self.get_position)',
+    'm_strRemark':            'QMT 订单字段 (akquant 不支持, 改 remark=...)',
+    'quickTrade':             'QMT subscribe_quote 参数 (akquant on_bar 自动)',
+    'is_last_bar':            'QMT handlebar gate (akquant daily 全是 last-bar)',
+    'subscribe_quote':        'QMT tick 订阅 (akquant 0.3.x on_bar 一次性)',
+    'run_time':               'QMT 定时器 (akquant enable_timer 但 API 不同)',
+    'after_init':             'QMT 初始化回调 (akquant 用 on_start / __init__ 子类)',
+    'XtQuantTrader':          'QMT native API class (v2 不引入)',
+    'XtQuantTraderCallback':  'QMT native API callback',
+    'xttrader':               'QMT native API module',
+    'xtdata':                 'QMT native API module',
+    'ContextInfo':            'QMT 编辑器形参 (akquant 用 self + bar)',
+}
+
+
+# ---- Rule 1: 文件编码 UTF-8 ------
+def _rule_coding_utf8(source: str) -> list[DisciplineError]:
+    """检测文件顶部是否有 # coding: gbk / cp936 — v2 走 akquant, UTF-8 是契约."""
+    errs: list[DisciplineError] = []
+    for i, line in enumerate(source.splitlines()[:3], 1):
+        stripped = line.strip().lower()
+        if not (stripped.startswith('# -*- coding:') or stripped.startswith('# coding:')):
+            continue
+        if stripped.startswith('# -*- coding:'):
+            enc = stripped.split(':', 1)[1].strip().rstrip(' -*-').strip()
+        else:
+            enc = stripped.split(':', 1)[1].strip()
+        if enc not in ('utf-8', 'utf8'):
+            errs.append(DisciplineError(
+                rule='coding_not_utf8',
+                line=i,
+                msg=f'文件编码 = {enc!r}; v2 走 akquant, UTF-8 是契约 (QMT 旧 GBK 策略需先转码)',
+            ))
+        return errs
+    return errs
+
+
+# ---- Rule 2: 必继承 akquant.Strategy / HamunaStrategy ------
+def _rule_akquant_strategy_subclass(tree: ast.Module) -> list[DisciplineError]:
+    """必须有一个 class Foo(akquant.Strategy) / class Foo(Strategy) /
+    class Foo(HamunaStrategy) (后者从 strategy_cli.references.base_strategy 导入,
+    HamunaStrategy 自身继承 akquant.Strategy, v2 skill 推荐基类)."""
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.ClassDef):
+            continue
+        for base in node.bases:
+            bname = None
+            if isinstance(base, ast.Attribute):
+                bname = base.attr
+            elif isinstance(base, ast.Name):
+                bname = base.id
+            if bname in ('Strategy', 'HamunaStrategy'):
+                return []
+    return [DisciplineError(
+        rule='missing_akquant_strategy_subclass',
+        line=1,
+        msg='未找到 `class Xxx(akquant.Strategy)` / `class Xxx(Strategy)` / '
+            '`class Xxx(HamunaStrategy)` 子类; v2 策略必须继承 akquant.Strategy 或 HamunaStrategy',
+    )]
+
+
+# ---- Rule 3: 无 QMT globals ------
+def _rule_no_qmt_globals(tree: ast.Module) -> list[DisciplineError]:
+    """扫描所有 Name / Attribute / Import, 命中 QMT 标识符即报."""
+    errs: list[DisciplineError] = []
+    seen: set[str] = set()  # 防同一标识符多行刷屏
+
+    def _check(ident: str, line: int) -> None:
+        if ident in _QMT_GLOBALS and ident not in seen:
+            seen.add(ident)
+            errs.append(DisciplineError(
+                rule='qmt_global_leaked',
+                line=line,
+                msg=f'QMT 标识符 {ident!r}: {_QMT_GLOBALS[ident]}',
+            ))
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name):
+            _check(node.id, node.lineno)
+        elif isinstance(node, ast.Attribute):
+            _check(node.attr, node.lineno)
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                _check(alias.name.split('.')[0], node.lineno)
+        elif isinstance(node, ast.ImportFrom):
+            if node.module:
+                _check(node.module.split('.')[0], node.lineno)
+            for alias in node.names:
+                _check(alias.name, node.lineno)
+    return errs
+
+
+# ---- Rule 4: 不混 def handlebar(...) (QMT 形态) ------
+def _rule_no_handlebar(tree: ast.Module) -> list[DisciplineError]:
+    """v2 走 akquant on_bar(bar); def handlebar(...) 是 QMT 形态, 报错."""
+    errs: list[DisciplineError] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.FunctionDef):
+            continue
+        if node.name == 'handlebar':
+            errs.append(DisciplineError(
+                rule='handlebar_not_akquant',
+                line=node.lineno,
+                msg='def handlebar(...) 是 QMT 形态; v2 走 akquant, 用 def on_bar(self, bar: Bar): ...',
+            ))
+    return errs
+
+
+# ---- Rule 5: 不混 def init(ContextInfo) ------
+def _rule_no_init_contextinfo(tree: ast.Module) -> list[DisciplineError]:
+    """QMT 形态 init(ContextInfo) vs akquant 形态 __init__(self) — 不混用."""
+    errs: list[DisciplineError] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.FunctionDef):
+            continue
+        if node.name != 'init':
+            continue
+        if not node.args.args:
+            continue
+        first = node.args.args[0].arg
+        if first == 'ContextInfo':
+            errs.append(DisciplineError(
+                rule='init_contextinfo_form',
+                line=node.lineno,
+                msg='def init(ContextInfo) 是 QMT 形态; v2 走 akquant, '
+                    '用 __init__(self) + self.subscribe + warmup_period',
+            ))
+    return errs
+
+
+# ---- Rule 6: bar.time / bar.date 是 akquant 0.3.x REPR ALIAS (实战踩过) ------
+def _rule_bar_field_uses_timestamp(tree: ast.Module) -> list[DisciplineError]:
+    """akquant 0.3.x Bar 字段名陷阱: bar.time / bar.date 是 REPR ALIAS, getattr 返 None.
+    检 on_bar 体内 bar.<field> 访问, 不允许 bar.time / bar.date 取日期.
+    真实字段是 bar.timestamp (int ns), 自定义 date 字段若存在也被拦 — 避免混用.
+    """
+    errs: list[DisciplineError] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if node.name != 'on_bar':
+            continue
+        for child in ast.walk(node):
+            if not isinstance(child, ast.Attribute):
+                continue
+            if not isinstance(child.value, ast.Name):
+                continue
+            if child.value.id == 'bar' and child.attr in ('time', 'date'):
+                errs.append(DisciplineError(
+                    rule='bar_field_alias_trap',
+                    line=child.lineno,
+                    msg=f'bar.{child.attr} 是 akquant 0.3.x REPR ALIAS, getattr 返 None — '
+                        f'用 bar.timestamp (int ns) 转 datetime.fromtimestamp(ts/1e9).date()',
+                ))
+    return errs
+
+
+
+
+# ---- Rule 7 (Round 1): 0.3.x 起 get_history 多次应改 get_history_multi -----
+def _rule_get_history_batched(tree: ast.Module) -> list[DisciplineError]:
+    """akquant 0.3.x 提供 `self.get_history_multi(count, sym, fields=...)`, 一次 FFI 拉多字段.
+
+    检 on_bar / on_timer 体内 self.get_history(...) 调用, 同一 (sym, count) 出现 >= 2 个
+    不同 field → 报建议合并为 get_history_multi. 单字段 / 多 sym 是正常的, 不报.
+
+    ponytail: 启发式, 只看字面 call, 不追变量 (e.g. sym = bar.symbol; c1 = self.get_history(n, sym, "close")
+    + c2 = self.get_history(n, sym, "volume") -> 报). 实测 false-positive 极低 (罕有人写多 sym 但同 (n,sym,field)).
+    """
+    errs: list[DisciplineError] = []
+    target_funcs = {"on_bar", "on_timer", "on_cross_section"}
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if node.name not in target_funcs:
+            continue
+        # 收集 (count, sym) -> {field}
+        calls: dict[tuple, set] = {}
+        for child in ast.walk(node):
+            if not isinstance(child, ast.Call):
+                continue
+            func = child.func
+            if not (isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name)):
+                continue
+            if func.value.id != "self" or func.attr != "get_history":
+                continue
+            args = child.args
+            if len(args) < 3:
+                continue
+            count_key = ast.dump(args[0])
+            sym_key = ast.dump(args[1])
+            field_key = ast.dump(args[2])
+            k = (count_key, sym_key)
+            calls.setdefault(k, set()).add(field_key)
+        for (_ck, _sk), fields in calls.items():
+            if len(fields) >= 2:
+                errs.append(DisciplineError(
+                    rule="get_history_not_batched",
+                    line=node.lineno,
+                    msg=(f"{node.name} 体内同一 (count, sym) 多次 self.get_history(... field=...) "
+                          f"(字段数 {len(fields)}); akquant 0.3.x 提供 self.get_history_multi(count, sym, "
+                          f"fields=('close', 'volume', ...)) 一次 FFI 拉多字段 - 跨 sym N 调用时省 "
+                          f"50~80% FFI 跨越"),
+                ))
+    return errs
+
+
+# ---- Rule 8 (Round 1): 0.3.x 起 universe 必须走 ParamModel 风格 -----
+def _rule_universe_param_style(tree: ast.Module) -> list[DisciplineError]:
+    """akquant 0.3.x 弃用 `__init__(self, universe=None)` 注入风格, 必须用:
+
+        class S(Strategy):
+            universe: list = ListParam(default=[])
+
+    检策略类的 __init__ 是否收 `universe` 形参; 若收 -> 报迁移提示 (0.3 strict 拒收).
+
+    ponytail: 仅警告 (severity=warn), 不强制 abort - 因为 0.3 也允许 0.2 老写法
+    (engine 调 __init__ 时 TypeError + warning 不会 fail backtest); 但 runner 检测
+    不到 universe 字段, 不会注入 -> 静默 0 trades. 显式报让用户立即感知.
+    """
+    errs: list[DisciplineError] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.ClassDef):
+            continue
+        is_strat = False
+        for base in node.bases:
+            base_str = ast.unparse(base) if hasattr(ast, "unparse") else ""
+            if "Strategy" in base_str:
+                is_strat = True
+                break
+        if not is_strat:
+            continue
+        for child in node.body:
+            if isinstance(child, ast.FunctionDef) and child.name == "__init__":
+                for arg in child.args.args:
+                    if arg.arg == "universe":
+                        errs.append(DisciplineError(
+                            rule="universe_init_style_deprecated",
+                            line=child.lineno,
+                            msg=(f"{node.name}.__init__ 形参含 `universe` - akquant 0.3.x 严格拒收 "
+                                 f"老风格 (TypeError); 改 `universe: list = ListParam(default=[])` "
+                                 f"类字段, 读 `self.params.universe`, runner 自动注入"),
+                        ))
+                        break
+    return errs
+
+# ---- 聚合入口 ------
+def check_discipline(source: str, config: dict) -> list[DisciplineError]:
+    """返 0~N 条 DisciplineError; 空 list = 通过. cmd_run 在 backtest.run 之前调."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as e:
+        return [DisciplineError(
+            rule='syntax_error',
+            line=e.lineno or 1,
+            msg=f'parse failed: {e.msg}',
+        )]
+
+    errs: list[DisciplineError] = []
+    errs += _rule_coding_utf8(source)
+    errs += _rule_akquant_strategy_subclass(tree)
+    errs += _rule_no_qmt_globals(tree)
+    errs += _rule_no_handlebar(tree)
+    errs += _rule_no_init_contextinfo(tree)
+    errs += _rule_bar_field_uses_timestamp(tree)
+    errs += _rule_get_history_batched(tree)
+    errs += _rule_universe_param_style(tree)
+    return errs
+
+
+def _selfcheck() -> None:
+    """v2 discipline._selfcheck: 跑一份合规 + 一份违规, 4 个 buy-and-hold 策略.
+
+    合规: class BuyHold(Strategy): on_bar(self, bar): self.buy(bar.symbol, 100)
+    违规: def handlebar(bar): passorder(...)  → 报 qmt_global_leaked + handlebar_not_akquant
+    """
+    good = '''
+from akquant import Strategy
+
+class BuyHold(Strategy):
+    warmup_period = 1
+    def on_bar(self, bar):
+        if self.get_position(bar.symbol) == 0:
+            self.buy(bar.symbol, 100)
+'''
+    errs = check_discipline(good, {})
+    assert not errs, f'合规策略不应被拦: {errs}'
+    print(f'OK: 合规策略 0 违规')
+
+    bad = '''# coding: gbk
+def init(ContextInfo):
+    pass
+
+def handlebar(ContextInfo):
+    passorder(23, 1101, '600000.SH', 0, 0, 100, 0, '', 'remark')
+    quickTrade = 2
+'''
+    errs = check_discipline(bad, {})
+    rules = {e.rule for e in errs}
+    assert 'coding_not_utf8' in rules, f'应拦 GBK: {errs}'
+    assert 'qmt_global_leaked' in rules, f'应拦 QMT globals: {errs}'
+    assert 'init_contextinfo_form' in rules, f'应拦 init(ContextInfo): {errs}'
+    assert 'handlebar_not_akquant' in rules, f'应拦 handlebar: {errs}'
+    assert 'missing_akquant_strategy_subclass' in rules, f'应拦无 Strategy: {errs}'
+    print(f'OK: 违规策略拦 {len(errs)} 条 (rules={sorted(rules)})')
+
+    # bar.time 陷阱
+    bad_time = '''
+from akquant import Strategy
+class MyStrat(Strategy):
+    def on_bar(self, bar):
+        d = bar.time   # 实际 attr 是 timestamp
+'''
+    errs = check_discipline(bad_time, {})
+    assert any(e.rule == 'bar_field_alias_trap' for e in errs), f'应拦 bar.time: {errs}'
+    print(f'OK: bar.time 陷阱拦住')
+
+
+if __name__ == '__main__':
+    _selfcheck()