zelqor

zelqor 是一个独立的 Python 交易引擎脚手架，面向：

• 历史回测
• 日频股票池策略
• 后续模拟盘运行时能力

这个包刻意与当前桌面应用和 Rust 运行时解耦。阶段一重点放在稳定的包结构、公共模型、数据 provider 契约、CLI 形状和测试覆盖上。

当前已纳入范围

• 基于 uv + hatchling 的可安装 Python 包
• 公共请求/结果模型
• run_backtest 入口
• run-backtest CLI 契约
• ClickHouseProvider 第一版真实实现
• ClickHouseConfig.from_env() / from_file()
• JSON / TOML 配置读取
• 基于结构化 NumPy 的执行层数据 schema
• 基于预先给定股票池的最小回测执行核心
• selector -> daily_pools -> backtest 最小链路
• stateful step strategy -> backtest 最小链路
• 自动文档、CI 和 GitHub Pages 发布流程

当前未实现内容

• 策略文件加载与执行
• 从策略直接生成 daily_pools 的接线
• 更完整的 broker / portfolio / reports 实现
• Rust 集成

当前阶段建议入口

如果你现在要基于这个包继续往前做，建议优先使用：

• zelqor.models.ClickHouseConfig
• zelqor.data.clickhouse.ClickHouseProvider
• zelqor.backtest.run_precomputed_pool_backtest
• zelqor.api.run_selector_backtest
• zelqor.api.run_stateful_step_backtest
• zelqor.strategy.selector.build_daily_pools
• zelqor.strategy.adapters.get_bars_compat

也就是说，数据层已经可以作为 selector、stateful step 策略和回测主循环的基础能力来用，而最小回测内核也已经可以直接被策略脚本调用。

文档结构

• 快速开始：本地环境和常用命令
• ClickHouse 配置：环境变量、配置文件和 provider 使用方式
• Selector 回测方案：selector 股票池生成与最小回测链路说明
• 逐日推进回测方案：面向未来模拟盘复用的 step 化回测内核演进方案
• 策略接入分层方案：selector、stateful step 与 script/demo 三类策略的边界和演进路径
• Stateful Step 示例详解：通过“涨停之后再次涨停”示例说明 stateful step 模式如何逐日运作
• 策略加载与统一运行方案：strategy loader、统一运行入口与 CLI 接线的推荐推进路径
• MarketData 与宿主运行契约方案：provider 配置、宿主 request 边界与运行控制项的推荐推进路径
• Runtime 与结果契约方案：metadata 回传、runtime 输出裁剪语义与宿主结果消费边界
• Broker / Portfolio / Reports 实施方案：账户状态、成交执行与绩效报表的推荐实施顺序
• API 参考：公共模块的自动生成文档