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/
This commit is contained in:
openbot-coder committed 2026-09-15 13:57:31 +08:00
1 parent 02ec5b6e33
commit c4dd61665b
26 files changed
+2934 -1

No files matched your search

+80
View File
@@ -0,0 +1,80 @@
# 通道与数据源
通达信的不同数据**散落在不同的协议和服务器上**。选路是 `router.py` 的职责,
调用方不需要关心——但知道「为什么慢」「为什么某个字段没有」时,这张表是排错起点。
## 路由表
| 请求 | 通道 | 为什么 |
|---|---|---|
| K 线 — **复权**(QFQ / HFQ) | **MAC** | 复权数据只有 MAC 通道提供 |
| K 线 — **`MIN_1` 不复权** | **MAC** | 标准通道 1 分钟深度不足;且必须串行分页 |
| K 线 — 其他周期不复权 | 标准 | 价格小数位规则已验证 |
| 指数 K 线 | 标准 | 含涨跌家数等指数专有字段 |
| 五档报价 | 标准 | 标准通道字段更全(含 `decimal_point`) |
| **逐笔成交** | **MAC** | 含 `trade_count`(成交笔数),且支持历史回溯 |
| **分时** | **MAC** | 标准通道不完整;MAC `0x122D` 稳定返回 240 条 |
| 证券列表 / 数量 | 标准 | 仅标准通道提供 |
| 除权除息 / 财务 | 标准 | 仅标准通道提供 |
| 板块 / 竞价 / 异动 / 快照 / 资金流 / 服务器时段 / 分类报价 | **MAC** | 这些是 MAC 专有命令 |
| 港股 / 美股 / 期货 / 期权 | **EX**(7727) | 完全不同的协议栈 |
!!! note "只请求,不改语义"
路由是**内部实现细节**。同一个 `get_kline()` 调用,传不传 `adjust` 会走不同通道,
但返回类型和字段完全一致——你不需要写 `if adjust:` 分支。
## 三组服务器 {#server-groups}
`src/pytdxdata/servers.json` 里维护三份清单,分别对应三个连接池:
| 池 | 数量级 | 用途 |
|---|---|---|
| **标准池** | 数十台 | 报价 / K线 / 列表 / 财务 |
| **MAC 池** | 数台 | 逐笔 / 分时 / 复权 / 板块 / 资金流 |
| **EX 池** | 4 台 | 港股 / 美股 / 期货 / 期权 |
EX 池内部还要再分两类,因为握手方式不同:
| 类型 | 数量 | 握手 |
|---|---|---|
| MAC EX 服务器 | 2 | `0x2454` login |
| pytdx EX 服务器 | 2(通达信扩展市场 / 国泰君安) | `0x2454` setup |
这就是 `config.get_ex_handshakes()` 存在的原因——EX 的 4 台机器不是同一种握手。
MAC 池远小于标准池,这也解释了为什么逐笔 / 分时的并发能力天然弱于日线。
## 为什么这些服务器会被「探测」
服务器列表不是静态配置——通达信节点会下线、换 IP、**或者握手正常但返回空数据**。
`server_probe` 的探测逻辑**不是只看 TCP 连通性**,而是真实请求一段 K 线并校验内容:
```bash
python -m pytdxdata.server_probe
```
普通「只 ping 握手」的探测会把这类坏节点放进来,症状是**偶发的空返回**——
比直接连不上更难查。所以探测必须校验数据。
## EX 通道细节
- 端口固定 **7727**,与标准 / MAC 的 7709 不同
- 走 **pytdx EX 协议**(`0x23FF` K线 / `0x23FA` 报价 / `0x23F4` 市场列表)
- 合约代码规则与 A 股不同:港股 5 位(`00700`)、美股字母(`AAPL`)、
期货带月份(`IFL0` / `rb2610`)、期权 8 位(`10010971`)
- 美股期权 / 港股期权**协议内无数据**
```python
from pytdxdata.models import ExMarket, KlinePeriod
await td.get_kline(ExMarket.HK_MAIN_BOARD, "00700", KlinePeriod.DAY, count=700)
await td.get_kline(ExMarket.US_STOCK, "AAPL", KlinePeriod.DAY, count=700)
```
`ExMarket` 的完整成员见 [枚举速查](../api/enums.md#exmarket)。
## 下一步
- [连接池与缓存](cache-pool.md) — 选到服务器之后怎么用
- [协议与命令](protocol.md) — 通道底下的字节格式