# Mt5 Ea Toolkit

> MT5/MQL5 Expert Advisor 全自动工具链：生成策略代码 → 编译 → 修复 → 多市场多周期回测 → 解析报告 → 排行榜。当用户提到 EA、MQL5、MQ5、MetaTrader、MT5、回测、backtest、交易策略、交易机器人、量化交易、外汇策略、algo trading、forex、技术指标策略等关键词时触发。即使用户只模糊地说'帮我写个EA'、'生成一个交易策略'、'编写1000个EA'、'做个自动交易程序'、'帮我回测'，也必须触发此技能。此技能同时适用于单EA和批量EA生成场景。

- Skill: `caoshuo594/mt5-ea-toolkit` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add caoshuo594/mt5-ea-toolkit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/caoshuo594/mt5-ea-toolkit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: caoshuo594 (https://skillmd.com/u/caoshuo594)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/caoshuo594/mt5-ea-toolkit

---


# MT5 EA Toolkit

MQL5 Expert Advisor 端到端自动化工具链。本 skill 包含一个编译好的 Rust CLI 引擎 `mt5ea.exe`，负责编译、回测、报告解析和排行榜生成。AI 工具（你）负责生成 MQL5 代码，然后调用 CLI 完成后续流程。

## CLI 位置

```
<SKILL_DIR>/scripts/mt5ea.exe
```

所有命令都通过这个路径调用，不需要加入系统 PATH。

## 认证（必须先登录）

**使用任何功能前，必须先完成认证。**

检查认证状态：

```bash
"<SKILL_DIR>/scripts/mt5ea.exe" auth status
```

如果未登录，需要向用户询问邮箱和密码（**绝对不要自己编造密码**），然后：

```bash
"<SKILL_DIR>/scripts/mt5ea.exe" auth login --email <邮箱> --password <密码>
```

### 认证流程

1. 每次会话开始时，先运行 `auth status` 检查登录状态
2. 如果未登录，向用户询问邮箱和密码
3. 运行 `auth login --email <邮箱> --password <密码>` 完成登录
4. 登录成功后即可正常使用所有命令
5. 如果登录失败，告知用户具体错误信息（如"邮箱或密码错误"、"账户已被禁用"）

### 认证命令

| 命令 | 说明 |
|------|------|
| `auth login --email X --password X` | 登录并保存令牌 |
| `auth status` | 查看当前登录状态 |
| `auth logout` | 登出并删除本地令牌 |

令牌加密保存在 `%APPDATA%/mt5ea/auth.json`（AES-256-GCM 加密，用户无法直接修改）。每 4 小时自动向服务端重新验证。JWT 有效期 7 天，过期后需重新登录。

## 工作流程

### 首次使用：初始化

```bash
"<SKILL_DIR>/scripts/mt5ea.exe" init
```

在用户工作目录创建 `CLAUDE.md`（工作规则）和 `PROGRESS.md`（进度跟踪）。如果已存在则跳过，读取 `PROGRESS.md` 从断点继续。

### 询问回测模式

**在开始生成第一个 EA 之前，必须询问用户选择回测模式：**

> 请选择回测模式：
> 1. **单市场单周期**（快速验证，~30-60秒/EA）— 只测 EURUSD H1，适合快速筛选策略
> 2. **多市场×多周期**（全面评估，~5-10分钟/EA）— 测 EURUSD/EURJPY/USDJPY × M15/H1/H4 共 9 种组合
> 3. **智能模式**（推荐）— 先快速验证，策略有效（PF>1.0）后自动扩展到多市场多周期
>
> 输入 1/2/3 选择模式，或直接说明偏好。

根据用户选择，后续 `run` 命令使用对应参数：
- 选择 1：使用 `-S`（标准模式）
- 选择 2：使用 `-F`（完整模式）
- 选择 3：使用 `-W`（智能模式）

**如果用户没有明确偏好，默认使用智能模式（`-W`）。**

### 检测 MT5 路径

```bash
"<SKILL_DIR>/scripts/mt5ea.exe" paths --json
```

返回 `terminal_path`、`metaeditor_path`、`data_path`、`toolkit_path`、`reports_path` 等。后续所有操作依赖这些路径。

### 核心：生成一个 EA

**原则：写一个 EA，编译回测一个。禁止批量生成后统一回测。**

1. **阅读 MQL5 模式参考**：生成代码前，阅读 `<SKILL_DIR>/references/mql5_patterns.md`，避免常见编译错误
2. **检测 MT5 路径**（如果尚未获取）：
```bash
"<SKILL_DIR>/scripts/mt5ea.exe" paths --json
```
从返回的 JSON 中记住 `toolkit_path`，这是 MT5 的 EA 工作目录。
3. **生成 MQL5 代码**：根据策略理论编写代码（见下方"EA 质量要求"）
4. **保存代码到 MT5 EA 目录**：将 .mq5 文件保存到 `toolkit_path` 下（**不是项目根目录**）：
```
{toolkit_path}/{日期}-{策略全称}.mq5
```
示例：`C:\Users\...\MQL5\Experts\mt5-ea-toolkit\20260418-MACD黄金交叉.mq5`

**重要：.mq5 文件必须保存到 toolkit_path 下，保存到其他位置会导致编译回测失败。**

> **Write 工具注意**：如果使用 Claude Code 的 Write 工具保存 .mq5 文件，必须先用 Read 工具读取目标路径（即使文件不存在），然后再用 Write 工具写入。这是 Claude Code Write 工具的强制要求。
5. **调用 CLI 执行流水线**：

```bash
# 完整流水线：多市场(EURUSD/EURJPY/USDJPY) × 多周期(M15/H1/H4)
"<SKILL_DIR>/scripts/mt5ea.exe" run -F -c {toolkit_path}/20260418-MACD黄金交叉.mq5 -t MACD黄金交叉 --json

# 标准流水线：单市场单周期
"<SKILL_DIR>/scripts/mt5ea.exe" run -S -c {toolkit_path}/20260418-MACD黄金交叉.mq5 -t MACD黄金交叉 --json

# 标准流水线 + 仅多市场
"<SKILL_DIR>/scripts/mt5ea.exe" run -S -M -c {toolkit_path}/20260418-MACD黄金交叉.mq5 -t MACD黄金交叉 --json

# 标准流水线 + 仅多周期(M15/H1/H4)
"<SKILL_DIR>/scripts/mt5ea.exe" run -S -P -c {toolkit_path}/20260418-MACD黄金交叉.mq5 -t MACD黄金交叉 --json

# 自定义多市场列表（逗号分隔）
"<SKILL_DIR>/scripts/mt5ea.exe" run -F --market-list GBPUSD,AUDUSD,NZDUSD -c {toolkit_path}/20260418-MACD黄金交叉.mq5 -t MACD黄金交叉 --json

# 自定义多周期列表
"<SKILL_DIR>/scripts/mt5ea.exe" run -F --period-list M30,H1,D1 -c {toolkit_path}/20260418-MACD黄金交叉.mq5 -t MACD黄金交叉 --json

# 智能模式 + 自定义首选测试对
"<SKILL_DIR>/scripts/mt5ea.exe" run -W --primary EURUSD/H1 -c {toolkit_path}/20260418-MACD黄金交叉.mq5 -t MACD黄金交叉 --json

# 仅编译不回测（快速验证代码语法）
"<SKILL_DIR>/scripts/mt5ea.exe" run --compile-only -c {toolkit_path}/20260418-MACD黄金交叉.mq5 -t MACD黄金交叉 --json

# 自动根据周期调整回测时间范围（M15:1年, H1/H4:3年, D1:5年）
"<SKILL_DIR>/scripts/mt5ea.exe" run -W --auto-range -c {toolkit_path}/20260418-MACD黄金交叉.mq5 -t MACD黄金交叉 --json
```

CLI 自动完成：编译 → 回测 → 解析报告。`--json` 返回结构化结果供解析。如果编译失败，JSON 中会包含错误信息，AI 读取错误后自行修复代码（直接修改 toolkit_path 下的 .mq5 文件），再次调用。

6. **解析结果**：读取 JSON 输出中的 `variants` 数组，查看每个变体的回测指标
7. **更新 PROGRESS.md**：记录 EA 结果
8. **生成排行榜**：

```bash
"<SKILL_DIR>/scripts/mt5ea.exe" leaderboard --open
```

### 单独操作（已有 EA 代码时）

```bash
# 仅编译
"<SKILL_DIR>/scripts/mt5ea.exe" compile 20260418-MACD黄金交叉.mq5 --json

# 仅回测（单个）
"<SKILL_DIR>/scripts/mt5ea.exe" backtest 20260418-MACD黄金交叉-EURUSD-H1 -s EURUSD -p H1 --json

# 多市场回测
"<SKILL_DIR>/scripts/mt5ea.exe" backtest 20260418-MACD黄金交叉 -M --json

# 多周期回测
"<SKILL_DIR>/scripts/mt5ea.exe" backtest 20260418-MACD黄金交叉 -P --json

# 解析报告
"<SKILL_DIR>/scripts/mt5ea.exe" report --ea 20260418-MACD黄金交叉-EURUSD-H1 --json
```

## EA 质量要求

每个 EA 必须有**专业的技术分析理论基础**，禁止随意拼凑指标参数。

### 可用理论体系

| 理论 | 说明 |
|------|------|
| MACD | Gerald Appel 原始理论，快慢线交叉 |
| RSI | J.Welles Wilder 原始理论，超买超卖 |
| 布林带 | John Bollinger 原始设计，波动率回归 |
| 海龟法则 | Richard Dennis/Donchian 通道突破 |
| 一目均衡表 | 细田悟一完整体系 |
| Elder 三重屏 | Alexander Elder 多时间框架 |
| 价格行为 | Pin Bar、Engulfing、供需区间 |
| Wyckoff | 量价分析、积累/派发 |
| KAMA/VIDYA | 自适应均线滤波 |
| ADX | 趋势强度过滤 |
| 谐波形态 | Gartley、Butterfly、Bat、Crab |
| 酒田五法 | 日本蜡烛图形态 |
| CCI | Donald Lambert 零轴交叉 |
| 动量理论 | 价格动量突破 |

### 禁止事项

- 过度优化参数（对历史数据微调止损到个位数点差）
- 使用未来函数（在当前 bar 引用未来数据）
- 不合理的止损止盈（应基于 ATR 或结构支撑阻力）

### EA 命名规则

```
{YYYYMMDD}-{策略中文全称}-{货币对}-{回测周期}.mq5
```

示例：`20260418-布林带突破回归-EURUSD-H1.mq5`

日期自动使用当天日期，策略全称由 AI 根据策略内容生成。多市场多周期回测时，CLI 自动为每个组合生成独立文件。

## 默认回测参数

| 参数 | 值 | 自定义 |
|------|-----|--------|
| 回测模式 | 0（Tick 级数据） | — |
| 多市场 | EURUSD, EURJPY, USDJPY | `--market-list GBPUSD,AUDUSD` |
| 多周期 | M15, H1, H4 | `--period-list M30,H1,D1` |
| 时间范围 | 2024.01.01 - 2025.12.31 | `--from` / `--to` / `--auto-range` |
| 初始资金 | 10000 USD | `--deposit` |
| 杠杆 | 1:100 | `--leverage` |
| 超时 | 900 秒 | `--timeout` |
| 智能模式首选对 | 自动根据策略类型选择 | `--primary EURUSD/H1` |
| 缓存失效 | 源文件更新时自动重测 | `--force` 强制重测 |

## 诊断与优化（解析结果后执行）

解析回测结果后，按以下规则判断是否需要优化：

| 情况 | 诊断 | 行动 |
|------|------|------|
| 0 笔交易 | 入场条件过严或逻辑错误 | CLI 会自动输出可能原因提示；检查条件是否矛盾，放宽阈值后重测。参考 mql5_patterns.md 中的"零笔交易排查清单" |
| 交易数过多（H1: >500, M15: >1000, H4: >200）且亏损 | 条件过松产生噪音信号 | 增加过滤条件（趋势确认、波动率过滤等） |
| PF < 0.8 | 策略逻辑可能根本有问题 | 考虑更换入场/出场机制 |
| PF 0.8–1.0 | 逻辑基本可行，参数需调优 | 调整止损止盈比例或增加过滤条件后重测 |
| PF 1.0–1.2 | 及格，有优化空间 | 微调参数看能否提升 |
| PF > 1.2 | 策略有效 | 记录结果，进入下一个 EA |

**迭代限制**：每个 EA 最多优化 2-3 次，确认无效后记录并进入下一个。修改代码后重新回测时，使用 `--force` 参数跳过缓存：

```bash
"<SKILL_DIR>/scripts/mt5ea.exe" run -F --force -c {toolkit_path}/xxx.mq5 -t 策略名 --json
```

## 持续运行规则

- **先优化再扩展**：有潜力的策略（PF > 0.8）先迭代优化，确认无效后再换下一个理论
- 除非用户明确说停，否则持续从不同理论体系生成新 EA
- 尽量覆盖多种交易思路，避免重复同一类策略
- 每完成 3-5 个 EA，调用 `leaderboard --open` 更新排行榜
- 每个 EA 经历：生成 → 编译 → 回测 → **诊断** → 优化或记录 → 下一个
- 会话中断时读取 `PROGRESS.md`，从断点继续

## 默认回测模式

根据用户在初始化时选择的模式执行：

| 模式 | CLI 参数 | 说明 | 适用场景 |
|------|----------|------|----------|
| 单市场单周期 | `-S` | 只测 EURUSD H1 | 快速筛选，急性子用户 |
| 多市场×多周期 | `-F` | 9 种组合全测 | 全面评估，慢性子用户 |
| 智能模式（默认） | `-W` | 先验证，有效后扩展 | 兼顾速度和覆盖面 |

## 策略推荐周期

| 策略类型 | 推荐周期 | 不推荐周期 | 原因 |
|----------|----------|------------|------|
| MACD 交叉 | H1, H4 | M15 | 信号频率在短周期过高 |
| RSI 超买超卖 | H4, D1 | M15 | 短周期 RSI 频繁穿越阈值 |
| 布林带回归 | H1, H4 | M15 | 波动率回归需要时间展开 |
| 海龟法则 | H4, D1 | H1, M15 | 通道突破需要足够宽的周期 |
| CCI 动量 | H4 | M15 | ±100 阈值在短周期噪音过大 |
| ADX 趋势 | H4 | M15 | 趋势强度判断需要长周期确认 |
| 一目均衡表 | H1, H4 | M15 | 云带跨度大，短周期无意义 |
| Elder 三重屏 | H1, H4 | M15 | 多时间框架需要足够跨度 |
| 谐波形态 | H4, D1 | M15 | 形态识别需要充分的价格历史 |
| 价格行为 | H1, H4 | M15 | Pin Bar/Engulfing 在短周期噪音大 |

## EA 评估标准

| 指标 | 优秀 | 良好 | 及格 | 需优化 |
|------|------|------|------|--------|
| 盈利因子 (PF) | > 1.5 | 1.2–1.5 | 1.0–1.2 | < 1.0 |
| 最大回撤 (DD) | < 10% | 10–20% | 20–30% | > 30% |
| 交易数量 | 30–300 | 300–500 | 500–1000 | < 30 或 > 1000 |
| 恢复因子 (RF) | > 2.0 | 1.0–2.0 | 0–1.0 | < 0 |

补充规则：
- 低胜率（< 35%）需要盈亏比 > 2.0 补偿
- 交易数 < 30 统计意义不足
- 交易数合理范围与周期相关：M15 可到 1000，H1 约 500，H4 约 200
- 交易数远超合理范围可能过拟合或噪音过多

## 参考文件

- `<SKILL_DIR>/references/mql5_patterns.md` — MQL5 代码模式参考（生成代码前必读）
- `<SKILL_DIR>/templates/CLAUDE.md` — 项目工作规则模板
- `<SKILL_DIR>/templates/PROGRESS.md` — 进度跟踪模板