feat: add durable WorldQuant backtests with UI and AI confirmation

backend/app/ai/tools.py

@@ -5,6 +5,7 @@ from typing import Literal
 
 from pydantic import Field
 
+from ..backtests.contracts import ControlInput, PreviewInput, RerunInput, StartInput
 from ..schemas import AlphaFilters, BulkInput, BulkUpdate, Contract, JobInput, ResearchInput, ResearchUpdate
 
 
@@ -43,7 +44,63 @@ class ResultMetadata(Contract):
     )
 
 
+class BacktestRunArgs(Contract):
+    run_id: str = Field(min_length=1, max_length=36)
+
+
+class BacktestListArgs(Contract):
+    limit: int = Field(default=20, ge=1, le=100)
+    offset: int = Field(default=0, ge=0)
+    source: str | None = Field(default=None, max_length=100)
+
+
+class BacktestResultsArgs(BacktestRunArgs):
+    limit: int = Field(default=20, ge=1, le=100)
+    offset: int = Field(default=0, ge=0)
+
+
+class BacktestPreviewArgs(Contract):
+    preview_id: str = Field(min_length=1, max_length=36)
+    limit: int = Field(default=20, ge=1, le=100)
+    offset: int = Field(default=0, ge=0)
+
+
+class BacktestControlArgs(BacktestRunArgs):
+    action: Literal["pause", "resume", "stop", "recover"]
+
+
+class BacktestRerunArgs(BacktestRunArgs):
+    item_ids: list[str] = Field(min_length=1, max_length=100)
+
+
 CATALOG = {
+    "get_backtest_capabilities": (
+        EmptyArgs,
+        "读取回测输入 schema、支持类型和本地调度配置，不代表平台剩余额度。",
+    ),
+    "prepare_backtest": (
+        PreviewInput,
+        "准备服务端固定回测预览，可用 inline 候选或草稿引用；只保存预览，不提交平台，不需要执行确认。",
+    ),
+    "get_backtest_preview": (BacktestPreviewArgs, "分页读取完整固定预览，确认前核对表达式和最终参数。"),
+    "start_backtest": (
+        StartInput,
+        "对已保存预览请求一次用户确认，确认后后台运行全部固定候选，立即返回运行 ID；禁止循环等待。",
+    ),
+    "list_backtests": (BacktestListArgs, "分页查询回测运行与统计，可按来源筛选。"),
+    "get_backtest": (BacktestRunArgs, "查询指定运行的真实进度，不循环等待完成。"),
+    "get_backtest_results": (
+        BacktestResultsArgs,
+        "分页读取逐项状态、历史指标和错误；未知结果不能推测为成功。",
+    ),
+    "control_backtest": (
+        BacktestControlArgs,
+        "预览并确认暂停/继续/停止剩余项/找回原任务；不远端取消，不重新提交。",
+    ),
+    "prepare_backtest_rerun": (
+        BacktestRerunArgs,
+        "从明确指定的已结束回测项准备新预览，保留来源；不会自动启动。",
+    ),
     "search_alphas": (
         SearchArgs,
         "按明确筛选条件查询本地 Alpha。Turnover 0.15 表示 15%；支持分页，禁止把当前页当作全部结果。",
@@ -65,7 +122,15 @@ CATALOG = {
     "cancel_job": (JobArgs, "提出取消指定同步任务，等待用户确认。"),
     "retry_job": (JobArgs, "提出重试指定失败或暂停的同步任务，等待用户确认。"),
 }
-WRITES = {"update_research", "bulk_update_research", "create_sync_job", "cancel_job", "retry_job"}
+WRITES = {
+    "update_research",
+    "bulk_update_research",
+    "create_sync_job",
+    "cancel_job",
+    "retry_job",
+    "start_backtest",
+    "control_backtest",
+}
 
 
 def bounded(value):
@@ -81,7 +146,26 @@ def bounded(value):
 async def read_tool(business, name, args):
     from datetime import timezone
 
-    if name == "search_alphas":
+    if name == "get_backtest_capabilities":
+        data = await business.backtests.capabilities()
+    elif name == "prepare_backtest":
+        data = await business.backtests.preview(args)
+    elif name == "get_backtest_preview":
+        data = await business.backtests.get_preview(**args.model_dump())
+    elif name == "list_backtests":
+        data = await business.backtests.runs(**args.model_dump())
+    elif name == "get_backtest":
+        data = await business.backtests.run(args.run_id)
+    elif name == "get_backtest_results":
+        data = await business.backtests.results(**args.model_dump())
+        # The complete historical response remains available through the business endpoint.
+        for item in data["items"]:
+            if item["result"]:
+                snapshot = item["result"].pop("snapshot")
+                item["result"].update({k: snapshot.get(k) for k in ("is", "os", "checks", "dateCreated")})
+    elif name == "prepare_backtest_rerun":
+        data = await business.backtests.rerun(args.run_id, RerunInput(item_ids=args.item_ids))
+    elif name == "search_alphas":
         data = await business.search_alphas(args.filters)
         data["filters"] = args.filters.model_dump(mode="json")
     elif name == "get_alpha_pnl":
@@ -105,6 +189,10 @@ async def read_tool(business, name, args):
 
 
 async def preview_tool(business, name, args):
+    if name == "start_backtest":
+        return {"backtest": await business.backtests.get_preview(args.preview_id)}
+    if name == "control_backtest":
+        return {"backtest_run": await business.backtests.run(args.run_id), "action": args.action}
     if name in ("update_research", "bulk_update_research"):
         ids = [args.alpha_id] if name == "update_research" else args.alpha_ids
         targets, versions = [], {}
@@ -131,6 +219,17 @@ async def preview_tool(business, name, args):
 
 
 async def execute_tool(business, name, args, preview):
+    if name == "start_backtest":
+        current = await business.backtests.get_preview(args.preview_id)
+        if current["digest"] != preview["backtest"]["digest"] or current["version"] != args.version:
+            from fastapi import HTTPException
+
+            raise HTTPException(409, "回测预览不匹配，请重新确认")
+        return await business.backtests.start(args)
+    if name == "control_backtest":
+        return await business.backtests.control(
+            args.run_id, ControlInput(action=args.action, version=preview["backtest_run"]["version"])
+        )
     if name == "update_research":
         body = ResearchUpdate(
             **args.changes.model_dump(exclude_unset=True), version=preview["versions"][args.alpha_id]