ptrade-sim

PTrade Python 策略 · 本地回测 · 原生数据链 · 可视化工作台

这是 ceke233/ptrade-sim 的公开 fork，由 JonePoon/ptrade-sim 维护本轮增量实现。保留上游作者与 MIT 许可证，不是全功能 PTrade 客户端，也不是把整个项目重写成 Rust。

使用指南 · 原生数据链 · Rust 索引与策略转换 · Windows 安装与发布 · 验收与基准 · 更新日志

能做什么

本地回测：分钟/日级调度，T+1、涨跌停、复权、佣金、印花税与滑点；读取既有 DuckDB 物理表。
PTrade API 边界：55 个注册项，保留策略需要的 pandas 返回值；完整实现、受限实现和占位项分开说明。
可选 Rust 分钟索引：精确、范围、批量定位；auto/python/rust 三后端，原生内存纳入统一 LRU 预算。
原生行情下载：独立 ptrade-fetch，TDX TCP、解码、并发限流、重试、不可变 Parquet shard、SHA-256 清单和成功水位。
原生增量入库：独立 ptrade-store，DuckDB 1.5.6，按实际业务主键更新/插入，校验与来源检查点在同一事务提交。
策略静态转换：CLI/看板生成 PTrade 单文件，冻结参数、局部模块与诊断；检查 Python 3.11 / 3.5 目标，不执行输入策略。
可视化工作台：运行列表、指标/曲线、成交、日志、源码/转换；数据页查看库/湖、预览计划、显式启动任务、进度和取消。

渐进 Rust 架构

TDX TCP ── Rust ptrade-fetch ── 不可变 Parquet + 清单/水位 ─┐
                                                         ├─ Rust ptrade-store ── DuckDB 1.5.6 物理库
独立 CNE SDK ── 参考数据 / active revision / hfq 适配器 ────┘                           │
                                                                                 ↓
                                                                  Polars / NumPy 列式数据
                                                                                 ↓
                                                     Rust MinuteIndex（可选）+ Python 策略 / API
                                                                                 ↓
                                                        Python 调度 / 撮合 / 账户 / 指标 / run 产物
                                                                                 ↓
                                                             FastAPI + Vue 3 可视化工作台

Rust 负责新增的索引、下载和入库算法。Python 继续负责控制层、策略执行、PTrade API、撮合/账户和显式 SDK 适配器。DuckDB 查询引擎本来是 C++，Polars 本来是 Rust；数据库格式和既有交易语义不因增加原生模块而改变。

组件	运行形态	构建/安装
主包	Python ≥3.10；本轮本地验收用 3.12	pyproject.toml，Hatch wheel
分钟索引	独立 PyO3 扩展，可不安装	native，maturin / abi3 wheel
行情下载	Rust 独立可执行文件	native-fetch，Cargo locked
DuckDB 入库	Rust 独立可执行文件，嵌入 1.5.6 引擎	native-store，Cargo locked
参考数据	独立已配置的 CNE SDK 环境	SDK 适配边界
前端	Vue 3 / TypeScript / Vite	web/package.json；Node 24、pnpm 11.8.0

界面预览

以下是真实浏览器中的合成 run 产物/数据目录，用于展示交互，不代表真实策略收益。数据页的原生工具 doctor 与只读计划真实执行；持久任务样本是合成保存状态，任务启动/取消交互另在明确 MOCK 后端验证。

运行列表与详情

PTrade 静态转换

通过时可复制/下载单文件和报告；阻塞时仍可查看诊断，不能下载被标为未通过的生产代码。

数据工作台与移动端

此图的三张合成库存表用于 UI 展示，不是完整回测契约库；partial 样本并非一次真实原生同步的运行结果。

手机数据页：390px 视口

回测结果页读取 run 产物；数据页不是“全部只读”。查询与计划预览只读，下载/入库/同步由明确的按钮或 CLI 命令启动。关闭看板不影响独立的回测进程；看板自己拥有的数据任务会在服务退出时取消并清理。

安装当前 fork

当前源码版本为 0.3.0。这个 fork 的 GitHub Release 和上游 PyPI 是独立发布渠道；本页新增能力以本仓库源码或对应 GitHub Release 附件为准，不把旧 PyPI 包视为本轮新增功能的发布。

