蓝图节点详细文档

风险提示：蓝图节点可以生成自动交易动作，但节点组合本身不保证盈利。实盘前必须先回测，再用模拟交易或小资金验证。交易所 API 不要开启提币权限。

1. 蓝图的基本工作方式

蓝图可以理解为“事件驱动的策略流程图”。一个可执行蓝图通常由以下几类节点组成：

事件节点：决定策略什么时候运行，例如启动时、每根 K 线、逐笔 Tick、定时器、订单回执。
行情节点：读取当前挂载交易对、K 线、最新价、盘口、账户和持仓。
指标节点：基于 K 线或数值序列计算技术指标。
信号/逻辑节点：把指标和价格转换成布尔条件，决定是否开仓、平仓或绘图。
风控节点：为订单增加限频、熔断、最小数量、最大仓位、冷却、止盈止损等约束。
下单/函数节点：生成开仓、平仓、撤单、退出规则等交易动作。
状态节点：保存变量、维护计数、持久化状态、判断信号变化。
工具节点：做表达式、类型转换、加减乘除、归一化、精度处理等中间计算。
图表节点：把指标线、水平线、背景、标记、表格和订单标记显示到图表上。

一个最常见的策略链路如下：

OnBar / OnBarClose
  -> Symbol Selector
  -> Get OHLCV
  -> 指标节点
  -> 信号/逻辑节点
  -> 风控节点
  -> strategy.entry / strategy.close / 下单节点

如果执行周期是 15m，但行情判断看 1h，通常这样配置：

event.on_bar(timeframe=15m)
  -> market.symbol_selector
  -> market.get_ohlcv(timeframe=1h, limit=200)
  -> 1h 指标和过滤条件
  -> 15m 执行链路

2. 端口、连线和参数

每个节点由 输入端口、输出端口 和参数组成。

概念	说明
输入端口	接收事件或数据。没有连接时，部分节点会使用参数默认值。
输出端口	输出事件、数值、布尔、交易对、订单意图、图表引用等。
参数	在右侧属性面板配置。标记为“暴露”的参数会出现在策略参数面板，挂载时可调整。
`multi` 输入	允许同一个输入口接多条连线，常见于 `riskInputs`、订单 `plot`、`chart.plotchar.shape`。

流类型

流类型	用途	常见场景
`event`	控制执行顺序和副作用触发	`eventIn` -> 下单、写状态、绘制图表
`data`	传递数据值	价格、指标、布尔条件、交易对、风控意图
`ui`	图表/界面视觉链路的历史类型	当前图表节点多作为末端视觉节点使用

值类型

类型	含义	常见来源
`any`	任意类型	表达式输入、动态标签、兼容端口
`voidType`	无数据事件	事件节点的触发输出
`number` / `integer` / `doubleType`	数值、整数、双精度	指标、价格计算、计数器
`boolType`	布尔条件	Compare、AND/OR、信号节点
`text`	文本	标签、注释、状态文本
`symbol`	交易对	Symbol Selector
`timeframe`	周期	周期过滤
`timestamp`	时间	日期过滤、图表时间区间
`seriesNumber`	数值序列	成交量、时间序列
`ohlcvSeries`	K 线序列	Get OHLCV 的 open/high/low/close
`chartVisualRef` / `chartPlotRef` / `chartHLineRef`	图表对象引用	Plot、HLine、Fill、订单标记模板
`price`	价格	Last Price、Bid/Ask、Mark Price
`orderIntent`	风控或下单意图	风控节点输出、下单节点输入
`orderUpdate`	订单回执	订单事件节点
`position` / `balance` / `account`	仓位、余额、账户快照	账户/持仓行情节点

编译和连接规则

蓝图必须至少有一个事件源节点，否则不会运行。
数据流必须是无环图；如果数据节点互相形成闭环，编译会失败。
事件流出现循环时必须放入 logic.gate 做节流，否则会造成高频重复触发。
数据端口类型要匹配。类型不匹配时，用 tool.cast_number、tool.cast_integer、tool.cast_bool 显式转换。
普通输入端口只允许一条连线；支持多连线的输入口会在节点定义里标记。
下单节点必须接 eventIn，否则事件不触发时不会执行。
有下单节点时建议至少连接一个风控节点到 riskInputs。编译器会提示“存在下单节点，但未配置任何风控节点”或“下单节点未连接任何风控输入”。
market.symbol_selector 输出的是当前回测、挂载或调试上下文里的交易对，适合做通用蓝图模板，不建议在模板里写死交易对。
market.get_ohlcv 的 timeframe=runtime 表示跟随运行周期；如果要用大周期过滤，应显式选择 1h、15m 等周期。

3. 高频策略搭建建议

