agentengine-sdk-python 0.7.0__py3-none-any.whl → 0.8.1__py3-none-any.whl

ksadk/deployment/providers/serverless.py

@@ -6,38 +6,38 @@ Serverless Provider - 金山云 Serverless 计算引擎 (AgentEngine 托管)
 - Deploy 阶段: 客户端调用 AgentEngine Server API 发起部署
 """
 
-import os
 import json
 import logging
-import shutil
+import os
 import time
-import yaml
 from pathlib import Path
-from typing import Dict, Any, List, Optional
+from typing import Any, Dict, List, Optional
+
 import click
+import yaml
 
-from ksadk.builders.ks3_uploader import KS3Uploader
+from ksadk.api import AgentEngineClient, DryRunExit
+from ksadk.builders.base import BaseBuilder
 from ksadk.builders.code_builder import CodeBuilder
+from ksadk.builders.container_builder import (
+    ContainerBuilder,
+    registry_kind_label,
+    resolve_registry_credentials,
+)
+from ksadk.builders.ks3_uploader import KS3Uploader
+from ksadk.configs.env_registry import ENV_VAR_REGISTRY
+from ksadk.configs.global_config import get_env_from_global_config
+from ksadk.configs.settings import DEFAULT_RUNTIME_TIMEZONE
 from ksadk.deployment.agent_access import get_latest_agent_access
 from ksadk.deployment.base import (
     BaseDeployProvider,
-    DeployTarget,
     DeployResult,
     DeployStatus,
+    DeployTarget,
     PackageInfo,
 )
 from ksadk.deployment.registry import DeployProviderRegistry
 from ksadk.deployment.ui_config import resolve_ui_config, ui_config_to_state_fields
-from ksadk.builders.container_builder import (
-    ContainerBuilder,
-    registry_kind_label,
-    resolve_registry_credentials,
-)
-from ksadk.configs.settings import DEFAULT_RUNTIME_TIMEZONE
-from ksadk.configs.env_registry import ENV_VAR_REGISTRY
-from ksadk.configs.global_config import get_env_from_global_config
-from ksadk.api import AgentEngineClient, DryRunExit
-
 
 logger = logging.getLogger(__name__)
 
@@ -71,11 +71,7 @@ _DEPLOY_PROCESS_ENV_ALLOWLIST = frozenset(
 )
 _DEPLOY_PROCESS_ENV_PREFIXES = ("KSADK_", "OPENAI_", "KSYUN_", "E2B_")
 _DEPLOY_PROCESS_ENV_DENYLIST = frozenset(
-    {
-        spec.name
-        for spec in ENV_VAR_REGISTRY
-        if spec.module in {"builders", "cli", "configs", "web"}
-    }
+    {spec.name for spec in ENV_VAR_REGISTRY if spec.module in {"builders", "cli", "configs", "web"}}
 ) | frozenset(
     {
         "KSADK_GLOBAL_CONFIG_ENV_KEYS",
@@ -96,7 +92,7 @@ def _should_forward_process_env(name: str) -> bool:
 @DeployProviderRegistry.register("kce")
 class ServerlessProvider(BaseDeployProvider):
     """金山云 Serverless 计算引擎 (AgentEngine Server 托管)
-    
+
     重构后直接继承 BaseDeployProvider，不再依赖 DockerProvider。
     Container 模式使用 ContainerBuilder 进行打包和构建。
     """
@@ -109,7 +105,7 @@ class ServerlessProvider(BaseDeployProvider):
     supports_scaling = True
     requires_image_registry = False
 
-    def __init__(self, config: Dict[str, Any] = None):
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
         self.config = config or {}
 
     @staticmethod
@@ -124,13 +120,15 @@ class ServerlessProvider(BaseDeployProvider):
 
         if password and not username and registry_kind != "personal_kcr":
             click.secho(
-                f"   ⚠️  检测到 KCR_PASSWORD 但缺少 KCR_USERNAME，已忽略{registry_kind_label(registry_kind)}镜像凭证；"
+                f"   ⚠️  检测到 KCR_PASSWORD 但缺少 KCR_USERNAME，"
+                f"已忽略{registry_kind_label(registry_kind)}镜像凭证；"
                 "企业版 KCR 和第三方镜像仓库必须配置 KCR_USERNAME + KCR_PASSWORD",
                 fg="yellow",
             )
         elif registry_kind == "personal_kcr":
             click.secho(
-                "   ⚠️  未配置个人版 KCR 镜像凭证 (KSYUN_ACCOUNT_ID/KCR_PASSWORD)，私有镜像可能无法拉取",
+                "   ⚠️  未配置个人版 KCR 镜像凭证 "
+                "(KSYUN_ACCOUNT_ID/KCR_PASSWORD)，私有镜像可能无法拉取",
                 fg="yellow",
             )
         else:
@@ -196,19 +194,25 @@ class ServerlessProvider(BaseDeployProvider):
     ) -> tuple[Dict[str, str], bool, int]:
         """读取部署时注入到托管运行时的环境变量。
 
