# CZSC 项目核心工具

## 文档概述

本文档旨在帮助新用户快速了解 CZSC（缠中说禅技术分析工具）库中可用的实用工具，按模块分类列出所有核心功能，并提供使用场景和API参考。

### 如何使用本文档

- **系统学习**：按模块顺序阅读，了解CZSC的完整工具体系
- **按需查阅**：通过"按功能查找索引"快速定位所需工具
- **快速上手**：参考"快速上手指南"开始第一个项目

### 工具重要性标注

- **⭐ 必用高频** - 几乎每个CZSC项目都会用到，建议优先掌握
- **🔥 常用中频** - 大多数策略研究需要，重要程度次之
- **💡 特定场景** - 特定需求时使用，按需学习

---

## 1. 核心分析工具 (czsc/core.py)

### 模块概述

核心分析工具是 CZSC 库的基础，实现了缠论的分型、笔、线段等核心概念的自动识别，以及基于此的多级别量化交易策略。

### 工具列表

| 工具名称 | 重要性 | 功能说明 | 使用场景 |
|---------|--------|----------|----------|
| `CZSC` | ⭐ | 缠论分析核心类，实现分型、笔、线段识别 | 所有缠论分析的基础 |
| `RawBar` | ⭐ | 原始K线数据结构 | K线数据处理 |
| `NewBar` | ⭐ | 合成K线数据结构 | 多级别K线合成 |
| `Freq` | ⭐ | K线频率枚举（日线、30分钟等） | 指定K线周期 |
| `format_standard_kline` | ⭐ | DataFrame转RawBar列表 | 数据格式转换 |
| `BarGenerator` | ⭐ | K线生成器，支持多级别合成 | 多级别分析 |
| `Signal` | 🔥 | 信号数据结构 | 信号生成与传递 |
| `Event` | 🔥 | 事件数据结构 | 事件定义与匹配 |
| `Position` | 🔥 | 持仓数据结构 | 持仓管理 |
| `Operate` | 🔥 | 操作枚举（开多、平多等） | 交易操作定义 |
| `Direction` | 🔥 | 方向枚举（向上、向下） | 趋势方向判断 |
| `ZS` | 💡 | 中枢数据结构 | 中枢分析 |

### API 参考

```python
# CZSC 分析器
czsc_obj = CZSC(bars, max_bi_num=envs.get_max_bi_num())

# 数据格式转换
bars = format_standard_kline(df, freq=Freq.F30)

# K线生成器
bg = BarGenerator(base_freq=Freq.F30, freqs=[Freq.F30, Freq.FD, FreqFW])
bg.update(bars)
```

### 快速示例

```python
from czsc.core import CZSC, format_standard_kline, Freq
from czsc.mock import generate_symbol_kines

# 生成测试数据
df = generate_symbol_kines('000001', '30分钟', '20240101', '20240105')

# 转换为CZSC对象
bars = format_standard_kline(df, freq=Freq.F30)
czsc_obj = CZSC(bars)

# 访问分析结果
print(f"笔的数量: {len(czsc_obj.bi_list)}")
```

---

## 2. 数据获取与处理 (czsc/utils/data_client.py)

### 模块概述

统一数据客户端接口，支持天勤、Tushare、聚宽、CCXT等多个数据源，提供一致的数据访问方式。

### 工具列表

| 工具名称 | 重要性 | 功能说明 | 使用场景 |
|---------|--------|----------|----------|
| `DataClient` | ⭐ | 统一数据客户端接口 | 获取多源市场数据 |
| `set_url_token` | ⭐ | 设置数据源Token | 数据源认证 |
| `get_url_token` | 🔥 | 获取存储的Token | Token管理 |
| `generate_fernet_key` | 💡 | 生成加密密钥 | 敏感数据加密 |
| `fernet_encrypt` | 💡 | 数据加密 | 安全存储 |
| `fernet_decrypt` | 💡 | 数据解密 | 读取加密数据 |

### API 参考

```python
# 创建数据客户端
dc = DataClient(symbol="000001", sdt="20240101", edt="20240131", freq="30分钟")

# 获取K线数据
df = dc.get_kline()

# Token管理
set_url_token("tushare", "your_token_here")
token = get_url_token("tushare")
```

### 快速示例

```python
from czsc.utils import DataClient

# 创建客户端并获取数据
dc = DataClient(symbol="000001", sdt="20240101", edt="20240105")
df = dc.get_kline()

print(df.head())
```

---

## 3. 技术分析指标 (czsc/utils/ta.py)

### 模块概述

