mt5-robot-tester

MT5 Robot Tester

概述

通过命令行驱动策略测试器，从 candidates 文件夹中选出最佳 MetaTrader 5 机器人（Expert Advisors），采用三轮流程，机器人晋级时会在文件夹之间移动，并在每轮测试中持续学习，以改进每轮的筛选结果。整个运行过程都会保存检查点，并可恢复。

• 第 1 轮 — 筛选（所有交易对）： 在配置的 common.symbols 列表中，对每个交易品种回测 EA（每个交易品种进行一次 Optimization=0 回测——MT5 build 6061 生成的 Optimization=3 XML 为空，因此改用逐品种回测）。门槛：至少 5 个交易品种盈利，且最佳交易品种的收益 ≥ 存款的 3 倍。
• 第 2 轮 — 最佳交易对回测： 在最佳交易品种上进行单次回测；分析净利润百分比、最大回撤百分比、盈利月份占比、是否所有年份均盈利、LR Correlation，以及创出新高所需月数。
• 第 3 轮 — 顺序参数优化： 对 MagicNumber 之后的 5–6 个输入逐个进行优化，范围为 ±50%，步长为 5%；然后进行最终回测。
• 决赛入围者： 优化后的结果优于第 2 轮，且利润至少为存款的 4 倍，最大回撤不超过 12%。

已测试的机器人会移至 in-testing；决赛入围者还会连同优化后的 .set 一起复制到 finalists。

适用场景

• “在 MetaTrader 5 上测试机器人 / bots / EAs。”
• 筛选一个 MT5 Expert Advisors 文件夹，并从所有交易对中选出最佳机器人。
• 优化 EA 参数，并根据利润 / 回撤 / 稳定性确定决赛入围者。
• 恢复中断的测试运行。

前置条件

• 已安装 Windows + MetaTrader 5（测试器运行 terminal64.exe）。
• 已下载经纪商的逐笔数据（默认使用真实逐笔数据建模，Model=4）。
• MQL5\Experts 下的三个文件夹：candidates、in-testing、finalists。
• 在配置中设置 common.symbols——第 1 轮回测使用的交易对（即 Market Watch 中的交易品种）。
• 可选的各机器人 .set 文件（配置中的 sets_dir），用于第 2 轮基准测试和第 3 轮参数优化。优化期间，除当前正在搜索的参数外，其他所有输入均固定；如果没有 .set，则跳过第 3 轮，依据第 2 轮给出结论。
• 运行前请关闭 MetaTrader 5——测试器需要独占使用数据文件夹。
• Python 3.9+（仅使用标准库）。无需付费 API。

工作流

步骤 1 — 配置

复制 assets/pipeline_config.template.json，填写三个文件夹路径，并将 terminal_path 设置为明确的 terminal64.exe 路径。实际运行测试器时， 必须提供终端路径，除非你选择在未提供路径时启用自动发现。可通过 --terminal-path、配置项 terminal_path 或 $MT5_TERMINAL_PATH 传入。 --dry-run 会生成 INI 文件，不会解析或启动终端，因此无需提供终端路径。 切勿提交真实的个人路径——请在运行时传入配置。默认值已包含约定的设置（2020.01.01→2026.06.30，H1， Model=4，10000 USD，1:100，门槛和阈值）。

终端选择需要主动启用。 为了安全起见，流水线绝不会在 Program Files 下自动发现 terminal64.exe。在同时进行实盘交易的机器上，自动检测到的终端通常是经纪商的实盘终端；生成的 INI 没有 Login，因此会在上次使用的账户上启动，并在结束时通过 ShutdownTerminal=1 关闭它。为避免在不知情的情况下借用（并关闭）实盘终端，请传入指向仅用于测试器的便携式安装的明确路径（一个带有独立数据目录的 /portable 文件夹）。如果你明确接受此风险，只有在未设置 --terminal-path / $MT5_TERMINAL_PATH / config.terminal_path 时，--allow-auto-detect 才会恢复对 Program Files 的发现。

**从旧版优先级／回退行为迁移：**现在的选择顺序为 --terminal-path > config.terminal_path > MT5_TERMINAL_PATH；配置项的优先级高于环境变量。优先级最高的已提供路径必须存在： 如果路径不存在，就会报错，不会回退，即使启用了 --allow-auto-detect 也一样。 例如，过时的 config.terminal_path 会阻止使用有效的 MT5_TERMINAL_PATH。 请修正或删除过时的配置项，或者通过有效的 CLI 路径覆盖它。 自动检测需要主动启用，且仅在未提供路径时生效。

步骤 2 — 试运行（可选）

在不解析或启动 MT5 的情况下，验证生成的 Round-1 INI 文件。离线试运行无需 终端路径或已安装的 MT5：

python3 skills/mt5-robot-tester/scripts/mt5_batch_tester.py \
  --config my_config.json --output-dir reports/mt5_pipeline --dry-run

步骤 3 — 运行流水线

python3 skills/mt5-robot-tester/scripts/mt5_batch_tester.py \
  --config my_config.json --output-dir reports/mt5_pipeline \
  --terminal-path "C:\Program Files\MetaTrader 5\tester\terminal64.exe"

每个机器人依次经过 R1 → R2 → R3 → 决选。每完成一步，进度都会写入 state.json 和 run.log。

步骤 4 — 中断后恢复