高频或偏高频策略要优先控制触发频率和订单频率：

优先使用 event.on_bar、event.on_bar_close 做主触发；只有明确需要逐笔响应时才使用 event.on_tick。
如果使用 event.on_tick 或较短 event.on_timer，下游必须加 logic.gate、risk.max_order_rate 和 logic.once_per_bar 中的一个或多个。
同一根 K 线不希望重复开仓时，使用 logic.once_per_bar 或 state.last_signal。
避免在 Tick 级别反复拉很大的 K 线数量。market.get_ohlcv.limit 按指标需要设置，常见 100-300 即可。
执行周期和判断周期可以分离。例如 15m 执行、1h 过滤：事件节点设 15m，行情节点设 1h。
实盘链路中建议固定接入 risk.kill_switch、risk.order_validation、risk.max_position_size 和 risk.max_order_rate。
亏损后暂停类策略建议加入 risk.cooldown_after_loss 或 risk.daily_consecutive_loss_cooldown。

4. 事件节点

事件节点是蓝图执行入口。没有事件节点，行情、指标、逻辑和订单不会形成运行帧。

节点 ID	名称	主要输入	主要输出	参数	用途和注意事项
`event.on_start`	OnStart	无	`out` 触发	无	策略启动时触发一次，适合初始化变量、读取初始快照。
`event.on_stop`	OnStop	`enabled`	`out` 触发	无	策略停止时触发一次，可用于收尾逻辑；未连接 `enabled` 时按默认启用处理。
`event.on_bar`	OnBar	`timeframe`	`out` 触发	`timeframe` 默认 `1m`，可选 `1s/1m/5m/15m/1h`	按指定周期触发，适合作为默认策略入口。
`event.on_bar_open`	OnBarOpen	`timeframe`	`out` 触发	同 OnBar	每根 K 线开盘时触发，适合开盘执行。
`event.on_bar_close`	OnBarClose	`timeframe`	`out` 触发	同 OnBar	每根 K 线收盘时触发，适合用已确认 K 线减少重绘。
`event.on_tick`	OnTick	无	`out` 触发	无	逐笔行情触发，频率最高；必须搭配限频和风控。
`event.on_timer`	OnTimer	`enabled`、`intervalSec`	`out` 触发	`intervalSec=60`，范围 1-86400 秒	固定间隔触发；输入口可覆盖参数。
`event.on_order_update`	OnOrderUpdate	`symbol`、`side`、`status` 过滤	`event`、`order`	无	订单/成交回执触发，适合成交后更新状态或补充止盈止损。
`event.on_trade_transaction`	OnTradeTransaction	`symbol`、`side`、`status` 过滤	`event`、`order`	无	交易事务更新触发，适合更细粒度的订单状态处理。
`event.on_position_update`	OnPositionUpdate	`symbol`、`side` 过滤	`event`、`position`	无	持仓变化触发，适合仓位同步、风险状态更新。

5. 行情节点

行情节点负责从当前运行上下文读取交易对、K 线、价格、账户和持仓数据。

节点 ID	名称	主要输入	主要输出	参数	用途和注意事项
`market.symbol_selector`	Symbol Selector	`eventIn`	`eventOut`、`symbol`	无	输出当前挂载或回测交易对，不在蓝图中写死 symbol。
`market.get_ohlcv`	Get OHLCV	`symbol`	`series/open/high/low/close/hlc3/ohlc4/volume/time`	`limit=200`，`timeframe=runtime/1m/5m/15m/1h`	获取最近 N 根 K 线。指标一般接 `series` 或 `close`，波动类可接 high/low/close。
`market.last_price`	Get Last Price	`symbol`	`price`	无	读取最新成交价，适合实时条件或图表价位。
`market.bid_ask`	Get Bid/Ask	`symbol`	`bid`、`ask`	无	读取买一卖一，适合估算滑点或主动/被动方向。
`market.mark_price`	Get Mark Price	`symbol`	`price`	无	读取永续合约标记价格，适合合约风控和强平相关判断。
`market.account_snapshot`	Get Balance/Position	`eventIn`	`eventOut`、`balance`、`position`	无	读取账户余额和持仓快照；接事件输入可控制读取时机。
`market.position_state`	Get Position State	`symbol`	`qty/absQty/side/entryPrice/openTimeMs/unrealizedPnl/isFlat`	无	输出当前交易对仓位状态，常用于“空仓才开仓”“有仓才平仓”。

6. 指标节点

指标节点多数接收 ohlcvSeries，输出当前 bar 的数值。需要多周期过滤时，把 Get OHLCV.timeframe 设置为目标周期。