Windows 源码安装

在准备存放项目的目录运行；不需要激活虚拟环境。

git clone https://github.com/JonePoon/ptrade-sim.git
Set-Location ptrade-sim
py -3.12 -m venv .venv
& ./.venv/Scripts/python.exe -m pip install --upgrade pip
& ./.venv/Scripts/python.exe -m pip install -e ".[duckdb,dashboard,perf]"
& ./.venv/Scripts/ptrade-sim.exe --version

预期最后输出 ptrade-sim 0.3.0。主包固定 duckdb==1.5.6；CNE SDK 使用另一环境，不让它的 DuckDB 依赖覆盖回测环境。

源码不携带构建好的前端。安装 Node 24 后构建：

npm install --global pnpm@11.8.0
pnpm --dir web install --frozen-lockfile
pnpm --dir web run build
$env:PTRADE_SIM_WEB_DIST = (Resolve-Path ./web/dist).Path

只使用回测/导出 CLI 时不需要 Node。安装发布 wheel、原生 ZIP 和独立索引 wheel 的完整命令见 Windows 安装与发布。

可选原生组件

编译全部原生组件使用 Rust stable ≥1.85.1 与 Windows MSVC C++ 构建工具；仅使用发布二进制无需 Rust。

# 分钟索引：独立安装，主包本身不触发 Rust 构建。
& ./.venv/Scripts/python.exe -m pip install ./native

# 下载与入库：直接运行 release locked 测试与构建。
foreach ($crate in @('native-fetch', 'native-store')) {
    cargo test --release --locked --manifest-path "$crate/Cargo.toml"
    if ($LASTEXITCODE -ne 0) { throw "原生测试失败：$crate" }
    cargo build --release --locked --manifest-path "$crate/Cargo.toml"
    if ($LASTEXITCODE -ne 0) { throw "原生构建失败：$crate" }
}

& ./native-fetch/target/release/ptrade-fetch.exe doctor
& ./native-store/target/release/ptrade-store.exe doctor
& ./.venv/Scripts/python.exe -c "from ptrade_sim.accelerator import backend_status; print(backend_status('rust'))"

下载器应报告原生能力；入库工具应报告 engine_version=v1.5.6；索引状态应为 effective=rust、available=True。构建、ABI 与错误条件见原生组件文档。

快速开始：回测

1. 准备物理库

引擎只读 DuckDB，不在回测时扫描 Parquet 视图。表/字段以数据契约为准。

必需表	用途
`ashare_calendar`	交易日历
`ashare_stock_basic`	证券基础、上市/退市日期
`ashare_1d_stock`	个股日线、前收、复权因子、历史状态
`ashare_1d_index`	基准指数日线
`ashare_1m_stock`	分钟回测行情；只跑 daily 可保留空表

另外五张可选契约表为 ashare_1m_index、ashare_1d_feature、ashare_index_weight、ashare_index_info_basic、ashare_l2_auction。缺可选数据会限制对应 API，不等于拥有完整财务/逐笔/盘口数据。

已有符合旧表布局的 Parquet 源可用 db build；CNE lake 使用新的 data ingest/sync，两种输入布局不混用。下面的旧布局命令假设源已放在本机 data/source：

& ./.venv/Scripts/ptrade-sim.exe db build --db ./data/quant.duckdb --data-dir ./data/source --start-year 2025 --end-year 2025
& ./.venv/Scripts/ptrade-sim.exe db verify --db ./data/quant.duckdb --contract-only --json
& ./.venv/Scripts/ptrade-sim.exe db verify --list-contract --json

日线/股票量单位为股，成交额为元，价格是未复权值。TDX 日线从手转换为股，TDX 分钟已经是股；指数未证实的量单位保留 unknown。详见数据单位、频率与 partial。

2. 运行完整示例

仓库提供可直接运行的示例策略与策略配置，包含完整动量排序、目标持仓和 T+1 检查，无需补充伪代码。示例使用 20 个交易日的回看窗口，库中应包含起始日期之前的相应历史。

& ./.venv/Scripts/ptrade-sim.exe backtest --strategy ./examples/demo_rotation --db-path ./data/quant.duckdb --start 2025-06-03 --end 2025-06-12 --frequency daily --no-dashboard

