# QuantDinger Python v3 策略开发指南

这份指南不是单纯罗列接口，而是站在**策略开发者**视角，回答一个更实际的问题：

**到底应该怎么写一个结构清晰、能回测、能落地成平台策略的指标策略？**

QuantDinger 当前支持两条 Python 开发路径：

- **IndicatorStrategy**：基于 `df` 的指标/信号脚本，用于 Indicator IDE、图表渲染和信号型回测。
- **ScriptStrategy**：基于 `on_init / on_bar` 的事件驱动脚本，用于策略运行时、策略回测与实盘执行。

如果你要从零开始开发一个策略，默认建议是：

1. 先用 `IndicatorStrategy` 把信号逻辑跑通。
2. 先验证图表、信号和回测语义。
3. 只有当你需要运行时状态、动态仓位管理或执行控制时，再升级为 `ScriptStrategy`。

---

## 1. 先建立正确心智模型

很多开发者会把**信号逻辑**、**止盈止损**、**仓位管理**、**执行逻辑**混在一起写，结果文档看不懂、代码也不好维护。

### 1.1 IndicatorStrategy 是什么

可以把 `IndicatorStrategy` 理解成：

- 基于 `df` 计算指标序列
- 生成布尔型 `buy` / `sell` 信号
- 通过元数据声明默认策略配置
- 返回 `output` 供图表展示

它最适合：

- 指标研究
- 策略原型验证
- 参数调优
- 信号型回测
- 先做信号、后保存成平台策略的工作流

### 1.2 ScriptStrategy 是什么

可以把 `ScriptStrategy` 理解成：

- 按 bar 逐根执行的运行时逻辑
- 通过 `ctx.position` 读取当前持仓状态
- 用 `ctx.buy()`、`ctx.sell()`、`ctx.close_position()` 发出动作
- 把退出、仓位、执行节奏写进代码

它最适合：

- 有状态的执行逻辑
- 动态止盈止损
- 分批加仓、减仓、部分止盈
- 冷却期、重入限制、bot 型执行策略

### 1.3 最重要的分层

对于 `IndicatorStrategy`，请强制把逻辑拆成三层：

1. **指标层**：均线、RSI、ATR、布林带、过滤条件。
2. **信号层**：`df['buy']` 和 `df['sell']`。
3. **风险默认配置层**：`# @strategy stopLossPct ...`、`takeProfitPct`、`entryPct` 等。

不要把这三层混成一团。

尤其要明确：

- `buy` / `sell` 负责表达**什么时候进出场**
- `# @strategy` 负责表达**引擎默认如何控风险、如何设仓位**
- 杠杆属于产品配置，不属于指标脚本

---

## 2. 应该选哪种模式？

| 使用场景 | 推荐模式 |
|----------|----------|
| 写指标、叠加图表、画买卖点 | `IndicatorStrategy` |
| 研究 dataframe 上的进出场信号 | `IndicatorStrategy` |
| 只想给策略补固定止损、止盈、仓位默认值 | `IndicatorStrategy` |
| 需要逐根读取持仓状态做判断 | `ScriptStrategy` |
| 止损止盈依赖当前持仓状态动态变化 | `ScriptStrategy` |
| 需要分批开平仓、状态机、bot 风格执行 | `ScriptStrategy` |

一个简单判断方法：

- 如果你的逻辑可以表述成“条件 A 出现就买，条件 B 出现就卖”，先用 `IndicatorStrategy`
- 如果你的逻辑更像“开仓后要持续盯着当前持仓，并根据状态做不同反应”，那就应该用 `ScriptStrategy`

---

## 3. 如何开发一个 IndicatorStrategy

这是大多数新策略最推荐的开发路径。

### 3.1 第一步：先把元数据和默认配置写清楚

脚本开头先定义名称、描述、可调参数、默认策略配置。

```python
my_indicator_name = "Trend Pullback Strategy"
my_indicator_description = "Buy pullbacks in an uptrend and exit on weakness."

# @param fast_len int 20 Fast EMA length
# @param slow_len int 50 Slow EMA length
# @param rsi_len int 14 RSI length
# @param rsi_floor float 45 Minimum RSI for long entries

# @strategy stopLossPct 0.03
# @strategy takeProfitPct 0.06
# @strategy entryPct 0.25
# @strategy trailingEnabled true
# @strategy trailingStopPct 0.02
# @strategy trailingActivationPct 0.04
# @strategy tradeDirection long
```

`# @param` 用来定义用户经常调的参数。

格式如下：

```python
# @param <name> <int|float|bool|str|string> <default> <描述>
```

最佳实践：

- 声明后的参数，应该通过 `params.get(...)` 读取
- `string` 与 `str` 等价
- 如果声明了参数，却仍然把值硬编码在正文里，平台内置的代码质量检查会给出提醒

`# @strategy` 用来定义策略默认配置，比如：

- `stopLossPct`：止损比例，例如 `0.03` 表示 3%
- `takeProfitPct`：止盈比例，例如 `0.06` 表示 6%
- `entryPct`：开仓资金占比
- `trailingEnabled`
- `trailingStopPct`
- `trailingActivationPct`
- `tradeDirection`：`long`、`short` 或 `both`

这里有个非常关键的边界：