节点 ID	名称	主要输入	主要输出	关键参数	适用场景
`indicator.sma`	SMA	`series`	`value`	`period=20`	简单均线，趋势方向、均值回归基准。
`indicator.ema`	EMA	`series`	`value`	`period=21`	指数均线，响应速度快于 SMA。
`indicator.kama`	KAMA	`series`	`value/previous/slope/trend`	`erPeriod=10`、`fastPeriod=2`、`slowPeriod=30`、`slopeLookback=5`	自适应均线，适合过滤震荡噪声。
`indicator.rsi`	RSI	`series` 或 high/low/close	`value`	`period=14`	超买超卖、动量背离、回调确认。
`indicator.atr`	ATR	`series` 或 high/low/close	`value`	`period=14`	波动率、止损距离、过滤低波动行情。
`indicator.atr_median`	ATR Median	`high/low/close`	`atr/median`	`atrPeriod=14`、`medianPeriod=50`	判断当前波动是否高于常态。
`indicator.bb`	Bollinger Bands	`series`	`upper/middle/lower`	`period=20`	布林带突破、回归、带宽过滤。
`indicator.macd`	MACD	`series`	`macd/signal/hist`	`fastPeriod=12`、`slowPeriod=26`、`signalPeriod=9`	趋势动量和零轴过滤。
`indicator.donchian`	Donchian	`series`	`upper/middle/lower`	`period=20`	区间突破、海龟类策略。
`indicator.candle_streak`	Candle Streak	`open/high/low/close`	`bullStreak/bearStreak/bullMoveAtr/bearMoveAtr/bodyAtr/direction`	`atrPeriod=14`、`minBodyPct=0.00005`	连续阳线/阴线和实体强度过滤，防追涨杀跌。
`indicator.adx`	ADX	`series` 或 high/low/close	`value`	`period=14`	趋势强度过滤，常用阈值 20/25。
`indicator.chop`	CHOP	`series` 或 high/low/close	`value`	`period=14`	识别趋势/震荡，值高偏震荡，值低偏趋势。
`indicator.vwap`	VWAP	`series`	`value`	`period=20`	成交量加权均价，适合日内价格偏离判断。
`indicator.stoch`	Stoch	`series`	`k/d`	`period=14`、`smoothK=3`、`smoothD=3`	随机指标，震荡市场入场/离场。
`indicator.stoch_rsi`	Stochastic RSI	`series`	`k/d`	`period=14`、`smoothK=3`、`smoothD=3`	对 RSI 再随机化，信号更敏感。
`indicator.highest`	Highest N	`series`	`value`	`period=20`	最近 N 根最高值，突破阈值。
`indicator.lowest`	Lowest N	`series`	`value`	`period=20`	最近 N 根最低值，跌破阈值。
`indicator.ichimoku`	Ichimoku	`series`	`conversion/base/spanA/spanB/lagging`	`conversionPeriod=9`、`basePeriod=26`、`spanBPeriod=52`、`displacement=26`	一目均衡表，多维趋势结构。
`indicator.supertrend`	Supertrend	`series`	`value/trend`	`period=10`、`multiplier=3.0`	趋势跟踪和止损参考。
`indicator.fibonacci`	Fibonacci Retracement	`series`	`level0/236/382/500/618/786/100`	`period=100`	近期区间斐波那契回撤位。
`indicator.cci`	CCI	`series`	`value`	`period=20`	顺势指标，趋势和极值判断。
`indicator.williams_r`	Williams %R	`series`	`value`	`period=14`	超买超卖振荡器。
`indicator.parabolic_sar`	Parabolic SAR	`series`	`value/trend`	`afStart=0.02`、`afStep=0.02`、`afMax=0.2`	趋势反转和移动止损。
`indicator.obv`	OBV	`series`	`value`	无	能量潮，价格与成交量方向确认。
`indicator.mfi`	MFI	`series`	`value`	`period=14`	资金流量指标，带成交量的超买超卖。
`indicator.volume`	Volume	`seriesNumber`	`value/average`	`period=20`	当前量与均量对比，可过滤假突破。
`indicator.keltner`	Keltner Channels	`series`	`upper/middle/lower`	`emaPeriod=20`、`atrPeriod=10`、`multiplier=2.0`	基于 ATR 的通道突破和回调。
`indicator.roc`	ROC	`series`	`value`	`period=12`	变动率，判断价格速度。
`indicator.momentum`	Momentum	`series`	`value`	`period=10`	动量振荡器。
`indicator.smoothed_momentum`	Smoothed Momentum	`series`	`momentum/value/bull/bear`	`period=10`、`smooth=3`	平滑动量，并直接输出多空布尔。
`indicator.wavetrend`	WaveTrend	`series`	`wt1/wt2/bull/bear/crossOver/crossUnder`	`channelLength=9`、`averageLength=12`、`maLength=3`、`overbought=60`、`oversold=-60`	振荡器和交叉信号，适合回调确认。
`indicator.aroon`	Aroon	`series`	`up/down/oscillator`	`period=25`	识别新高/新低驱动的趋势强弱。
`indicator.cmf`	CMF	`series`	`value`	`period=20`	Chaikin Money Flow，资金流入/流出过滤。
`indicator.pivot_points`	Pivot Points	`series`	`pp/r1/r2/r3/s1/s2/s3`	`period=20`	支撑阻力、突破和回撤目标。

