雪雪AI · 统一综合交易系统（xuexue-ai-scan）

基于 MetaTrader 5（MT5） 行情源的本地量化交易系统：行情扫描、技术面 + 基本面 + 新闻面研判、 13 源财经新闻聚合、ForexFactory 财经日历、🤖 AI 智能助手、🧙 小策 AI 策略师（自然语言写策略 → 回测 → 接实盘）、 🧠 小雪 AI 交易员、15 套精选自动交易策略（黄金 5 + 外汇 5 + 比特币 5，全部通过 12 个月 4 窗回测验证）， 并内置 MCP Server，可被 WorkBuddy 等支持 MCP 的 AI 客户端直接调用。

全部行情数据来自本地 MT5 终端，无需任何外部 API Key（AI 对话可选接入外部 LLM）。

当前版本：1.3.5（版本真源：包根目录 VERSION 文件，与 package.json 同步维护）

一、核心特性

| 模块 | 说明 | | --- | --- | | 单端口统一面板 | 一个 8888 端口承载全部功能：仪表盘 / 行情扫描 / 技术面 / 基本面 / 报价 / 策略中心 / 自动交易 / AI，支持 #hash 直达（如 /#fund、/#aist、/#center）。 | | 🧙 小策 · AI 策略师 | 用一句话描述想法 → 小策写出策略代码 → 一键回测（12 个月） → 🔍 信号自检 → ⚙️ 调参重跑 → ▶ 启动接入实盘。支持趋势/回归/突破/多因子/波动率 5 类原型，代码经沙箱关键字检查后落盘。 | | 🔌 账户一键接入 | 「🔐 账户接入」页一个 🔌 MT5 连接 按钮完成连接：默认读取 config.yaml 已保存账户，连接前自动断开旧会话，无需重复填写。 | | 黄金 / 外汇 / 比特币自动交易 | 三大自动交易页各绑定 5 套精选策略（共 15 槽位），每套均通过「精选精良」四项静态闸 + 真实 12 个月 4 不重叠窗口回测；黄金页夏普 2.0~5.5、外汇页全部净盈利（头名 PF 4.20 / 夏普 4.60）、比特币页为熊市挖矿所得（全部净盈利、回撤 <1%）。 | | 波动/点差闸（风控） | 运行时实时检查 ATR ÷ 点差，低于阈值（默认 3.0，面板可改）自动不开单，避免「点差吞噬」；基础手数 0.01、扫描间隔等参数均可在面板修改。 | | 策略挖掘管线 | mine_btc.py 两段式挖矿（快筛 → 4 窗验证 → 家族去重）；mine_fx_health.py 从 250 套外汇候选池精选；所有入选策略需通过真实 4 窗验证防过拟合。 | | 基本面分析 v2 | 13 个国内外新闻源（FXStreet / ForexLive / CNBC / MarketWatch / SeekingAlpha / 金十数据 / 华尔街见闻 / 新浪财经 / 英为财情 / CoinTelegraph / OilPrice / 新浪7x24 / 新浪美股）+ 6 大主题情绪分类（黄金 / 外汇 / 美联储 / 特朗普 / 加密货币 / 大宗商品）+ ForexFactory 本周财经日历（高/中影响事件、北京时间、预期/前值）+ FRED 宏观指标卡（利率 / 非农 / CPI + 倒计时）。 | | 小雪 AI 交易员 | 全自主交易员引擎（20 外汇品种宇宙，6 维加权评分，波动/点差比护栏，15 天模拟→盈利转实盘的成长路径，自我迭代按绩效调权，记忆跨重启持久化）。 | | 🤖 AI 智能对话 | 流式对话 + 拖入文件 / K 线截图；外部 LLM 意图理解 + 本地金融工具层（行情 / 持仓 / 风控 / 订单预览）。支持商汤 SenseNova（默认）/ OpenAI / DeepSeek / 智谱 / 通义 / Kimi / 豆包 / 百度 / 硅基流动 / Ollama 等。 | | MCP Server（内置） | 面板自带 Streamable HTTP MCP 端点（/mcp，协议 2025-03-26），暴露 6 个工具；「🧩 AI MCP」页可一键把面板注册进 WorkBuddy 的 mcp.json。 | | 量化研究设施 | 30 套生产策略 + 250 套外汇候选池 + 挖掘金/银/BTC/ETH 历史数据；quant_arch/ 六层量化架构（数据层 / 因子引擎 / 策略引擎 / 风控执行 / 实盘引擎 / 监控）。 |

