workbuddy-qmt-bridge
WorkBuddy-QMT Bridge
WorkBuddy/MCP 与大 QMT 内置 Python 之间的本机、失败关闭型交易桥接器。
重要风险提示
本项目能够触发模拟或真实资金账户的委托,不构成投资建议,也不保证盈利。默认模式为 OBSERVE_ONLY。任何真实资金部署都必须先完成目标 QMT 版本、券商柜台、账户字段、委托回报、撤单与恢复流程的现场验收。仓库中的示例映射不能直接用于实盘。
5 分钟只读上手
首次目标只有一个:让 WorkBuddy 能查询 QMT,同时保持 OBSERVE_ONLY,不实际报单。
从 GitHub Releases 下载完整 ZIP 并解压到独立目录;
双击
安装、升级或修复.cmd,安装器会自动校验 wheel 哈希并启动中文配置向导;按自动打开的账户目录中的
部署说明.txt,把qmt_adapter.py放入对应的大 QMT 策略并启动;双击桌面的
启动QMT桥接.cmd,直接按 Enter 使用安全默认模式OBSERVE_ONLY;双击桌面的
查看QMT桥接状态.cmd;它会先验证完整连接,再显示当前状态。所有项目显示“完成”后,重启 WorkBuddy 并调用qmt_health。
完整图文步骤见 快速开始。首次只读连接不需要签名 Profile,也不需要理解人工实盘或有限自动交易。
Related MCP server: IBKR MCP Server
当前版本
版本:0.3.6
阶段:P1 LIMITED_AUTO 软件控制面完成
MCP 工具:31 个
Python:Worker 需要 3.10 或更高版本
QMT Adapter:兼容 QMT 内置 Python 3.6 环境
运行边界:仅绑定 127.0.0.1,不依赖 xtquant
项目主页:https://github.com/peppaboar95/workbuddy-qmt-bridge
“P1 完成”只表示软件侧的结构化授权、额度预留、状态机、熔断和 Adapter 复核已经实现并通过本地测试,不表示任意真实资金柜台已经验收。
四种模式
模式 | 是否可能调用 QMT 报单 | 授权要求 |
OBSERVE_ONLY | 否 | 无;默认安全模式 |
SIM_SIGNAL | 是,仅限已人工确认的模拟柜台 | 本机切换模式,映射签名并通过风控 |
MANUAL_LIVE | 是 | 本机切换模式;逐笔审批或 1–60 分钟账户时间授权 |
LIMITED_AUTO | 是,可在许可期内重复报单 | 本机切换模式;同一交易日结构化 P1 策略许可 |
SIM_SIGNAL 不是“只生成信号但不下单”。如果错误连接到真实资金柜台,它仍可能调用 passorder,因此必须人工核对账户和柜台。
安全设计
preview_trade 与 submit_trade_intent 两阶段提交;
单笔优先使用 prepare_trade 合并快照刷新与预览;提交后使用一次 wait_trade_intent 有界等待;
提交时重新执行完整硬风控并比较风险决策指纹;
Worker 与 QMT Adapter 双端检查账户、模式、签名、TTL 和授权代次;
LIMITED_AUTO 许可绑定账户、证券、动作、策略/规则版本、交易窗口、下单类型及多层额度;
额度原子预留,限制单笔、累计金额、订单数、频率、并发、持仓敞口、回撤和连续失败;
PRE_SUBMIT 或 SUBMIT_CALLED 状态不会自动重发,未知结果保持 SUBMIT_UNKNOWN;
熔断后只能在本机恢复,并安全回到 OBSERVE_ONLY;
信用自动交易默认关闭,新信用负债需要额外显式许可和现场验收。
安装
普通用户优先从 GitHub Releases 下载完整 ZIP。安装器会自动核验 ZIP 内 wheel 的 SHA-256:
workbuddy-qmt-bridge-0.3.6.zip
workbuddy-qmt-bridge-0.3.6.zip.sha256
SHA256SUMS.txt
完整解压后双击 安装、升级或修复.cmd。旧名称 首次安装与配置.cmd 仍作为兼容入口。需要手工安装 wheel 时,下载:
workbuddy_qmt_bridge-0.3.6-py3-none-any.whl
Windows PowerShell:
python -m pip install .\workbuddy_qmt_bridge-0.3.6-py3-none-any.whl
workbuddy-qmt setup从 0.3.2 开始,重复运行 setup 或使用 setup --force 都会保留已有 qmt_profile.json。有意重置时必须指定账户,并提供专用确认词:
workbuddy-qmt setup --reset-profile main_stock --confirm-reset-profile RESET-QMT-PROFILE从源码开发安装:
git clone https://github.com/peppaboar95/workbuddy-qmt-bridge.git
cd workbuddy-qmt-bridge
python -m pip install -e .从只读到交易
运行 setup,创建本机配置、密钥、Worker 令牌和账户隔离目录;
将生成的 qmt_adapter.py 与 qmt_adapter.json 部署到对应 QMT 策略实例;
保持 OBSERVE_ONLY,完成心跳、账户、持仓、委托、成交和行情字段采集;
在目标模拟柜台完成 P0 映射验证并签名 Profile;
在 SIM_SIGNAL 完成最小数量、报单、成交、撤单、重启与未知结果恢复校对;
真实资金场景先使用 MANUAL_LIVE 小额验收;
只有 readiness 无阻断且策略边界明确时,才创建 LIMITED_AUTO P1 许可。
MANUAL_LIVE 的 1–60 分钟时间授权只免除逐笔人工审批;每笔仍必须重新同步、预览并通过硬风控。LIMITED_AUTO 的许可最长 720 分钟,但不能跨交易日,并受完整策略边界和累计预算约束。
启动时自动同步模式
启动桥接时,所选模式会自动同步到已启用账户的 Adapter 配置。新版 Adapter 默认在约 500ms 内读取模式变化,两种启动顺序均可使用。升级后须按账户部署说明更新一次 QMT 策略中的 Adapter 源码;之后切换模式无需手工修改 JSON。详见 日常使用。
QMT 环境限制 open/os 时,可按账户选择 mmap 传输,默认仍使用文件模式。mmap 需要两端共享的进程间锁接口;生成的策略包含消息签名密钥,部署前请阅读同步与密钥保护说明。
尚不确定目标 QMT 实际限制时,先运行 环境能力探针,获取文件、数据库、本机网络、共享内存和双向互斥的实测结果。
低延迟调用建议
单笔交易优先调用
prepare_trade,它会把账户、持仓、委托、成交和目标行情合并成一次同步,等待新快照后直接返回预览;它不会提交订单;多标的交易先用一次
request_sync,把同一账户的全部目标放入symbols,随后复用账户和持仓快照逐笔preview_trade,不要按标的重复同步;submit_trade_intent返回QUEUED后,只调用一次wait_trade_intent。如果等待超时,稍后按intent_id查询,绝不重新提交预览;新生成 Adapter 的命令轮询为 500ms,Worker 回报摄取为 250ms。已有部署必须重新生成并部署
qmt_adapter.py/qmt_adapter.json后才会使用新的 Adapter 周期;Adapter 每 5 秒刷新账户和持仓;委托/成交由 QMT 回调实时更新,并每 30 秒完整对账兜底。启动、
prepare_trade和显式request_sync仍会刷新委托/成交;上述优化不减少预览、确认、提交时硬风控或 Adapter 报单前复核。
LIMITED_AUTO P1 流程
在本机把 Worker 和对应 Adapter 切换为 LIMITED_AUTO;
调用 check_limited_auto_readiness,确认队列、快照、心跳、死信和 SUBMIT_UNKNOWN 均无阻断;
向操作者展示完整许可策略,并在明确确认后调用 authorize_limited_auto;
自动任务对每笔交易继续执行同步、预览、提交;
使用 get_limited_auto_status 观察剩余时间、订单数、金额预算和暂停原因;
健康、回撤或连续失败守卫触发时自动暂停;条件恢复后只能显式 resume_limited_auto;
结束时调用 revoke_limited_auto。撤销许可不会自动撤销券商侧已有委托。
已验证与未验证
本版本的本地增量测试覆盖:
schema v1 到 v2 迁移;
结构化 P1 许可;
预览、提交与额度原子占用;
策略版本绑定;
暂停、恢复与授权代次轮换;
Adapter 防篡改复核。
仍需按目标环境完成:
真实 QMT 与券商构建能力矩阵;
真实资金柜台的委托、成交、备注和撤单回报;
Windows ACL、备份、恢复和 SUBMIT_UNKNOWN 演练;
信用账户六类动作、字段量纲、资格、额度与负债规则;
小额人工实盘验收。
数据与隐私
runtime、数据库、WAL/SHM、日志、队列、执行日志、签名 Profile、密钥、Worker 令牌、账户号和本机 MCP 配置都不得提交到仓库或附加到 Issue。诊断材料必须先脱敏。
文档
快速开始:docs/QUICKSTART.zh-CN.md
日常使用:docs/DAILY-USE.zh-CN.md
升级、备份与恢复:docs/UPGRADE-RECOVERY.zh-CN.md
P0/P1 高级配置:docs/P0-P1-ADVANCED.zh-CN.md
排障与脱敏诊断:docs/TROUBLESHOOTING.zh-CN.md
兼容性矩阵:docs/COMPATIBILITY.zh-CN.md
在线 API 参考(GitHub Pages):https://peppaboar95.github.io/workbuddy-qmt-bridge/
单文件离线 HTML,零外部依赖;当前源码文档覆盖全部 31 个 MCP 工具、错误码、风控原因码与配置参考。可另存为
.html本地打开。
发布与安装:docs/README-RELEASE.zh-CN.md
P1 验证说明:docs/P1-VALIDATION.zh-CN.md
配置示例:examples/README.md
安全政策:SECURITY.md
License
本项目采用 MIT License,详见 LICENSE。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Connect any MCP client to MetaTrader 4/5 to read prices, manage positions, and place trades.
JW3.ai remote MCP server for market reads and confirm-gated trading execution.
Hosted MCP server for MT4 and MT5: read accounts, prices and candles, and place or close orders.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA portable MCP server that exposes Lighter trading to any MCP-capable agent with safety-first features like mode-based gating, two-step confirmations, and audit logging.2MIT
- FlicenseNot gradedqualityDmaintenanceProvides an MCP server for Interactive Brokers trading operations, managing an IBKR Gateway Docker container and exposing trading functionality through REST API and MCP endpoints.6-
- AlicenseNot gradedqualityDmaintenanceEnables AI trading agents to trade safely through any broker MCP server by recording every tool call and reasoning in a local blackbox, while enforing configurable guardrails such as symbol whitelists, order size caps, rate limits, and daily-loss circuit breakers before orders reach the exchange.MIT
- FlicenseNot gradedqualityBmaintenanceEnables local, fail-closed futures trading between WorkBuddy/MCP and InfiniTrader PythonGO v2, exposing 31 MCP tools for market and account queries, trade previews, and order submission while enforcing hard risk controls and an observe-only default.2-