雪雪AI · 本地交易系统（单面板综合交易）

一款运行在本地的 MT5 实盘 交易辅助系统，前端为 零依赖单页应用（SPA），后端由 Python 提供行情 / 扫描 / 策略引擎。 以本机已登录的 MT5 终端为行情数据源，免 API Key。 当前版本 1.1.8：完成单面板综合交易系统整合——控制面板与自动交易面板合并为一个 http://127.0.0.1:8888/ 单页应用；并包含 1.1.7→1.1.8 的安全止血（所有 /api/* 增加 Host/Origin 本地白名单、实盘强提示、/assets/ 路径遍历闭环等）。

雪雪AI 现在是一个统一单页系统，全部功能在同一个 8888 端口、同一个页面内通过左侧导航切换：

| 模块 | 入口（侧边栏） | 说明 | | --- | --- | --- | | 仪表盘 | 📊 仪表盘 | 账户概览、行情快览、策略运行状态总览 | | 行情扫描 | 📡 行情扫描 | 技术面打分 + AI 基本面 / 宏观研判 + 当日财经新闻，综合评分排序；支持自动执行规则 | | 策略中心 | 🎯 策略中心 | 纯策略管理页：20 套策略槽（黄金 / 外汇），含策略介绍、运行状态、盈亏统计、参数配置、启停 | | 黄金 / 外汇自动交易 | 🥇 黄金自动交易 / 💱 外汇自动交易 | 20 个策略槽的快捷入口分组（黄金 1–10 / 外汇 11–20），直达对应策略槽 | | 策略库 | 📚 策略库 | 20 套策略的详细逻辑、回测指标与说明 | | 回测对比 | 📈 回测对比 | 策略回测结果对比分析 | | 技术面分析 | 📊 技术面分析 | RSI / MACD / 均线 / 布林 / ATR / ADX / KDJ 等多指标快照与超标标记 | | 市场报价 | 💹 市场报价 | 实时 tick 行情、涨跌 / 涨跌幅（红涨绿跌） | | 账户 | 👤 账户 | MT5 账户连接、持仓、权益、历史 | | AI 对话 | 🤖 AI 对话 | AI 聊天 / Agent / 工具调用 / 自动交易辅助 | | 指南 / 帮助 | 📖 指南 / ❓ 帮助 | 使用指南与帮助文档 |

单端口模式（npm start，默认）：系统统一监听 8888 一个端口，Node 启动器（scripts/serve_single.js）拉起后端 Python 服务并提供前端 SPA；无需多端口、无需反向代理。 旧版双端口（node scripts/serve.js，8899 / 8900）已弃用，前端已合并为单页，不再区分「控制面板 / 自动交易」两个独立面板。

⚠️ 实盘交易风险提示（必读）

本软件包含按信号向 MT5 自动下单的代码，实盘交易有亏损甚至爆仓风险。

• 随包发布的 config.example.yaml 默认 live_trading: false（仅监控、不下单），这是 fail-safe 默认值。
• 引擎在缺少该字段时同样回退为「仅监控」。
• 只有当你把某个槽位的 live_trading 显式改为 true 并启动策略时，才会真实下单。 此举代表你完全理解并自担全部实盘风险。
• 作者与版权持有人不对任何交易亏损负责。请先在「仅监控」模式下充分验证，再谨慎开启实盘。

✨ 功能

单页综合交易系统（8888）

• 行情扫描（📡 行情扫描）：技术面打分 + AI 基本面 / 宏观研判 + 当日财经新闻，综合评分排序；可配置自动执行规则、查看扫描结果与最近扫描历史。
• 策略中心（🎯 策略中心）：纯策略管理页——20 套策略槽（黄金 / 外汇），含策略介绍、运行状态、盈亏统计、参数配置与启停开关。
• 黄金 / 外汇自动交易分组：侧边栏「🥇 黄金自动交易」「💱 外汇自动交易」分组，分别直达黄金 1–10 / 外汇 11–20 策略槽。
• 20 套策略库：黄金 gold1–10 / 外汇 fx1–10，回测均达标（PF≥1.1 且净利为正）；每槽位独立进程、独立 magic（900001–900020）、独立日志。
• 策略库 / 回测对比：策略逻辑详解、回测指标与多策略对比分析。
• 技术面分析：RSI / MACD / 均线 / 布林 / ATR / ADX / KDJ 等多指标快照，超标颜色标记、卡片可隐藏。
• 市场报价：实时 tick 行情、涨跌 / 涨跌幅（红涨绿跌）。
• 账户：MT5 账户连接、持仓、权益、历史。
• AI 对话：AI 聊天 / Agent / 工具调用 / 自动交易辅助。
• 界面设置：雪雪冰蓝 / 极简 × 浅色 / 深色 4 套主题，界面与文字大小可调。

