YangSal BigQMT 数据桥参考
本技能服务于开源项目 bigqmt-data-bridge，外部包名 bigqmt_bridge，内置包名 qmt_bridge。它不是完整 xtquant 兼容层。先完整阅读本文件；需要更详细部署或接口说明时，读取用户指定源码根目录的 README.md 和实际 --help，不假设技能目录就是源码目录。
定位与环境
从任务取得源码根目录、外部 Python 3.10+ 解释器、配置或 IPC 目录。若无法确定，先只读检查用户指定目录，仍缺失则询问；不要搜索或加载其他私人项目配置。
外部安装命令在源码根目录为 python -m pip install -e .；开发测试可用 ".[test]"。安装前遵循当前任务的授权。内置端不运行 pip：QMT 策略编辑器加载 qmt_bridge/strategy.py，PROJECT_ROOT 指向源码根，BRIDGE_DIR 指向独立本机 IPC 目录。需用户操作客户端时给出具体步骤，不声称已点击或重启。
配置合同
CLI 只读取显式 --config 的扁平 JSON，没有 qmt 包装键，不自动加载配置或原项目环境变量。配置示例在源码根 config.example.json，默认 cache_prepared=false。只有确认对应日期、代码、周期的 QMT 本地缓存已准备，才将本地配置改为 true；此值是人工确认，不是下载或新鲜度检测。
配置中的相对 bridge_dir 相对于配置文件目录；命令行相对目录则相对于当前工作目录。优先使用明确绝对路径。不要将新测试桥指向正在使用的其他 IPC 目录。
新路径的最小本地配置示例（config.local.json）：
{"backend": "file_bridge", "bridge_dir": "E:\\qmt-ipc", "cache_prepared": false}
常用命令
以下为 PowerShell 示例，替换为任务实际路径；20260904 是固定北京时间日期示例，不是自动选择的“今天”。使用外部解释器运行。
Set-Location E:\research\bigqmt-data-bridge
$bridgePython = '.\.venv\Scripts\python.exe'
& $bridgePython -m bigqmt_bridge probe --config config.local.json --timeout 5 --output evidence\probe.json
# 核对缓存后，配置里的 cache_prepared 应为 JSON true
& $bridgePython -m bigqmt_bridge sample --config config.local.json --date 20260904 --codes 000001.SZ --periods 1d --families market --output evidence\bridge-daily.json
& $bridgePython -m bigqmt_bridge compare evidence\native-daily.json evidence\bridge-daily.json --output evidence\diff.json
如果只拿到了 IPC 目录，probe 可用 --bridge-dir E:\qmt-ipc 而不指定配置。取样需要显式配置中的缓存确认；不要发明 --cache-prepared 参数。
原生基线在仍可用的授权原生环境执行：python -m bigqmt_bridge sample --backend native --date 20260904 --codes 000001.SZ --periods 1d --families market --output evidence\native-daily.json。可从另一节点带回样本，不为此切换生产登录模式。没有有效原生样本时记录缺少基线，不能宣称对照通过。
| 任务 | 入口与事实 |
|---|---|
| 行情 | sample --families market --periods 1d/1m/5m/tick，实际填写单一周期或逗号列表；显式日期、最多10个代码 |
| 其他样本 | --families divid/financial/instrument/sectors/weights，填写单一类别或逗号列表 |
| Python 调用 | create_backend(load_config(path))，分别来自 bigqmt_bridge.backend/config |
| 验证 | compare 返回0才是样本对照通过，1表示失败；空样本不能通过 |
| 离线测试 | 源码根运行 python -m pytest tests -q，需已安装测试依赖 |
行情读取固定 subscribe=False, fill_data=False，时间为 UTC 毫秒，转换使用 utc=True 再 tz_convert('Asia/Shanghai')。比较需要同代码、日期、周期、字段、单位、复权口径，保留重复行和数组次序，不通过删列/去重/猜单位让差异消失。
compare 不校验文件来源身份。跨端验收时保留两端真实生成命令、项目/解释器/客户端版本及原始报告；复制同一报告后的相等不能证明独立原生对照。
探测与故障判定
- 桥 probe 的
ok:true仅证明定时往返和方法存在；检查worker_version:2、market_reader、各项 capabilities。原生 probe 的import_only:true连真实连通性都未证明。 - 原始行情路径优先
get_market_data_ex_ori，缺失时退到内置get_market_data_ex；券商封装可能要求 pandas。财务八表、完整合约、分类 ID 和指数成员必须单独验收。 download_*只是缓存确认入口，不会下载。缓存为空或QmtDataError应报告失败，不能写成空交易日、零成员或删旧快照。- timeout：保留请求编号和错误，检查路径、权限、策略定时器及客户端状态。外部超时不能终止内置 API；停止堆积请求，不删活跃锁或抢占 worker。需要停止策略、修改客户端依赖、重启、清理时，先确认影响与授权。
- 每2秒一个请求，Tick 每请求1股；5000股调度下限约2.8小时，不能承诺全市场吞吐已达标。响应未压缩 JSON 上限64MiB，超大窗口需缩小，未实现自动拆分。
输出与任务边界
交付实际命令、退出码、证据路径、验证范围及未通过项；区分模拟测试通过、probe通过、真实取样通过、跨端对照通过。维护结束不等于结构性兼容问题消失。
默认只读诊断和小样本，不自行触发下载、下单、数据库写入、双写切换或 GitHub 发布。正式切换需要逐通道数据和容量验收；原生权限仍有效才具备原生回退条件。IPC 目录必须可信且有受控权限；SHA256不是身份认证。公开 issue 不附账号、真实数据、运行目录或日志中的敏感信息。