Tectonic Structure Engine

一个为您的 EA、指标或脚本描绘市场结构的 MQL4 库：带 HH、HL、LH、LL、EQH 和 EQL 标签的已确认波段，结构突破 (BOS)，性质转变 (CHoCH)，流动性扫荡，带填充跟踪的订单块和公允价值缺口，以及价格在交易区间中的位置。它只读取已收盘的K线，从不重绘。它不交易、不绘图、不发送警报。您获得编译好的 Tectonic_Structure_Engine.ex4；本页即完整的 API 参考。

快速开始

1. 将 Tectonic_Structure_Engine.ex4 复制到 MQL4/Libraries（文件 > 打开数据文件夹）。
2. 将下面的 #import 块粘贴到您的程序中。
3. 在 OnInit 中：h = TSE_Create("", 0, 3, 1000); 可选 TSE_Configure。
4. 在 OnTick 或 OnCalculate 中调用 TSE_Update(h)。没有新K线时约一微秒内返回 0。
5. 读取 TSE_Trend、TSE_GetEvent、TSE_NearestZone 等；在 OnDeinit 中调用 TSE_Release(h)。
6. 验证：在策略测试器中运行下面的示例（任意品种，M15）。日志列出每个事件；第一次更新会列出全部历史。

导入声明（可直接复制）

#import "Tectonic_Structure_Engine.ex4"
   int    TSE_Create(string symbol, int timeframe, int strength, int history_bars);
   bool   TSE_Configure(int handle, int break_mode, double min_swing_atr, double equal_tol_atr, double fvg_min_atr, int atr_period);
   void   TSE_Release(int handle);
   int    TSE_Update(int handle);
   int    TSE_Trend(int handle);
   int    TSE_SwingCount(int handle);
   bool   TSE_GetSwing(int handle, int index, int &side, double &price, datetime &time, int &label);
   int    TSE_EventCount(int handle);
   bool   TSE_GetEvent(int handle, int index, int &type, double &level, datetime &swing_time, datetime &break_time);
   bool   TSE_GetLevels(int handle, double &swing_high, double &swing_low, bool &high_broken, bool &low_broken);
   double TSE_RangePosition(int handle, double price);
   int    TSE_ZoneCount(int handle);
   bool   TSE_GetZone(int handle, int index, int &kind, int &dir, double &top, double &bottom, datetime &time, int &state, double &fill);
   int    TSE_NearestZone(int handle, int kind, int dir, double price, double &top, double &bottom);
   int    TSE_GetStats(int handle, int &stats[]);
   int    TSE_LastError();
   string TSE_ErrorText(int code);
   string TSE_LabelText(int label);
   string TSE_EventText(int type);
   string TSE_ZoneText(int kind, int dir);
   string TSE_StateText(int state);
#import 

代码

• 波段标签：1 HH，2 LH，3 EQH（高点）；-1 LL，-2 HL，-3 EQL（低点）；0 FIRST（该侧此前没有波段）。
• 事件类型：1 BOS UP，-1 BOS DOWN，2 CHOCH UP，-2 CHOCH DOWN，3 SWEEP HIGH，-3 SWEEP LOW。
• 区域类型 (kind)：1 公允价值缺口，2 订单块。dir：1 看涨（支撑），-1 看跌（阻力）。文本：BULL FVG、BEAR FVG、BULL OB、BEAR OB。
• 区域状态：0 FRESH（未触及），1 TESTED（价格已进入），2 FILLED（FVG 被完全穿越），3 BROKEN（OB 被收盘突破）。
• 错误：0 OK，-1 BAD HANDLE，-2 BAD PARAMETERS，-3 NO HISTORY，-4 NO FREE SLOT，-5 BAD INDEX。对于其他代码，文本函数返回 UNKNOWN。

每根已收盘K线如何被读取

