Refactor project components and workflows

backend/app/mcp_api/server.py

@@ -35,8 +35,11 @@ TOOLS = {
     "get_data_preparation": (c.PreparationRead, "preparation", "research:read", "按集合 ID 与版本分页预览字段、类型、描述和数据集归属。提交回测时携带 preparation_refs，由服务端核对版本并固定独立输入快照；空集合不能用于研究。"),
     "search_research_templates": (c.TemplateSearch, "templates", "research:read", "分页搜索模板工坊的模板与最新版本，不执行研究。"),
     "get_research_template": (c.TemplateRead, "template", "research:read", "读取模板内容、字段定义和来源；新增版本前核对最新版本。"),
-    "create_research_template_version": (c.CreateTemplateVersion, "create_template_version", "research:write", "为已有模板新增不可变版本。先读取模板，携带 template_id、expected_version、完整 template、hypothesis、1–20 个已完成采集的 source_item_ids 及 idempotency_key。沿用创建模板的结构和来源校验；版本冲突须重新读取，不覆盖历史、不调用模型、不回测。"),
-    "create_research_template": (c.CreateTemplate, "create_template", "research:write", "将调用方大模型研究后自行总结的参数化模板保存到模板工坊，供用户后续批量回测。先用 get_backtest_results 阅读实际指标和检查，选择 1–20 个已完成采集的 source_item_ids，并说明 hypothesis；不要把 completed 当作检查通过。template 使用 {name} 占位符及逐一对应的 variables，字段变量须声明 MATRIX/VECTOR/GROUP，VECTOR 聚合须明确写入表达式。提供唯一名称和 idempotency_key，可附 reference。返回模板 ID、版本和理论组合数；仅核验结构及来源，不验证所有参数组合，不再次调用模型、不执行回测、不覆盖已有模板。"),
+    "create_research_template_version": (c.CreateTemplateVersion, "create_template_version", "research:write", "为已有模板新增不可变版本。先读取模板，携带 template_id、expected_version、完整 template、hypothesis 和 idempotency_key。source_item_ids 可选，提供时须为真实、已完成采集的回测项。版本冲突须重新读取；不调用模型、不回测。"),
+    "create_research_template": (c.CreateTemplate, "create_template", "research:write", "保存调用方编写的模板，不要求已有回测结果。提供 template、hypothesis、唯一名称和 idempotency_key；source_item_ids 可选，提供时须为真实、已完成采集的回测项。template 使用 {name} 占位符及对应 variables，字段定义只需类型和描述；空字段 values 由展开时的数据准备绑定，其他空参数须补充 values 或直接写入表达式。仅保存模板，不调用模型、不展开、不执行回测。"),
+    "expand_research_template": (c.TemplateExpansion, "expand_template", "research:write", "按 template_id/version、preparation_refs 和完整 settings 生成固定候选集合，支持全组合或固定 seed 随机采样。仅检查语法和数据准备/回测参数组合一致性，无逐行校验状态，不回测。返回首25项和 experiment_id，更多候选用 get_template_candidates 分页读取；用户授权后按明确 candidate_ids 调用 start_template_backtest。重试复用 idempotency_key。"),
+    "get_template_candidates": (c.TemplateCandidates, "template_candidates", "research:read", "分页读取固定模板候选集合的表达式、参数、候选 ID、模板版本、数据准备及关联回测；每页最多100条，total 不是当前页数量。"),
+    "start_template_backtest": (c.SubmitTemplateBacktest, "start_template_backtest", "backtests:execute", "对用户已授权的模板候选集合执行批量回测。提供 experiment_id、明确的 candidate_ids 和 idempotency_key；服务端使用保存的表达式和参数并保留来源，不接受重写输入。不需要另建预览，不重新校验类型或平台可用性。相同请求重试返回同一运行；新幂等键会创建新的回测，包括重复候选。立即返回运行 ID，结果另行查询。"),
     "get_submission_check": (c.SelfCorrelationReference, "submission_check_context", "research:read", "读取已导入 Alpha 的表达式、Description、snapshot 和缓存检查结果；check_summary 分离 Alpha 检查和 REGULAR_SUBMISSION 提交限制，原始 checks 保留；限制不代表当前额度。不发起检查。先核对或生成三段 Description，再调用 check_submission。"),
     "check_submission": (c.SubmissionCheck, "check_submission", "research:refresh", "对单个待提交 Alpha 写回已获用户授权的 Description 并调用平台 GET /check，返回 job_id。须先用 get_submission_check 获取 snapshot；保留本地自相关门槛和冲突保护。通过 get_refresh_job 查进度、get_submission_check 读结果。无论检查结果如何，都不会调用 /submit 或正式提交 Alpha。"),
     "get_worldquant_connection": (c.ConnectionReference, "connection", "research:read", "读取 WorldQuant 连接状态及可选认证 job_id 的进度，不发起认证；人工验证在网页完成。"),
@@ -70,7 +73,7 @@ class MCPResearchServer:
         self.mutation_lock = asyncio.Lock()
         self.server = Server("wq-alpha-research", version="1.0.0", on_list_tools=self.list_tools,
                              on_call_tool=self.call_tool,
-                             instructions="自由探索，直接固定候选回测，无需先建研究资产。工具不安排定时研究；结果按运行 ID 查询。")
+                             instructions="自由探索，直接固定候选回测，无需先建研究资产。使用已有模板时，expand_research_template 生成候选，get_template_candidates 分页核对，获得用户授权后 start_template_backtest 执行；无需额外预览或结果评估步骤。工具不安排定时研究；结果按运行 ID 查询。")
         from urllib.parse import urlsplit
 
         host = urlsplit(settings.public_origin).netloc
@@ -85,8 +88,8 @@ class MCPResearchServer:
         return types.ListToolsResult(tools=[types.Tool(name=name, description=description,
             inputSchema=schema.model_json_schema(), annotations=types.ToolAnnotations(
                 readOnlyHint=scope == "research:read", destructiveHint=method == "control",
-                idempotentHint=method in {"submit", "control", "create_template", "create_template_version", "save_super_plan", "build_super_candidates"} or scope == "research:read",
-                openWorldHint=method in {"refresh", "submit", "metadata", "check_self_correlation", "check_submission", "authenticate", "pyramid_distribution", "preview_super_selection"}))
+                idempotentHint=method in {"submit", "control", "create_template", "create_template_version", "save_super_plan", "build_super_candidates", "expand_template", "start_template_backtest"} or scope == "research:read",
+                openWorldHint=method in {"refresh", "submit", "metadata", "check_self_correlation", "check_submission", "authenticate", "pyramid_distribution", "preview_super_selection", "start_template_backtest"}))
             for name, (schema, method, scope, description) in TOOLS.items()
             if scope in principal.scopes and "research:read" in principal.scopes])
 
@@ -139,7 +142,7 @@ class MCPResearchServer:
                         data = {"error": ResearchError(code, "研究操作失败；可使用原幂等键重试或查询历史", retryable=True).data}
                     db.add(MCPAudit(id=str(uuid4()), token_id=principal.token_id, tool=name,
                         request_id=fingerprint({"request_id": request_id}), input_digest=digest,
-                        business_id=data.get("backtest_run_id", data.get("job_id", data.get("template_id", data.get("id")))),
+                        business_id=data.get("backtest_run_id", data.get("job_id", data.get("experiment_id", data.get("template_id", data.get("id"))))),
                         result_code=code, elapsed_ms=int((time.monotonic()-started)*1000)))
                 if not error:
                     if access.wake == "backtests":