feat(agent_runtime): support workspace_name in create/list (auto-resolve to workspace_id)

让用户在创建 / 查询 Agent Runtime 时可以直接填 workspace 名称，
SDK 自动调用官方 ListWorkspaces 解析为 workspace_id 再下发，
无需用户手动查 ID。

模型变更（agentrun/agent_runtime/model.py）：
- AgentRuntimeImmutableProps: 新增 workspace_name（流入 CreateInput）
- AgentRuntimeListInput: 新增 workspace_name / workspace_names

新增 agentrun/agent_runtime/_workspace.py：
- resolve_workspace_id_by_name(_async) 精确名字匹配 + (ak, region, name) 缓存
- resolve_workspace_ids_by_names(_async) 批量名字 -> 逗号分隔 ID
- 找不到抛 ResourceNotExistError，重名抛 ValueError，
  Tea ClientException/ServerException 转 SDK 内置 ClientError/ServerError

client / runtime（async 模板 + codegen 同步生成）：
- AgentRuntimeClient.create / list：调底层 API 前自动解析 workspace_name(s)
- 同时传 workspace_id+workspace_name（或复数版本）抛 ValueError
- AgentRuntime.list_all：透传 workspace_name / workspace_names

示例：examples/quickstart_runtime.py
- 演示通过镜像部署 AgentRuntime，并使用 workspace_name 选择工作空间

测试（tests/unittests/agent_runtime/test_workspace.py，新增 25 用例）：
- 精确匹配 / 缓存 / 空名 / 找不到 / 重名 / Tea 异常透传
- client.create 与 client.list 在 sync + async 路径下的解析与互斥校验

校验：
- 全量 3469 单测通过
- agentrun.agent_runtime 总覆盖率 99%，_workspace.py 95%
- mypy --config-file mypy.ini agentrun/agent_runtime/ 无 issue

Signed-off-by: Sodawyx <sodawyx@126.com>

Author: Sodawyx

agentrun/agent_runtime/__client_async_template.py

@@ -18,6 +18,12 @@
 )
 from typing_extensions import Unpack
 
