feat(sandbox): add NAS, OSS, and PolarFS configuration support with multi-language docs

This commit introduces comprehensive storage configuration capabilities for sandbox environments, including NAS mount configurations, OSS mount points, and PolarFS filesystem support. The changes span across multiple files to enhance the sandbox creation API with new configuration options and improve documentation with bilingual comments.

The modifications include:
- Adding new model classes for NAS, OSS, and PolarFS configurations
- Extending sandbox creation methods with optional storage parameters
- Enhancing API endpoints to support new configuration options
- Adding bilingual documentation (Chinese/English) for improved usability
- Updating template files to reflect the new configuration parameters

New features include the ability to specify NAS mount points with TLS encryption, OSS bucket mount points with read-only options, and PolarFS filesystem configurations during sandbox creation. Additionally, the commit includes workflow documentation for adding parameters to specific modules.

此提交为沙箱环境引入了全面的存储配置功能，包括 NAS 挂载配置、OSS 挂载点和 PolarFS 文件系统支持。这些更改跨越多个文件，以使用新的配置选项增强沙箱创建 API，并使用双语注释改进文档。

修改包括：
- 为 NAS、OSS 和 PolarFS 配置添加新的模型类
- 使用可选存储参数扩展沙箱创建方法
- 增强 API 端点以支持新配置选项
- 添加双语文档（中文/英文）以提高可用性
- 更新模板文件以反映新的配置参数

新功能包括在沙箱创建期间指定具有 TLS 加密的 NAS 挂载点、具有只读选项的 OSS 存储桶挂载点以及 PolarFS 文件系统配置的能力。此外，提交还包括为特定模块添加参数的工作流程文档。

Change-Id: I2c16129da2d4c21ccf4f495c0c6fe62737af933c
Signed-off-by: OhYee <[email protected]>

Author: OhYee

AGENTS.md

