From b78d0fabf5d8ed073646331695caaa9481badcf2 Mon Sep 17 00:00:00 2001 From: openbot-coder Date: Mon, 21 Sep 2026 19:42:06 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BF=AE=E6=AD=A3=20servers.json=20?= =?UTF-8?q?=E6=B8=85=E7=90=86=E5=90=8E=E9=81=97=E7=95=99=E7=9A=84=E8=BF=87?= =?UTF-8?q?=E6=97=B6=E6=8F=8F=E8=BF=B0=EF=BC=88=E5=90=AB=E4=B8=80=E5=A4=84?= =?UTF-8?q?=E4=BA=8B=E5=AE=9E=E5=8F=8D=E8=BD=AC=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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(无告警) --- README.md | 5 +++-- docs/internals/cache-pool.md | 8 ++++---- docs/internals/routing.md | 9 ++++++--- docs/refactor-audit.md | 2 +- 4 files changed, 14 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index a2c7a68..3f8752d 100644 --- a/README.md +++ b/README.md @@ -104,7 +104,7 @@ curl -o ~/.workbuddy/skills/pytdxdata/SKILL.md --create-dirs \ ```bash uv sync # 建虚拟环境 + 注册 tdx 命令 -uv run pytest tests/ # 127 个测试用例(协议 / 池 / 缓存 / 分页 / 全接口回归 / 文件解析 / CLI / 文档漂移) +uv run pytest tests/ # 164 个测试用例(协议 / 池 / 缓存 / 分页 / 全接口回归 / 文件解析 / CLI / 文档漂移 / 当日测速缓存) uv sync --group docs # 文档站依赖(mkdocs-material + mkdocstrings) uv run mkdocs serve # 本地预览文档站 ``` @@ -115,7 +115,8 @@ uv run mkdocs serve # 本地预览文档站 - 标准通道 K 线 `count < 100` 部分服务器返回空 → 分页器已强制 `min_page=100` 规避 - 港股 / 美股期权在通达信协议内无数据 - 服务器可用性随时间变化。**当日首次启动会自动在后台测速并缓存**(对调用方无感,当天不再重测); - 也可用 `python -m pytdxdata.server_probe` 离线重生成随包清单 + 也可用 `python -m pytdxdata.server_probe` 离线重生成随包清单。 + 缓存路径与三个开关见 [安装与配置 → 当日自动测速](https://openbot-coder.github.io/pytdxdata/getting-started/#当日自动测速无感) ## 免责声明 diff --git a/docs/internals/cache-pool.md b/docs/internals/cache-pool.md index b2c2e45..f6ebeaf 100644 --- a/docs/internals/cache-pool.md +++ b/docs/internals/cache-pool.md @@ -81,11 +81,11 @@ results = await asyncio.gather(*[ EWMA(指数加权移动平均)延迟让选路对「最近变慢」敏感,而不是被历史均值拖住。 -### 为什么 MAC 池更小 +### MAC 通道的单台连接上限 -MAC 通道可用服务器只有数台(见 [通道与数据源](routing.md#server-groups)), -所以 `mac_pool_cap` 默认只有 `4`——这是**对端限制**,不是本项目的选择。 -逐笔 / 分时的并发能力天然弱于日线,原因就在这里。 +`mac_pool_cap` 默认 `4`,与标准池的 `std_pool_cap` 一致——这是**对端单台连接限制**, +不是本项目的选择。两个通道的可用台数见 [通道与数据源](routing.md#server-groups): +实测可达台数会随服务器上下线变化,以**当日测速缓存**为准。 ## 并发分页 diff --git a/docs/internals/routing.md b/docs/internals/routing.md index bee6bf1..22d0c63 100644 --- a/docs/internals/routing.md +++ b/docs/internals/routing.md @@ -29,10 +29,13 @@ | 池 | 数量级 | 用途 | |---|---|---| -| **标准池** | 数十台 | 报价 / K线 / 列表 / 财务 | -| **MAC 池** | 数台 | 逐笔 / 分时 / 复权 / 板块 / 资金流 | +| **标准池** | 9 台 | 报价 / K线 / 列表 / 财务 | +| **MAC 池** | 22 台 | 逐笔 / 分时 / 复权 / 板块 / 资金流 | | **EX 池** | 4 台 | 港股 / 美股 / 期货 / 期权 | +> 上表为 2026-09-21 离线探针(`python -m pytdxdata.server_probe --discover`)实测**可达**台数。 +> 服务器会下线、换 IP 或变更协议,**实际台数以当日测速缓存为准**(见下方「运行时:当日测速缓存」)。 + EX 池内部还要再分两类,因为握手方式不同: | 类型 | 数量 | 握手 | @@ -42,7 +45,7 @@ EX 池内部还要再分两类,因为握手方式不同: 这就是 `config.get_ex_handshakes()` 存在的原因——EX 的 4 台机器不是同一种握手。 -MAC 池远小于标准池,这也解释了为什么逐笔 / 分时的并发能力天然弱于日线。 +注意 MAC 池实测**并不比标准池小**(22 台 vs 9 台)。早期版本曾按「MAC 可用节点很少」来解释逐笔 / 分时并发弱于日线,实测已推翻该前提——两者的单台连接上限(`mac_pool_cap` / `std_pool_cap`)默认相同,都是 `4`。 ## 为什么这些服务器会被「探测」 diff --git a/docs/refactor-audit.md b/docs/refactor-audit.md index 813c057..8207da1 100644 --- a/docs/refactor-audit.md +++ b/docs/refactor-audit.md @@ -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`)。 - `scripts/check_docs.py`:`MUST_LIST_ALL` + `MUST_NOT_BE_STALE` 全部 `[OK]`。 - 签名核对:统一接口签名与返回类型与本文一致;全仓无 `_as_symbols` 及元组式调用残留。