docs: 修正 servers.json 清理后遗留的过时描述(含一处事实反转)

servers.json 复测后三池台数已变(standard 9 / mac 22 / ex 4),但 README 与部分文档
仍停留在旧口径,且有一处因果结论被实测推翻:

- README.md
  - 测试用例数 127 → 164(并补「当日测速缓存」到用例分组说明)
  - 「已知限制」补测速缓存详情的文档站链接
- docs/internals/routing.md
  - 三池台数:标准池「数十台」→ 9 台、MAC 池「数台」→ 22 台(EX 池 4 台不变),
    并标注为 2026-09-21 离线探针实测可达数、实际以当日测速缓存为准
  - **事实反转修正**:原文「MAC 池远小于标准池,这解释了逐笔/分时并发弱于日线」
    与实测不符(mac 22 > standard 9)→ 已改为陈述实测台数,
    并指出两通道单台连接上限默认相同(均 4)
- docs/internals/cache-pool.md
  - 「为什么 MAC 池更小」小节前提已不成立 → 改为「MAC 通道的单台连接上限」,
    保留 mac_pool_cap=4 的可用信息,删除错误因果
- docs/refactor-audit.md
  - 历史快照的 127 passed 标注「审查当时」,避免误读为当前基线

验证:scripts/check_docs.py exit 0;mkdocs build --strict exit 0(无告警)
This commit is contained in:
openbot-coder committed 2026-09-21 19:42:06 +08:00
1 parent d422385877
commit b78d0fabf5
4 files changed
+14 -10

No files matched your search