二、环境要求

• Node.js ≥ 18（面板启动器 scripts/serve_single.js）

• Python 3.10 ~ 3.13（扫描 / 自动交易 / AI 后端）

• Python 依赖（requirements.txt，实测可运行组合；numpy 必须为 1.26.x，pandas 2.1.4 不兼容 numpy 2.x）：

  MetaTrader5==5.0.45
  pyzmq==27.1.0
  requests==2.31.0
  pandas==2.1.4
  numpy==1.26.4
  PyYAML==6.0.3
  python-dotenv==1.2.3

• MetaTrader 5 桌面终端（已登录账号、「选项 → EA 交易器」勾选允许算法交易）

• Windows 推荐；Linux/macOS 需自行配置 MT5（Wine 或远程行情网关）

三、快速开始

# 1) 安装（npm 包自带面板与策略，无需额外前端依赖）
npm install -g xuexue-ai-scan     # 或本地 npm install
pip install -r requirements.txt   # Python 后端依赖

# 2) 配置（首次会自动从样例生成）
cp config.example.yaml config.yaml   # 账户 / 扫描品种 / 权重 / LLM 端点 / 策略参数

# 3) 启动（单端口 8888）
npm start                            # 等价于 node scripts/serve_single.js

# 4) 打开面板
# http://127.0.0.1:8888          → 仪表盘
# http://127.0.0.1:8888/#account → 账户接入（点「🔌 MT5 连接」）
# http://127.0.0.1:8888/#aist    → 小策 AI 策略师
# http://127.0.0.1:8888/#fund    → 基本面分析
# http://127.0.0.1:8888/#mcp     → AI MCP（WorkBuddy 集成）

首次使用请看面板内「🧭 引导页」：安装 MT5 → 启动面板 → 一键接入账户 → 运行扫描 → 启停策略 → 让小策写策略。

四、页面导航（单页应用 · 侧栏切换）

| 分组 | 页面 | 说明 | | --- | --- | --- | | 总览 | 📊 仪表盘 | 账户、槽位状态、扫描机会汇总 | | | 🧭 引导页 | 首次使用分步指引（7 步） | | | 📖 使用说明 | 五分钟上手流程、常见问题、版本要点 | | 策略 | 📡 行情扫描 | 技术面 + 基本面 + 新闻综合评分，可自动开单 | | | 🎯 策略中心 | 15 个精选槽位的启停与配置（槽位卡片只在策略中心 / 槽位页显示） | | | 📚 策略库 | 生产策略 + 研究候选，按标签 / 家族 / 健康度筛选 | | | 📈 回测对比 | 精选策略 4 窗回测明细 | | | 🥇 💱 🪙 自动交易 ×3 | 黄金 / 外汇 / 比特币分页，每页 5 套精选策略卡片 | | 行情 · 账户 | 📊 技术面分析 | RSI / MACD / 均线 / 布林 / ATR 快照 | | | 📉 市场报价 | 实时买卖价、点差、涨跌幅（红涨绿跌） | | | 🔐 账户接入 | MT5 连接状态 + 🔌 MT5 连接 一键重连 | | 基本面 | 🌐 基本面分析 | 13 源新闻流（主题过滤）、6 类情绪、宏观指标、FF 财经日历 | | AI 助手 | 🤖 AI 智能 | 流式对话 + 多 Agent（导演 / 技术 / 新闻 / 策略 / 宏观 / 风控） | | | 🧙 AI 策略师 | 小策：写策略 / 回测 / 自检 / 调参 / 改进 / 启动 | | | 🧩 AI MCP | MCP 端点状态、6 工具列表、一键注册到 WorkBuddy | | | 🧠 AI 交易员 | 小雪：交易员档案 / 模拟 / 迭代 / 记忆面板 |

五、🧙 小策 · AI 策略师

把「想法」直接变成「可运行的策略」。全程在面板内闭环，不需要你写一行代码。

