Skip to main content

czsc - 缠中说禅技术分析工具

Downloads Downloads Downloads Python 3.10+ PyPI

项目文档 | 投研数据共享 | 信号函数编写规范 | DEVIN生成的文档

1.0.X 版本开始,缠论核心算法(分型、笔、中枢等)已全部迁移到 Rust 实现,通过 PyO3 扩展(czsc._native)暴露给 Python。 需要了解旧 Python 实现逻辑的,可查看 0.9.X 版本。

czsc_skills

源于缠中说缠博客,原始博客中的内容不太完整,且没有评论,以下是网友整理的原文备份

架构概览

CZSC 1.0 采用 Rust + Python 混合架构

czsc (Python 包)
├── czsc._native          ← Rust 扩展(PyO3),缠论核心
│   ├── CZSC / FX / BI / ZS / RawBar / NewBar / BarGenerator
│   ├── Freq / Mark / Direction / Signal / Event / Position / Operate
│   ├── CzscTrader / CzscSignals / generate_czsc_signals
│   ├── signals.*         ← 220+ 信号函数(Python 端 7 个子模块;详见 crates/czsc-signals/src/)
│   └── ta.*              ← Rust TA 算子 (ema/sma/boll 等,本次清理 起仅内部使用)
├── czsc.traders          ← Python 门面,汇聚 Rust 交易 API
├── czsc.utils            ← 工具函数(绘图/缓存/统计/交易工具)
├── czsc.connectors       ← 数据源连接器(天勤/Tushare/CCXT/本地缓存)
├── czsc.strategies       ← 策略门面(CzscStrategyBase/CzscJsonStrategy)
├── czsc.fsa              ← 飞书自动化工具
├── czsc.mock             ← 测试用模拟数据(转发自 wbt)
└── czsc.envs             ← 环境变量管理

底层 Rust workspace 包含 9 个 crate:czsc / czsc-core / czsc-derive / czsc-signals / czsc-trader / czsc-utils / czsc-ta / czsc-signal-macros / czsc-python(PyO3 绑定入口)。

项目贡献

  • 缠论的 分型、笔 的自动识别,由 Rust 实现并通过 czsc._native 暴露
  • 定义并实现 信号-事件-交易 量化交易逻辑体系,事件通过 signals_all/signals_any/signals_not 实现信号的逻辑组合
  • 定义并实现了 220+ 信号函数(Rust 实现),见 czsc._native.signals
  • 缠论多级别联立决策分析交易,详见 CzscTrader
  • HTML 可视化(plotly + lightweight-charts):czsc.utils.plotting.{kline,weight,lightweight}.*

安装使用

注意: Python 版本必须 ≥ 3.10

从 PyPI 安装预编译版本(推荐):

pip install czsc -U

使用 uv 安装(推荐开发环境):

uv pip install czsc

从源码构建(需要 Rust 工具链和 maturin):

# 安装 Rust:https://rustup.rs/
# 安装 maturin
pip install maturin

# 克隆并构建
git clone https://github.com/waditu/czsc.git
cd czsc
maturin develop --release

Rust 构建环境约束:底层依赖 pyo3 / pyo3-stub-gen 0.22 要求 Python ≥ 3.10。 当系统默认 Python 低于 3.10 时,请通过环境变量显式指定:

export PYO3_PYTHON=$(which python3.12)   # 或任意 3.10+ 的解释器

否则 cargo build / cargo test 会在 crates/czsc-python/build.rs 提前 panic 并给出修复建议。 用 uv sync --extra dev 走 UV 流程时,UV 会自动选择项目声明的 Python,不需要额外设置。

快速开始

核心缠论分析

import czsc
from czsc import CZSC, Freq, format_standard_kline
from czsc.mock import generate_symbol_kines

# 生成模拟 K 线数据
df = generate_symbol_kines('000001', '30分钟', '20240101', '20240601')

# 转换为 RawBar 对象列表
bars = format_standard_kline(df, freq=Freq.F30)

# 创建 CZSC 分析对象(自动识别分型、笔、中枢)
czsc_obj = CZSC(bars)
print(f"笔数量:{len(czsc_obj.bi_list)}")
print(f"中枢数量:{len(czsc_obj.zs_list)}")

K 线合成与多级别分析

from czsc import BarGenerator, Freq

# 使用 BarGenerator 进行 K 线合成
bg = BarGenerator(base_freq='1分钟', freqs=['5分钟', '30分钟', '日线'])
for bar in raw_bars:
    bg.update(bar)

# 获取各周期 K 线
bars_5m = bg.bars['5分钟']
bars_30m = bg.bars['30分钟']