-        全局配置作为兜底，项目 .env 作为项目级覆盖；真实 .env 文件不会随
-        Code/Container 制品打包，只通过 deploy payload 注入到 Pod 环境变量。
+        优先级: --env/--env-file (explicit) > shell env (转发白名单前缀) > 项目 .env > 全局配置。
+        真实 .env 文件不会随 Code/Container 制品打包，只通过 deploy payload 注入到 Pod 环境变量。
         """
+        shell_keys = set(os.environ)
         env_vars: Dict[str, str] = dict(get_env_from_global_config())
         env_file = Path(project_dir) / ".env"
         project_env_count = 0
-        for key, value in sorted(os.environ.items()):
-            if value and _should_forward_process_env(key):
-                env_vars.setdefault(key, value)
         if env_file.exists():
             project_env = cls._load_project_env_vars(env_file)
             project_env_count = len(project_env)
-            env_vars.update(project_env)
+            # auto .env 覆盖 global_config，但不覆盖 shell (shell 优先于 auto .env)
+            for key, value in project_env.items():
+                if key not in shell_keys:
+                    env_vars[key] = value
+        # shell 转发 (仅 KSADK_/OPENAI_/KSYUN_/E2B_ 前缀 + 白名单)；shell 覆盖 auto .env 与全局配置
+        for key, value in sorted(os.environ.items()):
+            if value and _should_forward_process_env(key):
+                env_vars[key] = value
+        # explicit --env/--env-file (显式 CLI 意图最高)
         env_vars.update(explicit_env_vars or {})
         env_vars.setdefault("TZ", DEFAULT_RUNTIME_TIMEZONE)
         return env_vars, env_file.exists(), project_env_count
@@ -269,7 +273,7 @@ class ServerlessProvider(BaseDeployProvider):
             return None
 
         public_access = getattr(network, "enable_public_access", None)
-        # 三态：None=未指定。create 默认开公网；update 未指定则不发 network 字段（保留服务端现有配置）。
+        # 三态：None=未指定。create 默认开公网；update 未指定则不发 network 字段。
         if public_access is None:
             public_value: Optional[bool] = None if is_update else True
         else:
@@ -317,19 +321,19 @@ class ServerlessProvider(BaseDeployProvider):
         seconds = int(elapsed % 60)
         return f"{minutes}m{seconds:02d}s"
 
-
     async def validate_config(self, target: DeployTarget) -> tuple[bool, str]:
         """验证配置: 确保已配置 AgentEngine Server"""
-        
+
         server_url = os.getenv("AGENTENGINE_SERVER_URL")
-        
+
         if not server_url:
             click.echo("⚠️  未配置 AGENTENGINE_SERVER_URL，将尝试使用默认 Region 配置")
-        
+
         # Container 模式: 检查 Docker 是否可用
         artifact_type = target.extra.get("artifact_type", "Code")
         if artifact_type == "Container":
             import subprocess
+
             try:
                 result = subprocess.run(["docker", "version"], capture_output=True, timeout=10)
                 if result.returncode != 0:
@@ -341,14 +345,19 @@ class ServerlessProvider(BaseDeployProvider):
 
         return True, ""
 
-    async def package(self, project_dir: str, detection_result: Any, config: Dict[str, Any] = None) -> PackageInfo:
+    async def package(
+        self,
+        project_dir: str,
+        detection_result: Any,
+        config: Optional[Dict[str, Any]] = None,
+    ) -> PackageInfo:
         """打包项目