5.1 工作流

描述需求（品种 / 周期 / 逻辑 / 过滤）
      ↓  🧙 生成策略        POST /api/ai-strategist/generate    （LLM 超时 240s）
生成 decide(ctx, cfg) 代码 + 沙箱关键字检查（禁网络 / 文件 / 进程 / 动态执行）
      ↓  📊 一键回测        POST /api/ai-strategist/backtest    （12 个月，真实成本模型）
      ↓  🔍 信号自检        POST /api/ai-strategist/validate    （最近 2000 根 K 线的信号数 / 方向 / 时段）
      ↓  ⚙️ 调参 → 再回测   POST /api/ai-strategist/params      （只改你改的键，其余保留）
      ↓  🔁 让小策改进       POST /api/ai-strategist/refine      （生成新版本，原版本保留）
      ↓  ▶ 启动接入实盘      POST /api/ai-strategist/launch       （分配 auto31+ 槽位）

5.2 能力边界

• 策略原型 5 类：趋势跟踪 / 均值回归 / 通道突破 / 多因子打分 / 波动率自适应，也可让小策自选。
• 品种与周期：XAUUSDc / XAGUSDc / EURUSDc / GBPUSDc / USDJPYc / AUDUSDc / USDCADc / BTCUSDc；入场周期 M15 / M30 / H1 / H4。
• 自动生成风控：ATR 动态 SL/TP + 波动/点差闸；参数面板暴露策略参数与风控参数，改完点「保存参数」再回测对比。
• 槽位分配：启动后占用 auto31+，在对应品种的自动交易页统一管理；可在面板上一键停止。
• 安全边界：生成代码只做纯指标计算，禁止网络 / 文件 / 进程 / 动态执行类调用；回测基于本机 MT5 历史，回测不代表未来收益。

六、策略体系

6.1 精选精良准入闸（四项静态规则）

1. 点差/ATR 运行时复核（SL 距离 ≥ 10×点差）
2. 止损 ≥ 10×点差（sl_spread_mult ≥ 10）
3. 盈亏比 ≥ 2.5（rr_target ≥ 2.5）
4. ATR 动态 SL/TP（sl_atr_mult / tp_atr_mult > 0）

外加运行时波动/点差闸：ATR÷点差 < min_vol_spread（默认 3.0）时本轮不开单。

6.2 回测口径

• 数据：本机 MT5 深度历史（黄金/白银/BTC/ETH/主流外汇各 ~10-12 个月，M5~H4 多周期 CSV）
• 4 个不重叠 3 个月窗口滚动验证，主窗口为最近 3 个月；成本模型按品种真实 tick_size / spread_points / contract_size
• 汇总指标：PF、净利（0.01 手）、胜率、最大回撤、夏普、跨窗口稳健性（robust）

6.3 当前精选阵容（strategies_db.yaml 为真源，15 槽位）

| 槽位 | 品种页 | 策略 | 亮点 | | --- | --- | --- | --- | | auto1-5 | 🥇 黄金 | gold6 / gold10 / gold1 / gold2 / gold8 | 夏普 5.54 / 5.07 / 3.60 / 2.78 / 2.01，回撤 ≤2.2%，全 robust | | auto11-15 | 💱 外汇 | fJPYH4_020 / 026 / 032 / 002 + fx6 | 全部净盈利（+8089 ~ +1953），头名 PF 4.20 | | auto21-25 | 🪙 比特币 | btc11 - btc15（熊市挖矿） | 全部净盈利（+204 ~ +76），回撤 <1% | | auto31+ | 动态 | 小策生成 | AI 生成策略专用槽位，面板启动后自动分配 |

每个槽位可配：strategy_id / lot / min_vol_spread / live_trading / loop_interval / symbol。

七、MCP 集成

面板内置 MCP Server（Streamable HTTP），WorkBuddy / Claude 等 MCP 客户端可直接调用：

{ "mcpServers": { "xuexue-ai-scan": { "url": "http://127.0.0.1:8888/mcp" } } }

| 工具 | 说明 | | --- | --- | | xuexue_status | 服务整体状态（在线 / 最近扫描 / 版本） | | xuexue_list_strategies | 策略目录 + 最近回测 + 精选标记 | | xuexue_account | MT5 账号 / 余额 / 净值 / 持仓 | | xuexue_auto_slots | 15 槽位运行状态与绑定 | | xuexue_scan | 触发一次综合扫描 | | xuexue_fundamental | 基本面快照（情绪 / 指标 / 日历） |

面板「🧩 AI MCP」页提供端点健康、工具列表与一键注册到 WorkBuddy。

八、HTTP API 速查

| 方法 | 路径 | 说明 | | --- | --- | --- | | GET | /api/status | 服务状态（含 version） | | GET | /api/config | 当前配置 | | GET | /api/quotes /api/quotes-analysis | 实时报价 / 含指标 | | GET | /api/mt5-status /api/mt5-terminals | MT5 连接状态 / 终端探测 | | GET | /api/scan-last /api/scan-history /api/logs | 扫描结果与日志 | | GET | /api/auto-slots /api/strategies /api/strategy-library /api/strategy-status | 槽位与策略目录 | | GET | /api/fundamental /api/quant-arch/status | 基本面快照 / 六层架构状态 | | GET | /api/ai/status /api/ai/providers /api/ai/traders | AI 能力状态 | | GET | /api/ai-strategist | 小策已生成策略列表 | | GET | /api/mcp/servers /api/mcp/health | MCP 注册与连通性 | | POST | /api/mt5-connect /api/mt5-disconnect | 一键连接 / 断开（空 payload 回退已保存账户） | | POST | /api/scan /api/analysis /api/order | 扫描 / 分析 / 下单 | | POST | /api/strategy-start /api/strategy-stop /api/backtest | 槽位启停与回测 | | POST | /api/ai/chat /api/ai/agent /api/ai/multi /api/ai/tool | AI 对话与工具 | | POST | /api/ai-strategist/generate /backtest /launch /validate /refine /params | 小策六步闭环 | | POST | /api/ai/trader/set /simulate /iterate | 小雪交易员 | | POST | /api/mcp/server /api/mcp/register-self /api/mcp/test | MCP 管理 |

完整列表以 panel/server.py 的 do_GET / do_POST 路由分支为准。

九、目录结构

xuexue-ai-scan/
├── panel/
│   ├── index.html            # 单页前端（全部页面，含小策 / MCP / 引导页 / 使用说明）
│   ├── server.py             # 面板后端（行情/扫描/AI/基本面/MCP API，监听 8888）
│   └── trader_xiaoxue.py     # 小雪 AI 交易员引擎（纯标准库离线）
├── src/                      # Python 核心库
│   ├── scanner.py            # 行情扫描主逻辑
│   ├── fundamental.py / fundamental_snapshot.py  # 基本面信号 / 快照（新闻+指标+日历+情绪，5 分钟调度）
│   ├── news_feed.py          # 13 路新闻源聚合（rss/jin10/wsc/sina/sina7x24）
│   ├── news_sentiment.py     # 新闻情绪因子
│   ├── econ_calendar.py      # 宏观指标卡（FRED 利率/非农/CPI + 下次公布）
│   ├── indicators.py / mt5_connector.py / mt5_session.py / macro_data.py
│   ├── strategy_backtester.py   # 向量化回测内核（4 窗切分 / Monte-Carlo / PSR·DSR）
│   ├── signal_tracker.py / signal_evaluator.py
│   └── ai_agents.py / ai_assistant.py / ai_llm.py / ai_tools.py
├── strategies_catalog.py     # 策略目录（生产 30 套 + 250 外汇候选 + 小策动态注册）
├── strategies_db.yaml        # 槽位绑定真源（15 槽：lot / min_vol_spread / 策略）
├── strategy_auto.py          # 自动交易引擎主循环（含波动/点差闸、健康加权仓位）
├── risk_control.py           # 跟踪止损 / 分批止盈 / 日内熔断
├── backtest.py               # 单/组策略回测 CLI（写 logs/backtest_<id>.json）
├── backtest_universe.py      # 全量生产策略 4 窗回测汇总
├── mine_btc.py               # BTC 熊市挖矿（快筛 → 4 窗验证 → 家族去重）
├── mine_fx_health.py         # 外汇候选池挖掘（250 套）
├── fetch_fx_history.py       # MT5 深度历史拉取（外汇 5 品种 × 5 周期）
├── save_mt5_history.py       # MT5 历史落盘（金/银/BTC/ETH）
├── quant_arch/               # 六层量化架构（数据/因子/策略/风控/实盘/监控）
├── scripts/serve_single.js   # 单端口启动器（npm start）
├── config.example.yaml       # 配置样例
├── VERSION                   # 版本真源（面板运行时读取并显示）
├── data/                     # 离线行情 CSV 与 AI 策略（运行时生成，config.yaml 不入包）
└── docs/                     # 技术文档、使用指南与回测报告

十、命令行工具

npm start                              # 启动面板（单端口 8888）
npm run scan                           # 单次行情扫描（standalone_scan.py）
npm run connect                        # MT5 连接检查
npm run analysis                       # 分析快照
npm run install:py                     # pip install -r requirements.txt

# 策略研究与回测
python backtest.py --ids gold6,btc11 --months 12   # 指定策略回测
python backtest_universe.py                        # 全量策略 4 窗回测汇总
python mine_btc.py --screen 2 --top 14             # BTC 挖矿（两段式）
python mine_fx_health.py --limit 250               # 外汇候选池挖掘
python fetch_fx_history.py --days 300              # 补拉外汇深度历史
python save_mt5_history.py                         # 金/银/BTC/ETH 历史落盘

十一、配置要点（config.yaml）

scanner:
  weights:
    fundamental: 0.4     # 基本面权重（主源：快照多空分类）
    news: 0.25           # 回退源：新闻情绪
  use_llm_fundamental: false   # 基本面信号源 = 分类情绪（非 LLM）

strategies:
  auto1:
    strategy_id: gold6
    lot: 0.01
    min_vol_spread: 3.0      # ATR÷点差 低于此值不开单，0 = 关闭
    live_trading: false      # false = 监控模式（只记录信号）；true = 真实下单

llm:
  active: sensenova          # 默认商汤 SenseNova（可切 OpenAI/DeepSeek/…）
  providers:
  - name: sensenova
    base_url: "https://token.sensenova.cn/v1"
    api_key: "${SENSENOVA_API_KEY}"   # 用环境变量占位，避免明文

字段以 config.example.yaml 为准；槽位参数（策略绑定 / 手数 / min_vol_spread）在 strategies_db.yaml（真源）与 config.yaml 的 strategies 段双向同步，面板改动即落盘。 config.yaml 含真实账户信息，不随 npm 包发布（.npmignore + files 白名单双重排除）。

十二、打包与发布

# 1. 升版：同步修改 VERSION 与 package.json（面板会实时读取 VERSION 显示）
# 2. 预览打包内容（files 显式白名单；config.yaml/.env 已双重排除）
npm pack --dry-run

# 3. 维护者发布（token 临时传入，不落全局）
npm publish --access public --userconfig /path/to/xxcf_npmrc

files 清单已覆盖运行时全部依赖闭包：panel/*、src/* 核心模块、 strategies_catalog.py、strategies_db.yaml、strategy_auto.py、risk_control.py、 回测/挖矿 CLI、quant_arch/、docs/、config.example.yaml、requirements.txt。

十三、已知限制

• MT5 依赖：行情与下单依赖本地 MT5 终端；终端离线时面板功能受限（只读缓存）。
• 历史数据深度：回测依赖本机 MT5 可提供的最大历史；外汇主品种默认拉取 300 天。
• 宏观指标种子值：FRED 网络受限时指标卡显示「末次真实值」并标注 stale，不伪造数据。
• AI 生成策略：小策产出的是统计意义上的候选策略，代码受限命名空间执行；必须先回测与自检再考虑实盘。
• 回测偏差：固定点差估算，未含滑点 / 隔夜费 / 流动性冲击；回测不代表未来收益。

十四、免责声明

本项目仅用于学习与技术研究，所有信号、策略与 AI 研判不构成任何投资建议。 交易涉及高风险，可能导致本金损失。使用者须自行承担一切交易后果，作者与维护者不承担任何盈亏责任。 请在合规前提下使用，并遵守所在地区法律法规与经纪商条款。