feat: 优化 Agent 运行时与聊天设置体验

backend/src/schemas/messages/chat_message.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from datetime import datetime
 from decimal import Decimal
-from typing import ClassVar
+from typing import Any, ClassVar
 from uuid import UUID
 
 from pydantic import BaseModel, ConfigDict, Field
@@ -11,7 +11,7 @@ from schemas.agent.runtime_models import RouterAgentOutput, WorkerAgentOutputRic
 from ..agent import AgentType, ToolAgentOutput
 
 
-class UserMessageAttachments(BaseModel):
+class UserMessageAttachment(BaseModel):
     model_config: ClassVar[ConfigDict] = ConfigDict(extra="allow")
 
     bucket: str
@@ -23,7 +23,7 @@ class AgentChatMessageMetadata(BaseModel):
     model_config: ClassVar[ConfigDict] = ConfigDict(extra="allow")
     run_id: str
     agent_type: AgentType | None = None
-    user_message_attachments: UserMessageAttachments | None = None
+    user_message_attachments: list[UserMessageAttachment] | None = None
     router_agent_output: RouterAgentOutput | None = None
     tool_agent_output: ToolAgentOutput | None = None
     worker_agent_output: WorkerAgentOutputRich | None = None
@@ -46,3 +46,32 @@ class AgentChatMessage(BaseModel):
     latency_ms: int | None = Field(default=None, ge=0)
     metadata: AgentChatMessageMetadata | dict[str, object] | None = None
     timestamp: datetime
+
+
+def extract_user_message_attachments(
+    metadata: AgentChatMessageMetadata | dict[str, object] | None,
+) -> list[UserMessageAttachment]:
+    if metadata is None:
+        return []
+
+    if isinstance(metadata, AgentChatMessageMetadata):
+        raw_value: Any = metadata.user_message_attachments
+    else:
+        raw_value = metadata.get("user_message_attachments")
+
+    if raw_value is None:
+        return []
+
+    raw_items: list[Any]
+    if isinstance(raw_value, list):
+        raw_items = raw_value
+    else:
+        raw_items = [raw_value]
+
+    attachments: list[UserMessageAttachment] = []
+    for item in raw_items:
+        try:
+            attachments.append(UserMessageAttachment.model_validate(item))
+        except Exception:
+            continue
+    return attachments