-        
+
         Code 模式: 返回基本 PackageInfo，实际构建在 build() 中进行
         Container 模式: 使用 ContainerBuilder 打包
         """
         project_path = Path(project_dir)
-        
+
         # 创建基本 PackageInfo
         package_info = PackageInfo(
             name=detection_result.name or project_path.name,
@@ -356,14 +365,15 @@ class ServerlessProvider(BaseDeployProvider):
             build_dir=str(project_path / ".agentengine" / "build"),
             project_dir=str(project_path),
             entry_point=detection_result.entry_point,
-            metadata={}
+            metadata={},
         )
-        
+
         # 尝试加载之前保存的构建元数据 (ks3_path 等)
         try:
             metadata_file = project_path / ".agentengine" / "build-metadata.json"
             if metadata_file.exists():
                 import json
+
                 with open(metadata_file, "r") as f:
                     saved_data = json.load(f)
                     if "metadata" in saved_data:
@@ -376,15 +386,18 @@ class ServerlessProvider(BaseDeployProvider):
                             click.echo(f"   📦 已加载上次构建元数据: {count} 项")
         except Exception as e:
             click.secho(f"⚠️  加载构建元数据失败: {e}", fg="yellow")
-            
-        return package_info
-
 
+        return package_info
 
     async def build(self, package_info: PackageInfo, target: DeployTarget) -> PackageInfo:
         """构建 & 上传 (客户端直传 KS3)"""
         artifact_type = target.extra.get("artifact_type", "Code")
 
+        if artifact_type == "ManagedRuntime":
+            from ksadk.deployment.managed_runtime import build_managed_runtime_package
+
+            return build_managed_runtime_package(package_info, target)
+
         if artifact_type == "Code":
             # 1. 检查是否已有 KS3 路径
             # 优先级: CLI传入 > Metadata缓存 (仅当 !no_cache)
@@ -392,58 +405,77 @@ class ServerlessProvider(BaseDeployProvider):
             cached_ks3_path = package_info.metadata.get("ks3_path")
             no_cache = target.extra.get("no_cache", False)
             repackage = target.extra.get("repackage", False)
-            
+
             # 如果显式传入了 ks3-path，直接使用
             if cli_ks3_path:
                 package_info.metadata["ks3_path"] = cli_ks3_path
                 return package_info
-            
+
             # 如果没有 no_cache 且有缓存，才使用缓存
             if not no_cache and not repackage and cached_ks3_path:
                 logger.info(f"Using cached bundle: {cached_ks3_path}")
                 return package_info
 
-            # 2. 构建 ZIP 包 (委托给 CodeBuilder)
-            
+            # 2. 构建 ZIP 包
+
             # 传递配置，包括 no_cache
             builder_config = target.extra.copy()
             builder_config["no_cache"] = no_cache
             builder_config["repackage"] = repackage
-            
-            # 实例化 Builder
-            # 注意: CodeBuilder 目前设计为直接操作 project_dir，
-            # 这里传入原始 project_dir (package_info.project_dir)
-            builder = CodeBuilder(Path(package_info.project_dir), config=builder_config)
-            
+
+            artifact_builder: BaseBuilder
+            if artifact_type == "ManagedRuntime":
+                from ksadk.builders.managed_runtime_builder import ManagedRuntimeBuilder
+
+                artifact_builder = ManagedRuntimeBuilder(
+                    Path(package_info.project_dir),
+                    config=builder_config,
+                    runtime_version=str(target.extra.get("runtime_version") or ""),
+                )
+            else:
+                # CodeBuilder 直接操作原始 project_dir。
+                artifact_builder = CodeBuilder(
+                    Path(package_info.project_dir),
+                    config=builder_config,
+                )
+
             # 执行构建
-            build_result = builder.build()
-            
+            build_result = artifact_builder.build()
+
             if not build_result.success:
                 raise Exception(f"构建失败: {build_result.error_message}")
-                
+
             zip_path = build_result.artifact_path
+            if zip_path is None:
+                raise RuntimeError("代码构建成功但未生成 artifact_path")
+            package_info.metadata.update(build_result.metadata)
+            if build_result.metadata.get("manifest_sha256"):
+                target.extra["manifest_sha256"] = build_result.metadata["manifest_sha256"]
             # click.echo(f"   ✅ ZIP 已生成: {zip_path}")
-            
+
             # 3. 直接上传 KS3 (使用本地 AK/SK)
             # 3. 直接上传 KS3 (使用本地 AK/SK)
-            click.echo("\n正在上传代码包到 KS3...")
+            artifact_label = "Runtime manifest" if artifact_type == "ManagedRuntime" else "代码包"
+            click.echo(f"\n正在上传{artifact_label}到 KS3...")
             upload_started_at = time.monotonic()
-            
+
             ks3_bucket = target.extra.get("ks3_bucket")
             upload_region = "cn-beijing-6" if target.region == "pre-online" else target.region
-            
+
             uploader = KS3Uploader(region=upload_region, bucket=ks3_bucket)
-            
+
             # 使用时间戳确保每次上传的代码包路径唯一，支持真正的版本回滚
             from datetime import datetime
+
             timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
-            object_key = f"agents/{package_info.name}/code_{timestamp}.zip"
-            
+            object_prefix = "runtime" if artifact_type == "ManagedRuntime" else "code"
+            object_key = f"agents/{package_info.name}/{object_prefix}_{timestamp}.zip"
+
             ks3_path = await uploader.upload(zip_path, object_key)
-            
+
             if not ks3_path:
                 raise Exception("KS3 上传失败")
-            
+
             logger.info(f"Upload success: {ks3_path}")
             click.echo(f"   ✓ 上传耗时: {self._format_elapsed(upload_started_at)}")
             package_info.metadata["ks3_path"] = ks3_path
@@ -466,45 +498,47 @@ class ServerlessProvider(BaseDeployProvider):
                 logger.info(f"Using cached image: {cached_image}")
                 package_info.image = cached_image
                 return package_info
-            
-            builder = ContainerBuilder(
+
+            container_builder = ContainerBuilder(
                 project_dir=Path(package_info.project_dir),
                 tag=tag,
                 registry=registry,
-                no_cache=no_cache
+                no_cache=no_cache,
             )
-            
+
             # 构建镜像
-            build_result = builder.build()
+            build_result = container_builder.build()
             if not build_result.success:
                 raise Exception(f"镜像构建失败: {build_result.error_message}")
-            
-            image_name = build_result.metadata.get("image")
+
+            image_name = str(build_result.metadata.get("image") or "").strip()
+            if not image_name:
+                raise RuntimeError("容器构建成功但未生成 image")
             package_info.image = image_name
             package_info.metadata["image"] = image_name
-            
+
             # 推送镜像
-            if not builder.push(image_name):
+            if not container_builder.push(image_name):
                 raise Exception("镜像推送失败")
-            
+
             click.secho(f"✅ 镜像已推送: {image_name}", fg="green")
 
         self._persist_build_metadata(package_info)
-             
+
         return package_info
 
     async def deploy(self, package_info: PackageInfo, target: DeployTarget) -> DeployResult:
         """通过 AgentEngine Server 部署
