第六版

chanlun-py/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "chanlun-py"
-version = "26.5.10"
+version = "26.5.11"
 edition = "2021"
 description = "缠论技术分析库 — Rust 高性能 Python 绑定"
 authors = ["YuYuKunKun"]
@@ -14,7 +14,7 @@ name = "chanlun"
 [dependencies]
 # 发布至 PyPI 前，需先将 chanlun 发布至 crates.io，然后替换为版本号依赖:
 # chanlun = "0.1"
-chanlun = { path = "../chanlun" }
+chanlun = "25.5.1" # { path = "../chanlun" }
 pyo3 = { version = "0.28", features = ["extension-module"] }
 serde_json = "1"
 chrono = "0.4"

chanlun-py/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "chanlun"
-version = "2605.10"
+version = "2605.11"
 description = "缠论技术分析库 — Rust 高性能实现"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE", content-type = "text/plain" }

chanlun-py/src/algorithm_py.rs

@@ -34,6 +34,16 @@ use crate::types_py::相对方向Py;
 
 // ========== 背驰分析 ==========
 
+/// 背驰分析 — 静态方法容器，提供背驰/背离检测算法。
+///
+/// 所有方法均为 staticmethod，直接调用无需实例化。
+///
+/// 方法:
+///   MACD背驰(虚线段, 线段序列, 中枢序列, 配置) -> bool
+///   MACD趋势背驰(虚线段, 线段序列, 中枢序列, 配置) -> bool
+///   MACD盘整背驰(虚线段, 线段序列, 中枢序列, 配置) -> bool
+///   MACD柱子面积背驰(虚线段, 线段序列, 中枢序列, 配置) -> bool
+///   MACD柱子高度背驰(虚线段, 线段序列, 中枢序列, 配置) -> bool
 #[pyclass(name = "背驰分析")]
 pub struct 背驰分析Py;
 