🤝 多 Agent 协同（AI 能力升级）

AI 对话页新增 「🤝 多Agent协同（专家会诊）」 模式，将原本单体通用 Agent 升级为协同架构， 整体提升专业度、覆盖度与决策稳健性：

┌─ 导演(Director) ──意图路由──▶ 技术面分析师 │ 新闻面分析师 │ 策略师 │ 宏观分析师 （并行扇出）
│                                            ▼ 共享 brief
│                                  综合研判官(Synthesizer) ──▶ 风控官(Risk Officer) 复核
└──────────────────────────────────────────────────────────▶ 最终交易研判 / 计划

• 角色分工：每个专家只持有其领域相关工具子集与专属 system prompt（技术面→报价/分析，新闻面→财经新闻， 策略师→策略目录/扫描，宏观→利率/美元传导），避免单一通用 prompt 在多任务下的注意力分散。
• 并行会诊：独立领域专家经 ThreadPoolExecutor 并发执行，延迟≈最慢专家而非累加（实测 4 专家并行较串行 ~4× 加速）； 多视角结论由综合研判官融合为统一、可操作的交易计划。
• AI 风控复核：涉及下单意图时，由独立风控官做合规/风险评审（不替代代码级 autotrade 风控闸门）。
• 意图路由：auto 模式按关键词自动派发相关专家；含「综合/全方位/会诊」等强意图词时触发全维度会诊。
• 后端：src/ai_agents.py（orchestrate 编排入口）+ 新路由 POST /api/ai/multi（SSE 流式，事件带 agent 维度）。
• 配置：config.yaml 的 agents: 段可开关各专家、切换 mode（auto/parallel/sequential）、调 max_concurrency 与 risk_review。

其余两种模式保留：纯对话（流式）、单体 Agent（调工具）。三者共用同一套 7 个工具与多厂商 LLM 客户端。

🧩 LLM 厂商配置（可视化多厂商管理）

AI 对话页侧栏新增 「🧩 LLM 厂商」 区块，点击 ⚙️ 管理厂商 打开管理弹窗，无需手动编辑 config.yaml 即可：

• 查看 / 管理多厂商：列出全部已配置厂商（名称、类型预设、base_url、模型、启用/激活态），支持 添加 / 编辑 / 删除。

• ⚡ 一键预设（内置 23 个主流厂商）：弹窗内以分组芯片列出全部厂商，点一下即自动填好 base_url、默认 model 与模型候选，通常只需再补 api_key：

  | 分组 | 厂商 | | --- | --- | | 国内主流 | DeepSeek、腾讯混元、通义千问、智谱 GLM、Kimi、豆包（火山方舟）、百度千帆、讯飞星火、MiniMax、零一万物、阶跃星辰 | | 国际主流 | OpenAI、Anthropic Claude、Google Gemini、Groq | | 聚合平台 | 硅基流动、OpenRouter、Together AI、One-API / New-API 网关 | | 本地部署 | Ollama、LM Studio、vLLM（无需 API Key，行情数据不出本机） | | 自定义 | 内部网关 / 自定义端点 |

• 模型可选可填：model 输入框带下拉候选（每个厂商预置常见模型，如 DeepSeek 的 deepseek-chat / deepseek-reasoner），同时允许自由输入以应对厂商模型更新。

• 预设说明内联提示：选中厂商后显示是否需要密钥、官方密钥/模型清单链接，以及易踩坑提示（如火山方舟需填 ep-xxxxx 接入点 ID、通义 base_url 必须带 /compatible-mode/v1）。

• 切换激活厂商：每个厂商可「设为激活」，激活项即为 AI 对话 / Agent / 多Agent 实际使用的模型。

• 测试连接：对任意厂商（含编辑中的草稿）发起一次最小连通测试，返回延迟与样例回复，快速验证 base_url / model / api_key 是否正确。

• 保存落盘：「💾 保存全部」经校验（名称非空 / 不重复）后写入 config.yaml 的 llm.providers + llm.active，并自动备份旧配置。

