CZSC / 数据源
czsc 数据源：四条连接器路径与各自的凭据前置
结构算得再准，数据不对也是白算。czsc 官方提供四条取数路径，覆盖期货、A 股、数字货币与本地缓存，每条都要自己准备账号或密钥，交易时段与复权口径也得自己确认。这一页把四条路径、前置条件与常见坑列清楚。
四条路径覆盖三类市场
官方在 README 里用一张表列出四个连接器模块，并说明各自的定位。下表补上凭据与口径要点。
| 模块 | 数据源 | 覆盖市场 | 凭据与前置 | 适用场景 | 注意点 |
|---|---|---|---|---|---|
| tq_connector.py | 天勤 | 期货实时与历史行情 | 需天勤账号；按官方流程登录取数 | 国内期货研究 | 官方曾修复该连接器的一处静默时间漂移问题，升级后行为会变化 |
| ts_connector.py | Tushare | A 股历史数据 | 需 Tushare Token（环境变量方式配置） | A 股历史研究与回测 | 接口额度与权限由数据源规则决定；复权口径需自己确认 |
| ccxt_connector.py | CCXT | 数字货币交易所 | 需交易所 API 密钥（按 CCXT 约定配置） | 加密市场研究 | 各交易所的时间戳精度与限频不同，需按交易所文档核对 |
| local_data.py | 投研数据本地缓存 | 取决于本地已有数据 | 需已有整理好的本地数据 | 已有数据管线、不想重复取数 | 数据格式要与库的预期一致，字段缺失会在转换阶段暴露 |
| 统一数据客户端 | 工具模块内的数据客户端与缓存 | 取决于接入源 | 无额外要求 | 在多个源之间切换 | 缓存能减少重复请求，但要注意缓存更新的时效 |
从取数到进入结构分析的四步
官方示例把这条链路串得很短：取数 → 转成标准 K 线 → 构造分析对象 → 读结构。难点通常在中间两步的清洗。
选择连接器并配置凭据
按市场选择对应模块，按要求准备账号或密钥（例如 Tushare 走环境变量配置 Token）。预期能成功发起一次取数请求。
核对时间与字段口径
确认返回数据的时间字段已去掉时区信息，且时间与周期对齐（例如分钟线的时间戳代表桶的起点还是终点）。预期时间字段是本地无时区的时间。
转成标准 K 线对象
用官方的格式转换函数把数据表转成 K 线对象列表，并指定周期枚举。预期得到可直接喂入分析对象的序列。
校验数据质量再入结构
用官方的 K 线质量校验工具检查缺失值、重复时间与异常值，必要时补齐或剔除。预期进入结构分析的数据没有缺失行情值。
一处被修复的静默时间漂移
官方在变更记录里写明了一个已经修复的连接器问题。它的价值在于提醒：时间口径出错时，程序不会报错，只会安静地给出错结果。
| 项 | 内容 | 影响 | 现状 |
|---|---|---|---|
| 问题现象 | 天勤连接器在取数后调用重采样时，没有显式传入基础周期 | 周期被默认标成 1 分钟，导致时间标签出现静默漂移 | 官方已修复：现在显式传入调用方指定的周期 |
| 为什么难发现 | 不会报错，只是时间刻度整体偏了 | 结构划分与后续信号都会跟着偏 | 升级到含该修复的版本即可 |
| 同类风险 | 任何「取数后转换周期」的环节都可能出现口径不一致 | 离线重采样与实时合成对同一数据可能给出不同结果 | 固定一条路径：实时用合成器，离线用重采样，不要混用 |
| 自查方式 | 取一小段已知周期的数据，打印转换后的时间刻度 | 能最快发现漂移 | 把这一步做成固定检查 |
配套的数据质量与辅助工具
工具模块里有一组不显眼但很实用的能力，官方 API 手册把它们分散列在不同分类下，这里集中起来看。
| 工具 | 作用 | 适用场景 | 注意点 |
|---|---|---|---|
| K 线质量校验 | 检查 K 线序列中的缺失、重复与异常 | 取数后入结构前 | 校验规则由实现定义，不要假设它覆盖了全部口径问题 |
| 指数成分 | 处理指数成分股相关数据 | 需要按指数范围筛选时 | 成分随调整变动，取数日期要记录 |
| 持股概念 | 处理个股所属概念板块 | 概念维度研究 | 概念标签由数据源定义，跨源不可比 |
| 交易时段标记 | 标注交易时段相关区间 | 过滤非交易时段数据 | 时段模板与品种相关，跨品种不能套用 |
| 波动率标记 | 计算并标注波动状态 | 波动分层研究 | 窗口长度直接改变结论 |
| 告警捕获 | 捕获运行期告警 | 长时间批量任务 | 属辅助能力，不替代日志 |
| 缓存与日志 | 数据缓存与运行日志 | 减少重复请求、排查问题 | 缓存要设置合理的更新策略 |
数据层排查表
数据问题多半不报错，只表现为「结构看起来不对」。按下表倒查比读日志更快。
| 现象 | 可能原因 | 核对方法 | 处理方向 |
|---|---|---|---|
| 构造对象时报时间相关错误 | 时间字段带时区，被新版本显式拒绝 | 检查时间列的类型是否带时区 | 去掉时区后再转换 |
| 回放中途抛缺失值错误 | 行情里有缺失的成交量或价格，且新版本会显式报错 | 统计缺失值数量与位置 | 补齐或剔除后再入结构；不要指望它被静默跳过 |
| 时间刻度整体偏移 | 取数后转换周期时基础周期没传对 | 取一段已知周期数据打印时间刻度 | 显式传入周期；确认使用含修复的版本 |
| 同一数据两个周期结果不一致 | 一条路径走实时合成、另一条走离线重采样 | 确认两处使用的转换方式 | 统一路径；注意重采样丢弃未完成桶对日级以上不起作用 |
| 结构粒度突然变化 | 成笔长度参数变了（含升级后环境变量开始生效） | 核对构造参数与环境变量 | 固定一种来源并把值写进配置 |
| 取数报权限或额度错误 | Token、账号或接口权限不足 | 看数据源返回的错误码 | 按数据源规则补齐权限或调整请求频率 |
取数这一段，两条路线有什么不同
取数是两边都做的事情，但形态不同：一边是代码里的连接器，一边是一次提问。
| 维度 | 自建连接器 | EasyClaw 数据类技能 | 怎么选 |
|---|---|---|---|
| 使用方式 | 在代码里调用对应模块，自己处理返回结构 | 用自然语言提问，直接拿到整理后的结果 | 要进自己的策略工程就自建；只要结论就提问 |
| 凭据 | Tushare Token、天勤账号或交易所密钥 | 部分技能也需要 Token 或 Key（例如 Tushare 类技能） | 两边都要准备，前置条件可以复用 |
| 覆盖面 | 期货、A 股、数字货币与本地缓存 | 股票、期货、期权、基金、外汇、债券、指数与加密数据（按技能文档） | 覆盖面各有侧重，按你的市场核对 |
| 与结构分析的衔接 | 直接转成内部 K 线对象，链路连续 | 输出的是数据与结论，需要自己再转成代码可用结构 | 要接缠论结构必须回到自建链路 |
常见问题
数据源相关的授权、额度与口径以各数据源官方说明与项目文档为准。
官方支持哪些数据源？
官方 README 列出四个连接器模块：天勤用于期货实时与历史行情，Tushare 用于 A 股历史数据，CCXT 用于数字货币交易所，另有本地缓存入口用于读取已有的投研数据。除此之外还可以通过工具模块里的统一数据客户端与缓存来组织取数。
需要准备哪些凭据？
按你选的数据源准备：Tushare 需要 Token（官方实践是用环境变量配置），天勤需要账号并按官方流程登录，CCXT 需要交易所 API 密钥。官方在案例索引里也特别标注了 Tushare 案例的 Token 前置条件。
为什么升级后取数会报时间错误？
因为新版本把「带时区时间被静默转成 UTC」改成了显式报错。历史行为下时间会被悄悄转换、导致周期桶定位全部错位。现在需要在取数后先去掉时区信息，再进入后续转换。
重采样和实时合成能混用吗？
不建议。官方提供两条能力：实时逐根更新用 K 线合成器，离线把一段数据整体转换周期用重采样函数。两者内部虽然共用聚合逻辑，但调用方式不同；混用容易出现同一数据两套时间口径的问题。另外重采样有一个官方标注的已知限制：丢弃未完成桶的开关对日级以上的目标周期不起作用。
数据质量需要自己校验吗？
需要。工具模块提供了 K 线质量校验、交易时段标记、波动率标记等能力，但复权方式、集合竞价是否包含、停牌日怎么补这些口径官方不做统一约定。建议把校验做成固定环节，并在取数时记录数据日期。
取数能用 EasyClaw 代替吗？
取数这一段可以部分代替：EasyClaw 本机有财经数据类技能，可以按提问方式拿到行情与基本面数据。但它们输出的是数据与结论，不提供缠论结构识别，也无法直接接进这套代码链路。如果你只是要先看数、看指标，用技能更省事；要进策略工程仍需自建连接器。两者没有已证实的集成关系。