@@ -191,6 +201,17 @@ impl 背驰分析Py {
 
 // ========== 笔 ==========
 
+/// 笔 — 静态方法容器，提供笔的创建与分析算法。
+///
+/// 所有方法均为 staticmethod，直接调用无需实例化。
+///
+/// 方法:
+///   创建(左分型, 右分型, 序号, 级别, 有效性?, 标识?) -> 虚线
+///      — 在左右分型之间创建一笔
+///   分析(分型序列, 配置, 序?, 初级序列?, 级别?) -> list[虚线]
+///      — 从分型序列中划分出所有笔
+///   弱化(笔序列) — 根据配置对笔序列执行弱化处理
+///   分析前检查(分型序列, 配置) -> bool — 检查是否可以启动笔分析
 #[pyclass(name = "笔")]
 pub struct 笔Py;
 
@@ -459,6 +480,24 @@ impl 笔Py {
 
 // ========== 线段 ==========
 
+/// 线段 — 静态方法容器，提供线段的创建与分析算法。
+///
+/// 所有方法均为 staticmethod/classmethod，直接调用无需实例化。
+///
+/// 核心方法:
+///   创建(左分型, 右分型, 级别, 序号?, 标识?) -> 虚线
+///   分析(笔序列, 配置, 级别?) -> (list[虚线], list[线段特征])
+///      — 从笔序列中划分线段，返回(线段序列, 特征序列)
+///
+/// 辅助方法:
+///   扩展分析(基础序列, 扩展结果容器, 配置) — 从基础序列生成扩展分析
+///   特征序列分析(特征序列, 中枢序列, 配置, 标识?) — 分析特征序列产生中枢
+///   分析前检查(分型序列, 配置) -> bool
+///   四象(虚线段) -> str — 返回"少阳"/"少阴"/"老阳"/"老阴"
+///   特征序列状态(虚线段) -> str
+///   虚线段特征序列成立(虚线段, 虚线序列, 配置) -> bool
+///   移除包含后的特征序列(特征序列, 配置) -> list[线段特征]
+///   检查特征序列趋势(特征序列) -> bool
 #[pyclass(name = "线段")]
 pub struct 线段Py;
 
@@ -939,6 +978,43 @@ impl 线段Py {
 
 // ========== 中枢 ==========
 
+/// 中枢 — 三段虚线重叠区间构成的价格中枢，支持延伸/扩展。
+///
+/// 属性 (只读):
+///   序号: int / 标识: str (如 "中枢<笔>" / "中枢<线段>") / 级别: int
+///   基础序列: list[虚线] — 构成中枢的三段虚线
+///   第三买卖线: 虚线|None — 第三类买卖点确认线
+///   本级_第三买卖线: 虚线|None
+///
+/// 计算属性:
+///   高: float — 中枢上沿（三段虚线高点的最小值）
+///   低: float — 中枢下沿（三段虚线低点的最大值）
+///   高高: float — 所有虚线高点的最大值
+///   低低: float — 所有虚线低点的最小值
+///   方向: 相对方向 — 中枢方向（与第一段虚线方向相反）
+///   文: 分型 — 中枢起点分型（第一段虚线的起点）
+///   武: 分型 — 中枢终点分型（最后一段虚线的终点）
+///   离开段: 虚线 — 中枢最后一段虚线
+///   图表标题: str
+///
+/// 方法:
+///   添加虚线(虚线) — 向中枢追加虚线（延伸）
+///   获取序列() -> list[虚线] — 基础序列 + 第三买卖线
+///   获取扩展中枢(扩展中枢列表, 配置) — 基础序列 >= 9 时生成扩展中枢
+///   校验合法性(虚线序列) -> bool — 根据当前虚线序列校验中枢合法性
+///   设置第三买卖线(虚线|None) — 设置第三类买卖确认线
+///   完整性(虚实="合") -> bool — 中枢是否完整（已有第三买卖线确认）
+///   当前状态() -> str — "中枢之上"/"中枢之下"/"中枢之中"
+///   获取数据文本() -> str
+///
+/// 类方法:
+///   基础检查(左虚线, 中虚线, 右虚线) -> bool — 检查三段虚线能否构成中枢
+///   创建(左虚线, 中虚线, 右虚线, 级别, 标识?) -> 中枢 — 创建新中枢
+///   从序列中获取中枢(虚线序列, 允许重叠?, 标识前缀?, 高级中枢容器?...) -> list[中枢]
+///      — 扫描虚线序列提取所有中枢
+///   向中枢序列尾部添加(中枢序列, 新中枢) — 维护中枢序列顺序
+///   从中枢序列尾部弹出(中枢序列, 配置) — 弹出最后一个中枢并更新相邻中枢
+///   分析(虚线序列, 中枢序列容器, 允许重叠?, 标识前缀?, ...) — 中枢分析主流程
 #[pyclass(name = "中枢", unsendable)]
 #[derive(Clone)]
 pub struct 中枢Py {

chanlun-py/src/business_py.rs

@@ -36,6 +36,14 @@ use crate::types_py::买卖点类型Py;
 
 // ========== 基础买卖点 ==========
 
+/// 基础买卖点 — 买卖点的数据结构，描述偏离买入/卖出位置的程度。
+///
+/// 属性:
+///   偏移: int — 买卖点距当前K线的偏差
+///   失效偏移: int — 买卖点失效的最大偏差
+///   有效性: bool — 买卖点是否仍有效
+///   与MACD柱子匹配: bool|None — 是否与MACD柱状图方向匹配
+///   与MACD柱子分型匹配: bool|None — 是否与MACD柱分型匹配
 #[pyclass(name = "基础买卖点", unsendable)]
 #[derive(Clone)]
 pub struct 基础买卖点Py {
@@ -156,6 +164,12 @@ impl 基础买卖点Py {
 
 // ========== 买卖点 ==========
 
+/// 买卖点 — 静态方法容器，提供各类买卖点的构造算法（不存储数据）。
+///
+/// 类方法（均返回对应的买卖点对象）:
+///   一卖点(...) / 一买点(...) / 二卖点(...) / 二买点(...) / 三卖点(...) / 三买点(...)
+///   生成买卖点(特征, 序号, 级别, 分型, 当前缠K, 备注?) -> 买卖点
+///      — 根据特征字符串自动路由到对应的一/二/三类买卖点构造函数
 #[pyclass(name = "买卖点")]
 pub struct 买卖点Py;
 
@@ -304,6 +318,35 @@ impl 买卖点Py {
 
 // ========== 观察者 ==========
 
+/// 观察者 — 单周期分析器，接收 K 线流式输入后逐层计算所有序列。
+///
+/// 支持 Python 继承（__new__ + __init__ 构造函数）。每根 K 线喂入后
+/// 自动增量计算: 缠论K线 → 分型 → 笔 → 线段 → 中枢 等全部层级。
+///
+/// 构造:
+///   观察者(符号, 周期, 配置) — 创建指定周期和配置的分析器
+///
+/// 属性（只读）:
+///   符号: str / 周期: int / 标识: str
+///   当前K线: K线|None / 当前缠K: 缠论K线|None
+///
+/// 序列 getter（只读，返回 list 副本）:
+///   普通K线序列 / 缠论K线序列 / 分型序列
+///   笔序列 / 笔_中枢序列
+///   线段序列 / 中枢序列
+///   扩展线段序列 / 扩展中枢序列
+///   扩展线段序列_线段 / 扩展中枢序列_线段
+///   线段_线段序列 / 线段_中枢序列
+///   扩展线段序列_扩展线段 / 扩展中枢序列_扩展线段
+///
+/// 核心方法:
+///   增加原始K线(普K) — 喂入一根普通K线，触发全层级增量计算
+///   重置基础序列() — 清空所有计算状态和序列
+///   静态重新分析() — 对已有普通K线序列进行全量重新分析
+///
+/// 调试方法:
+///   测试_保存数据(root?) — 将各层级序列保存到文件，用于与Python版对比
+///   读取数据文件(文件路径, 配置) -> 观察者 (classmethod) — 从 .nb 文件加载数据
 #[pyclass(name = "观察者", subclass, unsendable)]
 pub struct 观察者Py {
     pub(crate) inner: Option<Rc<RefCell<chanlun::business::observer::观察者>>>,
@@ -598,6 +641,16 @@ impl 观察者Py {
 
 // ========== K线合成器 ==========
 
+/// K线合成器 — 将小周期K线合成为大周期K线。
+///
+/// 构造:
+///   K线合成器(标识, 周期组) — 周期组为升序排列的整数列表（如 [60, 300, 900]）
+///
+/// 方法:
+///   投喂K线(普K) -> list[(周期, K线)] — 喂入普通K线，返回合成后的大周期K线
+///   投喂(时间戳, 开盘价, 最高价, 最低价, 收盘价, 成交量) -> list[(周期, K线)]
+///      — 快捷入口，免去构造K线对象
+///   获取当前K线(周期) -> K线|None — 获取指定周期的当前合成结果
 #[pyclass(name = "K线合成器", unsendable)]
 pub struct K线合成器Py {
     pub(crate) inner: chanlun::business::synthesizer::K线合成器,
@@ -671,6 +724,17 @@ impl K线合成器Py {
 
 // ========== 立体分析器 ==========
 
+/// 立体分析器 — 多周期分析器，内部包含 K线合成器 + 每周期一个观察者。
+///
+/// 通过最小周期数据合成大周期，并将各周期分析结果对齐。
+///
+/// 构造:
+///   立体分析器(符号, 周期组, 配置?, 配置组?) — 周期组为升序列表（如 [60, 300, 900]）
+///     配置为默认配置，配置组为各周期独立配置（dict[周期, 缠论配置]）
+///
+/// 方法:
+///   投喂K线(普K) — 喂入最小周期K线，自动合成大周期并分发给各周期观察者
+///   测试_保存数据(root?) — 保存各周期的分析数据到文件
 #[pyclass(name = "立体分析器", unsendable)]
 pub struct 立体分析器Py {
     pub(crate) inner: chanlun::business::multi_frame::立体分析器,

chanlun-py/src/config_py.rs

@@ -26,7 +26,71 @@ use pyo3::prelude::*;
 use pyo3::types::{PyDict, PyType};
 use std::collections::HashMap;
 
-/// 缠论配置 — Python binding
+/// 缠论配置 — 控制所有分析阶段行为的参数集（共 60+ 字段，均有默认值）。
+///
+/// 构造:
+///   缠论配置(**kwargs) — 创建配置，可选关键字参数覆盖默认值
+///
+/// 字段分组:
+///   [基础]
+///     标识: str — K线标识（默认 "bar"）
+///
+///   [缠K]
+///     缠K合并替换: bool — K线合并时是否替换原值
+///
+///   [笔]
+///     笔内元素数量: int — 笔的最小元素数（默认 5）
+///     笔弱化: bool — 是否启用笔弱化模式
+///     笔次成笔: bool — 线段内部次级笔是否成笔
+///     笔内相同终点取舍: bool / 笔内起始分型包含整笔: bool /
+///     笔内原始K线包含整笔: bool
+///
+///   [线段]
+///     线段_特征序列忽视老阴老阳: bool / 线段_缺口后紧急修正: bool /
+///     线段_非缺口下穿刺: bool / 线段_修正: bool / 线段内部中枢图显: bool /
+///     扩展线段_当下分析: bool
+///
+///   [分析开关]
+///     分析笔: bool / 分析线段: bool / 分析扩展线段: bool /
+///     分析笔中枢: bool / 分析线段中枢: bool
+///
+///   [指标]
+///     计算指标: bool / 指标计算方式: str
+///     平滑异同移动平均线_快线周期: int / _慢线周期 / _信号周期
+///     相对强弱指数_周期: int / _移动平均线周期 / _超买阈值 / _超卖阈值
+///     随机指标_RSV周期: int / _K值平滑周期 / _D值平滑周期 / _超买阈值 / _超卖阈值
+///
+///   [推送/显示]
+///     图表展示: bool / 推送K线: bool / 推送笔: bool / 推送线段: bool / 推送中枢: bool
+///     图表展示_笔: bool / 图表展示_线段: bool / 图表展示_扩展线段: bool /
+///     图表展示_中枢_笔: bool / 图表展示_中枢_线段: bool 等
+///
+///   [买卖点]
+///     买卖点偏移: int / 买卖点激进识别: bool / 买卖点与MACD柱强相关: bool /
+///     买卖点错过误差值: float / 买卖点_背离率: float /
+///     买卖点_计算方式: str / 买卖点_中枢来源: str /
+///     买卖点_指标模式: str / 买卖点_指标匹配_MACD: bool / _KDJ: bool / _RSI: bool /
+///     买卖点_峰值条件: bool / 买卖点_依赖T1: bool /
+///     买卖点_计算线段BSP1: bool / _处理BSP2: bool / _计算线段BSP3: bool
+///
+///   [背驰]
+///     线段内部背驰_MACD: bool / 线段内部背驰_斜率: bool /
+///     线段内部背驰_测度: bool / 线段内部背驰_模式: str
+///
+///   [其他]
+///     手动终止: str — 手动终止时间（ISO 8601 字符串）
+///     加载文件路径: str
+///
+/// 方法:
+///   to_dict() -> dict — 导出为 Python 字典
+///   to_json() -> str — 导出为 JSON 字符串
+///   保存配置(path?) — 保存到 JSON 文件（默认 "缠论配置.json"）
+///   加载配置(path?) -> 缠论配置 (classmethod) — 从 JSON 文件加载
+///   from_dict(data) -> 缠论配置 (classmethod) — 从字典创建
+///   from_json(json_str) -> 缠论配置 (classmethod) — 从 JSON 字符串创建
+///   不推送() -> 缠论配置 (classmethod) — 创建关闭所有推送的配置副本
+///   按序号重组字典(默认配置, 原始字典) -> dict (classmethod) — 按默认配置的键序重排字典
+///   对比(other) -> dict — 返回与另一个配置的差异字段
 #[pyclass(name = "缠论配置")]
 pub struct 缠论配置Py {
     fields: HashMap<String, Py<PyAny>>,
@@ -90,6 +154,7 @@ impl 缠论配置Py {
         self.__str__()
     }
 
+    /// 将配置导出为 Python 字典。
     fn to_dict(&self, py: Python<'_>) -> PyResult<Py<PyDict>> {
         let dict = PyDict::new(py);
         for (k, v) in &self.fields {
@@ -98,6 +163,7 @@ impl 缠论配置Py {
         Ok(dict.into())
     }
 
+    /// 将配置序列化为 JSON 字符串。
     fn to_json(&self, py: Python<'_>) -> PyResult<String> {
         let dict = self.to_dict(py)?;
         let json_mod = py.import("json")?;
@@ -105,12 +171,14 @@ impl 缠论配置Py {
         dumps.call1((dict,))?.extract()
     }
 
+    /// 保存配置到 JSON 文件（默认路径 "缠论配置.json"）。
     fn 保存配置(&self, py: Python<'_>, path: Option<&str>) -> PyResult<()> {
         let path = path.unwrap_or("缠论配置.json");
         let json = self.to_json(py)?;
         std::fs::write(path, json).map_err(|e| pyo3::exceptions::PyIOError::new_err(e.to_string()))
     }
 
+    /// 从 JSON 文件加载配置（默认路径 "缠论配置.json"）。
     #[classmethod]
     fn 加载配置(
         _cls: &Bound<'_, PyType>,

chanlun-py/src/indicators_py.rs

@@ -27,6 +27,22 @@ use pyo3::types::PyType;
 
 // ========== 平滑异同移动平均线 ==========
 
+/// MACD 技术指标 — 指数平滑异同移动平均线。
+///
+/// 属性:
+///   时间戳: str / 收盘价: float / 快线周期: int / 慢线周期: int / 信号周期: int
+///   DIF: float|None — 快线EMA - 慢线EMA
+///   DEA: float|None — DIF 的 EMA 平滑（信号线）
+///   MACD柱: float — (DIF - DEA) * 2（柱状值）
+///   快线EMA: float|None / 慢线EMA: float|None / DEA_EMA: float|None
+///
+/// 方法（均为 classmethod，直接构造实例）:
+///   首次计算(初始收盘价, 初始时间, 快线周期=12, 慢线周期=26, 信号周期=9) -> 平滑异同移动平均线
+///   首次计算_K线(k线, 计算方式, ...) -> 平滑异同移动平均线
+///      — 计算方式: "收盘价"/"高"/"低"/"开盘价"
+///   增量计算(前一个MACD, 当前收盘价, 当前时间) -> 平滑异同移动平均线
+///      — 基于前一根的 EMA 状态增量更新，用于流式计算
+///   增量计算_K线(前一个MACD, 当前K线, 计算方式) -> 平滑异同移动平均线
 #[pyclass(name = "平滑异同移动平均线")]
 #[derive(Clone)]
 pub struct 平滑异同移动平均线Py {
@@ -183,6 +199,21 @@ impl 平滑异同移动平均线Py {
 
 // ========== 相对强弱指数 ==========
 
+/// RSI 技术指标 — 相对强弱指数（Wilder SMA 平滑）。
+///
+/// 属性:
+///   时间戳: str / 收盘价: float / 周期: int / 超买阈值: float / 超卖阈值: float
+///   RSI: float|None — 当前 RSI 值
+///   RSI_SMA: float|None — RSI 的 SMA 平滑值
+///   平均上涨: float|None / 平均下跌: float|None
+///   上涨幅度: float / 下跌幅度: float / 平滑系数: float
+///   RSI历史队列: list[float]
+///
+/// 方法（均为 classmethod，直接构造实例）:
+///   首次计算(初始收盘价, 初始时间, 周期=14, 超买阈值=70, 超卖阈值=30, RSI_SMA周期=None)
+///   首次计算_K线(k线, 计算方式, ...)
+///   增量计算(前一个RSI, 当前收盘价, 当前时间)
+///   增量计算_K线(前一个RSI, 当前K线, 计算方式)
 #[pyclass(name = "相对强弱指数")]
 #[derive(Clone)]
 pub struct 相对强弱指数Py {
@@ -344,6 +375,21 @@ impl 相对强弱指数Py {
 
 // ========== 随机指标 ==========
 
+/// KDJ 技术指标 — 随机指标（Stochastic Oscillator）。
+///
+/// 属性:
+///   时间戳: str / 最高价: float / 最低价: float / 收盘价: float
+///   N: int (RSV周期) / M1: int (K值平滑) / M2: int (D值平滑) / 超买阈值 / 超卖阈值
+///   RSV: float|None — 未成熟随机值
+///   K: float|None / D: float|None / J: float|None — KDJ 三线值
+///   历史最高价队列 / 历史最低价队列: list[float]
+///   前一个RSV / 前一个K / 前一个D: float|None
+///
+/// 方法（均为 classmethod，直接构造实例）:
+///   首次计算(最高价, 最低价, 收盘价, 时间, N=9, M1=3, M2=3, 超买=80, 超卖=20)
+///   首次计算_K线(k线, 计算方式, ...)
+///   增量计算(前一个KDJ, 最高价, 最低价, 收盘价, 时间)
+///   增量计算_K线(前一个KDJ, 当前K线, 计算方式)
 #[pyclass(name = "随机指标")]
 #[derive(Clone)]
 pub struct 随机指标Py {
@@ -543,6 +589,12 @@ impl 随机指标Py {
 
 // ========== 指标 (static namespace) ==========
 
+/// 指标 — 静态工具类，提供指标计算的辅助方法。
+///
+/// 方法:
+///   K线取值(k线, 指标计算方式) -> float (classmethod)
+///     根据计算方式从K线提取数值。
+///     计算方式: "收盘价" / "开盘价" / "高" / "低" / "均值" 等
 #[pyclass(name = "指标")]
 pub struct 指标Py;
 

chanlun-py/src/kline_py.rs

@@ -32,6 +32,25 @@ use crate::types_py::相对方向Py;
 
 // ========== K线 ==========
 
+/// 原始 K 线 — OHLCV 数据，可内嵌 MACD/RSI/KDJ 指标。
+///
+/// 属性（大部分可读写）:
+///   标识: str / 序号: int / 周期: int (秒) / 时间戳: int (Unix秒)
+///   高: float / 低: float / 开盘价: float / 收盘价: float / 成交量: float
+///   方向: 相对方向 (只读) — 根据开盘价vs收盘价判定
+///   MACD: 平滑异同移动平均线|None (只读)
+///   RSI: 相对强弱指数|None (只读)
+///   KDJ: 随机指标|None (只读)
+///
+/// 类方法:
+///   创建普K(标识, 时间戳, 开盘价, 最高价, 最低价, 收盘价, 成交量, 序号?, 周期?) -> K线
+///      — 快捷构造普通K线
+///   读取大端字节数组(bytes, 周期, 标识?) -> K线
+///      — 从大端字节序二进制数据反序列化（兼容 .dat/.nb 文件格式）
+///   保存到DAT文件(路径, K线序列) -> 写入 .dat 二进制文件
+///   获取MACD(K线序列, 计算方式, 快线周期?, 慢线周期?, 信号周期?) -> list[平滑异同移动平均线]
+///      — 对整个K线序列批量计算 MACD
+///   截取(序列, 起点K线, 终点K线) -> list — 按时间戳截取K线区间
 #[pyclass(name = "K线")]
 #[derive(Clone)]
 pub struct K线Py {
@@ -287,6 +306,23 @@ impl K线Py {
 
 // ========== 缠论K线 ==========
 
+/// 缠论K线 — 经包含处理后的标准化K线，有方向（向上/向下）、分型结构标记。
+///
+/// 属性 (只读):
+///   序号: int / 时间戳: int (Unix秒) / 高: float / 低: float / 周期: int / 标识: str
+///   方向: 相对方向 — K线运行方向（向上/向下）
+///   分型: 分型结构|None — 当前K线在分型中的角色
+///
+/// 类方法:
+///   时间戳对齐(缠K序列, 参照K线或时间戳) -> int
+///      — 在缠K序列中找到与参照最接近的时间戳
+///   创建缠K(普K, 指示器) -> 缠论K线
+///      — 从普通K线创建缠论K线
+///   兼并(缠K序列, 方向, 配置, 需要特定强度?) -> list[缠论K线]
+///      — 根据方向进行K线包含处理（合并）
+///   分析(缠K序列, 配置, 可以逆序包含?, 忽视顺序包含?, 可以逆序包含新?) -> (str, 分型|None)
+///      — 分析分型形成结果
+///   截取(序列, 起点分型, 终点分型) -> list — 截取分型间的缠K子序列
 #[pyclass(name = "缠论K线", unsendable)]
 #[derive(Clone)]
 pub struct 缠论K线Py {

chanlun-py/src/structure_py.rs

@@ -34,6 +34,19 @@ use crate::types_py::{分型结构Py, 相对方向Py, 缺口Py};
 
 // ========== 分型 ==========
 
+/// 分型 — 由左中右三根缠论K线构成的顶/底分型。
+///
+/// 属性 (只读):
+///   左: 缠论K线|None / 中: 缠论K线 / 右: 缠论K线|None
+///   结构: 分型结构 — 上/下/顶/底/散
+///   时间戳: int / 分型特征值: float / 强度: str
+///   关系组: (相对方向, 相对方向, 相对方向)|None — 左中、中右、左右的相对方向
+///   与MACD柱子分型匹配: bool|None — MACD 柱状图是否与分型结构一致
+///
+/// 类方法:
+///   判断分型(缠K序列, 索引, 配置) -> 分型|None — 在缠K序列中指定位置尝试创建分型
+///   从缠K序列中获取分型(缠K序列, 配置) -> list[分型] — 扫描全序列提取所有分型
+///   向序列中添加(分型序列, 新分型) — 维护分型序列的顺序一致性
 #[pyclass(name = "分型", unsendable)]
 #[derive(Clone)]
 pub struct 分型Py {
@@ -177,6 +190,34 @@ impl 分型Py {
 
 // ========== 虚线 ==========
 
+/// 虚线 — 笔/线段的通用数据结构，持有一组分型端点（文=起点分型, 武=终点分型）。
+///
+/// 属性 (只读):
+///   标识: str — "笔" / "线段" / "扩展线段" 等
+///   序号: int / 级别: int / 有效性: bool / 模式: str
+///   文: 分型 — 起点分型
+///   武: 分型 — 终点分型
+///   方向: 相对方向 — 根据文/武高低判定
+///   高: float (计算) / 低: float (计算)
+///   确认K线: 缠论K线|None / 前一缺口: 缺口|None
+///   前一结束位置: 虚线|None / 短路修正: bool
+///   基础序列: list[虚线] — 构成该虚线的子级虚线序列
+///   实_中枢序列: list[中枢] / 虚_中枢序列: list[中枢] / 合_中枢序列: list[中枢]
+///   笔序列: list[虚线] (计算) — 递归获取所有笔
+///
+/// 方法:
+///   之前是(其他虚线) -> bool — 判断当前虚线是否紧接在另一虚线之前
+///   之后是(其他虚线) -> bool — 判断当前虚线是否紧接在另一虚线之后
+///   获取普K序列(普K序列) -> list[K线] — 截取该虚线的原始K线范围
+///   获取缠K序列(缠K序列) -> list[缠论K线] — 截取该虚线的缠K范围
+///   获取数据文本() -> str
+///
+/// 类方法（算法辅助）:
+///   创建笔(序号, 标识, 文, 武, 级别) / 创建线段(...)
+///   缠K买卖点模式(缠K) / 买卖点配置匹配 / 买卖点任意匹配 / 买卖点全量匹配 / 买卖点相对匹配
+///   计算MACD柱子均值 / 武之全量MACD均值 / 武之MACD均值 / 武之MACD极值
+///   计算K线序列MACD趋向背驰 / 买卖意义 / 计算MACD柱子分段
+///   密集区域按间隔 / 统计MACD行为
 #[pyclass(name = "虚线", unsendable)]
 #[derive(Clone)]
 pub struct 虚线Py {
@@ -694,6 +735,23 @@ impl 虚线Py {
 
 // ========== 线段特征 ==========
 
+/// 线段特征 — 特征序列元素构成的集合，支持 list-like 索引访问。
+///
+/// 实现 __getitem__ / __len__ / __iter__，可像 list 一样遍历。
+///
+/// 属性 (只读):
+///   文: 分型 — 特征序列的起点分型
+///   武: 分型 — 特征序列的终点分型
+///   方向: 相对方向 / 高: float / 低: float
+///
+/// 方法:
+///   添加(虚线) — 向特征序列追加虚线元素
+///   删除(虚线) — 从特征序列移除虚线元素
+///
+/// 类方法:
+///   新建(序号, 文, 武, 基础序列?) -> 线段特征
+///   静态分析(虚线序列, 配置) -> 线段特征|None
+///   获取分型序列(虚线序列, 配置) -> list[线段特征]
 #[pyclass(name = "线段特征", unsendable)]
 #[derive(Clone)]
 pub struct 线段特征Py {
@@ -881,6 +939,11 @@ impl 线段特征Py {
 
 // ========== 特征分型 ==========
 
+/// 特征分型 — 线段特征序列中的分型节点。
+///
+/// 属性 (只读):
+///   左: 线段特征|None / 中: 线段特征 / 右: 线段特征|None
+///   结构: 分型结构 — 顶/底分型判定结果
 #[pyclass(name = "特征分型", unsendable)]
 #[derive(Clone)]
 pub struct 特征分型Py {

chanlun-py/src/types_py.rs

@@ -27,6 +27,16 @@ use pyo3::types::PyType;
 
 // ========== 买卖点类型 ==========
 
+/// 买卖点类型 — 缠论的三类买卖点及扩展类型。
+///
+/// 类属性（可作为常量直接使用）:
+///   一买, 一卖, 二买, 二卖, 三买, 三卖
+///   T1买, T1卖, T1P买, T1P卖, T2买, T2卖,
+///   T2S买, T2S卖, T3A买, T3A卖, T3B买, T3B卖
+///
+/// 属性:
+///   是买点: bool — 是否为买入类型
+///   是卖点: bool — 是否为卖出类型
 #[pyclass(name = "买卖点类型")]
 #[derive(Clone)]
 pub struct 买卖点类型Py {
@@ -73,6 +83,24 @@ impl 买卖点类型Py {
 
 // ========== 相对方向 ==========
 
+/// 相对方向 — 描述两个K线/分型之间相对位置关系的枚举。
+///
+/// 用于包含处理、分型判定、中枢重叠检测等。不代表绝对涨跌方向，
+/// 而是描述前后两个价格区间的包含/位置关系。
+///
+/// 类属性（可作为常量直接使用）:
+///   向上, 向下, 向上缺口, 向下缺口, 衔接向上, 衔接向下, 顺, 逆, 同
+///
+/// 属性:
+///   是否向上: bool — 当前方向是否归类为"向上"（含衔接向上）
+///   是否向下: bool — 当前方向是否归类为"向下"（含衔接向下）
+///   是否包含: bool — 前后区间是否存在包含关系
+///   是否缺口: bool — 前后区间之间是否存在缺口
+///   是否衔接: bool — 前后区间是否恰好衔接
+///
+/// 方法:
+///   翻转() -> 相对方向 — 返回方向的对立面（向上↔向下, 缺口↔反向缺口）
+///   分析(前高, 前低, 后高, 后低) -> 相对方向 (classmethod) — 根据价格区间判断方向
 #[pyclass(name = "相对方向")]
 #[derive(Clone)]
 pub struct 相对方向Py {
@@ -100,6 +128,7 @@ impl 相对方向Py {
         self.inner as u64
     }
 
+    /// 返回方向的对立面（向上↔向下, 缺口↔反向缺口, 衔接↔反向衔接）。
     fn 翻转(&self) -> Self {
         Self {
             inner: self.inner.翻转(),
@@ -131,6 +160,15 @@ impl 相对方向Py {
         self.inner.是否衔接()
     }
 
+    /// 根据前后价格区间的OHLC值分析方向关系。
+    ///
+    /// 参数:
+    ///   前高: float — 前一个区间的高点
+    ///   前低: float — 前一个区间的低点
+    ///   后高: float — 后一个区间的高点
+    ///   后低: float — 后一个区间的低点
+    /// 返回:
+    ///   相对方向 — 两个区间的相对位置关系
     #[classmethod]
     fn 分析(
         _cls: &Bound<'_, PyType>, 前高: f64, 前低: f64, 后高: f64, 后低: f64
@@ -143,6 +181,18 @@ impl 相对方向Py {
 
 // ========== 分型结构 ==========
 
+/// 分型结构 — 描述三根K线构成的顶底分型形态。
+///
+/// 类属性（可作为常量直接使用）:
+///   上 — 向上结构（两根K线均向上）
+///   下 — 向下结构（两根K线均向下）
+///   顶 — 顶分型（先上后下）
+///   底 — 底分型（先下后上）
+///   散 — 松散结构（逆序包含）
+///
+/// 方法:
+///   分析(左, 中, 右, 可以逆序包含?, 忽视顺序包含?) -> 分型结构|None (classmethod)
+///      — 根据三根K线的高低价分析分型结构
 #[pyclass(name = "分型结构")]
 #[derive(Clone)]
 pub struct 分型结构Py {
@@ -170,6 +220,16 @@ impl 分型结构Py {
         self.inner as u64
     }
 
+    /// 根据左中右三根K线的高/低价分析分型结构。
+    ///
+    /// 参数:
+    ///   左: object — 左侧K线，需有 高/低 属性
+    ///   中: object — 中间K线，需有 高/低 属性
+    ///   右: object — 右侧K线，需有 高/低 属性
+    ///   可以逆序包含: bool — 是否允许逆序包含判定
+    ///   忽视顺序包含: bool — 是否忽略顺序包含（K线合并后可能产生）
+    /// 返回:
+    ///   分型结构 或 None — 无法判定时返回 None
     #[classmethod]
     fn 分析(
         _cls: &Bound<'_, PyType>,
@@ -233,6 +293,15 @@ impl 分型结构Py {
 
 // ========== 缺口 ==========
 
+/// 缺口 — 描述价格区间之间的缺口（未重叠部分）。
+///
+/// 属性:
+///   高: float — 缺口上沿价格（可读写）
+///   低: float — 缺口下沿价格（可读写）
+///
+/// 方法:
+///   居中截取区间(起点, 终点, 比例=0.15) -> 缺口|None (classmethod)
+///     — 在两个价格之间截取中间区域作为缺口
 #[pyclass(name = "缺口")]
 #[derive(Clone)]
 pub struct 缺口Py {
@@ -285,6 +354,14 @@ impl 缺口Py {
         self.inner.低 = value;
     }
 
+    /// 在两个价格之间截取中间区域作为缺口。
+    ///
+    /// 参数:
+    ///   起点: float — 起始价格
+    ///   终点: float — 终止价格
+    ///   比例: float — 截取区间占总区间的比例（默认 0.15）
+    /// 返回:
+    ///   缺口 或 None — 起点==终点时返回 None
     #[classmethod]
     fn 居中截取区间(
         _cls: &Bound<'_, PyType>,
@@ -380,6 +457,13 @@ pub fn register(m: &Bound<'_, PyModule>) -> PyResult<()> {
 
 // ========== Module-level functions ==========
 
+/// 将多种类型的时间表示转换为 Unix 时间戳（秒）。
+///
+/// 支持输入类型:
+///   int — 直接返回
+///   float — 取整数部分
+///   str — ISO 8601 ("2024-10-15T16:45:00") 或 "YYYY-MM-DD HH:MM:SS" 或 "YYYY-MM-DD"
+///   datetime — 调用其 .timestamp() 方法
 #[pyfunction]
 fn 转化为时间戳(ts: &Bound<'_, PyAny>) -> PyResult<i64> {
     // Try int first