+from agentrun.agent_runtime._workspace import (
+    resolve_workspace_id_by_name,
+    resolve_workspace_id_by_name_async,
+    resolve_workspace_ids_by_names,
+    resolve_workspace_ids_by_names_async,
+)
 from agentrun.agent_runtime.api.data import InvokeArgs
 from agentrun.agent_runtime.model import (
     AgentRuntimeArtifact,
@@ -68,11 +74,26 @@ async def create_async(
             AgentRuntime: 创建的 Agent Runtime 对象 / Created Agent Runtime object
 
         Raises:
-            ValueError: 当既未提供代码配置也未提供容器配置时 / When neither code nor container configuration is provided
+            ValueError: 当既未提供代码配置也未提供容器配置时；或同时传入
+                workspace_id 与 workspace_name / When neither code nor container
+                configuration is provided, or when workspace_id and workspace_name
+                are both set
             ResourceAlreadyExistError: 资源已存在 / Resource already exists
-            ResourceNotExistError: 资源不存在 / Resource does not exist
+            ResourceNotExistError: 资源不存在；或 workspace_name 在该账号下未找到
+                / Resource does not exist, or no workspace matches workspace_name
             HTTPError: HTTP 请求错误 / HTTP request error
         """
+        if input.workspace_id and input.workspace_name:
+            raise ValueError(
+                "workspace_id and workspace_name are mutually exclusive; please"
+                " only set one of them."
+            )
+        if input.workspace_name:
+            input.workspace_id = await resolve_workspace_id_by_name_async(
+                input.workspace_name, config
+            )
+            input.workspace_name = None
+
         if input.network_configuration is None:
             input.network_configuration = NetworkConfig()
 
@@ -198,12 +219,41 @@ async def list_async(
             List[AgentRuntime]: Agent Runtime 对象列表 / List of Agent Runtime objects
 
         Raises:
+            ValueError: 同时传入 workspace_id 与 workspace_name，或同时传入
+                workspace_ids 与 workspace_names / When workspace_id and
+                workspace_name (or workspace_ids and workspace_names) are
+                both set
+            ResourceNotExistError: workspace_name(s) 在该账号下未找到
+                / No workspace matches the given workspace_name(s)
             HTTPError: HTTP 请求错误 / HTTP request error
         """
         try:
             if input is None:
                 input = AgentRuntimeListInput()
 
+            if input.workspace_id and input.workspace_name:
+                raise ValueError(
+                    "workspace_id and workspace_name are mutually exclusive;"
+                    " please only set one of them."
+                )
+            if input.workspace_ids and input.workspace_names:
+                raise ValueError(
+                    "workspace_ids and workspace_names are mutually exclusive;"
+                    " please only set one of them."
+                )
+            if input.workspace_name:
+                input.workspace_id = await resolve_workspace_id_by_name_async(
+                    input.workspace_name, config
+                )
+                input.workspace_name = None
+            if input.workspace_names:
+                input.workspace_ids = (
+                    await resolve_workspace_ids_by_names_async(
+                        input.workspace_names, config
+                    )
+                )
+                input.workspace_names = None
+
             results = await self.__control_api.list_agent_runtimes_async(
                 ListAgentRuntimesRequest().from_map(input.model_dump()),
                 config=config,

agentrun/agent_runtime/__runtime_async_template.py

@@ -77,7 +77,9 @@ async def create_async(
             ResourceAlreadyExistError: 资源已存在 / Resource already exists
             HTTPError: HTTP 请求错误 / HTTP request error
         """
-        return await cls.__get_client(config=config).create_async(input, config=config)
+        return await cls.__get_client(config=config).create_async(
+            input, config=config
+        )
 
     @classmethod
     async def delete_by_id_async(cls, id: str, config: Optional[Config] = None):
@@ -155,7 +157,9 @@ async def get_by_id_async(cls, id: str, config: Optional[Config] = None):
             ResourceNotExistError: 资源不存在 / Resource does not exist
             HTTPError: HTTP 请求错误 / HTTP request error
         """
-        return await cls.__get_client(config=config).get_async(id, config=config)
+        return await cls.__get_client(config=config).get_async(
+            id, config=config
+        )
 
     @classmethod
     async def _list_page_async(
@@ -179,6 +183,8 @@ async def list_all_async(
         status: Optional[str] = None,
         workspace_id: Optional[str] = None,
         workspace_ids: Optional[str] = None,
+        workspace_name: Optional[str] = None,
+        workspace_names: Optional[str] = None,
         config: Optional[Config] = None,
     ) -> List["AgentRuntime"]:
         return await cls._list_all_async(
@@ -190,6 +196,8 @@ async def list_all_async(
             status=status,
             workspace_id=workspace_id,
             workspace_ids=workspace_ids,
+            workspace_name=workspace_name,
+            workspace_names=workspace_names,
         )
 
     @classmethod

agentrun/agent_runtime/_workspace.py

@@ -0,0 +1,205 @@
+"""Workspace 名称解析助手 / Workspace Name Resolution Helper
+
+提供 ``workspace_name -> workspace_id`` 的解析能力，供 ``AgentRuntimeClient``
+在 ``create`` / ``list`` 等场景下自动转换用户传入的工作空间名称。
+
+The official AgentRun API only accepts ``workspace_id``. The SDK exposes a
+convenience field ``workspace_name``; this module wraps ``list_workspaces``
+to look the id up by name (exact match, with a simple in-memory cache).
+"""
+
+from typing import Dict, List, Optional, Tuple
+
+from alibabacloud_agentrun20250910.models import (
+    ListWorkspacesRequest,
+    Workspace,
+)
+from alibabacloud_tea_openapi.exceptions._client import ClientException
+from alibabacloud_tea_openapi.exceptions._server import ServerException
+import pydash
+
+from agentrun.utils.config import Config
+from agentrun.utils.control_api import ControlAPI
+from agentrun.utils.exception import (
+    ClientError,
+    ResourceNotExistError,
+    ServerError,
+)
+
+# Cache key 为 (access_key_id, region_id, name)，避免不同账号/地域串号。
+# Value 为解析得到的 workspace_id。
+_RESOLVE_CACHE: Dict[Tuple[str, str, str], str] = {}
+
+
+def _cache_key(cfg: Config, name: str) -> Tuple[str, str, str]:
+    return (
+        cfg.get_access_key_id() or "",
+        cfg.get_region_id() or "",
+        name,
+    )
+
+
+def _pick_exact_match(
+    workspaces: List[Workspace], name: str
+) -> Optional[Workspace]:
+    matches = [w for w in workspaces if w.name == name]
+    if len(matches) > 1:
+        raise ValueError(
+            f"Workspace name {name!r} is ambiguous: matched"
+            f" {len(matches)} workspaces; please use workspace_id instead."
+        )
+    return matches[0] if matches else None
+
+
+def _raise_for_tea_exception(e: Exception) -> None:
+    if isinstance(e, ClientException):
+        raise ClientError(
+            e.status_code,
+            pydash.get(e, "data.message", pydash.get(e, "message", "")),
+            pydash.get(e, "data.requestId", ""),
+            pydash.get(e, "data.code", ""),
+        ) from e
+    if isinstance(e, ServerException):
+        raise ServerError(
+            e.status_code,
+            pydash.get(e, "data.message", pydash.get(e, "message", "")),
+            pydash.get(e, "data.requestId", ""),
+            pydash.get(e, "data.code", ""),
+        ) from e
+
+
+class _WorkspaceResolver(ControlAPI):
+    """轻量封装：复用 ControlAPI 拿底层 AgentRun client。"""
+
+    def resolve(self, name: str, config: Optional[Config] = None) -> str:
+        if not name:
+            raise ValueError("workspace_name must be non-empty")
+
+        cfg = Config.with_configs(self.config, config)
+        cache_key = _cache_key(cfg, name)
+        if cache_key in _RESOLVE_CACHE:
+            return _RESOLVE_CACHE[cache_key]
+
+        ws = self._lookup_sync(name, config)
+        if ws is None:
+            raise ResourceNotExistError("Workspace", name)
+
+        assert ws.workspace_id is not None
+        _RESOLVE_CACHE[cache_key] = ws.workspace_id
+        return ws.workspace_id
+
+    async def resolve_async(
+        self, name: str, config: Optional[Config] = None
+    ) -> str:
+        if not name:
+            raise ValueError("workspace_name must be non-empty")
+
+        cfg = Config.with_configs(self.config, config)
+        cache_key = _cache_key(cfg, name)
+        if cache_key in _RESOLVE_CACHE:
+            return _RESOLVE_CACHE[cache_key]
+
+        ws = await self._lookup_async(name, config)
+        if ws is None:
+            raise ResourceNotExistError("Workspace", name)
+
+        assert ws.workspace_id is not None
+        _RESOLVE_CACHE[cache_key] = ws.workspace_id
+        return ws.workspace_id
+
+    # --- internal -----------------------------------------------------------
+
+    def _lookup_sync(
+        self, name: str, config: Optional[Config] = None
+    ) -> Optional[Workspace]:
+        client = self._get_client(config)
+        try:
+            response = client.list_workspaces(
+                ListWorkspacesRequest(name=name, page_size="50")
+            )
+        except (ClientException, ServerException) as e:
+            _raise_for_tea_exception(e)
+            raise
+        workspaces = (
+            getattr(getattr(response.body, "data", None), "workspaces", None)
+            or []
+        )
+        return _pick_exact_match(workspaces, name)
+
+    async def _lookup_async(
+        self, name: str, config: Optional[Config] = None
+    ) -> Optional[Workspace]:
+        client = self._get_client(config)
+        try:
+            response = await client.list_workspaces_async(
+                ListWorkspacesRequest(name=name, page_size="50")
+            )
+        except (ClientException, ServerException) as e:
+            _raise_for_tea_exception(e)
+            raise
+        workspaces = (
+            getattr(getattr(response.body, "data", None), "workspaces", None)
+            or []
+        )
+        return _pick_exact_match(workspaces, name)
+
+
+def resolve_workspace_id_by_name(
+    name: str, config: Optional[Config] = None
+) -> str:
+    """同步：根据 workspace name 解析出 workspace_id。
+
+    Raises:
+        ValueError: ``name`` 为空，或在该账号下存在重名 workspace。
+        ResourceNotExistError: 该账号下未找到同名 workspace。
+    """
+
+    return _WorkspaceResolver(config).resolve(name, config)
+
+
+async def resolve_workspace_id_by_name_async(
+    name: str, config: Optional[Config] = None
+) -> str:
+    """异步：根据 workspace name 解析出 workspace_id。"""
+
+    return await _WorkspaceResolver(config).resolve_async(name, config)
+
+
+def resolve_workspace_ids_by_names(
+    names: str, config: Optional[Config] = None
+) -> str:
+    """同步：将逗号分隔的多个 workspace 名称解析为逗号分隔的 workspace_id 列表。"""
+
+    return ",".join(
+        resolve_workspace_id_by_name(n.strip(), config)
+        for n in names.split(",")
+        if n.strip()
+    )
+
+
+async def resolve_workspace_ids_by_names_async(
+    names: str, config: Optional[Config] = None
+) -> str:
+    """异步：将逗号分隔的多个 workspace 名称解析为逗号分隔的 workspace_id 列表。"""
+
+    out: List[str] = []
+    for n in names.split(","):
+        n = n.strip()
+        if not n:
+            continue
+        out.append(await resolve_workspace_id_by_name_async(n, config))
+    return ",".join(out)
+
+
+def _clear_cache_for_tests() -> None:
+    """仅供单测使用：清空内部解析缓存。"""
+
+    _RESOLVE_CACHE.clear()
+
+
+__all__ = [
+    "resolve_workspace_id_by_name",
+    "resolve_workspace_id_by_name_async",
+    "resolve_workspace_ids_by_names",
+    "resolve_workspace_ids_by_names_async",
+]