提供各类常用技术分析指标的计算函数，包括趋势指标、振荡指标、成交量指标等。

### 工具列表

| 工具名称 | 重要性 | 功能说明 | 使用场景 |
|---------|--------|----------|----------|
| `MACD` | ⭐ | MACD指标计算 | 趋势判断 |
| `RSI` | ⭐ | RSI指标计算 | 超买超卖判断 |
| `BOLL` | ⭐ | 布林带计算 | 波动率分析 |
| `KDJ` | 🔥 | KDJ指标计算 | 短期交易信号 |
| `ATR` | 🔥 | ATR真实波幅 | 风险管理 |
| `SMA` | 🔥 | 简单移动平均线 | 趋势跟踪 |
| `EMA` | 🔥 | 指数移动平均线 | 趋势跟踪 |
| `WMA` | 💡 | 加权移动平均线 | 自定义权重 |
| `VOLUME_MA` | 💡 | 成交量均线 | 成交量分析 |

### API 参考

```python
# MACD指标
macd_result = MACD(df['close'], fast=12, slow=26, signal=9)

# RSI指标
rsi_value = RSI(df['close'], period=14)

# 布林带
upper, middle, lower = BOLL(df['close'], period=20, std_dev=2)
```

### 快速示例

```python
from czsc.utils import ta

# 计算MACD
macd_df = ta.MACD(df['close'])
print(macd_df[['dif', 'dea', 'bar']].tail())

# 计算RSI
rsi = ta.RSI(df['close'], period=14)
print(f"最新RSI值: {rsi.iloc[-1]:.2f}")
```

---

## 4. 缓存与性能 (czsc/utils/cache.py)

### 模块概述

提供高效的磁盘缓存机制，避免重复计算，显著提升性能。支持函数级装饰器和类级缓存管理。

### 工具列表

| 工具名称 | 重要性 | 功能说明 | 使用场景 |
|---------|--------|----------|----------|
| `disk_cache` | ⭐ | 磁盘缓存装饰器 | 函数结果缓存 |
| `DiskCache` | ⭐ | 缓存管理类 | 高级缓存控制 |
| `home_path` | 🔥 | 缓存目录路径 | 缓存位置管理 |
| `clear_cache` | 🔥 | 清空所有缓存 | 定期清理 |
| `clear_expired_cache` | 🔥 | 清理过期缓存 | 自动维护 |
| `get_dir_size` | 💡 | 获取目录大小 | 缓存监控 |
| `empty_cache_path` | 💡 | 清空缓存目录 | 一键清理 |

### API 参考

```python
# 使用装饰器缓存函数结果
@disk_cache(cache_key="my_func_{arg1}_{arg2}")
def my_expensive_function(arg1, arg2):
    # 耗时计算
    return result

# 缓存管理类
cache = DiskCache()
cache.set("key", value, expire=3600)
result = cache.get("key")

# 清理缓存
clear_cache()  # 清空所有
clear_expired_cache()  # 清理过期
```

### 快速示例

```python
from czsc.utils import disk_cache

@disk_cache(cache_key="calc_{symbol}_{days}", expire=86400)
def calculate_indicators(symbol, days):
    # 耗时计算
    return result

# 第一次调用会计算并缓存
result1 = calculate_indicators("000001", 30)
# 第二次调用直接从缓存读取
result2 = calculate_indicators("000001", 30)
```

---

## 5. 可视化工具 (czsc/utils/plotly_plot.py)

### 模块概述

提供丰富的交互式可视化工具，支持K线图、缠论分析图、回测结果图表、权重分析图等多种图表类型。

### 工具列表

| 工具名称 | 重要性 | 功能说明 | 使用场景 |
|---------|--------|----------|----------|
| `KlineChart` | ⭐ | K线图表绘制类 | 交互式K线图 |
| `plot_czsc_chart` | ⭐ | 绘制缠论分析图表 | 分型、笔、线段可视化 |
| `plot_weight` | 🔥 | 权重可视化 | 策略权重分析 |
| `plot_backtest` | 🔥 | 回测结果可视化 | 回测报告图表 |
| `echarts_plot` | 💡 | ECharts静态图表 | 网页展示 |

### API 参考

```python
# K线图表
kc = KlineChart(n_rows=2)
kc.add_kline(df, name="000001")
kc.show()

# 缠论图表
plot_czsc_chart(czsc_obj, show_bi=True, show_xd=True)

# 权重可视化
plot_weight(weights_df, title="策略权重分析")
```

### 快速示例