- 这些是**引擎读取的默认配置**
- 不是让你再去 dataframe 里造一列 `stop_loss`
- 不要在这里写 `leverage`
- 数值尽量保持合理，并结合回测验证；底层解析器允许的范围会比示例更宽松

### 3.2 第二步：复制 dataframe，再算指标

Indicator 代码运行在沙盒里，`pd`、`np` 和 `params` 字典已预置。

推荐开头固定写：

```python
df = df.copy()
```

通常可用列包括：

- `open`
- `high`
- `low`
- `close`
- `volume`

`time` 列可能存在，但不要假设其类型永远一致。

避免这些写法：

- 网络请求
- 文件读写
- 子进程
- `eval`、`exec`、`open`、`__import__` 这类破坏沙盒边界的模式

### 3.3 第三步：把原始条件变成干净的 `buy` / `sell`

回测引擎读取的是两列**布尔信号**：

- `df['buy']`
- `df['sell']`

它们应满足：

- 与 dataframe 长度完全一致
- `fillna(False)` 后为布尔值
- 除非你明确要连续触发，否则应尽量做成边缘触发

推荐模式：

```python
raw_buy = (ema_fast > ema_slow) & (ema_fast.shift(1) <= ema_slow.shift(1))
raw_sell = (ema_fast < ema_slow) & (ema_fast.shift(1) >= ema_slow.shift(1))

df['buy'] = (raw_buy.fillna(False) & (~raw_buy.shift(1).fillna(False))).astype(bool)
df['sell'] = (raw_sell.fillna(False) & (~raw_sell.shift(1).fillna(False))).astype(bool)
```

这样可以避免同一段趋势里每根 bar 都重复发信号。

### 3.4 第四步：先决定“谁负责退出”

止盈止损和仓位管理最容易在这里写乱。

在 `IndicatorStrategy` 里，退出逻辑通常有两种合法写法。

#### 写法 A：信号自己负责退出

也就是由你的指标逻辑直接生成 `df['sell']`。

典型例子：

- 均线死叉
- RSI 跌破阈值
- 收盘价跌破 ATR 止损线
- 均值回归到目标位后离场

如果退出本身就是策略思想的一部分，用这种写法最自然。

#### 写法 B：引擎负责固定止盈止损

也就是你只定义默认配置，由引擎按固定规则处理：

- `stopLossPct`
- `takeProfitPct`
- `entryPct`
- trailing 系列参数

如果你的信号逻辑想保持简洁，而保护性规则是固定的，就用这种写法。

#### 最佳实践

尽量明确一个“主退出来源”。

例如：

- 如果你的核心逻辑是“金叉进，死叉出”，那退出就主要由 `sell` 信号负责
- 如果你的逻辑是“信号进场，固定 3% 止损 + 6% 止盈管理交易”，那退出主要由 `# @strategy` 负责

两者可以同时存在，但一定要在注释或描述里写清楚，否则别的开发者不知道到底是**信号退出**还是**引擎退出**在起主要作用。

### 3.5 第五步：最后再组装 `output`

脚本最后必须赋值 `output`：

```python
output = {
    "name": "My Strategy",
    "plots": [],
    "signals": []
}
```

主要支持键：

- `name`
- `plots`
- `signals`
- `calculatedVars`：可选元数据

每个 `plot` 项通常包含：

- `name`
- `data`，长度必须等于 `len(df)`
- `color`
- `overlay`
- 可选 `type`

每个 `signal` 项通常包含：

- `type`：`buy` 或 `sell`
- `text`
- `color`
- `data`：无信号的 bar 用 `None`

### 3.6 第六步：校验回测语义

指标回测是典型的信号驱动：

- 引擎读取 `df['buy']` 和 `df['sell']`
- 信号按 bar close 确认
- 通常在**下一根 bar 开盘价**成交

这件事非常重要，因为：

- 你在当前 K 线上画出来的“止损线”不等于系统一定按这根 K 线内部价格成交
- 一旦用了 `shift(-1)`，就基本等于引入未来函数

还要注意一个实现细节：

- 标准工作流下，最常见的成交语义仍然是“收盘确认、下一根开盘成交”
- 但保存后的策略快照，会根据产品配置被规范成 `next_bar_open` 或 `same_bar_close`
- 如果你改了成交时机配置，不要凭印象判断结果，要重新回测并核对成交明细

---

## 4. 止盈止损和仓位管理到底怎么写

这一节就是给开发者的直接答案。

### 4.1 在 IndicatorStrategy 里写固定止损、止盈、仓位

如果你想要的是固定默认配置，就写成 `# @strategy`：

```python
# @strategy stopLossPct 0.03
# @strategy takeProfitPct 0.06
# @strategy entryPct 0.25
# @strategy tradeDirection long
```

含义分别是：

- `stopLossPct 0.03`：默认 3% 止损
- `takeProfitPct 0.06`：默认 6% 止盈
- `entryPct 0.25`：默认用 25% 资金开仓
- `tradeDirection long`：默认只做多

这种写法适合：

- 信号代码尽量简单
- 希望回测时能直接读懂默认风险参数
- 希望 UI 和引擎都能直接识别这些默认值

### 4.2 在 IndicatorStrategy 里写“指标驱动型止损”

如果你的“止损”本质上是策略逻辑的一部分，那就不要假装成外部配置，而是直接写进 `sell` 信号。

例如：跌破 ATR 风格止损线就卖出。