7. 信号和逻辑节点

信号节点通常输出布尔值，逻辑节点可以组合条件或控制事件流。

节点 ID	名称	主要输入	主要输出	参数	用途和注意事项
`logic.compare`	Compare	`left/right`	`result`	`operator` 可选 `> = true` 时把事件放行，避免条件持续为 true 时重复下单。
`logic.if_else`	If-Else	`eventIn/condition`	`trueOut/falseOut`	无	按条件拆分事件流。
`bool.expression`	Bool Expression	动态变量输入	`result`	`expression`、`variableCount`、变量别名	用表达式替代多级 Compare/AND/OR/NOT，支持 `and/or/not`、`&&/
`logic.bool_expr`	Bool Expr	`a/b/c/d`	`result`	`expression`	旧版布尔表达式，变量固定为 a-d。
`logic.ternary`	Select / Ternary	动态变量输入	`result`	`expression`、变量别名	三元表达式，例如 `a ? b : c`，适合颜色、数值、文本二选一。
`logic.select_value`	Select Value	`condition/trueValue/falseValue`	`result`	无	按布尔条件在两个值中选择一个。
`logic.gate`	Gate	`eventIn`	`eventOut`	`cooldownSec=10`	事件流限流；高频、Tick、循环事件必须重点使用。
`logic.once_per_bar`	Once Per Bar	`eventIn`	`eventOut`	无	同一根 K 线只放行一次事件。

表达式节点说明：

bool.expression、math.expression、tool.number_expr 支持动态变量数量，variableCount 范围为 1-32。
变量默认是 a/b/c...，可以用变量别名改成 close、emaFast、atr 等更易读的名字。
布尔表达式适合写 `close > ema and rsi 下单节点 riskInputs


## 9. 函数节点和下单节点

函数节点是 Pine Script 风格的交易函数，会输出 `eventOut`、`triggered` 和 `label`，适合在策略链路中继续串联。下单节点更像终端动作节点，通常作为交易动作的末端。

### 函数节点

| 节点 ID                 | 名称                | 主要输入                                | 主要输出                     | 关键参数                                                                                                      | 用途和注意事项                                                                      |
| ----------------------- | ------------------- | --------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `strategy.entry`      | strategy.entry      | `eventIn/when/symbol/riskInputs/plot` | `eventOut/triggered/label` | `enabled`、`entryId`、`direction`、`orderType`、`qtyMode`、`qty`、`limitOffsetPct`、`comment` | 满足 `when` 时生成多头或空头入场意图。`entryId` 是策略标签，不是交易所订单 ID。 |
| `strategy.cancel`     | strategy.cancel     | `eventIn/when/riskInputs/plot`        | `eventOut/triggered/label` | `enabled`、`orderId`、`comment`                                                                         | 撤销指定交易所委托；live 撤单通常需要真实 `orderId`。                             |
| `strategy.close`      | strategy.close      | `eventIn/when/symbol/riskInputs/plot` | `eventOut/triggered/label` | `enabled`、`entryId`、`orderType`、`qtyMode`、`qty`、`limitOffsetPct`、`comment`                | 平当前交易对仓位，可按全部、数量或百分比平仓。                                      |
| `strategy.cancel_all` | strategy.cancel_all | `eventIn/when/riskInputs/plot`        | `eventOut/triggered/label` | `enabled`、`comment`                                                                                      | 满足条件时生成全部撤单意图。                                                        |
| `strategy.close_all`  | strategy.close_all  | `eventIn/when/symbol/riskInputs/plot` | `eventOut/triggered/label` | `enabled`、`orderType`、`limitOffsetPct`、`comment`                                                   | 满足条件时对当前交易对执行全平。                                                    |
| `strategy.exit`       | strategy.exit       | `eventIn/when/symbol/riskInputs/plot` | `eventOut/triggered/label` | `exitId`、`fromEntry`、`stop`、`limit`、`profit`、`loss`、`trailPoints`、`trailOffset`        | Pine 风格退出规则，可配置止盈、止损、追踪止损。                                     |

### 下单节点

