Merge remote-tracking branch 'origin/main'

# Conflicts:
#	src/agentscope_runtime/engine/services/agent_state/redis_state_service.py
#	src/agentscope_runtime/engine/services/memory/redis_memory_service.py

Author: zhilingluo

cookbook/en/cli.md

@@ -579,6 +579,7 @@ agentscope deploy k8s SOURCE [OPTIONS]
 | `--deploy-timeout` | integer | `300` | Deployment timeout in seconds |
 | `--health-check` | flag | `None` | Enable/disable health check |
 | `--platform` | string | `"linux/amd64"` | Target platform (e.g., 'linux/amd64', 'linux/arm64') |
+| `--pypi-mirror` | string | `None` | PyPI mirror URL for pip package installation (e.g., 'https://pypi.tuna.tsinghua.edu.cn/simple'). If not specified, uses pip default |
 
 ##### Prerequisites
 

cookbook/en/deployment.md

@@ -24,6 +24,7 @@ Most deployments follow these stages:
 - Access to at least one LLM provider (DashScope, OpenAI, or self-hosted inference).
 - Permissions for the target platform (local machine, Docker, Kubernetes, etc.).
 - Access grants for tool/sandbox resources such as browser automation, file systems, or bespoke services.
+- (Optional) Custom PyPI mirror URL if deploying in regions with restricted or slow access to the default PyPI index. This can significantly speed up Docker image builds, especially in China or corporate networks.
 
 ## Section Guide
 

cookbook/zh/cli.md

@@ -578,6 +578,7 @@ agentscope deploy k8s SOURCE [OPTIONS]
 | `--deploy-timeout` | integer | `300` | 部署超时时间（秒） |
 | `--health-check` | flag | `None` | 启用/禁用健康检查 |
 | `--platform` | string | `"linux/amd64"` | 目标平台（例如 'linux/amd64'、'linux/arm64'） |
+| `--pypi-mirror` | string | `None` | PyPI 镜像源 URL，用于 pip 包安装（例如 'https://pypi.tuna.tsinghua.edu.cn/simple'）。如果未指定，使用 pip 默认源 |
 
 ##### 前置要求
 

cookbook/zh/deployment.md

@@ -24,6 +24,7 @@
 - 至少一个可用的大模型接入（例如 DashScope、OpenAI 或自建推理服务）。
 - 目标部署平台（本地、Docker、Kubernetes 等）的访问与权限。
 - 对应的工具/沙箱权限，如浏览器自动化、文件系统或自定义工具服务。
+- （可选）如果在访问默认 PyPI 受限或速度较慢的区域（如中国或企业网络）部署，可配置自定义 PyPI 镜像源 URL，这可以显著加速 Docker 镜像构建。
 
 ## 子章节导读
 

src/agentscope_runtime/cli/commands/deploy.py

@@ -828,6 +828,13 @@ def agentrun(
     help="Target platform (e.g., 'linux/amd64', 'linux/arm64')",
     default="linux/amd64",
 )
