waditu/czsc

# czsc - 缠中说禅技术分析工具 [](https://pepy.tech/project/czsc) [](https://pepy.tech/project/czsc) [](https://pepy.tech/project/czsc) [](https://www.python.org/downloads/) [](https://pypi.org/project/czsc/) **[项目文档](https://s0cqcxuy3p.feishu.cn/wiki/wikcn3gB1MKl3ClpLnboHM1QgKf)** | **[投研数据共享](https://s0cqcxuy3p.feishu.cn/wiki/wikcnzuPawXtBB7Cj7mqlYZxpDh)** | **[信号函数编写规范](https://s0cqcxuy3p.feishu.cn/wiki/wikcnCFLLTNGbr2THqo7KtWfBkd)** | **[DEVIN生成的文档](https://deepwiki.com/waditu/czsc/1-overview)** * 备份网址1：http://www.fxgan.com * 备份网址2：https://chzhshch.blog * 已经开始用czsc库进行量化研究的朋友，欢迎[加入飞书群](https://applink.feishu.cn/client/chat/chatter/add_by_link?link_token=0bak668e-7617-452c-b935-94d2c209e6cf)，快点击加入吧！ * [B站视频教程合集（持续更新...）](https://space.bilibili.com/243682308/channel/series) ## 架构概览 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 绑定入口）。 ## 安装使用 **注意：** 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 ``` ## 快速开始 ### 核心缠论分析 ``` 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 版本使用说明和案例](https://s0cqcxuy3p.feishu.cn/wiki/X0mAwSZyqiuebek2EUacbyPMnDd)。 | 序号 | 案例 | 一句话介绍 | |------|------|------------| | 1 | [基于 Event 的策略回测 + wbt HTML 报告](https://s0cqcxuy3p.feishu.cn/wiki/Li7ewsbReiQlWokEEVpcvLjznJU) | 5 行命令跑通 Event → Position → 回测 → 可交互 HTML 报告的完整闭环。 | | 2 | [lightweight_charts 缠论可视化](https://s0cqcxuy3p.feishu.cn/wiki/VF7Gwq3N8iuplckG1Tmcmp1Qn3d) | 几行代码把缠论结构（分型/笔/线段/中枢）导出为自包含离线 HTML，便于分享与嵌入。 | | 3 | [把信号函数画到 K 线主图（plot_czsc_signals）](https://s0cqcxuy3p.feishu.cn/wiki/ULxhwFyVkiavqhkZ2Xkc0N3fnYc) | 把信号触发点叠在 K 线主图上，直观调试 signals_config 与多周期联立。 | | 4 | [性能基准测试：在本地复现 CZSC / CzscTrader 吞吐量](https://s0cqcxuy3p.feishu.cn/wiki/ReRfw9WUjiVgEckZbMxcT87WnRc) | 一行命令本地评估吞吐量，配套关键指标速查表，用于容量规划与加速效果核对。 | | 5 | [信号函数模块深入介绍](https://s0cqcxuy3p.feishu.cn/wiki/WxU8wKTBViekKbkCyKzcwa7SnJd) | 系统讲解 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 输出） 本次清理 起项目不再依赖 streamlit，可视化统一以 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`](docs/migration/cleanup-non-czsc-core.md) | 如需 streamlit 集成，调用方自行 `pip install streamlit` 后用 `st.components.v1.html(plot_czsc(c, output='html'))` 嵌入即可。从 1.x 升级请参考 [`docs/migration/cleanup-non-czsc-core.md`](docs/migration/cleanup-non-czsc-core.md)。 ## 相关项目（生态依赖） czsc 在权重回测、权重落地与 TA 算子一致性校验上依赖以下三个独立开源项目，它们与 czsc 形成"分析 + 回测 + 落地 + 校验"的完整闭环： | 项目 | GitHub | 角色 | 与 czsc 的关系 | |------|--------|------|----------------| | **wbt** | | 策略持仓权重回测引擎（Weight Back Test） | **硬依赖**。提供 `WeightBacktest / daily_performance / top_drawdowns / generate_backtest_report` 等；`czsc.mock` 也转发自 `wbt.mock`。czsc 顶层 `from czsc import WeightBacktest` 即来自此包。 | | **wmr** | | 策略持仓权重管理系统（Weight Manager，DuckDB / ClickHouse 双后端） | **下游配套**（非硬依赖）。wbt 负责"离线回测权重"，wmr 负责"实盘 / 投研环境下权重的持久化、版本管理与查询"。czsc 产出信号 / 持仓 → wbt 跑回测 → wmr 落库供下游消费。 | | **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](https://www.chiark.greenend.org.uk/~sgtatham/bugs-cn.html)》，然后在 [issues](https://github.com/waditu/czsc/issues) 中报告 Bug ## 缠论精华 ## 原文整理 * [缠中说禅重新编排版《论语》（整理版）](https://blog.csdn.net/baidu_25764509/article/details/109517775) * [缠中说禅交易指南](https://blog.csdn.net/baidu_25764509/article/details/109598229) * [缠中说禅技术原理](https://blog.csdn.net/baidu_25764509/article/details/109597255) * [缠中说禅图解分析示范](https://blog.csdn.net/baidu_25764509/article/details/110195063) * [缠中说禅：缠非缠、禅非禅，枯木龙吟照大千（整理版）](https://blog.csdn.net/baidu_25764509/article/details/110775662) * [缠中说禅教你打坐（整理版）](https://blog.csdn.net/baidu_25764509/article/details/113735170) ## 资料分享 * 链接：https://pan.baidu.com/s/1RXkP3188F0qu8Yk6CjbxRQ * 提取码：vhue

标签：Python, Rust, 可视化界面, 技术分析, 无后门, 缠论, 网络流量审计, 股票期货, 逆向工具, 通知系统, 量化交易