```python
atr = (df['high'] - df['low']).rolling(14).mean()
stop_line = df['close'].rolling(20).max() - atr * 2.0

raw_sell = df['close'] < stop_line.shift(1)
df['sell'] = (raw_sell.fillna(False) & (~raw_sell.shift(1).fillna(False))).astype(bool)
```

这种写法表示：

- 退出属于你的指标逻辑
- 引擎不是替你“发明”一个止损
- 你最好在描述或注释里说明这一点

### 4.3 IndicatorStrategy 里的仓位管理边界

对 `IndicatorStrategy` 来说，仓位管理应该尽量保持简单：

- 用 `entryPct` 管默认开仓资金占比
- 用 `tradeDirection` 管做多 / 做空 / 双向
- 用固定的止损止盈或 trailing 默认值做保护

如果你需要下面这些能力：

- 分批加仓、减仓
- 部分止盈
- 开仓前后用不同逻辑
- 止损线会跟随当前持仓状态动态变化
- 止损后冷却一段时间再重入

那就说明这套逻辑已经超出 `IndicatorStrategy` 该承担的范围，应该迁移到 `ScriptStrategy`。

---

## 5. 完整的 IndicatorStrategy 示例

下面这个例子展示了一个更符合开发者思维的完整结构：元数据、默认配置、指标计算、信号生成、图表输出分层清楚。

```python
my_indicator_name = "EMA Pullback Strategy"
my_indicator_description = "Buy pullbacks above the slow EMA and exit on trend failure."

# @param fast_len int 20 Fast EMA length
# @param slow_len int 50 Slow EMA length
# @param rsi_len int 14 RSI length
# @param rsi_floor float 50 Minimum RSI for entry

# @strategy stopLossPct 0.03
# @strategy takeProfitPct 0.06
# @strategy entryPct 0.25
# @strategy tradeDirection long

df = df.copy()

fast_len = int(params.get('fast_len', 20))
slow_len = int(params.get('slow_len', 50))
rsi_len = int(params.get('rsi_len', 14))
rsi_floor = float(params.get('rsi_floor', 50.0))

ema_fast = df['close'].ewm(span=fast_len, adjust=False).mean()
ema_slow = df['close'].ewm(span=slow_len, adjust=False).mean()

delta = df['close'].diff()
gain = delta.clip(lower=0).ewm(alpha=1 / rsi_len, adjust=False).mean()
loss = (-delta.clip(upper=0)).ewm(alpha=1 / rsi_len, adjust=False).mean()
rs = gain / loss.replace(0, np.nan)
rsi = 100 - (100 / (1 + rs))

trend_up = ema_fast > ema_slow
pullback_done = df['close'] > ema_fast
rsi_ok = rsi > rsi_floor

raw_buy = trend_up & pullback_done & rsi_ok & (~trend_up.shift(1).fillna(False))
raw_sell = (ema_fast < ema_slow) | (rsi < 45)

buy = (raw_buy.fillna(False) & (~raw_buy.shift(1).fillna(False))).astype(bool)
sell = (raw_sell.fillna(False) & (~raw_sell.shift(1).fillna(False))).astype(bool)

df['buy'] = buy
df['sell'] = sell

buy_marks = [df['low'].iloc[i] * 0.995 if buy.iloc[i] else None for i in range(len(df))]
sell_marks = [df['high'].iloc[i] * 1.005 if sell.iloc[i] else None for i in range(len(df))]

output = {
    "name": my_indicator_name,
    "plots": [
        {
            "name": "EMA Fast",
            "data": ema_fast.fillna(0).tolist(),
            "color": "#1890ff",
            "overlay": True
        },
        {
            "name": "EMA Slow",
            "data": ema_slow.fillna(0).tolist(),
            "color": "#faad14",
            "overlay": True
        },
        {
            "name": "RSI",
            "data": rsi.fillna(0).tolist(),
            "color": "#722ed1",
            "overlay": False
        }
    ],
    "signals": [
        {
            "type": "buy",
            "text": "B",
            "data": buy_marks,
            "color": "#00E676"
        },
        {
            "type": "sell",
            "text": "S",
            "data": sell_marks,
            "color": "#FF5252"
        }
    ]
}
```

这个例子刻意强调了几件事：

- 先算指标，再出信号
- 进出场逻辑通过布尔列表达
- 固定风险默认值通过 `# @strategy` 单独声明
- 图表输出是最后一步，不要和信号逻辑搅在一起

### 5.1 一个更贴近平台 UI 的示例

下面这个版本更接近 QuantDinger 当前真实使用方式：

- 用 `# @param` 暴露常调参数
- 用 `# @strategy` 暴露默认止损、止盈、仓位和跟踪止损
- 显式声明 `tradeDirection`，让代码、保存后的策略、回测面板保持一致
- 杠杆仍然留给产品 UI 管，不写进源码