+3 -2
View File
@@ -104,7 +104,7 @@ curl -o ~/.workbuddy/skills/pytdxdata/SKILL.md --create-dirs \
```bash ```bash
uv sync # 建虚拟环境 + 注册 tdx 命令 uv sync # 建虚拟环境 + 注册 tdx 命令
uv run pytest tests/ # 127 个测试用例(协议 / 池 / 缓存 / 分页 / 全接口回归 / 文件解析 / CLI / 文档漂移) uv run pytest tests/ # 164 个测试用例(协议 / 池 / 缓存 / 分页 / 全接口回归 / 文件解析 / CLI / 文档漂移 / 当日测速缓存)
uv sync --group docs # 文档站依赖(mkdocs-material + mkdocstrings) uv sync --group docs # 文档站依赖(mkdocs-material + mkdocstrings)
uv run mkdocs serve # 本地预览文档站 uv run mkdocs serve # 本地预览文档站
``` ```
@@ -115,7 +115,8 @@ uv run mkdocs serve # 本地预览文档站
- 标准通道 K 线 `count < 100` 部分服务器返回空 → 分页器已强制 `min_page=100` 规避 - 标准通道 K 线 `count < 100` 部分服务器返回空 → 分页器已强制 `min_page=100` 规避
- 港股 / 美股期权在通达信协议内无数据 - 港股 / 美股期权在通达信协议内无数据
- 服务器可用性随时间变化。**当日首次启动会自动在后台测速并缓存**(对调用方无感,当天不再重测); - 服务器可用性随时间变化。**当日首次启动会自动在后台测速并缓存**(对调用方无感,当天不再重测);
也可用 `python -m pytdxdata.server_probe` 离线重生成随包清单 也可用 `python -m pytdxdata.server_probe` 离线重生成随包清单。
缓存路径与三个开关见 [安装与配置 → 当日自动测速](https://openbot-coder.github.io/pytdxdata/getting-started/#当日自动测速无感)
## 免责声明 ## 免责声明
+4 -4
View File
@@ -81,11 +81,11 @@ results = await asyncio.gather(*[
EWMA(指数加权移动平均)延迟让选路对「最近变慢」敏感,而不是被历史均值拖住。 EWMA(指数加权移动平均)延迟让选路对「最近变慢」敏感,而不是被历史均值拖住。
### 为什么 MAC 池更小 ### MAC 通道的单台连接上限
MAC 通道可用服务器只有数台(见 [通道与数据源](routing.md#server-groups)), `mac_pool_cap` 默认 `4`,与标准池的 `std_pool_cap` 一致——这是**对端单台连接限制**,
所以 `mac_pool_cap` 默认只有 `4`——这是**对端限制**,不是本项目的选择。 不是本项目的选择。两个通道的可用台数见 [通道与数据源](routing.md#server-groups):
逐笔 / 分时的并发能力天然弱于日线,原因就在这里。 实测可达台数会随服务器上下线变化,以**当日测速缓存**为准。
## 并发分页 ## 并发分页
+6 -3
View File
@@ -29,10 +29,13 @@
| 池 | 数量级 | 用途 | | 池 | 数量级 | 用途 |
|---|---|---| |---|---|---|
| **标准池** | 数十台 | 报价 / K线 / 列表 / 财务 | | **标准池** | 9 台 | 报价 / K线 / 列表 / 财务 |
| **MAC 池** | 数台 | 逐笔 / 分时 / 复权 / 板块 / 资金流 | | **MAC 池** | 22 台 | 逐笔 / 分时 / 复权 / 板块 / 资金流 |
| **EX 池** | 4 台 | 港股 / 美股 / 期货 / 期权 | | **EX 池** | 4 台 | 港股 / 美股 / 期货 / 期权 |
> 上表为 2026-09-21 离线探针(`python -m pytdxdata.server_probe --discover`)实测**可达**台数。
> 服务器会下线、换 IP 或变更协议,**实际台数以当日测速缓存为准**(见下方「运行时:当日测速缓存」)。
EX 池内部还要再分两类,因为握手方式不同: EX 池内部还要再分两类,因为握手方式不同:
| 类型 | 数量 | 握手 | | 类型 | 数量 | 握手 |
@@ -42,7 +45,7 @@ EX 池内部还要再分两类,因为握手方式不同:
这就是 `config.get_ex_handshakes()` 存在的原因——EX 的 4 台机器不是同一种握手。 这就是 `config.get_ex_handshakes()` 存在的原因——EX 的 4 台机器不是同一种握手。
MAC 池远小于标准池,这也解释了为什么逐笔 / 分时的并发能力天然弱于日线。 注意 MAC 池实测**并不比标准池小**(22 台 vs 9 台)。早期版本曾按「MAC 可用节点很少」来解释逐笔 / 分时并发弱于日线,实测已推翻该前提——两者的单台连接上限(`mac_pool_cap` / `std_pool_cap`)默认相同,都是 `4`。
## 为什么这些服务器会被「探测」 ## 为什么这些服务器会被「探测」
+1 -1
View File
@@ -142,7 +142,7 @@
## 七、验证 ## 七、验证
- `pytest`:**127 passed**。其中 `tests/test_all_interfaces.py` 为全接口回归:mock 连接逐个 - `pytest`:**127 passed**(审查当时的快照;当前基线为 164 passed)。其中 `tests/test_all_interfaces.py` 为全接口回归:mock 连接逐个
调用 63 个公开方法,并以「覆盖哨兵」断言无遗漏(7 条告警为别名测试的预期 `DeprecationWarning`)。 调用 63 个公开方法,并以「覆盖哨兵」断言无遗漏(7 条告警为别名测试的预期 `DeprecationWarning`)。
- `scripts/check_docs.py`:`MUST_LIST_ALL` + `MUST_NOT_BE_STALE` 全部 `[OK]`。 - `scripts/check_docs.py`:`MUST_LIST_ALL` + `MUST_NOT_BE_STALE` 全部 `[OK]`。
- 签名核对:统一接口签名与返回类型与本文一致;全仓无 `_as_symbols` 及元组式调用残留。 - 签名核对:统一接口签名与返回类型与本文一致;全仓无 `_as_symbols` 及元组式调用残留。