python3 skills/mt5-robot-tester/scripts/mt5_batch_tester.py \
  --config my_config.json --output-dir reports/mt5_pipeline --resume \
  --terminal-path "C:\Program Files\MetaTrader 5\tester\terminal64.exe"

--resume 会跳过已完成的机器人，并且只有在执行配置、EA 二进制文件和输入 .set 的指纹仍然匹配时，才会复用已完成的轮次。如果周期、交易品种列表、二进制文件或 .set 发生变化，系统会安全地重新启动该机器人的测试。

可选 — HTML 控制面板

启动本地仪表盘，查看各文件夹中的机器人、每个机器人的阶段和判定结果，以及一个启动按钮——启动后无需 CLI：

python3 skills/mt5-robot-tester/scripts/dashboard.py \
  --config my_config.json --output-dir reports/mt5_pipeline

服务地址为 http://127.0.0.1:8765/（会自动打开，仅限本地主机）。页面每 3 秒自动刷新：文件夹内容、每个机器人的阶段（R1/R2/R3/done）、通过／未通过判定、汇总计数以及实时 run.log。启动／停止请求仅限于精确匹配的本地来源，并且需要每个服务端的 CSRF 令牌。

步骤 5 — 查看结果

• leaderboard_<ts>.md / .json — 含判定结果和关键指标的排名。
• learnings.json / learnings.md — 此轮技能学到的内容（参数影响和交易品种先验），位于配置的输出目录下。
• mt5_reports/ 和 mt5_ini/ — 每个机器人／轮次对应的原始 MT5 报告和配置。

轮次详情

第 1 轮门槛（两项都必须满足）

1. count_positive_profit(passes) ≥ round1_min_positive（默认 5）。
2. best_symbol_profit ≥ round1_min_profit_multiple × deposit（默认 3×）。

未通过 → 拒绝该机器人（移至 in-testing）。

第 2 轮质量档案（参考阈值）

净利润 ≥300%，最大回撤 <15%（余额／净值百分比中的较大值），盈利月份

70%，所有年份均为正值，LR Correlation ≥0.80，创新高所需月数 ≤3。 每个机器人都会报告这些指标；硬性决选门槛是第 3 轮。

第 3 轮顺序优化

对 MagicNumber 之后的每个 5–6 个输入（先按学习得出的顺序），在 [V×0.5, V×1.5] 范围内以 V×0.05 为步长优化该单个参数（Optimization=1），同时固定其他所有 .set 输入；固定其最佳值后，再继续优化下一个参数。使用为入围候选保存的完整精确输入集运行最终回测。

入围候选

evaluate_finalist：表现优于第 2 轮，并且利润 ≥ 存款的 4 倍，并且最大回撤 ≤12%。→ 连同 <bot>.set 一起复制到 finalists。

循环间自学习

learnings.json 会逐次运行累积以下数据：参数平均利润提升（据此调整第 3 轮优化顺序，让影响最大的参数优先尝试）、交易品种先验（每个品种成为最佳组合的频率）以及各机器人的评定结果。这能让每轮选择更快收敛。结果是确定性的——仅使用简单的汇总统计。

输出格式

• leaderboard_<ts>.json — {name, verdict, best_symbol, r2_profit, final_profit, final_dd_pct, lr, reason} 列表，按入围候选优先、利润降序排列。
• leaderboard_<ts>.md — 相同内容，以表格形式呈现。
• state.json — 可恢复的逐机器人、逐轮检查点。

资源

• scripts/mt5_batch_tester.py — 流水线编排器 + INI 构建器（CLI）。
• scripts/parse_mt5_optimization.py — 优化报告（XML/HTML）解析器 + 第 1 轮门槛检查。
• scripts/parse_mt5_report.py — 回测报告解析器 + 余额序列指标。
• scripts/mt5_learnings.py — 跨运行学习存储。
• scripts/mt5_common.py — 共享解析辅助工具（EN/ES 表头、数字）。
• references/mt5-cli-reference.md — MT5 [Tester]/[TesterInputs] 键、枚举值、报告格式和注意事项。
• assets/pipeline_config.template.json — 带占位符的配置模板。

核心原则

1. 绝不提交个人路径 — 文件夹/终端路径来自配置/ENV/参数。
2. 使用相对的 Report= 名称，因为 build 6061 会忽略绝对报告路径；从终端数据目录收集已完成的报告。
3. **真实点差（Model=4）**需要经纪商的点差数据；速度较慢——请预留较长运行时间。
4. 可恢复：每轮都会创建检查点；--resume 只会复用指纹匹配的任务，并重试执行错误。
5. 失败时采取保守处理：不完整、超时、过时或无法解析的报告绝不会淘汰、晋级或移动候选项。每个唯一的第 1 轮交易品种都必须完成。
6. MT5 单一所有者：每个共享的 MT5 数据文件夹在整个进程生命周期内都会持有 OS 锁。如果无法确认子进程已终止，整个运行将停止并写入 .blocked 标记；手动移除该标记前，请确认记录的 PID/进程树已退出。
7. 全周期指标：测试周期配置范围内，开始时、结束时或完整一年内没有交易的月份仍会计入。
8. 每轮学习：参数/交易品种统计会让后续运行更倾向于成功的组合。
9. 根据你的构建版本进行验证：报告布局（尤其是交易表）以及 32 ms 延迟映射可能不同——请参阅参考文档中的 (verify) 注释。