策略接口文档

三十秒看懂OVERVIEW

写一个策略，只需要做一件事：实现 generate_orders(ctx)，返回一串订单。 引擎在每个交易日收盘后调它一次，你只能看到当日及更早的数据；你返回的订单在下一个交易日撮合。

三个概念，就这么多：

Strategy 基类quant.strategy.base.Strategy

from quant.strategy.base import Context, Strategy

class Strategy(ABC):
    name: str = "strategy"

    def on_start(self, ctx: Context) -> None: ...      # 可选：回测/实盘开始前调用一次

    @abstractmethod
    def generate_orders(self, ctx: Context) -> list[Order]:
        """收盘后调用：基于 <= ctx.date 的数据产出订单，下一交易日撮合。"""

    def on_finish(self, ctx: Context) -> None: ...     # 可选：结束后调用一次

Order 订单quant.core.types.Order

from quant.core.enums import Side
from quant.core.types import Order

Order(code="600519", side=Side.BUY, qty=300, reason="mom_enter")

Context 上下文quant.strategy.base.Context

策略拿到的一切都从 ctx 走。它是只读的：读数据、读持仓、读现金，然后返回订单—— 策略不碰经纪商、不碰下单通道，所以同一份代码回测能跑、实盘也能跑。

数据访问（全部 point-in-time）

资金与持仓

下单辅助

你拿不到未来数据POINT-IN-TIME

这是整套引擎最重要的一条设计，也是我们敢把体检结论摆出来的前提。

策略看到的 ctx.data 不是完整数据集，而是一个被裁剪到当前决策时点的视图 （PointInTimeDataView）。frame / window / dates / codes 全都不含未来；请求一个晚于 ctx.date 的日期会直接抛错，而不是悄悄返回数据：

ValueError: point-in-time 数据越界：请求 2025-06-01，当前时点 2025-05-30

唯一的例外是内置策略的启动期因子预算：on_start 里可以用 ctx.data.frame(code) 拿到「截至当日」的完整历史，一次性算完整条因子序列， 之后在每个交易日用 last_index 按下标取值。这与「每天用截至当天的窗口现算」 逐点等价，只是快得多——内置策略用单元测试锁定了这个等价性（逐窗口等价 + 截断不变性两项）。

完整示例：双均线quant.strategy.examples.SmaCross

这不是伪代码，是仓库里 examples.py 的原文。短均线上穿长均线满仓买入、下穿清仓：

from typing import Optional

from quant.core.enums import Side
from quant.core.types import Order
from quant.strategy.base import Context, Strategy


class SmaCross(Strategy):
    """单只股票日线双均线：短均线上穿长均线满仓买入，下穿清仓卖出。"""

    name = "sma_cross"

    def __init__(self, code: str, fast: int = 5, slow: int = 20,
                 target_pct: float = 0.95) -> None:
        if fast >= slow:
            raise ValueError("fast 必须小于 slow")
        self.code = code
        self.fast = fast
        self.slow = slow
        self.target_pct = target_pct

    def _cross(self, ctx: Context) -> Optional[str]:
        w = ctx.window(self.code, self.slow + 1)          # 截至当日的最后 slow+1 根
        if len(w) < self.slow + 1:
            return None                                 # 预热不足，今天不动
        close = w["close"]
        fast_now  = close.iloc[-self.fast:].mean()
        slow_now  = close.iloc[-self.slow:].mean()
        fast_prev = close.iloc[-self.fast - 1:-1].mean()
        slow_prev = close.iloc[-self.slow - 1:-1].mean()
        if fast_prev <= slow_prev and fast_now > slow_now:
            return "golden"
        if fast_prev >= slow_prev and fast_now < slow_now:
            return "death"
        return None

    def generate_orders(self, ctx: Context) -> list[Order]:
        signal = self._cross(ctx)
        if signal is None:
            return []
        bar = ctx.bar(self.code)
        if bar is None:                                # 当日停牌，买不进也卖不出
            return []
        held = ctx.position_qty(self.code)
        if signal == "golden" and held == 0:
            qty = ctx.lots_affordable(bar.close, cash=ctx.cash * self.target_pct)
            if qty >= ctx.lot_size:                    # 不足一手就别下
                return [Order(self.code, Side.BUY, qty, reason="sma_golden_cross")]
        elif signal == "death":
            sellable = ctx.sellable_qty(self.code)         # T+1：只卖可卖的
            if sellable > 0:
                return [Order(self.code, Side.SELL, sellable, reason="sma_death_cross")]
        return []