| 节点 ID                  | 名称                 | 主要输入                                                        | 输出 | 关键参数                                                                                          | 用途和注意事项                                                               |
| ------------------------ | -------------------- | --------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `strategy.entry_block` | Strategy Entry Block | `eventIn/longCondition/shortCondition/symbol/riskInputs/plot` | 无   | `orderType`、`qtyMode`、`qty`、`preferLongWhenBoth`、`longLabel`、`shortLabel`        | 策略级入场块，同时接多空条件；两边同时触发时可配置优先多头。                 |
| `strategy.exit_block`  | Strategy Exit Block  | `eventIn/longCondition/shortCondition/symbol/riskInputs/plot` | 无   | `orderType`、`qtyMode`、`qty`、`longLabel`、`shortLabel`                                | 策略级出场块，直接根据多/空退出条件生成平仓意图。                            |
| `order.place_market`   | Place Market Order   | `eventIn/sideInput/riskInputs/plot`                           | 无   | `side=buy/sell/auto`、`qtyMode=fixed/percent/quantity`、`qty`                               | 生成市价单意图。`qty` 当前按 USDT 金额解释，`percent` 按可用资金百分比。 |
| `order.place_limit`    | Place Limit Order    | `eventIn/sideInput/riskInputs/plot`                           | 无   | `side`、`qtyMode`、`qty`、`priceOffsetPct`                                                | 生成限价单意图；BUY 向下偏移，SELL 向上偏移。                                |
| `order.cancel_order`   | Cancel Order         | `eventIn/riskInputs/plot`                                     | 无   | `orderId`                                                                                       | 撤销指定交易所委托。                                                         |
| `order.close_position` | Close Position       | `eventIn/riskInputs/plot`                                     | 无   | `qtyMode=all/quantity/percent`、`qty`、`orderType`、`priceOffsetPct`、`reduceOnly=true` | 平当前仓位；默认仅减仓。                                                     |
| `order.set_tpsl`       | Set TP/SL            | `eventIn/riskInputs/plot`                                     | 无   | `stopLossPct=1.0`、`takeProfitPct=2.0`                                                        | 为仓位或订单设置止盈止损意图。                                               |

下单链路示例：

OnBarClose(15m).out

-> Edge Trigger.eventIn

Compare.result

-> Edge Trigger.condition

Edge Trigger.eventOut

-> strategy.entry.eventIn

Symbol Selector.symbol

-> strategy.entry.symbol

risk.max_order_rate.intent

risk.max_position_size.intent

risk.stop_take_rule.intent

-> strategy.entry.riskInputs


## 10. 状态节点

状态节点用于记忆当前运行过程中的变量和信号。需要跨重启保留时，用 `persistent_*`。

| 节点 ID                  | 名称              | 主要输入                | 主要输出                           | 参数                              | 用途和注意事项                                   |
| ------------------------ | ----------------- | ----------------------- | ---------------------------------- | --------------------------------- | ------------------------------------------------ |
| `state.var_set`        | Var Set           | `value`               | `value`                          | `key=signal`                    | 设置当前策略变量，生命周期通常跟随运行实例。     |
| `state.var_get`        | Var Get           | 无                      | `value`                          | `key=signal`                    | 读取当前策略变量。                               |
| `state.counter`        | Counter           | `eventIn`             | `value/eventOut`                 | `initialValue=0`、`step=1`    | 每次事件触发时计数，适合统计触发次数。           |
| `state.persistent_set` | Persistent KV Set | `eventIn/value`       | `value/eventOut`                 | `key=last_signal`               | 写入跨重启持久化变量。                           |
| `state.persistent_get` | Persistent KV Get | 无                      | `value`                          | `key=last_signal`、`fallback` | 读取跨重启变量；不存在时返回默认值。             |
| `state.rolling_window` | Rolling Window    | `eventIn/value`       | `values/latest/count/eventOut`   | `size=20`                       | 维护最近 N 个数值窗口。                          |
| `state.last_signal`    | Last Signal       | `eventIn/signal`      | `signal/changed/eventOut`        | `key=signal`                    | 保存上次信号，并输出是否变化；适合避免重复下单。 |
| `state.overbought`     | Overbought State  | `value/threshold`     | `result`                         | `threshold=70`                  | 指标值大于等于阈值。                             |
| `state.oversold`       | Oversold State    | `value/threshold`     | `result`                         | `threshold=30`                  | 指标值小于等于阈值。                             |
| `state.midline`        | Midline State     | `value/threshold`     | `result`                         | `threshold=50`                  | 指标值大于等于中线阈值。                         |
| `strategy.trend_state` | Trend State       | `changeUp/changeDown` | `state/stateCode/isLong/isShort` | `longCode=B`、`shortCode=S`   | 也属于状态类节点，用于根据切换信号维护趋势状态。 |

## 11. 工具节点