```python
my_indicator_name = "Breakout Retest With Direction Control"
my_indicator_description = "Breakout-and-retest logic with platform-friendly params and default risk settings."

# @param breakout_len int 20 Breakout lookback bars
# @param retest_buffer float 0.002 Retest tolerance ratio
# @param volume_mult float 1.2 Minimum volume filter
# @param ema_filter_len int 50 Trend filter EMA length

# @strategy stopLossPct 0.02
# @strategy takeProfitPct 0.05
# @strategy entryPct 0.2
# @strategy trailingEnabled true
# @strategy trailingStopPct 0.015
# @strategy trailingActivationPct 0.03
# @strategy tradeDirection both

df = df.copy()

breakout_len = int(params.get('breakout_len', 20))
retest_buffer = float(params.get('retest_buffer', 0.002))
volume_mult = float(params.get('volume_mult', 1.2))
ema_filter_len = int(params.get('ema_filter_len', 50))

ema_filter = df['close'].ewm(span=ema_filter_len, adjust=False).mean()
range_high = df['high'].rolling(breakout_len).max().shift(1)
range_low = df['low'].rolling(breakout_len).min().shift(1)
volume_avg = df['volume'].rolling(breakout_len).mean()

long_breakout = df['close'] > range_high
long_retest_ok = df['low'] <= range_high * (1 + retest_buffer)
long_volume_ok = df['volume'] >= volume_avg * volume_mult
long_trend_ok = df['close'] > ema_filter

short_breakout = df['close'] < range_low
short_retest_ok = df['high'] >= range_low * (1 - retest_buffer)
short_volume_ok = df['volume'] >= volume_avg * volume_mult
short_trend_ok = df['close'] < ema_filter

raw_buy = long_breakout & long_retest_ok & long_volume_ok & long_trend_ok
raw_sell = short_breakout & short_retest_ok & short_volume_ok & short_trend_ok

buy = (raw_buy.fillna(False) & (~raw_buy.shift(1).fillna(False))).astype(bool)
sell = (raw_sell.fillna(False) & (~raw_sell.shift(1).fillna(False))).astype(bool)

df['buy'] = buy
df['sell'] = sell

buy_marks = [df['low'].iloc[i] * 0.995 if buy.iloc[i] else None for i in range(len(df))]
sell_marks = [df['high'].iloc[i] * 1.005 if sell.iloc[i] else None for i in range(len(df))]

output = {
    "name": my_indicator_name,
    "plots": [
        {
            "name": "EMA Filter",
            "data": ema_filter.fillna(0).tolist(),
            "color": "#1890ff",
            "overlay": True
        },
        {
            "name": "Range High",
            "data": range_high.fillna(0).tolist(),
            "color": "#52c41a",
            "overlay": True
        },
        {
            "name": "Range Low",
            "data": range_low.fillna(0).tolist(),
            "color": "#f5222d",
            "overlay": True
        }
    ],
    "signals": [
        {
            "type": "buy",
            "text": "L",
            "data": buy_marks,
            "color": "#00E676"
        },
        {
            "type": "sell",
            "text": "S",
            "data": sell_marks,
            "color": "#FF5252"
        }
    ]
}
```

这个例子为什么更贴近平台：

- `# @param` 的值可以直接被 AI 调参或手动参数修改流程接管
- `# @strategy` 能和保存后的策略默认值、右侧回测面板风险配置更自然地对齐
- `tradeDirection both` 让人一眼看出这份代码本身就是为多空双向设计的
- 杠杆继续交给产品配置层，不会被藏进源码里造成误解

---

## 6. 什么时候该切到 ScriptStrategy

当策略需要“运行时状态”而不是“纯 dataframe 信号”时，就该迁移到 `ScriptStrategy`。

典型信号包括：

- 止损止盈依赖当前持仓，而不是仅依赖历史序列
- 开仓后要动态移动止损
- 需要部分平仓或加仓
- 首次开仓和再次开仓逻辑不同
- 需要冷却期、节流、bot 风格执行规则

### 6.1 必需函数

面向当前产品链路，最稳妥的约定是：

- `def on_init(ctx): ...`
- `def on_bar(ctx, bar): ...`

原因是：

- 运行时编译器真正强制的是 `on_bar`
- 但部分产品侧校验路径仍然要求源码里同时存在 `on_init` 和 `on_bar`
- 为了避免“运行时能跑、校验却不过”的不一致，建议两个函数都写，即使 `on_init` 只是做初始化或打印日志

### 6.2 可用对象

`bar` 通常提供：

- `bar.open`
- `bar.high`
- `bar.low`
- `bar.close`
- `bar.volume`
- `bar.timestamp`

`ctx` 当前通常提供：

- `ctx.param(name, default=None)`
- `ctx.bars(n=1)`
- `ctx.position`
- `ctx.balance`
- `ctx.equity`
- `ctx.log(message)`
- `ctx.buy(price=None, amount=None)`
- `ctx.sell(price=None, amount=None)`
- `ctx.close_position()`

补充说明：

- `ctx` 不会直接把完整交易配置对象暴露给脚本
- 杠杆、交易标的、交易场所、账户凭证等，应放在产品配置层，而不是写死在脚本里
- 脚本源码内部需要的默认参数，优先通过 `ctx.param(...)` 管理

`ctx.position` 同时支持数值判断和字段访问，例如：

```python
if not ctx.position:
    ...

if ctx.position > 0:
    ...

if ctx.position["side"] == "long":
    ...
```

### 6.3 一个带运行时退出的 ScriptStrategy 示例