1. 区域：低点进入看涨区域（高点进入看跌区域）时状态设为 TESTED 并提高 fill，即最深穿透占区域高度的百分比。价格到达 FVG 远端边缘时 FVG 变为 FILLED；收盘越过 OB 远端边缘时 OB 变为 BROKEN（OB 仍有效时 fill 可达 100%）。
2. 波段：向前第 strength 根K线，如果其高点高于之前的 strength 根K线、且不低于之后的 strength 根K线，即为波段高点（低点对称）。波段延迟 strength 根K线报告，且永不移动。min_swing_atr 大于 0 时，该高点减去 2 x strength + 1 根K线中的最低低点必须至少为 min_swing_atr x ATR。与同侧前一个波段比较打标签：在 equal_tol_atr x ATR 以内为 EQH 或 EQL，否则为 HH 或 LH、LL 或 HL。最新的波段高点和波段低点就是突破水平。
3. 突破：break_mode 0 需要收盘越过水平，1 只需影线。突破波段高点时，若趋势为 -1 则为 CHOCH UP，否则为 BOS UP；趋势变为 1，该水平作废。低点对称。在收盘模式下，影线越过但收盘回到内部即为 SWEEP，每个水平一次。
4. 订单块：每次 BOS 或 CHoCH 时，取波段与突破之间那段行情极值处、或其前最多 10 根K线内的最后一根反向K线（向上突破时为阴线）；区域为该K线的最高-最低范围。
5. 公允价值缺口：第三根K线的低点高于第一根的高点（看涨），或第三根的高点低于第一根的低点（看跌），高度至少为 fvg_min_atr x ATR。

ATR 为 atr_period 根K线真实波幅的简单平均。

API 参考

TSE_Create

symbol：""或 NULL = 图表品种；品种必须存在。timeframe：0 = 图表周期，否则为 PERIOD_M1 至 PERIOD_MN1。strength：1-50。history_bars：100-20000，在第一次更新时构建。返回句柄 0-31，或返回 -1 并设置 BAD PARAMETERS 或 NO FREE SLOT。默认值：break_mode 0，min_swing_atr 0，equal_tol_atr 0.10，fvg_min_atr 0.25，atr_period 14。

TSE_Configure

break_mode 0-1，min_swing_atr 0-10（0 = 关闭），equal_tol_atr 0-5，fvg_min_atr 0-10，atr_period 1-500。清空句柄；下一次 TSE_Update 重新构建。任何超出范围的值：返回 false，BAD PARAMETERS，不做任何更改。

TSE_Release

释放句柄以便重用。请在 OnDeinit 中调用。

TSE_Update

读取尚未处理的已收盘K线；第一次调用构建 history_bars。返回新事件的数量（TSE_GetEvent 的索引 0 到 n-1），没有新K线时返回 0，或返回 -1：BAD HANDLE，或在已加载K线少于 2 x strength + 4 根时返回 NO HISTORY（在下一个报价时再次调用）。如果最后读取的K线消失（历史重新加载），句柄会自行重建。

int n = TSE_Update(h);
if(n > 0) Print(n, " new events"); 

TSE_Trend

向上突破后为 1，向下突破后为 -1，首次突破前或句柄无效时为 0。

TSE_SwingCount 和 TSE_GetSwing

已存储的波段，最新的在索引 0：side（1 高点，-1 低点）、price、波段K线时间、label。句柄无效时数量为 -1；索引超出 0 到数量-1 时，TSE_GetSwing 返回 false 并设置 BAD INDEX。

TSE_EventCount 和 TSE_GetEvent

已存储的事件，最新的在索引 0：type、level（波段价格）、swing_time、break_time（突破或扫荡它的K线）。

TSE_GetLevels

最新的波段高点和波段低点（尚无时为 0.0），以及各自是否已被突破。未被突破的水平就是下一个 BOS 或 CHoCH 的触发点。

TSE_RangePosition

价格在这两个水平之间的位置：0 = 波段低点，50 = 均衡，100 = 波段高点，区间之外低于 0 或高于 100。price 0 = 句柄品种的 Bid。缺少某个水平或高点不高于低点时返回 EMPTY_VALUE。演示程序在 45 以下显示 DISCOUNT，在 55 以上显示 PREMIUM。

TSE_ZoneCount 和 TSE_GetZone

已存储的所有状态区域，最新的在索引 0：kind、dir、top、bottom、time（FVG：中间K线；OB：该K线本身）、state、fill 0-100。

