chore: init qmt_bridge repo (HTTP+WS bridge, MCP endpoint, docs, references)

2026-08-26 16:53:15 +08:00
commit 22a5b8ca04
210 changed files with 68176 additions and 0 deletions
@@ -0,0 +1,523 @@
+# QMT API 参考手册
+
+本文档是 `qmt-trader` skill 的完整 API 参考。当 SKILL.md 的速查不够用时，查阅本文件获取
+参数细节、返回值结构和已知陷阱。
+
+---
+
+## 1. 初始化与配置
+
+### 配置来源（优先级从高到低）
+
+1. **环境变量**
+   | 变量 | 默认 | 说明 |
+   |------|------|------|
+   | `BIGQMT_ACCOUNT_ID` | — | 资金账号 |
+   | `BIGQMT_REDIS_HOST` | `127.0.0.1` | Redis 地址 |
+   | `BIGQMT_REDIS_PORT` | `6379` | Redis 端口 |
+   | `BIGQMT_REDIS_DB` | `5` | Redis DB |
+   | `BIGQMT_REDIS_PASSWORD` | — | Redis 密码 |
+   | `BIGQMT_RPC_TRANSPORT` | `redis` | 传输方式 redis/zmq |
+   | `BIGQMT_RPC_TIMEOUT_SECONDS` | `6.0` | RPC 超时 |
+
+2. **配置文件** `bigqmt_signal_trader_client_config.py`（在 PYTHONPATH 中，gitignored）
+
+3. **备选配置文件** `bigqmt_signal_trader_local_config.py`
+
+### Python 初始化
+
+```python
+from bigqmt_signal_trader.xtquant_compat import StockAccount, configure, xt_trader, xtdata
+
+configure()  # 从配置/环境变量初始化
+acc = StockAccount(xt_trader.client.account_id, "STOCK")
+```
+
+---
+
+## 2. 行情数据 API
+
+### 2.1 get_full_tick — 实时五档盘口
+
+```python
+xtdata.get_full_tick(code_list)
+```
+
+- **参数**: `code_list: list[str]`，如 `["000001.SZ", "600000.SH"]`；也支持整市场 `["SH"]`, `["SZ"]`
+- **返回**: `dict[code -> dict]`，每只含 `lastPrice`/`open`/`high`/`low`/`lastClose`/`volume`/`amount`/
+  `bidPrice`(10档)/`askPrice`(10档)/`bidVol`/`askVol`/`time`/`stime`
+- **CLI**: `python qmt.py tick 600000.SH 000001.SZ`
+- **注意**: 整市场快照数据量大（5000+ 股），超时自动设 30 秒
+
+### 2.2 get_market_data_ex — K线/历史行情
+
+```python
+xtdata.get_market_data_ex(
+    field_list=None,      # ["close","open","high","low","volume","amount"] 或 None=全部
+    stock_list=None,      # ["000001.SZ"]
+    period="1d",          # "1d"/"1m"/"5m"/"15m"/"30m"/"60m"/"tick"
+    start_time="",        # "YYYYMMDD" 或 "YYYYMMDDHHMMSS"
+    end_time="",
+    count=-1,             # -1=不限
+    dividend_type="none", # "none"/"front"(前复权)/"back"(后复权)
+    fill_data=True,       # 是否填充缺失
+)
+```
+
+- **返回**: `dict[code -> pandas.DataFrame]`，index 是时间戳字符串，列含 `time`(epoch ms)/`open`/`high`/`low`/`close`/`volume`/`amount`
+- **CLI**: `python qmt.py kline 600000.SH --period 1d --count 60 --dividend front`
+- **自愈**: 请求复权但服务端缺原始数据时（返回全 0），自动触发下载+重试
+- **陷阱**: 前/后复权必须先在服务端下载原始数据，否则返回全 0（已自愈但仍可能首次慢）
+
+### 2.3 get_instrument_detail — 合约详情
+
+```python
+xtdata.get_instrument_detail(stock_code)  # 别名 get_instrumentdetail
+```
+
+- **返回**: `dict`，含名称/上市日/合约乘数/最小变动价位等约 30 字段
+- **CLI**: `python qmt.py instrument 600000.SH`
+
+### 2.4 get_stock_list_in_sector — 板块成分股
+
+```python
+xtdata.get_stock_list_in_sector(sector_name)  # 如 "沪深A股", "科创板", "创业板"
+```
+
+- **返回**: `list[str]` 代码列表
+- **CLI**: `python qmt.py sector "沪深A股"`
+
+### 2.5 get_sector_list — 板块列表
+
+```python
+xtdata.get_sector_list()
+```
+
+- **返回**: `list[str]`
+- **CLI**: `python qmt.py sector`
+- **注意**: 大 QMT 环境 fallback 返回 13 个常用板块名（非完整列表）
+
+### 2.6 get_trading_dates — 交易日历
+
+```python
+xtdata.get_trading_dates(market="SH", start_time="", end_time="", count=-1)
+```
+
+- **CLI**: `python qmt.py trading-dates --count 10`
+
+### 2.7 get_north_finance_change — 北向资金
+
+```python
+xtdata.get_north_finance_change(period="1d")
+```
+
+- **CLI**: `python qmt.py north`
+
+### 2.8 get_longhubang — 龙虎榜
+
+```python
+xtdata.get_longhubang(stock_list=["600000.SH"], start_time="", end_time="", count=5)
+```
+
+- **返回**: `pandas.DataFrame`
+- **CLI**: `python qmt.py longhubang 600000.SH --count 5`
+
+### 2.9 get_financial_data — 财务数据
+
+```python
+xtdata.get_financial_data(
+    stock_list=["000001.SZ"],
+    table_list=["Capital.CAPITAL"],  # 表名
+    start_time="", end_time="",
+)
+```
+
+- **CLI**: `python qmt.py financial 000001.SZ --tables Capital.CAPITAL`
+
+### 2.10 download_history_data2 — 下载历史数据
+
+```python
+xtdata.download_history_data2(
+    stock_list=["600654.SH"], period="1d",
+    start_time="20240101", dividend_type="front",
+)
+```
+
+- **返回**: `{"finished": N, "total": M}`
+- **CLI**: `python qmt.py download 600654.SH --period 1d --start 20240101 --dividend front`
+
+### 2.11 subscribe_whole_quote — 全推行情订阅
+
+```python
+sub_id = xtdata.subscribe_whole_quote(["SH","SZ"], callback=on_quote)
+# ... 运行策略 ...
+xtdata.unsubscribe_quote(sub_id)
+```
+
+- **机制**: 服务端真推送（非轮询），增量推送有变化的品种
+- **CLI**: `python qmt.py quote-subscribe SH SZ --max 10 --timeout 30`
+- **心跳**: 客户端 3 秒一次 keepalive，服务端重启后自动恢复
+
+---
+
+## 3. 账户/持仓/委托查询 API
+
+### 3.1 query_stock_asset — 查询资产
+
+```python
+asset = xt_trader.query_stock_asset(acc)
+```
+
+- **返回属性**: `account_id` / `cash`(可用现金) / `frozen_cash` / `total_asset` / `market_value`
+- **CLI**: `python qmt.py account`
+- **容错**: RPC 失败时从 Redis 缓存 `bigqmt:positions:{account_id}` 读取
+
+### 3.2 query_stock_positions — 查询全部持仓
+
+```python
+positions = xt_trader.query_stock_positions(acc)
+```
+
+- **返回属性**: `stock_code` / `stock_name` / `volume`(总持仓) / `can_use_volume`(可用) /
+  `avg_price`(成本) / `price`(最新价) / `market_value` / `frozen_volume` / `yesterday_volume`
+- **CLI**: `python qmt.py positions [code]`
+
+### 3.3 query_stock_position — 查询单只持仓
+
+```python
+pos = xt_trader.query_stock_position(acc, "600000.SH")
+```
+
+- **返回**: 单个对象或 `None`
+
+### 3.4 query_stock_orders — 查询委托
+
+```python
+orders = xt_trader.query_stock_orders(acc, cancelable_only=False, strategy_name="")
+```
+
+- **返回属性**: `stock_code` / `order_type`(23=BUY,24=SELL) / `order_status` /
+  `order_volume` / `traded_volume` / `price` / `order_sysid` / `order_remark`
+- **CLI**: `python qmt.py orders [--cancelable] [--strategy ""]`
+- **⚠️ strategy_name 陷阱**: 下单时的 strategy_name 必须和查询时一致。服务端默认 `""` 返回全部；
+  客户端 `BigQmtXtTrader` 默认 `"bigqmt_signal_trader"`。用 `""` 查全部最安全。
+
+### 3.5 query_stock_trades — 查询成交
+
+```python
+trades = xt_trader.query_stock_trades(acc, strategy_name="")
+```
+
+- **返回属性**: `stock_code` / `order_type` / `traded_volume` / `traded_price` /
+  `traded_at` / `order_sysid` / `trade_id`
+- **CLI**: `python qmt.py trades`
+
+### 3.6 委托状态码
+
+| 值 | 常量 | 含义 |
+|----|------|------|
+| 48 | ORDER_UNREPORTED | 未申报 |
+| 49 | ORDER_WAIT_REPORTING | 等待申报 |
+| 50 | ORDER_REPORTED | 已申报 |
+| 51 | ORDER_REPORTED_CANCEL | 已申报撤单 |
+| 52 | ORDER_PARTSUCC_CANCEL | 部成撤单 |
+| 53 | ORDER_PART_CANCEL | 部撤 |
+| 54 | ORDER_CANCELED | 已撤 |
+| 55 | ORDER_PART_SUCC | 部分成交 |
+| 56 | ORDER_SUCCEEDED | 全部成交 |
+| 57 | ORDER_JUNK | 废单 |
+| 255 | ORDER_UNKNOWN | 未知 |
+
+可撤状态: 49, 50, 55
+
+---
+
+## 4. 下单 API
+
+### 4.1 order_stock — 同步下单
+
+```python
+from bigqmt_signal_trader.xtquant_compat import STOCK_BUY, STOCK_SELL, FIX_PRICE, LATEST_PRICE
+
+order_id = xt_trader.order_stock(
+    acc,            # StockAccount
+    stock_code,     # "600000.SH"
+    order_type,     # STOCK_BUY(23) / STOCK_SELL(24)
+    order_volume,   # int，委托数量
+    price_type,     # FIX_PRICE(11) / LATEST_PRICE(5)
+    price,          # float，限价单价格（最新价时传 0）
+    strategy_name,  # str
+    order_remark,   # str，user_order_id
+)
+```
+
+- **返回**: `order_sys_id`(字符串) 或 `-1`(失败)
+- **CLI**: `python qmt.py buy 600000.SH 100 --price 7.50 [--strategy s] [--remark r]`
+- **CLI**: `python qmt.py sell 600000.SH 100 --price 7.50`
+- **⚠️ 权限**: 服务端默认 `rpc_allow_order_methods=False`，必须显式开启才能下单
+- **⚠️ 超时**: 超时后委托可能已提交，先查 `query_orders` 确认，避免重复下单
+
+### 4.2 order_stock_async — 异步下单
+
+```python
+seq = xt_trader.order_stock_async(acc, code, order_type, vol, price_type, price, strategy, remark)
+```
+
+- **返回**: seq（结果通过 callback 回调）
+
+### 4.3 order_stock_batch — 批量下单
+
+```python
+results = xt_trader.order_stock_batch(acc, orders, batch_id="")
+# orders: list[dict]，每项含 stock_code/action/volume/price/price_type/strategy_name
+```
+
+- **上限**: 500 条/批
+
+### 4.4 信用交易委托类型
+
+| 常量 | 值 | 用途 |
+|------|-----|------|
+| CREDIT_BUY | 23 | 担保品买入 |
+| CREDIT_SELL | 24 | 担保品卖出 |
+| CREDIT_FIN_BUY | 27 | 融资买入 |
+| CREDIT_SLO_SELL | 28 | 融券卖出 |
+| CREDIT_BUY_SECU_REPAY | 29 | 买券还券 |
+| CREDIT_DIRECT_SECU_REPAY | 30 | 直接还券 |
+| CREDIT_SELL_SECU_REPAY | 31 | 卖券还款 |
+| CREDIT_DIRECT_CASH_REPAY | 32 | 直接还款 |
+
+---
+
+## 5. 撤单 API
+
+### 5.1 cancel_order_stock_sysid
+
+```python
+success = xt_trader.cancel_order_stock_sysid(acc, market, order_sysid)
+# market: "SH" / "SZ" / ""
+```
+
+- **CLI**: `python qmt.py cancel <order_sysid> --market SH`
+
+### 5.2 cancel_order_stock
+
+```python
+success = xt_trader.cancel_order_stock(acc, order_id)
+# 等价于 cancel_order_stock_sysid(acc, "", order_id)
+```
+
+---
+
+## 6. 回调系统
+
+```python
+from bigqmt_signal_trader.xtquant_compat import XtQuantTraderCallback
+
+class MyCallback(XtQuantTraderCallback):
+    def on_stock_order(self, order): ...       # 委托变更
+    def on_stock_trade(self, trade): ...        # 成交推送
+    def on_order_error(self, error): ...        # 委托错误
+    def on_cancel_error(self, error): ...       # 撤单错误
+    def on_order_stock_async_response(self, resp): ...
+    def on_account_status(self, status): ...
+
+xt_trader.register_callback(MyCallback())
+xt_trader.start()
+xt_trader.connect()
+xt_trader.subscribe(acc)
+```
+
+事件推送通过 Redis pubsub 频道:
+- `bigqmt:exec:order:{account_id}`
+- `bigqmt:exec:trade:{account_id}`
+- `bigqmt:exec:order_error:{account_id}`
+- `bigqmt:exec:cancel_error:{account_id}`
+
+---
+
+## 7. 关键陷阱速查
+
+### 7.1 strategy_name 不匹配
+- 下单用 `strategy_name="rpc_test"` → 查询用 `strategy_name="bigqmt_signal_trader"` → 返回空
+- **解决**: 查询时传 `strategy_name=""` 返回全部，或保持一致
+
+### 7.2 下单静默失败
+- `passorder` 调用成功但委托没进系统（QMT 风控拒绝但没报错）
+- **解决**: 服务端下单后等 0.5 秒查 `query_orders` 确认；检查返回的 `server_error` 字段
+
+### 7.3 复权 K 线返回全 0
+- 服务端缺原始数据时，前/后复权返回的 close 全是 0.0
+- **解决**: 先 `download_history_data2` 下载原始数据（客户端有自愈机制）
+
+### 7.4 Transport 不匹配
+- 客户端 redis / 服务端 zmq → ping 超时
+- **解决**: 两端 `transport` 字段保持一致
+
+### 7.5 QMT 必须运行在实盘模式
+- 模拟模式下委托进 QMT 界面但不在真实委托队列，`query_orders` 查不到
+- `order_stock` 返回 -1，触发 `on_order_error`
+
+### 7.6 整市场快照数据量大
+- `get_full_tick(["SH"])` 返回 5000+ 股完整盘口
+- **解决**: 启用 `full_tick_cache` 或增大超时（已自动设 30 秒）
+
+### 7.7 全推行情是增量的
+- `subscribe_whole_quote` 的大 QMT 回调只推有变化的品种
+- **解决**: 订阅成功后客户端自动调一次 `get_full_tick` 打底
+
+### 7.8 下单超时与重复下单
+- `order_stock` 超时 → 委托可能已提交但没收到响应
+- **解决**: 超时后先查 `query_orders`/`query_trades` 确认状态，再决定是否重试
+
+---
+
+## 8. 常量速查
+
+### 交易常量
+
+| 常量 | 值 | 用途 |
+|------|-----|------|
+| STOCK_BUY | 23 | 股票买入 |
+| STOCK_SELL | 24 | 股票卖出 |
+| FIX_PRICE | 11 | 限价/指定价 |
+| LATEST_PRICE | 5 | 最新价 |
+| MARKET_PEER_PRICE_FIRST | 44 | 对手方最优价 |
+
+### 账号类型
+
+| 常量 | 值 |
+|------|-----|
+| FUTURE_ACCOUNT | 1 |
+| SECURITY_ACCOUNT | 2 |
+| CREDIT_ACCOUNT | 3 |
+| FUTURE_OPTION_ACCOUNT | 5 |
+| STOCK_OPTION_ACCOUNT | 6 |
+
+### 期货委托类型（部分）
+
+| 常量 | 值 | 用途 |
+|------|-----|------|
+| FUTURE_OPEN_LONG | 0 | 开多 |
+| FUTURE_CLOSE_LONG_TODAY | 2 | 平今多 |
+| FUTURE_OPEN_SHORT | 3 | 开空 |
+| FUTURE_CLOSE_SHORT_TODAY | 4 | 平今空 |
+| FUTURE_CLOSE_LONG_HISTORY | 6 | 平昨多 |
+| FUTURE_CLOSE_SHORT_HISTORY | 7 | 平昨空 |
+
+---
+
+## 9. 直接 RPC 调用（绕过兼容层）
+
+当兼容层方法不够用时，可直接调 RPC：
+
+```python
+from bigqmt_signal_trader.redis_rpc import call_redis_rpc
+import redis
+
+r = redis.Redis(host="...", port=6379, db=5, password="...")
+resp = call_redis_rpc(r, "ACCOUNT_ID", "get_full_tick", {"codes": ["000001.SZ"]})
+print(resp["data"]["000001.SZ"]["lastPrice"])
+```
+
+- **万能入口**: `xtdata.call_method("get_float_caps", stockcode="000001.SZ")`
+- **方法别名映射**:
+  - `get_full_tick` → `get_ticks`
+  - `get_instrument_detail` → `get_instrument`
+  - `query_stock_asset` → `get_asset`
+  - `query_stock_positions` → `get_positions`
+  - `query_stock_orders` → `query_orders`
+  - `query_stock_trades` → `query_trades`
+  - `order_stock` → `submit_order`
+  - `cancel_order_stock` → `cancel_order`
+
+### RPC 响应结构
+
+```json
+{
+    "ok": true,
+    "data": {...},
+    "error": "",
+    "server_error": "",
+    "handled_at": "2024-07-01 15:00:00"
+}
+```
+
+- `ok=true`: `data` 为方法返回值（DataFrame 已序列化，客户端自动还原 pandas 对象）
+- `ok=false`: `error` 为错误信息
+- `server_error`: 额外诊断（如 passorder 提交但委托未进系统）
+
+---
+
+## 10. 可用 RPC 方法白名单（117 个只读 + 3 个下单/撤单）
+
+### 行情快照
+`get_ticks`/`get_full_tick`, `get_instrument`/`get_instrument_detail`, `get_instrument_type`,
+`get_stock_name`, `get_stock_type`, `get_last_close`, `get_last_volume`, `get_float_caps`,
+`get_total_share`, `get_turn_over_rate`, `get_weight_in_index`, `get_contract_multiplier`,
+`get_contract_expire_date`, `get_open_date`, `get_svol`, `get_bvol`, `get_risk_free_rate`,
+`is_stock_type`, `get_cb_info`
+
+### K线/历史
+`get_market_data`, `get_market_data_ex`, `get_local_data`, `get_close_price`, `get_index_weight`
+
+### L2 行情（需 L2 权限）
+`get_l2_quote`, `get_l2_order`, `get_l2_transaction`, `subscribe_l2thousand`
+
+### 板块
+`get_stock_list_in_sector`, `get_sector_list`, `get_sector_info`, `create_sector`, `add_sector`, `remove_sector`
+
+### 交易日历/时段
+`get_trading_dates`, `get_holidays`, `get_markets`, `get_market_last_trade_date`,
+`get_date_location`, `get_trading_calendar`, `get_trade_times`
+
+### 数据下载
+`download_history_data`, `download_history_data2`, `download_holiday_data`,
+`download_etf_info`, `download_cb_data`, `download_history_contracts`,
+`download_index_weight`, `download_sector_data`
+
+### 财务/因子
+`get_financial_data`, `download_financial_data`, `download_financial_data2`,
+`get_raw_financial_data`, `get_factor_data`
+
+### ETF/期权/期货
+`get_etf_info`, `get_ipo_info`, `get_option_list`, `get_his_option_list`,
+`get_his_option_list_batch`, `get_option_detail_data`, `get_option_undl_data`,
+`get_option_undl`, `get_ETF_list`, `get_main_contract`, `get_his_contract_list`
+
+### 期权定价
+`bsm_price`, `bsm_iv`, `get_option_iv`
+
+### 龙虎榜/股东
+`get_longhubang`, `get_top10_share_holder`, `get_holder_num`, `get_turnover_rate`,
+`get_industry`, `get_his_st_data`, `get_his_index_data`
+
+### 资金流
+`get_north_finance_change`, `get_hkt_statistics`, `get_hkt_details`, `get_hkt_exchange_rate`
+
+### 因子/模型
+`call_formula`, `subscribe_formula`, `unsubscribe_formula`, `get_formula_result`, `gen_factor_index`
+
+### 时间转换（纯本地）
+`datetime_to_timetag`, `timetag_to_datetime`
+
+### 账户查询
+`get_asset`, `get_positions`, `query_stock_position`, `query_orders`, `query_trades`,
+`get_history_trade_detail_data`, `get_value_by_order_id`, `get_last_order_id`
+
+### 融资融券（需两融权限）
+`get_assure_contract`, `get_enable_short_contract`, `get_unclosed_compacts`,
+`get_closed_compacts`, `get_debt_contract`
+
+### 期权持仓
+`get_option_subject_position`, `get_comb_option`
+
+### 持仓同步
+`sync_positions`
+
+### 下单/撤单（需开启 rpc_allow_order_methods）
+`submit_order`/`order_stock`, `submit_orders_batch`/`order_stock_batch`,
+`cancel_order`/`cancel_order_stock`/`cancel_order_stock_sysid`
+
+### 全推行情
+`subscribe_whole_quote`, `unsubscribe_whole_quote`, `quote_keepalive`