API 文档 | TraderEdgeAIFactor

介绍我们

TraderEdgAIFactor 是一个基于 C++ 开发的算法因子库（DLL），供 MetaTrader 4 / 5 通过 MQL4/MQL5 直接调用。它把「趋势判断、震荡识别、削单建议、R² 趋势强度」等能力封装成统一接口，你只需把 DLL 和头文件放进 MT4/MT5 目录，在 EA 里几行代码即可拿到方向、动作、置信度等信号。

能解决什么问题：接入简单（无需自写复杂因子算法）、多因子可选（按策略选不同因子 ID）、信号统一（方向、动作、regime 等格式一致，便于和你的开平仓逻辑对接）。

典型用法一句话：创建因子 → 传入 K 线数据 → 调用 Process → 读取方向、动作、置信度。削单与 R² 为独立 API，按需调用。下面「快速完成对接」按场景给出极简代码和字段说明，让你一次性跑通。

快速完成对接

按你的需求选一个场景，按下面步骤即可对接成功。每个场景都给出极简代码，并对代码里用到的每个字段、每个入参/出参做解释，方便你一次跑通。

只要方向/动作单因子 Init→Update→Signal，拿 direction/action 只要趋势强度 R²TEA_RSquared(closes, n) 一行取值只要削单建议TEA_ReductionRecommend 按需调用查完整 API进阶版：全部函数、参数、返回值

前置条件（所有场景通用）

将 TraderEdgAIFactor.dll 放到 MT4 的 MQL4/Libraries（或 MT5 的 MQL5/Libraries）。
将 TraderEdgAIFactor.mqh 放到 MQL4/Include（或 MQL5/Include）。
在 EA 中 #include <TraderEdgAIFactor.mqh>（MQ4 也可用 #import "TraderEdgAIFactor.dll" 声明函数）。
若 MT 提示不允许 DLL，请在「工具 → 选项 → 专家顾问」中勾选「允许 DLL 导入」。

5 分钟跑通：最小代码（推荐）

用 CTEAFactor 按名称初始化，Update 后 Signal 一次拿齐方向/动作。不知道选哪个因子？用 "HedgeRegime" 即可。只需单个值时可用快捷函数：TEA_ATR()、TEA_Direction("HedgeRegime")、TEA_Action("HedgeRegime")、TEA_Brake("HedgeCore")（适合每 Bar 一次调用）。

#include <TraderEdgAIFactor.mqh>
CTEAFactor factor;
int OnInit() {
  if (!factor.Init("HedgeRegime", 200)) return INIT_FAILED;  // 按名称，不必记 ID
  return INIT_SUCCEEDED;
}
void OnDeinit(int r) { factor.Destroy(); }
void OnTick() {
  TEAStandardSignalData sig;
  if (!factor.Update() || !factor.Signal(sig)) return;
  if (sig.action != 0)  // 0=FLAT 1=LONG 2=SHORT
    Print("方向:", sig.direction, " 动作:", sig.action, " 置信度:", sig.confidence);
}

必读概念

因子 ID / 名称：0–16 对应不同算法，常用 2（HedgeRegime）、8（HedgeCore）。推荐用 Init("HedgeRegime") 按名称，不必记 ID。
句柄 (handle)：Create 或 Init 返回的 int，后续 Process、Get* 都要传。CTEAFactor 封装后无需直接操作。
Process / Update：每次 K 线数据更新后调用一次，之后才能读 Direction、Action 等。
方向 (direction) / 动作 (action)：direction 为 -1 / 0 / +1；action 为 0=FLAT / 1=LONG / 2=SHORT。
regime：1=趋势，2=震荡，0=不确定，-1=高风险。可用于减仓或刹车逻辑。

场景 A：只要方向/动作

在 EA 里拿到「做多 / 做空 / 观望」以及方向强度，用于开平仓判断。下面用因子 ID = 2（HedgeRegime） 做示例，推荐对冲/网格类策略使用；其他因子只需把 TEA_FactorCreate(2) 里的 2 改成 0/1/3，详见算法因子库。

极简代码（MQ4，复制即用）

#include <TraderEdgAIFactor.mqh>
int g_h = 0;
int OnInit() {
  g_h = TEA_FactorCreate(2);  // 2 = HedgeRegime，推荐先用这个
  return (g_h != 0) ? INIT_SUCCEEDED : INIT_FAILED;
}
void OnDeinit(int r) { if (g_h != 0) TEA_FactorDestroy(g_h); }
void OnTick() {
  if (g_h == 0) return;
  double o[], h[], l[], c[], v[]; int n = 200;
  ArrayResize(o,n); ArrayResize(h,n); ArrayResize(l,n); ArrayResize(c,n); ArrayResize(v,n);
  for (int i = 0; i < n; i++) {
    int bar = n - 1 - i;
    o[i] = iOpen(Symbol(), PERIOD_CURRENT, bar);
    h[i] = iHigh(Symbol(), PERIOD_CURRENT, bar);
    l[i] = iLow(Symbol(), PERIOD_CURRENT, bar);
    c[i] = iClose(Symbol(), PERIOD_CURRENT, bar);
    v[i] = (double)iVolume(Symbol(), PERIOD_CURRENT, bar);
  }
  if (TEA_FactorProcess(g_h, o, h, l, c, v, n) != 1) return;
  double dir = TEA_FactorGetDirection(g_h);
  int act = TEA_FactorGetAction(g_h);
  int regime = TEA_FactorGetRegime(g_h);
  // 这里用 dir / act / regime 做你的开平仓逻辑
}

