# miniQMT

**Repository Path**: topkernel/miniQMT

## Basic Information

- **Project Name**: miniQMT
- **Description**: 可视化的miniQMT前端
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# miniQMT 期货策略框架

miniQMT 专属期货量化平台：**声明式策略（26 入场 × 8 出场任意组合）+ 多品种实盘 + 高保真回测（K 线子步 / tick 回放 / 多品种选股）+ ML 市场状态识别 + pywebview 桌面交易程序（TradingView Lightweight Charts）**。所有数据走 xtquant（无离线 CSV）。

> ## ⚠️ 风险免责与合规告知（实盘前必读）
>
> - **非投资建议**：本软件仅为策略开发/回测/实盘执行的工具框架，**不构成任何投资建议，不承诺盈利**。所有交易决策由使用者自行作出。
> - **期货高风险**：期货交易采用保证金杠杆，可能**损失全部本金甚至更多**。历史回测表现不代表未来收益。
> - **自担风险**：使用者须自行承担一切交易损失。软件按"现状"提供（见 [LICENSE](LICENSE)），作者不对任何直接或间接损失负责。
> - **程序化交易报备**：在中国境内使用程序化/自动交易，**使用者须自行向期货公司及交易所完成"程序化交易报备"**。未报备实盘可能被限制交易或监管处罚。
> - **报单频率自律**：交易所对程序化报撤单频率有自律要求（过度报撤单→警告/限制交易/异常上报）。本框架提供 `max_orders_per_window` 报单频率上限（见下文风控），**实盘前须向开户营业部确认具体阈值并据此配置**。
> - **严禁代客理财**：本软件仅供个人自有账户使用，**严禁用于代他人理财、集资、或任何受托理财业务**（涉期货投资咨询/资管牌照监管）。

> 详细设计见 [docs/DESIGN.md](docs/DESIGN.md)，AI 辅助开发见 [CLAUDE.md](CLAUDE.md)，策略测试结论见 [docs/STRATEGY_REPORT.md](docs/STRATEGY_REPORT.md) / [docs/TREND_REPORT.md](docs/TREND_REPORT.md) / [docs/AG_REPORT.md](docs/AG_REPORT.md)。

## 核心能力

- **声明式策略**：一份 YAML = 一个策略（选入场 + 选出场 + 配调度），零代码。内置 **26 种入场 + 8 种出场**，可任意组合。
- **多品种实盘**：每秒扫描 N 个品种，按品种独立判断、独立持仓、独立出场；主力连续码自动换月。
- **ML 市场状态识别**：XGBoost + LSTM 判震荡/趋势，震荡→均值回归、趋势→突破自动分流。
- **高保真回测**：保守盘中路径（不利极值先到）+ 维持保证金强平 + 手数敏感滑点；tick 级回放与实盘事件同源。
- **阶梯出场**：初始止损 → 保本 → 移动止盈 → 尾盘，每品种 / 每笔 Trade 独立状态；另有海龟五档、剥头皮固定跳数等出场。
- **风险定仓**：每笔固定亏总权益 1.5%，ATR 自适应手数；与出场止损同源。
- **61 品种内置档**：覆盖六大交易所（上期/能源/大商/郑商/中金/广期），含乘数/保证金/tick/手续费（开/平今/平昨分别计）/交易时段。
- **纯逻辑可单测**：核心层不依赖 xtquant，**176 项单测**。

## 架构

