快速开始¶

在 Windows 上启动 QMT Bridge，供局域网内 HTTP/WebSocket 客户端调用。自然语言工作流见 qmt-trading-skill。

桌面安装包（无需 Python）¶

给不熟悉命令行的 Windows 用户：把 miniQMT 封装成可双击的控制面板。客户机仍需先安装并登录券商 miniQMT（勾选「独立交易」）。

开发者在仓库根目录打包：

powershell -ExecutionPolicy Bypass -File packaging\windows\build.ps1
powershell -ExecutionPolicy Bypass -File packaging\windows\build.ps1 -Arch x64
powershell -ExecutionPolicy Bypass -File packaging\windows\build.ps1 -Arch arm64

产物在 packaging\windows\dist\：

文件	说明
`QMTBridge-Setup-<版本>-x86-win.exe`	Windows x64 安装包（Intel/AMD，ARM 电脑也可模拟运行）
`QMTBridge-<版本>-x86-win.zip`	同上便携版（含桌面面板 + `qmt-server.exe`）
`QMTBridge-CLI-<版本>-x86-win.zip`	仅 CLI：解压后直接运行 `qmt-server.exe` 启动服务
`QMTBridge-Setup-<版本>-arm-win.exe`	Windows ARM64 安装包
`QMTBridge-<版本>-arm-win.zip`	同上便携版
`QMTBridge-CLI-<版本>-arm-win.zip`	ARM64 CLI 便携包
`portable\` / `cli-portable\`	打包中间目录，可直接运行验证

GitHub 上创建 Release（v* tag）后，Release desktop 会自动编译并上传上述 exe / zip。券商 miniQMT 目前以 x64 为主，连交易请优先下 x86-win。

客户使用：

桌面：安装或解压 → 双击 QMT Bridge → 确认端口 / miniQMT 路径 → 启动。关闭窗口后程序仍在托盘运行，退出请用托盘菜单「退出」。
CLI：解压 QMTBridge-CLI-*.zip → 运行 qmt-server.exe（参数与 pip 版 qmt-server 相同，如 --port 8000 --trading）。须与同目录 runtime\ 一起拷贝，勿只拷贝单个 exe。配置以命令行参数为准；当前目录若有 .env 仅作缺省补充。

桌面版配置与日志在 %APPDATA%\QMT Bridge\。

开发模式（已有 Python 环境）也可直接：

pip install -e ".[full,desktop]"
qmt-desktop

前提条件¶

Windows 端（服务端）¶

Python 3.10+（仅源码 / pip 安装需要；桌面安装包已内置运行时）
QMT 客户端 — 已安装并获得券商账号密码（需联系客户经理开通 miniQMT 权限）
xtquant — 通常随 QMT 客户端安装，或 pip install xtquant（安装包会尝试内置）

网络¶

Windows 和你的主力机在同一局域网下（连同一个路由器 / WiFi）
Windows 防火墙放行本项目使用的端口（代码默认 8000，以 .env 的 QMT_BRIDGE_PORT 为准）

1. 安装¶

git clone https://github.com/atorber/qmt-bridge.git
cd qmt-bridge

# 安装服务端（含 WebSocket 支持）
pip install -e ".[full]"

# 或者只安装服务端（不含 WebSocket）
pip install -e ".[server]"

如果只需要在远程机器上使用客户端：

# 零依赖安装（仅 HTTP）
pip install -e .

# 含 WebSocket 订阅支持
pip install -e ".[client]"

2. 配置¶

cp .env.example .env
# 按需编辑 .env

详细配置项请参考配置参考。

3. 启动 QMT 客户端¶

打开 QMT，勾选 "独立交易" 模式登录，保持窗口运行（可最小化）。

4. 启动 API 服务¶

# 使用 CLI 命令（推荐）
qmt-server

# 自定义参数
qmt-server --port 8080 --log-level debug

# 启用交易模块
qmt-server --trading --api-key your-secret-key \
    --mini-qmt-path "C:\国金QMT交易端\userdata_mini" \
    --account-id 12345678

也可以使用脚本：

# 前台运行（Ctrl+C 停止）
bash scripts/start.sh

# 后台运行
bash scripts/start-nohup.sh
bash scripts/stop.sh

# Windows
scripts\start.bat
scripts\stop.bat

PM2 守护（崩溃自动拉起，推荐长期运行）¶

需先安装 PM2：npm install -g pm2，并完成 pip install -e ".[server,...]" 与 .env 配置。

REM 可选：指定 venv Python
set PM2_PYTHON=C:\path\to\venv\Scripts\python.exe

REM 仅启动 API（读 .env：端口、TRADING_ENABLED、DEFAULT_ACCOUNT 等）
scripts\pm2-start.bat

REM 或手动
pm2 start ecosystem.config.cjs --only qmt-server
pm2 logs qmt-server
pm2 restart qmt-server
scripts\pm2-stop.bat

信用户为默认账户时，在 .env 设置 QMT_BRIDGE_DEFAULT_ACCOUNT=credit 与 QMT_BRIDGE_TRADING_ENABLED=true 即可，无需改 ecosystem.config.cjs。

定时下载调度器（独立进程，按需）：

pm2 start ecosystem.config.cjs --only qmt-scheduler

开机自启（管理员 PowerShell）：pm2 startup → pm2 save。

日志文件：logs/pm2/。F5 调试仍用 .vscode/launch.json；PM2 用于无断点的后台守护。

5. 验证¶

在你的 Mac/Linux 浏览器中访问：

http://<Windows局域网IP>:<端口>/docs

端口以启动参数或 .env 为准（未配置时为 8000）。看到 Swagger 文档页面即表示服务正常。也可以用 curl 检查：

curl http://<Windows局域网IP>:<端口>/api/meta/health

Python 客户端用法¶

from qmt_bridge import QMTClient

client = QMTClient(host="192.168.1.100", port=8000)

# 历史 K 线
df = client.get_history("000001.SZ", period="1d", count=60)

# 增强版 K 线，前复权
dfs = client.get_history_ex(
    ["000001.SZ", "600519.SH"],
    dividend_type="front",
    count=60,
)

# 大盘行情一览
indices = client.get_major_indices()

# 实时快照
snapshot = client.get_market_snapshot(["000001.SZ", "600519.SH"])

# 板块
sectors = client.get_sector_list()
stocks = client.get_sector_stocks("沪深A股")

# 财务数据
fin = client.get_financial_data(["000001.SZ"], tables=["Balance"])

# ETF / 期权 / 期货
etfs = client.get_etf_list()
options = client.get_option_list("000300.SH", "20250321")
main_contract = client.get_main_contract("IF.CFE")

# 元数据
markets = client.get_markets()
periods = client.get_periods()
last_date = client.get_last_trade_date("SH")

交易（需要 API Key）¶

client = QMTClient(host="192.168.1.100", api_key="your-secret-key")

# 下单
order_id = client.place_order(
    stock_code="000001.SZ",
    order_type=23,        # 买入
    order_volume=100,
    price_type=5,         # 最新价
)

# 查询
orders = client.query_orders()
positions = client.query_positions()
asset = client.query_asset()

# 撤单
client.cancel_order(order_id)

WebSocket 实时订阅¶

import asyncio

def on_tick(data):
    print(data)

# 实时行情
asyncio.run(client.subscribe_realtime(
    stocks=["000001.SZ", "600519.SH"],
    callback=on_tick,
))

# 全市场行情
asyncio.run(client.subscribe_whole_quote(
    codes=["SH", "SZ"],
    callback=on_tick,
))