#include <TraderEdgAIFactor.mqh>
int g_h = 0;
int OnInit() {
  g_h = TEA_FactorCreate(2);  // 2 = HedgeRegime, recommended first
  return (g_h != 0) ? INIT_SUCCEEDED : INIT_FAILED;
}
void OnDeinit(int r) { if (g_h != 0) TEA_FactorDestroy(g_h); }
void OnTick() {
  if (g_h == 0) return;
  double o[], h[], l[], c[], v[]; int n = 200;
  ArrayResize(o,n); ArrayResize(h,n); ArrayResize(l,n); ArrayResize(c,n); ArrayResize(v,n);
  for (int i = 0; i < n; i++) {
    int bar = n - 1 - i;
    o[i] = iOpen(Symbol(), PERIOD_CURRENT, bar);
    h[i] = iHigh(Symbol(), PERIOD_CURRENT, bar);
    l[i] = iLow(Symbol(), PERIOD_CURRENT, bar);
    c[i] = iClose(Symbol(), PERIOD_CURRENT, bar);
    v[i] = (double)iVolume(Symbol(), PERIOD_CURRENT, bar);
  }
  if (TEA_FactorProcess(g_h, o, h, l, c, v, n) != 1) return;
  double dir = TEA_FactorGetDirection(g_h);
  int act = TEA_FactorGetAction(g_h);
  int regime = TEA_FactorGetRegime(g_h);
  // Use dir / act / regime for your open/close logic
}

字段与接口说明（本场景用到的）

名称	含义	怎么用
`g_h`	因子句柄	由 TEA_FactorCreate(2) 返回，后续 Process、GetDirection 等都要传这个值；MQ4 里是 int。
`o[], h[], l[], c[], v[]`	K 线数组	开盘、最高、最低、收盘、成交量；下标 0 = 最旧一根，n-1 = 最新一根，顺序不能反。
`n = 200`	K 线根数	至少 50，建议 200；数组长度要和 Process 的 count 一致。
`TEA_FactorProcess(g_h, o, h, l, c, v, n)`	执行一次因子计算	每次 tick 或新 K 线时调用一次；返回 1 表示成功，之后才能读 GetDirection/GetAction。
`dir = TEA_FactorGetDirection(g_h)`	方向	double：-1.0 = 偏空，0 = 中性，+1.0 = 偏多；可用于仓位方向或过滤。
`act = TEA_FactorGetAction(g_h)`	动作	int：0 = FLAT（观望），1 = LONG（做多），2 = SHORT（做空）；直接用于开平仓判断。
`regime = TEA_FactorGetRegime(g_h)`	市场状态	int：1 = 趋势，2 = 震荡，-1 = 高风险；可用于减仓或刹车逻辑。

对接成功：编译通过，EA 挂到图表后，在 OnTick 里能正确读到 dir / act / regime（例如用 Print 输出），即表示本场景对接成功。使用 MT5 时，MQ5 示例见本页底部「进阶版」入口。

场景 B：只要趋势强度 R²

在 EA 里拿到 0～1 的趋势强度（R²），替代手写 R² 计算，数值更稳定、抗异常值。无状态，每次传入收盘价数组和长度即可。

极简代码（MQ4）

#include <TraderEdgAIFactor.mqh>
void OnTick() {
  double closes[]; int n = 100;
  ArrayResize(closes, n);
  CopyClose(Symbol(), PERIOD_CURRENT, 0, n, closes);
  double r2 = TEA_RSquared(closes, n);
  // r2 在 0～1 之间，越大趋势越强，可用于过滤或仓位权重
}

#include <TraderEdgAIFactor.mqh>
void OnTick() {
  double closes[]; int n = 100;
  ArrayResize(closes, n);
  CopyClose(Symbol(), PERIOD_CURRENT, 0, n, closes);
  double r2 = TEA_RSquared(closes, n);
  // r2 in 0~1; higher = stronger trend; use for filter or position weight
}

字段与接口说明

名称	含义	怎么用
`closes[]`	收盘价数组	顺序：下标 0 = 最旧，n-1 = 最新；由 CopyClose 或等价方式填充。
`n`	数组长度（周期）	即 R² 计算用的 K 线根数，建议 2～512；count < 2 时函数返回 0。
`TEA_RSquared(closes, n)`	计算 R²	返回值 double，范围 0～1：越接近 1 趋势越强，接近 0 表示无明显趋势。