工具节点负责中间计算和格式处理。复杂计算优先用表达式节点，简单计算可用加减乘除节点。

| 节点 ID               | 名称            | 主要输入     | 主要输出      | 参数                                        | 用途和注意事项                                |
| --------------------- | --------------- | ------------ | ------------- | ------------------------------------------- | --------------------------------------------- |
| `math.expression`   | Math Expression | 动态变量输入 | `value`     | `expression`、`variableCount`、变量别名 | 数值表达式，支持 `+ - * / %` 和括号。       |
| `tool.number_expr`  | Number Expr     | 动态变量输入 | `value`     | `expression`、`variableCount`、变量别名 | 旧版数值表达式，适合替代 Add/Sub/Mul/Div 链。 |
| `tool.cast_number`  | Cast -> Number  | `value`    | `value`     | 无                                          | 显式转换为数值。                              |
| `tool.cast_integer` | Cast -> Int     | `value`    | `value`     | 无                                          | 显式转换为整数。                              |
| `tool.cast_bool`    | Cast -> Bool    | `value`    | `value`     | 无                                          | 显式转换为布尔。                              |
| `tool.clamp`        | Clamp           | `value`    | `value`     | `min=0`、`max=100`                      | 把数值限制在区间内。                          |
| `tool.normalize`    | Normalize       | `value`    | `value`     | `min=0`、`max=100`                      | 把数值归一化到 0-1。                          |
| `tool.add`          | Add             | `a/b`      | `value`     | 无                                          | 加法。                                        |
| `tool.sub`          | Sub             | `a/b`      | `value`     | 无                                          | 减法。                                        |
| `tool.mul`          | Mul             | `a/b`      | `value`     | 无                                          | 乘法。                                        |
| `tool.div`          | Div             | `a/b`      | `value`     | 无                                          | 除法。                                        |
| `tool.map_symbol`   | Map Symbol      | `symbol`   | `symbol`    | `exchange=binance/okx/bybit`              | 把交易对映射到目标交易所格式。                |
| `tool.tag`          | JSON/Tag        | `value`    | `value/tag` | `tag`                                     | 给数据附加文本标签或 JSON 片段。              |
| `tool.round`        | Round/Precision | `value`    | `value`     | `precision=2`                             | 数值精度处理，适合价格、数量和图表展示。      |

## 12. 图表节点

图表节点用于可视化策略。部分节点接 `eventIn` 控制当前 bar 是否绘制，部分节点是纯数据驱动。图表节点通常不参与下单决策，建议作为策略链路的旁路输出。

### 通用图表参数

| 参数            | 说明                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------- |
| `pane`        | 显示区域：`main` 主图、`chart` 图表层、`volume` 成交量、`indicator:0/1` 指标面板。                    |
| `visible`     | 是否显示。                                                                                                    |
| `zIndex`      | 层级，范围 -200 到 200，越大越靠上。                                                                          |
| `layer`       | 渲染层：`background`、`underlay`、`overlay`、`annotation`。                                           |
| `style`       | Plot 样式：`line`、`linebr`、`stepline`、`area`、`histogram`、`columns`、`circles`、`cross`。 |
| `strokeStyle` | 线型：`solid`、`dashed`、`dotted`。                                                                     |

### 图表节点索引

