feat: 增加 MCP 研究模板保存工具

backend/app/research_access/contracts.py

@@ -7,6 +7,7 @@ from pydantic import Field, model_validator
 
 from ..backtests.contracts import Candidate, SimulationSettings
 from ..catalog.contracts import CatalogFilters, Scope
+from ..research.workspace_contracts import TemplateSpec
 from ..schemas import Contract
 
 Identifier = Annotated[str, Field(min_length=1, max_length=100)]
@@ -74,6 +75,26 @@ class Control(Contract):
     idempotency_key: Identifier
 
 
+class CreateTemplate(Contract):
+    template: TemplateSpec
+    hypothesis: str = Field(min_length=1, max_length=10000)
+    source_item_ids: list[RunId] = Field(min_length=1, max_length=20)
+    reference: str | None = Field(default=None, max_length=200)
+    idempotency_key: Identifier
+
+    @model_validator(mode="after")
+    def research_template(self):
+        self.template.name = self.template.name.strip()
+        self.hypothesis = self.hypothesis.strip()
+        if not self.template.name or not self.hypothesis or not self.template.expression.strip():
+            raise ValueError("模板名称、表达式和研究假设不能为空")
+        if self.template.category != "template":
+            raise ValueError("此工具仅创建完整模板，不保存表达式片段")
+        if len(set(self.source_item_ids)) != len(self.source_item_ids):
+            raise ValueError("来源候选 ID 不能重复")
+        return self
+
+
 class CatalogSearch(Contract):
     filters: CatalogFilters
     dataset_id: str | None = Field(default=None, min_length=1, max_length=200)

backend/app/research_access/service.py

@@ -53,6 +53,12 @@ class ResearchAccess:
                 "confirmation": "调用者须已获本批执行授权；直接提交后返回稳定运行 ID",
                 "duplicate_policies": ["reject", "rerun"], "permissions": sorted(self.principal.scopes),
                 "metadata_only": True, "actual_platform_allowance": None,
+                "templates": {
+                    "create_with": "create_research_template", "required_scope": "research:write",
+                    "authored_by": "caller", "max_source_items": 20,
+                    "source_items_with": "get_backtest_results", "starts_backtests": False,
+                    "web_url": f"{self.public_origin}/#templates",
+                },
                 "submission_check": {
                     "check_with": "check_submission", "read_with": "get_submission_check",
                     "job_with": "get_refresh_job", "max_targets": 1,
@@ -220,6 +226,18 @@ class ResearchAccess:
     async def history(self, args):
         return await self.evidence.history(args)
 
+    async def create_template(self, args):
+        """Persist the caller's template and evidence without model or queue execution."""
+        from .templates import create_template
+
+        previous, digest = await self.previous("create_research_template", args)
+        if previous:
+            return previous.response
+        result = await create_template(self.db, args, self.principal)
+        result["web_url"] = f"{self.public_origin}/#templates"
+        return await self.remember("create_research_template", args, digest, result,
+                                   business_id=result["template_id"])
+
     async def previous(self, operation, args):
         # PostgreSQL row lock is shared with HTTP start and catalog/job creation.
         account = await self.db.scalar(select(Account).where(Account.id == self.principal.account_id).with_for_update())
@@ -233,13 +251,13 @@ class ResearchAccess:
             raise ResearchError("IDEMPOTENCY_CONFLICT", "幂等键已用于不同内容")
         return row, digest
 
-    async def remember(self, operation, args, digest, result):
+    async def remember(self, operation, args, digest, result, *, business_id, wake=None):
         result["_meta"] = {"schema_version": 1, "observed_at": now().isoformat(), "source": "system"}
         self.db.add(ResearchRequest(id=str(uuid4()), account_id=self.principal.account_id,
             operation=operation, idempotency_key=args.idempotency_key, digest=digest,
-            business_id=result["backtest_run_id"], response=encode_snapshot(result)))
+            business_id=business_id, response=encode_snapshot(result)))
         await self.db.flush()
-        self.wake = "backtests"
+        self.wake = wake
         return result
 
     async def validate_settings(self, candidates):