```python
def on_init(ctx):
    ctx.log("strategy initialized")


def on_bar(ctx, bar):
    stop_loss_pct = ctx.param("stop_loss_pct", 0.03)
    take_profit_pct = ctx.param("take_profit_pct", 0.06)
    order_amount = ctx.param("order_amount", 1)

    bars = ctx.bars(30)
    if len(bars) < 20:
        return

    closes = [b.close for b in bars]
    ma_fast = sum(closes[-10:]) / 10
    ma_slow = sum(closes[-20:]) / 20

    if not ctx.position and ma_fast > ma_slow:
        ctx.buy(price=bar.close, amount=order_amount)
        return

    if not ctx.position:
        return

    if ctx.position["side"] != "long":
        return

    entry_price = ctx.position["entry_price"]

    if bar.close <= entry_price * (1 - stop_loss_pct):
        ctx.close_position()
        return

    if bar.close >= entry_price * (1 + take_profit_pct):
        ctx.close_position()
        return

    if ma_fast < ma_slow:
        ctx.close_position()
```

这种写法适合“止盈止损属于运行时持仓管理”的场景，而不是单纯图表信号输出。

仓位语义还要补一句：

- 在当前系统里，保存后的策略回测，仓位大小仍然主要由规范化后的交易配置决定，例如 `entryPct`
- 因此 `ctx.buy()` / `ctx.sell()` 里的 `amount` 更适合理解成运行时下单意图，而不是回测仓位的唯一来源
- 真正准备上模拟盘或实盘前，一定要先通过“保存后的策略回测”核对实际仓位暴露

### 6.4 普通脚本模式与 bot 模式

大多数 `ScriptStrategy` 都运行在**已收盘 K 线**语义下：

- 引擎会在 bar 确认收盘后调用 `on_bar(ctx, bar)`
- 这也是普通策略回测和逐 bar 实盘最接近的心智模型

当前系统里还存在 bot 风格运行模式：

- bot 模式下，系统可能会基于最新价格构造“类 tick 的伪 bar”反复调用 `on_bar`
- 这种模式更适合网格、DCA 或其他更偏机器人执行的策略
- 如果你的脚本是为 bot 模式设计的，应该和标准 bar-close 策略分开测试，不要混为一谈

### 6.5 一个更贴近平台实盘的 ScriptStrategy 示例

下面这个例子更接近平台里真实可落地的实盘脚本写法：

- 用 `ctx.param(...)` 管脚本级默认参数
- 先看 `ctx.position`，再决定是开仓、反手、减仓还是全部平仓
- 用 `ctx.buy()` / `ctx.sell()` 表达方向性下单意图
- 当你的语义是“现在全部退出”时，用 `ctx.close_position()` 最明确

```python
def on_init(ctx):
    ctx.log("live strategy initialized")


def on_bar(ctx, bar):
    fast_len = int(ctx.param("fast_len", 10))
    slow_len = int(ctx.param("slow_len", 30))
    risk_pct = float(ctx.param("risk_pct", 0.25))
    stop_loss_pct = float(ctx.param("stop_loss_pct", 0.02))
    take_profit_pct = float(ctx.param("take_profit_pct", 0.05))
    allow_short = bool(ctx.param("allow_short", True))

    bars = ctx.bars(slow_len + 5)
    if len(bars) < slow_len:
        return

    closes = [b.close for b in bars]
    fast_ma = sum(closes[-fast_len:]) / fast_len
    slow_ma = sum(closes[-slow_len:]) / slow_len
    price = bar.close

    if not ctx.position:
        if fast_ma > slow_ma:
            ctx.buy(price=price, amount=risk_pct)
            return
        if allow_short and fast_ma < slow_ma:
            ctx.sell(price=price, amount=risk_pct)
            return
        return

    if ctx.position["side"] == "long":
        entry_price = float(ctx.position["entry_price"])
        if price <= entry_price * (1 - stop_loss_pct):
            ctx.close_position()
            return
        if price >= entry_price * (1 + take_profit_pct):
            ctx.close_position()
            return
        if allow_short and fast_ma < slow_ma:
            ctx.sell(price=price, amount=risk_pct)
            return

    if ctx.position["side"] == "short":
        entry_price = float(ctx.position["entry_price"])
        if price >= entry_price * (1 + stop_loss_pct):
            ctx.close_position()
            return
        if price <= entry_price * (1 - take_profit_pct):
            ctx.close_position()
            return
        if fast_ma > slow_ma:
            ctx.buy(price=price, amount=risk_pct)
            return
```

这个例子重点演示了：

- `ctx.param(...)` 让脚本默认值集中且清晰
- `ctx.position` 决定当前是空仓、做多还是做空分支
- `ctx.buy()` / `ctx.sell()` 表达的是方向性意图，不只是孤立的“开多”或“开空”
- 当规则的语义是“现在全部退出”时，`ctx.close_position()` 最不容易产生歧义

下面这些回测 / 实盘差异一定要记住：

- 标准脚本回测和普通实盘模式都以“已确认收盘的 bar”为核心，但 bot 模式可能会用类 tick 的伪 bar 反复驱动脚本
- `amount` 更适合理解成运行时下单意图；保存后的策略回测，仓位大小仍然主要受 `entryPct` 这类规范化交易配置影响
- 当你在多头持仓中调用 `ctx.sell()`，或在空头持仓中调用 `ctx.buy()` 时，实际效果可能会根据运行时状态与产品配置表现为“先平后反手”一类意图
- 如果你要的是明确的“全部平仓”，优先用 `ctx.close_position()`，不要依赖隐式解释

---

## 7. 回测、持久化与当前限制

保存后的策略会被后端解析成统一快照，再进入回测或执行链路。常见字段包括：

