CZSC / 多级别联立
czsc 多级别联立：把多个周期的信号做成一份决策
单周期信号只能看到一段走势，缠论要的是级别之间的相互印证。czsc 的做法是用 K 线合成器把基础周期展开成多个大级别，再由交易器在这些级别上联立决策，并把仓位一起管起来。这一页说明五类对象的职责、合成流程，以及 rc.8 引入的失败即报错行为。
五类对象，各管一段链路
下表按官方 API 手册的「交易器与信号管理」分类整理。区分 CzscSignals 与 CzscTrader 是关键：一个只出信号，一个还要管仓位。
| 对象 | 职责 | 实现位置 | 适用场景 | 注意点 |
|---|---|---|---|---|
| BarGenerator | 多周期 K 线合成器：一个基础周期喂进去，得到多个大级别 | crates/czsc-trader/src/bar_generator.rs | 需要多周期数据时 | 入参是基础周期与目标周期列表；不接收 NaN 行情值 |
| CzscSignals | 多周期联立信号分析器，只管信号不管仓位 | crates/czsc-trader/src/signals.rs | 只想看多周期信号是否同时成立 | 它的更新方法 rc.8 起会抛错 |
| CzscTrader | 多周期联立交易器，含仓位管理与信号 | crates/czsc-trader/src/trader.rs | 要完整回放含持仓的策略 | 内部依赖 CzscSignals、Position 与 Event |
| Position | 持仓结构：开仓事件 + 平仓事件 + 风控 | crates/czsc-trader/src/position.rs | 描述一段持仓的完整生命周期 | 它描述目标状态，不等于实际成交 |
| Event | 事件结构：信号的逻辑组合（与、或、非） | crates/czsc-trader/src/event.rs | 构造复合开平仓条件 | 改策略逻辑通常只改事件层 |
| 策略门面 | CzscStrategyBase / CzscJsonStrategy | crates/czsc-trader/src/strategy.rs（Python 侧仅透传） | 把一套信号与持仓配置封装成策略 | 保存与读取的完整性校验用规范化 JSON 的哈希，两端结果一致 |
多周期 K 线合成怎么走
官方 README 给出的示例是「合成器 + 周期列表」的用法：构造时声明基础周期与目标周期，之后逐根更新，再从合成器里取各周期数据。下面把这条链路拆开。
准备基础周期数据
把行情整理成原始 K 线对象列表，并确认时间字段已经去掉时区（带时区的时间会被直接拒绝）。预期得到可入参的 K 线序列。
声明基础周期与目标周期
构造合成器时传入基础周期与目标周期列表，例如基础周期为 1 分钟，目标为 5 分钟、30 分钟与日线。预期得到一个待填充的合成器。
逐根更新
把原始 K 线按时间顺序逐根交给合成器更新。预期各周期的桶被正确闭合，跨周期的收盘点不会提前出现。
取出各周期数据
从合成器按周期名取出 K 线序列，交给结构分析或信号生成。预期各周期数据可直接进入后续流程。
交给联立层
把多周期数据交给联立分析器或交易器，由它们在各周期上分别算信号再做联立。预期得到一份跨周期的信号状态。
rc.8 起：宁可报错，也不要用旧状态算
这是升级时最容易被拦住的变更。官方把它归入破坏性变更，并说明了动机：历史上遇到异常输入会吞掉错误继续算，可能产出与实际不符的信号。
| 方法 | 历史行为 | 现在的行为 | 你要做什么 | 适用场景 |
|---|---|---|---|---|
| CzscTrader.update | 遇 NaN 或周期不匹配时静默继续，用旧状态产出结果 | 返回可失败结果，硬错抛出 ValueError | 补异常处理，或在入数据前把数据洗干净 | 逐根回放 |
| CzscTrader.on_bar | 同上 | 同上 | 同上 | 事件驱动式回放 |
| CzscTrader.update_signals | 同上 | 同上 | 同上 | 只更新信号不做交易 |
| CzscSignals.update_signals | 同上 | 同上 | 同上 | 纯信号联立 |
| BarGenerator.update_bar | 成交量相加会让 NaN 沿桶传染，与 pandas 跳过缺失值求和的口径不一致 | 显式返回错误并向上传播 | 缺失值先补齐或剔除 | 多段行情拼接 |
官方自己标注的两处已知限制
官方在 1.0.0-rc.8 的变更记录里主动写明了两个尚未处理的问题，并说明会另开改动处理。使用时按「已知限制」对待即可。
| 限制 | 具体表现 | 影响范围 | 现有规避方式 |
|---|---|---|---|
| 重采样丢弃未完成桶对日级以上无效 | czsc.resample_bars 的 drop_unfinished 参数对日、周、月、季、年这些目标周期实际不起作用，因为周期结束时间会把日级以上的桶时间归到 00:00:00 | 离线批量转换到日级以上周期时 | 自己在转换后处理尾部未完成数据 |
| 合成器预分配内存偏大 | 构造时为基础周期的桶也按输入长度预分配容量，单次输入达到百万级时会产生约一倍的内存浪费 | 一次性灌入超大历史数据时 | 分批喂入 |
| 日级以上时间口径 | 周期结束时间函数把日级以上的桶时间归到零点，做时间对齐时需注意 | 跨周期对齐 | 对齐前统一时间口径 |
配套的研究与优化入口
除了交易器本身，官方还提供了批量研究与参数优化的入口。注意其中一部分的位置在 1.0 的清理中发生过迁移。
| 入口 | 作用 | 现在的导入位置 | 适用场景 | 注意点 |
|---|---|---|---|---|
| run_replay | 单品种回放 | 顶层导出 | 先跑通一个品种 | 入参含信号序列与持仓序列 |
| run_research | 批量品种研究 | 顶层导出 | 多品种批量验证 | 批量跑要注意数据量与耗时 |
| OpensOptimize / ExitsOptimize | 开仓与平仓参数优化 | czsc.utils.optimize | 参数寻优 | 该类已从交易器模块迁到工具模块，旧导入路径在 1.0 会失败 |
| CzscOpenOptimStrategy / CzscExitOptimStrategy | 配套的优化策略封装 | czsc.utils.optimize | 与上面两个优化器配对使用 | 同上，注意导入路径 |
| generate_czsc_signals | 在 K 线序列上批量生成信号 | czsc.traders | 不回放持仓只看信号 | 与交易器回放是两个粒度 |
常见问题
联立相关的口径以官方 API 手册与变更记录为准，本文不做实现之外的推断。
CzscSignals 和 CzscTrader 该用哪个？
看你要不要仓位。CzscSignals 只做多周期联立的信号分析，不涉及仓位；CzscTrader 在其之上还包含仓位管理，内部同样依赖持仓与事件对象。只想验证信号是否同时成立用前者，要完整回放策略用后者。
为什么升级后回放会抛异常？
因为官方在 rc.8 把「遇到异常输入静默继续」改成了失败即报错：交易器与信号分析器的更新方法遇到缺失值或周期不匹配时会抛出 ValueError，K 线合成器也会对缺失行情值显式返回错误。这是有意为之的变更，目的是避免用旧状态算出与真实情况不符的信号。
实时更新和离线重采样该用哪个？
实时逐根行情用合成器逐根更新；已经有一整段历史数据、只想转换周期时用官方的重采样函数，它内部复用合成器的单桶聚合逻辑。注意重采样有一个官方标注的已知限制：丢弃未完成桶的开关对日级以上的目标周期不起作用。
优化器导入报错是什么原因？
因为优化相关代码在 1.0 的清理中从交易器模块迁移到了工具模块。现在应该从 czsc.utils.optimize 导入开仓优化、平仓优化与配套的策略封装类。0.9.X 时代的旧导入路径已经失效。
一次灌入很长的历史数据会有什么问题？
官方标注了一个已知限制：合成器构造时会为基础周期的桶也按输入长度预分配容量，单次输入达到百万级时会产生约一倍的内存浪费。分批喂入可以规避，官方也说明会另开改动处理这个预分配问题。
多级别联立这块 EasyClaw 能做吗？
不能。EasyClaw 本机的技术分析技能针对单一标的输出指标与形态结论，研究回测类技能是做向量化研究，都不提供多周期 K 线合成与跨级别联立决策，也没有持仓与事件层。需要这条链路只能走自建路线；两者之间没有已证实的集成关系。