agentengine-sdk-python 0.8.3__py3-none-any.whl → 0.8.4__py3-none-any.whl

ksadk/_build_provenance.json

@@ -1 +1 @@
-{"schemaVersion":1,"sourceCommit":"320b7f324966bd3aa8557a65cf592716699edb8c","sourceTree":"clean","version":"0.8.3"}
+{"schemaVersion":1,"sourceCommit":"8e37106d1faed44c2de8b7f72a0d8cd2f1fbddd5","sourceTree":"clean","version":"0.8.4"}

ksadk/api/client.py

@@ -162,8 +162,30 @@ class AgentEngineClient:
         timeout: float = 60.0,
         dry_run: bool = False,
         extra_headers: Optional[Dict[str, str]] = None,
+        allow_env_fallback: bool = True,
+        api_version: Optional[str] = None,
     ):
-        resolved_base_url = base_url or os.getenv("AGENTENGINE_SERVER_URL")
+        if type(allow_env_fallback) is not bool:
+            raise ValueError("allow_env_fallback must be a boolean")
+        self._allow_env_fallback = allow_env_fallback
+        self._explicit_api_version = api_version
+        if not allow_env_fallback:
+            parsed = urlsplit(base_url or "")
+            parsed.port  # validate malformed or out-of-range ports before any transport
+            if (
+                parsed.scheme not in {"http", "https"} or not parsed.hostname
+                or parsed.username is not None or parsed.password is not None
+                or parsed.query or parsed.fragment or "\\" in (base_url or "")
+                or any(char.isspace() for char in (base_url or ""))
+                or not access_key or not secret_key or not region
+                or region.strip().lower() == "pre-online"
+            ):
+                raise ValueError(
+                    "Explicit control clients require endpoint, credentials and region"
+                )
+        resolved_base_url = base_url or (
+            os.getenv("AGENTENGINE_SERVER_URL") if allow_env_fallback else None
+        )
         self.base_url: str = resolved_base_url or self._detect_default_base_url()
 
         # 本地调试覆盖 (如果需要)
@@ -172,10 +194,12 @@ class AgentEngineClient:
         self.logical_region = region
         self.region = self._normalize_control_region(region)
         self.custom_source = self._resolve_custom_source(region)
-        self.dry_run = bool(dry_run or self._is_global_dry_run_enabled())
+        self.dry_run = bool(dry_run or (allow_env_fallback and self._is_global_dry_run_enabled()))
         self.extra_headers = extra_headers or {}
         # 签名 service 可通过环境变量覆盖（例如 aicp）
-        self.service: str = service or os.getenv("AGENTENGINE_SIGN_SERVICE") or "aicp"
+        self.service: str = service or (
+            os.getenv("AGENTENGINE_SIGN_SERVICE") if allow_env_fallback else None
+        ) or "aicp"
 
         # AWS V4 签名
         self._auth = AWSV4Auth(
@@ -183,6 +207,7 @@ class AgentEngineClient:
             secret_access_key=secret_key or "",
             region=self.region,
             service=self.service,
+            allow_env_fallback=allow_env_fallback,
         )
 
         if self._auth.is_enabled:
@@ -197,10 +222,6 @@ class AgentEngineClient:
         # requests.Session must not be used by several worker threads at once.
         self._async_action_lock = asyncio.Lock()
         self._http_error_log_suppressors: list[HttpErrorLogSuppressor] = []
-        # A Server Action can be deployed before the external KOP publication
-        # finishes.  Remember that result per client so an approval retry does
-        # not repeatedly hit the known-unpublished control-plane route.
-        self._unpublished_kop_actions: set[str] = set()
         # 反查身份的实例缓存（避免同会话重复调 IAM）；None=未尝试，ResolvedIdentity|None=已反查
         self._resolved_identity: Any = None
         self._identity_resolve_attempted: bool = False
@@ -217,6 +238,15 @@ class AgentEngineClient:
             return False
         return True
 
+    def _request_ssl_verify(self) -> bool:
+        return True if not self._allow_env_fallback else self._ssl_verify_enabled()
+
+    def _request_api_version(self) -> str:
+        return self._explicit_api_version or (
+            os.getenv("AGENTENGINE_API_VERSION", "2024-06-12")
+            if self._allow_env_fallback else "2024-06-12"
+        )
+
     @staticmethod
     def _is_global_dry_run_enabled() -> bool:
         """根命令 --dry-run 开关：支持未显式透传 dry_run 参数的命令。"""