信号生成

from czsc import generate_czsc_signals, get_signals_config, get_signals_freqs

# 配置信号序列(使用 Rust 实现的信号函数)
signals_seq = [
    "czsc._native.signals.bar.bar_end_V230331",
    "czsc._native.signals.cxt.cxt_bi_status_V230101",
]

# 解析信号所需的周期配置
freqs = get_signals_freqs(signals_seq)
config = get_signals_config(signals_seq)

# 生成信号序列
results = generate_czsc_signals(bars, signals_seq)

权重回测

from czsc import WeightBacktest
from czsc.mock import generate_klines_with_weights

# 生成带权重的模拟数据
dfw = generate_klines_with_weights(seed=42)

# 运行权重回测
wb = WeightBacktest(dfw, fee_rate=0.0002)
print(wb.stats)  # 回测统计汇总

策略研究

from czsc import run_research, run_replay

# 单品种回放
run_replay(bars, signals_seq, pos_seq, res_path='./results/')

# 批量品种研究
run_research(symbols, signals_seq, pos_seq, res_path='./results/')

缠论可视化与回测报告

# 缠论 K 线(多周期联立,自包含 HTML,离线即可打开)
from czsc.utils.plotting.lightweight import plot_czsc, plot_czsc_trader

html = plot_czsc(c, output="html")  # 单周期
plot_czsc_trader(ct, output="html", path="trader.html")  # 多周期

# 回测 HTML 报告:用 wbt.generate_backtest_report 一键产出
from wbt import generate_backtest_report
generate_backtest_report(df=dfw, output_path="report.html", weight_type="ts")

使用案例

更多端到端案例汇总见飞书 wiki:CZSC 1.0.X 版本使用说明和案例

序号 案例 一句话介绍
1 基于 Event 的策略回测 + wbt HTML 报告 5 行命令跑通 Event → Position → 回测 → 可交互 HTML 报告的完整闭环。
2 lightweight_charts 缠论可视化 几行代码把缠论结构(分型/笔/线段/中枢)导出为自包含离线 HTML,便于分享与嵌入。
3 把信号函数画到 K 线主图(plot_czsc_signals) 把信号触发点叠在 K 线主图上,直观调试 signals_config 与多周期联立。
4 性能基准测试:在本地复现 CZSC / CzscTrader 吞吐量 一行命令本地评估吞吐量,配套关键指标速查表,用于容量规划与加速效果核对。
5 信号函数模块深入介绍 系统讲解 czsc-signals 架构与 246 个信号函数的模块划分、参数模板、信号表达示例。

核心 API 一览

类型 符号 说明
缠论对象 CZSC, FX, BI, ZS 缠论核心数据结构(Rust)
K线对象 RawBar, NewBar, BarGenerator K线与合成器(Rust)
枚举 Freq, Mark, Direction, Operate 方向/频率等枚举(Rust)
信号/事件 Signal, Event, Position 信号与持仓逻辑(Rust)
分析工具 check_fx, check_bi, remove_include 分型/笔校验工具(Rust)
TA算子顶层别名 czsc.ema, czsc.sma, czsc.rolling_rank, czsc.boll_positions, czsc.ultimate_smoother 技术指标算子顶层别名(Rust)
交易器 CzscTrader, CzscSignals 多级别交易决策(Rust)
信号生成 generate_czsc_signals 批量信号生成(Rust)
权重回测 WeightBacktest 权重序列回测(来自 wbt)
策略 CzscStrategyBase, CzscJsonStrategy 策略封装(Python)
模拟数据 generate_symbol_kines 测试用 K线数据(来自 wbt)
格式转换 format_standard_kline DataFrame → RawBar 列表

数据源连接器

czsc.connectors 提供多个数据源适配器:

模块 数据源 说明
tq_connector.py 天勤(TQSdk) 期货实时/历史行情
ts_connector.py Tushare A股历史数据
ccxt_connector.py CCXT 数字货币交易所
local_data.py 投研数据本地缓存 CZSC 共享数据本地读取入口

可视化(HTML 输出)

可视化统一以 plotly + lightweight-charts 输出 HTML:

模块 功能
czsc.utils.plotting.kline 单周期 K 线 + 缠论结构(plotly Figure)
czsc.utils.plotting.weight 权重时序图(plotly Figure)
czsc.utils.plotting.lightweight lightweight-charts 自包含 HTML,多周期联立 + 信号叠加
累计收益 / 回撤 / 月度热力图 / 综合回测概览 改用 wbt.generate_backtest_report 或直接 plotly,见 docs/migration/cleanup-non-czsc-core.md