对接成功：编译通过，挂图后能稳定读到 0～1 的 r2 值即表示成功。需要 Theil-Sen 或指数加权等扩展时，见进阶版 · R² API（TEA_RSquaredEx）。

场景 C：只要削单建议

在对冲/马丁类 EA 里，根据当前多空两侧持仓与市场状态，拿到「本 tick 是否建议削单、削哪一侧、先平盈利还是亏损」等推荐。无状态，每次传入多空两侧的盈亏、手数、开仓时间等数组及少量参数即可。

极简用法说明

削单 API（TEA_ReductionRecommend）入参较多，这里只说明核心含义和返回值怎么用；完整参数与 MQ4/MQ5 示例见进阶版 · 削单 API。

入参：多侧与空侧各自的 profit[]、lots[]、open_time[]（按开仓时间升序），以及 regime、confidence、净利目标、是否允许跨侧等。若同时使用因子接口，regime、confidence 可直接传 TEA_FactorGetRegime(句柄)、TEA_FactorGetConfidence(句柄)；进阶版中有每个参数的说明与推荐取值。
返回：1 = 本 tick 有削单推荐，0 = 无推荐。通过 out_action、out_side、out_profit_start_index、out_profit_count 等输出参数可得到「单侧削多/削空」或「跨侧」以及要平的仓位索引与数量。

关键输出字段（怎么用）

输出	含义	怎么用
返回值 1/0	是否有推荐	1 = 有削单建议，可依 out_* 执行平仓；0 = 本 tick 不推荐削单。
`out_action`	动作类型	1 = 单侧削多，2 = 单侧削空，3 = 跨侧削单。
`out_side`	亏损侧	配合 out_loss_index 等可定位要平的亏损单。
`out_profit_start_index` / `out_profit_count`	盈利段	先平盈利段（从 start_index 起共 profit_count 笔），再平亏损。

对接成功：在 EA 里按进阶版示例准备好多空两侧数组和参数，调用后能根据返回值与 out_* 正确执行一次「先平盈利再平亏损」的削单逻辑即表示成功。

多因子组合

用 CTEAFactorSelector 按名称组合多个因子：单因子直用、双因子主备（主 70% 子 30%）、3–8 因子投票（按 accuracy 加权）。组合因子（如 HedgeCore）与原子因子等价，都可参与。

用法一：单因子

CTEAFactor factor;
factor.Init("HedgeRegime");  // 或 factor.Init("HedgeCore");
if (factor.Update()) {
  TEAStandardSignalData sig;
  factor.Signal(sig);
  // sig.direction, sig.action, sig.confidence...
}

CTEAFactor factor;
factor.Init("HedgeRegime");  // or factor.Init("HedgeCore");
if (factor.Update()) {
  TEAStandardSignalData sig;
  factor.Signal(sig);
  // sig.direction, sig.action, sig.confidence...
}

用法二：双因子主备（主 70% + 子 30%）

CTEAFactorSelector sel;
sel.Init("HedgeCore,VolatilityAdjustedMomentum", "HedgeCore");  // 主=HedgeCore
if (sel.Update()) {
  TEAStandardSignalData sig;
  sel.GetStandardSignal(sig);
  // sig 已是两因子加权后的结果
}

CTEAFactorSelector sel;
sel.Init("HedgeCore,VolatilityAdjustedMomentum", "HedgeCore");  // main=HedgeCore
if (sel.Update()) {
  TEAStandardSignalData sig;
  sel.GetStandardSignal(sig);
  // sig is weighted result of two factors
}

用法三：多因子投票（3–8 个）

CTEAFactorSelector sel;
sel.Init("HedgeCore,VolatilityAdjustedMomentum,AdaptiveTrendIntensity,HurstRegime");
if (sel.Update()) {
  TEAStandardSignalData sig;
  sel.GetStandardSignal(sig);
  // 方向按 accuracy 加权，regime 取最严
}

CTEAFactorSelector sel;
sel.Init("HedgeCore,VolatilityAdjustedMomentum,AdaptiveTrendIntensity,HurstRegime");
if (sel.Update()) {
  TEAStandardSignalData sig;
  sel.GetStandardSignal(sig);
  // direction weighted by accuracy, regime takes strictest
}

汇总只产出 StandardSignal；要 ATR、Brake 等扩展字段时，需单独持有一个因子句柄调用 ATR()、Brake() 等。

进阶版（高级用户）

若需每个函数、每个入参/出参的完整说明，以及 MQ4 与 MQ5 双平台代码示例、注释与注意事项，请查看进阶版 API 文档。简单对接与进阶版已分开成两页，普通用户与高级用户互不干扰。

进入进阶版 API 文档 →