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` — 进度跟踪模板