@@ -447,3 +447,27 @@ A: 建议：
 - [Python SDK 文档](./python/README.md)
 - [示例代码](./python/examples/)
 - [阿里云 AgentRun 官方文档](https://help.aliyun.com/zh/agentrun/)
+
+## 工作流程
+
+### 为特定模块增加参数
+
+名词解释
+- AgentRun SDK：当前项目
+- 底层 SDK：我们会依赖底层 SDK 与平台进行交互，如果是 python sdk，则为 `agentrun-20250910`；如果是 nodejs sdk，则为 `@alicloud/agentrun20250910`
+- 要修改模块：sandbox、model 等
+
+此时，应该遵循如下流程
+
+该模块的代码位于 ${component} 目录，包含如下部分
+- api/ 							和底层 SDK 交互的逻辑。你可以根据该文件的调用方式，跳转到底层 sdk 的逻辑，进行检查
+- client 						为用户封装的客户端，你需要检查一下是否需要修改
+- model							相关类型描述，你需要严格检查当前文件是否需要修改，这里可能存在大量修改
+- 其他文件						你也需要一并检查，如果是 nodejs sdk，需要检查 class 的属性
+- _xxx_async_template.py 		python sdk 中生成 xxx.py 文件的模板，只需要声明 async 即可（使用 `make codegen` 进行生成）
+
+1. 请严格检查底层 SDK 的输入、输出参数，并对照现有类型定义，整理出新增的参数列表
+2. 根据新增的参数列表，在 agentrun sdk 中进行修改，补充对应的中英文注释
+3. 执行相关模块的 ut 测试，确保可以正确执行
+4. 进行修改内容的总结汇报
+5. 根据汇报内容进行检查，重新检查底层 SDK 和 AgentRun SDK 的定义

agentrun/sandbox/__client_async_template.py

@@ -5,7 +5,7 @@
 """
 
 import time
-from typing import List, Optional, TYPE_CHECKING
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
 
 from alibabacloud_agentrun20250910.models import (
     CreateTemplateInput,
@@ -18,7 +18,11 @@
 from agentrun.sandbox.model import (
     ListSandboxesInput,
     ListSandboxesOutput,
+    NASConfig,
+    OSSMountConfig,
     PageableInput,
+    PolarFsConfig,
+    SandboxInput,
     TemplateInput,
 )
 from agentrun.utils.config import Config
@@ -273,25 +277,50 @@ async def create_sandbox_async(
         self,
         template_name: str,
         sandbox_idle_timeout_seconds: Optional[int] = 600,
+        sandbox_id: Optional[str] = None,
+        nas_config: Optional[NASConfig] = None,
+        oss_mount_config: Optional[OSSMountConfig] = None,
+        polar_fs_config: Optional[PolarFsConfig] = None,
         config: Optional[Config] = None,
     ) -> Sandbox:
-        """创建 Sandbox（异步）
+        """创建 Sandbox（异步） / Create Sandbox (async)
 
         Args:
-            input: Sandbox 配置
-            config: 配置对象
+            template_name: 模板名称 / Template name
+            sandbox_idle_timeout_seconds: 沙箱空闲超时时间（秒） / Sandbox idle timeout (seconds)
+            sandbox_id: 沙箱 ID（可选） / Sandbox ID (optional)
+            nas_config: NAS 配置 / NAS configuration
+            oss_mount_config: OSS 挂载配置 / OSS mount configuration
+            polar_fs_config: PolarFS 配置 / PolarFS configuration
+            config: 配置对象 / Config object
 
         Returns:
-            Sandbox: 创建的 Sandbox 对象
+            Sandbox: 创建的 Sandbox 对象 / Created Sandbox object
 
         Raises:
-            ClientError: 客户端错误
-            ServerError: 服务器错误
+            ClientError: 客户端错误 / Client error
+            ServerError: 服务器错误 / Server error
         """
+        # 将配置对象转换为字典格式
+        nas_config_dict: Optional[Dict[str, Any]] = None
+        if nas_config is not None:
+            nas_config_dict = nas_config.model_dump(by_alias=True)
+
+        oss_mount_config_dict: Optional[Dict[str, Any]] = None
+        if oss_mount_config is not None:
+            oss_mount_config_dict = oss_mount_config.model_dump(by_alias=True)
+
+        polar_fs_config_dict: Optional[Dict[str, Any]] = None
+        if polar_fs_config is not None:
+            polar_fs_config_dict = polar_fs_config.model_dump(by_alias=True)
 
         result = await self.__sandbox_data_api.create_sandbox_async(
             template_name=template_name,
             sandbox_idle_timeout_seconds=sandbox_idle_timeout_seconds,
+            sandbox_id=sandbox_id,
+            nas_config=nas_config_dict,
+            oss_mount_config=oss_mount_config_dict,
+            polar_fs_config=polar_fs_config_dict,
             config=config,
         )
 
@@ -309,6 +338,34 @@ async def create_sandbox_async(
         data = result.get("data", {})
         return Sandbox.model_validate(data, by_alias=True)
 
+    async def create_sandbox_with_input_async(
+        self,
+        input: SandboxInput,
+        config: Optional[Config] = None,
+    ) -> Sandbox:
+        """使用 SandboxInput 创建 Sandbox（异步） / Create Sandbox with SandboxInput (async)
+
+        Args:
+            input: Sandbox 创建配置 / Sandbox creation configuration
+            config: 配置对象 / Config object
+
+        Returns:
+            Sandbox: 创建的 Sandbox 对象 / Created Sandbox object
+
+        Raises:
+            ClientError: 客户端错误 / Client error
+            ServerError: 服务器错误 / Server error
+        """
+        return await self.create_sandbox_async(
+            template_name=input.template_name,
+            sandbox_idle_timeout_seconds=input.sandbox_idle_timeout_seconds,
+            sandbox_id=input.sandbox_id,
+            nas_config=input.nas_config,
+            oss_mount_config=input.oss_mount_config,
+            polar_fs_config=input.polar_fs_config,
+            config=config,
+        )
+
     async def stop_sandbox_async(
         self, sandbox_id: str, config: Optional[Config] = None
     ) -> Sandbox:

agentrun/sandbox/__sandbox_async_template.py

@@ -4,7 +4,16 @@
 This module defines the high-level API for sandbox resources.
 """
 
-from typing import List, Literal, Optional, overload, TYPE_CHECKING, Union
+from typing import (
+    Any,
+    Dict,
+    List,
+    Literal,
+    Optional,
+    overload,
+    TYPE_CHECKING,
+    Union,
+)
 
 from agentrun.sandbox.model import TemplateType
 from agentrun.utils.config import Config
@@ -32,23 +41,29 @@ class Sandbox(BaseModel):
     _template_type: Optional[TemplateType]
 
     created_at: Optional[str] = None
-    """沙箱创建时间"""
+    """沙箱创建时间 / Sandbox creation time"""
+    ended_at: Optional[str] = None
+    """沙箱结束时间 / Sandbox end time"""
     last_updated_at: Optional[str] = None
-    """最后更新时间"""
+    """最后更新时间 / Last updated time"""
+    metadata: Optional[Dict[str, Any]] = None
+    """元数据 / Metadata"""
     sandbox_arn: Optional[str] = None
-    """沙箱全局唯一资源名称"""
+    """沙箱全局唯一资源名称 / Sandbox ARN"""
     sandbox_id: Optional[str] = None
-    """沙箱 ID"""
+    """沙箱 ID / Sandbox ID"""
+    sandbox_idle_ttlin_seconds: Optional[int] = None
+    """沙箱空闲 TTL（秒） / Sandbox Idle TTL (seconds)"""
     sandbox_idle_timeout_seconds: Optional[int] = None
-    """沙箱空闲超时时间（秒）"""
+    """沙箱空闲超时时间（秒） / Sandbox Idle Timeout (seconds)"""
     status: Optional[str] = None
-    """沙箱状态"""
+    """沙箱状态 / Sandbox status"""
     template_id: Optional[str] = None
-    """模板 ID"""
+    """模板 ID / Template ID"""
     template_name: Optional[str] = None
-    """模板名称"""
+    """模板名称 / Template name"""
     _config: Optional[Config] = None
-    """配置对象，用于子类的 data_api 初始化"""
+    """配置对象，用于子类的 data_api 初始化 / Config object for data_api initialization"""
 
     @classmethod
     def __get_client(cls):

agentrun/sandbox/__template_async_template.py

@@ -29,59 +29,61 @@ class Template(BaseModel):
     """
 
     template_id: Optional[str] = None
-    """模板 ID"""
+    """模板 ID / Template ID"""
     template_name: Optional[str] = None
-    """模板名称"""
+    """模板名称 / Template Name"""
     template_version: Optional[str] = None
-    """模板版本"""
+    """模板版本 / Template Version"""
     template_arn: Optional[str] = None
-    """模板 ARN"""
+    """模板 ARN / Template ARN"""
     resource_name: Optional[str] = None
-    """资源名称"""
+    """资源名称 / Resource Name"""
     template_type: Optional[TemplateType] = None
-    """模板类型"""
+    """模板类型 / Template Type"""
     cpu: Optional[float] = None
-    """CPU 核数"""
+    """CPU 核数 / CPU Cores"""
     memory: Optional[int] = None
-    """内存大小（MB）"""
+    """内存大小（MB） / Memory Size (MB)"""
     disk_size: Optional[int] = None
-    """磁盘大小（GB）"""
+    """磁盘大小（GB） / Disk Size (GB)"""
     description: Optional[str] = None
-    """描述"""
+    """描述 / Description"""
     execution_role_arn: Optional[str] = None
-    """执行角色 ARN"""
+    """执行角色 ARN / Execution Role ARN"""
     sandbox_idle_timeout_in_seconds: Optional[int] = None
-    """沙箱空闲超时时间（秒）"""
+    """沙箱空闲超时时间（秒） / Sandbox Idle Timeout (seconds)"""
     sandbox_ttlin_seconds: Optional[int] = None
-    """沙箱存活时间（秒）"""
+    """沙箱存活时间（秒） / Sandbox TTL (seconds)"""
     share_concurrency_limit_per_sandbox: Optional[int] = None
-    """每个沙箱的最大并发会话数"""
+    """每个沙箱的最大并发会话数 / Max Concurrency Limit Per Sandbox"""
     template_configuration: Optional[Dict] = None
-    """模板配置"""
+    """模板配置 / Template Configuration"""
     environment_variables: Optional[Dict] = None
-    """环境变量"""
+    """环境变量 / Environment Variables"""
     network_configuration: Optional[TemplateNetworkConfiguration] = None
-    """网络配置"""
+    """网络配置 / Network Configuration"""
     oss_configuration: Optional[List[TemplateOssConfiguration]] = None
-    """OSS 配置列表"""
+    """OSS 配置列表 / OSS Configuration List"""
     log_configuration: Optional[TemplateLogConfiguration] = None
-    """日志配置"""
+    """日志配置 / Log Configuration"""
     credential_configuration: Optional[TemplateCredentialConfiguration] = None
-    """凭证配置"""
+    """凭证配置 / Credential Configuration"""
     container_configuration: Optional[TemplateContainerConfiguration] = None
-    """容器配置"""
+    """容器配置 / Container Configuration"""
     mcp_options: Optional[TemplateMcpOptions] = None
-    """MCP 选项"""
+    """MCP 选项 / MCP Options"""
     mcp_state: Optional[TemplateMcpState] = None
-    """MCP 状态"""
+    """MCP 状态 / MCP State"""
+    allow_anonymous_manage: Optional[bool] = None
+    """是否允许匿名管理 / Whether to allow anonymous management"""
     created_at: Optional[str] = None
-    """创建时间"""
+    """创建时间 / Creation Time"""
     last_updated_at: Optional[str] = None
-    """最后更新时间"""
+    """最后更新时间 / Last Updated Time"""
     status: Optional[str] = None
-    """状态"""
+    """状态 / Status"""
     status_reason: Optional[str] = None
-    """状态原因"""
+    """状态原因 / Status Reason"""
 
     @classmethod
     def __get_client(cls, config: Optional[Config] = None):

agentrun/sandbox/api/__sandbox_data_async_template.py

@@ -4,7 +4,7 @@
 This template is used to generate sandbox data API code.
 """
 
-from typing import Optional
+from typing import Any, Dict, Optional
 
 from agentrun.utils.config import Config
 from agentrun.utils.data_api import DataAPI, ResourceType
@@ -70,16 +70,26 @@ async def create_sandbox_async(
         self,
         template_name: str,
         sandbox_idle_timeout_seconds: Optional[int] = 600,
+        sandbox_id: Optional[str] = None,
+        nas_config: Optional[Dict[str, Any]] = None,
+        oss_mount_config: Optional[Dict[str, Any]] = None,
+        polar_fs_config: Optional[Dict[str, Any]] = None,
         config: Optional[Config] = None,
     ):
         self.__refresh_access_token(template_name=template_name, config=config)
-        return await self.post_async(
-            "/",
-            data={
-                "templateName": template_name,
-                "sandboxIdleTimeoutSeconds": sandbox_idle_timeout_seconds,
-            },
-        )
+        data: Dict[str, Any] = {
+            "templateName": template_name,
+            "sandboxIdleTimeoutSeconds": sandbox_idle_timeout_seconds,
+        }
+        if sandbox_id is not None:
+            data["sandboxId"] = sandbox_id
+        if nas_config is not None:
+            data["nasConfig"] = nas_config
+        if oss_mount_config is not None:
+            data["ossMountConfig"] = oss_mount_config
+        if polar_fs_config is not None:
+            data["polarFsConfig"] = polar_fs_config
+        return await self.post_async("/", data=data)
 
     async def delete_sandbox_async(
         self, sandbox_id: str, config: Optional[Config] = None