- `strategy_type`
- `strategy_mode`
- `strategy_code`
- `indicator_config`
- `trading_config`

当前常见 `run_type` 包括：

- `indicator`
- `strategy_indicator`
- `strategy_script`

当前限制包括：

- `cross_sectional` 在当前策略快照链路中不支持
- `ScriptStrategy` 当前不支持 `cross_sectional` 实盘运行
- 脚本策略回测当前不会走指标侧的 MTF 执行路径
- 策略回测要求 symbol 合法且代码非空

---

## 8. 最佳实践

### 8.1 始终避免未来函数

- 只使用已完成 bar 的信息
- 优先使用 `shift(1)` 做确认
- 不要在信号逻辑中使用 `shift(-1)`

### 8.2 显式处理 NaN

滚动窗口和 EWM 都会产生前导 NaN，生成信号前必须先清理。

### 8.3 保持所有序列长度一致

所有 `plot['data']` 和 `signal['data']` 都必须与 `len(df)` 完全一致。

### 8.4 IndicatorStrategy 尽量保持向量化

核心指标计算优先用 pandas 原生向量化逻辑，不要把主逻辑写成逐行循环。

### 8.5 ScriptStrategy 保持确定性

`ScriptStrategy` 尽量避免 `ctx` 外部的隐式状态、随机行为，以及含糊不清的下单意图。

### 8.6 把配置放在正确层级

- 指标型默认值用 `# @param` 和 `# @strategy`
- 脚本型默认值优先用 `ctx.param()`
- 杠杆、成交时机、交易所和账户凭证放在产品配置层，不要硬编码

---

## 9. 故障排除

### 9.1 `column "strategy_mode" does not exist`

说明数据库结构版本落后于当前代码，需要对 `qd_strategies_trading` 执行对应迁移。

### 9.2 `Strategy script must define on_bar(ctx, bar)`

说明 `ScriptStrategy` 缺少必需的 `on_bar`。

### 9.3 `Missing required functions: on_init, on_bar`

说明当前 UI 校验器要求源码里同时存在这两个函数。

### 9.4 `Strategy code is empty and cannot be backtested`

说明保存后的策略在当前模式下没有有效代码。

### 9.5 图表长度不一致

说明某个 plot 或 signal 的数组长度没有和 `df` 对齐。

### 9.6 回测结果很奇怪

优先检查这几件事：

- 有没有误用未来数据
- `buy` / `sell` 是否做成了边缘触发
- 是否同时混用了“信号退出”和“引擎退出”却没有说明清楚
- `# @strategy` 默认值是否真的符合策略风格

### 9.7 后端日志排查

如果策略创建、校验、回测或执行失败，请优先查后端日志。常见问题包括：

- 数据库结构不匹配
- JSON / 配置载荷格式错误
- 代码校验失败
- 市场 / symbol 不匹配
- 交易所凭证或配置异常

---

## 10. 完整工作流：从 Indicator IDE 到保存成策略再到实盘

这是目前最符合产品链路的实战流程。

### 10.1 先在 Indicator IDE 里做原型

在策略还处于构思阶段时，优先从 Indicator IDE 开始：

1. 先把指标逻辑写在 `df` 上。
2. 用 `# @param` 声明可调参数。
3. 用 `# @strategy` 声明默认止损、止盈、仓位和方向。
4. 补齐图表展示需要的 `plots` 和 `signals`。
5. 先跑指标侧回测，确认信号密度、图表观感和成交语义都合理。

这个阶段的目标不是立刻上实盘，而是先把策略逻辑变得可见、可测、可迭代。

### 10.2 在产品里调参与校验

当指标逻辑已经基本正确后：

1. 先跑代码质量检查，排除缺少元数据或明显可疑写法。
2. 用真实的标的、周期、手续费、滑点、杠杆配置去跑回测。
3. 必要时使用 AI 调参或结构化扫参比较参数组合。
4. 把最终采用的参数重新写回源码，让代码本身仍然是最直观的“单一真相”。

这里推荐的分工方式是：

- 信号逻辑由代码表达
- `# @param` 和 `# @strategy` 表达默认参数和风控
- 市场、杠杆、日期区间、执行环境由产品面板管理

### 10.3 把指标保存成策略

当信号模型稳定后：

1. 先保存当前指标代码。
2. 通过产品流程创建或保存策略记录。
3. 确认保存后的策略快照模式、默认值和交易配置都符合预期。
4. 从持久化后的策略记录发起策略回测，而不是只看编辑器里的即时结果。

这一步很关键，因为：

- 保存后的策略回测更接近真实执行链路
- 规范化快照可能会补齐成交时机和交易配置默认值
- 很多 symbol、模式、配置、持久化层面的错配，都是在这一步才暴露出来

### 10.4 判断 IndicatorStrategy 是否已经够用

如果满足下面这些条件，就继续保留 `IndicatorStrategy`：

- 进出场核心仍然主要靠信号驱动
- 固定止损、止盈、跟踪止损默认值已经足够
- 不需要依赖当前持仓状态做复杂运行时逻辑

如果出现下面这些需求，就应升级成 `ScriptStrategy`：

- 开仓后要持续盯着持仓逐根处理
- 退出逻辑依赖当前持仓状态，而不只是历史序列
- 需要冷却期、分批止盈、加仓、减仓、机器人式执行逻辑

