| name | qmt-xtquant |
| description | QMT/MiniQMT xtquant 原生 API 知识库，用于编写、调试或扩展调用 `xtquant.xtdata` 的 A 股数据采集任务。
适用场景：下载/读取 K线、tick、财务、合约信息、板块分类、指数权重、除权因子数据；股票代码与
UTC 毫秒时间戳转换；MiniQMT 连接失败排障（返回 -1、端口冲突、session、权限）。覆盖 xtdata 的
download_*→get_* 核心范式、全部函数签名、各类数据字段 schema，以及关键坑（get_market_data 与
get_market_data_ex 返回结构不同、单股订阅 ≤50、tick 时间戳为 UTC 毫秒需 +8h、静态信息无需频繁下载）。
当处理 xtquant / xtdata / MiniQMT / QMT 相关的行情数据接口、字段含义或下载逻辑时使用；
亦含 xttrader 交易模块（报单/撤单/查询/回调）与分品种数据字典（stock/index/future）参考。
|
QMT xtquant 数据采集知识库
xtquant 是迅投 MiniQMT 衍生的 Python 量化库。xtdata 模块提供行情（历史/实时 K 线和分笔）、
财务、合约基础信息、板块/行业分类、指数权重等数据。本知识库以数据采集为主；交易模块 xttrader 另有精简参考备查。
官方文档：https://dict.thinktrader.net/nativeApi/start_now.html
运行模型（必读）
- xtdata 不直连行情服务器，而是连接本地运行的 MiniQMT 客户端，由 MiniQMT 处理数据请求再回传到
Python 层。因此运行任何脚本前，MiniQMT 必须已启动并登录（登录时需勾选"极简模式"）。
- xtquant 大部分历史数据以压缩格式存储在本地。获取接口（
get_*）只读本地缓存，本地数据不足时
必须先用下载接口（download_*）补充，否则取不到。
- 仅 Windows 平台可用（本项目所有 xtquant 任务都标了
platform: windows）。
核心范式：先 download_ 再 get_
接口前缀语义：download_ 下载到本地 / get_ 读本地 / subscribe_、unsubscribe_ 订阅实时。
from xtquant import xtdata
xtdata.download_history_data2(stock_list, period="1d",
start_time="20240101", end_time="20240131")
data = xtdata.get_market_data_ex([], stock_list, period="1d",
start_time="20240101", end_time="20240131",
count=-1, dividend_type="none", fill_data=False)
- 历史部分用
download_history_data2 补；实时部分用 subscribe_quote 订阅，之后 get_* 会自动拼接
本地历史 + 服务器实时。
- 静态信息（板块、合约）也是先
download_sector_data() / download_history_contracts() 再 get_*。
get_market_data vs get_market_data_ex（关键区别）
两者参数完全相同，但 K 线返回结构不同。本项目统一用 _ex（见
a_share_daily.py）：
| 接口 | K 线返回结构 | 取单只 |
|---|
get_market_data | {field: DataFrame(index=股票, columns=时间)} | 需跨多个 field 切片 |
get_market_data_ex | {股票代码: DataFrame(index=时间, columns=field)} | data[code] 直接拿到该股 DataFrame |
get_market_data_ex 额外支持日线以上周期（1w/1mon/1q/1hy/1y）和 ETF 申赎清单。tick 周期下两者都返回 {股票: np.ndarray}（按 time 升序）。
关键约定
- 代码格式：
code.market，如 000001.SZ、600000.SH、000300.SH、430047.BJ。
- 周期 period：
tick 1m 5m 15m 30m 1h 1d 1w 1mon 1q 1hy 1y。
- 复权 dividend_type：
none / front / back / front_ratio / back_ratio（仅对 K 线有效，对 tick 无效）。
- 时间戳：返回的
time 字段是 UTC 毫秒。转北京时间用
pd.to_datetime(time, unit="ms") + pd.Timedelta(hours=8)——不要用官方示例里的 time.localtime
（依赖机器时区，跨平台不可靠）。
- 时间范围：
[start_time, end_time] 是闭区间。count：-1 全部、0 不返回、>0 以 end_time
为基准向前取 N 条。start/end 留空 + count=-1 = 全量（范围过大会很慢，按需裁剪）。
- 请求限制：单股订阅建议 ≤50 只，更多时改用全推
subscribe_whole_quote；板块等静态信息按周/日
定期更新即可，无需频繁下载。
常用函数速查
| 用途 | 函数 |
|---|
| A 股代码列表 | get_stock_list_in_sector("沪深A股")（需先 download_sector_data()） |
| 批量下载 K 线 | download_history_data2(stock_list, period, start, end, callback) |
| 读 K 线 | get_market_data_ex(field_list, stock_list, period, start, end, count, dividend_type, fill_data) |
| 全推快照 | get_full_tick(code_list) |
| 除权因子 | get_divid_factors(code, start, end)（先下载历史 K 线） |
| 合约信息 | get_instrument_detail(code, iscomplete=True) |
| 财务数据 | download_financial_data2(...) → get_financial_data(...) |
| 板块成分/列表 | get_stock_list_in_sector(name) / get_sector_list() |
| 指数权重 | download_index_weight() → get_index_weight(index_code) |
| 交易日 | get_trading_dates(market, ...) / get_trading_calendar(market, ...) |
详细参考（按需加载）
