feat: add reusable Studio workspaces (#1004)

Author: evanlowe

frontend/README.md

@@ -451,6 +451,10 @@ local image or a downloaded network image into the VeFaaS deployment package.
 
 ## Environment image builds
 
+Studio 的“工作区”用于组织一组可复用环境。一个工作区可以包含多个环境，同一个环境也可以加入多个工作区；删除工作区只会删除组合关系，不会删除环境。侧边栏只展示“工作区”入口，工作区页面内可在“工作区”和“环境”两个视图之间切换。Agent 的创建与部署仍直接选择具体环境及其构建版本。
+
+工作区元数据保存在与环境相同的 Studio TOS 桶中，路径为 `veadk-studio/v1/workspaces/<owner>/<workspace-id>/summary.json`。接口包括 `/web/workspaces` CRUD，以及 `/web/workspaces/{workspaceId}/environments/{environmentId}` 的添加和移除操作。被工作区引用的环境不能直接删除。
+
 The Studio `环境` page stores each environment definition, generated Dockerfile,
 build version, log metadata, and resulting image reference in the private Studio
 TOS bucket. Creating or saving an environment starts an asynchronous

frontend/server/environments/__init__.py

@@ -27,7 +27,7 @@
 from .repository import TosEnvironmentRepository
 from .resources import EnvironmentResourceSettings, StudioEnvironmentCloudGateway
 from .routes import mount_environment_routes
-from .service import EnvironmentService
+from .service import EnvironmentService, WorkspaceReferenceLookup
 
 
 def create_environment_service(
@@ -36,17 +36,22 @@ def create_environment_service(
     resolve_credentials: CredentialResolver | None = None,
     client_factory: Callable[[], Any] | None = None,
     environment: Mapping[str, str] | None = None,
+    workspace_references: WorkspaceReferenceLookup | None = None,
 ) -> EnvironmentService:
     storage = StudioStorageConfig.from_env(provider, environment)
     if not storage.configured:
         return EnvironmentService(
-            None, None, unavailable_reason=storage.unavailable_reason
+            None,
+            None,
+            workspace_references=workspace_references,
+            unavailable_reason=storage.unavailable_reason,
         )
     if client_factory is None:
         if resolve_credentials is None:
             return EnvironmentService(
                 None,
                 None,
+                workspace_references=workspace_references,
                 unavailable_reason="管理员未配置环境存储与构建凭据。",
             )
         client_factory = create_tos_client_factory(storage, resolve_credentials)
@@ -67,6 +72,7 @@ def create_environment_service(
             settings,
             resolve_credentials=resolve_credentials,
         ),
+        workspace_references=workspace_references,
     )
 
 

frontend/server/environments/service.py

@@ -22,6 +22,7 @@
 import tarfile
 from datetime import datetime, timezone
 from pathlib import Path, PurePosixPath
+from typing import Protocol
 from uuid import uuid4
 
 from veadk.cli.generated_agent_codegen import (
@@ -53,20 +54,32 @@
     EnvironmentView,
     ResolvedEnvironment,
 )
-from .repository import EnvironmentStorageUnavailable, TosEnvironmentRepository
+from .repository import (
+    EnvironmentConflict,
+    EnvironmentStorageUnavailable,
+    TosEnvironmentRepository,
+)
 from .resources import EnvironmentCloudGateway
 
 
+class WorkspaceReferenceLookup(Protocol):
+    async def workspace_names_for_environment(
+        self, owner_id: str, environment_id: str
+    ) -> list[str]: ...
+
+
 class EnvironmentService:
     def __init__(
         self,
         repository: TosEnvironmentRepository | None,
         cloud: EnvironmentCloudGateway | None,
         *,
+        workspace_references: WorkspaceReferenceLookup | None = None,
         unavailable_reason: str = "管理员未配置环境持久化存储。",
     ) -> None:
         self._repository = repository
         self._cloud = cloud
+        self._workspace_references = workspace_references
         self._unavailable_reason = unavailable_reason
         self._skillspace_resolver: SkillSpaceResolver | None = None
 
@@ -151,6 +164,18 @@ async def update(
         return await self._view(repository, owner_id, saved)
 
     async def delete(self, owner_id: str, environment_id: str) -> None:
+        if self._workspace_references is not None:
+            workspace_names = (
+                await self._workspace_references.workspace_names_for_environment(
+                    owner_id, environment_id
+                )
+            )
+            if workspace_names:
+                names = "、".join(workspace_names[:3])
+                suffix = "等工作区" if len(workspace_names) > 3 else "工作区"
+                raise EnvironmentConflict(
+                    f"该环境正在被 {names}{suffix} 使用，请先从工作区中移除。"
+                )
         await self._require_repository().delete(owner_id, environment_id)
 
     async def start_build(self, owner_id: str, environment_id: str) -> EnvironmentBuild:

frontend/server/workspaces/__init__.py

@@ -0,0 +1,57 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Studio workspace backend composition."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from frontend.server.environments.repository import TosEnvironmentRepository
+from frontend.server.storage import StudioProvider, StudioStorageConfig
+from frontend.server.storage.tos import CredentialResolver, create_tos_client_factory
+
+from .repository import TosWorkspaceRepository
+from .routes import mount_workspace_routes
+from .service import WorkspaceService
+
+
+def create_workspace_service(
+    *,
+    provider: StudioProvider = "volcengine",
+    resolve_credentials: CredentialResolver | None = None,
+    client_factory: Callable[[], Any] | None = None,
+    environment: Mapping[str, str] | None = None,
+) -> WorkspaceService:
+    storage = StudioStorageConfig.from_env(provider, environment)
+    if not storage.configured:
+        return WorkspaceService(
+            None, None, unavailable_reason=storage.unavailable_reason
+        )
+    if client_factory is None:
+        if resolve_credentials is None:
+            return WorkspaceService(
+                None,
+                None,
+                unavailable_reason="管理员未配置工作区存储凭据。",
+            )
+        client_factory = create_tos_client_factory(storage, resolve_credentials)
+    return WorkspaceService(
+        TosWorkspaceRepository(bucket=storage.bucket, client_factory=client_factory),
+        TosEnvironmentRepository(bucket=storage.bucket, client_factory=client_factory),
+    )
+
+
+__all__ = ["WorkspaceService", "create_workspace_service", "mount_workspace_routes"]

frontend/server/workspaces/models.py

@@ -0,0 +1,80 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Validated contracts for Studio workspaces."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class WorkspaceInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    name: str = Field(min_length=1, max_length=128)
+    description: str = Field(default="", max_length=2000)
+    environment_ids: list[str] = Field(
+        default_factory=list, alias="environmentIds", max_length=100
+    )
+
+    @model_validator(mode="after")
+    def normalize(self) -> WorkspaceInput:
+        self.name = self.name.strip()
+        self.description = self.description.strip()
+        if not self.name:
+            raise ValueError("工作区名称不能为空。")
+        self.environment_ids = list(
+            dict.fromkeys(item.strip() for item in self.environment_ids if item.strip())
+        )
+        return self
+
+
+class WorkspacePatch(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    name: str | None = Field(default=None, min_length=1, max_length=128)
+    description: str | None = Field(default=None, max_length=2000)
+    environment_ids: list[str] | None = Field(
+        default=None, alias="environmentIds", max_length=100
+    )
+
+    @model_validator(mode="after")
+    def normalize(self) -> WorkspacePatch:
+        if not self.model_fields_set:
+            raise ValueError("至少需要更新一个工作区字段。")
+        if self.name is not None:
+            self.name = self.name.strip()
+            if not self.name:
+                raise ValueError("工作区名称不能为空。")
+        if self.description is not None:
+            self.description = self.description.strip()
+        if self.environment_ids is not None:
+            self.environment_ids = list(
+                dict.fromkeys(
+                    item.strip() for item in self.environment_ids if item.strip()
+                )
+            )
+        return self
+
+
+class WorkspaceRecord(WorkspaceInput):
+    id: str = Field(min_length=32, max_length=32)
+    owner_id: str = Field(alias="ownerId", min_length=1, max_length=1024)
+    created_at: datetime = Field(alias="createdAt")
+    updated_at: datetime = Field(alias="updatedAt")
+
+
+__all__ = ["WorkspaceInput", "WorkspacePatch", "WorkspaceRecord"]