-        
+
         逻辑:
         - 读取本地 .agentengine.state 文件获取 agent_id
         - 如果有 agent_id → 执行更新 (endpoint 不变)
         - 如果没有 → 创建新 Agent，保存 agent_id 到状态文件
         """
-        
+
         server_url = os.getenv("AGENTENGINE_SERVER_URL")
         click.echo(f"\n🚀 开始部署到 Serverless (Managed by {server_url})...")
-        
+
         # 读取本地状态文件
         project_dir = package_info.project_dir
         state_file = Path(project_dir) / ".agentengine.state"
@@ -527,26 +561,29 @@ class ServerlessProvider(BaseDeployProvider):
             ui_state["ui_bundle_path"] = project_config.get("ui_bundle_path")
         if project_config.get("ui_bundle_dir") and not ui_state.get("ui_bundle_dir"):
             ui_state["ui_bundle_dir"] = project_config.get("ui_bundle_dir")
-        
+
         # 构造请求 payload
         artifact_type = target.extra.get("artifact_type", "Code")
         artifact_path = ""
-        if artifact_type == "Code":
+        code_backed = artifact_type == "Code"
+        if code_backed:
             original_artifact_path = package_info.metadata.get("ks3_path", "")
             artifact_path = original_artifact_path
-            
+
             # 转换为内网地址 (如果 serverless 无法解析 ks3://)
             if artifact_path.startswith("ks3://"):
                 try:
                     from ksadk.common.constants import get_ks3_endpoints
-                    
+
                     # 确定 KS3 Region code (pre-online -> cn-beijing)
                     ks3_region = target.extra.get("ks3_region")
                     if not ks3_region:
-                         ks3_region = "cn-beijing-6" if target.region == "pre-online" else target.region
-                    
+                        ks3_region = (
+                            "cn-beijing-6" if target.region == "pre-online" else target.region
+                        )
+
                     _, internal_endpoint = get_ks3_endpoints(ks3_region)
-                    
+
                     if internal_endpoint:
                         # ks3://bucket/key -> http://bucket.internal_endpoint/key
                         bucket, key = self._parse_code_artifact_path(artifact_path)
@@ -555,32 +592,39 @@ class ServerlessProvider(BaseDeployProvider):
                             click.echo(f"   Converted artifact path: {artifact_path}")
                 except Exception as e:
                     logger.warning(f"Failed to convert ks3 path to internal URL: {e}")
-            
+
             if not artifact_path:
                 raise ValueError(
-                    "❌ 未找到代码包路径 (ks3_path)。\n"
-                    "   在 Serverless 模式下，必须先上传代码包。\n"
-                    "   👉 请先执行: agentengine build --mode code --push\n"
+                    "❌ 未找到 KS3 artifact 路径 (ks3_path)。\n"
+                    "   在 Serverless 模式下，必须先上传构建产物。\n"
+                    "   👉 请先执行: agentengine build --push\n"
                     "   或者在 deploy 命令中使用 --ks3-path 指定路径。"
                 )
 
-            parsed_bucket, parsed_object_key = self._parse_code_artifact_path(original_artifact_path)
+            parsed_bucket, parsed_object_key = self._parse_code_artifact_path(
+                original_artifact_path
+            )
             if not parsed_bucket or not parsed_object_key:
                 raise ValueError(
-                    "❌ ks3_path 格式无效，缺少代码包对象路径。\n"
+                    "❌ ks3_path 格式无效，缺少 artifact 对象路径。\n"
                     f"   当前值: {original_artifact_path or '(empty)'}\n"
                     "   期望格式: ks3://<bucket>/<object-key>\n"
-                    "   👉 请重新执行: agentengine build --mode code --push\n"
+                    "   👉 请重新执行: agentengine build --push\n"
                     "   或者传入完整的 --ks3-path。"
                 )
-                    
-        else:
-            artifact_path = package_info.image
-        
+
+        elif artifact_type == "Container":
+            artifact_path = str(package_info.image or "").strip()
+            if not artifact_path:
+                raise ValueError("Container 部署缺少 image")
+        elif artifact_type != "ManagedRuntime":
+            raise ValueError(f"Unsupported artifact type: {artifact_type}")
+
         # 构建 KS3 凭证
         ks3_config = None
-        if artifact_type == "Code":
+        if code_backed:
             from ksadk.common.auth import AWSV4Auth
+
             auth = AWSV4Auth()  # 读取本地 AK/SK
             if auth.access_key_id and auth.secret_access_key:
                 # 智能推断 Bucket 和 Region
@@ -589,7 +633,7 @@ class ServerlessProvider(BaseDeployProvider):
                     bucket_name, _ = self._parse_code_artifact_path(
                         package_info.metadata.get("ks3_path", "")
                     )
-                
+
                 # 如果没有提供，尝试从 artifact_path 解析
                 if not bucket_name:
                     if artifact_path.startswith("ks3://"):
@@ -599,35 +643,38 @@ class ServerlessProvider(BaseDeployProvider):
                             logger.info(f"Extracted bucket from ks3:// path: {bucket_name}")
                         except IndexError:
                             pass
-                    elif artifact_path.startswith("http")  and "." in artifact_path:
+                    elif artifact_path.startswith("http") and "." in artifact_path:
                         try:
                             # http://bucket.endpoint/key -> bucket
                             from urllib.parse import urlparse
+
                             parsed = urlparse(artifact_path)
                             bucket_name = parsed.netloc.split(".")[0]
                             logger.info(f"Extracted bucket from HTTP URL: {bucket_name}")
                         except Exception as e:
                             logger.warning(f"Failed to extract bucket from URL: {e}")
-                
+
                 # 如果仍然没有，使用智能默认值（与 KS3Uploader 逻辑一致）
                 if not bucket_name:
                     account_id = os.getenv("KSYUN_ACCOUNT_ID")
-                    upload_region = "cn-beijing-6" if target.region == "pre-online" else target.region
-                    
+                    upload_region = (
+                        "cn-beijing-6" if target.region == "pre-online" else target.region
+                    )
+
                     if not account_id:
                         raise ValueError(
                             "❌ 缺少 KSYUN_ACCOUNT_ID 环境变量\n"
                             "   Bucket 名称格式必须为: agentengine-{account_id}-{region}\n"
                             "   请在 .env 文件中设置: KSYUN_ACCOUNT_ID=你的账号ID"
                         )
-                    
+
                     bucket_name = f"agentengine-{account_id}-{upload_region}"
                     logger.info(f"Using default bucket: {bucket_name}")
-                
+
                 # Region 逻辑需与 Build 阶段保持一致 (pre-online -> cn-beijing-6)
                 ks3_region = target.extra.get("ks3_region")
                 if not ks3_region:
-                     ks3_region = "cn-beijing-6" if target.region == "pre-online" else target.region
+                    ks3_region = "cn-beijing-6" if target.region == "pre-online" else target.region
 
                 ks3_config = {
                     "access_key": auth.access_key_id,
@@ -636,18 +683,96 @@ class ServerlessProvider(BaseDeployProvider):
                     "bucket": bucket_name,
                 }
                 logger.info(f"📦 KS3 Config: bucket={bucket_name}, region={ks3_region}")
-        
+
+        runtime_config = None
+        if artifact_type == "ManagedRuntime":
+            runtime_config = {
+                "name": str(target.extra.get("runtime_name") or "").strip(),
+                "version": str(target.extra.get("runtime_version") or "").strip(),
+                "manifest_sha256": str(target.extra.get("manifest_sha256") or "").strip(),
+            }
+            missing = [key for key, value in runtime_config.items() if not value]
+            if missing:
+                raise ValueError(
+                    "ManagedRuntime 部署缺少 "
+                    + ", ".join(f"runtime_config.{key}" for key in missing)
+                )
+
         try:
             # 获取 dry_run 标识
             is_dry_run = target.extra.get("dry_run", False)
 
             async with AgentEngineClient(region=target.region, dry_run=is_dry_run) as client:
                 agent_exists = False
-                
-                if existing_agent_id:
+
+                # 显式 --agent-id：优先于本地 state，用于状态丢失后重新关联已有 Agent。
+                explicit_agent_id = (target.extra.get("agent_id") or "").strip() or None
+                if explicit_agent_id:
+                    if existing_agent_id and existing_agent_id != explicit_agent_id:
+                        click.secho(
+                            f"   ⚠️  --agent-id ({explicit_agent_id}) 与本地状态 "
+                            f"({existing_agent_id}) 不一致，以 --agent-id 为准",
+                            fg="yellow",
+                        )
+                    if is_dry_run:
+                        # DryRun 无法真实校验，假设存在并走更新路径
+                        existing_agent_id = explicit_agent_id
+                        agent_exists = True
+                        click.secho(
+                            f"   [Dry Run] 假设 Agent {explicit_agent_id} 存在", fg="cyan"
+                        )
+                    else:
+                        try:
+                            detail = await client.get_agent(
+                                explicit_agent_id, include_api_key=True
+                            )
+                        except Exception as e:
+                            return DeployResult(
+                                status=DeployStatus.FAILED,
+                                agent_id=explicit_agent_id,
+                                message=(
+                                    f"❌ 指定的 Agent ID '{explicit_agent_id}' 不存在，"
+                                    f"或当前凭证无权限访问。\n"
+                                    f"   详情: {e}\n"
+                                    "   👉 请确认 agent_id 正确，且当前 AK/SK / 账号"
+                                    "有该 Agent 的权限。"
+                                ),
+                            )
+
+                        # 校验通过 → 关联并回填 state，走热更新
+                        qa = detail.get("quick_access", {}) or {}
+                        basic = detail.get("basic", {}) or {}
+                        recovered_state = local_state.copy()
+                        recovered_state.update(
+                            {
+                                "agent_id": explicit_agent_id,
+                                "name": basic.get("name") or package_info.name,
+                                "region": target.region,
+                                "endpoint": qa.get("public_endpoint"),
+                                "updated_at": self._now_iso(),
+                            }
+                        )
+                        if qa.get("api_key"):
+                            recovered_state["api_key"] = qa["api_key"]
+                        # 去掉 None 值，避免覆盖掉旧的有效字段
+                        recovered_state = {
+                            k: v for k, v in recovered_state.items() if v is not None
+                        }
+                        self._save_state(state_file, recovered_state)
+                        local_state = recovered_state
+
+                        existing_agent_id = explicit_agent_id
+                        agent_exists = True
+                        click.secho(
+                            f"   🔗 已通过 --agent-id 关联 Agent: {explicit_agent_id} "
+                            f"(已回填 .agentengine.state)",
+                            fg="green",
+                        )
+
+                if existing_agent_id and not agent_exists:
                     # 有本地状态 → 先检查服务器上是否存在
                     click.echo(f"   检测到本地状态: {existing_agent_id}")
-                    
+
                     try:
                         # 尝试获取 agent，确认是否存在
                         existing_agent = await client.get_agent(existing_agent_id)
@@ -657,32 +782,37 @@ class ServerlessProvider(BaseDeployProvider):
                         # Agent 不存在或查询失败
                         err_msg = str(e).lower()
                         if "not found" in err_msg or "404" in err_msg or "不存在" in err_msg:
-                            click.secho(f"   ⚠️  服务器上未找到 Agent {existing_agent_id}，将创建新 Agent", fg="yellow")
+                            click.secho(
+                                f"   ⚠️  服务器上未找到 Agent {existing_agent_id}，将创建新 Agent",
+                                fg="yellow",
+                            )
                             agent_exists = False
-                        # 如果是 DryRun 抛出的异常（表明请求本来会发出去但被拦截了），我们认为 Agent 可能存在也可能不存在
-                        # 但为了安全起见，在 DryRun 模式下我们假设它存在并走更新路径，或者简单地打印日志
+                        # DryRun 异常表示真实请求被拦截，无法确认 Agent 是否存在。
+                        # 为安全起见，DryRun 假设它存在并走更新路径。
                         elif "Dry Run" in str(e):
-                             click.secho(f"   [Dry Run] 假设 Agent {existing_agent_id} 存在", fg="cyan")
-                             agent_exists = True
+                            click.secho(
+                                f"   [Dry Run] 假设 Agent {existing_agent_id} 存在", fg="cyan"
+                            )
+                            agent_exists = True
                         else:
                             # 其他错误，重新抛出
                             raise
-                    
+
                     if agent_exists:
                         # Agent 存在 → 执行更新
-                        click.echo(f"   执行热更新 (endpoint 保持不变)...")
-                        
+                        click.echo("   执行热更新 (endpoint 保持不变)...")
+
                         update_data = {
                             "artifact_type": artifact_type,
                             "artifact_path": artifact_path,
                             "resources": {
                                 "cpu": target.resources.cpu,
-                                "memory": target.resources.memory
+                                "memory": target.resources.memory,
                             },
                             "scaling": {
                                 "min_replicas": target.scaling.min_replicas,
                                 "max_replicas": target.scaling.max_replicas,
-                                "concurrency": target.scaling.concurrency
+                                "concurrency": target.scaling.concurrency,
                             },
                             "observability": {
                                 "langfuse_enabled": target.extra.get("enable_observability", True)
@@ -693,16 +823,20 @@ class ServerlessProvider(BaseDeployProvider):
                                 "url": resolved_ui.url,
                             },
                         }
-                        
+                        if runtime_config:
+                            update_data["runtime_config"] = runtime_config
+
                         if ks3_config:
                             update_data["ks3"] = ks3_config
                         elif artifact_type == "Container":
                             image_credential = self._image_credential_from_env(artifact_path)
                             if image_credential:
                                 update_data["image_credential"] = image_credential
-                                click.echo(
-                                    f"   🔑 镜像凭证: {image_credential['username']}@{image_credential['endpoint']}"
+                                credential_target = (
+                                    f"{image_credential['username']}@"
+                                    f"{image_credential['endpoint']}"
                                 )
+                                click.echo(f"   🔑 镜像凭证: {credential_target}")
 
                         # 加载全局配置 + 本地 .env，并通过部署参数注入到运行时环境变量。
                         env_vars, env_file_exists, project_env_count = self._load_deploy_env_vars(
@@ -727,17 +861,19 @@ class ServerlessProvider(BaseDeployProvider):
                         storage_config = self._serialize_storage_config(target)
                         if storage_config:
                             update_data["storage"] = storage_config
-                        
+
                         # 注入更新时间戳，强制触发 Rolling Update (Pod 重启)
                         if "env_vars" not in update_data:
                             update_data["env_vars"] = {}
-                        
+
                         import time
+
                         update_data["env_vars"]["KSADK_UPDATED_AT"] = str(int(time.time()))
-                        
+
                         # DEBUG: 打印 Payload 确认 trigger 是否存在
-                        click.echo(f"   🔄 更新 Trigger: KSADK_UPDATED_AT={update_data['env_vars']['KSADK_UPDATED_AT']}")
-                        
+                        updated_at_value = update_data["env_vars"]["KSADK_UPDATED_AT"]
+                        click.echo(f"   🔄 更新 Trigger: KSADK_UPDATED_AT={updated_at_value}")
+
                         res = await client.update_agent(existing_agent_id, update_data)
                         latest_access = {}
                         if not is_dry_run:
@@ -751,38 +887,40 @@ class ServerlessProvider(BaseDeployProvider):
                                     exc,
                                 ),
                             )
-                        
+
                         # 如果是 Dry Run，手动构造假响应以避免崩溃
                         if is_dry_run and not res:
                             res = {"name": package_info.name, "endpoint": "http://dry-run-endpoint"}
-                        
+
                         # 更新本地状态 (保留旧字段如 api_key)
                         new_state = local_state.copy()
-                        new_state.update({
-                            "agent_id": latest_access.get("agent_id") or existing_agent_id,
-                            "name": latest_access.get("name") or res.get("name"),
-                            "region": target.region,
-                            "endpoint": latest_access.get("endpoint") or res.get("endpoint"),
-                            "updated_at": self._now_iso(),
-                            **ui_state,
-                        })
+                        new_state.update(
+                            {
+                                "agent_id": latest_access.get("agent_id") or existing_agent_id,
+                                "name": latest_access.get("name") or res.get("name"),
+                                "region": target.region,
+                                "endpoint": latest_access.get("endpoint") or res.get("endpoint"),
+                                "updated_at": self._now_iso(),
+                                **ui_state,
+                            }
+                        )
                         if latest_access.get("api_key"):
                             new_state["api_key"] = latest_access["api_key"]
                         self._save_state(state_file, new_state)
-                        
+
                         return DeployResult(
-                            status=DeployStatus.DEPLOYING, 
+                            status=DeployStatus.DEPLOYING,
                             agent_id=existing_agent_id,
                             agent_name=res.get("name"),
                             endpoint=res.get("endpoint"),
-                            message=f"✅ Agent 已更新: {existing_agent_id}"
+                            message=f"✅ Agent 已更新: {existing_agent_id}",
                         )
                     # else: agent_exists = False，继续执行创建逻辑
-                
+
                 # 没有本地状态，或本地状态对应的 Agent 在服务器上不存在 → 创建新 Agent
                 if not existing_agent_id or not agent_exists:
                     click.echo(f"   创建新 Agent: {package_info.name}")
-                    
+
                     request_data = {
                         "name": package_info.name,
                         "framework": package_info.framework,
@@ -792,12 +930,12 @@ class ServerlessProvider(BaseDeployProvider):
                         "instance_id": target.extra.get("instance_id", "default"),
                         "resources": {
                             "cpu": target.resources.cpu,
-                            "memory": target.resources.memory
+                            "memory": target.resources.memory,
                         },
                         "scaling": {
                             "min_replicas": target.scaling.min_replicas,
                             "max_replicas": target.scaling.max_replicas,
-                            "concurrency": target.scaling.concurrency
+                            "concurrency": target.scaling.concurrency,
                         },
                         "observability": {
                             "langfuse_enabled": target.extra.get("enable_observability", True)
@@ -808,7 +946,9 @@ class ServerlessProvider(BaseDeployProvider):
                             "url": resolved_ui.url,
                         },
                     }
-                    
+                    if runtime_config:
+                        request_data["runtime_config"] = runtime_config
+
                     if ks3_config:
                         request_data["ks3"] = ks3_config
 
@@ -817,9 +957,10 @@ class ServerlessProvider(BaseDeployProvider):
                         image_credential = self._image_credential_from_env(artifact_path)
                         if image_credential:
                             request_data["image_credential"] = image_credential
-                            click.echo(
-                                f"   🔑 镜像凭证: {image_credential['username']}@{image_credential['endpoint']}"
+                            credential_target = (
+                                f"{image_credential['username']}@" f"{image_credential['endpoint']}"
                             )
+                            click.echo(f"   🔑 镜像凭证: {credential_target}")
 
                     # 加载全局配置 + 本地 .env，并通过部署参数注入到运行时环境变量。
                     env_vars, env_file_exists, project_env_count = self._load_deploy_env_vars(
@@ -837,7 +978,7 @@ class ServerlessProvider(BaseDeployProvider):
                             click.echo(f"   📦 加载环境变量: {len(env_vars)} 项 from 全局配置")
 
                     if env_vars:
-                         request_data["env_vars"] = env_vars
+                        request_data["env_vars"] = env_vars
 
                     network_config = self._serialize_network_config(target, is_update=False)
                     if network_config:
@@ -852,20 +993,22 @@ class ServerlessProvider(BaseDeployProvider):
                     ksyun_account_id = os.getenv("KSYUN_ACCOUNT_ID")
                     if ksyun_account_id:
                         extra_headers["X-Ksc-Account-Id"] = ksyun_account_id
-                    
+
                     # 重新构造一个带 Header 的 client
-                    async with AgentEngineClient(region=target.region, extra_headers=extra_headers, dry_run=is_dry_run) as new_client:
+                    async with AgentEngineClient(
+                        region=target.region, extra_headers=extra_headers, dry_run=is_dry_run
+                    ) as new_client:
                         res = await new_client.create_agent(request_data)
-                    
+
                     # 如果是 Dry Run，手动构造假响应
                     if is_dry_run and not res:
                         res = {
-                            "agent_id": "dry-run-agent-id", 
-                            "name": package_info.name, 
-                            "endpoint": "http://dry-run-endpoint", 
-                            "api_key": "dry-run-key"
+                            "agent_id": "dry-run-agent-id",
+                            "name": package_info.name,
+                            "endpoint": "http://dry-run-endpoint",
+                            "api_key": "dry-run-key",
                         }
-                    
+
                     # CreateAgentProduct 返回 order_id，需要轮询 list_agents 获取 agent_id
                     new_agent_id = res.get("agent_id")
                     order_id = res.get("order_id")
@@ -876,10 +1019,13 @@ class ServerlessProvider(BaseDeployProvider):
                     if order_id and not new_agent_id:
                         click.echo(f"   📋 订单已创建: {order_id}，等待实例创建...")
                         import time
+
                         for i in range(12):  # 最多等 60s
                             time.sleep(5)
                             try:
-                                detail = await client.get_agent(name=package_info.name, include_api_key=True)
+                                detail = await client.get_agent(
+                                    name=package_info.name, include_api_key=True
+                                )
                                 qa = detail.get("quick_access", {})
                                 basic = detail.get("basic", {})
                                 new_agent_id = basic.get("agent_id")
@@ -894,7 +1040,10 @@ class ServerlessProvider(BaseDeployProvider):
                             click.echo(f"   ⏳ 等待中... ({(i+1)*5}s)")
 
                         if not new_agent_id:
-                            click.secho("   ⚠️  实例仍在创建中，稍后使用 'agentengine status' 查看", fg="yellow")
+                            click.secho(
+                                "   ⚠️  实例仍在创建中，稍后使用 'agentengine status' 查看",
+                                fg="yellow",
+                            )
 
                     latest_access = {}
                     if new_agent_id and not is_dry_run:
@@ -913,54 +1062,63 @@ class ServerlessProvider(BaseDeployProvider):
                         agent_name = latest_access.get("name") or agent_name
                         agent_endpoint = latest_access.get("endpoint") or agent_endpoint
                         agent_api_key = latest_access.get("api_key") or agent_api_key
-                    
+
                     # 保存 agent_id 到本地状态文件
-                    self._save_state(state_file, {
-                        "agent_id": new_agent_id,
-                        "name": agent_name,
-                        "region": target.region,
-                        "endpoint": agent_endpoint,
-                        "api_key": agent_api_key,  # 只在首次保存
-                        "order_id": order_id,
-                        "created_at": self._now_iso(),
-                        **ui_state,
-                    })
-                    
-                    click.echo(f"   💾 已保存状态到 .agentengine.state")
-                    
+                    self._save_state(
+                        state_file,
+                        {
+                            "agent_id": new_agent_id,
+                            "name": agent_name,
+                            "region": target.region,
+                            "endpoint": agent_endpoint,
+                            "api_key": agent_api_key,  # 只在首次保存
+                            "order_id": order_id,
+                            "created_at": self._now_iso(),
+                            **ui_state,
+                        },
+                    )
+
+                    click.echo("   💾 已保存状态到 .agentengine.state")
+
                     return DeployResult(
-                        status=DeployStatus.DEPLOYING, 
+                        status=DeployStatus.DEPLOYING,
                         agent_id=new_agent_id,
                         agent_name=agent_name,
-                        endpoint=agent_endpoint, 
+                        endpoint=agent_endpoint,
                         api_key=agent_api_key,
-                        message=f"✅ Agent ID: {new_agent_id or '(创建中)'} (首次部署, 订单: {order_id or '-'})"
+                        message=(
+                            f"✅ Agent ID: {new_agent_id or '(创建中)'} "
+                            f"(首次部署, 订单: {order_id or '-'})"
+                        ),
                     )
 
+            return DeployResult(
+                status=DeployStatus.FAILED,
+                message="部署流程未返回 Agent 状态",
+            )
+
         except DryRunExit as e:
             return DeployResult(
                 status=DeployStatus.SKIPPED,
                 message="✅ Dry Run Completed: 请求已打印，未执行实际变更。",
                 metadata={"dry_run_request": e.payload or {}},
             )
-            
+
         except Exception as e:
             logger.error(f"Deploy failed: {e}")
-            
+
             # 检测名称冲突
             err_msg = str(e)
             if "Conflict" in err_msg or "409" in err_msg or "already exists" in err_msg:
                 return DeployResult(
                     status=DeployStatus.FAILED,
                     message=f"❌ 部署失败: Agent 名称 '{package_info.name}' 已存在。\n"
-                            f"   提示: 请检查是否重复创建。\n"
-                            f"   👉 解决方法: 请在 agentengine.yaml 中修改 'name' 字段 (如添加后缀) 后重试。"
+                    f"   提示: 请检查是否重复创建。\n"
+                    "   👉 解决方法: 请在 agentengine.yaml 中修改 'name' 字段 "
+                    "(如添加后缀) 后重试。",
                 )
-                
-            return DeployResult(
-                status=DeployStatus.FAILED,
-                message=f"Server 请求失败: {str(e)}"
-            )
+
+            return DeployResult(status=DeployStatus.FAILED, message=f"Server 请求失败: {str(e)}")
 
     async def get_status(self, agent_id: str, target: DeployTarget) -> DeployResult:
         """获取 Agent 状态"""
@@ -968,7 +1126,7 @@ class ServerlessProvider(BaseDeployProvider):
         try:
             async with AgentEngineClient(region=target.region, dry_run=dry_run) as client:
                 res = await client.get_agent(agent_id)
-                
+
                 status_map = {
                     "running": DeployStatus.RUNNING,
                     "ready": DeployStatus.RUNNING,
@@ -978,9 +1136,9 @@ class ServerlessProvider(BaseDeployProvider):
                     "scaling": DeployStatus.UPDATING,
                     "failed": DeployStatus.FAILED,
                     "error": DeployStatus.FAILED,
-                    "unknown": DeployStatus.UNKNOWN
+                    "unknown": DeployStatus.UNKNOWN,
                 }
-                
+
                 # 使状态匹配不区分大小写，以兼容服务端的改动 (Creating -> CREATING)
                 current_status = (res.get("status") or "").lower()
                 return DeployResult(
@@ -988,21 +1146,20 @@ class ServerlessProvider(BaseDeployProvider):
                     agent_id=res.get("agent_id"),
                     agent_name=res.get("name"),
                     endpoint=res.get("endpoint"),
-                    message=f"Status: {res.get('status')} ({res.get('phase')})"
+                    message=f"Status: {res.get('status')} ({res.get('phase')})",
                 )
         except DryRunExit:
             return DeployResult(status=DeployStatus.SKIPPED, message="Dry Run executed.")
         except Exception as e:
-            return DeployResult(
-                status=DeployStatus.UNKNOWN,
-                message=f"查询失败: {e}"
-            )
+            return DeployResult(status=DeployStatus.UNKNOWN, message=f"查询失败: {e}")
 
     async def destroy(self, agent_id: str, target: DeployTarget) -> bool:
         """销毁 Agent"""
         dry_run = target.extra.get("dry_run", False)
         project_dir = str(target.extra.get("project_dir") or "").strip()
-        state_file = (Path(project_dir).resolve() if project_dir else Path(".").resolve()) / ".agentengine.state"
+        state_file = (
+            Path(project_dir).resolve() if project_dir else Path(".").resolve()
+        ) / ".agentengine.state"
 
         try:
             async with AgentEngineClient(region=target.region, dry_run=dry_run) as client:
@@ -1015,8 +1172,10 @@ class ServerlessProvider(BaseDeployProvider):
                             os.remove(state_file)
                             logger.info(f"Deleted local state file: {state_file}")
                         except Exception as cleanup_error:
-                            logger.warning(f"Failed to delete local state file {state_file}: {cleanup_error}")
-                return success
+                            logger.warning(
+                                f"Failed to delete local state file {state_file}: {cleanup_error}"
+                            )
+                return bool(success)
         except DryRunExit:
             # 让异常冒泡给 CLI 处理
             raise
@@ -1030,19 +1189,27 @@ class ServerlessProvider(BaseDeployProvider):
         try:
             async with AgentEngineClient(region=target.region, dry_run=dry_run) as client:
                 res = await client.list_agents()
-                
+
                 results = []
                 for agent in res.get("Agents", []):
                     current_status = (agent.get("status") or "").lower()
-                    results.append(DeployResult(
-                        status=DeployStatus.RUNNING if current_status in ("running", "ready") else (
-                            DeployStatus.DEPLOYING if current_status == "creating" else DeployStatus.UNKNOWN
-                        ),
-                        agent_id=agent.get("agent_id"),
-                        agent_name=agent.get("name"),
-                        endpoint=agent.get("endpoint"),
-                        message=agent.get("status")
-                    ))
+                    results.append(
+                        DeployResult(
+                            status=(
+                                DeployStatus.RUNNING
+                                if current_status in ("running", "ready")
+                                else (
+                                    DeployStatus.DEPLOYING
+                                    if current_status == "creating"
+                                    else DeployStatus.UNKNOWN
+                                )
+                            ),
+                            agent_id=agent.get("agent_id"),
+                            agent_name=agent.get("name"),
+                            endpoint=agent.get("endpoint"),
+                            message=agent.get("status"),
+                        )
+                    )
                 return results
         except DryRunExit:
             raise
@@ -1056,7 +1223,7 @@ class ServerlessProvider(BaseDeployProvider):
         try:
             async with AgentEngineClient(region=target.region, dry_run=dry_run) as client:
                 response = await client.chat(agent_id, message, stream=False)
-                return response.get("output", "")
+                return str(response.get("output", ""))
         except DryRunExit:
             raise
         except Exception as e:
@@ -1066,7 +1233,7 @@ class ServerlessProvider(BaseDeployProvider):
         """读取本地状态文件"""
         if state_file.exists():
             try:
-                with open(state_file, 'r', encoding='utf-8') as f:
+                with open(state_file, "r", encoding="utf-8") as f:
                     return yaml.safe_load(f) or {}
             except Exception as e:
                 logger.warning(f"Failed to load state file: {e}")
@@ -1102,8 +1269,9 @@ class ServerlessProvider(BaseDeployProvider):
     def _save_state(self, state_file: Path, state: Dict[str, Any]) -> None:
         """保存状态到本地文件"""
         import yaml
+
         try:
-            with open(state_file, 'w', encoding='utf-8') as f:
+            with open(state_file, "w", encoding="utf-8") as f:
                 yaml.dump(state, f, default_flow_style=False, allow_unicode=True)
             logger.debug(f"State saved to {state_file}")
         except Exception as e:
@@ -1112,4 +1280,5 @@ class ServerlessProvider(BaseDeployProvider):
     def _now_iso(self) -> str:
         """返回当前时间 ISO 格式"""
         from datetime import datetime
+
         return datetime.now().isoformat()