| 节点 ID                      | 名称            | 主要输入                                                | 主要输出     | 关键参数                                                                                     | 用途和注意事项                                               |
| ---------------------------- | --------------- | ------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `chart.color`              | Color           | 无                                                      | `color`    | `color=#FF38BDF8`                                                                          | 输出颜色文本，可复用到多个图表节点。                         |
| `chart.background`         | Background      | `eventIn/color/startValue/endValue/startTime/endTime` | 无           | `color`、`rangeMode=bars/time`、`startBarsAgo/endBarsAgo`                              | 绘制背景区域，可按 K 线区间或时间区间控制。                  |
| `chart.bar_color`          | Bar Color       | `eventIn`                                             | 无           | `colorMode=single/trend/theme`、body/wick/border/up/down 颜色                              | 修改 K 线颜色，适合趋势状态可视化。                          |
| `chart.plots`              | Plot            | `color/value`                                         | `plotRef`  | `style`、`color`、`lineWidth`、`histBase`、`offset`、`showLast`、`trackPrice`  | 绘制指标线、柱状图、面积等，并输出 Plot 引用。               |
| `strategy.plot_trend_line` | Plot Trend Line | `value/trend`                                         | `plotRef`  | `style`、`upColor`、`downColor`、`neutralColor`、`lineWidth`                       | 按趋势状态自动切换颜色的指标线。                             |
| `chart.fill`               | Fill            | `color/plot1/plot2`                                   | 无           | `color`、`showLast`、`fillGaps`                                                        | 在两条 Plot/HLine 引用之间填充区域。两个引用必须在同一面板。 |
| `chart.hline`              | HLine           | `price/color/startValue/endValue/startTime/endTime`   | `hlineRef` | `price`、`title`、`color`、`linestyle`、`linewidth`、`rangeMode`                 | 绘制水平线，并可作为 Fill 引用。                             |
| `chart.levels`             | Levels          | `value/color`                                         | 无           | `value`、`color`、`lineWidth`、`strokeStyle`、`label`、区间参数                    | 绘制价位线，适合支撑阻力、止盈止损参考。                     |
| `chart.line`               | Line            | `startValue/endValue`                                 | 无           | `lineColor`、`lineWidth`、`strokeStyle`、`leftBarsAgo/rightBarsAgo`                  | 绘制从历史 bar 到当前或未来偏移的线段。                      |
| `chart.box`                | Box             | `top/bottom/text`                                     | 无           | `fillColor`、`borderColor`、`textColor`、`borderWidth`、`leftBarsAgo/rightBarsAgo` | 绘制价格区间盒，适合震荡区间、供需区。                       |
| `chart.tables`             | Tables          | `eventIn` 和动态 `value1...valueN`                  | 无           | `title`、`placement`、`itemCount=1-12`、`labelPosition`、`columnCount`、颜色和对齐 | 显示图表看板。`itemCount` 会动态展开输入口和标签参数。     |
| `chart.text`               | Text            | `value`                                               | `text`     | `color`、`textFallback`、`size`、`barsAgo`                                           | 输出文本。连接值时按“文本 + 值”拼接。                      |
| `chart.shapes`             | Shapes          | `value/series/text`                                   | `shape`    | `shape`、`location=abovebar/belowbar/absolute`、颜色、尺寸、offset                       | 绘制形状标记；`series` 为 false 时通常不绘制。             |
| `chart.plotchar`           | PlotChar        | `series/value/text/shape`                             | 无           | `location`、`value`、`color`、`offset`、`yOffset`                                  | 按条件绘制文本或形状标记；`shape` 支持多连接。             |
| `chart.entry_plot`         | Entry Plot      | 无                                                      | `plotRef`  | `shape=arrow_right_sharp`、`size`、`textSize`                                          | 输出开仓图表模板，真正绘制发生在订单成交时。                 |
| `chart.exit_plot`          | Exit Plot       | 无                                                      | `plotRef`  | `shape=arrow_left_sharp`、`size`、`textSize`                                           | 输出平仓图表模板，真正绘制发生在订单成交时。                 |

常见图表用法：

EMA.value -> chart.plots.value

RSI.value -> chart.tables.value1

Entry Plot.plotRef -> strategy.entry.plot

Exit Plot.plotRef -> strategy.close.plot


## 13. 常见策略模板

### 15m 执行，1h 趋势过滤

event.on_bar_close(timeframe=15m)

-> market.symbol_selector.eventIn

market.symbol_selector.symbol

-> market.get_ohlcv.symbol

market.get_ohlcv(timeframe=1h).close

-> indicator.ema(period=50)

market.get_ohlcv(timeframe=1h).close

-> indicator.ema(period=200)

EMA50.value > EMA200.value

-> logic.compare.result

logic.compare.result

-> strategy.entry.when

event.on_bar_close.out

-> logic.edge_trigger.eventIn

logic.compare.result

-> logic.edge_trigger.condition

logic.edge_trigger.eventOut

-> strategy.entry.eventIn


### 突破入场，加 ATR 风控

Get OHLCV.close -> indicator.donchian.series

Last Price.price -> signal.breakout.value

Donchian.upper -> signal.breakout.level

Get OHLCV -> indicator.atr

ATR.value -> strategy.atr_stop_block.atr

risk.max_order_rate.intent

risk.order_validation.intent

strategy.atr_stop_block.intent

-> strategy.entry.riskInputs


### 防止同一信号重复下单

Compare.result -> state.last_signal.signal

OnBar.out -> state.last_signal.eventIn

state.last_signal.changed -> strategy.entry.when

state.last_signal.eventOut -> strategy.entry.eventIn


## 14. 排错指南

