# 协议与命令 约 2500 行里最硬的部分。目标是:**不依赖 `pytdx` / `easy-tdx`,自己把线上字节跑通**。 > 本页讲「要解决什么问题」。**精确的字节布局以 `src/pytdxdata/protocol/` 源码为准**—— > 每个命令类里的 `build_request()` / `parse_response()` docstring 都写了实际偏移。 ## 三条协议 | | 标准通道 | MAC 通道 | EX 通道 | |---|---|---|---| | 端口 | 7709 | 7709 | **7727** | | 帧格式 | 经典 TDX 帧 | MAC 帧(带会话 seq) | pytdx EX 协议 | | 覆盖 | 报价 / K线 / 列表 / 除权 / 财务 | 逐笔 / 分时 / 复权K线 / 板块 / 竞价 / 资金流 | 港股 / 美股 / 期货 / 期权 | | 握手 | 无需登录 | `0x2454` login | `0x2454` setup/login | MAC 与标准**共用 7709 端口但协议不同**,所以连接池也分成两个——一条 TCP 连接只能跑一种帧格式。 ## 需要自己还原的编码 通达信不是「大端小端调对就完事」的协议,这些都得逆出来: ### 变长整数 部分字段用可变字节数编码。`protocol/_binary.py` 负责读写。 ### 差分还原 **成交量(volume)不是直接存的**。它是相对前一条记录的差分,必须按顺序累加还原。 这意味着**不能随意乱序或跳读**——分页拼接时必须保证顺序正确。 ### 自定义浮点价格 价格用一套私有编码而不是 IEEE754。`protocol/price.py` 负责还原。 不同**品种**的小数位还不同:股票 2 位,指数 / ETF / 可转债 3 位。 模型里的 `decimal_point` 就是这个信息。 ### 日期 / 时间编码 `protocol/datetime_.py`。K 线里年月日时分是**分开的整数字段**, 模型上额外提供了一个 `datetime` 属性做拼装。 ## 命令模块 `protocol/commands/` 下 16 个模块,按业务域划分: | 模块 | 负责 | |---|---| | `base.py` | 命令基类 | | `setup.py` | 连接建立与握手 | | `kline.py` | K 线(标准) | | `quotes.py` | 五档报价 | | `security_list.py` | 证券列表与数量 | | `transaction.py` | 逐笔成交 | | `minute.py` | 分时 | | `xdxr.py` | 除权除息 | | `finance.py` | 财务 | | `mac.py` | MAC 通道通用命令 | | `mac_ext.py` | MAC 扩展(板块 / 竞价 / 异动 / 快照 / 资金流) | | `mac_tick.py` | MAC 单日分时图(`0x122D`) | | `std_ext.py` | 标准通道扩展(F10 / 文件下载) | | `ex_ext.py` | EX 辅助接口 | | `ex_proto.py` | EX 主协议(K线 / 报价 / 市场列表) | 每个命令类只做两件事:**把参数打成请求字节**、**把响应字节解析成模型**。不做网络、不做缓存。 ## 关键命令码 排错时对照用: | 命令 | 码 | 通道 | |---|---|---| | K 线(标准) | — | 标准 | | K 线(MAC,支持复权) | `0x122E` | MAC | | 分时 | `0x122D` | MAC | | 远程文件元信息 | `0x1215` | MAC | | 远程文件下载 | `0x1217` | MAC | | 分时缩略采样 | `0x254D` | MAC | | 板块文件 | `0x06B9` 系 | 标准 | | EX K 线 | `0x23FF` | EX | | EX 报价 | `0x23FA` | EX | | EX 市场列表 | `0x23F4` / `0x23F5` | EX | | EX 港股逐笔 | `0x23FC` / `0x2406` | EX | | MAC / EX 登录 | `0x2454` | MAC / EX | ## 踩过的坑 这些是实际调试中撞出来的,写在这免得重踩: | 现象 | 根因 | |---|---| | K 线数据**时有时无** | 标准通道部分服务器在 `count < 100` 时返回空 → 分页器强制 `min_page=100` | | MAC K 线**随机丢数据** | 并发分页把不同页分到深度不一致的服务器,`stop_when_short` 提前截断 → 改单连接串行 | | 1 分钟 K 线**深度不足** | 标准通道给的深度不够 → 切到 MAC `0x122E` | | 分时只有几十条 | 标准通道命令不完整 → 切到 MAC `0x122D`,稳定 240 条 | | 财报**市场字段恒为深市** | 上游用 `<6s1c1L` 解析,`1c` 的类型转换吞掉了市场字节 → 改 `<6sBL` | | 握手正常但**拉不到数据** | 坏节点。服务器探测改为「真实请求一段 K 线」而不是只看握手 | ## 下一步 - [文件解析器](../api/codec.md) — 服务器静态文件的字节格式 - [通道与数据源](routing.md) — 哪个命令走哪条通道