```
mqmt/
├── strategy/
│   ├── interface.py          策略契约(Strategy/Context/Action/Registry)
│   ├── declarative.py        ★声明式引擎(读 sched/*.yaml → 运行)
│   ├── regime.py             ★市场状态判断(ML震荡/趋势 + ADX兜底 + &&/||组合)
│   ├── components.py         组件化(EntrySignal + ExitRule → ComposableStrategy)
│   ├── trade.py              Trade对象 + TradeManager(每笔独立状态, FIFO平仓)
│   ├── sizing.py             ATR 风险定仓
│   ├── ind_cache.py          指标缓存(策略读, 禁止对 ctx.bars 重算)
│   ├── ma_portfolio.py       多品种 MA 突破策略(每品种自管状态)
│   ├── eod_squeeze.py        尾盘挤压策略(尾盘时间窗吃均值回归)
│   ├── builtin.py            demo 策略: 双均线交叉 sma_cross
│   ├── sched/                ★声明式策略配置(每份 YAML = 一个策略, 29 个已注册)
│   ├── entries/              入场模块: 26 种(ma_cross/breakout/mean_revert/vwap_scalp/dual_thrust/orb/...)
│   └── exits/                出场模块: 8 种(stepped/atr_stop/ladder/scalp/eod_close/...)
├── engine/
│   ├── base.py               ★引擎基类(模板方法统一 5 引擎公共循环)
│   ├── backtest.py           K线子步回测(保守盘中路径 + 强平 + 涨跌停)
│   ├── multi_asset.py        多品种选股回测(横截面 panel)
│   ├── tick_replay.py        tick 回放(高频, tick_stride 抽样提速)
│   ├── live.py               xttrader 实盘(多品种 + 状态持久化 + 对账 + 防重单)
│   ├── account.py            保证金账户(盯市/多空/今昨 rollover, TradeManager 驱动)
│   ├── matcher.py            撮合(手数敏感滑点/手续费/涨跌停/今昨拆分)
│   ├── risk.py               风控护栏(冷却/连亏/次数/熔断/保证金, 含 restore)
│   ├── state_store.py        实盘状态持久化(JSON, 重启续跑)
│   └── event_source.py       事件源(bar/tick/timer, XtEventSource + MockEventSource)
├── data/                     indicators(TA-Lib: ATR/MA/ADX/RSI/BB/Donchian/VWAP/KDJ/MACD) / features(ML) / xt_source / cache
├── analytics/                metrics(绩效+Sharpe/Alpha/Beta) / attribution(归因) / scoring(★标的选择打分排序)
├── viz/
│   ├── trader.py             ★pywebview 桌面交易程序(Flask 后端 + 前端 fetch 通信)
│   ├── report.py             独立 HTML 报告(浏览器直开)
│   └── static/               index.html / style.css / app.js + vendored lightweight-charts.js v4.1.3
└── utils/                    logger / timeutil / persistence / ml_window / ml_guard
tools/                        train_xgboost / train_lstm / train_regime (ML 训练, 数据走 xtquant)
tests/                        确定性K线夹具 + 各层单测(176 项, 不依赖xtquant)
```

## 安装

```bash
pip install -r requirements.txt        # 核心依赖(精确版本锁定): pywebview pandas numpy pyyaml
pip install -r requirements-optional.txt  # 可选: ML 策略 + TA-Lib + ruamel(不用 ML 则跳过)
pip install pytest                     # 测试可选
cp config.example.yaml config.yaml
```

> **依赖锁定（审计 L1）**：`requirements.txt` 用精确版本（`==`）而非 `>=`，防止 `pip install` 拉到未经测试/被污染的上游版本。升级依赖须手动改版本号 + 重跑全部测试。更高安全级别可用 `pip install --require-hashes`（需额外生成 `requirements.lock` 含 sha256）。
>
> `xtquant` 由 miniQMT 客户端附带，不在 requirements 中。`lightweight-charts.js` v4.1.3 已 vendored 在 `mqmt/viz/static/`，无需安装。TA-Lib 需单独装 C 库（Wheel: https://github.com/cgohlke/talib-build）。

## 已注册策略（29 个）

> 前 24 个是纯配置（`sched/*.yaml`），换入场/出场/参数只需改 YAML；后 5 个是代码策略。