横截面策略的骨架

选股类策略（多因子、均值回归、低波动……）都是同一个骨架：先卖后买。 引擎按列表顺序撮合，卖单必须排在买单前面，否则现金不够、买单会被拒：

orders = []
# ① 先卖：已持有但不在今天目标里的
for code in ctx.portfolio.holding_codes():
    if code not in target:
        s = ctx.sellable_qty(code)
        if s > 0:
            orders.append(Order(code, Side.SELL, s, reason="exit"))

# ② 再买：目标里尚未持有的，等权分配
per = ctx.equity() / top_k
for code in target:
    if code in held:
        continue
    b = ctx.bar(code)
    if b is None:
        continue
    qty = ctx.lots_affordable(b.close, cash=per)
    if qty >= ctx.lot_size:
        orders.append(Order(code, Side.BUY, qty, reason="enter"))
return orders

撮合与成本口径MATCHING & COSTS

你返回订单之后发生的事，都由引擎负责，策略无从干预——这也是回测与实盘能共用一份策略的原因。

八个常见错误PITFALLS

1. 用 position_qty 下卖单。当日买入的部分卖不掉，实盘会被券商直接拒单。一律用 sellable_qty。
2. 忘了判 ctx.bar(code) is None。停牌股会让你的价格计算变成 None 参与运算，一路炸到引擎。
3. 买入股数没对齐 100。回测里也许被容忍，实盘一定报错。用 lots_affordable，别自己 int(cash/price)。
4. 买单排在卖单前面。引擎按列表顺序撮合，现金还没回来，买单就被拒了。先卖后买。
5. 用 cash 而不是 equity() 做仓位预算。满仓时现金接近 0，等权分配会算出 0 股，策略从此不动了。
6. NaN 用 0 兜底。因子缺失的票用 0 填充，会在截面排序里排到中间偏上，悄悄进了组合。 正确做法是整只剔除（fail-closed），宁可候选不足今天不动。
7. 在 __init__ 里初始化状态、不在 on_start 里复位。同一个策略实例被喂给第二个引擎时， 会带着上一次回测的残留状态，结果无法复现。
8. 候选不足时重置换仓计时。会导致「今天凑不齐 → 空等一整个换仓周期」。 正确做法是不重置，次日自动重试。

内置策略BUILT-IN

引擎自带 18 个日线策略类（其中 3 个是入门示例）与 2 个日内策略类，全部实现本页这套接口， 源码都可当模板抄。日线与日内是两套基类，日内策略不能喂给日线回测。

边界与规矩SCOPE

• 信号在服务器算，下单在你自己的电脑上执行。易维量化不代客户下单、不托管资金、不碰你的券商密码。
• 不提供投资建议。本页与本站的一切内容是研究工具与客观数据呈现，不构成荐股、目标价或收益承诺。
• 历史回测不代表未来收益。体检通过只说明「这份回测结论在统计上还站得住」，不说明未来会赚钱。
• 第一版策略工厂只开参数化模板（选因子、调参数），暂不开放自由代码上传—— 在沙箱（独立进程、只读文件系统、无网络、资源与时限配额、import 白名单）就绪之前， 在交易服务器上跑客户代码是不可接受的风险。见策略工厂。

接口若有变更，会在易维社区发版本说明； 破坏性变更会保留旧接口至少一个版本周期。