- 新增 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/
103 lines
4.1 KiB
Markdown
103 lines
4.1 KiB
Markdown
# 协议与命令
|
||
|
||
约 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) — 哪个命令走哪条通道
|