@@ -259,6 +289,7 @@ class AgentEngineClient:
     def _get_session(self) -> requests.Session:
         if self._session is None:
             self._session = requests.Session()
+            self._session.trust_env = self._allow_env_fallback
         return self._session
 
     def _get_host(self) -> str:
@@ -421,6 +452,8 @@ class AgentEngineClient:
         )
 
     def _can_retry_with_inner_aicp_endpoint(self, details: Dict[str, Any]) -> bool:
+        if not self._allow_env_fallback:
+            return False
         if not self._is_inner_account_intranet_error(details):
             return False
         parsed = urlparse(self.base_url or "")
@@ -439,7 +472,7 @@ class AgentEngineClient:
         kop_mode = self._is_kop_mode()
         headers = self._build_headers(action=action, kop_mode=kop_mode)
         if kop_mode:
-            version = os.getenv("AGENTENGINE_API_VERSION", "2024-06-12")
+            version = self._request_api_version()
             full_url = f"{self.base_url.rstrip('/')}/?Action={action}&Version={version}"
         else:
             full_url = f"{self.base_url}{path}"
@@ -453,7 +486,7 @@ class AgentEngineClient:
         headers["Accept"] = accept
         if has_files:
             headers.pop("Content-Type", None)
-        version = os.getenv("AGENTENGINE_API_VERSION", "2024-06-12")
+        version = self._request_api_version()
         full_url = (
             f"{self.base_url.rstrip('/')}/?Action={action}&Version={version}"
             if kop_mode
@@ -532,7 +565,7 @@ class AgentEngineClient:
         }
         if kop_mode and action:
             headers["X-Action"] = action
-            headers["X-Version"] = os.getenv("AGENTENGINE_API_VERSION", "2024-06-12")
+            headers["X-Version"] = self._request_api_version()
         if self.custom_source:
             headers["X-KSC-CUSTOM-SOURCE"] = self.custom_source
 
@@ -579,6 +612,10 @@ class AgentEngineClient:
 
     def _get_resolved_identity(self) -> Any:
         """反查身份并缓存到实例。dry-run 只读文件缓存不联网。"""
+        if not self._allow_env_fallback:
+            # Explicit resource admission owns identity resolution and its target.
+            # Never consult a global identity cache or contact an implicit service.
+            return None
         if self._identity_resolve_attempted:
             return self._resolved_identity
         self._identity_resolve_attempted = True
@@ -606,7 +643,9 @@ class AgentEngineClient:
             if key.lower() == "x-ksc-account-id" and str(value or "").strip():
                 return str(value).strip()
         # 2. env KSYUN_ACCOUNT_ID
-        account_id = os.getenv("KSYUN_ACCOUNT_ID", "").strip()
+        account_id = (
+            os.getenv("KSYUN_ACCOUNT_ID", "").strip() if self._allow_env_fallback else ""
+        )
         if account_id:
             return account_id
         # 3. 反查主账号 ID（复用 _get_resolved_identity 的反查，不重复调）
@@ -734,11 +773,17 @@ class AgentEngineClient:
                 headers=headers,
                 auth=self._auth.get_auth(),  # AWS V4 签名
                 timeout=self.timeout,
-                verify=self._ssl_verify_enabled(),
+                verify=self._request_ssl_verify(),
+                allow_redirects=self._allow_env_fallback,
             )
 
             logger.debug(f"Response: {response.status_code}")
 
+            if not self._allow_env_fallback and 300 <= response.status_code < 400:
+                raise AgentEngineAPIError(
+                    response.status_code, "Explicit connection redirect refused"
+                )
+
             if response.status_code < 400:
                 break
 
@@ -996,24 +1041,6 @@ class AgentEngineClient:
             )
         return AgentEngineAPIError(response.status_code, message)
 