```python
from czsc.utils.plotly_plot import KlineChart, plot_czsc_chart

# 创建K线图
kc = KlineChart()
kc.add_kline(df, name="000001")
kc.add_series(df['ma5'], name="MA5", row=1)
kc.show()

# 绘制缠论分析图
plot_czsc_chart(czsc_obj, show_bi=True, show_xd=True)
```

---

## 6. 回测分析 (czsc/svc/backtest.py)

### 模块概述

提供完整的权重回测框架，支持多品种、多策略的回测分析，包括绩效计算、风险指标、报告生成等功能。

### 工具列表

| 工具名称 | 重要性 | 功能说明 | 使用场景 |
|---------|--------|----------|----------|
| `WeightBacktest` | ⭐ | 权重回测核心类 | 策略回测 |
| `daily_performance` | ⭐ | 日绩效计算 | 回测指标分析 |
| `top_drawdowns` | ⭐ | 最大回撤计算 | 风险评估 |
| `backtest_report` | 🔥 | 回测报告生成 | 报告输出 |
| `HtmlReportBuilder` | 🔥 | HTML报告构建器 | 美化报告 |

### API 参考

```python
# 创建回测对象
wb = WeightBacktest(weights_df, price_df)

# 计算绩效
stats = wb.daily_performance()
print(stats['年化收益率'])

# 最大回撤
drawdowns = top_drawdowns(stats['净值曲线'], top_n=5)

# 生成报告
report = backtest_report(wb)
```

### 快速示例

```python
from czsc.core import WeightBacktest

# 准备数据和权重
wb = WeightBacktest(weights_df, price_df)

# 获取回测结果
results = wb.results
print(f"年化收益率: {results['年化收益率']:.2%}")
print(f"最大回撤: {results['最大回撤']:.2%}")
print(f"夏普比率: {results['夏普比率']:.2f}")
```

---

## 7. 策略研究 (czsc/sensors/cta.py)

### 模块概述

提供CTA策略研究框架，支持单品种回放、多品种优化、参数网格搜索等功能，是策略开发的核心工具。

### 工具列表

| 工具名称 | 重要性 | 功能说明 | 使用场景 |
|---------|--------|----------|----------|
| `CTAResearch` | ⭐ | CTA研究框架 | 策略回放与优化 |
| `EventMatchSensor` | 🔥 | 事件匹配传感器 | 事件驱动策略 |
| `holds_concepts_effect` | 🔥 | 持仓概念效果分析 | 板块分析 |
| `FixedNumberSelector` | 💡 | 固定数量选择器 | 因子筛选 |

### API 参考

```python
# CTA研究
cta = CTAResearch(symbol="000001", sdt="20230101", edt="20231231")
results = cta.run(param_grid)

# 事件匹配
sensor = EventMatchSensor(events_config)
matches = sensor.match(czsc_obj)
```

### 快速示例

```python
from czsc.sensors import CTAResearch

# 创建CTA研究对象
cta = CTAResearch(symbol="000001", sdt="20230101", edt="20231231")

# 参数网格搜索
param_grid = {'param1': [1, 2, 3], 'param2': [0.5, 1.0]}
results = cta.run(param_grid)

# 查看最优参数
best_params = results.nlargest(1, '夏普比率')
```

---

## 8. 实用工具集 - 交易与绩效 (czsc/traders/)

### 模块概述

提供交易执行、信号管理、持仓管理等核心交易功能的工具集。

### 工具列表

| 工具名称 | 重要性 | 功能说明 | 使用场景 |
|---------|--------|----------|----------|
| `CzscTrader` | ⭐ | 交易执行核心类 | 多级别交易 |
| `CzscSignals` | ⭐ | 信号管理类 | 信号生成与匹配 |
| `generate_czsc_signals` | 🔥 | 生成CZSC信号 | 批量信号生成 |
| `check_signals_acc` | 🔥 | 检查信号准确性 | 信号验证 |
| `rolling_daily_performance` | 🔥 | 滚动日绩效 | 绩效跟踪 |
| `holds_performance` | 🔥 | 持仓绩效计算 | 组合分析 |
| `stoploss_by_direction` | 💡 | 方向止损 | 风险控制 |

### API 参考

```python
# 创建交易员
trader = CzscTrader(signal_config, pos_config)

# 生成信号
signals = generate_czsc_signals(bars, signals_config)

# 检查信号准确性
acc = check_signals_acc(signals_df, events_df)

# 滚动绩效
perf = rolling_daily_performance(weights_df, returns_df, window=20)
```

---

