Files
pytdxdata/docs/internals/protocol.md
T
openbot-coder c4dd61665b docs: 建立 MkDocs 文档站与 AI 层文档
- 新增 MkDocs + Material 文档站(19 页):入门、CLI、场景示例、FAQ、
  Contributing、Changelog、API 参考(mkdocstrings 自动渲染)、内部原理
  (架构 / 协议 / 三池路由 / 缓存)
- 新增 docs/llms.txt:面向 LLM 的结构化摘要(枚举取值、方法速查、常见陷阱)
- 新增 scripts/check_docs.py:校验文档与 api.py 公开方法清单是否漂移
- 新增根 CHANGELOG.md 作为版本记录唯一来源,docs/changelog.md 用 snippet 引入
- 新增 .github/workflows/docs.yml:push main 自动构建并部署 GitHub Pages
- 修正文档口径:TdxData 公开方法 53 个(51 数据方法 + start/close);
  API_REFERENCE 版本号 v0.3.2 -> v0.4.0
- pyproject.toml 新增 docs 依赖组;.gitignore 忽略 site/
2026-09-15 13:57:31 +08:00

103 lines
4.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 协议与命令
约 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) — 哪个命令走哪条通道