后端：GET /api/ai/providers（厂商列表 + 分组预设元数据）、POST /api/ai/provider-test（连通测试）、POST /api/ai/provider-save（校验 + 落盘）。预设库定义在 src/ai_llm.py 的 _PRESETS，可通过 preset_list() 读取；厂商 name 可自定义（如 my-deepseek），只要 preset 字段指明厂商即可继承端点与模型候选。api_key 支持留空（免鉴权内部网关 / 本地部署）或 ${ENV_VAR} 环境变量占位（避免明文落盘）。

安全提示：本面板为 本机 localhost 单用户 运行，厂商密钥与 config.yaml 处于同一信任边界；弹窗以密码框展示 api_key，请仅在可信环境使用。

🚀 快速开始

方式一：npm 全局安装（推荐）

npm install -g xuexue-ai-scan
npm start
# 浏览器打开 http://127.0.0.1:8888/   （单页综合交易系统）

npm start 默认启动单端口模式（8888），会自动探测本机 venv / 系统 Python 来运行后端服务，并在 8888 提供单页前端。

方式二：手动运行

pip install -r requirements.txt
npm start                 # 单端口 8888 模式

🌐 中 / English 双语支持

界面内置语言切换：点击页面右上角的 中 / EN 浮动按钮即可在中文与英文之间切换，选择会记入浏览器 localStorage，刷新后保持。

• 翻译通过内置 i18n 引擎实现：维护一份中→英词典，对页面文本节点与 title/placeholder/aria-label/alt 等属性做实时替换；动态渲染的内容由 MutationObserver 自动翻译，无需刷新。
• 默认语言为中文；所有可见 UI 文案（导航、标题、按钮、设置、状态、风险提示、面板切换等）均已翻译。
• 切换为纯前端行为，不影响任何行情 / 交易逻辑。

📌 更新说明

• 1.1.8（当前）：单面板综合交易系统整合——控制面板与自动交易面板合并为一个 8888 单页应用（零依赖 vanilla JS，无构建步骤）；新增「📡 行情扫描」独立扫描页、把原「策略·扫描中心」改为纯策略管理的「🎯 策略中心」、侧边栏「黄金自动交易 / 外汇自动交易」分组命名；同时包含安全止血 Quick Wins（Q1–Q6）：/api/* 增加 Host/Origin 本地白名单（挡 DNS 重绑定 / 跨进程误调）、/api/config 在任一槽位开启 live_trading=true 时回显强提示、/assets/ 先 unquote 再查 .. 闭环编码型路径遍历、/api/status 的 service_online 改为真实心跳、修正 strategy_auto.py 中 live_trading 矛盾注释、补 .gitignore/.npmignore。
• 1.1.7：新增 中 / English 双语切换（右上角浮动按钮，记忆于 localStorage）。
• 1.1.5：修复打包缺陷——原 1.1.4 漏发 src/mt5_session.py（启动即 ModuleNotFoundError 崩溃），已补入 files；并新增「单端口 8888 模式」（scripts/serve_single.js）。
• 已知小缺陷：包内无 assets/snowflake.png，面板 logo 显示 404（纯装饰，不影响功能）。

📖 文档

| 文档 | 说明 | | --- | --- | | docs/使用指南.md | 从安装到扫描的全步骤使用指南 | | docs/雪雪MT5接入.md | MT5 终端接入方式技术文档 | | docs/雪雪AI机会扫描.md | 机会扫描功能技术文档 | | docs/雪雪AI自动交易技术文档.md | 自动交易 / 20 套策略库技术文档 | | docs/控制面板UI升级计划书.md | 控制面板 UI 升级计划书 | | docs/控制面板UI升级技术文档.md | 控制面板 UI 升级技术文档 |

⚙️ 配置

复制 config.example.yaml 为 config.yaml 后填写你的信息（也可在面板直接修改并保存）。

cp config.example.yaml config.yaml

• 切勿把真实 config.yaml 提交或分发——它包含你的 MT5 账户与终端路径；已通过 .npmignore 排除，不会进入 npm 包。
• 环境变量可按需配置（参见 .env.example）。

🔗 相关链接

• EXNESS 开户：https://one.exnessonelink.com/a/zh/743861
• WorkBuddy 下载：https://www.workbuddy.cn/

📄 许可证

MIT（含实盘交易风险提示，详见 LICENSE）