| 问题            | 优先检查                                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------------------------- |
| 蓝图无法编译    | 是否有事件源；端口类型是否匹配；数据流是否成环；输入端口是否重复连线。                                        |
| 策略不触发      | 事件周期是否正确；`when` 是否为 true；`Edge Trigger` 是否已经触发过；日期过滤是否过期。                   |
| 下单节点不执行  | 是否接了 `eventIn`；是否连接 `riskInputs`；风控是否拒绝；运行模式是否允许交易。                           |
| 高频重复下单    | 增加 `logic.gate`、`logic.once_per_bar`、`state.last_signal`、`risk.max_order_rate`。                 |
| 1h 过滤没有生效 | 检查 `market.get_ohlcv.timeframe` 是否显式设置为 `1h`，不要误用 `runtime`。                             |
| 指标为空或异常  | `limit` 是否足够覆盖指标周期；输入是否接了正确序列；回测区间是否有足够历史 K 线。                           |
| 图表不显示      | 图表节点是否有必要输入；`visible` 是否开启；`pane/layer/zIndex` 是否合理；Fill 的两个引用是否在同一面板。 |
| 类型不匹配      | 插入 `tool.cast_number`、`tool.cast_integer` 或 `tool.cast_bool`。                                      |

## 15. 完整节点 ID 索引

以下索引用于快速核对蓝图文件中的 `schemaId`。

| 分类 | 节点 ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 事件 | `event.on_start`, `event.on_stop`, `event.on_bar`, `event.on_bar_open`, `event.on_bar_close`, `event.on_tick`, `event.on_timer`, `event.on_order_update`, `event.on_trade_transaction`, `event.on_position_update`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 行情 | `market.symbol_selector`, `market.get_ohlcv`, `market.last_price`, `market.bid_ask`, `market.mark_price`, `market.account_snapshot`, `market.position_state`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 指标 | `indicator.sma`, `indicator.ema`, `indicator.kama`, `indicator.rsi`, `indicator.atr`, `indicator.atr_median`, `indicator.bb`, `indicator.macd`, `indicator.donchian`, `indicator.candle_streak`, `indicator.adx`, `indicator.chop`, `indicator.vwap`, `indicator.stoch`, `indicator.stoch_rsi`, `indicator.highest`, `indicator.lowest`, `indicator.ichimoku`, `indicator.supertrend`, `indicator.fibonacci`, `indicator.cci`, `indicator.williams_r`, `indicator.parabolic_sar`, `indicator.obv`, `indicator.mfi`, `indicator.volume`, `indicator.keltner`, `indicator.roc`, `indicator.momentum`, `indicator.smoothed_momentum`, `indicator.wavetrend`, `indicator.aroon`, `indicator.cmf`, `indicator.pivot_points` |
| 信号 | `logic.cross_over`, `logic.cross_under`, `signal.enter_range`, `signal.leave_range`, `signal.breakout`, `signal.breakdown`, `strategy.date_range_filter`, `strategy.cross_signal`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 逻辑 | `logic.compare`, `logic.boolean_and`, `logic.boolean_or`, `logic.boolean_not`, `logic.edge_trigger`, `logic.if_else`, `bool.expression`, `logic.bool_expr`, `logic.ternary`, `logic.select_value`, `logic.gate`, `logic.once_per_bar`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 风控 | `risk.max_order_rate`, `risk.kill_switch`, `risk.order_validation`, `risk.max_position_size`, `risk.cooldown_after_loss`, `risk.daily_consecutive_loss_cooldown`, `risk.stop_take_rule`, `strategy.atr_stop_block`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 函数 | `strategy.entry`, `strategy.cancel`, `strategy.close`, `strategy.cancel_all`, `strategy.close_all`, `strategy.exit`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 下单 | `strategy.entry_block`, `strategy.exit_block`, `order.place_market`, `order.place_limit`, `order.cancel_order`, `order.close_position`, `order.set_tpsl`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 状态 | `strategy.trend_state`, `state.var_set`, `state.var_get`, `state.counter`, `state.persistent_set`, `state.persistent_get`, `state.rolling_window`, `state.last_signal`, `state.overbought`, `state.oversold`, `state.midline`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 工具 | `math.expression`, `tool.number_expr`, `tool.cast_number`, `tool.cast_integer`, `tool.cast_bool`, `tool.clamp`, `tool.normalize`, `tool.add`, `tool.sub`, `tool.mul`, `tool.div`, `tool.map_symbol`, `tool.tag`, `tool.round`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 图表 | `chart.color`, `chart.background`, `chart.bar_color`, `chart.plots`, `strategy.plot_trend_line`, `chart.fill`, `chart.hline`, `chart.levels`, `chart.line`, `chart.box`, `chart.tables`, `chart.text`, `chart.shapes`, `chart.plotchar`, `chart.entry_plot`, `chart.exit_plot                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

蓝图节点详细文档

1. 蓝图的基本工作方式

2. 端口、连线和参数

流类型

值类型

编译和连接规则

3. 高频策略搭建建议

4. 事件节点

5. 行情节点

6. 指标节点

7. 信号和逻辑节点

相关文档

第一次使用 NavaX 应该从哪里开始？

如何获取 API 交易密钥

扩展市场使用文档