# 更新日志 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 ## [0.7.1] - 2026-10-29 ### 性能 - **DataFrame 转换提速近一倍:24 万行 K 线 894ms → 462ms(polars)/ 1,001ms → 587ms(pandas)**。 0.7.0 的取列实现有两处浪费:每个单元格都套一层 Python 闭包(顺带做 `IntEnum` 判断), 而 `trading_date` 每行都重新格式化三个整数 —— 24 万行里这个值往往只有 **1~2 种**。 | 转换层(不碰网络) | 0.7.0 | 现在 | |---|---|---| | 5,225 行报价 → polars | 66 ms | **51 ms** | | 5,225 行报价 → pandas | 74 ms | **62 ms** | | 240,000 行 K 线 → polars | 1,038 ms | **444 ms** | | 240,000 行 K 线 → pandas | 1,234 ms | **585 ms** | 端到端(缓存已热,1,000 只 × 240 根 1 分钟):`df=None` 1,386ms、 polars 1,768ms(原 2,680ms)、pandas 1,976ms(原 2,848ms)。 - 普通列改用 `list(map(attrgetter(name), rows))`:取值发生在 C 层,不再每格建一个 Python 帧。 - `trading_date` 按「时间字段(除 minute 外)」缓存(`_TD_KEYS`):A股/港股/期货一个交易日 一个键,美股靠键里的 `hour` 覆盖凌晨段跨日判断 —— 不依赖 `_US_DAY_SPLIT_HOUR` 的具体取值。 - `IntEnum` 归一化从「每格判断一次」改为「按列判断一次、需要时才整列转」。 - 逐字段等价有测试锁定(`test_every_bar_field_equals_model` 等 3 项),口径零变化。 ### 文档 - `docs/dataframe.md` 性能一节改为**实测数据 + 何时该用/不该用 DataFrame 出口**的说明, 并把「缓存命中也要付转换成本」写清。 ## [0.7.0] - 2026-10-28 ### 新增 - **DataFrame 直出:`TdxData(df="polars")` / `TdxData(df="pandas")`**。 表格型接口不再只能返回 `list[dataclass]`,构造时声明一次后端即可直接拿到 DataFrame: ```python async with TdxData(df="polars") as td: df = await td.get_bars("sh600000", KlinePeriod.DAY, count=240) ``` - 覆盖 **42 个**返回表格数据的方法(33 个 `list[dataclass]`、2 个 `list[dict]`、 2 个批量 `dict[str, list[...]]`、`get_indicators` 与 `get_index_trade_stats(_multi)`), 另含 deprecated 别名(`get_kline` / `get_transactions` / `get_goods_*` 等)。 - **核心包仍然零依赖**:pandas / polars 是可选 extras —— `pip install "pytdxdata[polars]"` / `[pandas]` / `[dataframe]`。 - `df=None`(默认)**行为与 0.6.x 完全一致**,且装饰器直接透传,零额外开销。 - 取值非法抛 `ValueError` 并列出可用值;后端未安装抛 `FrameBackendError`(继承 `ImportError`, `e.name` 为缺的包名,消息里带安装命令)——**在构造时就失败**,不会拖到第一次查询。 - **列口径**(三条约定,一次定死): | 约定 | 说明 | |---|---| | 时间列替换 | `SecurityBar`/`IndexBar`/`MinuteBar` 的 `year/month/day/hour/minute` 不再单列输出,统一给 `datetime`(polars `Datetime('us')` / pandas `datetime64[ns]`)与 `trading_date`;`XdxrRecord` 给 `date` | | 嵌套定型 | `SecurityQuote.bid`/`ask` 展开成 `bid1_price`…`ask5_vol` 共 10 列(缺档 `None`);`fields` 字典 JSON 化成字符串列(空字典给 `None`);`TdxBlock.codes` 保持列表 | | 容器展开 | `get_indicators` → bars + 各指标一列(长度不足补 `None`);`get_index_trade_stats(_multi)` → `minutes` 展开并补 `index`/`date` 常量列;`get_kline_batch`/`get_minute_batch` → 各标的纵向拼接成一张表 | - **嵌套调用不二次转换**:`get_kline_batch` 这类方法内部还会调 `get_bars`, 用 `ContextVar`(按 task 隔离)记录层次,内层一律返回原始 `list`,只有最外层那次才转 DataFrame。 并发调用互不干扰。 ### 性能 - **按日期区间取 K 线:右端贴最新时改走「倒推」,1 分钟 K 线 4.2s → 82ms(51 倍)**。 原先 `start_date` / `end_date` 一律走「探总根数 → 二分定位偏移」。1 分钟 K 线历史总量 二十万根量级,等于 6 次翻倍探测 + 2 次方向探测 + **两次各 ~18 次**跳转,共 36+ 次串行往返。 而「取今天」「增量到最新」这类占绝对多数的调用,右端本来就贴着最新,根本不需要二分。 | 场景(1 分钟,冷启动) | 优化前 | 优化后 | |---|---|---| | 单只「取今天」 | 4,208 ms | **82 ms** | | 单只「2 天前 ~ now」 | 2,211 ms | **75 ms** | | 单只「取最近 3 天」 | 2,000 ms+ | **239 ms** | | 单只「历史中段(5~3 天前)」 | 1,512 ms | 285 ms | | 全市场 5,225 只「取今天」 | — | 32.1 s(1,140,699 根,**精确当天口径**) | 做法:右端离最新不超过 `_BACKTRACK_GRACE`(10 天,覆盖长假)时,直接 `start=0, count=N` 拿最新 N 根再裁剪 —— N 按时间跨度估算(`_BARS_PER_DAY`), 一天内一次就命中,不够才翻倍。历史中段仍走二分,结果完全一致。 偏移方向是**通道级属性**(与具体标的无关),首次探测后缓存在实例上: 全市场 5,225 只批量调用只付一次探测成本,不会每只探两遍。 - **多标的 K 线改「多连接 × 单连接流水线」抓取,全市场 1 分钟 K 线 43.6s → 5s 级 (盘中增量 1.5s)**。 单只 K 线是「一请求一标的」,5,000 只就是 5,000 次往返。实测单连接串行 **33ms/只 ≈ 恰好一个 RTT** —— 瓶颈是**往返次数,不是带宽**(此前「单 IP 限流 1.5MB/s」的 结论是浅流水下的假象:同一台服务器 16 连接 × 深度 8 实测能跑到 5.2 MB/s)。 做法:同一连接连续下发 `pipeline` 条请求(协议帧自描述长度且服务器**按序应答**, 无需等前一个回来),再叠加多台服务器并行(每台 1 连接,尊重 `per_server_cap`)。 | 场景(全市场 5,225 只,1 分钟) | 优化前(逐只 `concurrency=6`) | 优化后 | |---|---|---| | 取当天全天(240 根) | 43.6 s | **5~8 s** | | 盘中 10:00(35 根) | 15 s+ | **~2 s** | | 盘中增量(最新 2 根) | 12 s+ | **~1.5 s** | - 流水深度默认**自适应**(`pipeline=None`):按单请求字节数把在途量控制在 ~60KB, 夹在 8~32 之间 —— 取 240 根用深度 8,只取最新 2 根用深度 32。 实测过深反而更慢(24 台 depth=64 比 depth=8 慢一倍,服务器会攒够一批才回)。 - 服务器**只取最快的 12 台**:池里 24 台全用反而被慢节点拖长尾 (`count=2` 全市场:24 台 2.95s / 12 台 1.45s)。 - **盘中只拉已走过的根数**:`start_date=今天` 时按交易时段折算(10:00 → 30 根, 而不是 240 根),数据量直接差 8 倍。收盘后回到一整天的量级。 - 标准通道(日线不复权)同样走批量:全市场日线 240 根 49~72s → **~10s**。 - 流水线中途失败时该批**交回逐只重试**(流水线失败意味着响应流已错配、连接作废), 连接全挂时队列里剩下的标的也一并回退 —— 不会静默少数据(新增测试覆盖)。 - `pipeline=1` 可关闭批量路径,行为与旧版逐只路径一致。 - **修正「右端是否贴最新」的时间戳比较**:`0x122E` 返回的 `hour/minute` 是**该周期的 结束时刻**,最新一根可能比 `datetime.now()` 略大(14:29 那根此刻还在走)。 原先没有容差,`end_date=datetime.now()` 这类最自然的写法会被误判成「历史中段」而走慢路径。 ### 修复 - **EX 通道 K 线的 `amount` 恒为 0.0,且末位字段(结算价)被解包丢弃**。 `0x23FF` 一条记录 32B = 4B 时间戳 + **28B 行情**,这 28B 只有**一个** 4B 槽位可复用, 语义按市场分两类(全市场实测,用 `成交额 / (close × vol)` 逐条校验): | 市场 | 槽位 5 | 槽位 6 | 槽位 7 | 校验 | |---|---|---|---|---| | 港股主板 31 / 港股基金 49 | **成交额**(f) | 成交量(手=100 股) | 未知 | 额/(c·vol) = **100.0** | | 港股创业板 48 / 新三板 44 / 美股 74 | **成交额**(f) | 成交量(股) | 0 | 额/(c·vol) ≈ **1.0** | | 期货 / 期权(7/8/9/47…) | 持仓量(I) | 成交量 | **结算价**(f) | 与 CFFEX 官网日结逐日相符 | 改动前:`amount` 被硬编码成 `0.0`、第 7 个 float 用 `_` 丢弃 —— 于是港股/美股/新三板 **明明帧内有成交额却全是 0**,期货期权的结算价也拿不到(用户只能换源)。 - 新增 `SecurityBar.settle`(结算价,`float | None`)。仅 EX 期货/期权**日线**有值, 分钟线该槽位恒 0 已归一化为 `None`;其它通道恒 `None`。 - 权益类市场的 `amount` 回填真实成交额。⚠️ 港股主板/基金的 `vol` 单位是**手(=100 股)**, `amount/vol` 是均价的 **100 倍**。 - 期货/期权的 `amount` **仍是 0.0** —— 帧内确实没有成交额,这是协议限制,已在 `SecurityBar` 与文档中写清,避免使用者再按文档误判为调用方 bug。 - 港股指数 27 / 中证指数 62 该槽位量级对不上(既非成交额也非结算价),保守保持 `0.0`。 - `SecurityBar.__setstate__` 兜底旧磁盘缓存:缓存键没有 schema 版本,升级后读旧 pickle 会缺 `settle` 槽位,默认反序列化不补默认值 → 直接 `AttributeError`,已容错。 EX K 线缓存键额外加 `@v2` 标记,让 `amount` 恒 0 的旧缓存自然失效。 ### 兼容性 - 无破坏性变更。不传 `df` 时所有方法签名、返回类型、行为与 0.6.9 完全相同。 - 空结果返回**列名齐全的空表**(列由模型定义推出),dtype 由后端自行推断。 - `SecurityBar` 新增可选字段 `settle`(默认 `None`):K 线 DataFrame 因此多一列 `settle`, 位置参数构造的老代码不受影响。 ### 升级 ```bash pip install -U pytdxdata # 只要 dataclass pip install -U "pytdxdata[polars]" # 想直出 DataFrame ``` - **磁盘缓存不需要手动清**:`SecurityBar` 的 `settle` 由 `__setstate__` 兜底补默认值, 旧缓存照常可读;EX K 线缓存键已带 `@v2`,`amount` 恒 0 的旧记录会自动失效重取。 - 新参数 `pipeline`(`get_bars`)默认自适应,**不传就是最优**;只有想显式退回旧的逐只路径时才传 `1`。 ### 文档 - 新增 [DataFrame 输出](https://openbot-coder.github.io/pytdxdata/dataframe/) 专页, `API_REFERENCE.md`(构造参数表补 `df` 与 `ex_pool_cap`、`pool_max` 默认值修正为 24)、 `SKILL.md`、`llms.txt`、`README.md`、`mkdocs.yml` 导航同步。 - 全站同步 0.7.0 口径:首页特性表与导航卡片、安装页(extras 与构造参数表补 `df` / `std_pool_cap` / `ex_pool_cap`)、场景示例的「转成 pandas」改为推荐 `df=` 开关、 数据模型页说明 dataclass 与 DataFrame 是同一份数据、README「已知限制」补 EX 成交额口径。 ## [0.6.9] - 2026-10-23 ### 修复 - **`get_universe` 冷启动 12~18s / 偶发失败:证券清单请求多发了 2 字节,污染连接**。 `GetSecurityListCmd` 的请求体是「12 字节命令头 + market(H) + start(H)」= **16 字节**, 但实现里多塞了一个 `H`(写死 0),实际发出 **18 字节**。服务端只消费前 16 字节, 剩下的 `00 00` 停在它的接收缓冲里,把**下一个请求**的开头吃掉 —— 于是同一条连接 「第一次成功、第二次起永远无响应」。 分页器复用连接,等于每拉一页都要先失败重连,冷启动被拖到 12~18s,还经常直接抛 `ConnectionError`。 | 场景 | 修复前 | 修复后 | |---|---|---| | `get_universe("sh")` 冷启动(27,534 条 / 28 页) | 12,267ms | **1,610ms** | | `get_universe("sz")` 冷启动(24,460 条 / 25 页) | 18,260ms | **571ms** | | `get_universe()` 全市场冷启动(146,848 条) | 19,085ms | **4,371ms** | | `get_universe()` 热缓存 | — | 669ms | | 同一连接连发 2 次清单(27 台主机) | **0/27 成功** | **27/27 成功** | - **北交所清单不再卡 15s 后报错,改为立即返回空列表**。 `0x053E` 对 `market=2` 在实测的 **27 台标准主机上全部无响应**(26 台 6s 无回包、 1 台立刻拒连),而同市场的 `0x053D` 数量接口正常(返回 389)。原实现会重试 2 次、 每次 3s 超时,最后让 `get_universe()`(不带参数)整批失败。 现在该市场直接返回空列表并 `WARNING` 一次,**北交所标的本身不受影响**: `get_quotes("bj920992")` / `get_bars` / 逐笔全部正常(实测 11.79 与日线 close 一致)。 ### 优化 - **`get_universe()` 的 EX 全量只取一次**:命中缓存也要反序列化 10 万条(~200ms), 原先十几个 EX 市场各来一次,纯属白烧。 - **EX 商品列表改并发翻页**(110 页,8 并发):全市场冷启动的一半时间花在这里。 ### 文档 - `get_universe` docstring 写明北交所限制;`API_REFERENCE` / `llms.txt` / `SKILL.md` 同步。 - 新增 `tests/test_universe.py` 7 项:请求长度锁定 16 字节、无尾部 padding、 北交所返回空且**不碰连接池**、`_ex_all` 只取一次。 ### 已知限制(非本次引入) - EX 全量列表含**非证券条目**(如人员名录),`(market, code)` 在原始数据里就不唯一, 且重复项出现在**同一页内部**。属数据源特性,未做去重(去重会丢真实品种)。 ## [0.6.8] - 2026-10-23 ### 修复 - **CLI 价格按品种小数位显示;`tdx minute` 时间列改回真实时钟**。 两处纯显示层缺陷,数据本身没问题(分时/逐笔数值见 0.6.7 的核对结论): | 现象 | 原因 | |---|---| | `tdx transactions sh113708` 打印 `128.89` | 价格写死 `%8.2f`;可转债报价步长 0.001 元,末位被截掉 | | `tdx minute sh113708` 时间列 `00:00~03:59` | 按序号推算 `i // 60, i % 60`,与 bar 自带时间无关 | | `tdx quotes sh113708` 打印 `128.8920` | `price_decimal_digits` 是**解码位数**(原始整数 / 10⁴),第 4 位恒为 0 | | 位置 | 变化 | |---|---| | `_price_fmt(dp)`(新) | 宽度随小数位走(`%8.2f` → `%9.3f`),不破坏表格对齐 | | `_display_dp(market, code)`(新) | 可转债(沪 `110/111/113/118`、深 `123/127/128`)由解码 4 位降到显示 3 位;其余沿用 `price_decimal_digits`(ETF 3 位、国债/回购 4 位、股票/指数 2 位) | | `cmd_kline` / `cmd_transactions` / `cmd_minute` / `_print_quote` | 统一改用上面的格式串 | | `cmd_minute` | 时间取 `MinuteBar.hour/minute`,不再用序号推算 | | `cmd_transactions` / `cmd_minute` | 改调 `get_ticks` / `get_minutes`,消掉 `get_transactions` / `get_minute` 的 DeprecationWarning | 新增回归测试 8 项(`tests/test_cli_format.py`)。 文档:`docs/cli.md` 补「价格小数位按品种适配」对照表与 `tdx minute` 时间列说明。 ## [0.6.7] - 2026-10-22 ### 性能 - **全市场 A股报价 3.5s → 0.33s:单连接流水线 + 工作窃取**(5,227 只 / 66 片实测)。 老实现 `get_quotes` 是**纯串行 for 循环**逐片发请求:协议硬上限 80 只/请求, 全市场必须切 66 片,每片一次往返(≈60ms)→ 3.5s 全花在等网络上。 关键发现:通达信响应是**自描述长度帧**(16B 帧头 + body)且服务器**按序应答**, 因此同一 TCP 连接上可以连续下发多条请求、只付一次往返。实测单连接流水 66 个请求 只要 526ms(串行 7,372ms),响应顺序与代码完全对得上(用昨收价交叉比对 30 只,零错配)。 | 位置 | 变化 | |---|---| | `TdxConnection.execute_pipeline(cmds)`(新) | 一次 write 全部请求 → 按序读回全部响应。中途失败**强制断连**(响应流已错配,不可复用) | | `PooledConnection.execute_pipeline`(新) | 池化包装转发 | | `api._execute_std_pipeline`(新) | 借一条连接流水一整组分片;节点不支持流水线时自动降级为逐片 | | `get_quotes(..., pipeline=True, concurrency=None)` | 新参数;小批量(≤80 只)仍走原路径,零额外开销 | | `_quotes_std` | 改为**工作窃取**:分片放队列,连接做完一批回来再取,快的多干、慢的少干 | | `DynamicPool.warm(n)`(新) | **并发**预建连接。`acquire()` 建连在全局锁内一次一条,22 并发首次会串行握手 22 次 —— 全市场首拉因此多花 5~6s;预热后降到 0.78s | | `CacheManager.get_or_fetch_obj`(新) | 回源直接返回对象,省掉冷路径「pickle→立刻 unpickle」的一次白烧(5,227 条实测 ~40ms) | | `TdxData(pool_max=)` | 默认 12 → 24,让报价并发能到「每台 2 连接」(池仍是懒扩容,不影响其他接口) | 调优实测(5,227 只 A股,11 台服务器,p50/max): | 并发 | 每台连接 | 流水深度 | p50 | max | |---|---|---|---|---| | 11 | 1 | 6 | 455ms | 464ms | | 12 | 1~2 | 3 | 457ms | 523ms | | **22** | **2** | **3** | **325ms** | **334ms** | | 33 | 3 | 2 | 328ms | 345ms | ⚠️ 剩余下限由公网决定:本机 → 服务器 TCP 握手 RTT 59~80ms,66 片最多只能压到 「1 次往返」;网络抖动时段实测会到 460~600ms。 端到端实测(全默认参数 `TdxData()`,11 台服务器,5,227 只): | 场景 | 耗时 | |---|---| | 首次调用(含并发建 22 条连接) | 783ms | | 稳态(第 2 次起) | **300~343ms** | | 命中 TTL 缓存 | 67ms | | 老版本对照(串行) | 5,996ms(首次)/ 3,460ms(稳态) | ### 修复 - **指数 / ETF / LOF 的 `trade_count` 不再伪装成成交笔数**。 通达信对**指数**和**多数场内基金**不提供笔数,但逐笔报文里那 4 字节仍塞了值: 指数是「当时均价 × 1000」,ETF/LOF 是「价格 × 1000」,货币 ETF(`sh511990`)恒为 `0`。 旧版直接把它当笔数,于是 `tdx transactions sh510310` 会打印出「3994笔」这种假数据 (实测 2026-10-22,价 3.989,原字段 3994)。 | 位置 | 变化 | |---|---| | `TransactionRecord.trade_count_available`(新字段) | 该品种协议上是否带笔数;默认 `True` | | `symbols.has_order_count(market, code)`(新函数) | 按品种判定;**沪市 501x/502x/506x 实测有真实笔数**,不能按「5 开头=基金」一刀切 | | `transaction.py` 三个解析器 | 不可用时 `trade_count=0` + `trade_count_available=False`;历史通道(0x013001,无笔数字段)同样标记 | | `tdx transactions` CLI | 不可用时打印 `(-)`,不再打印假笔数 | 实测样本(2026-10-22,按前缀各取样):沪股票/科创/深股票/深可转债/沪逆回购 → 真实笔数; 沪 `51/52/56/58`、深 `159/15x/16x/17x/18x`、所有指数 → 不可用。 ### 文档 - **可转债的量纲口径补全**(数据本身无缺陷,但对外文档一片空白,很容易被误判成 bug)。 起因:核查可转债的分时(`0x122D`)与逐笔(`0x122F`)是否有类似 ETF/LOF 的笔数问题。 结论是**价格 / 成交量 / 笔数三样全部正确**,顺带确认了 K 线标度也对;唯一的问题是 `vol` 的单位没人写清楚 —— 直接拿 `amount / vol` 算均价会**错 10 倍**。 实测(2026-10-22,16 只 A股可转债当日 + 8 只历史日 `2026-10-21`): | 校验项 | 结果 | |---|---| | 分时末价 / 快照现价 | **1.000000** | | Σ分时 vol / 日线 vol | **1.000000** | | Σ逐笔 vol / 日线 vol | **1.000000** | | 逐笔 VWAP vs `amount/(vol×10)` | 吻合(差 ≤0.002,是 amount 精度) | | 快照 `pre_close` vs 上一交易日日线 `close` | **16/16 精确相等** | | `trade_count` | 真实笔数(`sh111000` 3631 条切片 / 20443 笔) | 关键口径对照(这是文档缺失的部分): | 品种 | 分时 / 逐笔 `vol` | 日线 `vol` | `Σ分时vol / 日线vol` | `amount / vol` | |---|---|---|---|---| | 股票 / ETF / LOF | 手(= 100 股) | 股 | **0.01** | 均价 ✓ | | 可转债 | 手(= 10 张) | **手** | **1.0** | 均价 **×10** ⚠️ | | 位置 | 变化 | |---|---| | `SecurityBar` / `TransactionRecord` / `MinuteBar` | 量纲注释补可转债(`vol`=手;日线 `amount/vol` 需再 `/10`) | | `symbols.has_order_count` | 实测表补沪可转债 `110/111/113/118`、沪 EB `132`、深可转债 `123/127/128`,并说明它们走「排除法」兜底分支 | | `docs/API_REFERENCE.md` | 新增**跨品种量纲对照表** | | `docs/llms.txt` / `SKILL.md` | 同步同一口径 | **代码逻辑未改**:可转债在 `has_order_count` 里本来就判为「有笔数」(不在基金/指数的 排除前缀里),本次只是把实测依据补进注释与文档。 ## [0.6.6] - 2026-10-22 ### 改进 - **价格小数位改用协议自带的权威值,前缀规则降为兜底**。 0.6.5 修好债券/回购标度时,采用的是「按代码前缀推断」+「用全量清单做离线校验」。 但同一份证券清单接口(`get_universe`,底层 `GetSecurityListCmd`)本来就**返回** `SecurityInfo.decimal_point`(外加自描述浮点的 `pre_close`)——权威值一直就在手上, 只是没接进取数路径。本次把它接进来: | 位置 | 说明 | |---|---| | `price_decimal_digits` | 查找顺序改为 **权威表 → 静态前缀规则**,未同步时行为与 0.6.5 完全一致 | | `decimal_sync`(新模块) | 每日后台同步一次 + 磁盘缓存(`%LOCALAPPDATA%\pytdxdata\decimal-points.json`) | | `TdxData.sync_decimal_points()` | 手动强制刷新(排障 / 立刻要权威表) | | `TdxData.decimal_point_status()` | 状态:`source` / `stock` / `mixed_prefixes` / `syncing` | **对用户仍无感**:`start()` 命中当日缓存就直接装表(实测 60 ms、零网络), 未命中则挂后台 task(实测首次 50 s,含沪 27,520 + 深 24,462 条清单), 不阻塞 `start()`(`start()` 仍 1.5 s);`close()` 会取消未完成的同步。 **表结构刻意做小**:全量 51,982 只标的只产生 **179 个**「三位前缀 → 小数位」映射 (沪 96 + 深 83),内存里就是 179 条。若将来某段代码混用两种小数位,该前缀自动 退化为**逐代码表**,只存例外代码(`mixed_prefixes` 会 > 0,可据此发现), 不会静默算错。清单拉取不完整时表会偏小 —— 缺的部分退回静态规则,不影响正确性。 为什么保留前缀规则:`get_quotes` 解析是纯同步、无网络的路径,解析那一刻可能还没 同步过清单;离线 / 首次安装也必须能出价格。实测两者在全量清单上**零分歧** (51,982 条逐条比对,不一致 0 条),并存不会造成口径冲突。 开关:`PYPYTDX_DATA_DISABLE_DECIMAL_SYNC=1` 关闭后台同步(CI / 测试用)。 ### 说明 - 新增回归测试 16 项(权威表优先级 / 混合前缀退化 / 缓存跨日失效 / 损坏容错 / 后台任务取消),测试总数 **289 → 306**。 ## [0.6.5] - 2026-10-22 ### 新增 - **指数成分成交汇总:一条接口拿到「某指数下全部股票的成交量与成交笔数」** (`get_index_members` / `get_index_trade_stats` / `get_index_trade_stats_multi`)。 起因是一个绕不开的协议事实:**指数本身没有成交笔数**。指数逐笔(`sh000001`)的 `trade_count` 字段实际是「当时均价 × 1000」(2026-10-21 已验证),`get_minutes` / `get_market_stat` / `SecurityBar` / `get_quotes` 的 160 个字段位里也都**没有**笔数 (扫描 0x122C 全字段位确认,`0x8`/`0x9` 是外盘/内盘手数)。所以「指数笔数」唯一可行 的口径是**把成分股的逐笔笔数累加**。 ```python async with TdxData() as td: st = await td.get_index_trade_stats("000300") # 沪深300,约 10 s for hhmm, cum in st.cum_trade_count(): # 截止该分钟的累计笔数 print(hhmm, cum) st.minutes[0] # MinuteTradeStat(time='09:25', volume=…, trade_count=…) st.total_volume # 手 st.total_trade_count # 笔 ``` | 方法 | 作用 | |---|---| | `get_index_members(index, *, fields=None, count=100000)` | 指数成分股(含实时报价)。裸 6 位按**指数语义**解析:`000001`=上证指数,不是平安银行 | | `get_index_trade_stats(index, date=None, *, concurrency=24, batch_size=50, members=None, skip_errors=True, on_progress=None)` | 成分逐笔 → 每分钟成交量/笔数;`date` 支持历史 | | `get_index_trade_stats_multi(index, dates, *, ...)` | 多日批量(成分只请求一次),用于「近 N 日同时点均值」基准 | **口径校验(2026-10-22 实测)**:``total_amount`` 是**成分股**合计。对「成分 = 指数 覆盖面」的指数,它与指数快照 ``amount`` 完全相等 —— 说明成分清单与量能口径一致。 | 指数 | 成分 | 成分合计 | 指数快照 | 比值 | 耗时 | |---|---|---|---|---|---| | `sh000016` 上证50 | 50 | 661.38 亿 | 661.34 亿 | 1.0001 | 5.8 s | | `sh000300` 沪深300 | 300 | 2373.98 亿 | 2373.98 亿 | 1.0000 | 9.7 s | | `sh000001` 上证指数 | 2230 | 3907.00 亿 | 4111.56 亿 | 0.9503 | 35.6 s | 历史日期同样成立(2026-10-21 收盘数据):`sh000016` 1046.29 / 1045.59 亿(1.0007)、 `sh000300` 3881.65 / 3879.30 亿(1.0006)。 单只股票级别的口径更硬:`Σ(逐笔价 × 手 × 100)` 与日线 `amount` 比值 **1.0000~1.0004**(`sh600000` / `sz000001` / `sh601398` / `bj920002` / `bj920015` 全部吻合),`Σvol` 与快照 `vol` 比值 1.0000。 CLI 同步新增:`tdx index-stats 000300 --top 10`。 **三个必须知道的限制**: 1. **深市 `399xxx` 的指数成交额是「全板块」口径**,不是样本股 —— 实测 `sz399001` 快照 5081.40 亿 = 深市 2908 只股票合计 5081.01 亿,`sz399006` 2568.60 亿 = 创业板全部股票合计。所以拿它跟 `total_amount` 比会得到 0.43 这种 无意义比值,不是数据错。**`get_index_trade_stats` 返回的始终是成分口径。** 2. **北交所(`899xxx`)没有笔数字段** —— 逐笔 `trade_count` 恒为 0,此时 `trade_count_available` 为 `False`,只有成交量可用。 3. **成分表比全市场滞后** —— 上证指数返回 2230 只,而 `get_universe("sh")` 里 股票段共 2360 只,差 130 只(新上市尚未纳入服务端板块),这正是上表 0.9503 的来源;`sh000016`/`sh000300` 这类固定样本指数不受影响。 需要精确覆盖时可自行传 `members=[...]`。 ### 修复 - **债券与回购价格全线偏差:沪市少 100 倍、深市少 10 倍**(`get_quotes`)。 `price_decimal_digits` 只覆盖了「股票 2 位 / 基金 3 位」两档,债券与回购没有对应 分支,落到默认档位。它们实际是 **4 位小数**,于是被读大了两个数量级: | 标的 | 真实价 | 修复前 | 偏差 | |---|---|---|---| | `sh019742` 国债 24特国01 | 110.2280 | 11022.8000 | ×100 | | `sh110077` 可转债 洪城转债 | 199.2790 | 19927.9000 | ×100 | | `sh204001` 回购 GC001 | 1.3850 | 138.5000 | ×100 | | `sh900901` B股 云赛B股 | 0.5670 | 5.6700 | ×10 | | `sz123107` 可转债 温氏转债 | 112.1890 | 1121.8900 | ×10 | | `sz131810` 回购 R-001 | 1.3800 | 13.8000 | ×10 | 沪市 `010/018/019/020/1xx/2xx` 与深市 `10x-14x/19x/50x/52x/56x` 全部改为 4 位; 沪市 B 股 `900xxx` 另改为 3 位(与深市 `200xxx` 的 2 位不同,两市不一致)。 股票 / ETF / 指数 / 板块的行为**不变**。 **验证方式(可作为该函数的验收标准)**:拿 `pre_close`(五档快照口径,走 `price_decimal_digits`)除以上一交易日**日线收盘**(K线口径,走独立的 `/1000` 路径),比值 1.0 即两口径一致。修复后 15 类标的全数为 1.0000,零偏差。 **权威来源已确认**:证券列表里协议**自带** `SecurityInfo.decimal_point` 字段。 2026-10-22 拉取全量 **51,982 只**(沪 27,520 + 深 24,462)逐条比对,本函数与 协议字段**完全一致、零例外**——因为全量清单里没有任何一个「三位前缀」出现混合 小数位。`get_quotes` 解析时拿不到证券清单,故仍用前缀推断;需要权威值时读 `SecurityInfo.decimal_point`。 - **美股(EX 通道)分时的 `hour` 是非法时钟值**(`get_minutes("usAAPL")`)。 EX 分时的 `minutes` 字段是**自开盘起的连续分钟数**,不是「当天的分钟数」。 旧代码直接 `minutes // 60`,于是 390 条里 **240 条** 的 `hour` ≥ 24: ``` 修复前: 21:30, 21:31, ..., 23:59, 24:00, 24:01, ..., 27:59 ← hour=27 不存在 修复后: 21:30, 21:31, ..., 23:59, 00:00, 00:01, ..., 03:59 ← 真实北京时间 ``` 任何 `datetime(...)` 拼接都会因 `hour=27` 抛 `ValueError`,按小时聚合也会把 凌晨段错误地归到同一个自然日。 **修法**:`MinuteBar.__post_init__` 把越界的 `hour` 拆成 「`hour %= 24` + `day_offset += hour // 24`」,并新增两个只读属性: | 属性 | 用途 | |---|---| | `MinuteBar.datetime` | 该分时点的时刻(北京时间,已含跨日偏移) | | `MinuteBar.trading_date` | 归属的交易日 `YYYY-MM-DD`。美股一个交易日横跨两个北京自然日(21:30~次日 04:00),**按交易日聚合必须用它**,与 `SecurityBar.trading_date` 口径一致 | A股(合成时间 09:30~15:00)/ 港股(09:30~16:00)/ 期货的 `hour` 本就合法 → **零行为变化**,`day_offset` 恒为 0。 实测(2026-10-22):`usAAPL` / `usTSLA` / `usNVDA` 各 390 条,修复后 `hour` 全在 0~23、时间轴严格单调、`trading_date` 收敛为单一交易日; `hk00700` 90 条无任何变化。 ### 说明 - 新增回归测试:债券/回购/B股小数位 ×29、美股分时跨日 ×6、指数成分成交汇总 ×34、 全接口 ×1,测试总数 **217 → 289**。 ## [0.6.4] - 2026-10-22 ### 修复 - **`get_ticks()` 返回列表不是时间序,每 `page_size` 处时间回跳一次**。 `0x122F`(A股逐笔)与 EX 逐笔通道的偏移量 `start` 都是**从最新一笔往回数**的: 实测 `sh600000`,`start=0` 返回 `14:07:48..15:20:16`(当天最新 1000 条), `start=4000` 返回 `09:15:03..09:41:18`(当天最早)。而 `paginator` 按 `start` 升序拼接,于是拼出"新的块在前、旧的块在后"的倒序结构: | | 修复前 | 修复后 | |---|---|---| | `sh600000` 时间轴 | 4 处逆序跳跃(index 999 / 1999 / 2999) | 严格升序 | | `hk00700` 时间轴 | 21 处逆序跳跃(每 1800 条一次) | 严格升序 | 修复分两层:① `PageSpec.newest_first=True` 让 `paginator` 反页序拼装(页内本身升序, 只翻页序),这条能力保留给将来需要按"最新优先"锚点分页的命令;② A股逐笔最终改为 **单连接串行游标**(见下一条),从根上避开多主机锚点错位。 **`start` 参数语义同时明确**:它是"从最新往回数的偏移",不是"从最早往后数的偏移", `docstring` 已补充。注意这修正的是**顺序**,数据本身无缺口、无重复(4304 条唯一时间戳)。 - **`TransactionRecord.trade_count` 在集合竞价段被读成 42 亿量级脏值**。 该字段在协议里是**有符号** `int32`,但解析格式串写的是无符号 `I`。集合竞价段 (`bs_flag=8`)真实值为负数,按 uint32 解出 `4294966422`: ``` 原始 18 字节: 17820000 0ad71b41 d9000000 96fcffff 0800 修复前: trade_count = 4294966422 修复后: trade_count = -874 ← 0xfffffc96 的 int32 补码 ``` 实测 `sh600000` 全天 4304 条中有 **38 条**命中(占 0.88%),全部落在 09:15~09:25 集合竞价段;正常交易段(`bs_flag` 0/1/2/5)**无一条为负**。旧行为会让 `max()` / `mean()` 等统计直接失真(曾算出 `mean=37,920,247`)。 格式串由 `= DAY`)不受本缺陷影响。 - 本版只修 K 线。**同日发现的同类问题未包含在内**:EX 分时(`get_minutes`)对美股返回的 `MinuteBar.hour` 是**未取模的连续分钟数**(实测可达 27,即次日 03:xx),且 `MinuteBar` 无日期分量可承载跨日信息——修法涉及"是否新增字段 / 日期如何归属"的取舍,留待下一版决策。 - 新增 9 项针对性回归测试(分界点、月末与年末进位、390 根整日单调性、MAC 路径同样归一化)。 ## [0.6.1] - 2026-09-21 ### 变更 - **重写「当日首次启动测速缓存」,改为对用户完全无感**。原实现在 v0.5.0 已随包发布,但存在 三个会让它**静默失效**的缺陷,本次一并修正: | 缺陷 | 原实现 | 现在 | |---|---|---| | 候选集自指 | 连接池只把自己**已过滤后的成员**交给探针 → 只重测了 9 台,另外 20+ 台候选(含快节点)永远测不到 | 探针内部取**全部候选**(包内清单 ∪ 代码常量 ∪ env) | | 写回安装目录 | 结果写回 `src/pytdxdata/servers.json` → 容器 / 系统级安装只读、多用户互相覆盖 | 改写入**用户级缓存目录**,包内清单运行时**绝不被改写** | | 探测太弱 | 只做握手(`TdxConnection.test`),测不出「握手正常但 K 线空响应」的坏节点 | 发**真实业务命令**并要求返回非空(标准 / MAC / EX 各一) | | EX 池漏测 | EX 的 4 台从未被探测 | EX 一并纳入(7727 + 各自握手模式) | - 测速结果按**实测延迟升序**被 `config.get_standard_hosts()` 等采用;当天已有缓存则**不再刷新**。 后台执行,不阻塞 `start()`、不打印、失败静默降级。 - 本版基于 **0.6.0 的统一对外接口**构建(`get_bars` + 字符串标的);同时把 0.6.0 全接口回归测试里对旧探针入口(`pool.get_probe_cache`)的替身改为新入口(`pool.schedule_probe`), 保证单测不触发真实网络测速。 ### 修复 - **A股分时缩略采样 100% 失败**(`get_minutes(sampling=True)` / `get_chart_sampling()`): 旧实现走 `MacChartSamplingCmd`(**0x254D**),但该 opcode 属于 **EX 协议**,7709 标准 / MAC 主机对它一律不响应——实测 3 台主机各 10s 超时,叠加连接池 3 次重试约 24s 才抛错。 现改为**由分时(0x122D)数据派生**价格点(分时本身就是 240 点,语义一致), 实测 4 个 A股 场景均在 0.1s 内返回 240 点;EX 通道仍用 0x254D(84 点)。 - **历史专业财报整条链路不可用**(`get_financial_records_parsed()`): `tdxfin/gpcw.txt` 索引里写的是裸 `gpcwYYYYMMDD.zip`,而服务器**实际只提供未压缩的** `tdxfin/gpcwYYYYMMDD.dat`。旧实现把索引名直接丢给 `zipfile` → 必然 `BadZipFile`; 废弃别名 `get_financial_records()` 更危险,会**静默返回 0~1 字节空壳**而不报错。 现按候选名(`tdxfin/*.zip` → `tdxfin/*.dat` → 原名)逐个尝试并校验数据形态, zip 与未压缩 dat 都支持。实测 `gpcw20260630.zip` → **5568 条**、 `gpcw20260331.zip` → **5547 条**(样本 000001,584 个 float 字段), 别名返回 **13,068,116 字节**真实数据;尚未生成的占位条目 (如 `gpcw20260930.zip`,filesize=164)优雅返回空列表而非报错。 ### 新增 - `codec.financial` 新增 `looks_like_gpcw_dat()` / `extract_gpcw_dat()`: 财报字节的形态判定与「zip / 未压缩 dat」统一提取(纯标准库,可脱网单测) - 环境变量 `PYPYTDX_DATA_CACHE_DIR`(覆盖测速缓存目录)、 `PYPYTDX_DATA_DISABLE_PROBE`(关闭测速,CI / 测试用) - `tests/test_probe_cache.py`(37 项):当日缓存不刷新、跨日重测、 原子写入且不留 tmp、**不改写包内 `servers.json`(逐字节校验)**、 单飞并发、非法主机过滤、`DISABLE_PROBE`、池 `start()` 不阻塞 / `close()` 取消后台探针 ### 文档 - [安装与配置](https://openbot-coder.github.io/pytdxdata/getting-started/#当日自动测速无感): 新增「当日自动测速(无感)」小节——缓存路径、优先级链、环境变量一览 - [通道与数据源](https://openbot-coder.github.io/pytdxdata/internals/routing/#daily-probe): 新增「运行时:当日测速缓存」小节,逐条说明必须踩对的实现要点与反例 ## [0.6.0] - 2026-09-16 ### 新增 - **统一对外接口**:一个数据类型 = 一个方法,跨市场自动选路。 标的统用字符串写法(`sz000001` / `hk00700` / `usAAPL` / `cffex:IFL0`), A股/港股/美股/期货/期权混合查询一次返回。旧的 51 个按通道/市场分裂的接口中, 33 个保留为 deprecated 别名(运行时发出 `DeprecationWarning`,**1.0 移除**), 另 18 个(`get_quotes` / `get_xdxr` / `get_finance` / `get_auction` / `get_capital_flow` / `get_market_stat` / `get_unusual` / `get_server_info` / `get_kline_offset` / `get_board_members` / `get_board_summary` / `get_board_ranking` / `get_board_change_ranking` / `get_block_parsed` / `get_industry_map` / `get_financial_file_infos` / `get_financial_records_parsed` / `get_price_limits`)同名升级为统一接口。 | 数据类型 | 新接口 | 合并掉的旧接口 | |----------|--------|----------------| | 标的清单 | `get_universe(market)` | get_security_count + get_security_list + get_security_list_all + get_goods_count + get_goods_list | | 报价 | `get_quotes(symbols, *, fields)` | get_quotes + get_stock_quotes + get_goods_quotes + get_goods_quotes_list | | K线 | `get_bars(symbols, period, ...)` | get_kline + get_index_kline + get_kline_batch + get_kline_since | | 指标 | `get_indicators(symbols, indicators, ...)` | get_stock_kline_with_indicators | | 逐笔 | `get_ticks(symbols, *, date)` | get_transactions + get_goods_transaction + get_goods_transaction_all | | 分时 | `get_minutes(symbols, *, date, sampling)` | get_minute + get_minute_batch + get_chart_sampling + get_goods_chart_sampling + get_goods_tick_chart | | F10 | `get_f10(symbol, section)` | get_company_info_category + get_company_info_content | | 文件 | `get_file(name)` | get_block_info + get_report_file + get_file_meta + download_file | | 财务文件 | `get_financial_file_infos()` / `get_financial_records_parsed(fn)` | get_financial_file_list + get_financial_records | | 板块列表 | `get_boards(kind)` | get_board_list | | 板块成员 | `get_board_members(board)` → 归一 `SecurityQuote` | get_board_members + get_stock_quotes_list(分类报价) | | 个股板块 | `get_board_of(symbols)` | get_belong_board | | 快照 | `get_snapshot(symbols)` | get_symbol_info | > `TdxData` 公开方法 63 个 = **28 个统一接口** + 33 个 deprecated 别名 + `start`/`close`。 > 统一接口一律只接受字符串标的;同名旧方法不再兼容 `(market, code)` 元组写法。 - **库层标的解析** `pytdxdata.symbols`(原仅 CLI 内有):`parse_symbol` / `format_symbol` / `parse_symbols` / `market_targets` / `is_cn_index`;裸 6 位数字视为沪市指数。 - **归一数据模型**:`SecurityBar` / `SecurityQuote` / `TransactionRecord` / `MinuteBar` / `SecurityInfo` 等均新增 `symbol`(规范化标的串)/ `name` / `fields`(原始字段位兜底), 老构造写法不受影响(新字段有默认值)。 - `IndicatorSet` dataclass(`get_indicators` 返回单元:`bars + indicators` 组合)。 - `CacheKey.quote_key(..., tag=)` 支持按取数口径(标准五档 / MAC 字段位)隔离缓存。 ### 修复 - **分页器连接泄漏**:`Paginator._worker` 换连接后旧连接不释放、池子被耗干 (`_Slot` 包装 + 归还时按槽释放)。 - **日期区间 K线返回 0 条**:标准通道 `start` 偏移方向是递减(0=最新),旧的二分 假设递增。改为运行时探测方向再二分(`_offset_descending` / `_bisect_offset`)。 - **池子全冷却死等**:所有服务器进冷却后 `acquire` 排队 30s 超时。 补 `ignore_cooldown=True` 兜底,避免无人持有连接时永久等待。 - `HealthEngine.COOLDOWN_SECONDS` 保持 120s(旧的 FAIL_STREAK_COOLDOWN=1 意味着 任意一次通信失败即冷却,实测下正常服务器不应被冷却,保留该行为)。 ### 变更 - **`docs/api/index.md` 接口总览**重新组织:统一接口(推荐)优先于旧接口列表。 - `scripts/check_docs.py`:`docs/api/index.md` 从 `MUST_LIST_ALL` 移到 `MUST_NOT_BE_STALE`(只列推荐的统一接口,旧方法不强制出现在总览页)。 - CLI `tdx quotes` 改为统一 `td.get_quotes(symbols)`(跨市场混合报价)。 - CLI `tdx kline` 改为统一 `td.get_bars(sym, period)`。 - 测试 127 个用例全绿(新增 codec mock `get_file` 适配 + check_docs 新方法列表 + `tests/test_all_interfaces.py` 全接口回归:mock 连接逐个调用全部 63 个公开方法, 并以「覆盖哨兵」断言无方法遗漏)。 ## [0.5.0] - 2026-09-15 ### 新增 - **文档站**(MkDocs + Material + `mkdocstrings`),每次 push 自动构建并部署到 - **[`SKILL.md`](https://github.com/openbot-coder/pytdxdata/blob/main/SKILL.md)** — 面向 AI 编程助手的技能文件:三条必守约定、枚举取值表、 「想做什么 → 用哪个方法」决策表、9 条真实陷阱 - [`llms.txt`](https://openbot-coder.github.io/pytdxdata/llms.txt) — 面向 LLM 的结构化摘要,随站点发布到根路径 - `CHANGELOG.md` 独立成文件(此前内嵌在 README 中) - `scripts/check_docs.py` + CI 步骤 — **文档漂移检查**:代码有而文档漏写、或文档引用了已删除的方法,都会 fail - `tests/test_check_docs.py`(10 项)— 漂移检查器自身的自测 ### 变更 - **README 瘦身为「入口层」**:361 → 129 行。只保留定位 / 安装 / 30 秒上手 / 特性 / 文档导航 / 免责声明; CLI 手册、API 表、通道路由、架构树、扩展市场、easy-tdx 对比、Changelog 全部移交文档站与 `CHANGELOG.md` - API 文档改由 `mkdocstrings` **从 docstring 实时生成**,不再手抄(根治漂移) - 漂移检查扩展为两档:`MUST_LIST_ALL`(须列全所有公开方法)+ `MUST_NOT_BE_STALE`(只需无过时引用), 并把 `SKILL.md` / `README.md` / `llms.txt` / 教程类页面一并纳入 - 包元数据 `Documentation` 由仓库首页改指文档站 - 测试用例 **99 → 109** ### 文档 - 新增文档站 19 页:快速开始 / 场景示例 / CLI / FAQ / 贡献指南 / 更新日志 / API 参考(总览·TdxData·枚举·模型·指标·解析器)/ 深入原理(架构·协议·三池路由·缓存) - 明确口径:`TdxData` 公开方法共 **53 个**(= 51 个数据方法 + `start` / `close`), 此前各处笼统写的「51 个公开方法」不严,已统一更正 ### 修复 - 修正**中文标题锚点被默认 slugify 剥光**导致跨页深链接全部失效的问题 (改用 `pymdownx.slugs.slugify`,并给被引用的标题加显式 ASCII id;`--strict` 不会报这个错,只能靠锚点检查兜住) - README 中标注的测试数量(85)与 pytest 实际收集数不符,已更正为 109 个用例 ## [0.4.0] - 2026-09-15 ### 新增 - **服务器文件「下载 + 解析」能力**(对齐并超越 easy-tdx 的文件解析): - `get_block_parsed(filename)` — 板块 `block_zs/gn/fg.dat` → `list[TdxBlock]`(板块名 / 类别 / 成分股代码) - `get_industry_map()` — `tdxhy.cfg` → `dict[str, IndustryInfo]`(通达信行业 + 申万行业) - `get_financial_file_infos()` — `tdxfin/gpcw.txt` → `list[FinancialFileInfo]`(文件名 / MD5 / 大小) - `get_financial_records_parsed(filename)` — `gpcw*.zip` 解压 + 解析 → `list[FinancialRecord]`(每股原始字段) - 解析器模块 `codec/block.py`、`codec/industry.py`、`codec/financial.py`(纯标准库,脱网可单测) - 数据模型 `TdxBlock` / `IndustryInfo` / `FinancialFileInfo` / `FinancialRecord` - CLI 新增 4 个命令:`tdx block` / `tdx industry` / `tdx financial-list` / `tdx financial` - 测试 `tests/test_cli_files.py`(11 项 CLI 离线测试,FakeTD 桩) ### 修复 - 修复财报索引市场字段解析(`<6s1c1L` → `<6sBL`)。此前恒判深市,现市场字段 **0=深 / 1=沪** 正确 ### 变更 - 公开异步方法 **47 → 51**,新增接口全部**向后兼容**(原 `bytes` 方法保留) - README 与 `docs/API_REFERENCE.md` 同步更新 ## [0.3.2] - 2026-08-17 ### 新增 - `get_kline_batch(stocks, period, ...)` — 批量 K 线,多股票自动并发,连接池分配不同服务器 - `get_minute_batch(stocks, ...)` — 批量分时,多股票自动并发 ## [0.3.1] - 2026-08-17 ### 变更 - `get_kline(MIN_1)` 切换为 **MAC 通道**(`0x122E`),解决标准通道 1 分钟 K 线深度不足的问题 - `router.py` 中 `KlinePeriod.MIN_1` 强制路由到 MAC 通道 - 标准通道其他周期(`MIN_5/15/30/60/DAY/WEEK/MONTH`)不受影响 ### 修复 - **修复 MAC K 线并发分页的数据空洞**:并发分页器把不同页分配到不同服务器, 而各服务器数据深度不一致时 `stop_when_short` 会导致**非确定性数据丢失**。 改为**单连接串行分页**(`_fetch_mac_kline_serial`,`start` 动态偏移,与 easy-tdx 一致) ## [0.3.0] - 2026-08-17 ### 变更 - `get_minute` 切换为 **MAC 通道**(`0x122D` `MacTickChartCmd`),历史分时稳定返回完整 240 条(09:30~14:59) - 移除不再使用的 `GetHistoryMinuteTimeDataCmd` ### 新增 - `protocol/commands/mac_tick.py` — MAC 单日分时图命令 ## [0.2.2] 及之前 - 初始版本:动态连接池 + 双层 TTL 缓存 + 3 连接并发分页 + 双通道(标准 / MAC)+ 扩展市场(港股 / 美股 / 期货 / 期权) [Unreleased]: https://github.com/openbot-coder/pytdxdata/compare/v0.7.1...HEAD [0.7.1]: https://github.com/openbot-coder/pytdxdata/compare/v0.7.0...v0.7.1 [0.7.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.6.0...v0.7.0 [0.6.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.5.0...v0.6.0 [0.5.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.4.0...v0.5.0 [0.4.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.3.2...v0.4.0 [0.3.2]: https://github.com/openbot-coder/pytdxdata/compare/v0.3.1...v0.3.2 [0.3.1]: https://github.com/openbot-coder/pytdxdata/compare/v0.3.0...v0.3.1 [0.3.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.2.2...v0.3.0