### 10.5 进入模拟盘或实盘前的最后检查

在真正开启实盘前，至少确认：

1. 交易所 / 经纪商 / 标的 / 凭证配置正确。
2. 对成交时机的假设已经再次核实。
3. 杠杆、方向、仓位大小放在了正确的产品配置层。
4. 先用保守仓位、小范围标的做验证。
5. 观察运行日志和真实下单行为，再决定是否放大规模。

实盘不是编辑器实验的自然延伸，而是一个单独的验证阶段。

---

## 11. 常见错误示例 vs 正确写法

这一节专门列出最容易把回测做“虚高”、把策略行为写混乱、或者把产品配置和策略代码搞串的高频坑点。

### 11.1 声明了 `# @param`，却根本没读取

错误写法：

```python
# @param fast_len int 20 Fast EMA length

df = df.copy()
fast_len = 20
ema_fast = df['close'].ewm(span=fast_len, adjust=False).mean()
```

正确写法：

```python
# @param fast_len int 20 Fast EMA length

df = df.copy()
fast_len = int(params.get('fast_len', 20))
ema_fast = df['close'].ewm(span=fast_len, adjust=False).mean()
```

为什么：

- 只声明不读取，会让参数变成“看起来能调，实际上调不动”
- 平台代码质量检查也可能对此给出提醒

### 11.2 `buy` / `sell` 每根 bar 都在触发

错误写法：

```python
df['buy'] = df['close'] > ema_fast
df['sell'] = df['close'] < ema_fast
```

正确写法：

```python
raw_buy = df['close'] > ema_fast
raw_sell = df['close'] < ema_fast

df['buy'] = (raw_buy.fillna(False) & (~raw_buy.shift(1).fillna(False))).astype(bool)
df['sell'] = (raw_sell.fillna(False) & (~raw_sell.shift(1).fillna(False))).astype(bool)
```

为什么：

- 如果每根 bar 都重复发信号，进出场、标记、回测解释都会变得混乱
- 大多数策略真正想表达的是“条件刚刚成立时触发一次”，而不是“条件持续成立就一直触发”

### 11.3 把杠杆写进策略源码

错误写法：

```python
# @strategy leverage 10
```

正确写法：

```python
# @strategy entryPct 0.2
# @strategy stopLossPct 0.02
# @strategy takeProfitPct 0.05
```

然后把杠杆放到产品面板或保存后的策略交易配置里。

为什么：

- 杠杆属于执行配置，不属于指标元数据
- 把杠杆藏进代码里，会让回测解释更混乱，也更容易和产品侧配置打架

### 11.4 误用 `shift(-1)`，把未来函数写进策略

错误写法：

```python
df['buy'] = (df['close'].shift(-1) > ema_fast).fillna(False)
```

正确写法：

```python
raw_buy = df['close'] > ema_fast
df['buy'] = (raw_buy.fillna(False) & (~raw_buy.shift(1).fillna(False))).astype(bool)
```

为什么：

- `shift(-1)` 本质上是在偷看未来数据
- 这类策略在回测里往往会“好得离谱”，但一到真实执行就失真

### 11.5 在 `ScriptStrategy` 里把 `amount` 当成绝对回测仓位

错误心智模型：

```python
ctx.buy(price=bar.close, amount=1.0)
```

“这就等于回测里永远按 100% 仓位开仓。”

正确心智模型：

```python
position_pct = float(ctx.param("risk_pct", 0.25))
ctx.buy(price=bar.close, amount=position_pct)
```

然后再用保存后的策略回测去核对规范化交易配置。

为什么：

- 在当前系统里，保存后的策略回测，仓位大小仍然主要由 `entryPct` 这类规范化配置决定
- `amount` 更适合理解成运行时下单意图，而不是历史回测仓位的唯一真相

### 11.6 明明想“全部平仓”，却写成了 `ctx.sell()` / `ctx.buy()`

容易歧义的写法：

```python
if stop_hit:
    ctx.sell(price=bar.close, amount=0.25)
```

更清晰的写法：

```python
if stop_hit:
    ctx.close_position()
```

为什么：

- `ctx.buy()` / `ctx.sell()` 表达的是方向性意图，最终效果会结合当前持仓状态解释
- 如果你的规则语义就是“现在全部退出”，`ctx.close_position()` 最不容易被误解

### 11.7 信号退出和引擎退出混着用，却没写说明

容易出问题的写法：

```python
# @strategy stopLossPct 0.02
# @strategy takeProfitPct 0.05

df['sell'] = some_other_exit_condition
```

更好的写法：

```python
# Primary exit: reverse signal
# Secondary protection: engine-managed fixed stop-loss / take-profit
# @strategy stopLossPct 0.02
# @strategy takeProfitPct 0.05

df['sell'] = reverse_signal
```

为什么：

- 两种退出方式并存本身不一定错
- 真正的问题是没人说得清“到底谁是主退出来源”

---

## 12. 平台支持字段速查表

这一节可以当成“当前平台到底支持什么”的速查页，写策略时可以直接对着查。

### 12.1 `# @strategy` 支持的 key