使用 plot_czscplot_czsc_traderplot_czsc_signals 生成自包含 HTML 后,可直接在浏览器中打开。

相关项目(生态依赖)

czsc 在权重回测、权重落地与 TA 算子一致性校验上依赖以下三个独立开源项目,它们与 czsc 形成"分析 + 回测 + 落地 + 校验"的完整闭环:

项目 GitHub 角色 与 czsc 的关系
wbt https://github.com/zengbin93/wbt 策略持仓权重回测引擎(Weight Back Test) 硬依赖。提供 WeightBacktest / daily_performance / top_drawdowns / generate_backtest_report 等;czsc.mock 也转发自 wbt.mock。czsc 顶层 from czsc import WeightBacktest 即来自此包。
wmr https://github.com/zengbin93/wmr 策略持仓权重管理系统(Weight Manager,DuckDB / ClickHouse 双后端) 下游配套(非硬依赖)。wbt 负责"离线回测权重",wmr 负责"实盘 / 投研环境下权重的持久化、版本管理与查询"。czsc 产出信号 / 持仓 → wbt 跑回测 → wmr 落库供下游消费。
talib-rs https://github.com/0xcjun/talib-rs 纯 Rust 实现的 TA-Lib 替代库 测试可选依赖。仅 tests/unit/test_ta_parity.py 用它对 czsc._native.ta(EMA / SMA 等)做数值 parity 校验,确保 czsc 自研 TA 算子与 TA-Lib 行为一致。运行时代码不依赖。

简言之:wbt = 回测wmr = 权重落地talib-rs = TA 基准;czsc 自身专注缠论核心算法(Rust)与信号-事件-交易体系,其余环节通过这三个项目解耦协同。

开发环境搭建

# 使用 UV 管理依赖(推荐)
uv sync --extra dev

# 构建 Rust 扩展(开发模式)
maturin develop

# 运行测试
uv run pytest tests/ -v

# 代码格式化
uv run ruff format czsc/ tests/
uv run ruff check czsc/ tests/

关键环境变量

变量 说明 默认值
CZSC_MIN_BI_LEN 最小笔长度 6
CZSC_MAX_BI_NUM 最大笔数量 50
CZSC_VERBOSE 是否输出详细日志 False

使用前必看

  • 1.0.X 版本核心算法已迁移到 Rust,与 0.9.X 版本 不兼容;旧代码需按新 API 迁移;
  • 免责声明:项目开源仅用于技术交流!
  • 如果你发现了项目中的 Bug,可以先读一下《如何有效地报告 Bug》,然后在 issues 中报告 Bug

缠论精华

学了本ID的理论,去再看其他的理论,就可以更清楚地看到其缺陷与毛病,因此,广泛地去看不同的理论,不仅不影响本ID理论的学习,更能明白本ID理论之所以与其他理论不同的根本之处。

为什么要去了解其他理论,就是这些理论操作者的行为模式,将构成以后我们猎杀的对象,他们操作模式的缺陷,就是以后猎杀他们的最好武器,这就如同学独孤九剑,必须学会发现所有派别招数的缺陷,这也是本ID理论学习中一个极为关键的步骤。

真正的预测,就是不测而测。所有预测的基础,就是分类,把所有可能的情况进行完全分类。有人可能说,分类以后,把不可能的排除,最后一个结果就是精确的。 这是脑子锈了的想法,任何的排除,等价于一次预测,每排除一个分类,按概率的乘法原则,就使得最后的所谓精确变得越不精确,最后还是逃不掉概率的套子。 对于预测分类的唯一正确原则就是不进行任何排除,而是要严格分清每种情况的边界条件。任何的分类,其实都等价于一个分段函数,就是要把这分段函数的边界条件确定清楚。 边界条件分段后,就要确定一旦发生哪种情况就如何操作,也就是把操作也同样给分段化了。然后,把所有情况交给市场本身,让市场自己去当下选择。 所有的操作,其实都是根据不同分段边界的一个结果,只是每个人的分段边界不同而已。因此,问题不是去预测什么,而是确定分段边界。

原文整理

资料分享

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

