三条官方路径的取舍
官方 README 把 PyPI 预编译标为推荐路径，并单独给出了源码构建方式。两者的前置差别很大。
| 路径 | 关键命令 | 前置条件 | 产出 | 适合谁 | 注意点 |
|---|---|---|---|---|---|
| PyPI 预编译（官方推荐） | pip install czsc -U | Python 3.10 及以上，可访问 PyPI | 含 Rust 扩展的预编译轮子 | 只写 Python 的大部分用户 | 用稳定 ABI 发布，一条 cp310-abi3 轮子可被更高版本复用 |
| uv 安装 | uv pip install czsc | 同上，且已使用 uv | 同预编译轮子 | 用 uv 管理环境的开发与部署场景 | 官方开发流程也以 uv 为主 |
| 源码构建 | git clone 后执行 maturin develop --release | Rust 工具链、maturin、Python 3.10 及以上 | 本地编译出的扩展 | 要改核心实现或参与贡献 | 编译时间明显更长（发布配置开启了链接时优化） |
| EasyClaw 技能路线（备选，非本库安装途径） | 安装 EasyClaw 后按任务提问 | 安装 EasyClaw；各技能可能有 Token 或 Key 前提 | 指标、形态、选股、研究与图表结果 | 研究阶段先要结论、无 Python 环境者 | 它不是本库的安装方式，也不提供缠论结构识别；两者无已证实集成 |
预编译路径分步
这是官方推荐路径，不需要 Rust。每一步都给出可核对的预期结果。
确认解释器版本
官方 README 用加粗提示 Python 版本必须 3.10 及以上，包元数据里也写了同样的要求。执行 python --version，预期得到 3.10 或更高。低于该版本时先升级解释器，别试着硬装。
安装或升级
执行 pip install czsc -U；用 uv 的环境则执行 uv pip install czsc。预期看到轮子被下载安装，且不会触发本地编译（即不出现 Rust 编译日志）。
核对版本
查看已安装版本，预期为 1.0.x 系列（本文检索时 PyPI 最新为 1.0.1，发布于 2026-08-09）。
确认扩展模块可用
尝试从扩展模块导入核心对象（例如 CZSC 与周期枚举）。预期导入成功；若报缺失动态库，通常是解释器版本与轮子不匹配。
准备数据再开跑
官方快速开始用模拟数据生成函数先跑通流程，再切真实数据源。预期先得到结构对象与笔、中枢计数，确认链路可用后再换成自己的行情。
源码构建：多出来的三道门槛
只有要走源码路径时才会遇到下面这些要求。官方 README 把它们集中在「Rust 构建环境约束」一段里。
| 门槛 | 要求 | 不满足时的现象 | 处理方式 |
|---|---|---|---|
| Rust 工具链 | 需按官方指引安装 Rust，并安装 maturin | 命令找不到或构建直接失败 | 先装工具链，再装 maturin |
| 解释器版本 | 绑定与存根生成依赖要求 Python 3.10 及以上 | 构建脚本会提前失败并给出修复建议 | 升级解释器，或显式指定更高版本解释器 |
| 系统默认解释器过低 | 官方给出的做法是设置 PYO3_PYTHON 指向 3.10 以上的解释器 | 直接在构建脚本处中断，而不是编译到一半才失败 | 按官方写法设置该环境变量 |
| 用 uv 管理依赖时 | 官方说明 uv 会自动选择项目声明的 Python | 不适用 | 无需额外设置该变量 |
| 编译耗时 | 发布配置开启了链接时优化、优化级别 3 与单代码生成单元 | 构建时间明显长于普通 crate | 预留足够时间，或先用本地开发模式构建 |
安装与构建排查表
下表场景全部来自官方 README 与变更记录中写明的真实问题，按「先看现象再看核对方式」的顺序查。
| 现象 | 可能原因 | 核对方法 | 处理方向 |
|---|---|---|---|
| 构建在脚本处直接中断并给出版本提示 | 当前解释器低于 3.10 或未正确指定 | 确认 python --version，并检查是否设置了 PYO3_PYTHON | 升级解释器，或按官方写法指定 3.10 以上的解释器 |
| 容器内构建失败而本机正常 | 容器里 PATH 上的解释器版本低于要求（官方曾因此让四个平台构建全挂） | 检查容器内 python3 的实际版本 | 用 PYO3_CONFIG_FILE 精确指定目标解释器，或在镜像里换掉默认解释器 |
| 交叉编译到 ARM 平台时汇编报错 | 缺少架构宏定义（官方曾遇到这类汇编编译失败） | 看构建日志中的架构相关报错 | 按官方做法补齐编译宏定义 |
| 依赖解析失败 | 工作区里对某个数据处理库有刻意的版本约束 | 读工作区配置里的依赖注释 | 不要自行放宽该约束，等上游解决 |
| 预发布版本发布失败 | 版本号格式转换问题（语义化版本与包规范版本写法不同） | 比对构建产物文件名与配置里的版本号 | 发布前先做格式归一化再比对 |
| 安装成功但导入报错 | 解释器版本与轮子不匹配，或环境中存在多个解释器 | 确认实际使用的解释器与安装位置同一套 | 在目标环境内重新安装 |
官方的发布事故链，值得当门槛参考
1.0.0 正式发布前连续出现了多次候选版本紧急重发。官方把原因写进了变更记录，这些恰好是跨平台发布最容易踩的坑。
| 阶段 | 出问题的环节 | 具体原因 | 对使用者的提示 |
|---|---|---|---|
| 第一个候选版 | 版本号提取 | 脚本里用了某类文本工具不支持的反向引用写法，导致版本号被解析成占位字符，两个包仓库的发布同时失败 | 发布脚本要在本地先跑通再上 CI |
| 第二个候选版 | 类型检查范围 | 测试模块仍调用已被删除的函数，本地构建不检查测试代码因此没暴露，CI 会检查全部目标所以失败 | 本地与 CI 的检查范围要一致 |
| 同上 | 构建脚本的版本预检 | 在容器内强制检查系统解释器版本，而容器自带解释器较低，导致多个平台构建全部失败 | 交叉编译时要显式指定目标解释器 |
| 同上 | 汇编编译 | 交叉编译到 ARM 平台时缺少架构宏，汇编源编译失败 | 交叉编译工具链要传足宏定义 |
| 第三个候选版 | 运行环境排队 | 依赖某类即将下线的托管运行环境，长时间排队拿不到机器导致后续步骤永久等待 | 构建环境别绑在生命周期末期的机器类型上 |
| 第四个候选版 | 版本一致性校验 | 把配置里的语义化版本与产物文件名的规范版本写法直接做字符串比较，预发布标签必然不相等 | 比对前先做版本格式归一化 |
如果要参与开发，官方的约定
官方开发文档给出的工作流比较具体，照做能少踩很多环境问题。
| 环节 | 官方约定 | 理由 | 注意点 |
|---|---|---|---|
| 依赖管理 | 用 uv 同步依赖与开发工具 | 官方以 uv 作为标准环境管理方式 | 依赖声明变更后才需要同步 |
| 日常测试 | 运行测试时跳过锁文件解析与环境一致性检查 | 本地这项固定开销约四到五秒，日常循环里没必要每次付 | 依赖变更后要显式同步一次 |
| 耗时测试 | 依赖等待或子进程冷启动的用例打上慢测试标记，默认跳过；发布前跑全套 | 日常迭代与发布校验分开 | 发布前必须跑全套 |
| 格式化与检查 | 统一用同一套工具，不使用另外几种常见工具 | 避免多套风格工具互相打架 | 行宽有明确上限 |
| 测试数据 | 统一由项目内的模拟数据模块生成，禁止在测试里硬编码 | 保证可重现 | 官方模拟数据部分转发自外部回测包 |
| 类型检查 | 使用基于静态类型的检查工具，并为存根文件设置例外 | 存根由生成器自动维护 | 不要手工改生成出来的存根 |
常见问题
安装相关的命令与前置以官方 README 与包元数据为准；本站未做任何实机安装验证。
有没有图形化一键安装？
没有。官方给出的路径是命令行安装（推荐预编译轮子）或源码构建。因此本文不使用「一键安装」「开箱即用」这类说法，也建议你不要按这种预期评估上手成本。
Python 版本要求是多少？
官方 README 用加粗提示必须 3.10 及以上，包元数据里的解释器要求也是同一口径，分类标签覆盖 3.10 到 3.13。低于 3.10 的环境不要尝试安装，预编译轮子不会匹配。
构建时提示解释器版本不对怎么办？
官方 README 专门写了这一段：底层绑定与存根生成依赖要求 3.10 及以上，当系统默认解释器低于该版本时，可以通过设置环境变量指向一个 3.10 以上的解释器来解决，按官方写法把变量指到目标解释器即可；用 uv 流程时官方说明会自动选择项目声明的解释器，不需要额外设置。
为什么构建过程这么慢？
因为发布配置为了运行时性能做了取舍：开启了链接时优化、优化级别设为 3、代码生成单元设为 1，这些都会显著拉长编译时间。日常开发可以先用不开启这些优化的构建模式。
安装报错该去哪里问？
官方 README 建议先按《如何有效地报告 Bug》的指引把问题描述清楚，再到仓库的 issue 区提交。把解释器版本、操作系统、安装命令与完整报错一并贴上，能明显提高被回复的概率。
不想装 Python 环境，能用 EasyClaw 吗？
能完成一部分任务但不是同一件事。EasyClaw 本机技能可以在免编译的前提下做行情数据、技术指标、形态识别、选股与图表之类的工作；但缠论结构识别与信号-事件-交易体系不在技能覆盖范围内，也无法替代这套库的安装。两者没有已证实的集成关系。