-    @staticmethod
-    def _is_unregistered_kop_action(error: AgentEngineAPIError, action: str) -> bool:
-        """Return whether KOP rejected an otherwise valid Server Action.
-
-        Public Action publication is an infrastructure step independent of a
-        Server rollout.  During that window the per-Agent Gateway route is
-        already authenticated and still forwards the exact same Action to
-        Server admission, so callers can safely use it as the data-plane
-        fallback instead of losing an approval response.
-        """
-
-        message = str(error.message or "").strip().lower()
-        return (
-            error.code == 400
-            and f"action {action.lower()}" in message
-            and "not valid for this web service" in message
-        )
-
     def _runtime_action(
         self,
         *,
@@ -1031,7 +1058,8 @@ class AgentEngineClient:
             headers={"Authorization": f"Bearer {api_key}"},
             json=params,
             timeout=self.timeout,
-            verify=self._ssl_verify_enabled(),
+            verify=self._request_ssl_verify(),
+            allow_redirects=self._allow_env_fallback,
         )
         if response.status_code >= 400:
             raise self._workspace_runtime_error(response)
@@ -1057,22 +1085,6 @@ class AgentEngineClient:
             raise AgentEngineAPIError(502, "Runtime Action returned non-object Data")
         return normalized
 
-    async def _runtime_action_for_agent(
-        self,
-        *,
-        agent_id: str,
-        action: str,
-        params: Dict[str, Any],
-    ) -> Dict[str, Any]:
-        detail = await self.get_agent(agent_id, include_api_key=True)
-        access = self._extract_runtime_access(detail)
-        return await asyncio.to_thread(
-            self._runtime_action,
-            access=access,
-            action=action,
-            params=params,
-        )
-
     @staticmethod
     def _compact_params(params: Dict[str, Any] | None) -> Dict[str, Any]:
         return {key: value for key, value in (params or {}).items() if value is not None}
@@ -1164,7 +1176,8 @@ class AgentEngineClient:
                 headers=headers,
                 auth=self._auth.get_auth(),
                 timeout=self.timeout,
-                verify=self._ssl_verify_enabled(),
+                verify=self._request_ssl_verify(),
+                allow_redirects=self._allow_env_fallback,
             )
             if response.status_code < 400:
                 return response
@@ -1238,7 +1251,8 @@ class AgentEngineClient:
             files=files,
             stream=False,
             timeout=self.timeout,
-            verify=self._ssl_verify_enabled(),
+            verify=self._request_ssl_verify(),
+            allow_redirects=self._allow_env_fallback,
         )
         setattr(response, "_ksadk_workspace_url", url)
         if response.status_code >= 400:
@@ -1501,8 +1515,13 @@ class AgentEngineClient:
         }
         if manifest_sha256:
             payload["ManifestSHA256"] = manifest_sha256
+        if isinstance(declaration, dict) and declaration.get("plugin_artifacts"):
+            payload["PluginArtifacts"] = declaration["plugin_artifacts"]
         return payload
 