@@ -286,7 +304,8 @@ class ResearchAccess:
         result = {**result, "input_digest": digest, "batch_count": preview["batch_count"],
                   "duplicates": {"within_batch": within, "historical_matches": history["total"]},
                   "validation": validation, "web_url": self.run_url(result["backtest_run_id"])}
-        return await self.remember("submit_backtests", args, digest, result)
+        return await self.remember("submit_backtests", args, digest, result,
+                                   business_id=result["backtest_run_id"], wake="backtests")
 
     async def run(self, args):
         result = await self.backtests.run(args.run_id)
@@ -325,4 +344,5 @@ class ResearchAccess:
             "indefinite_account_block_cleared": args.action == "resume" and bool(before["scheduler"]["blocked_reason"])
                 and before["scheduler"]["blocked_until"] is None,
             "note": "暂停/停止仅阻止后续提交；已提交模拟继续采集。recover 不重新提交。"}
-        return await self.remember("control_backtest", args, digest, result)
+        return await self.remember("control_backtest", args, digest, result,
+                                   business_id=result["backtest_run_id"], wake="backtests")

backend/app/research_access/templates.py

@@ -0,0 +1,60 @@
+"""Persist caller-authored templates with frozen local research evidence."""
+
+import math
+
+from sqlalchemy import select
+
+from ..models import BacktestItem, BacktestResult, ResearchAsset
+from ..research.assets import Assets
+from ..research.workspace_contracts import AssetWrite
+from .queries import item_summary
+
+
+async def create_template(db, args, principal):
+    """Save a new asset inside the caller's account-locked, idempotent transaction.
+
+    Args contain the external model's TemplateSpec and local source item IDs.
+    Return the versioned asset and theoretical combination count. Raise
+    ResearchError for name conflicts or missing/incomplete research evidence.
+    Stored evidence proves provenance, not profitability or platform eligibility;
+    schema validation does not validate every expanded FASTEXPR combination.
+    """
+    from .service import ResearchError
+
+    existing = await db.scalar(select(ResearchAsset).where(
+        ResearchAsset.kind == "template", ResearchAsset.name == args.template.name,
+    ).order_by(ResearchAsset.id).limit(1))
+    if existing:
+        raise ResearchError("TEMPLATE_NAME_CONFLICT", "模板名称已存在，请使用新名称；此工具不覆盖已有模板",
+                            affected_items=[{"template_id": existing.id, "version": existing.version}])
+    rows = (await db.execute(select(BacktestItem, BacktestResult).outerjoin(
+        BacktestResult, BacktestResult.item_id == BacktestItem.id,
+    ).where(BacktestItem.id.in_(args.source_item_ids)))).all()
+    found = {item.id: (item, result) for item, result in rows}
+    missing = [item_id for item_id in args.source_item_ids if item_id not in found]
+    if missing:
+        raise ResearchError("NOT_FOUND", "部分来源回测候选不存在", affected_items=missing)
+    incomplete = [item.id for item, result in rows if (
+        item.platform_status != "completed" or item.collection_status != "complete"
+        or item.persistence_status != "saved" or not result or not result.complete
+    )]
+    if incomplete:
+        raise ResearchError("SOURCE_NOT_READY", "来源候选须完成回测、结果采集和持久化，请先读取 get_backtest_results",
+                            affected_items=sorted(incomplete))
+    provenance = {
+        "source": {"kind": "mcp", "reference": args.reference},
+        "hypothesis": args.hypothesis,
+        "mcp_token_id": principal.token_id,
+        "admin_id": principal.admin_id,
+        "source_items": [item_summary(*found[item_id]) for item_id in args.source_item_ids],
+    }
+    asset = await Assets(db).save(AssetWrite(
+        kind="template", content=args.template.model_dump(mode="json"),
+    ), provenance=provenance)
+    return {
+        **asset, "template_id": asset["id"],
+        "combination_count": str(math.prod(len(v.values) for v in args.template.variables.values())),
+        "validation": {"structure": "valid", "source_evidence": "recorded",
+                       "expanded_candidates": "not_validated", "platform_semantics": "unknown"},
+        "next_step": "在模板工坊选择固定输入及模拟设置，展开并核验候选，再确认批量回测。",
+    }