# 改为分钟周期，明确要求已安装的 Rust 索引。
& ./.venv/Scripts/ptrade-sim.exe backtest --strategy ./examples/demo_rotation --db-path ./data/quant.duckdb --start 2025-06-03 --end 2025-06-12 --frequency minute --accelerator rust --no-dashboard

默认输出为 backtest_results/<策略目录名>-<时间戳>/。配置可放在策略目录；机器级路径与缓存放在私有配置。分层、全部环境变量、撮合与输出字段见使用指南。

3. 打开看板

& ./.venv/Scripts/ptrade-sim.exe dashboard --root ./backtest_results --host 127.0.0.1 --port 8765

浏览器打开 http://127.0.0.1:8765。健康检查：

Invoke-RestMethod http://127.0.0.1:8765/api/ping

源码安装须完成前端构建；发布 wheel 应带有前端。查看结果不执行策略，列表/详情从结果目录读取。新增 run 在开始时冻结源码、参数、转换代码与报告，历史导出不依赖后来改动的原策略。

快速开始：数据计划与任务

数据配置和回测配置分离。公开数据模板中的相邻 cne_lake 路径只是兼容布局，独立安装可用 CLI 或自己的数据配置选择目标。

# 仅预览计划，不下载、不写库、不创建数据任务。
& ./.venv/Scripts/ptrade-sim.exe data plan --config ./data_config.example.json --lake ./data/demo-lake --db ./data/demo.duckdb --start 2025-06-03 --end 2025-06-03 --symbols "000001.SZ,600000.SH" --datasets "daily_bars,minute_bars,minute_bars_5m" --json

& ./.venv/Scripts/ptrade-sim.exe data status --config ./data_config.example.json --json
& ./.venv/Scripts/ptrade-sim.exe data jobs --output-dir ./backtest_results --json

计划中的 ready 只反映所需原生工具可启动，不承诺源覆盖完整或参考数据齐全。完整配置、fetch/ingest/sync/verify、HTTP 任务、取消与 SDK 参考刷新见原生数据链。

1m 和 5m 保持独立数据集、保留期、水位和覆盖报告；5m 不填入 1m 物理表。
回测调度有 241 个槽位，含 09:30；TDX 1m 源是 240 根结束标签，从 09:31 开始。下载器不会为了凑 241 根虚造竞价。
partial 与 succeeded 分开；默认 allow_partial=false，部分完成以非零退出，不推进完整窗口成功水位。
已有正式库/数据湖不因安装、计划预览或打开页面而重建；入库仅按实际输入业务键变更，不按缺失日期删除旧行情。

PTrade 单文件转换

不需要行情库，不执行策略。

& ./.venv/Scripts/ptrade-sim.exe export --strategy ./examples/demo_rotation --target-python 3.11 --output ./production/demo_rotation_ptrade.py --json
& ./.venv/Scripts/ptrade-sim.exe export --strategy ./examples/demo_rotation --target-python 3.11 --check --json

# 示例含 f-string，3.5 目标应给出 source_syntax 诊断并退出 4。
& ./.venv/Scripts/ptrade-sim.exe export --strategy ./examples/demo_rotation --target-python 3.5 --check --json

通过会生成 UTF-8/LF 单文件及同名 .manifest.json；阻塞时只输出报告。报告 validation=static_only：它证明已声明的静态检查通过，不等于已经在券商客户端执行。3.5 是目标语法检查，不会自动把所有现代 Python 特性降级。

API 支持边界

注册清单与 API 语义测试对齐。55 个注册项中包括受限项与占位项，不能解读为 55 个完整官方功能。

分组	数量	主要接口
环境与调度	11	`g/log/context/run_daily/get_frequency/get_strategy_params`
设置	9	`set_universe/set_benchmark/set_commission/set_slippage/set_limit_mode`
行情	5	`get_history/get_price/get_trend_data/get_snapshot/get_current_kline_count`
证券信息	18	`get_Ashares/get_stock_info/get_stock_status/get_trade_days/get_fundamentals/get_index_stocks`
交易	9	`order/order_value/order_target/order_target_value/cancel_order/get_orders/get_trades`
持仓	3	`get_position/get_positions/get_all_positions`