+    async def get_plugin_delivery_capabilities(self) -> Dict[str, Any]:
+        return await self._action_async("GetPluginDeliveryCapabilities", {})
+
     async def create_agent(self, data: Dict[str, Any]) -> Dict[str, Any]:
         """Create an Agent through the established order workflow.
 
@@ -1604,21 +1623,10 @@ class AgentEngineClient:
             advanced["ProjectId"] = project_id
         params["Advanced"] = advanced
 
-        # ManagedRuntime is an already-paid, platform-owned YAML runtime.  It
-        # has no Code/Container order callback to materialize later, so use
-        # the existing CreateAgent action to create its Agent/Runtime now.
-        # Code and Container keep the established CreateAgentProduct flow.
-        action = (
-            "CreateAgent"
-            if params["DeploymentType"] == "ManagedRuntime"
-            else "CreateAgentProduct"
-        )
-        if action == "CreateAgent":
-            # CreateAgent is also used as an order callback and therefore
-            # requires an InstanceId.  A declarative runtime has no order to
-            # allocate one for us, so the SDK supplies a stable request UUID.
-            params["InstanceId"] = str(data.get("instance_id") or uuid.uuid4())
-        return self._action(action, params)
+        # CreateAgentProduct is the established public Action. The Server
+        # handles ManagedRuntime synchronously without involving Ding, while
+        # Code and Container retain their existing order/callback lifecycle.
+        return self._action("CreateAgentProduct", params)
 
     async def get_agent(
         self,
@@ -1686,6 +1694,33 @@ class AgentEngineClient:
             params["Name"] = name
         return self._action("ListAgentModels", params)
 
+    async def list_knowledge_bases(self) -> Dict[str, Any]:
+        """List knowledge bases visible to the current signed cloud identity."""
+
+        result = await self._action_async("ListKnowledgeBases", {})
+        return {
+            "knowledge_bases": result.get("knowledge_bases", []),
+            "total_count": result.get("total_count", 0),
+        }
+
+    async def list_memory_instances(self) -> Dict[str, Any]:
+        """List long-term memory instances visible to the signed identity."""
+
+        result = await self._action_async("ListMemoryInstances", {})
+        return {
+            "memory_instances": result.get("memory_instances", []),
+            "total_count": result.get("total_count", 0),
+        }
+
+    async def list_skill_workspaces(self) -> Dict[str, Any]:
+        """List Skill Center workspaces visible to the signed identity."""
+
+        result = await self._action_async("ListSkillWorkspaces", {})
+        return {
+            "skill_workspaces": result.get("skill_workspaces", []),
+            "total_count": result.get("total_count", 0),
+        }
+
     async def create_dashboard_access_link(
         self,
         *,
@@ -2060,24 +2095,7 @@ class AgentEngineClient:
             "Response": response or {},
             "IdempotencyKey": idempotency_key,
         }
-        if "SubmitInteraction" not in self._unpublished_kop_actions:
-            try:
-                return await self._action_async("SubmitInteraction", params)
-            except AgentEngineAPIError as exc:
-                if not self._is_unregistered_kop_action(exc, "SubmitInteraction"):
-                    raise
-                self._unpublished_kop_actions.add("SubmitInteraction")
-        if "SubmitInteraction" in self._unpublished_kop_actions:
-            # KOP publication can lag the Server/Gateway rollout.  The
-            # per-Agent endpoint is authenticated with the API key returned by
-            # signed GetAgent and still traverses Gateway -> Server admission;
-            # it never submits directly to Runtime.
-            return await self._runtime_action_for_agent(
-                agent_id=agent_id,
-                action="SubmitInteraction",
-                params=params,
-            )
-        raise AssertionError("unreachable SubmitInteraction transport state")
+        return await self._action_async("SubmitInteraction", params)
 
     async def list_workspace_files(
         self,
@@ -2582,6 +2600,7 @@ class AgentEngineClient:
             raise AssertionError("dry-run request unexpectedly returned")
 
         session = requests.Session()
+        session.trust_env = self._allow_env_fallback
         response: requests.Response | None = None
         retried_inner_endpoint = False
         try:
@@ -2596,7 +2615,8 @@ class AgentEngineClient:
                     # reasoning before its next SSE chunk.  Bound connection
                     # establishment, not the lifetime of an admitted stream.
                     timeout=(self.timeout, None),
-                    verify=self._ssl_verify_enabled(),
+                    verify=self._request_ssl_verify(),
+                    allow_redirects=self._allow_env_fallback,
                     stream=True,
                 )
                 content_type = str(response.headers.get("content-type") or "").lower()
@@ -2622,9 +2642,7 @@ class AgentEngineClient:
                     )
                     message = (
                         str(
-                            details.get("remote_error_message")
-                            or details.get("message")
-                            or ""
+                            details.get("remote_error_message") or details.get("message") or ""
                         ).strip()
                         or "RunAgent stream did not return text/event-stream"
                     )
@@ -2650,11 +2668,7 @@ class AgentEngineClient:
                     details=details,
                 )
                 message = (
-                    str(
-                        details.get("remote_error_message")
-                        or details.get("message")
-                        or ""
-                    ).strip()
+                    str(details.get("remote_error_message") or details.get("message") or "").strip()
                     or resp_text
                 )
                 raise AgentEngineAPIError(

ksadk/builders/code_builder.py

@@ -280,7 +280,15 @@ class CodeBuilder(BaseBuilder):
         "mcp>=1.1.0",
         "langchain-mcp-adapters>=0.0.1",
     )
-    BUNDLED_KSADK_POSTGRES_SESSION_REQUIREMENTS = ("asyncpg>=0.30.0,<1.0.0",)
+    BUNDLED_KSADK_POSTGRES_SESSION_REQUIREMENTS = (
+        "asyncpg>=0.30.0,<1.0.0",
+        "greenlet>=1.0.0",
+    )
+    BUNDLED_KSADK_LANGGRAPH_POSTGRES_REQUIREMENTS = (
+        "langgraph-checkpoint-postgres>=3.1.0",
+        "psycopg[binary]>=3.2,<4.0",
+        "psycopg-pool>=3.2,<4.0",
+    )
     BUNDLED_KSADK_ATTACHMENT_RUNTIME_REQUIREMENTS = (
         "pypdf>=6.0.0",
         "beautifulsoup4>=4.12.0",
@@ -584,8 +592,14 @@ class CodeBuilder(BaseBuilder):
         value = os.getenv("KSADK_BUILD_ENABLE_ATTACHMENT_OCR", "")
         return value.strip().lower() in {"1", "true", "yes", "on"}
 
-    def _bundled_runtime_requirements(self) -> tuple[str, ...]:
+    def _bundled_runtime_requirements(self, detection_result: Any = None) -> tuple[str, ...]:
         requirements = list(self.BUNDLED_KSADK_RUNTIME_REQUIREMENTS)
+        detection_type = getattr(detection_result, "type", None)
+        framework = str(
+            getattr(detection_type, "value", detection_type) or ""
+        ).strip().lower()
+        if framework in {"langgraph", "langchain", "deepagents"}:
+            requirements.extend(self.BUNDLED_KSADK_LANGGRAPH_POSTGRES_REQUIREMENTS)
         if self._attachment_ocr_runtime_enabled():
             requirements.extend(self.BUNDLED_KSADK_ATTACHMENT_OCR_RUNTIME_REQUIREMENTS)
         if self._mcp_runtime_enabled():
@@ -612,16 +626,26 @@ class CodeBuilder(BaseBuilder):
         if self._env_flag_enabled("KSADK_BUILD_ENABLE_POSTGRES_SESSION"):
             return True
         backend = (
-            self._project_env_value("KSADK_SESSION_BACKEND")
-            or self._project_env_value("AGENTENGINE_SESSION_BACKEND")
-            or self._project_env_value("KSADK_STM_BACKEND")
+            self._project_file_env_value("KSADK_SESSION_BACKEND")
+            or self._project_file_env_value("AGENTENGINE_SESSION_BACKEND")
+            or self._project_file_env_value("KSADK_STM_BACKEND")
+            or os.getenv("KSADK_SESSION_BACKEND")
+            or os.getenv("AGENTENGINE_SESSION_BACKEND")
+            or os.getenv("KSADK_STM_BACKEND")
+            or ""
         )
         if backend.strip().lower() == "postgres":
             return True
         dsn = (
-            self._project_env_value("KSADK_SESSION_DSN")
-            or self._project_env_value("KSADK_STM_URL")
-            or self._project_env_value("KSADK_STM_DB_URL")
+            self._project_file_env_value("KSADK_CHECKPOINT_DSN")
+            or self._project_file_env_value("KSADK_SESSION_DSN")
+            or self._project_file_env_value("KSADK_STM_URL")
+            or self._project_file_env_value("KSADK_STM_DB_URL")
+            or os.getenv("KSADK_CHECKPOINT_DSN")
+            or os.getenv("KSADK_SESSION_DSN")
+            or os.getenv("KSADK_STM_URL")
+            or os.getenv("KSADK_STM_DB_URL")
+            or ""
         )
         return self._looks_like_postgres_dsn(dsn)
 
@@ -642,6 +666,9 @@ class CodeBuilder(BaseBuilder):
         value = os.getenv(name)
         if value:
             return value
+        return self._project_file_env_value(name)
+
+    def _project_file_env_value(self, name: str) -> str:
         for env_file in (self.project_dir / ".env", self.project_dir / "agentengine.env"):
             if not env_file.is_file():
                 continue
@@ -942,7 +969,7 @@ class CodeBuilder(BaseBuilder):
     def _build_requirements_list(self, detection_result) -> List[str]:
         final_deps = merge_requirement_lists(
             self._get_base_requirements(detection_result),
-            self._bundled_runtime_requirements(),
+            self._bundled_runtime_requirements(detection_result),
         )
 
         user_requirements = self.project_dir / "requirements.txt"

ksadk/builders/framework_requirements.py

@@ -8,8 +8,9 @@ FASTAPI_REQUIREMENT = "fastapi>=0.136.0,<0.137.0"
 STARLETTE_REQUIREMENT = "starlette>=1.0,<1.4"
 
 ADK_REQUIREMENTS = (
-    # goal-00: 与 ksadk 自身 adk extra 对齐,允许 1.34.x 与 2.x
+    # 与 ksadk 自身 adk extra 对齐，支持 1.x 与 2.x。
     "google-adk>=1.34.0,<3.0.0",
+    "greenlet>=1.0.0",
     "litellm>=1.0.0",
 )
 

ksadk/builders/ks3_uploader.py

@@ -2,6 +2,7 @@
 KS3 上传模块 - 金山云对象存储上传
 """
 