| Key | 含义 | 常见写法 | 说明 |
|-----|------|----------|------|
| `stopLossPct` | 默认止损比例 | `# @strategy stopLossPct 0.02` | 引擎读取的默认风控配置 |
| `takeProfitPct` | 默认止盈比例 | `# @strategy takeProfitPct 0.05` | 底层解析器允许范围比示例更宽松 |
| `entryPct` | 默认开仓资金占比 | `# @strategy entryPct 0.25` | 是回测仓位的重要来源之一 |
| `trailingEnabled` | 是否开启跟踪止损 | `# @strategy trailingEnabled true` | 布尔值 |
| `trailingStopPct` | 跟踪止损比例 | `# @strategy trailingStopPct 0.015` | 通常与 trailing 一起使用 |
| `trailingActivationPct` | 启动跟踪止损前的盈利阈值 | `# @strategy trailingActivationPct 0.03` | 通常与 trailing 一起使用 |
| `tradeDirection` | 方向限制 | `# @strategy tradeDirection both` | 可选 `long`、`short`、`both` |

要点：

- 这些 key 用于指标侧默认策略配置
- 不要把 `leverage` 写进 `# @strategy`
- 交易所、标的、凭证、杠杆都应该放在产品配置层

### 12.2 `# @param` 速查格式

| 部分 | 示例 | 含义 |
|------|------|------|
| 名称 | `fast_len` | 参数键名 |
| 类型 | `int` / `float` / `bool` / `str` / `string` | 支持的类型 |
| 默认值 | `20` | 系统看到的默认值 |
| 描述 | `Fast EMA length` | 给人看的说明 |

示例：

```python
# @param fast_len int 20 Fast EMA length
# @param allow_short bool true Allow short entries
```

随后用下面这种方式读取：

```python
fast_len = int(params.get('fast_len', 20))
allow_short = bool(params.get('allow_short', True))
```

### 12.3 `ScriptStrategy` 里的 `ctx` 支持什么

| 项目 | 类型 | 含义 |
|------|------|------|
| `ctx.param(name, default)` | 方法 | 读取或初始化脚本级默认参数 |
| `ctx.bars(n=1)` | 方法 | 取得当前运行时之前的最近若干根 bar |
| `ctx.log(message)` | 方法 | 写策略日志 |
| `ctx.buy(price=None, amount=None)` | 方法 | 表达买入 / 做多方向意图 |
| `ctx.sell(price=None, amount=None)` | 方法 | 表达卖出 / 做空方向意图 |
| `ctx.close_position()` | 方法 | 显式全部平仓 |
| `ctx.position` | 字段 | 当前持仓对象 |
| `ctx.balance` | 字段 | 当前余额快照 |
| `ctx.equity` | 字段 | 当前权益快照 |

`ctx.position` 常见字段：

| 字段 | 含义 |
|------|------|
| `side` | `long`、`short`，或空字符串表示空仓 |
| `size` | 当前持仓大小 |
| `entry_price` | 平均开仓价 |
| `direction` | `1`、`-1`、`0` |
| `amount` | 运行时数量镜像 |

### 12.4 `ScriptStrategy` 里的 `bar` 有哪些字段

| 字段 | 含义 |
|------|------|
| `bar.open` | 开盘价 |
| `bar.high` | 最高价 |
| `bar.low` | 最低价 |
| `bar.close` | 收盘价 |
| `bar.volume` | 成交量 |
| `bar.timestamp` | 当前运行时传入的时间值 |

### 12.5 `IndicatorStrategy` 的 `output` 允许哪些结构

顶层结构通常写成：

```python
output = {
    "name": my_indicator_name,
    "plots": [],
    "signals": [],
    "calculatedVars": {}
}
```

顶层常见 key：

| Key | 是否必需 | 含义 |
|-----|----------|------|
| `name` | 建议提供 | 展示名称 |
| `plots` | 建议提供 | 图表曲线输出 |
| `signals` | 建议提供 | 买卖点标记输出 |
| `calculatedVars` | 可选 | 额外元数据或计算结果 |

每个 `plot` 项常见字段：

| Key | 含义 |
|-----|------|
| `name` | 曲线名称 |
| `data` | 与 `len(df)` 对齐的数组 |
| `color` | 显示颜色 |
| `overlay` | 是否叠加在主图上 |
| `type` | 可选的渲染提示 |

每个 `signal` 项常见字段：

| Key | 含义 |
|-----|------|
| `type` | `buy` 或 `sell` |
| `text` | 标记文本 |
| `color` | 标记颜色 |
| `data` | 与 `len(df)` 对齐的数组；无信号位置用 `None` |

### 12.6 快速提醒

- `df['buy']` 和 `df['sell']` 应该是布尔值，并与 `df` 长度完全对齐
- 尽量使用边缘触发信号
- 不要在信号逻辑里使用 `shift(-1)`
- 当规则语义明显是“全部退出”时，优先用 `ctx.close_position()`
- `amount` 更适合作为运行时下单意图，最终仓位仍应通过保存后的策略回测核实

---

## 13. 推荐开发流程

1. 先用 `IndicatorStrategy` 把想法原型化。
2. 先验证图表、信号密度和 next-bar-open 的回测语义。
3. 把 `# @param` 和 `# @strategy` 元数据补完整。
4. 明确写清楚：退出到底是“信号负责”还是“引擎负责”。
5. 保存策略后，再从持久化记录跑策略回测。
6. 只有在确实需要运行时仓位管理时，再迁移到 `ScriptStrategy`。
7. 确认配置、凭证和市场语义都正确后，再进入模拟盘或实盘。