+@click.option(
+    "--pypi-mirror",
+    help="PyPI mirror URL for pip package installation (e.g., "
+    "https://pypi.tuna.tsinghua.edu.cn/simple). If not specified, "
+    "uses pip default.",
+    default=None,
+)
 def k8s(
     source: str,
     name: str,
@@ -854,6 +861,7 @@ def k8s(
     deploy_timeout: int,
     health_check: bool,
     platform: str,
+    pypi_mirror: str,
 ):
     """
     Deploy to Kubernetes/ACK.
@@ -898,6 +906,7 @@ def k8s(
             "deploy_timeout": deploy_timeout,
             "health_check": health_check,
             "platform": platform,
+            "pypi_mirror": pypi_mirror,
         }
         merged_config = _merge_config(config_dict, cli_params)
 
@@ -918,6 +927,7 @@ def k8s(
         deploy_timeout = merged_config.get("deploy_timeout", 300)
         health_check = merged_config.get("health_check", True)
         platform = merged_config.get("platform")
+        pypi_mirror = merged_config.get("pypi_mirror")
 
         # Handle requirements (can be comma-separated string, list, or file
         # path)
@@ -1033,6 +1043,8 @@ def k8s(
             deploy_params["health_check"] = health_check
         if platform:
             deploy_params["platform"] = platform
+        if pypi_mirror:
+            deploy_params["pypi_mirror"] = pypi_mirror
 
         # Add agent_source for state saving
         deploy_params["agent_source"] = abs_source

src/agentscope_runtime/engine/deployers/kubernetes_deployer.py

@@ -144,6 +144,7 @@ async def deploy(
         image_tag: str = "latest",
         push_to_registry: bool = False,
         use_cache: bool = True,
+        pypi_mirror: Optional[str] = None,
         **kwargs,
     ) -> Dict[str, Any]:
         """
@@ -170,6 +171,7 @@ async def deploy(
             mount_dir: Mount directory
             runtime_config: K8s runtime configuration
             use_cache: Enable build cache (default: True)
+            pypi_mirror: PyPI mirror URL for pip package installation
             # Backward compatibility
             image_name: Image name
             image_tag: Image tag
@@ -209,6 +211,7 @@ async def deploy(
                     protocol_adapters=protocol_adapters,
                     custom_endpoints=custom_endpoints,
                     use_cache=use_cache,
+                    pypi_mirror=pypi_mirror,
                     **kwargs,
                 )
                 if not built_image_name:

src/agentscope_runtime/engine/deployers/utils/docker_image_utils/dockerfile_generator.py

@@ -22,6 +22,7 @@ class DockerfileConfig(BaseModel):
     health_check_endpoint: str = "/health"
     custom_template: Optional[str] = None
     platform: Optional[str] = None
+    pypi_mirror: Optional[str] = None
 
 
 class DockerfileGenerator:
@@ -73,8 +74,7 @@ class DockerfileGenerator:
 # Install Python dependencies
 RUN pip install --no-cache-dir --upgrade pip
 RUN if [ -f requirements.txt ]; then \\
-        pip install --no-cache-dir -r requirements.txt \\
-        -i https://pypi.tuna.tsinghua.edu.cn/simple; fi
+        pip install --no-cache-dir -r requirements.txt{pypi_mirror_flag}; fi
 
 # Create non-root user for security
 RUN adduser --disabled-password --gecos '' {user} && \\
@@ -136,6 +136,11 @@ def generate_dockerfile_content(self, config: DockerfileConfig) -> str:
                 f'"--port", "{config.port}"]'
             )
 
+        # Prepare PyPI mirror flag
+        pypi_mirror_flag = ""
+        if config.pypi_mirror:
+            pypi_mirror_flag = f" -i {config.pypi_mirror}"
+
         # Format template with configuration values
         content = template.format(
             base_image=config.base_image,
@@ -147,6 +152,7 @@ def generate_dockerfile_content(self, config: DockerfileConfig) -> str:
             env_vars_section=env_vars_section,
             startup_command_section=startup_command_section,
             platform=config.platform,
+            pypi_mirror_flag=pypi_mirror_flag,
         )
 
         return content

src/agentscope_runtime/engine/deployers/utils/docker_image_utils/image_factory.py

@@ -40,6 +40,7 @@ class ImageConfig(BaseModel):
     port: int = 8000
     env_vars: Dict[str, str] = Field(default_factory=lambda: {})
     startup_command: Optional[str] = None
+    pypi_mirror: Optional[str] = None
 
     # Runtime configuration
     host: str = "0.0.0.0"  # Container-friendly default
@@ -218,6 +219,7 @@ def _build_image(
                 env_vars=config.env_vars,
                 startup_command=startup_command,
                 platform=config.platform,
+                pypi_mirror=config.pypi_mirror,
             )
 
             dockerfile_path = self.dockerfile_generator.create_dockerfile(
@@ -314,6 +316,7 @@ def build_image(
         embed_task_processor: bool = True,
         extra_startup_args: Optional[Dict[str, Union[str, int, bool]]] = None,
         use_cache: bool = True,
+        pypi_mirror: Optional[str] = None,
         **kwargs,
     ) -> str:
         """
@@ -339,6 +342,7 @@ def build_image(
             embed_task_processor: Whether to embed task processor
             extra_startup_args: Additional startup arguments
             use_cache: Enable build cache (default: True)
+            pypi_mirror: PyPI mirror URL for pip package installation
             **kwargs: Additional configuration options
 
         Returns:
@@ -373,6 +377,7 @@ def build_image(
             host=host,
             embed_task_processor=embed_task_processor,
             extra_startup_args=extra_startup_args or {},
+            pypi_mirror=pypi_mirror,
             **kwargs,
         )
 

src/agentscope_runtime/engine/services/agent_state/state_service_factory.py

@@ -43,13 +43,10 @@ class StateServiceFactory(ServiceFactory[StateService]):
 
 StateServiceFactory.register_backend(
     "in_memory",
-    lambda **kwargs: InMemoryStateService(),
+    InMemoryStateService,
 )
 
 StateServiceFactory.register_backend(
     "redis",
-    lambda **kwargs: RedisStateService(
-        redis_url=kwargs.get("redis_url", "redis://localhost:6379/0"),
-        redis_client=kwargs.get("redis_client"),
-    ),
+    RedisStateService,
 )