| 策略 | 类型 | 说明 |
|---|---|---|
| `live_regime_switch` | **声明式·实盘** | 6 品种每秒扫描 → ML 判震荡/趋势 → 均值回归/突破分流 → 四档出场 |
| `趋势交易策略` | 声明式 | 海龟操作法(Donchian 突破 + 五档出场 + 金字塔加仓) |
| `震荡交易策略` | 声明式 | 均值回归(BB+RSI) |
| `日内短线操作` | 声明式 | 日内多空短线 |
| `1分钟VWAP微反转剥头皮` | 声明式 | VWAP 偏离剥头皮(固定跳数止盈止损) |
| `Dual Thrust突破` | 声明式 | 经典 Dual Thrust 区间突破 |
| `开盘区间突破` | 声明式 | ORB 开盘区间突破 |
| `Supertrend趋势翻转` / `三重Supertrend` | 声明式 | Supertrend 翻转 / 三重对齐 |
| `均线穿越` / `5-8-13 SMA多头排列` | 声明式 | MA 系突破/排列 |
| `EMA9-21+VWAP` / `VWAP回踩趋势` | 声明式 | VWAP 趋势系 |
| `MACD零轴穿越` / `动量ROC突破` | 声明式 | 动量系 |
| `ADX-DI趋势系统` / `布林带收敛突破` | 声明式 | ADX / 布林系 |
| `海龟双系统突破` | 声明式 | 海龟双 Donchian(20/55) |
| `Pin Bar价格行为` / `量价配合突破` | 声明式 | 价格行为 / 量价系 |
| `Heikin Ashi变色` / `RSI2超短回归` | 声明式 | HA 变色 / Connors RSI(2) |
| `菲阿里四价` | 声明式(组合) | 昨高/昨低突破 + 开价止损 |
| `xgb_rb` / `lstm_rb` / `three_price_ma` | 声明式(组合) | XGBoost / LSTM / 三价均价 + 四档出场 |
| `尾盘挤压` | 代码 | 尾盘固定时间窗吃均值回归(原油夜盘收尾) |
| `ma120_portfolio` | 代码 | 多品种 MA 突破(每品种自管状态) |
| `sma_cross` | 代码(demo) | 双均线交叉(教学) |

`py -m mqmt strategies` 列全部策略及默认参数。

## 用法

### 桌面交易程序（推荐入口）

```bash
py -m mqmt trader    # 或 py run.py 选 1
```

pywebview 窗口（实盘监控 + 回测双 Tab）：实盘监控 K 线/持仓/权益/统计实时刷新（700ms 轮询），回测选策略+选品种+选时间区间→净值/回撤/交易明细/盈亏分布/归因/月度收益。每次回测自动生成报告(CSV + JSON + HTML)。内置 61 品种选择弹窗、平台设置(实盘连接/风控/界面)、本地数据覆盖矩阵。

> pywebview 仅作窗口壳，UI 由本地 Flask 服务、前端经 `fetch('/api/...')` 通信（**不用** pywebview 的 js_api 桥——该桥在当前 WebView2 运行时会递归崩坏）。

### 回测（CLI，数据走 xtquant）

```bash
# 单品种(必填时间区间, 需 miniQMT 已下载该区间数据)
py -m mqmt backtest -s 趋势交易策略 --start 2024-01-01 --end 2024-06-30

# 多品种选股回测
py -m mqmt backtest -s 趋势交易策略 --symbols rb,SA,FG --start 2024-01-01 --end 2024-06-30

# 指定周期
py -m mqmt backtest -s 趋势交易策略 --period 15m --start 2024-01-01 --end 2024-06-30

# 交互式菜单
py run.py
```

引擎自动选择：多品种(>1)→ MultiAssetEngine；`need_tick=True`→ TickReplayEngine；否则→ K 线子步 BacktestEngine。

### 实盘

```bash
# config.yaml 配品种(universe) → dry-run(不下真实委托, 走 paper 账户)
py -m mqmt live -s live_regime_switch

# config.yaml 设 trading_enabled: true → 真实下单
```

### ML 训练（数据走 xtquant）

```bash
# 涨跌方向(供 xgb_rb/lstm_rb)
py tools/train_xgboost.py --symbol rb0 --code RB00.SHF --start 2024-01-01 --end 2025-06-30
py tools/train_lstm.py     --symbol rb0 --code RB00.SHF --start 2024-01-01 --end 2025-06-30

# 市场状态: 震荡/趋势(供 live_regime_switch)
py tools/train_regime.py   --symbol rb0 --code RB00.SHF --bar 5m --start 2024-01-01 --end 2025-06-30
```

### 标的选择（选品种打分排序）

`analytics/scoring.py` 按趋势涨跌幅 / 趋势效率 / 震荡度给品种打分排序，帮助选交易标的（桌面程序内集成为品种选择弹窗）。

### 声明式策略配置

一份 `sched/*.yaml` = 一个策略。入场从注册表选（26 种），出场从注册表选（8 种），可任意组合：

```yaml
# sched/my_strategy.yaml
schedule: {interval_seconds: 1.0, bar_period: 5m}
universe: [rb]                          # 交易标的(框架 resolve_instruments 解析规格)

entry:
  type: breakout                        # 入场: breakout/ma_cross/mean_revert/vwap_scalp/dual_thrust/orb/...
  lookback: 60
  ma_period: 60

exits:
  mode: turtle                          # 出场模式: turtle=海龟五档; 不设=四档ATR; 或 scalp/ladder/revert
  sl_mult: 2.0
  trail_atr: 2.0
  exit_lookback: 30

risk_pct: 0.015                         # 风险定仓(>0=每笔亏权益1.5%; 0=固定手数)
lots: 2
```

```python
# 注册(declarative.py 已有通用工厂, 按需添加)
@register_strategy("my_strategy")
def _make(params=None):
    return build_composable_from_yaml(load_strategy_config("my_strategy"), params)
```

## 测试

```bash
py -m pytest -q    # 176 项, 不依赖 xtquant
```

## 声明式框架核心（live_regime_switch 示例）

```yaml
# 每秒扫描 → ML 判市场状态 → 自动选入场 → 四档出场
schedule: {interval_seconds: 1, bar_period: 5m}
universe: [SA, TA, HC, FG, RB, M]       # 框架解析为主力连续码(SA00.CZCE/...)

regime:                                 # 市场状态判断
  classifiers: [xgb, lstm]              # 双模型(每品种独立; 缺失走ADX+日志告警)
  mode: and                             # 全判震荡→震荡; 全判趋势→趋势; 矛盾→空仓
  dead_band: 0.10                       # 置信度缓冲带(概率0.45~0.65不操作)
  fallback: adx                         # ML不可用/矛盾 → ADX兜底

entries:
  ranging:  {type: mean_revert}         # 震荡→均值回归(BB+RSI)
  trending: {type: breakout}            # 趋势→突破(Donchian)

exits: {sl_mult: 1.5, be_trigger_atr: 1.5, trail_atr: 2.0, eod_minutes: 5}
```

**执行机制**：bar_close（每 5 分钟）重计算 ML + 指标 + 触发价 → 缓存；timer（每 1 秒）只比较 `price vs 缓存阈值`（微秒级，零 ML 推理）。能抓 1 分钟级拉升，但 CPU 降 1000 倍。

## 平台中立原则

1. 不约束持仓时长（尾盘强平默认关闭，支持自然过夜）；2. 不约束交易频率（K 线子步 + tick 回放并存）；3. 不约束多空方向；4. 风控是安全边界（可配可关）而非交易模式；5. 策略语义完全由策略自决。一套引擎承载日内、波段、高频全谱。

## 风控护栏（实盘安全边界，config.yaml 可配）

套在所有策略之外的框架级护栏（`engine/risk.py` RiskGuard），**只拦截开仓，平仓/止损一律放行**：

| 规则 | 配置 | 默认 |
|---|---|---|
| 单次交易冷却 | `cool_down_short` | 300s |
| 连续亏损长冷却 | `cool_down_long` / `max_consec_loss` | 1800s / 3 |
| 单日交易次数上限 | `max_daily_trade` | 12 |
| 单日亏损熔断 | `daily_loss_limit` | 5% |
| 保证金占用上限 | `max_margin_usage` | 60% |
| **报单频率上限**（审计H2，防交易所程序化报撤单限制） | `max_orders_per_window` / `max_orders_window` | 0=关（实盘建议设如 30/60s） |

另有实盘专属护栏：维持保证金强平（margin_call）、对账偏离自动进安全模式（只平不开）、委托超时撤单、收盘撤单、kill-switch 一键全平全撤、崩溃恢复当日成交重放。

> ⚠️ **`trading_enabled` 默认 `false`（dry-run，不下真实委托）**。真实下单前在 `config.yaml` 设 `trading_enabled: true` 并填写 `account_id`，启动时会有醒目告警。**强烈建议先 dry-run 数日，核对 paper 账户与券商一致后再切真实下单。**

## 卸载与凭证清除

停用本软件时，为防止凭证/账户信息残留，手动删除以下内容：

```bash
rm config.yaml          # 含资金账号 account_id
rm CLAUDE.local.md      # 含天勤账号密码(若存在)
rm -rf logs/            # 含 account_id 与总资产的日志
rm -rf state/           # 含策略/风控/pnl 状态
rm -rf models/          # 含 ML 模型(.pkl/.pt + .sha256 签名)
```

> `config.yaml` / `CLAUDE.local.md` / `logs/` / `state/` / `models/` 均已在 `.gitignore`，不会被提交。但它们以**明文**存在本地磁盘——共享机器或二手盘需注意清除。