feat: add Super Alpha research, management and MCP workflows

backend/app/research_access/contracts.py

@@ -5,7 +5,7 @@ from typing import Annotated, Literal
 
 from pydantic import Field, model_validator
 
-from ..backtests.contracts import Candidate, SimulationSettings
+from ..backtests.contracts import Candidate, SimulationSettings, SuperSimulationSettings
 from ..catalog.contracts import CatalogFilters, Scope
 from ..preparations.contracts import PreparationReference
 from ..research.workspace_contracts import TemplateSpec
@@ -50,11 +50,26 @@ class CompleteSettings(SimulationSettings):
     model_config = {"json_schema_extra": {"required": list(SimulationSettings.model_fields)}}
 
 
+class CompleteSuperSettings(SuperSimulationSettings):
+    @model_validator(mode="before")
+    @classmethod
+    def complete(cls, value):
+        if isinstance(value, dict) and set(cls.model_fields) - value.keys():
+            raise ValueError("必须提供每项完整 SUPER 设置；先读取 get_research_capabilities")
+        return value
+
+    model_config = {"json_schema_extra": {"required": list(SuperSimulationSettings.model_fields)}}
+
+
 class DirectCandidate(Candidate):
-    settings: CompleteSettings
+    settings: CompleteSuperSettings | CompleteSettings
 
 
 class Provenance(Contract):
+    research_id: RunId | None = None
+    superalpha_plan_id: RunId | None = None
+    superalpha_plan_version: int | None = Field(default=None, ge=1)
+    selection_snapshot_ids: list[RunId] = Field(default_factory=list, max_length=100)
     reference: str | None = Field(default=None, max_length=200)
     batch_id: str | None = Field(default=None, max_length=200)
     hypothesis: str | None = Field(default=None, max_length=2000)
@@ -129,12 +144,18 @@ class Scopes(Contract):
 
 class SettingOptions(Page):
     kind: Literal["settings"]
+    alpha_type: Literal["REGULAR", "SUPER"] = "REGULAR"
 
 
 class Operators(Page):
     kind: Literal["operators"]
     q: str = Field(default="", max_length=300)
     category: str | None = None
+    stage: Literal["REGULAR", "SELECTION", "COMBO"] | None = None
+
+
+class SuperMetadata(Contract):
+    kind: Literal["superalpha"]
 
 
 class Availability(Contract):
@@ -144,7 +165,7 @@ class Availability(Contract):
 
 
 class Metadata(Contract):
-    query: Annotated[Scopes | SettingOptions | Operators | Availability, Field(discriminator="kind")]
+    query: Annotated[Scopes | SettingOptions | Operators | Availability | SuperMetadata, Field(discriminator="kind")]
 
 
 class CatalogRefresh(Contract):
@@ -192,6 +213,8 @@ class SubmissionCheck(Contract):
 
 
 class History(Page):
+    research_id: str | None = Field(default=None, max_length=36)
+    alpha_type: Literal["REGULAR", "SUPER"] | None = None
     source: str | None = Field(default=None, max_length=100)
     reference: str | None = Field(default=None, max_length=200)
     status: str | None = Field(default=None, max_length=30)
@@ -224,13 +247,13 @@ class Results(Page):
 
 class Artifact(Page):
     item_id: RunId
-    kind: Literal["snapshot", "pnl"]
+    kind: Literal["snapshot", "pnl", "components"]
     date_from: date | None = None
     date_to: date | None = None
 
     @model_validator(mode="after")
     def dates(self):
-        if self.kind == "snapshot" and (self.date_from or self.date_to):
+        if self.kind != "pnl" and (self.date_from or self.date_to):
             raise ValueError("日期筛选仅用于 PnL")
         if self.date_from and self.date_to and self.date_from > self.date_to:
             raise ValueError("起始日期不能晚于结束日期")