chan-lun-core

缠论结构识别与理论辅助计算库。输入单标的、单周期的行情或结构序列， 输出分型、笔、线段、中枢、背驰、买卖点，以及多级分解和辅助状态。 算法用 Python 实现，第三方运行依赖只有 numpy 与 pandas；MACD 内置计算。

本库维护算法、公开契约、包测试及仓库验收资产。调用方负责行情获取、交易日历、 复权、标的和周期管理、策略调度、组合风控与下单。跨级别和板块接口需要调用方 提供多组已对齐的输入；理论级别由结构关系和输入声明确定，不按分钟周期自动映射。

阅读入口

下列链接指向仓库当前主干文档，安装版本及升级差异按版本记录核对。

安装

安装示例固定本版 1.0.1；发行产物可用性与升级差异按版本记录核对。 使用将要运行程序的解释器安装，固定版本便于复现：

python -m pip install 'chan-lun-core==1.0.1'
python -c "import chan; print(chan.__version__); print(chan.__file__)"

发行名与导入名不同。安装后的包应来自预期环境，工作区中的 chan.py 或同名 目录可能遮蔽它。Notebook 安装后若此前已导入过包，应重启内核再核对。 聚宽、离线 wheel 安装和导入诊断见安装指南。

运行依赖下限与现代开发依赖分别管理。旧 Python 环境优先安装已构建的 wheel； requirements-dev.txt 用于维护和构建，不用于升级平台内置环境。源码版本相同 不代表提交或发行产物相同，工程维护和发布记录分别核验。

快速开始

下面生成单标的、单周期的合成行情，无需行情账号，复制后即可运行：

import json
import math
from datetime import datetime, timedelta

import pandas as pd
from chan import normalize_bars, analyze_bars

closes = [20.0 + 3.0 * math.sin(i / 6.0) + i / 80.0 for i in range(160)]
df = pd.DataFrame({
    "open": closes,
    "close": closes,
    "high": [price + 0.3 for price in closes],
    "low": [price - 0.3 for price in closes],
    "volume": [1000.0] * len(closes),
}, index=[datetime(2025, 1, 1) + timedelta(days=i) for i in range(160)])

bars = normalize_bars(df)
result = analyze_bars(bars)
summary = {
    "as_of": str(result.as_of),
    "fxs": len(result.fxs),
    "bis": len(result.bis),
    "xds": len(result.xds),
    "bi_zss": len(result.bi_zss),
    "xd_zss": len(result.xd_zss),
    "buy_points": len(result.buy_points),
    "sell_points": len(result.sell_points),
}
print(json.dumps(summary, ensure_ascii=False, indent=2))
snapshot = result.to_dict()
json_text = json.dumps(snapshot, ensure_ascii=False, allow_nan=False)

按当前默认参数，摘要为：

{
  "as_of": "2025-06-09 00:00:00",
  "fxs": 8,
  "bis": 7,
  "xds": 1,
  "bi_zss": 1,
  "xd_zss": 0,
  "buy_points": 0,
  "sell_points": 0
}

这个输入识别出分型、笔和线段，笔级中枢与线段级中枢分别统计；买卖候选为空 是正常结果，不表示程序失败，也不证明价格安全或全部理论分支已经检查。 示例只用于说明调用与结果，不是行情案例或策略验证。

analyze_bars 组合基础识别链，默认采用 81 课笔标准。需要 106 课标准时用 analyze_bars(bars, bi_standard="106")。自定义 MACD、背驰、买卖点参数或使用 严格条件、递归、谱系及其他辅助模块时，按模块示例 另行组合；这些能力不会全部由 analyze_bars 自动执行。

输入与结果

标准输入是时间严格递增、唯一的 dict 列表或元组，每条包含 dt/open/high/low/close/volume。OHLC 必须有限且严格为正，成交量有限且非负， 并满足 low <= open/close <= high。一个序列对应一个标的、一个周期及同一价格基准。

DataFrame 可先经 normalize_bars 映射列名、转数值并排序；它默认剔除 volume == 0 且 high == low 的行。该适配不代替行情校验。 analyze_bars 会校验输入；底层函数各有前提，直接组合时可先调用 validate_bars。重复时间、缺失值、复权、时区与停牌处理方式须由调用方明确。 完整规则见行情输入契约。

AnalysisResult 按级别保留结果：

结果字段不能重新绑定，内部列表、数组与结构对象仍可修改。每次批量计算独立 分配结果，AnalysisResult.to_dict() 生成独立的 JSON 可写快照。底层对象按各自 契约序列化，例如 NewBar.to_dict() 保留原时间类型，不能据此假定任意对象均可 直接 json.dumps。

空行情也是合法输入：

from chan import analyze_bars

empty = analyze_bars([])
assert empty.as_of is None
assert empty.bis == []
assert empty.buy_points == []

字段 None、空结果、条件否决与证据不足有不同含义。扫描入口还可返回 exclusions、skipped、conditions 和 completed_types，用于解释未产生点位的 原因；它们的范围见 API 与排错指南。

按输入选择入口

公开入口经 import chan 或 from chan import ... 使用；完整导出以 chan.__all__ 为准，字段与稳定性以 API 为准。

笔级简化买卖候选、已确认输入上的条件判定、严格结构判定和工程辅助状态分别 解释。将任意笔或线段包装为 ConfirmedMove，不能证明它是真实完成的次级走势。 confirmed 也须结合所属接口的条件、力度方法与证据理解，不能统一视为理论证明 或交易指令。输入、示例与模块边界见使用指南。

时间、回放与证据边界

结构位置、证据确认时间、行情可用时间分别记录。 分型中心、笔端点和点位 dt 表达结构位置；as_of 表达输入截止，并不证明末根 bar 已收盘。 XD.evidence_dt 是最后证据笔的端点，也不能当作实际行情确认时间。

历史计算先确定观察时点可见的输入，再计算结构。已经保证收盘的离线行情可以用：

from chan import analyze_at, replay_bars

# 复用快速开始的 bars；真实接入时由调用方保证相应时点的收盘与价格基准。
cutoff = bars[-1]["dt"]
current = analyze_at(bars, cutoff)
for observed in replay_bars(bars, observations=[cutoff]):
    print(observed.observed_dt, len(observed.changes))

盘中或存在数据延迟时，应提供收盘与实际到达时间，使用 analyze_available。调用方还须按相应观察 时刻截断跨周期输入，并使用当时可得的复权基准；库不下载行情或复权。

固定输入历史版本、固定观察时点时，视野之外的未来价格不应影响当前结果。 观察时点推进后，未完成尾部和候选允许修订或撤销；first_seen 只代表在给定 观察网格中首次出现。用全样本最终结果按端点时间过滤，无法还原历史可见状态。 回放规则与账本身份见时间指南。

当前使用边界包括：同侧多轮独立真实样本缺口、课 77 历史 OHLC 缺失和课 106 图文歧义、辅助模块的工程阈值，以及调用方对最低类型、级别和供应历史版本的 证明责任。接口实现、真实样本覆盖、平台可运行和策略有效性是不同结论。 当前理论能力与剩余缺口只在正式计划 §6 维护；分支证据和随版声明见验收记录。

项目结构与维护

本仓库独立开发和验收，采用 src 布局；也可由研究项目作为 Git 子模块引用。 仓库根的 src/chan/ 是可安装包，仓库本身不是运行时包目录。

.
├── pyproject.toml       # 包元数据、运行依赖与包发现配置
├── requirements-dev.txt # 现代开发与构建依赖
├── src/chan/           # 算法、数据对象、公开导出与运行时版本
├── tests/              # 自包含包测试；fixtures 为最小冻结输入与预期
├── tools/              # 包测试、诊断、产物检查与基准工具
├── docs/               # 用法、架构导航、正式计划与治理文档
├── validation/         # 仓库验收资产、资产测试与数据工具
└── .github/            # CI 与随版声明

算法与包测试分别以 src/chan/、tests/ 为真源；工程入口在 tools/，资产工具 在 validation/tools/。独立包开发不读取外层研究项目。研究集成与平台接线由 调用方另行验收，冻结脚本和历史产物保留各自版本。

在核心库仓库根准备现代开发环境后执行：

python -m pip install -r requirements-dev.txt
python tools/check_core.py                              # 自包含包测试
python tools/check_core.py --pattern test_contracts.py   # 文档示例与工程契约
python tools/check_core.py --scope validation            # 完整仓库资产验收
python tools/check_core.py --scope all                   # 两层合跑

包测试可从解包 sdist 执行；资产验收需要完整仓库，缺失输入或空测试集明确失败。 README 和使用指南的基础链、回放及独立辅助示例随契约测试执行。文档移动或示例 修改时，须同步示例定位和源码包内容，保持相同的执行验证。

CI 定义现代 Python 3.10 / 3.13、Python 3.6 旧依赖及仓库资产验收，并分别检查 wheel 与解包 sdist；某次提交是否通过，以该提交的运行记录为准。仓库历史结果见 验收索引，不把旧测试数量写成当前全量通过结论。

目录和文档职责见 docs/README.md。架构、原文核验、开发流程与 工程命令分别维护在 ARCHITECTURE、CONTRIBUTING、 AGENTS 与工具索引，README 不另维护开发规则或理论进度表。

版本与升级

1.x 的公开入口、字段、时间、身份及异常契约见 API。算法 修正需要固定输入与逐前缀差异证据；输入历史被修订或候选随新证据变化，按对应 输入版本和时间契约解释。升级前保留旧结果，按迁移指南逐项核对。

版本号在 pyproject.toml 与 src/chan/__init__.py 保持一致。工程治理按变更影响 纳入修订、次或主版本；只有内部维护的提交可暂不发布，已发布产物不覆盖。本地提交、标签、远端推送、CI、GitHub Release 和 PyPI 分别核验；已有标签保持原指向，新增阶段标签须有明确的交付或 复现价值，推送单独评估。版本事实见 CHANGELOG，历史收据保留当时记录。

许可证与使用责任

本项目采用 MIT 许可证。计算结果用于结构研究与辅助分析，不构成投资 建议；交易决策、风控与执行由调用方负责。