refactor: 简化 AgentScope 运行时模块与事件处理

- 移除冗余的 user_token 参数传递
- 重构 tool.result 事件使用 ToolAgentOutput 模型
- 重构 text.end 事件使用 WorkerAgentOutput 模型
- 简化 store 模块的 tool result 处理逻辑
- 更新 router/service 适配新事件结构
- 清理废弃的测试文件与设计文档
- 新增 AgentRuns 多模态存储设计文档

backend/src/v1/agent/service.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass
 from datetime import date
 import hashlib
 from typing import Any, Protocol
+from urllib.parse import urlparse
 
 import dashscope
 from ag_ui.core import RunAgentInput, StateSnapshotEvent
@@ -23,19 +24,6 @@ _MAX_ATTACHMENT_BYTES = 5 * 1024 * 1024
 _MAX_TOTAL_ATTACHMENT_BYTES = 12 * 1024 * 1024
 
 
-def _normalize_bearer_token(value: str | None) -> str | None:
-    if not isinstance(value, str):
-        return None
-    normalized = value.strip()
-    if not normalized:
-        return None
-    lower = normalized.lower()
-    if lower.startswith("bearer "):
-        token = normalized[7:].strip()
-        return token or None
-    return normalized
-
-
 @dataclass(frozen=True)
 class TaskAccepted:
     task_id: str
@@ -70,14 +58,6 @@ class AgentRepositoryLike(Protocol):
         metadata: dict[str, object] | None,
     ) -> None: ...
 
-    async def get_message_attachment_reference(
-        self,
-        *,
-        session_id: str,
-        message_id: str,
-        attachment_index: int,
-    ) -> dict[str, str] | None: ...
-
 
 class QueueClientLike(Protocol):
     async def enqueue(
@@ -148,7 +128,6 @@ class AgentService:
         *,
         run_input: RunAgentInput,
         current_user: CurrentUser,
-        user_token: str | None = None,
     ) -> TaskAccepted:
         created = False
         thread_id = run_input.thread_id
@@ -188,7 +167,6 @@ class AgentService:
             command={
                 "command": "run",
                 "owner_id": str(current_user.id),
-                "user_token": _normalize_bearer_token(user_token),
                 "run_input": run_input.model_dump(mode="json", by_alias=True),
             },
             dedup_key=None,
@@ -226,19 +204,28 @@ class AgentService:
                 mime_type = "application/octet-stream"
 
             if self._attachment_storage is None:
-                continue
+                raise HTTPException(
+                    status_code=503,
+                    detail="Attachment storage unavailable",
+                )
 
             try:
-                bucket, path = self._attachment_storage.parse_signed_url(url)
+                bucket, path = self._validate_binary_signed_url(
+                    url=url,
+                    thread_id=run_input.thread_id,
+                    current_user=current_user,
+                )
                 user_attachments = UserMessageAttachments(
                     bucket=bucket,
                     path=path,
                     mime_type=mime_type,
                 )
                 break
-            except Exception:  # noqa: BLE001
-                logger.warning("Failed to parse signed URL", url=url)
-                continue
+            except HTTPException:
+                raise
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("Failed to parse signed URL", url=url, error=str(exc))
+                raise HTTPException(status_code=422, detail="Invalid signed image url")
 
         metadata: dict[str, object] | None = None
         if user_attachments is not None:
@@ -329,13 +316,57 @@ class AgentService:
             "url": signed_url,
         }
 
+    async def create_attachment_signed_url(
+        self,
+        *,
+        bucket: str,
+        path: str,
+        current_user: CurrentUser,
+    ) -> dict[str, str]:
+        if self._attachment_storage is None:
+            raise HTTPException(
+                status_code=503, detail="Attachment storage unavailable"
+            )
+        normalized_bucket = bucket.strip()
+        if normalized_bucket != config.storage.bucket:
+            raise HTTPException(status_code=422, detail="Invalid attachment bucket")
+
+        normalized_path = path.strip()
+        expected_prefix = f"agent-inputs/{current_user.id}/"
+        if not _is_safe_attachment_path(
+            normalized_path, expected_prefix=expected_prefix
+        ):
+            raise HTTPException(status_code=422, detail="Invalid attachment path scope")
+
+        try:
+            signed_url = await self._attachment_storage.create_signed_url(
+                bucket=normalized_bucket,
+                path=normalized_path,
+                expires_in_seconds=self._SIGNED_URL_EXPIRES_IN_SECONDS,
+            )
+        except Exception:  # noqa: BLE001
+            logger.exception(
+                "Attachment signed URL generation failed",
+                extra={
+                    "bucket": normalized_bucket,
+                    "path": normalized_path,
+                    "user_id": str(current_user.id),
+                },
+            )
+            raise HTTPException(status_code=502, detail="Failed to generate signed URL")
+
+        return {
+            "bucket": normalized_bucket,
+            "path": normalized_path,
+            "url": signed_url,
+        }
+
     async def enqueue_resume(
         self,
         *,
         thread_id: str,
         run_input: RunAgentInput,
         current_user: CurrentUser,
-        user_token: str | None = None,
     ) -> TaskAccepted:
         owner = await self._repository.get_session_owner(session_id=thread_id)
         ensure_session_owner(owner_id=owner, current_user=current_user)
@@ -345,7 +376,6 @@ class AgentService:
             command={
                 "command": "resume",
                 "owner_id": str(current_user.id),
-                "user_token": _normalize_bearer_token(user_token),
                 "run_input": run_input.model_dump(mode="json", by_alias=True),
             },
             dedup_key=dedup_key,
@@ -428,6 +458,37 @@ class AgentService:
             current_user=current_user,
         )
 
+    def _validate_binary_signed_url(
+        self,
+        *,
+        url: str,
+        thread_id: str,
+        current_user: CurrentUser,
+    ) -> tuple[str, str]:
+        if self._attachment_storage is None:
+            raise HTTPException(
+                status_code=503, detail="Attachment storage unavailable"
+            )
+        parsed = urlparse(url)
+        expected_host = urlparse(config.supabase.url).netloc
+        if parsed.netloc != expected_host:
+            raise HTTPException(status_code=422, detail="INVALID_BINARY_URL_HOST")
+
+        try:
+            bucket, path = self._attachment_storage.parse_signed_url(url)
+        except Exception as exc:  # noqa: BLE001
+            raise HTTPException(
+                status_code=422, detail="Invalid signed image url"
+            ) from exc
+
+        if bucket != config.storage.bucket:
+            raise HTTPException(status_code=422, detail="INVALID_BINARY_URL_BUCKET")
+
+        expected_prefix = f"agent-inputs/{current_user.id}/{thread_id}/uploads/"
+        if not _is_safe_attachment_path(path, expected_prefix=expected_prefix):
+            raise HTTPException(status_code=422, detail="INVALID_BINARY_URL_PATH_SCOPE")
+        return bucket, path
+
 
 class AsrService:
     def __init__(self) -> None: