CZSC / 信号体系
czsc 信号函数：220+ 信号怎么组织、怎么调用
信号是这套框架里最容易误解的一层：它不是下单指令，而是「可组合的判断」。框架先产出信号，再把信号按与、或、非组合成事件，事件才驱动持仓。这一页把信号的层级、子模块划分、命名规范与调用路径讲清楚，也把官方内部两处数字口径的差异如实列出来。
信号、事件、持仓各是什么
官方在 README 的项目贡献里把这件事写得很直接：定义并实现「信号-事件-交易」量化交易逻辑体系，事件通过 signals_all、signals_any、signals_not 实现信号的逻辑组合。
| 层 | 对象 | 职责 | 实现位置 | 适用场景 | 注意点 |
|---|---|---|---|---|---|
| 信号 | Signal | 单个判断结果的数据表达 | crates/czsc-core/src/signal.rs | 把结构与特征转成可比较的取值 | 信号本身不产生任何交易动作 |
| 事件 | Event | 信号的逻辑组合（与、或、非） | crates/czsc-trader/src/event.rs | 表达「多个条件同时成立」这类策略逻辑 | 事件是策略逻辑与执行之间的隔离带，改逻辑不必改执行 |
| 持仓 | Position | 开仓事件、平仓事件与风控的组合 | crates/czsc-trader/src/position.rs | 把事件变成可回放的仓位变化 | 持仓描述目标状态，不等于实际成交 |
| 组合函数 | signals_all / signals_any / signals_not | 分别实现「全部成立」「任一成立」「取反」 | 官方 README 项目贡献 | 构造复合条件 | 这三者是官方点名的组合机制，不要自己另起一套 |
| 批量生成 | generate_czsc_signals | 在 K 线序列上批量生成信号并返回 DataFrame | crates/czsc-trader | 回放整段历史 | 底层依赖 K 线合成、交易器与信号注册表 |
| 联立分析 | CzscSignals / CzscTrader | 多周期联立：只出信号 / 出信号并管仓位 | crates/czsc-trader/src | 多级别决策 | 详见多级别联立页 |
Python 端暴露的 7 个信号子模块
信号函数在 Python 侧按主题分成 7 个子模块，这是官方开发文档明确写出的划分。
| 子模块 | 主题方向 | 适用场景 | 注意点 |
|---|---|---|---|
| bar | K 线本身的形态与结束特征 | 判断某根 K 线是否具备特定形态 | 命名里常见 bar_end 这类前缀 |
| cvolp | 量价关系相关信号 | 成交量与价格的配合关系 | 成交量口径受数据源影响，跨源比较要谨慎 |
| cxt | 缠论上下文（结构状态）相关信号 | 基于笔与中枢状态的判断 | 这是与缠论结构结合最紧的一组 |
| obv | 能量潮类量能指标信号 | 量能趋势判断 | 属指标派生，不依赖缠论结构 |
| pressure | 压力与支撑相关信号 | 位置判断 | 计算口径由实现定义 |
| tas | 技术分析算子派生信号 | 均线、平滑类判断 | 底层 TA 算子由 Rust 提供，仅供信号内部使用 |
| vol | 波动率相关信号 | 波动状态判断 | 窗口长度直接改变结论，需固定参数 |
Rust 侧的源文件清单与官方口径差异
官方开发文档写「底层 crates/czsc-signals/src/ 有 22 个 .rs 源文件，可用 ls crates/czsc-signals/src/ 自查」；本文在 2026-09-16 实测该目录为 23 个 .rs 文件。两个数字都列出来，并给出自查方式。
| 来源 | 数字口径 | 观测方式 | 建议 |
|---|---|---|---|
| 官方开发文档（CLAUDE.md） | 22 个 .rs 源文件 | 文档原文 | 以文档为准了解设计意图 |
| 本文实测 | 23 个 .rs 文件 | GitHub contents API 读取 crates/czsc-signals/src/ | 以你拉取的版本实际文件数为准 |
| README | 220+ 信号函数；同一份 README 另一处写 246 | README 两处文本 | 以 czsc._native.signals 实际导出为准 |
| 实测存在的 .rs 模块（2026-09-16） | 分组 |
|---|---|
| ang、bar、byi、cat、clv、coo、cvolp、cxt、cxt_trader | 信号实现模块（前九个） |
| jcc、kcatr、ntmdk、obv、pressure、pos、tas、vol | 信号实现模块（其余） |
| xl、zdy、zdy_trader | 信号实现模块 |
| params、registry、types | 辅助模块（参数、注册表、类型定义） |
| utils（目录） | 工具函数 |
命名规范与调用路径
信号函数名带版本后缀，这是官方约定。理解这套命名，才能看懂示例里那一串点号。
| 要素 | 写法 | 含义 | 注意点 |
|---|---|---|---|
| 完整调用路径 | czsc._native.signals.<子模块>.<函数名> | 从扩展模块到具体信号函数 | 0.9.X 时代的 czsc.signals 命名空间层已在 1.0 中删除 |
| 示例一 | czsc._native.signals.bar.bar_end_V230331 | K 线结束类信号 | 来自官方 README 信号生成示例 |
| 示例二 | czsc._native.signals.cxt.cxt_bi_status_V230101 | 缠论笔状态类信号 | 同属官方示例 |
| 版本后缀 | _V230331 / _V230101 | 标识该信号函数的版本 | 版本号是命名的一部分，不能省略 |
| 注册方式 | czsc-signal-macros 提供的注册宏 | 信号函数在编译期登记进注册表 | 这是 Rust 侧的事，Python 端不必关心 |
| 文档解析 | parse_signal_doc | 解析信号函数的文档字符串 | 可用于自动生成信号文档 |
信号解析：把序列变成可用配置
写信号序列之后，需要把它翻译成运行时可用的配置与周期集合。官方 API 手册把这一组函数列在「交易器与信号管理」分类下。
| API | 作用 | 适用场景 | 注意点 |
|---|---|---|---|
| get_signals_config | 把信号序列解析为运行时配置列表 | 生成信号前的第一步 | 配置格式由实现定义，不要手工拼 |
| get_signals_freqs | 从信号配置中提取涉及的周期 | 决定需要合成哪些周期 | 漏掉周期会导致信号函数拿不到数据 |
| derive_signals_config | 从信号 key 列表派生信号配置 | 已有信号 key 时 | 与 get_signals_config 的输入形式不同 |
| derive_signals_freqs | 从信号配置列表派生周期列表 | 二次推导 | 与 derive_signals_config 配套使用 |
| get_unique_signals | 从持仓列表中提取去重的唯一信号 key | 统计一笔持仓用到了哪些信号 | 用于复盘与文档化 |
| generate_czsc_signals | 直接在 K 线序列上批量生成信号 | 省掉手工串联的步骤 | 返回 DataFrame，字段以官方实现为准 |
从 0.9 迁移：调用路径变了两处
1.0 把核心迁到 Rust 之后，信号层的调用方式也变了。这两条是升级时最先撞到的。
| 项 | 0.9.X 写法 | 1.0.X 写法 | 后果 | 怎么改 |
|---|---|---|---|---|
| 信号命名空间 | 从 czsc.signals 导入信号函数 | 该 Python 命名空间层已在 Phase J 彻底删除 | 旧的 import 语句直接报错 | 改用 czsc._native.signals 或经 czsc.traders 调用 |
| 实现归属 | Python 实现 | Rust 实现，Python 仅透传 | 不能再去改 Python 源码定制行为 | 改行为要改 Rust 或选择不同参数 |
| TA 算子 | Python 侧可能直接调用 | czsc._native.ta 仅供信号内部使用；Python 顶层保留 ema、sma、rolling_rank、boll_positions、ultimate_smoother 五个别名 | 使用其它算子的代码会失败 | 改用顶层保留别名，或自行实现 |
| 信号更新 | 遇错静默继续 | rc.8 起更新方法返回可失败结果，硬错抛 ValueError | 批量回放时会中断 | 补异常处理，或在入数据前清洗 |
| 信号文档 | 靠注释 | parse_signal_doc 可解析文档字符串；仓库另有导出脚本 | 不适用 | 可用脚本导出信号目录做本地索引 |
常见问题
信号相关的口径以官方 README 与 API 手册为准；数量类表述本文并列两个官方数字。
信号函数到底有多少个？
官方内部就有两处口径：README 的「项目贡献」与「架构概览」写 220+，同一份 README 的「使用案例」一节写 246 个信号函数。本文不替你选一个数字，建议直接查你安装版本里 czsc._native.signals 的实际导出。
信号可以直接拿来下单吗？
按官方设计不行。信号只是「可组合的判断」，需要用 signals_all、signals_any、signals_not 组合成事件，再由事件驱动持仓。跳过事件层会让策略逻辑与执行耦合在一起，之后改条件就会牵动执行代码。
signals_all 和 signals_any 有什么区别？
官方定义里的三个组合函数分别对应「全部成立」「任一成立」与「取反」。它们是构造复合条件的标准手段：需要多条件同时满足用第一个，只需要命中之一用第二个，需要排除某个条件用第三个。
为什么从 czsc.signals 导入会报错？
因为原 czsc/signals/ 这层 Python 命名空间在 1.0 的清理中已被彻底删除。信号函数现在的暴露路径是 czsc._native.signals，或者经 czsc.traders 封装后的接口。0.9.X 的教程代码需要按这条路径改写。
Rust 侧到底有多少个信号源文件？
官方开发文档写 22 个 .rs 文件，并给出了 ls crates/czsc-signals/src/ 的自查方式；本文在 2026-09-16 实测为 23 个。差异不影响使用，但引用时建议直接跑一次那条命令看你自己的版本。
信号这块 EasyClaw 能替我做吗？
不能。EasyClaw 本机的技术分析类技能计算的是指标与形态（均线、MACD、K 线形态、量价关系），输出的是指标结论；czsc 的信号是缠论结构派生的可组合判断，再经事件与持仓层驱动交易。两者层级不同，也没有已证实的集成关系。