532 lines
15 KiB
Markdown
532 lines
15 KiB
Markdown
# QuantDinger 脚本代码开发指南
|
||
|
||
本文说明如何编写可回测、可实盘、可维护的 QuantDinger 脚本代码。脚本代码适合有运行状态的策略，例如分层建仓、篮子均价止盈、追踪止损、金字塔加仓、冷却期、重复下单防护等。
|
||
|
||
## 1. 核心边界
|
||
|
||
脚本代码只负责策略逻辑。用户运行时填写的内容不应该再写进代码参数。
|
||
|
||
运行面板负责：
|
||
|
||
- 标的，例如 BTC/USDT
|
||
- 市场类型，现货或合约
|
||
- 交易方向，做多、做空或双向
|
||
- 投入金额
|
||
- 合约杠杆
|
||
- 账户、通知、实盘风控开关
|
||
|
||
脚本代码负责：
|
||
|
||
- 入场条件
|
||
- 加仓、减仓、止盈、止损规则
|
||
- 分层数量、间距、倍数、周期、冷却期
|
||
- 状态持久化和防重复下单
|
||
- 日志与篮子状态 checkpoint
|
||
|
||
不要在脚本中写：
|
||
|
||
```python
|
||
ctx.param('direction', 'long')
|
||
ctx.param('market_type', 'swap')
|
||
ctx.param('investment_amount', 1000)
|
||
ctx.param('leverage', 3)
|
||
ctx.param('base_notional', 50)
|
||
```
|
||
|
||
这些值应由运行面板传入，可在脚本中读取：
|
||
|
||
```python
|
||
direction = ctx.direction
|
||
market_type = ctx.market_type
|
||
budget = ctx.investment_amount
|
||
leverage = ctx.leverage
|
||
```
|
||
|
||
## 2. 生命周期
|
||
|
||
脚本必须包含：
|
||
|
||
```python
|
||
def on_init(ctx):
|
||
pass
|
||
|
||
def on_bar(ctx, bar):
|
||
pass
|
||
```
|
||
|
||
`on_init(ctx)` 在脚本启动时执行一次，用于读取策略参数和初始化默认值。
|
||
|
||
`on_bar(ctx, bar)` 每根 K 线执行一次。当前统一使用 1m K 线作为脚本粒度；实盘还会每 10 秒检查一次最新价格，用于降低止盈止损响应延迟。回测只基于历史 K 线，因此极高频 tick 级逻辑不应该写在脚本里。
|
||
|
||
`bar` 支持：
|
||
|
||
```python
|
||
bar['open']
|
||
bar['high']
|
||
bar['low']
|
||
bar['close']
|
||
bar['volume']
|
||
bar['timestamp']
|
||
```
|
||
|
||
## 3. 参数设计
|
||
|
||
只把策略结构参数放进 `ctx.param(...)`：
|
||
|
||
```python
|
||
def on_init(ctx):
|
||
ctx.fast_period = ctx.param('fast_period', 12)
|
||
ctx.slow_period = ctx.param('slow_period', 36)
|
||
ctx.take_profit_pct = ctx.param('take_profit_pct', 0.006)
|
||
ctx.max_layers = ctx.param('max_layers', 5)
|
||
```
|
||
|
||
百分比默认值在 Python 里使用 0-1 小数：
|
||
|
||
- `0.006` 表示 0.6%
|
||
- `0.02` 表示 2%
|
||
- `0.8` 表示 80%
|
||
|
||
前端可以用 0-100 的显示方式，但写回代码时应保持 Python 小数。
|
||
|
||
## 4. 投入金额和下单金额
|
||
|
||
推荐所有状态型脚本使用 `ctx.basket(side).open_child_order(..., notional=quote_amount)`。
|
||
|
||
`notional` 表示计价货币金额，例如 USDT 金额。回测和实盘会根据市场类型、价格和杠杆换算为实际下单数量。
|
||
|
||
示例：
|
||
|
||
```python
|
||
def _run_budget(ctx):
|
||
try:
|
||
budget = float(ctx.investment_amount or 0.0)
|
||
except Exception:
|
||
budget = 0.0
|
||
if budget > 0:
|
||
return budget
|
||
return 0.0
|
||
|
||
def _planned_base_notional(ctx):
|
||
total_weight = 1 + 1.8 + 3.24
|
||
return _run_budget(ctx) / total_weight
|
||
|
||
def on_bar(ctx, bar):
|
||
price = float(bar['close'])
|
||
side = 'short' if str(ctx.direction).lower() == 'short' else 'long'
|
||
basket = ctx.basket(side)
|
||
quote_amount = _planned_base_notional(ctx)
|
||
basket.open_child_order(
|
||
layer=1,
|
||
order=1,
|
||
notional=quote_amount,
|
||
price=price,
|
||
action='open',
|
||
payload={'reason': 'first_entry'},
|
||
)
|
||
```
|
||
|
||
不要把“基础下单金额”作为模板参数暴露给用户。更清晰的模型是：用户填投入金额，脚本根据层数、倍数和总权重自动拆分每个子单的计划金额。
|
||
|
||
## 5. 方向处理
|
||
|
||
方向由运行面板选择。脚本只读取，不写死。
|
||
|
||
推荐写法：
|
||
|
||
```python
|
||
def _side(ctx):
|
||
try:
|
||
direction = str(ctx.direction)
|
||
except Exception:
|
||
direction = 'long'
|
||
return 'short' if direction.lower() == 'short' else 'long'
|
||
```
|
||
|
||
现货只能做多；这个限制由运行面板和执行层处理。脚本里不需要再做一套复杂分支。
|
||
|
||
## 6. 状态管理
|
||
|
||
有分层、篮子、冷却期的策略必须使用 `ctx.state`。
|
||
|
||
常见状态：
|
||
|
||
- 当前层数：`layer`
|
||
- 当前子单：`order`
|
||
- 均价：`avg_cost`
|
||
- 总数量：`qty`
|
||
- 下一次触发价格：`next_trigger`
|
||
- 冷却到哪根 K 线：`cooldown_until`
|
||
- 上次下单 K 线：`last_order_bar`
|
||
|
||
示例：
|
||
|
||
```python
|
||
bar_no = int(ctx.current_index)
|
||
last_order_bar = int(ctx.state.get('last_order_bar', -999999) or -999999)
|
||
if last_order_bar == bar_no:
|
||
return
|
||
|
||
ctx.state.set('last_order_bar', bar_no)
|
||
```
|
||
|
||
这样可以防止同一根 K 线重复发单。
|
||
|
||
## 7. Basket API
|
||
|
||
`ctx.basket(side)` 适合所有有篮子概念的策略。
|
||
|
||
常用方法：
|
||
|
||
```python
|
||
basket = ctx.basket('long')
|
||
|
||
basket.open_child_order(
|
||
layer=1,
|
||
order=1,
|
||
notional=50,
|
||
price=price,
|
||
action='open',
|
||
payload={'reason': 'entry'},
|
||
)
|
||
|
||
basket.open_child_order(
|
||
layer=2,
|
||
order=1,
|
||
notional=80,
|
||
price=price,
|
||
action='add',
|
||
payload={'reason': 'add_layer'},
|
||
)
|
||
|
||
basket.close_all(reason='take_profit')
|
||
```
|
||
|
||
`checkpoint` 用于展示策略当前状态：
|
||
|
||
```python
|
||
basket.checkpoint(
|
||
status='opening',
|
||
current_layer=layer,
|
||
current_order_in_layer=order,
|
||
total_qty=qty,
|
||
total_notional=qty * avg_cost,
|
||
avg_entry_price=avg_cost,
|
||
next_entry_trigger=next_trigger,
|
||
take_profit_price=take_profit,
|
||
max_layer=max_layers,
|
||
max_orders_per_layer=orders_per_layer,
|
||
)
|
||
```
|
||
|
||
## 8. 回测和实盘对齐
|
||
|
||
脚本回测和实盘使用同一套 `on_init/on_bar` 语义。需要注意：
|
||
|
||
- 回测基于历史 K 线，不模拟每 10 秒 tick 细节。
|
||
- 实盘会额外拉取最新价格用于更及时地检查价格条件。
|
||
- 下单金额建议使用 basket `notional`，这样合约杠杆在回测和实盘中口径一致。
|
||
- 策略不能依赖未来数据，只能使用 `ctx.bars(n)` 获取当前及历史 K 线。
|
||
- 每次加仓必须有价格间距、最大层数和防重复下单。
|
||
|
||
## 9. 沙箱限制
|
||
|
||
脚本在安全沙箱中执行。不要使用：
|
||
|
||
- `getattr`、`setattr`、`delattr`
|
||
- `eval`、`exec`、`open`、`compile`
|
||
- `globals`、`vars`、`dir`
|
||
- `__builtins__`、dunder 属性
|
||
- 文件、网络、数据库、进程、线程相关 API
|
||
- `os`、`sys`、`requests`、`urllib`、`socket`、`subprocess`、`threading`、`multiprocessing`、`sqlite3`、`psycopg`、`sqlalchemy`、`pathlib`、`tempfile`、`glob`、`io`、`operator`、`pickle`、`ctypes`
|
||
|
||
读取可选字段时，用 `try/except` 直接访问：
|
||
|
||
```python
|
||
try:
|
||
direction = str(ctx.direction)
|
||
except Exception:
|
||
direction = 'long'
|
||
```
|
||
|
||
不要写：
|
||
|
||
```python
|
||
direction = getattr(ctx, 'direction', 'long')
|
||
```
|
||
|
||
## 10. 推荐模板类型
|
||
|
||
经典可落地的脚本模板包括：
|
||
|
||
- EMA ATR 趋势风控：趋势跟随、ATR 止损、ATR 追踪止损。
|
||
- Donchian 突破金字塔：通道突破入场，盈利后顺势加仓。
|
||
- 布林均值回归篮子：触及布林外轨后分层建仓，均价回归止盈。
|
||
- 阶梯分仓马丁篮子：多层分仓、子单马丁、均价止盈、硬止损。
|
||
|
||
这些模板覆盖趋势、突破、震荡均值回归和高风险篮子模型，避免把多个相似的“加仓模板”重复展示给用户。
|
||
|
||
## 11. 复杂策略的推荐架构
|
||
|
||
复杂脚本不要写成一大坨 `if/else`。推荐拆成五层：
|
||
|
||
1. 信号层：判断是否允许入场、是否允许加仓、是否应该退出。
|
||
2. 资金层：把运行面板的投入金额拆成每一层、每一单的计划金额。
|
||
3. 状态层：保存当前阶段、层数、子单、均价、触发价、冷却期。
|
||
4. 执行层：只负责发出 `basket.open_child_order` 或 `basket.close_all`。
|
||
5. 风控层：硬止损、最大层数、最大订单数、冷却期、同 K 线防重复。
|
||
|
||
推荐文件结构虽然仍然是一个脚本，但代码内部应保持这种顺序：
|
||
|
||
```python
|
||
def on_init(ctx):
|
||
# 1. 读取策略参数
|
||
pass
|
||
|
||
def _side(ctx):
|
||
# 2. 读取运行面板方向
|
||
pass
|
||
|
||
def _run_budget(ctx):
|
||
# 3. 读取运行面板投入金额
|
||
pass
|
||
|
||
def _planned_notional(ctx, layer, order):
|
||
# 4. 计算每一单计划金额
|
||
pass
|
||
|
||
def _entry_signal(ctx, bar, bars):
|
||
# 5. 入场信号
|
||
pass
|
||
|
||
def _risk_exit(ctx, price, avg_cost):
|
||
# 6. 风控退出
|
||
pass
|
||
|
||
def _place_child(ctx, basket, layer, order, price, action):
|
||
# 7. 发单并更新状态
|
||
pass
|
||
|
||
def on_bar(ctx, bar):
|
||
# 8. 主流程，只编排，不塞复杂公式
|
||
pass
|
||
```
|
||
|
||
这样用户后续加新条件、换资金模型、换退出逻辑时，不需要重写整份策略。
|
||
|
||
## 12. 状态机模型
|
||
|
||
复杂策略应该先设计状态机。推荐状态：
|
||
|
||
| 状态 | 含义 | 允许动作 |
|
||
| --- | --- | --- |
|
||
| `idle` | 空仓等待 | 判断入场 |
|
||
| `opening` | 已开首单或正在建仓 | 加仓、止盈、止损 |
|
||
| `active` | 仓位完整运行中 | 止盈、止损、追踪退出 |
|
||
| `closing` | 已触发平仓 | 等待执行层完成 |
|
||
| `cooldown` | 平仓后冷却 | 不允许重新入场 |
|
||
|
||
脚本里可以不用显式保存字符串状态，但逻辑上必须有这套概念。最少要保存：
|
||
|
||
```python
|
||
ctx.state.set('layer', layer)
|
||
ctx.state.set('order', order)
|
||
ctx.state.set('avg_cost', avg_cost)
|
||
ctx.state.set('qty', qty)
|
||
ctx.state.set('next_trigger', next_trigger)
|
||
ctx.state.set('cooldown_until', cooldown_until)
|
||
ctx.state.set('last_order_bar', bar_no)
|
||
```
|
||
|
||
主流程建议固定为：
|
||
|
||
```python
|
||
def on_bar(ctx, bar):
|
||
# 1. 数据不足直接返回
|
||
# 2. 读取运行面板方向、价格、状态
|
||
# 3. 如果空仓，检查是否需要重置状态
|
||
# 4. 如果冷却中，直接返回
|
||
# 5. 如果空仓，判断入场
|
||
# 6. 如果持仓，先判断止盈/止损
|
||
# 7. 如果仍持仓，再判断加仓
|
||
# 8. 发单后更新 checkpoint 和 state
|
||
```
|
||
|
||
不要先加仓再判断止损。复杂策略里这个顺序很重要。
|
||
|
||
## 13. 资金拆分模型
|
||
|
||
用户只填一个“投入金额”。脚本需要根据策略结构拆分每个子单。
|
||
|
||
### 13.1 等额分层
|
||
|
||
适合突破金字塔：
|
||
|
||
```python
|
||
base_notional = ctx.investment_amount / ctx.max_layers
|
||
```
|
||
|
||
如果投入 1000 USDT、4 层，则每层 250 USDT。
|
||
|
||
### 13.2 温和递增分层
|
||
|
||
适合布林均值回归：
|
||
|
||
```python
|
||
weights = [ctx.layer_multiplier ** i for i in range(ctx.max_layers)]
|
||
base_notional = ctx.investment_amount / sum(weights)
|
||
layer_notional = base_notional * (ctx.layer_multiplier ** (layer - 1))
|
||
```
|
||
|
||
如果投入 1000 USDT、4 层、倍数 1.25，则每层按权重 1、1.25、1.56、1.95 拆分。
|
||
|
||
### 13.3 分仓马丁
|
||
|
||
适合 5 个分仓、每仓 3 单：
|
||
|
||
```python
|
||
one_layer_weight = sum([ctx.martingale_multiplier ** i for i in range(ctx.orders_per_layer)])
|
||
total_weight = one_layer_weight * ctx.max_layers
|
||
base_notional = ctx.investment_amount / total_weight
|
||
child_notional = base_notional * (ctx.martingale_multiplier ** (order - 1))
|
||
```
|
||
|
||
如果投入金额是 1000 USDT、5 层、每层 3 单、倍数 1.8：
|
||
|
||
- 单层权重：`1 + 1.8 + 3.24 = 6.04`
|
||
- 总权重：`6.04 * 5 = 30.2`
|
||
- 基础子单金额：`1000 / 30.2 = 33.11 USDT`
|
||
- 每层三单约为：`33.11 / 59.60 / 107.27 USDT`
|
||
|
||
这能避免“代码里写了基础下单金额，用户又填投入金额”的冲突。
|
||
|
||
## 14. 信号层设计
|
||
|
||
复杂策略的入场信号最好是“事件”，不是“状态”。
|
||
|
||
不推荐：
|
||
|
||
```python
|
||
if not has_position and fast > slow:
|
||
open_position()
|
||
```
|
||
|
||
这样会在趋势状态持续时频繁尝试入场，必须依赖其他防线兜底。
|
||
|
||
推荐：
|
||
|
||
```python
|
||
cross_up = prev_fast <= prev_slow and fast > slow
|
||
if not has_position and cross_up:
|
||
open_position()
|
||
```
|
||
|
||
常见信号模型：
|
||
|
||
- 趋势：EMA 金叉/死叉、价格突破均线并确认。
|
||
- 突破：当前收盘价突破过去 N 根最高/最低。
|
||
- 均值回归：价格触及布林带外轨，并用 RSI 过滤极端状态。
|
||
- 分仓马丁：首单可以无信号启动，也可以加趋势/震荡过滤；后续加仓只能由价格间距触发。
|
||
|
||
## 15. 风控层设计
|
||
|
||
复杂策略必须至少有三类风控：
|
||
|
||
1. 结构风控：最大层数、每层最大子单数、单 K 线只允许一次下单。
|
||
2. 价格风控：硬止损、均价止盈、追踪止损、通道退出。
|
||
3. 时间风控：冷却期、超时退出、长时间未成交后的状态重置。
|
||
|
||
示例：
|
||
|
||
```python
|
||
if last_order_bar == bar_no:
|
||
return
|
||
|
||
if layer >= ctx.max_layers and order >= ctx.orders_per_layer:
|
||
# 不再继续加仓，只等待止盈或硬止损
|
||
return
|
||
|
||
if pnl <= -ctx.hard_stop_pct:
|
||
basket.close_all(reason='hard_stop')
|
||
_reset_cycle(ctx, bar_no + ctx.cooldown_bars)
|
||
return
|
||
```
|
||
|
||
## 16. 回测前检查清单
|
||
|
||
用户写完复杂脚本后，先检查：
|
||
|
||
- 是否定义了 `on_init(ctx)` 和 `on_bar(ctx, bar)`。
|
||
- 是否没有使用 `getattr`、文件、网络、数据库、进程等沙箱禁止能力。
|
||
- 是否没有把方向、市场类型、投入金额、杠杆写成 `ctx.param`。
|
||
- 是否所有百分比参数在代码里都是 0-1 小数。
|
||
- 是否所有加仓都有最大次数和价格间距。
|
||
- 是否所有发单都有同 K 线防重复。
|
||
- 是否下单金额来自 `ctx.investment_amount` 的拆分。
|
||
- 是否使用 `basket.open_child_order(..., notional=...)` 表示计价金额。
|
||
- 是否在止盈/止损后重置状态并进入冷却。
|
||
- 是否能解释每一个状态变量的含义。
|
||
|
||
## 17. 实盘前检查清单
|
||
|
||
回测通过不等于可以直接实盘。实盘前还要检查：
|
||
|
||
- 现货策略是否只做多。
|
||
- 合约策略的杠杆是否符合交易所限制。
|
||
- 投入金额是否足够覆盖最大计划层数。
|
||
- 最大单数是否会超过交易所限频或最小下单金额限制。
|
||
- 硬止损是否存在，且不是过大到没有意义。
|
||
- 是否设置了账户级风控、通知和异常停机策略。
|
||
- 是否用小金额或模拟盘跑过至少一个完整开仓、加仓、平仓周期。
|
||
|
||
## 18. AI 助手提示词建议
|
||
|
||
让 AI 生成复杂脚本时，提示词要明确边界。推荐这样写：
|
||
|
||
```text
|
||
写一个 QuantDinger 脚本代码：
|
||
1. 使用 on_init/on_bar。
|
||
2. 运行面板负责标的、现货/合约、方向、投入金额和杠杆，代码里不要写成 ctx.param。
|
||
3. 使用 ctx.basket(side).open_child_order(..., notional=...) 下单。
|
||
4. 投入金额按 5 层、每层 3 单、马丁倍数 1.8 自动拆分。
|
||
5. 每个子单之间有价格间距，均价止盈，硬止损，同 K 线防重复。
|
||
6. 不要使用 getattr、文件、网络、数据库、导入危险模块。
|
||
```
|
||
|
||
如果要改现有模板，建议说：
|
||
|
||
```text
|
||
基于当前模板，只调整参数和风控，不要改变运行面板边界。
|
||
把止盈改为 0.8%，层间距改成逐层扩大，最大亏损 12% 硬止损。
|
||
```
|
||
|
||
## 19. 最小骨架
|
||
|
||
```python
|
||
"""
|
||
My Script Strategy
|
||
"""
|
||
|
||
def on_init(ctx):
|
||
ctx.lookback = ctx.param('lookback', 20)
|
||
ctx.take_profit_pct = ctx.param('take_profit_pct', 0.01)
|
||
|
||
def _side(ctx):
|
||
try:
|
||
direction = str(ctx.direction)
|
||
except Exception:
|
||
direction = 'long'
|
||
return 'short' if direction.lower() == 'short' else 'long'
|
||
|
||
def on_bar(ctx, bar):
|
||
bars = ctx.bars(ctx.lookback + 1)
|
||
if len(bars) < ctx.lookback + 1:
|
||
return
|
||
|
||
side = _side(ctx)
|
||
price = float(bar['close'])
|
||
basket = ctx.basket(side)
|
||
|
||
# Add entry, state, risk, and exit logic here.
|
||
```
|