+import logging
 import os
 import socket
 import time
@@ -27,7 +28,15 @@ class KS3Uploader:
     UPLOAD_TIMEOUT_PER_MB_SECONDS = 4.0
     UPLOAD_TIMEOUT_MAX_SECONDS = 3600
 
-    def __init__(self, region: str = "cn-beijing-6", bucket: Optional[str] = None):
+    def __init__(
+        self,
+        region: str = "cn-beijing-6",
+        bucket: Optional[str] = None,
+        *,
+        access_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        public_read: bool = True,
+    ):
         """初始化 KS3 上传器
 
         Args:
@@ -37,7 +46,15 @@ class KS3Uploader:
                    - 如果未指定，优先从环境变量 KS3_BUCKET 读取
                    - 如果环境变量也未设置，默认使用 agentengine-{region}
         """
+        # ks3sdk logs the signed Authorization header at INFO. Studio uploads
+        # run inside a long-lived server process, so keep that transport logger
+        # above INFO before any request can be emitted.
+        logging.getLogger("ks3.http").setLevel(logging.WARNING)
+
         self.region = region
+        self.access_key = access_key
+        self.secret_key = secret_key
+        self.public_read = public_read
 
         # 确定 bucket 名称 (优先级: 参数 > 环境变量 > 默认值)
         if bucket:
@@ -260,8 +277,12 @@ class KS3Uploader:
     def _upload_via_host(self, file_path: Path, object_key: str, host: str) -> bool:
         from ks3.connection import Connection  # type: ignore[import-untyped]
 
-        ak = os.environ.get("KSYUN_ACCESS_KEY") or os.environ.get("KS3_ACCESS_KEY")
-        sk = os.environ.get("KSYUN_SECRET_KEY") or os.environ.get("KS3_SECRET_KEY")
+        ak = self.access_key or os.environ.get("KSYUN_ACCESS_KEY") or os.environ.get(
+            "KS3_ACCESS_KEY"
+        )
+        sk = self.secret_key or os.environ.get("KSYUN_SECRET_KEY") or os.environ.get(
+            "KS3_SECRET_KEY"
+        )
 
         conn = Connection(
             ak,
@@ -291,10 +312,14 @@ class KS3Uploader:
                 resumable=True,
                 resumable_filename=str(resume_path),
             )
-            result = upload_task.upload(headers={"x-kss-acl": "public-read"})
+            headers = {"x-kss-acl": "public-read"} if self.public_read else {}
+            result = upload_task.upload(headers=headers)
         else:
             click.echo(f"   普通上传: {file_path.stat().st_size / (1024 * 1024):.2f} MB")
-            result = key.set_contents_from_filename(str(file_path), policy="public-read")
+            if self.public_read:
+                result = key.set_contents_from_filename(str(file_path), policy="public-read")
+            else:
+                result = key.set_contents_from_filename(str(file_path))
 
         status = getattr(result, "status", None)
         if status is None:
@@ -313,8 +338,12 @@ class KS3Uploader:
             成功返回 ks3:// URI, 失败返回 None
         """
         # 检查环境变量 (优先使用 KSYUN_* 金山云 IAM 凭证)
-        ak = os.environ.get("KSYUN_ACCESS_KEY") or os.environ.get("KS3_ACCESS_KEY")
-        sk = os.environ.get("KSYUN_SECRET_KEY") or os.environ.get("KS3_SECRET_KEY")
+        ak = self.access_key or os.environ.get("KSYUN_ACCESS_KEY") or os.environ.get(
+            "KS3_ACCESS_KEY"
+        )
+        sk = self.secret_key or os.environ.get("KSYUN_SECRET_KEY") or os.environ.get(
+            "KS3_SECRET_KEY"
+        )
 
         if not ak or not sk:
             click.secho("❌ 请在 .env 文件中设置金山云 IAM 凭证:", fg="red")

ksadk/builders/managed_runtime_builder.py

@@ -27,6 +27,7 @@ _MANIFEST_KEYS = (
     "soul_digest",
     "skills",
     "mcp_servers",
+    "plugins",
     "sandbox",
     "approval_mode",
     "context",

ksadk/cli/__init__.py

@@ -339,16 +339,33 @@ def _register_optional_command(cli: click.Group, module_path: str, *cmd_names: s
 
 
 def _register_commands():
+    # Runtime fast path: when the hosted entrypoint runs ``ksadk web`` the
+    # process only needs the web command. Importing the other commands here
+    # pulls in deploy/create/run deps (ks3, questionary, ...) that the hosted
+    # Python runtime image does not ship, so a full register crashes the
+    # runtime before the server starts. Only import what argv actually needs;
+    # ``--help`` and other exploratory invocations still register everything.
+    import sys as _sys
+
+    _argv = [a for a in _sys.argv[1:] if not a.startswith("-")]
+    _runtime_only = bool(_argv) and _argv[0] == "web"
+
+    from ksadk.cli.cmd_web import web
+
+    _add_command_once(cli, web)
+
+    if _runtime_only:
+        # Skip create/deploy/run/managed_runtime imports on the runtime path.
+        return
+
     from ksadk.cli.cmd_create import create
     from ksadk.cli.cmd_deploy import deploy
     from ksadk.cli.cmd_managed_runtime import managed_runtime
     from ksadk.cli.cmd_run import run
-    from ksadk.cli.cmd_web import web
 
     # 注册现有命令
     _add_command_once(cli, run)
     _add_command_once(cli, deploy)
-    _add_command_once(cli, web)
     _add_command_once(cli, managed_runtime)
 
     # init 作为主命令 (PRD 规范)
@@ -391,7 +408,7 @@ def _register_commands():
     _register_optional_command(cli, "ksadk.cli.cmd_hermes", "hermes")
 
 
-def main():
+def _main():
     # 全局加载 .env 文件
     try:
         from dotenv import find_dotenv, load_dotenv
@@ -476,5 +493,17 @@ def main():
         raise SystemExit(cli_error.exit_code) from None
 
 
+def main():
+    """Run the CLI without exposing a traceback for an operator interrupt."""
+
+    try:
+        return _main()
+    except KeyboardInterrupt:
+        # Ctrl+C can arrive while optional commands are still importing, before
+        # Click or Uvicorn installs its own signal handling.  Treat it as the
+        # same clean operator stop and preserve the conventional exit status.
+        raise SystemExit(130) from None
+
+
 if __name__ == "__main__":
     main()

ksadk/cli/cmd_managed_runtime.py

@@ -83,8 +83,20 @@ def managed_runtime(manifest_path: Path, port: int, host: str) -> None:
     """Serve one mounted, declarative ``agentengine.yaml`` in hosted mode."""
 
     manifest_path = manifest_path.resolve()
-    _load_managed_runtime_manifest(manifest_path)
+    manifest = _load_managed_runtime_manifest(manifest_path)
     work_dir = _prepare_writable_runtime_dir(manifest_path)
+    from ksadk.plugins.delivery import prepare_cloud_plugins
+
+    try:
+        prepare_cloud_plugins(manifest, work_dir)
+    except Exception as exc:
+        # Transport exceptions can contain signed URLs; keep startup logs secret-free.
+        import httpx
+
+        detail = "artifact transport failed" if isinstance(exc, httpx.HTTPError) else str(exc)
+        raise click.ClickException(
+            "plugin delivery failed before runtime startup: " + detail
+        ) from None
     # The command is a production process entrypoint, never a local UI action.
     # ``web`` owns the RuntimeAdapter composition, while no_open prevents an
     # accidental browser launch if this container is ever run with a display.