czsc-1.0.1.tar.gz (577.8 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

czsc-1.0.1-cp310-abi3-win_amd64.whl (23.2 MB view details)

Uploaded CPython 3.10+Windows x86-64

czsc-1.0.1-cp310-abi3-musllinux_1_2_x86_64.whl (21.4 MB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ x86-64

czsc-1.0.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (21.3 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

czsc-1.0.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (19.5 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ ARM64

czsc-1.0.1-cp310-abi3-macosx_11_0_arm64.whl (18.9 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

czsc-1.0.1-cp310-abi3-macosx_10_12_x86_64.whl (20.8 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file czsc-1.0.1.tar.gz.

File metadata

  • Download URL: czsc-1.0.1.tar.gz
  • Upload date:
  • Size: 577.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for czsc-1.0.1.tar.gz
Algorithm Hash digest
SHA256 30b4257f3bfa936c420b144c3115ad1ca95f013ce11d8389974114f57b9de50e
MD5 e3f889f08b71fd7199187fa37d01e1ac
BLAKE2b-256 fbcbf3812a11c47c65e9c9cad9cc3a8beac0255d16fb20df5b2b88d9b43e9e25

See more details on using hashes here.

Provenance

The following attestation bundles were made for czsc-1.0.1.tar.gz:

Publisher: python-publish.yml on waditu/czsc

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file czsc-1.0.1-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: czsc-1.0.1-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 23.2 MB
  • Tags: CPython 3.10+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for czsc-1.0.1-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 18f3fb6c38f8834b8b94e35b990a9632d24e46e269bdf4d94b3aa401ce8f4581
MD5 62fa1b6b046069a5abdfbe2de64e17d4
BLAKE2b-256 6b84bd612aa74c59b3085693c5da07210a69f2d4488e4edef83390d44c0ad34d

See more details on using hashes here.

Provenance

The following attestation bundles were made for czsc-1.0.1-cp310-abi3-win_amd64.whl:

Publisher: python-publish.yml on waditu/czsc

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file czsc-1.0.1-cp310-abi3-musllinux_1_2_x86_64.whl.

File metadata

  • Download URL: czsc-1.0.1-cp310-abi3-musllinux_1_2_x86_64.whl
  • Upload date:
  • Size: 21.4 MB
  • Tags: CPython 3.10+, musllinux: musl 1.2+ x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for czsc-1.0.1-cp310-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 2cca2c9f7d96fea9c9f61f9f0caad13063fcb3edabce6f630909f758c94fe83c
MD5 b667d1f2fd45d2ef752ee0bf3963e04f
BLAKE2b-256 3918d29c31f6f27e120709e4bf57c2afd89d8c5a0efe8bcb642d80b675940c7c

See more details on using hashes here.

Provenance

The following attestation bundles were made for czsc-1.0.1-cp310-abi3-musllinux_1_2_x86_64.whl:

Publisher: python-publish.yml on waditu/czsc

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file czsc-1.0.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for czsc-1.0.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 2c65d266bd58b51960be505678f2daae69892ca4031808eeeef2ccbc2848c036
MD5 e01fecc3307b7a6b39d5b8b700432b93
BLAKE2b-256 77bdecd2ea965cc43996ab33ec59982569ded5e6a29cb45d0700fab888cd0f70

See more details on using hashes here.

Provenance

The following attestation bundles were made for czsc-1.0.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: python-publish.yml on waditu/czsc

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file czsc-1.0.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for czsc-1.0.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 e88907a1bcf212787bef70fcac76d04353555d035b5d6d2f8029c44518c6b5ab
MD5 5de4e9c3c84d635c2d58e6d031fe108a
BLAKE2b-256 c1d18efa1662d5b2fd214d124f9d5582950d242b77c9c4d84590e6ef5323fc5e

See more details on using hashes here.

Provenance

The following attestation bundles were made for czsc-1.0.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: python-publish.yml on waditu/czsc

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file czsc-1.0.1-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

  • Download URL: czsc-1.0.1-cp310-abi3-macosx_11_0_arm64.whl
  • Upload date:
  • Size: 18.9 MB
  • Tags: CPython 3.10+, macOS 11.0+ ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for czsc-1.0.1-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c12e73ef520150994af7b7a73e8f875c8d704ab5f01a17ca119f0706dbac8b83
MD5 06b1e3fcd008596e2380b5bef53a1ee9
BLAKE2b-256 5bff70bf02d21501266d4d246b86780e899659db5a5b7cf439a5af8cccdca23c

See more details on using hashes here.

Provenance

The following attestation bundles were made for czsc-1.0.1-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: python-publish.yml on waditu/czsc

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file czsc-1.0.1-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for czsc-1.0.1-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 2a48c24afc0c083afc7824db6b8049adc9781e6c52b895413002657abaaf6a15
MD5 da04ff212084417b43d238ebd6268fae
BLAKE2b-256 7e4530be33b5fc9af762ae14679ce70b744bb9706d61c4dfe1aa506866ff6169

See more details on using hashes here.

Provenance

The following attestation bundles were made for czsc-1.0.1-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: python-publish.yml on waditu/czsc

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.0.1

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page