策略加载与统一运行方案

本文档定义 zelqor 当前需要补齐的实际功能：策略加载、统一运行入口，以及 CLI 接线。

一句话总结：

当前不再是继续证明 selector 和 stateful step 模式是否可行，而是把这两类策略正式接入统一运行入口，完成：

strategy loader
run_backtest(...) 真实分发
CLI 与请求模型的接线

1. 为什么当前应该做这个功能

当前仓库已经具备这些基础能力：

selector -> daily_pools -> backtest
stateful step strategy -> backtest
逐日 step 回测执行核心
stateful step 示例与详细文档

也就是说，仓库已经不缺：

策略模式
回测骨架
示例代码

当前真正的缺口在于：

策略还不能被框架统一加载
run_backtest(...) 仍然是 scaffold
CLI 还不能真正运行策略文件

因此当前最有价值的事情，不是继续增加更多策略样例，而是把现有策略接入能力“产品化”。

2. 功能目标

这个功能建议聚焦三个目标。

2.1 目标一：实现 strategy loader

需要支持从：

Python 文件路径
模块路径

加载两类标准策略：

DailyPoolSelector
StatefulStepStrategy

loader 的职责应是：

导入模块
发现策略导出对象或工厂
校验对象是否符合协议
返回标准化的策略实例与类型信息

2.2 目标二：让 `run_backtest(...)` 能真实分发

当前 run_backtest(...) 仍然走的是占位实现。

应让它具备：

根据请求加载 provider
根据请求加载策略
识别策略是 selector 还是 stateful step
分发到对应 runner：
run_selector_backtest(...)
run_stateful_step_backtest(...)

2.3 目标三：让 CLI 真正可运行策略

当前 CLI 仍然只能返回稳定结构的 scaffold 结果。

应让：

python -m zelqor.cli run-backtest --request-file request.json

真正可以：

解析请求
加载策略文件
执行回测
输出真实 BacktestResult

3. 当前不应该优先做什么

为了避免目标发散，这一阶段不建议优先做：

分钟级或 tick 级回测
更复杂的 broker 撮合模型
模拟盘 runtime
UI / 桌面端集成
大规模参数扫描系统
复杂的策略注册中心

这些都比“先把统一策略加载跑通”更靠后。

4. 推荐范围

这一阶段建议纳入的文件和模块主要包括：

src/zelqor/strategy/loader.py
src/zelqor/api.py
src/zelqor/cli.py
src/zelqor/models.py
tests/test_cli_contract.py
新增 loader 相关测试文件

如有必要，也可以补：

docs/quickstart.md
docs/strategy-integration-plan.md
README.md

5. 推荐接口约定

5.1 selector 的导出约定

推荐支持以下任一形式：

selector = MySelector()

def build_selector(params: dict[str, object]) -> DailyPoolSelector:
    ...

5.2 stateful step 的导出约定

推荐支持以下任一形式：

strategy = MyStatefulStrategy(...)

def build_strategy(params: dict[str, object]) -> StatefulStepStrategy:
    ...

5.3 loader 的返回结果

建议 loader 最终返回一个标准结构，例如：

@dataclass(slots=True)
class LoadedStrategy:
    strategy_type: str  # "selector" | "stateful_step"
    instance: object
    source: str

这样上层 API 可以更容易分发。

6. 推荐请求模型演进

当前请求已经演进为：

strategy.type
strategy.path
strategy.kind

不再保留旧 selector 兼容字段。

对应地，回测结果也统一为：

strategyType

不再保留旧 selectorType。

可以先约定：

strategy.type == "python_file" 时
由 loader 从文件里自动判断是：
selector
stateful step

如果调用方已经知道策略形态，也可以通过：

strategy.kind == "selector"
strategy.kind == "stateful_step"

显式约束加载结果。

后续如果需要，再演进为更明确的区分字段。

这样做的好处是：

schema 语义更清晰
能先把运行链路跑通
后续再迭代 schema 更稳

7. 推荐实施顺序

建议按下面顺序推进。

7.1 第一步：实现最小 loader

先在：

src/zelqor/strategy/loader.py

实现最小功能：

从 Python 文件导入模块
识别 selector
识别 strategy
识别 build_selector(...)
识别 build_strategy(...)
返回标准化结果

7.2 第二步：补 loader 测试

建议新增：

selector 文件加载测试
stateful step 文件加载测试
非法导出报错测试
缺少导出对象报错测试

7.3 第三步：接通 `run_backtest(...)`

让 run_backtest(...)：

读取请求
初始化 provider
读取日期区间
调用 loader
分发到不同 runner

7.4 第四步：接通 CLI

让 CLI 直接输出真实运行结果，而不是 scaffold。

7.5 第五步：补文档与 example

新增一个最小“可被 loader 运行的策略文件”示例，最好包含：

一个 selector 示例
一个 stateful step 示例

8. 验收标准

这个功能建议以这些结果作为完成标志。

8.1 loader 验收

能从 Python 文件加载 selector
能从 Python 文件加载 stateful step strategy
对错误导出给出明确报错

8.2 API 验收

run_backtest(...) 不再返回 scaffold
能根据真实策略运行回测

8.3 CLI 验收

run-backtest --request-file ... 能跑通 selector
run-backtest --request-file ... 能跑通 stateful step

8.4 文档验收

README 说明新的运行方式
quickstart 补充最小可运行策略文件示例
CHANGELOG 记录阶段完成情况

9. 风险与取舍

这个功能最常见的风险有三个。

9.1 过早把策略协议设计得太复杂

建议保持最小支持面：

selector
stateful step

不要一开始就加太多中间抽象层。

9.2 过早改 request schema

建议以 strategy 作为唯一主字段继续演进，把策略类型识别与显式 kind 校验交给 loader。

9.3 强行接管所有 script/demo

不建议让所有脚本都必须适配 loader。

更稳妥的方式是：

loader 先服务标准接口
script/demo 继续保留

10. 结论

zelqor 当前最应该补齐的是：

让策略可以被统一加载
让 API 可以真实运行策略
让 CLI 可以直接跑策略文件

也就是说，这个功能的关键词不是“再加一个模式”，而是：

把已经存在的模式正式接起来

完成这部分后，仓库会从：

有回测内核
有策略接口
有示例和文档

进一步进入：

有统一策略加载
有真实运行入口
有可扩展宿主边界

这会是 zelqor 从“能力原型”走向“可用框架”的关键一步。

11. 当前落地状态

本页方案的最小链路已经落地，当前已支持：

从 Python 文件或模块路径加载 selector
从 Python 文件或模块路径加载 stateful step strategy
run_backtest(...) 按策略类型自动分发
run-backtest --request-file ... 直接运行可加载策略

当前仍建议后续继续补齐：

更细的 CLI 文档与宿主集成说明