让外部 Python 通过本机文件队列读取大 QMT 内置 Python 暴露的数据接口。
GitHub：YangSal/qmt-python-bridge。Python 发行包名为 bigqmt-data-bridge，导入名为 bigqmt_bridge。
实验性 / Alpha · 只读 · 不下单 · 不自动下载历史数据
本项目从一个已有数据采集项目中提取。目标是保留外部 Python 的 pandas、研究和存储环境，让内置 Python 只承担有限的数据读取。它不是完整的 xtquant 替代品，也不保证任意券商版本、账号权限和数据种类均可用。
可以开源代码，不等于可以转授权行情。请自行确认券商、迅投及数据提供方的接口使用和数据再分发许可。本项目不附带 QMT、xtquant、券商源码、账号或真实行情样本，不提供权限绕过。
适合已经获得大 QMT 使用权限、希望在外部 Python 读取小规模历史样本并验证迁移的开发者。不适合直接接管实盘交易、全市场高频订阅，或未经验证替换整条生产采集流水线。
| 能力 | 实现情况 | 尚需验证 / 限制 |
|---|---|---|
| 文件协议、锁、超时、结果完整性 | 已实现并有离线测试 | 不等于真实客户端稳定性验收 |
| 日线 / 1分钟 / 5分钟 / Tick | 优先 C.get_market_data_ex_ori，外部构造 DataFrame |
新原始行情路径需要真实券商数据对照；缓存必须预先准备 |
| 复权因子 | 支持事件日期、七字段规范化 | 历史样本有返回记录，仍需跨端逐值对照 |
| 简版合约 | 可调用并保留返回字段 | 部分客户端公开封装只有约 30 个键，不能冒充完整合约 |
| 板块树 / 成员 | 通过全局板块树接口及 ContextInfo 取成员 | 大 QMT 显示名称不等于原生分类 ID，不能按名字猜主键映射 |
| 指数权重 | 先按人工确认的成分板块取全体成员，再逐批查询 | 需验证成员集合和权重单位；合计近 100 只是粗检查 |
| 财务八表 | 已有字段契约和验证逻辑 | 部分内置封装仍要求 pandas；不保证可运行或完整 |
download_* 兼容入口 |
仅检查用户的缓存准备确认 | 不会下载；没有每日缓存自动供应机制 |
| 原生 xtquant 基线 | CLI 可选，使用本地缓存接口 | 必须有仍可连接的授权原生环境；导入成功不代表连通 |
| 交易、实时订阅、任意代码执行 | 不提供 | 没有 XtQuantTrader、下单、撤单或任意 RPC |
已有离线测试使用合成数据和模拟 ContextInfo。即使全部测试通过，也不能据此宣称财务、完整合约或全市场 Tick 已具备生产接管能力。正式接入前应在自己的券商客户端重做验收。
外部 Python 3.10+ 大 QMT 内置 Python
bigqmt_bridge qmt_bridge.strategy
│ 写请求 JSON │
├──────── 本机独立 IPC 目录 ────────────────┤
│ 定时回调每 2 秒处理一个请求
│ 调用白名单 ContextInfo 接口
│ 读结果 manifest + gzip JSON │
└─ 校验 UUID / 协议 / 长度 / SHA256 ───────┘
在外部规范化为 pandas DataFrame
内置端自身只导入 Python 标准库；但它调用的券商封装可能自行导入 pandas。优先使用原始行情方法只解决相应行情封装的依赖问题，不会自动解决财务封装的 pandas 依赖。
请求只允许 probe、market_data、divid_factors、financial、instrument、sectors、sector_stocks、weights。普通客户端不需要手工操作协议文件。
以下命令为 Windows PowerShell。python 应指向你选择的 外部 Python 3.10+，不是内置 Python。
将源码解压或 clone 到 D:\bigqmt-data-bridge。如果使用其他路径，修改后续命令和策略内 PROJECT_ROOT。
Set-Location D:\bigqmt-data-bridge
python --version
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[test]"
.\.venv\Scripts\python.exe -m bigqmt_bridge --help
Copy-Item -LiteralPath config.example.json -Destination config.local.json后文使用 .\.venv\Scripts\python.exe。如果你使用现有 conda 环境，可以替换为该环境解释器的完整路径，无需另建 venv。
外部依赖为 pandas；pytest 只用于开发测试。不要求安装 Redis、ZMQ、数据库驱动或外部 xtquant。仅在生成原生基线时需要你自己已有的 xtquant 环境。当前发行包声明的 Python 版本范围只针对外部客户端。
-
启动并登录已授权的大 QMT 客户端，进入支持内置 Python 的策略编辑环境。
-
在编辑器中新建普通 Python 策略，打开或粘贴
qmt_bridge/strategy.py的完整内容。各券商菜单名称可能不同。 -
核对脚本开头两个路径：
PROJECT_ROOT = r'D:\bigqmt-data-bridge' BRIDGE_DIR = r'D:\bigqmt-data-bridge-runtime'
PROJECT_ROOT是包含qmt_bridge子目录的源码根目录；BRIDGE_DIR是独立运行目录，不是源码目录，也不要指向其他桥正在使用的目录。 -
使用客户端支持定时回调的运行方式启动策略，不用历史回测结果证明桥在线。脚本通过
C.run_time('bridge_poll', '2nSecond', ...)注册回调，handlebar不承担取数工作。 -
确认日志出现
QMT data bridge ready: ...。还需要下一步外部 probe 验证定时器实际工作。
策略文件使用 ASCII，便于兼容需要 GBK 的编辑器。路径若包含中文，需自行保证编辑器保存编码与文件编码声明一致；建议初次测试使用纯英文路径。
不要在内置 Python 中运行 pip install .，也不要把外部 Python 的 site-packages 加入其路径。内置端只加载源码根目录里的 qmt_bridge 包。离线测试检查了 Python 3.6 语法，但不保证每个券商环境都提供同一套 API。
升级服务端时，先确认没有活跃客户端请求，再停止该桥策略、更新文件并重新启动。修改 Python 文件不会自动让已运行的策略加载新实现。不要为测试随意停止已有生产桥。
config.local.json 的 bridge_dir 必须与脚本中的 BRIDGE_DIR 一致。运行：
.\.venv\Scripts\python.exe -m bigqmt_bridge probe --config config.local.json --timeout 5 --output evidence\probe.json标准输出给出简短结果，完整探测保存在 evidence\probe.json。成功退出码为 0，失败为 1；参数格式错误通常为 2。
本版本 probe 报告包含 worker_version: 2、market_reader、Python 版本、方法是否 callable、板块树接口是否存在。ok: true 表示探测条件通过，不表示这些方法已经成功返回真实数据。缺少某个被探测的方法也会让总体 ok 为 false，需查看详细字段，不要一律当作文件连接失败。
本项目并不要求绑定账号 ID；登录和接口权限由客户端管理。
先在 QMT 的数据管理界面准备指定品种、日期和周期的历史缓存，核对下载完成且内容新鲜。仅在确认后，将 config.local.json 中：
"cache_prepared": true该标志是人工确认，不是缓存检测器，不会触发下载；维护期间不能用它让失败“变成功”。
以下使用固定北京时间交易日作为示例，请改成两端都已准备的真实日期：
.\.venv\Scripts\python.exe -m bigqmt_bridge sample --config config.local.json --date 20260904 --codes 000001.SZ --periods 1d --families market --output evidence\bridge-daily.json样本文件包含采样范围、字段、逐行数据、错误和每类耗时。它不连接数据库、不下单，也不会调用历史下载接口。
以下代码在源码根目录运行；安装后也可以在其他目录运行，但应传配置文件的实际绝对路径。
from bigqmt_bridge.backend import create_backend
from bigqmt_bridge.config import load_config
xtdata = create_backend(load_config(r'D:\bigqmt-data-bridge\config.local.json'))
frames = xtdata.get_market_data_ex(
field_list=['time', 'open', 'high', 'low', 'close', 'volume', 'amount'],
stock_list=['000001.SZ'],
period='1d',
start_time='20260904',
end_time='20260904',
count=-1,
dividend_type='none',
subscribe=False,
fill_data=False,
)
print(frames['000001.SZ'])frames 是 {代码: DataFrame}，time 为 UTC 毫秒。转换北京时间使用：
import pandas as pd
frame = frames['000001.SZ']
beijing_time = pd.to_datetime(frame['time'], unit='ms', utc=True).dt.tz_convert('Asia/Shanghai')不要依赖机器时区、datetime.now() 的默认日期或 time.localtime()。12 位的早期毫秒时间戳和 13 位毫秒时间戳均有专门处理。
异常类型为 bigqmt_bridge.QmtDataError。调用者应记录失败并保留证据，不应把桥错误当成“停牌”“空交易日”或“板块已删除”。本项目没有数据库写入层，也不会替调用方回滚已经写入的批次。
在仍可用的原生 QMT / MiniQMT 授权环境中，安装本项目外部客户端，然后用该环境的 Python 执行：
python -m bigqmt_bridge sample --backend native --date 20260904 --codes 000001.SZ --periods 1d --families market --output evidence\native-daily.json原生取样使用 xtdata.get_local_data；本工具不补下载。确保原生端也已具备同日缓存。可以在另一台机器生成基线后复制到本机受控的 evidence 目录。
原生 probe 只测试能否导入 xtquant，报告含 import_only: true，不是客户端连通性验证。大 QMT 已登录不代表原生服务同时可连接；不要为了取得基线擅自切换生产客户端的登录模式。
.\.venv\Scripts\python.exe -m bigqmt_bridge compare evidence\native-daily.json evidence\bridge-daily.json --output evidence\daily-diff.json比较范围、日期、代码、周期、字段、行数与每个值。整数精确比较，浮点相对/绝对容差均为 1e-9；数组次序保留，重复行不会被丢弃，最多记录 100 个错误。不同 scope 的样本不能验收通过。
compare 不验证样本来源身份：复制同一文件两次也可能相等。跨端验收还需保留两端实际生成命令、项目/解释器/客户端版本以及原始报告；没有独立原生来源记录时，只能称为文件内容相等，不能称为迁移验收通过。
空对象、空帧、缺码、缺列、错误报告都会使验收失败，即使两边都为空。无复权事件的合法空样本需要另选有效样本或人工说明，不代表所有空值都是数据源故障。不得为通过比较而只取字段交集、猜单位、静默重标权重或改写源数据。
已返回的核心行情字段（time、OHLC、lastPrice、volume、amount）必须是非布尔的有限数值，不能以 null、NaN、Infinity 或字符串冒充有效价格/量额；合法零成交量允许保留。此规则仅用于行情，不把财务字段中的所有空值一律视作错误。
在上述 sample 命令上替换这些参数；未验收接口可能明确失败：
| 数据 | 参数 | 先决条件 |
|---|---|---|
| 分钟线 | --periods 1m --families market |
对应日分钟缓存 |
| Tick | --periods tick --families market |
近期 tick 缓存和全部严格字段；先单股单日 |
| 复权事件 | --families divid |
历史复权数据；从 1990 到指定日期取样 |
| 财务八表 | --families financial |
内置依赖、字段、历史版本均需验证 |
| 完整合约 | --families instrument |
instrument_fields 来自完整原生基线 |
| 板块 | --families sectors --sectors 沪深A股 |
树根与成员身份明确 |
| 指数权重 | --families weights --indices 000300.SH |
已验证的 index_sectors 映射 |
--codes 最多 10 个唯一代码。CLI 行情样本逐股请求；Python 客户端 K 线可每批最多 10 股，Tick 每批仍仅 1 股。
配置是扁平 JSON，不包含顶层 qmt 键，不读取原采集项目配置，也不自动读取环境变量。未知键会报错，避免拼写错误静默生效。
| 键 | 缺省行为 | 说明 |
|---|---|---|
backend |
file_bridge |
native 仅供 CLI 基线；create_backend 只创建文件桥 |
bridge_dir |
无，文件桥必填 | 独立 IPC 目录；相对路径相对于配置文件目录解析 |
cache_prepared |
未确认，取行情/复权/财务失败 | 只能是 JSON true/false；不是自动下载或新鲜度检测 |
timeout |
probe 5 秒、sample 60 秒 | 每次请求等待上限，不能硬中断内置调用 |
poll_interval |
0.1 秒 | 外部检查响应间隔，不改变服务端 2 秒调度周期 |
batch_size |
10 | 整数 1～10；Tick 固定 1 |
sector_root |
空字符串 | 部分客户端需要真实根节点名称 |
instrument_fields |
空列表 | 完整合约的必需键全集，必须来自可靠原生基线 |
index_sectors |
空对象 | 指数代码到已验证成分板块的映射，不自动猜中文名 |
命令行 --backend、--bridge-dir、--timeout 优先于配置；配置优先于默认值。命令行 --bridge-dir 的相对路径相对于当前工作目录，建议使用绝对路径。未指定 --config 时不自动寻找 config.local.json。
财务契约在 bigqmt_bridge/schemas/financial.json，包含 Balance、Income、CashFlow、Pershareindex、Capital、Holdernum、Top10holder、Top10flowholder 八表请求字段。它是客户端的严格合同，不是券商 API 支持声明。不要通过删掉缺失字段来掩盖兼容问题。
外部对象提供以下有限的 xtdata 风格方法，详细签名见 backend.py：
probe()
get_market_data_ex(...), get_local_data(...)
get_divid_factors(stock_code, start_time='', end_time='')
get_instrument_detail(stock_code, iscomplete=False)
get_sector_list(), get_stock_list_in_sector(sector_name)
get_index_weight(index_code)
get_financial_data(stock_list, table_list=None, ...)
download_history_data2(...), download_financial_data2(...), download_index_weight()
最后三个方法只是兼容确认入口，不执行下载。此版本不提供 get_full_tick、实时订阅回调、交易接口，也不支持把任意 xtquant 调用原样透传。外部 get_local_data(data_dir=...) 不能选择内置端缓存路径，会明确报错。
| 现象 | 检查与处理 |
|---|---|
QMT bridge timeout |
对比两端目录、ACL、策略日志、定时器是否运行、GUI 是否被阻塞；停止自动重试后再调查 |
No module named qmt_bridge |
PROJECT_ROOT 必须指向包含该包的源码根目录；不是包自身目录 |
No module named pandas 出现在内置端 |
确认报错接口及 market_reader；原始行情可能绕过该依赖，财务封装仍可能需要它；不能混装外部 Python 库 |
cache_prepared 错误 |
人工确认实际缓存后再设置；不能为绕过错误直接改 true |
empty QMT cache / 缺字段 |
核对代码、周期、日期、下载、权限及维护状态；空不是验收成功 |
complete instrument contract requires... |
从原生完整基线整理字段全集；简版返回不能用来定义“完整” |
| 板块列表有名称但不匹配原生分类 | 核对分类提供商、层级、稳定身份和成员，不按同名直接映射 |
index_sectors must map... |
先验证指数成分全集，再配置；单股权重能返回不说明全集正确 |
| worker 锁被占用 | 不删活跃锁、不抢占；查明持有者，确认无活跃请求后按授权停止旧策略并重启 |
原生 无法连接xtquant服务 |
登录大 QMT 不代表原生服务在线；从仍获授权的原生节点取基线 |
| 响应超出上限 | 缩小日期窗口或标的批量；当前无自动大窗口拆分 |
维护、服务器空返回和接口结构性差异必须区分。等待维护结束可解决暂时性问题，但不能修复缺依赖、固定字段投影或分类命名差异。
- 信任边界是本机目录权限。 SHA256 用于损坏检测，不是签名或身份认证。目录可写者能伪造数据；不要把 IPC 目录开放给不可信用户或放到公开共享、Git仓库同步和云盘同步目录中。
- 请求 UUID 和 deadline、协议版本、长度等被检查；结果数据先发布、manifest 后发布。坏请求隔离，进程锁避免多个 worker 同时消费；崩溃后的只读请求可能重放，因此不要扩展为交易通道而沿用此语义。
- 请求 JSON 上限 1 MiB，单响应未压缩 JSON 上限 64 MiB；这些不是完整内存占用上限，大返回值在序列化前仍可能占据较多内存。
- 服务端每 2 秒处理一个工单。5000 股 Tick 仅调度下限约 2.8 小时，还没计读缓存和序列化。先测 10 / 100 / 全市场耗时，不要直接调大生产超时掩盖瓶颈。
- 外部超时只结束外部等待，不能硬中断 QMT 内置 API。不要持续堆积新请求；恢复可能需要用户停止策略或重启客户端。
- 工单、结果及异常证据暂不自动清理。监控磁盘，制定保留期；仅在确认消费者和 worker 停止后清理已消费且不再需要的明确文件，勿递归清空运行目录。
- 真实结果可能含受许可限制的数据和运行路径，
evidence/默认忽略，不上传公开仓库或公开 issue。
生产切换应是独立工作：逐通道只读对照、至少连续多个交易日验收、缓存自动供应与容量测试通过后，再安排停旧调度/启新调度。不要同时运行两个写入相同目标的采集器，不要在活跃采集目录热替换代码。保留回退条件，但原生权限已取消时不能承诺能回退。
附带 skills/bigqmt-data-bridge/SKILL.md。这是本项目专用的参考技能，不是一般交易技能；包含实际命令、路径规则、采样契约和故障判定。
使用方式任选一种：
- 在对话中提供该文件的路径，要求智能体先完整阅读，再执行指定的探测或取样任务。
- 将整个
skills/bigqmt-data-bridge文件夹复制到智能体支持的技能目录。例如 Codex 的个人技能目录通常为%USERPROFILE%\.codex\skills，也可放在目标项目的.agents\skills中，由该工具的发现机制加载。
技能无需与源码相邻安装，不会自动寻找私人采集仓库。调用时提供项目目录、外部 Python 路径、配置/IPC目录、明确北京时间日期和代码。例如：
使用
$bigqmt-data-bridge。项目在D:\bigqmt-data-bridge，外部解释器是该项目.venv\Scripts\python.exe，配置是config.local.json。只读验证20260904的000001.SZ日线，保存证据，不重启 QMT、不下载、不写数据库。
本仓库只是附带技能文件，不会自动安装到你的个人技能目录。技能不能赋予操作账号、安装券商依赖、发布数据或切换生产的额外权限。
Set-Location D:\bigqmt-data-bridge
.\.venv\Scripts\python.exe -m pytest tests -q测试使用临时目录和合成数据，不连接真实 QMT。覆盖协议往返、损坏/超时/过期、锁、字段完整性、Tick 大整数和盘口、财务身份、采样对比、独立配置与 Python 3.6 语法。这里的 Python 3.6 检查是语法检查，不是完整的 Python 3.6 运行时认证。
bigqmt_bridge/ 外部客户端、CLI、规范化、JSON字段契约
qmt_bridge/ 内置端策略、worker、文件协议（标准库）
tests/ 离线回归测试
skills/ 可复制给智能体的技能
docs/ 拆分设计、实施记录、验证与发布清单
config.example.json 不含凭据，缓存确认缺省为 false
pyproject.toml 外部客户端安装元数据
LICENSE MIT
.\.venv\Scripts\python.exe -m pip wheel . --no-deps --wheel-dir distwheel 用于外部客户端安装，包含所需字段资源及内置端 Python 包。面向用户的完整源码发行还应包含 README、tests、docs 和 skills；发布 GitHub 源码或 Release 源码包即可。不要把整个运行目录压缩上传。
先按 docs/release-checklist.md 审查本地文件。新建独立仓库，不继承私人原项目历史。提交前查看 git status 和暂存差异，确保没有样本、日志或本地配置。
在 GitHub 手动创建你选择的仓库后，使用其实际地址设置 remote 并 push。本文不预填账号或仓库 URL，也没有替你执行发布。初版建议标为 0.1.0a1 / Alpha，在仓库说明中保留限制和验收状态。
本项目沿用原作者 MIT 许可证，版权声明见 LICENSE。代码许可不涵盖第三方行情和券商软件。无需第三方桥接库，未捆绑第三方 RPC 实现。
接口背景可参阅迅投官方 内置 Python 快速开始、数据接口 和 使用须知。实际支持范围以你使用的券商客户端、授权和实测为准；本项目不据公众号文章声明统一停用日期或通用迁移政策。