A 股分钟线接入 CZSC：最容易错的不是字段，而是时间标签

不同供应商的分钟 K 线都有 open、high、low、close、volume，看起来只要改列名就能接入策略框架。一次 Codex 历史会话中，我把一套 A 股行情 SDK 接进 CZSC，真正花时间的却是一个不起眼的问题：源数据的 09:30 表示 09:30:00–09:30:59，CZSC 的分钟棒则用结束时刻 09:31 标记。

如果这个偏差没有修正，所有多周期合成和信号都会整体错一档。数值看起来仍然合理，因而比直接报错更危险。

先定义统一的 RawBar 契约

连接器的目标不是返回“一个 DataFrame”，而是提供稳定语义：

• symbol：明确市场与资产；
• dt：统一为 K 线结束时刻；
• open/high/low/close：浮点价格；
• vol/amount：成交量与成交额；
• freq：与实际聚合周期一致；
• 可选择 DataFrame 或 CZSC RawBar。

现有 Tushare 连接器支持股票、指数和基金，以及 1/5/15/30/60 分钟。新增数据源还提供 1/3/5/10/15/30/60/120 分钟原生周期。CZSC 本地研究缓存则以 1 分钟 Parquet 为基础，再重采样到目标周期。

调用表面可以统一为 get_symbols() 和 get_raw_bars()，但每个源的时间、复权和分页契约仍需要各自适配，不能因为函数名一致就假设数据等价。

起始标签与结束标签只差一分钟吗

对 1 分钟线，源端 09:30 如果代表 [09:30:00, 09:30:59]，转换后应标为 09:31。原生 5 分钟线的 09:30 则应移动到 09:35：

df["dt"] = pd.to_datetime(df["kline_time"]) + pd.Timedelta(minutes=minutes)

不能把所有周期固定加一分钟。更不能先把起始标签误当结束标签，再用 CZSC 分桶；那会把 09:30 的数据放进错误区间，午休与收盘边界也可能产生额外异常。

这类 bug 用肉眼看几行 CSV 很难发现。那次接入用一个完整交易日做了交叉验证：源端返回 240 根 1 分钟线，原生 5 分钟线 48 根；1 分钟数据经过 CZSC 合成同样得到 48 根，双方 OHLCV 完全一致，成交额只剩浮点累加误差。只有这种端到端等价检查，才能证明标签、分桶和午休处理同时正确。

原生周期与重采样周期要走不同路径

供应商原生支持的周期直接查询，再按该周期长度修正标签。CZSC 支持、供应商不支持的 2/4/6/12/20 分钟等周期，则查询 1 分钟线后调用 resample_bars。

这里必须显式告诉重采样器 base frequency 是 1 分钟。若沿用默认值或错误地把目标周期当 base，生成对象可能写着“30分钟”，内部却按另一分桶规则聚合。

重采样还要覆盖：

• 早盘、午休和尾盘的交易所分段；
• 日期边界和半日市；
• 重复 bar 与缺失 bar；
• 非交易时段数据；
• 查询起止边界是闭区间还是开区间。

复权不是乘一个因子就结束

原始行情结合复权因子时，常见公式是：

后复权价格 = 原价 × 当日因子
前复权价格 = 原价 × 当日因子 ÷ 最新因子

OHLC 同步调整，成交量和成交额通常保持原值。连接器还要决定“最新因子”相对于查询截止日还是全量最新日，避免历史回测读取了未来才知道的因子。

用于形态与收益研究时，前后复权序列可能只差一个常数比例，信号日期一致；但输出价格的含义不同。真实委托永远需要不复权市场价格，不能把后复权价格直接送给交易接口。

第三方 SDK 也是威胁边界

那次接入还发现几类不能由策略层承担的问题：

• 登录过程可能向 stdout 打印完整会话信息；
• 登录函数返回值与实际状态不完全一致；
• 失败路径可能抛出 SystemExit；
• SDK 使用进程级全局状态和查询锁；
• 可选存储功能依赖没有在 wheel 元数据中完整声明。

连接器因此在登录时捕获输出，只记录成功/失败；用轻量健康查询确认真实状态；把 SystemExit 转成普通运行时错误；每进程复用一个客户端并串行查询。凭据从环境读取，不进入日志、缓存键或异常文本。

隔离单元测试覆盖字段、标签、复权和错误映射；真实凭据测试只作为慢速 integration test，并明确检查输出中不存在 token。第三方 SDK 能返回数据，不等于可以直接进入生产研究链路。

数据源清单要按市场准确命名

CZSC 还包含天勤和 CCXT 等连接器，但它们分别面向期货和数字资产，不能被笼统列入“A 股分钟线来源”。CSV、Parquet、Feather 可以导入自有数据，也只是文件入口，不是在线供应商。

数据接入最重要的不是支持列表更长，而是每个来源都能回答：覆盖什么资产、有哪些原生周期、时间戳代表什么、如何复权、缺失如何处理、怎样独立复算。字段映射只是第一步，语义对齐才是连接器真正的产品。

项目地址：cyijun/czsc