## 9. 实用工具集 - 数据处理 (czsc/utils/)

### 模块概述

提供数据转换、横截面分析、特征工程等数据处理实用工具。

### 工具列表

| 工具名称 | 重要性 | 功能说明 | 使用场景 |
|---------|--------|----------|----------|
| `resample_to_daily` | 🔥 | 重采样为日线 | 数据转换 |
| `cross_sectional_ranker` | 🔥 | 横截面排名 | 截面策略 |
| `cross_sectional_ic` | 🔥 | 横截面IC计算 | 因子有效性 |
| `update_bbars` | 🔥 | 更新基础K线数据 | 数据维护 |
| `update_tbars` | 🔥 | 更新合成K线数据 | 数据维护 |
| `normalize_feature` | 💡 | 特征标准化 | 因子预处理 |
| `feature_cross_layering` | 💡 | 特征交叉分层 | 特征工程 |

### API 参考

```python
# 横截面排名
rank_df = cross_sectional_ranker(factor_df)

# 横截面IC
ic = cross_sectional_ic(factor_df, return_df)

# 特征标准化
norm_feature = normalize_feature(raw_feature, method='zscore')
```

---

## 10. 实用工具集 - 统计与因子 (czsc/eda.py)

### 模块概述

提供探索性数据分析、因子检验、绩效分析等统计工具，是量化研究的重要辅助。

### 工具列表

| 工具名称 | 重要性 | 功能说明 | 使用场景 |
|---------|--------|----------|----------|
| `remove_beta_effects` | 🔥 | 去除beta影响 | 因子中性化 |
| `vwap` | 🔥 | 成交量加权均价 | 交易分析 |
| `twap` | 🔥 | 时间加权均价 | 交易分析 |
| `judge_factor_direction` | 🔥 | 因子方向判断 | 因子测试 |
| `monotonicity` | 💡 | 单调性分析 | 因子检验 |
| `turnover_rate` | 💡 | 换手率计算 | 流动性分析 |
| `make_price_features` | 💡 | 价格特征工程 | 特征生成 |
| `cross_sectional_strategy` | 💡 | 横截面策略 | 截面策略 |

### API 参考

```python
# 去除beta影响
neutral_factor = remove_beta_effects(factor_df, returns_df)

# 因子方向判断
direction = judge_factor_direction(factor_df, returns_df)

# 单调性分析
mono_score = monotonicity(factor_df, returns_df)
```

---

## 按功能查找索引

### 数据获取类
- 获取市场数据 → `DataClient`
- 数据格式转换 → `format_standard_kline`
- 多级别K线合成 → `BarGenerator`

### 分析计算类
- 缠论分析 → `CZSC`
- 技术指标计算 → `ta` 模块（MACD、RSI等）
- 因子分析 → `eda` 模块
- 横截面分析 → `cross_sectional_ranker`

### 可视化类
- K线图表 → `KlineChart`
- 缠论图表 → `plot_czsc_chart`
- 回测报告 → `plot_backtest`
- 权重分析 → `plot_weight`

### 回测策略类
- 权重回测 → `WeightBacktest`
- CTA研究 → `CTAResearch`
- 策略执行 → `CzscTrader`
- 参数优化 → `OpensOptimize` / `ExitsOptimize`

### 工具辅助类
- 缓存管理 → `disk_cache`
- 数据加密 → `fernet_encrypt`
- 交易日历 → `is_trading_date`
- 持仓管理 → `Position`

---

## 快速上手指南

### 典型工作流程

一个完整的 CZSC 工作流程通常包含以下步骤：

```python
# 1. 数据获取
from czsc.utils import DataClient
dc = DataClient(symbol="000001", sdt="20240101", edt="20240105")
df = dc.get_kline()

# 2. 数据处理
from czsc.core import format_standard_kline, CZSC, Freq
bars = format_standard_kline(df, freq=Freq.F30)

# 3. 缠论分析
czsc_obj = CZSC(bars)

# 4. 可视化
from czsc.utils.plotly_plot import plot_czsc_chart
plot_czsc_chart(czsc_obj, show_bi=True, show_xd=True)
```

### 工具使用顺序

**必需顺序**
```
数据获取 (DataClient) → 数据转换 (format_standard_kline) → 分析 (CZSC) → 可视化/回测
```

**独立使用**
- 缓存工具 (`disk_cache`) 可在任何耗时函数上使用
- 技术指标 (`ta` 模块) 可独立计算
- 统计工具 (`eda` 模块) 可单独使用

---

## 常见使用场景

### 场景1：单品种策略回测

