七个核心对象，各自管一段
官方 API 手册为每个对象标注了 Rust 实现文件，下表照录，便于你直接定位源码。
| 对象 | 含义 | 实现位置 | 内部依赖 | 适用场景 | 注意点 |
|---|---|---|---|---|---|
| CZSC | 缠论分析主对象，管理原始 K 线、分型与笔列表 | crates/czsc-core/src/czsc.rs | RawBar、NewBar、FX、BI、check_fx、check_bi、remove_include | 结构分析的起点 | 1.0.1 起新增 min_bi_len 字段与 zs_list 属性，构造签名也随之扩展 |
| RawBar | 原始 K 线数据结构 | crates/czsc-core/src/bar.rs | Freq | 行情入参 | 构造时拒绝带时区的时间对象，需要先做本地化处理 |
| NewBar | 去包含关系后的 K 线 | crates/czsc-core/src/bar.rs | RawBar | 分型判定的输入 | 去包含会改变 K 线数量，索引不能与原始 K 线一一对应 |
| FX | 分型（顶分型 / 底分型） | crates/czsc-core/src/fx.rs | NewBar、Mark | 标出结构的转折候选点 | 分型不等于买卖点，它只是结构候选 |
| BI | 笔，含力度、R²、斜率等统计量 | crates/czsc-core/src/bi.rs | FX、NewBar、Direction、FakeBI | 结构的主干与力度比较 | 除坐标外还带统计量，可用于强度筛选 |
| FakeBI | 由笔内部分型连接得到的近似次级别笔 | crates/czsc-core/src/bi.rs | FX | 在次级别视角观察同一段走势 | 它是由已有分型连接出来的近似结果，不是真实的次级别数据 |
| ZS | 中枢数据结构 | crates/czsc-core/src/zs.rs | BI、Direction | 判断震荡区间与结构级别 | 1.0.1 起 zs_list 基于 finished_bis 计算，与早期实现口径可能不同 |
| Freq / Mark / Direction / Operate | 周期、分型标记、方向、操作四类枚举 | crates/czsc-core/src/enums.rs | 无 | 贯穿全部结构的类型约定 | rc.8 起四个枚举都暴露 .name 并支持哈希，可作为字典键使用 |
六个算法函数，可以单独调用
这些函数在官方 API 手册中属于「缠论核心算法函数（Rust 实现）」一组。它们可以被独立调用，便于你校验结构逻辑或实现自己的流程。
| 函数 | 用途 | 输入与依赖 | 适用场景 | 注意点 |
|---|---|---|---|---|
| check_fx | 检查三根无包含 K 线是否构成分型 | NewBar / FX / Mark | 自定义分型判定流程 | 输入必须是去包含后的 K 线，直接传原始 K 线结果不成立 |
| check_fxs | 批量检查分型序列 | check_fx、FX | 一次性标注整段区间 | 本质是 check_fx 的批处理封装 |
| check_bi | 检查两个分型之间是否构成笔 | FX / BI / NewBar | 自定义成笔规则或校验 | 1.0.1 起改为接收成笔长度阈值参数，不再硬编码 |
| remove_include | 去除 K 线包含关系 | RawBar / NewBar | 结构分析的前置处理 | 去除后 K 线数量会变化，后续长度计算要以 NewBar 为准 |
| freq_end_time | 计算指定周期的 K 线结束时间 | Freq | 对齐多周期数据、定位桶 | 日级以上桶的时间会被归到 00:00:00，做重采样时要注意 |
| is_trading_time | 判断给定时间是否为交易时间 | Freq | 过滤非交易时段数据 | 交易时段模板与品种相关，不能跨品种套用 |
成笔阈值：一个曾经完全失效的参数
成笔长度直接决定结构的粗细。这个参数在 1.0.1 之前存在一个真实缺陷，官方已在 CHANGELOG 中记录并修复，值得单独说明。
| 项 | 1.0.0 及之前 | 1.0.1 之后 | 影响 | 注意点 |
|---|---|---|---|---|
| 缺陷现象 | 设置 CZSC_MIN_BI_LEN 后笔数量没有任何变化 | 该变量真正作用于成笔逻辑 | 此前用环境变量调参等于没调 | 对应官方 issue #328 |
| 根因 | crates/czsc-core/src/analyze/utils.rs 的 check_bi 内硬编码了长度为 6 的阈值，且 CZSC 构造函数签名只有 bars_raw 与 max_bi_num 两个参数 | check_bi 改为接收阈值参数，CZSC 增加 min_bi_len 字段 | 环境变量只影响 envs 的返回值，对笔列表毫无作用 | 这是实现细节问题，不是设计意图 |
| 现在的取值顺序 | 不适用 | 构造参数显式传入且大于 0 时优先；否则读环境变量（大小写不敏感）；再否则默认 6 | 三种来源可预期地覆盖 | max_bi_num 同样改为 env-aware，默认 50 |
| 相关环境变量 | CZSC_MIN_BI_LEN 名义存在但无效 | CZSC_MIN_BI_LEN（默认 6）、CZSC_MAX_BI_NUM（默认 50）、CZSC_VERBOSE（默认 False） | 结构粗细与日志详细度可控 | 页面上的默认值来自官方 README 表格 |
| 回归保障 | 无 | 新增测试锁定「更大阈值产出更少更长的笔」 | 该行为不会被后续改动悄悄破坏 | 测试名见官方 CHANGELOG |
1.0.1 新增的公开结构分析链
这一批 API 在 Python 顶层、czsc._native 类型桩与 Rust facade 三处同步暴露，属于官方定义的公开能力。
| API | 用途 | 适用场景 | 注意点 |
|---|---|---|---|
| create_fake_bis | 由分型连接生成近似次级别笔 | 想看更细的结构层次 | 结果是从已有分型推导的近似值，不能当真实次级别数据 |
| get_zs_seq | 取得中枢序列 | 批量分析中枢演化 | 序列口径以官方实现为准 |
| is_symmetry_zs | 判断中枢是否对称 | 结构形态筛选 | 对称性的判定标准由实现定义 |
| is_bis_up | 判断笔序列是否向上 | 方向确认 | 方向判断依赖传入的笔序列范围 |
| is_bis_down | 判断笔序列是否向下 | 方向确认 | 与 is_bis_up 成对使用 |
| check_gap_info | 检查缺口信息 | 跳空相关结构判断 | 缺口定义以官方实现为准 |
| CZSC.zs_list | 基于 finished_bis 计算的中枢列表属性 | 直接读取中枢 | 基于已完成的笔，未完成的笔不参与 |
两处构造约束：不符合就直接报错
官方在 1.0.0-rc.8 把两类「静默出错」改成了显式报错。它们都属于破坏性变更，升级时会立刻暴露出来。
| 约束 | 历史行为（问题） | 现在行为 | 你该怎么做 | 适用场景 |
|---|---|---|---|---|
| RawBar 拒绝带时区的时间 | 带时区的入参走时间戳转换被静默转成 UTC，例如上海时间 09:31 变成 01:31，导致下游周期桶定位全部错位 | 抛出 ValueError | 先执行 df['dt'] = df['dt'].dt.tz_localize(None) 去掉时区，再做转换 | 从数据库或带时区的行情接口取数时 |
| K 线合成拒绝 NaN 行情值 | 成交量相加会让 NaN 沿桶传染，与 pandas 默认跳过 NaN 求和的口径不一致，安静地产出错值 | 显式返回错误，并沿信号与交易器调用链向上抛 | 在入数据前清洗缺失值，或在调用处捕获异常 | 拼接多段行情或补齐交易日时 |
| 交易器与信号更新方法改为可失败 | 遇到 NaN 或周期不匹配时吞掉错误，用旧状态继续算，可能产出与真实情况不符的信号 | 返回可失败结果，硬错上抛 ValueError | 调用方准备异常处理或允许异常冒泡 | 多周期联立与批量回放 |
| 错误类型统一 | 历史实现混用多种异常类型，捕获时容易漏 | 解析失败路径统一返回 ValueError | 统一按 ValueError 捕获即可 | 所有时间解析路径 |
和「指标类技术分析」不是一件事
很多中文资料把缠论指标和 MACD 之类的指标放在一起讲，这容易让人低估结构识别的工程量。两者输出的东西根本不同。
| 维度 | 缠论结构识别（czsc 的定位） | 指标类技术分析 | 对使用者的影响 |
|---|---|---|---|
| 输出对象 | 分型、笔、中枢等结构对象及其统计量 | 指标数值序列 | 前者可直接作为策略条件，后者通常还要再加工 |
| 依赖关系 | 笔依赖分型，中枢依赖笔，存在严格的先后顺序 | 多数指标彼此独立 | 结构计算不能跳步，参数会影响下游全部结果 |
| 参数敏感度 | 成笔长度等参数会显著改变结构粒度 | 参数影响曲线平滑度 | 换参数等于换了一套结构，需要重新验证 |
| 数据要求 | 对时间对齐与缺失值更敏感（时区与 NaN 都会被拒绝） | 一般容忍缺失值 | 取数环节的清洗质量直接决定结构是否可用 |
| 典型误用 | 把分型当买卖点 | 把指标金叉当买卖点 | 两者都不是买卖指令，都需要事件与持仓层承接 |
常见问题
结构相关的口径以官方 API 手册与 CHANGELOG 为准，本文不做实现之外的推断。
分型和笔能直接当买卖信号用吗？
不建议。官方把结构层与信号、事件、持仓层分开设计：分型只是结构的转折候选，笔是结构主干，真正驱动交易的是一层信号组合出来的事件。把分型当买卖点用，等于绕过后面三层，也就失去了这套框架的主要价值。
成笔长度该怎么设？
三种来源按优先级覆盖：构造时显式传入且大于 0 的值优先；否则读环境变量 CZSC_MIN_BI_LEN（大小写不敏感）；再否则用默认值 6。1.0.1 之前这个环境变量是无效的，升级后结果会变化，建议固定一种来源并把值写进配置。
为什么我的带时区数据会报错？
因为官方在 rc.8 把「静默转 UTC」改成了显式报错。历史行为下，上海时间 09:31 会被悄悄转成 01:31，导致周期桶定位全部错位，问题极难排查。现在需要在入参前去掉时区信息，官方给的写法是 df['dt'] = df['dt'].dt.tz_localize(None)。
中枢列表是怎么算出来的？
1.0.1 新增了基于已完成笔（finished_bis）计算的 zs_list 属性，同时提供 get_zs_seq 取中枢序列、is_symmetry_zs 判断中枢是否对称。注意它只使用已完成的笔，因此最新的未完成段不会体现在中枢里。
FakeBI 是真实的次级别数据吗？
不是。官方定义里 FakeBI 是「笔内部分型连接得到的近似次级别笔」，也就是从当前级别已有的分型推导出来的近似结构。想得到真实的次级别结构，需要真实导入次级别 K 线再单独分析。
结构这部分 EasyClaw 能替我做吗？
不能。EasyClaw 本机的技术分析类技能做的是指标与形态层（例如均线、MACD、K 线形态与量价关系），不提供缠论分型、笔、中枢的自动识别，也不提供信号-事件-交易体系。需要缠论结构就只能走自建路线；两者之间没有已证实的集成关系。