get_Ashares 是按历史日期判断的沪深 A 股（含创业板/科创板，不含北交所）；get_fundamentals 仅 valuation；指数成分依赖对应表；除权/板块/行业/REITs 部分接口是首次调用留日志的占位；部分设置是 no-op；无实盘推送、逐笔委托队列与完整财务报表。完整列表见使用指南；PTrade 参考文档描述官方接口，不是本地全部支持的承诺。

验收与性能

最新 Windows 原始基准 JSON · 逐项交付验收 JSON。下方保留历史测量，最新测量与当前逐项状态见这两份记录。

2026-11-08 的本地 Python 3.12 回归为 1031 passed / 7 skipped，组合行/分支覆盖率 85.84%；23 个登记模块均达到原有门槛。7 项跳过来自 Windows 真实符号链接创建权限，不能写成“零跳过”。具体命令、各组件验收与证据范围见验收记录；CI 配置矩阵与本地实际执行分开记录。

历史合成基准的中位数：

工作量	Python	Rust	比值
100,000 次精确索引	281.87 ms	20.56 ms	13.71×
241,000 个批量定位结果	536.11 ms	18.85 ms	28.44×
200 股票 × 20 日引擎阶段	4.762 s	2.602 s	1.83×

两后端处理 964,000 个 Bar / 100 笔成交并验证结果散列一致。这是该合成工作负载的历史测量；计时包含引擎构造、读取、策略和 run IO，不含数据库生成和最终流水线指标汇总。不将索引倍数当成全部策略或下载→入库→回测端到端加速。完整原始样本已整理进可复核基准。

开发与仓库结构

ptrade-sim/
├── src/ptrade_sim/       Python 控制、API、回测、看板与 SDK 适配
├── native/              可选 Rust/PyO3 分钟索引
├── native-fetch/        Rust TDX 下载与不可变 Parquet 发布
├── native-store/        Rust DuckDB 1.5.6 事务入库/校验
├── web/                 Vue 3 + TypeScript 前端源码
├── examples/            完整目录式示例策略与参数
├── scripts/             基准、原生构建、安装、发布打包、覆盖率门槛
├── docs/                使用、数据、架构、发布、验收与公开截图
├── config.example.json  回测公开模板
└── data_config.example.json  数据链公开模板

开发安装和检查：

& ./.venv/Scripts/python.exe -m pip install -e ".[dev,duckdb,dashboard,perf]"
& ./.venv/Scripts/python.exe -m ruff check src tests scripts
& ./.venv/Scripts/python.exe -m ruff format --check src tests scripts
& ./.venv/Scripts/python.exe -m mypy
& ./.venv/Scripts/python.exe -m pytest --cov=ptrade_sim --cov-report=json:coverage.json
& ./.venv/Scripts/python.exe scripts/check_coverage.py --json coverage.json

贡献指南说明测试、数据契约、单向依赖、原生验证和发布约定。GitHub 使用当前 fork 的 Issues；上游历史与作者归属保留在原项目和 LICENSE。

Navigation Menu

Repository navigation

About

Repository files navigation

ptrade-sim

能做什么

渐进 Rust 架构

界面预览

运行列表与详情

PTrade 静态转换

数据工作台与移动端

安装当前 fork

Windows 源码安装

可选原生组件

快速开始：回测

1. 准备物理库

2. 运行完整示例

3. 打开看板

快速开始：数据计划与任务

PTrade 单文件转换

API 支持边界

验收与性能

开发与仓库结构

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
data		data
docs		docs
examples/demo_rotation		examples/demo_rotation
integrations/cne_lake		integrations/cne_lake
native-fetch		native-fetch
native-store		native-store
native		native
scripts		scripts
src/ptrade_sim		src/ptrade_sim
tests		tests
web		web
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
config.example.json		config.example.json
data_config.example.json		data_config.example.json
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

ptrade-sim

能做什么

渐进 Rust 架构

界面预览

运行列表与详情

PTrade 静态转换

数据工作台与移动端

安装当前 fork

Windows 源码安装

可选原生组件

快速开始：回测

1. 准备物理库

2. 运行完整示例

3. 打开看板

快速开始：数据计划与任务

PTrade 单文件转换

API 支持边界

验收与性能

开发与仓库结构

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages