WonderTrader / Installation & wtpy
wondertrader 安装教程：三条官方路径、前置条件与 wtpy 模块清单
官方没有图形化一键安装。可验证的路径有三条：只写 Python 就装 wtpy 子框架；要改核心就编译源码；想直接看运行器就用仓库里的预编译产物。三条路径的前置条件差别很大，本文按官方术语逐条列出，并给出安装后你会拿到哪些模块。
三条安装路径对照
官方在 README 与官方文档里给出的可验证路径就是这三条，前置条件与产出各不同。
| 路径 | 关键命令 | 前置条件 | 安装后你会拿到什么 | 适合谁 | 注意点 |
|---|---|---|---|---|---|
| pip 安装 wtpy（官方推荐入口） | pip install wtpy --upgrade，用 pip show wtpy 查版本 | Python 3.8 及以上；可访问 PyPI | Python 子框架、包装层、监控服务与内置的 C++ 二进制 | 只想用 Python 写策略、跑回测的人 | 官方 README 原文写「wtpy 可以直接在 python3.8 以上的版本安装」；UFT 引擎不在此路径覆盖范围内 |
| 源码编译 | 克隆仓库后执行构建脚本（Linux 用仓库内构建脚本，Windows 用复制二进制脚本） | C++ 构建工具链；官方 Docker 目录另提供编译环境镜像定义 | 自行编译出的引擎与各运行器二进制 | 要改核心、要接自研接口、要审计代码的人 | 仓库 docker 目录含两份 Dockerfile 与一份依赖压缩包，可用容器统一环境 |
| dist 预编译运行器 | 直接使用仓库 dist 目录下的运行器 | 随产物而定的运行库 | CTA / HFT / UFT 运行器、回测运行器、行情加载器、通用配置与数据目录 | 想先跑通流程、暂不编译的人 | dist 目录条目存在是事实，但其可用性与依赖未在本站实机验证 |
| EasyClaw 技能路线（备选，非本框架安装途径） | 安装 EasyClaw 后按任务提问 | 安装 EasyClaw；各技能可能有 Token/Key/网络前提 | 数据、研究、模拟交易类技能 | 研究阶段先要结论、无柜台条件的人 | 它不是本框架的安装方式，也不提供本框架的引擎与实盘链路；两者无已证实集成 |
pip 路径分步：从安装到确认版本
这是官方文档「快速入门」给出的主路径，每一步都给了预期结果，便于自我核对。
确认 Python 版本
官方要求 3.8 及以上。执行
python --version，预期输出Python 3.8.x或更高。低于 3.8 时先升级解释器，不要试图用旧版本装上再补依赖。安装或升级 wtpy
执行
pip install wtpy --upgrade。预期看到 wtpy 及其依赖被安装或升级；内网环境可用官方文档提到的阿里云镜像地址。核对版本号
执行
pip show wtpy，预期输出中包含版本行。官方 PyPI 记录的最新版本为 0.9.9.3，要求 Python 3.8.0 及以上。选定要跑的 demo
官方在演示目录中按场景提供了多组示例：期货策略实盘、期货策略回测、股票策略实盘、股票策略回测、期货数据组件、股票数据组件、期货高频实盘、期货选股回测等。挑一个最接近你场景的，不要从零搭目录。
改配置并首次运行
打开该 demo 的配置文件，确认基础文件路径（品种、合约、节假日、主力映射、交易时间模板、佣金）与数据存储路径都指向存在的目录，然后运行入口脚本。预期生成日志目录与输出目录。
安装后拿到的模块：wtpy 文件职责
下面这份清单来自 wtpy 官方 README 的模块说明，按官方划分的三个子模块整理，方便你判断该改哪一层。
| 子模块 | 文件 / 组件 | 职责 | 你要改它的场景 | 注意点 |
|---|---|---|---|---|
| apps | 回测分析模块 | 读取回测输出，计算各项回测指标并输出到 Excel | 要自定义绩效指标口径 | 官方文档注明该模块目前仅适用 CTA 策略 |
| apps | CTA 参数优化器 | 用多进程并发回测，汇总各项交易指标输出到 csv | 做参数寻优 | 官方 WtStudio 侧注明优化算法目前只提供遍历算法 |
| apps | 主力换月辅助模块 | 确定主力与次主力合约换月规则，可从数据组件收盘生成的快照解析，也支持爬取交易所页面 | 维护主力合约规则 | 官方标注爬取方式不稳定，优先用收盘快照 |
| apps | 数据辅助模块 | 按统一格式拉取并落地历史数据，封装多个数据源差异 | 接入自己的数据源 | 官方已封装的数据源见数据落地页；平台层面不做财务数据标准化 |
| wrapper | 回测包装、交易引擎包装、数据组件包装 | 与 C++ 核心模块对接的接口层 | 排查 Python 与 C++ 的边界问题 | 参数与返回值命名是排错的首要线索 |
| wrapper | 数据转换辅助 | 在自有数据结构与框架内部格式之间互转，并可重采样 K 线 | 把已有 csv 或数据库数据导入 | 转换涉及定长结构体，字段顺序错位很难发现 |
| wrapper | 数据直读接口 | 让 Python 侧直接随机访问数据组件落地的行情 | 做向量化研究而不是事件回放 | 它与事件驱动回测是两个使用习惯，别混在一段代码里 |
| wrapper | 独立执行模块对接 | 与独立执行器入口模块对接 | 做纯算法交易执行 | 执行侧与策略侧解耦，需自己定义目标头寸来源 |
| monitor | 监控服务核心 | 提供 http 接口与推送服务，整合数据管理、调度、事件转发与回测管理 | 自建控制台或改权限 | 默认口令属官方文档公开的初始值，部署后必须改 |
| monitor | 调度与数据管理组件 | 自动调度进程、监控运行状态；读取并缓存组合数据 | 调整调度策略与守护间隔 | 进程守护适合 7×24 常驻任务，交易组合按交易日调度更合适 |
官方 demo 名册：照场景挑一个
官方演示目录里有二十多个示例。以下按用途分组列出常用的部分，名称取自仓库演示目录的实际条目。
| demo 目录 | 用途 | 覆盖的引擎 / 组件 | 适合什么时候跑 | 注意点 |
|---|---|---|---|---|
| 期货策略回测 | 用历史数据回放一个期货 CTA 策略 | CTA + 回测引擎 | 第一次跑通回测 | 配置里要指定基础文件与数据存储模式 |
| 股票策略回测 | 股票标的的 CTA 回测 | CTA + 回测引擎 | 验证股票侧逻辑 | 股票要按复权口径取数，代码规则与期货不同 |
| 期货策略实盘 | 连接柜台做期货实盘或仿真 | CTA + 交易适配 | 回测通过后准备上实盘 | 需先配好行情与交易通道，且数据组件要先启动 |
| 股票策略实盘 | 股票侧实盘或仿真 | CTA + 股票交易适配 | 验证股票实盘链路 | 注意交易单位与不可做空的约束 |
| 期货 / 股票数据组件 | 实时录制行情、收盘转历史 | 数据组件 | 实盘前必须先跑起来 | 落地目录与广播端口要和交易进程配置一致 |
| 期货高频实盘 | 高频策略接入 | HFT | 有低延迟需求时 | 高频路径对字符串与内存分配更敏感 |
| 期货选股回测 | 异步选股策略回测 | SEL | 多标的筛选类策略 | 重算按调度周期触发，不是逐 K 线 |
| 参数优化器 | 批量遍历参数并汇总结果 | 优化器 | 基础参数确定后 | 并行进程数与 CPU 核心数匹配更稳 |
| 合约加载器 | 从柜台拉取品种与合约列表 | 加载器 | 每次合约换月或新品种上市 | 官方提示新增品种需同步维护映射文件，否则引擎初始化会报错 |
| 数据伺服 / 回测查看器 | 随机访问落地数据、图形化看回测信号 | 数据伺服 + 查看器 | 研究取数与复盘 | 查看器依赖数据伺服提供的基础数据访问能力 |
前置条件与版本矩阵
先把版本与平台前提钉死，再决定要不要动手。下表是本站在 2026-09-16 从官方渠道核验到的状态。
| 项 | 要求 / 当前状态 | 来源 | 适用场景 | 注意点 |
|---|---|---|---|---|
| Python 版本 | 3.8 及以上 | 官方 README 与 PyPI 元数据 | pip 路径 | 低版本装上后依赖冲突更难排查 |
| wtpy 版本 | PyPI 最新 0.9.9.3 | PyPI JSON 接口（2026-09-16） | pip 路径 | 该版本的 wheel 上传时间较早，升级前先确认与核心版本的对应关系 |
| 核心版本 | 仓库 Tag 最新为 v0.9.9 | 仓库 Tag 列表（2026-09-16） | 源码编译路径 | wtpy 更新日志记录了每个版本对应的核心日期，升级时两边要对齐 |
| 平台 | Windows 与 Linux | README 徽章与更新日志 | 全部路径 | 两平台的时间函数、编码与二进制格式都不同，跨平台迁移优先用容器 |
| 许可证 | MIT | 仓库 LICENSE 与 GitHub API | 全部路径 | 商用前仍建议由法务确认自身合规要求 |
| 数据库（可选） | 支持用 MySQL 存储历史数据 | 官方文档与 README | 要搭自有投研库 | 实盘默认仍是自有文件存储，数据库是扩展手段 |
安装与首次运行的排查表
以下场景来自官方更新日志与文档里反复出现的适配问题，按「先看现象再看核对方法」的顺序查。
| 现象 | 可能原因 | 核对方法 | 处理方向 |
|---|---|---|---|
| 装完 import 报错或版本对不上 | Python 版本低于要求，或 wtpy 与核心二进制版本不匹配 | 执行版本查询命令，对照 PyPI 与仓库 Tag | 升级解释器；按更新日志把两边版本对齐 |
| Windows 控制台中文日志乱码 | 编码处理未适配当前系统 | 看日志里中文是否可读 | 官方在多个版本里修过编码适配，升级到较新小版本优先 |
| 引擎初始化直接报错 | 基础文件里的品种或合约缺失，或新增品种未同步维护映射文件 | 确认品种与合约文件已更新，且映射文件里有对应键 | 官方提示：新增品种必须更新映射文件，否则引擎初始化会失败 |
| 回测跑起来但没有数据 | 数据存储模式与数据目录配置不一致，或历史文件不存在 | 检查存储模式与数据路径，确认目录里有对应文件 | 先用官方 demo 附带的样例数据跑通，再换自己的数据 |
| Linux 下启动失败 | 平台相关的启动参数或依赖缺失 | 对照更新日志里 Linux 相关修复条目 | 优先用官方 Docker 目录的镜像定义统一环境 |
| 监控服务打开但组合列表为空 | 部署根目录配置错误，或数据目录没有组合数据 | 核对监控服务启动时的部署目录参数 | 先确认交易进程已在该目录下写入组合数据 |
常见问题
安装相关的问题一律以官方 README、官方文档与官方更新日志为准；本站未做任何实机安装验证。
有图形化一键安装吗？
没有。官方 README 给出的是 pip install wtpy --upgrade 这类命令行安装方式，源码路径需要自己构建，仓库另提供预编译产物目录。实盘还要额外准备行情与交易账号。因此本文不使用「一键安装」「开箱即用」这类说法，也建议你不要按这种预期评估上手成本。
只装 wtpy 就够用了吗？
看你要做什么。写 Python 策略、跑回测、起监控服务，wtpy 路径覆盖得住。但如果你的目标是 UFT 极速引擎，就不在这一路径里，因为该引擎全部由 C++ 实现且不向应用层提供接口。要改核心逻辑、对接自研接口或审计代码，也还是要走源码编译。
Windows 和 Linux 该选哪个？
官方两个平台都支持，且历史上针对两者分别做过多次适配修正，比如时间函数开销差异、编码处理、二进制格式等。如果你的策略对延迟敏感，官方《延迟优化日记》里记录过两个平台下时间函数开销不同的现象。跨平台需求多的话，先看仓库 docker 目录里的镜像定义，用容器统一环境比逐条排查便宜。
装了 wtpy 之后，怎么确认装的是哪个版本？
官方文档给的命令是 pip show wtpy。PyPI 上记录的最新版本为 0.9.9.3，要求 Python 3.8.0 及以上。需要注意 wtpy 与 C++ 核心是两套版本号体系，官方 wtpy 的更新日志里逐条记录了每个 wtpy 版本对应的核心发布日期，升级时建议两边一起对齐看。
能不能直接用仓库里的预编译产物跑？
仓库确实有预编译产物目录，其中的条目包括 CTA、HFT、UFT 三个运行器、回测运行器、行情加载器、通用配置与数据目录。这是仓库里客观存在的目录条目，但本站没有实机验证这些产物在你环境下的可用性与依赖完整性，具体以官方发布说明为准。
安装这件事，能用 EasyClaw 跳过吗？
不能把这理解成同一件事。EasyClaw 是本机技能路线的软件，装好后可用行情数据、技术分析、选股与研究回测类技能，但它不是本框架的安装方式，也不提供本框架的引擎与实盘链路。如果你想先做研究、暂时不搭环境，可以先走 EasyClaw 路线，之后再决定要不要自建；两者之间没有已证实的集成关系。