**涉及工具**：`DataClient` → `CZSC` → `CzscTrader` → `WeightBacktest`

**适用场景**：验证单个品种的交易策略

```python
from czsc.utils import DataClient
from czsc.core import CZSC, format_standard_kline, Freq
from czsc.traders import CzscTrader

# 获取数据并分析
dc = DataClient(symbol="000001", sdt="20230101", edt="20231231")
df = dc.get_kline()
bars = format_standard_kline(df, freq=Freq.F30)
czsc_obj = CZSC(bars)

# 创建交易员并回测
trader = CzscTrader(signal_config, pos_config)
results = trader.backtest(czsc_obj)
```

### 场景2：多品种组合优化

**涉及工具**：`CTAResearch` → `OpensOptimize` / `ExitsOptimize`

**适用场景**：多品种参数优化

```python
from czsc.sensors import CTAResearch

# 创建研究框架
cta = CTAResearch(symbols=["000001", "000002"], sdt="20230101", edt="20231231")

# 参数优化
param_grid = {'open_para': [1, 2, 3], 'exit_para': [0.5, 1.0]}
results = cta.optimize(param_grid)
```

### 场景3：因子研究与分析

**涉及工具**：`cross_sectional_ic` → `judge_factor_direction` → `remove_beta_effects`

**适用场景**：评估因子的有效性

```python
from czsc.utils import cross_sectional_ic
from czsc.eda import judge_factor_direction, remove_beta_effects

# 计算IC
ic = cross_sectional_ic(factor_df, return_df)

# 判断方向
direction = judge_factor_direction(factor_df, return_df)

# 因子中性化
neutral_factor = remove_beta_effects(factor_df, return_df)
```

### 场景4：实时监控与可视化

**涉及工具**：`DataClient` → `BarGenerator` → `plot_czsc_chart`

**适用场景**：实时数据可视化

```python
from czsc.utils import DataClient
from czsc.utils.plotly_plot import plot_czsc_chart

# 获取实时数据
dc = DataClient(symbol="000001")
df = dc.get_kline()

# 可视化
bars = format_standard_kline(df, freq=Freq.F30)
czsc_obj = CZSC(bars)
plot_czsc_chart(czsc_obj, show_bi=True, show_xd=True)
```

---

## 工具使用频率统计

| 优先级 | 工具数量 | 建议学习顺序 | 典型工具 |
|--------|----------|--------------|----------|
| ⭐ 必用高频 | ~15个 | 第一周掌握 | CZSC, DataClient, format_standard_kline, Freq, BarGenerator, KlineChart, WeightBacktest, daily_performance, top_drawdowns |
| 🔥 常用中频 | ~25个 | 第二周掌握 | Signal, Event, Position, MACD, RSI, BOLL, disk_cache, plot_czsc_chart, CTAResearch, CzscTrader |
| 💡 特定场景 | ~30个 | 按需学习 | ZS, fernet_encrypt, echarts_plot, EventMatchSensor, monotonicity |

---

## 扩展资源

### 官方文档
- 完整API文档：https://czsc.readthedocs.io/en/latest/modules.html
- 项目飞书文档：https://s0cqcxuy3p.feishu.cn/wiki/wikcn3gB1MKl3ClpLnboHM1QgKf

### 示例代码
- 基础示例：`examples/30分钟笔非多即空.py`
- CTA研究：`examples/use_cta_research.py`
- 参数优化：`examples/use_optimize.py`
- Streamlit应用：`examples/animotion/`

### 视频教程
- B站教程：https://space.bilibili.com/243682308/channel/series

### 信号函数开发
- 编写规范：https://s0cqcxuy3p.feishu.cn/wiki/wikcnCFLLTNGbr2THqo7KtWfBkd

---

## 版本说明与兼容性

### Rust/Python 混合架构
- **版本控制**：通过环境变量 `CZSC_USE_PYTHON` 控制
- **默认行为**：优先使用 Rust 版本（rs-czsc），性能更优
- **回退机制**：Rust 版本不可用时自动回退到 Python 版本

### 环境变量
```bash
# 强制使用 Python 版本
export CZSC_USE_PYTHON=1

# 缠论参数
export czsc_min_bi_len=6  # 最小笔长度
export czsc_max_bi_num=50  # 最大笔数量
```

### 依赖关系
- Python 3.8+
- 推荐使用 UV 进行依赖管理
- 参考 `docs/UV管理开源项目指南.md`

---

*文档最后更新：2025-01-15*
*CZSC 版本：0.10.8*
