# CZSC 源码阅读指南

> 本文档旨在帮助开发者快速理解 CZSC（缠中说禅技术分析工具）项目的代码结构、核心概念和使用方法

## 📋 目录

- [项目简介](#项目简介)
- [阅读前的准备](#阅读前的准备)
- [核心概念理解](#核心概念理解)
- [源码阅读顺序](#源码阅读顺序)
- [详细模块解析](#详细模块解析)
- [实战上手指南](#实战上手指南)
- [进阶学习路径](#进阶学习路径)

---

## 项目简介

**CZSC** 是基于缠中说禅理论的综合性量化交易 Python 库，提供：

- ✅ 缠论核心概念（分型、笔、线段、中枢）的自动识别
- ✅ 多级别联立分析框架
- ✅ 信号-事件-交易的完整量化体系
- ✅ 策略回测和参数优化工具
- ✅ 多数据源接入（Tushare、聚宽、天勤等）
- ✅ Rust/Python 混合架构（性能优化）

**技术栈**: Python 3.8+, Rust (可选), Pandas, Plotly, Streamlit

---

## 阅读前的准备

### 1. 环境搭建

```bash
# 克隆项目
git clone https://github.com/waditu/czsc.git
cd czsc

# 安装依赖（推荐使用 UV）
uv sync --extra dev

# 或使用 pip
pip install -e .
```

### 2. 必备知识

- **Python 基础**: 面向对象、装饰器、数据类（dataclass）
- **金融知识**: K线图、技术指标、量化交易基本概念
- **缠论基础**: 建议先阅读缠中说禅原文（见项目文档）

### 3. 关键文档

| 文档 | 链接/位置 | 说明 |
|------|----------|------|
| README.md | 项目根目录 | 项目概览和快速开始 |
| CLAUDE.md | 项目根目录 | 详细开发指南（强烈推荐） |
| API 文档 | https://czsc.readthedocs.io | 完整 API 参考 |
| 飞书文档 | https://s0cqcxuy3p.feishu.cn | 项目文档和教程 |
| B站视频 | https://space.bilibili.com/243682308 | 视频教程合集 |

---

## 核心概念理解

### 信号-事件-交易体系

这是 CZSC 最核心的量化交易方法论：

```
原始K线 → 信号(Signal) → 事件(Event) → 交易决策(Position)
```

#### 1. **信号 (Signal)**
- 最基础的技术指标或市场状态判断
- 例如：均线位置、分型状态、成交量特征
- 位置：`czsc/signals/`
- 信号是最小的判断单元，每个信号函数返回一个明确的市场状态

#### 2. **事件 (Event)**
- 通过逻辑关系（AND/OR/NOT）组合多个信号
- 代表一个完整的市场事件或交易条件
- 例如："多头启动事件" = "MA5上穿MA20"(signals_all) AND NOT "涨停"(signals_not)
- 对应开仓或平仓的触发条件
- 包含三种信号组合方式：
  - `signals_all`: 必须全部满足的信号列表
  - `signals_any`: 满足任一即可的信号列表  
  - `signals_not`: 不能出现的信号列表

#### 3. **交易 (Position)**
- 基于事件的完整交易策略
- 定义开仓事件列表（opens）和平仓事件列表（exits）
- 包含止损、超时、开仓间隔等风险控制参数

### 缠论核心对象

```python
RawBar   # 原始K线（带 OHLCV）
  ↓ 去除包含关系
NewBar   # 处理后的K线（无包含关系）
  ↓ 识别分型
FX       # 分型（顶分型/底分型）
  ↓ 识别笔
BI       # 笔（连接相邻分型的线段）
  ↓ 识别线段和中枢
ZS       # 中枢（价格震荡区间）
```

**说明**: 这些是缠论的核心技术分析对象，与交易决策体系（Signal→Event→Position）是两个不同的层面。

### 多级别联立分析

CZSC 支持同时分析多个时间周期，例如：

```python
freqs = ['1分钟', '5分钟', '30分钟', '日线']
# 可以组合不同级别的信号进行决策
# 例如：日线看趋势 + 30分钟看入场点 + 1分钟看精确位置
```

---

## 源码阅读顺序

### 🥇 第一阶段：核心数据结构（必读）

**目标**: 理解缠论的核心对象和数据流转

| 序号 | 文件路径 | 关键内容 | 阅读重点 |
|------|---------|---------|---------|
| 1 | `czsc/py/enum.py` | 枚举类型定义 | `Freq`, `Mark`, `Direction`, `Operate` |
| 2 | `czsc/py/objects.py` | 核心数据结构 | `RawBar`, `NewBar`, `FX`, `BI`, `ZS`, `Signal`, `Event`, `Position` |
| 3 | `czsc/core.py` | Rust/Python 混合架构入口 | 智能导入逻辑、版本检测 |

**阅读建议**:
- 重点理解每个数据类的字段含义和用途
- 注意对象之间的继承和组合关系
- 对照缠论原文理解分型、笔、中枢的定义

### 🥈 第二阶段：核心算法实现（必读）

**目标**: 掌握缠论自动识别的核心算法

| 序号 | 文件路径 | 关键内容 | 阅读重点 |
|------|---------|---------|---------|
| 4 | `czsc/py/analyze.py` | 缠论分析核心类 `CZSC` | `remove_include`（去包含）, `check_fx`（识别分型）, `check_bi`（识别笔） |
| 5 | `czsc/py/bar_generator.py` | K线生成器 `BarGenerator` | 多周期K线合成、K线更新逻辑 |

**阅读建议**:
- **`remove_include`**: 理解包含关系的处理（缠论的关键）
- **`check_fx`**: 分型识别的3根K线判断逻辑
- **`check_bi`**: 笔的识别规则（分型之间的有效连接）
- **`BarGenerator`**: 如何从基础周期合成更大周期的K线

**代码示例**:
```python
from czsc.core import CZSC, format_standard_kline, Freq
from czsc.mock import generate_symbol_kines

# 生成模拟K线数据
df = generate_symbol_kines('000001', '30分钟', '20240101', '20240105')
bars = format_standard_kline(df, freq=Freq.F30)

# 创建CZSC分析对象
czsc_obj = CZSC(bars)

# 查看识别结果
print(f"分型数量: {len(czsc_obj.fx_list)}")
print(f"笔的数量: {len(czsc_obj.bi_list)}")
print(f"最后一笔: {czsc_obj.bi_list[-1]}")
```

### 🥉 第三阶段：信号体系（重要）

**目标**: 理解如何定义和使用交易信号

| 序号 | 文件路径 | 关键内容 | 阅读重点 |
|------|---------|---------|---------|
| 6 | `czsc/signals/bar.py` | K线级别信号 | 信号函数的标准格式、命名规范 |
| 7 | `czsc/signals/cxt.py` | 上下文信号 | 多级别信号、分型笔信号 |
| 8 | `czsc/signals/tas.py` | 技术指标信号 | 均线、MACD、RSI 等信号 |
| 9 | `czsc/signals/vol.py` | 成交量信号 | 量价关系信号 |
| 10 | `czsc/signals/pos.py` | 持仓相关信号 | 开仓后的状态信号 |

**阅读建议**:
- 每个信号模块选 2-3 个函数深入阅读
- 理解信号函数的标准输入输出格式
- 注意信号命名规范（版本化命名，如 `V241013`）

**信号函数标准格式**:
```python
def signal_example_V240101(c: CZSC, **kwargs) -> OrderedDict:
    """信号函数示例
    
    参数模板: "30分钟_信号名称_参数1_参数2_0"
    
    :param c: CZSC对象
    :param kwargs: 其他参数
    :return: 信号字典
    """
    di = kwargs.get('di', 1)  # 倒数第几根K线
    # ... 信号计算逻辑 ...
    
    v = "满足" if 条件 else "不满足"
    s = {
        "信号名称": f"{c.freq.value}_D{di}_信号名称_参数1_参数2_{v}_0"
    }
    return s
```

### 🏅 第四阶段：交易框架（核心应用）

**目标**: 掌握策略定义和回测执行

| 序号 | 文件路径 | 关键内容 | 阅读重点 |
|------|---------|---------|---------|
| 11 | `czsc/traders/base.py` | `CzscSignals`, `CzscTrader` | 多级别信号计算、交易决策流程 |
| 12 | `czsc/strategies.py` | `CzscStrategyBase`, `CzscJsonStrategy` | 策略定义的标准模板、JSON配置化 |
| 13 | `czsc/sensors/cta.py` | `CTAResearch` | 策略研究框架、回测和优化 |
| 14 | `czsc/traders/dummy.py` | `DummyBacktest` | 简单回测框架 |

**阅读建议**:
- **`CzscSignals`**: 如何从 K线生成器（BarGenerator）计算信号
- **`CzscTrader`**: 如何根据信号和持仓策略（Position）执行交易
- **`CzscStrategyBase`**: 策略的四要素（品种、周期、信号、持仓）
- **`CTAResearch`**: 如何组织策略回测和参数优化

**策略定义示例**:
```python
from czsc import CzscJsonStrategy, Event, Position

class MyStrategy(CzscJsonStrategy):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
    
    @property
    def positions(self):
        """定义持仓策略"""
        opens = [{"operate": "开多", "factors": [...]}]
        exits = [{"operate": "平多", "factors": [...]}]
        
        pos = Position(
            name="策略名称",
            symbol=self.symbol,
            opens=[Event.load(x) for x in opens],
            exits=[Event.load(x) for x in exits],
            interval=3600,  # 开仓间隔（秒）
            timeout=100,    # 超时退出（K线数）
            stop_loss=500   # 止损（基点）
        )
        return [pos]
```

### 🎖️ 第五阶段：工具和服务（扩展阅读）

**目标**: 了解辅助工具和高级功能

| 序号 | 文件路径 | 关键内容 | 用途说明 |
|------|---------|---------|---------|
| 15 | `czsc/utils/ta.py` | 技术指标计算 | 常用技术指标实现（TA-Lib包装） |
| 16 | `czsc/utils/plotting/backtest.py` | 回测可视化 | Plotly交互式图表（累计收益、回撤等） |
| 17 | `czsc/svc/backtest.py` | 回测分析服务 | 绩效统计、风险指标计算 |
| 18 | `czsc/connectors/` | 数据源连接器 | Tushare、聚宽、天勤等数据接入 |
| 19 | `czsc/traders/optimize.py` | 参数优化 | 网格搜索、参数优化工具 |

**阅读建议**:
- 根据实际需求选择性阅读
- 重点关注自己会用到的数据源连接器
- 回测可视化模块是数据分析的好帮手

---

## 详细模块解析

### 模块1: `czsc/py/analyze.py` - 缠论分析核心

**核心类**: `CZSC`

**关键方法**:

```python
class CZSC:
    def __init__(self, bars: List[RawBar], **kwargs):
        """初始化CZSC分析对象"""
        
    def update(self, bar: RawBar):
        """更新一根K线，实时识别分型、笔"""
        
    @property
    def bars_raw(self) -> List[RawBar]:
        """原始K线序列"""
        
    @property
    def bars_ubi(self) -> List[NewBar]:
        """去除包含关系后的K线序列"""
        
    @property
    def fx_list(self) -> List[FX]:
        """识别出的分型序列"""
        
    @property
    def bi_list(self) -> List[BI]:
        """识别出的笔序列"""
```

**工作流程**:
1. 输入原始K线 (`RawBar`)
2. 去除包含关系 → 生成 `NewBar` 序列
3. 识别分型 → 生成 `FX` 序列
4. 识别笔 → 生成 `BI` 序列
5. 识别中枢 → 生成 `ZS` 序列（如需要）

### 模块2: `czsc/traders/base.py` - 交易执行框架

**核心类**: `CzscSignals` 和 `CzscTrader`

#### `CzscSignals`: 多级别信号计算

```python
class CzscSignals:
    def __init__(self, bg: BarGenerator, **kwargs):
        """
        bg: K线生成器（包含多个周期的K线）
        signals_config: 信号配置列表
        """
        self.kas = {freq: CZSC(bars) for freq, bars in bg.bars.items()}
        # kas 是一个字典，key是周期，value是CZSC对象
        
    def get_signals_by_conf(self) -> OrderedDict:
        """根据配置计算所有信号"""
```

**使用示例**:
```python
signals_config = [
    {'name': 'czsc.signals.tas_ma_base_V221101', 
     'freq': '日线', 'di': 1, 'ma_type': 'SMA', 'timeperiod': 5},
    {'name': 'czsc.signals.cxt_bi_status_V230101', 
     'freq': '30分钟', 'di': 1},
]

cs = CzscSignals(bg, signals_config=signals_config)
signals = cs.s  # 当前所有信号字典
```

#### `CzscTrader`: 完整交易决策

```python
class CzscTrader:
    def __init__(self, bg: BarGenerator, positions: List[Position], **kwargs):
        """
        bg: K线生成器
        positions: 持仓策略列表
        """
        
    def update(self, bar: RawBar):
        """更新一根K线，判断是否触发交易事件"""
        
    @property
    def positions(self) -> List[Position]:
        """所有持仓策略及其状态"""
```

### 模块3: `czsc/strategies.py` - 策略定义

**策略四要素**:

1. **交易品种**: `symbol` 和品种相关参数
2. **K线周期**: 从信号配置中自动提取
3. **信号配置**: `signals_config` 列表
4. **持仓策略**: `positions` 方法返回的 `Position` 列表

**标准流程**:
```python
class MyStrategy(CzscStrategyBase):
    @property
    def positions(self):
        # 定义开仓事件
        opens = [
            {
                "operate": "开多",
                "factors": [
                    {
                        "signals_all": ["信号1", "信号2"],  # 必须同时满足
                        "signals_any": ["信号3", "信号4"],  # 满足任一
                        "signals_not": ["信号5"],           # 不能出现
                    }
                ]
            }
        ]
        
        # 定义平仓事件
        exits = [...]
        
        # 创建持仓对象
        pos = Position(name="策略名", symbol=self.symbol, 
                      opens=[Event.load(x) for x in opens],
                      exits=[Event.load(x) for x in exits])
        return [pos]
```

---

## 实战上手指南

### 示例1: 基础缠论分析

```python
"""识别分型和笔"""
from czsc.core import CZSC, format_standard_kline, Freq
from czsc.mock import generate_symbol_kines

# 1. 准备K线数据
df = generate_symbol_kines('000001', '30分钟', '20240101', '20240131')
bars = format_standard_kline(df, freq=Freq.F30)

# 2. 创建CZSC分析对象
czsc_obj = CZSC(bars)

# 3. 查看识别结果
print("=" * 50)
print(f"原始K线数量: {len(czsc_obj.bars_raw)}")
print(f"处理后K线数量: {len(czsc_obj.bars_ubi)}")
print(f"分型数量: {len(czsc_obj.fx_list)}")
print(f"笔数量: {len(czsc_obj.bi_list)}")

# 4. 查看最后一笔的信息
last_bi = czsc_obj.bi_list[-1]
print(f"\n最后一笔:")
print(f"  方向: {last_bi.direction}")
print(f"  高点: {last_bi.high}")
print(f"  低点: {last_bi.low}")
print(f"  时间: {last_bi.fx_b.dt}")
```

### 示例2: 多级别K线合成

```python
"""使用BarGenerator合成多周期K线"""
from czsc.core import BarGenerator, format_standard_kline, Freq
from czsc.mock import generate_symbol_kines

# 1. 准备基础周期K线（1分钟）
df = generate_symbol_kines('000001', '1分钟', '20240101', '20240105')
bars = format_standard_kline(df, freq=Freq.F1)

# 2. 创建K线生成器（合成多周期）
bg = BarGenerator(
    base_freq='1分钟',
    freqs=['5分钟', '15分钟', '30分钟', '日线'],
    max_count=2000
)

# 3. 逐根更新K线
for bar in bars:
    bg.update(bar)

# 4. 查看各周期K线数量
for freq, freq_bars in bg.bars.items():
    print(f"{freq}: {len(freq_bars)} 根K线")
    
# 5. 获取某个周期的K线
bars_30m = bg.bars[Freq.F30]
print(f"\n30分钟K线最后一根: {bars_30m[-1]}")
```

### 示例3: 计算信号

```python
"""使用CzscSignals计算多级别信号"""
from czsc.traders import CzscSignals
from czsc.core import BarGenerator, format_standard_kline, Freq
from czsc.mock import generate_symbol_kines

# 1. 准备K线生成器
df = generate_symbol_kines('000001', '1分钟', '20240101', '20240105')
bars = format_standard_kline(df, freq=Freq.F1)
bg = BarGenerator(base_freq='1分钟', freqs=['5分钟', '30分钟', '日线'])
for bar in bars:
    bg.update(bar)

# 2. 定义信号配置
signals_config = [
    # 均线信号
    {'name': 'czsc.signals.tas_ma_base_V221101', 
     'freq': '日线', 'di': 1, 'ma_type': 'SMA', 'timeperiod': 5},
    # 分型状态信号
    {'name': 'czsc.signals.cxt_fx_power_V221107', 
     'freq': '30分钟', 'di': 1},
]

# 3. 创建信号计算对象
cs = CzscSignals(bg, signals_config=signals_config)

# 4. 查看当前信号
print("当前信号:")
for k, v in cs.s.items():
    print(f"  {k}: {v}")
```

### 示例4: 完整策略回测

```python
"""使用CTAResearch进行策略回测"""
from czsc.sensors import CTAResearch
from czsc import CzscStrategyBase, Position, Event

# 1. 定义策略类
class SimpleStrategy(CzscStrategyBase):
    @property
    def positions(self):
        opens = [{
            "operate": "开多",
            "factors": [{
                "signals_all": ["30分钟_D1_表里关系V230101_向上_任意_任意_0"],
            }]
        }]
        exits = []
        
        pos = Position(
            name="简单策略",
            symbol=self.symbol,
            opens=[Event.load(x) for x in opens],
            exits=[Event.load(x) for x in exits],
            interval=3600,
            timeout=100
        )
        return [pos]

# 2. 定义读取K线的函数
def read_bars(symbol, freq, sdt, edt, **kwargs):
    from czsc.mock import generate_symbol_kines
    from czsc.core import format_standard_kline, Freq
    df = generate_symbol_kines(symbol, freq, sdt, edt)
    return format_standard_kline(df, freq=Freq.F30)

# 3. 创建研究对象
cta = CTAResearch(
    strategy=SimpleStrategy,
    read_bars=read_bars,
    results_path='./results'
)

# 4. 执行回测
cta.replay(symbol='000001', sdt='20240101', edt='20240131')
```

### 示例5: 回测结果可视化

```python
"""绘制回测图表"""
from czsc.utils.plotting.backtest import (
    plot_cumulative_returns,
    plot_backtest_stats,
    plot_monthly_heatmap
)
import pandas as pd

# 假设你已经有了日收益数据 (DataFrame, index为日期)
# dret = pd.read_csv('daily_returns.csv', index_col=0, parse_dates=True)

# 1. 累计收益曲线
fig = plot_cumulative_returns(
    dret,
    title="策略累计收益",
    template="plotly"
)
fig.show()

# 2. 综合统计图（回撤+分布+热力图）
fig = plot_backtest_stats(dret, ret_col='total', title="回测统计")
fig.show()

# 3. 月度收益热力图
fig = plot_monthly_heatmap(dret, ret_col='total')
fig.show()

# 4. 导出HTML
html = plot_cumulative_returns(dret, to_html=True)
with open('backtest_report.html', 'w', encoding='utf-8') as f:
    f.write(html)
```

---

## 进阶学习路径

### Level 1: 入门阶段（1-2周）

**目标**: 能够使用现有策略进行回测

- [ ] 完成"源码阅读顺序"的第1-2阶段
- [ ] 运行 `examples/30分钟笔非多即空.py` 示例
- [ ] 理解 `Position` 和 `Event` 的配置方法
- [ ] 尝试修改策略参数（间隔、超时、止损）

**推荐资料**:
- 飞书文档: [CTA择时：缠论30分钟笔非多即空](https://s0cqcxuy3p.feishu.cn/wiki/YPlewoj70ikwxakPnOucTP8lnYg)
- B站视频教程（入门篇）

### Level 2: 进阶阶段（2-4周）

**目标**: 能够开发自定义信号函数

- [ ] 完成"源码阅读顺序"的第3阶段
- [ ] 阅读 `czsc/signals/` 下至少5个信号函数
- [ ] 编写1-2个自定义信号函数
- [ ] 理解信号命名规范和版本管理

**推荐资料**:
- 飞书文档: [信号函数编写规范](https://s0cqcxuy3p.feishu.cn/wiki/wikcnCFLLTNGbr2THqo7KtWfBkd)
- 查看 `examples/signals_dev/` 示例

### Level 3: 高级阶段（4-8周）

**目标**: 能够开发完整策略并优化

- [ ] 完成"源码阅读顺序"的第4-5阶段
- [ ] 使用 `CTAResearch` 框架进行策略研究
- [ ] 学习参数优化（`OpensOptimize`, `ExitsOptimize`）
- [ ] 理解多品种回测和组合优化

**推荐资料**:
- 飞书文档: [使用CTA研究UI页面进行策略研究](https://s0cqcxuy3p.feishu.cn/wiki/JWe3wo1VNiglO9kE999cGy8innh)
- 查看 `examples/use_optimize.py`

### Level 4: 专家阶段（持续学习）

**目标**: 贡献代码、深度定制

- [ ] 理解 Rust/Python 混合架构
- [ ] 阅读 `rs-czsc` Rust 实现源码
- [ ] 为项目贡献信号函数或工具
- [ ] 开发自定义数据源连接器

**推荐资料**:
- 项目 GitHub Issues 和 Pull Requests
- 飞书群讨论（链接见 README）

---

## 常见问题 FAQ

### Q1: 如何选择阅读Python版本还是Rust版本？

**A**: 
- **初学者**: 建议阅读 **Python 版本**（`czsc/py/`），代码更易理解
- 设置环境变量 `CZSC_USE_PYTHON=1` 强制使用 Python 版本
- Rust 版本主要用于性能优化，核心逻辑与 Python 版本一致

### Q2: 信号函数中的 `di` 参数是什么意思？

**A**: `di` 表示"倒数第几根K线"（Distance Index）
- `di=1`: 最后一根K线（实时）
- `di=2`: 倒数第二根K线
- 用于回溯分析历史信号

### Q3: 如何理解"去除包含关系"？

**A**: 这是缠论的核心概念
- 包含关系: 一根K线的高低点被另一根完全包含
- 去除方法: 根据趋势方向合并K线（向上取大，向下取小）
- 详见 `czsc/py/analyze.py` 中的 `remove_include` 函数

### Q4: 策略回测为什么没有交易信号？

**A**: 检查以下几点：
1. K线数据是否充足（至少100根以上）
2. 信号配置是否正确（检查信号名称和参数）
3. 开仓事件的信号条件是否过于严格
4. 使用 `print(cs.s)` 查看实际生成的信号

### Q5: 如何获取更多数据源？

**A**: 
- 查看 `czsc/connectors/` 目录
- Tushare: 需要 token（免费注册）
- 聚宽: 需要账号认证
- 天勤: 期货数据，需要账号
- 建议先使用 `czsc.mock.generate_symbol_kines` 模拟数据学习

---

## 推荐学习资源

### 缠论原著

- [缠中说禅博客备份1](http://www.fxgan.com)
- [缠中说禅博客备份2](https://chzhshch.blog)
- 项目 `czsc/docs/` 目录下的整理版文档

### 视频教程

- [B站官方教程合集](https://space.bilibili.com/243682308/channel/series)
- 涵盖从入门到实战的完整教程

### 在线文档

- [API 文档](https://czsc.readthedocs.io/en/latest/modules.html)
- [飞书项目文档](https://s0cqcxuy3p.feishu.cn/wiki/wikcn3gB1MKl3ClpLnboHM1QgKf)

### 社区交流

- 飞书群: [加入链接](https://applink.feishu.cn/client/chat/chatter/add_by_link?link_token=0bak668e-7617-452c-b935-94d2c209e6cf)
- GitHub Issues: 提问和讨论
- 微信: zengbin93（备注"CZSC学习"）

---

## 附录：关键文件清单

### 核心模块（必读）

```
czsc/
├── core.py                    # Rust/Python混合架构入口
├── py/
│   ├── enum.py                # 枚举类型定义
│   ├── objects.py             # 核心数据结构
│   ├── analyze.py             # 缠论分析核心（CZSC类）
│   └── bar_generator.py       # K线生成器
├── signals/                   # 信号函数库
│   ├── bar.py                 # K线信号
│   ├── cxt.py                 # 上下文信号
│   ├── tas.py                 # 技术指标信号
│   ├── vol.py                 # 成交量信号
│   └── pos.py                 # 持仓信号
├── traders/                   # 交易执行框架
│   ├── base.py                # CzscSignals和CzscTrader
│   ├── dummy.py               # 简单回测
│   └── optimize.py            # 参数优化
├── strategies.py              # 策略定义模板
└── sensors/
    └── cta.py                 # CTA研究框架
```

### 工具和服务（选读）

```
czsc/
├── utils/                     # 工具模块
│   ├── ta.py                  # 技术指标
│   ├── plotting/backtest.py   # 回测可视化
│   └── data/                  # 数据工具
├── svc/                       # 服务模块
│   ├── backtest.py            # 回测分析
│   ├── factor.py              # 统计因子分析
│   └── statistics.py          # 统计工具
├── connectors/                # 数据源连接器
│   ├── ts_connector.py        # Tushare
│   ├── jq_connector.py        # 聚宽
│   └── tq_connector.py        # 天勤
└── mock.py                    # 模拟数据生成
```

### 示例代码（实战参考）

```
examples/
├── 30分钟笔非多即空.py         # 经典策略示例
├── use_cta_research.py        # CTA框架使用
├── use_optimize.py            # 参数优化示例
└── signals_dev/               # 信号开发示例
```

---

## 总结

本指南提供了系统化的 CZSC 源码阅读路径，建议按照以下步骤进行：

1. ✅ **理解核心概念** - 花1天时间理解信号-事件-交易体系
2. ✅ **阅读核心数据结构** - 2-3天深入理解 `objects.py` 和 `enum.py`
3. ✅ **学习核心算法** - 3-5天精读 `analyze.py`，理解分型、笔识别
4. ✅ **实战信号开发** - 1-2周学习和模仿现有信号函数
5. ✅ **策略开发与回测** - 2-4周开发完整策略并回测优化

**记住**: 量化交易是实践驱动的，边学边做效果最好！

理解核心理念：
- **信号(Signal)**: 市场状态的基本判断
- **事件(Event)**: 信号的逻辑组合，代表交易条件
- **持仓(Position)**: 完整的交易策略定义


---

**文档版本**: v1.0.0  
**更新日期**: 2024-02-16  
**作者**: CZSC Community  
**维护**: 如有疑问或建议，请提交 GitHub Issue
