feat: 新增需求理解并实现human in loop

app/schemas/clarification.py

@@ -1,11 +1,35 @@
 """等待用户补充的问题"""
 
-from pydantic import Field
+from typing import Self
+
+from pydantic import Field, model_validator
 
 from app.schemas.base import ExtensibleModel, NonBlankString
 
 
+class ClarificationOption(ExtensibleModel):
+    id: NonBlankString = Field(description="本题内唯一的选项 ID")
+    label: NonBlankString = Field(description="简短选项名称")
+    description: NonBlankString = Field(description="一句话说明选择的影响或推荐依据")
+    recommended: bool = False
+
+
 class Clarification(ExtensibleModel):
     question: NonBlankString = Field(
         description="一个简短、具体、便于用户回答的澄清问题"
     )
+    options: list[ClarificationOption] = Field(
+        default_factory=list,
+        description="适合选择时提供 2–3 个互斥选项，否则留空，自由输入由客户端提供",
+    )
+
+    @model_validator(mode="after")
+    def validate_options(self) -> Self:
+        if len(self.options) not in (0, 2, 3):
+            raise ValueError("选项应为空或包含 2–3 项")
+        if len({option.id for option in self.options}) != len(self.options):
+            raise ValueError("选项 ID 不能重复")
+        if sum(option.recommended for option in self.options) > 1:
+            raise ValueError("最多一个推荐选项")
+        self.options.sort(key=lambda option: not option.recommended)
+        return self

app/schemas/input_context.py

@@ -1,7 +1,12 @@
 """输入节点校验后的上下文"""
 
+from pydantic import Field
+
+from .base import JsonObject
 from .request import DesignRequest
 
 
 class InputContext(DesignRequest):
     """当前复用请求协议，后续可添加解析结果而不改变前端传参"""
+
+    clarification_history: list[JsonObject] = Field(default_factory=list)