TSE_NearestZone

离价格最近的 FRESH 或 TESTED 区域（0 = Bid）；在区域内距离为 0，距离相同时取较新的区域。kind：0 任意，1 FVG，2 OB。dir：0 任意，1，-1。返回其索引供 TSE_GetZone 使用并填写 top 和 bottom；没有时返回 -1（错误 OK）或 BAD PARAMETERS。

double top, bottom;
int z = TSE_NearestZone(h, 2, 1, 0, top, bottom);   // nearest bullish order block 

TSE_GetStats

传入一个动态 int 数组；其大小被调整为 12 并返回 12：0 已读K线，1 波段高点，2 波段低点，3 BOS UP，4 BOS DOWN，5 CHOCH UP，6 CHOCH DOWN，7 SWEEP HIGH，8 SWEEP LOW，9 FVG，10 OB，11 当前有效区域。自上次构建以来的计数。

TSE_LastError 和文本函数

TSE_LastError：最后一次调用的代码。TSE_ErrorText、TSE_LabelText、TSE_EventText、TSE_ZoneText(kind, dir) 和 TSE_StateText 返回"代码"一节中列出的字符串。

可运行的集成示例

#import "Tectonic_Structure_Engine.ex4"
   int    TSE_Create(string symbol, int timeframe, int strength, int history_bars);
   void   TSE_Release(int handle);
   int    TSE_Update(int handle);
   int    TSE_Trend(int handle);
   bool   TSE_GetEvent(int handle, int index, int &type, double &level, datetime &swing_time, datetime &break_time);
   int    TSE_NearestZone(int handle, int kind, int dir, double price, double &top, double &bottom);
   string TSE_EventText(int type);
#import

int h = -1, htf = -1;

int OnInit()
{
   h   = TSE_Create("", 0, 3, 1000);           // chart timeframe
   htf = TSE_Create("", PERIOD_H4, 3, 1000);   // higher-timeframe bias
   return (h >= 0 && htf >= 0) ? INIT_SUCCEEDED : INIT_FAILED;
}

void OnDeinit(const int reason) { TSE_Release(h); TSE_Release(htf); }

void OnTick()
{
   TSE_Update(htf);
   int n = TSE_Update(h);
   for(int i = n - 1; i >= 0; i--)
   {
      int type; double level; datetime st, bt;
      if(TSE_GetEvent(h, i, type, level, st, bt))
         Print(TSE_EventText(type), " at ", level, ", H4 trend ", TSE_Trend(htf));
   }
   double top, bottom;
   if(n > 0 && TSE_NearestZone(h, 2, 1, 0, top, bottom) >= 0)
      Print("nearest bullish OB ", bottom, " - ", top);
} 

典型设置

• 内部与外部结构：同一图表上两个句柄，strength 2 和 8。
• 多周期方向：图表句柄用于入场，H4 或 D1 句柄作为 TSE_Trend 过滤。
• 影线突破：TSE_Configure(h, 1, 0, 0.10, 0.25, 14)；此模式下没有扫荡。
• 更少、更大的区域和波段：fvg_min_atr 0.5-1.0，min_swing_atr 1.0。

架构与说明

• 每个句柄一个引擎，每个程序最多 32 个句柄；每个导入它的程序都有自己的句柄。数据保存在内存中，重启后从历史重新构建。
• 只用已收盘K线，每根只读一次，从旧到新：不会重绘，也从不使用第 0 根K线。
• 在 MT4 策略测试器中构建 20,000 根K线约耗时 80 毫秒。
• 其他品种或周期通过 iHigh、iLow、iOpen、iClose 和 iTime 读取；终端下载数据期间出现 NO HISTORY 属正常。在策略测试器中请使用被测品种（任意周期）。
• 每个句柄最多 2000 个波段、2000 个事件和 500 个区域；存满时丢弃最旧的 10%。
• MetaTrader 4 build 600 或更高版本。可安全用于策略测试器和优化。无 DLL、文件、全局变量、图表对象、计时器、警报或交易。

风险提示

本库描述价格结构。它不预测价格，也不保证盈利。基于它的任何策略请先在模拟账户上测试。