协议与命令¶
约 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 线」而不是只看握手 |