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

ksadk/deployment/providers/serverless.py

@@ -6,6 +6,7 @@ Serverless Provider - 金山云 Serverless 计算引擎 (AgentEngine 托管)
 - Deploy 阶段: 客户端调用 AgentEngine Server API 发起部署
 """
 
+import hashlib
 import json
 import logging
 import os
@@ -25,7 +26,6 @@ from ksadk.builders.container_builder import (
     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
@@ -36,55 +36,46 @@ from ksadk.deployment.base import (
     DeployTarget,
     PackageInfo,
 )
+from ksadk.deployment.env_forward import should_forward_process_env
 from ksadk.deployment.registry import DeployProviderRegistry
 from ksadk.deployment.ui_config import resolve_ui_config, ui_config_to_state_fields
 
 logger = logging.getLogger(__name__)
 
+# CodeBuilder archives put the runnable application below ``runtime/``.  The
+# command and checksum travel together: sending the command for an arbitrary
+# legacy ``--ks3-path`` archive could change its launch semantics, while a
+# fresh locally built archive can be attested and safely admitted as v1.
+_HOSTED_CODE_COMMAND = (
+    "ksadk",
+    "web",
+    "/app/code/runtime",
+    "--port",
+    "8080",
+    "--host",
+    "0.0.0.0",
+    "--no-open",
+)
 
-_DEPLOY_PROCESS_ENV_ALLOWLIST = frozenset(
-    {
-        spec.name
-        for spec in ENV_VAR_REGISTRY
-        if spec.module
-        not in {
-            "builders",
-            "cli",
-            "configs",
-            "web",
-        }
-    }
-) | frozenset(
+
+# 转发规则已迁移至 ksadk.deployment.env_forward（hermes/openclaw deploy 共用）；
+# 保留私有别名以兼容既有调用与测试。
+_should_forward_process_env = should_forward_process_env
+
+# These values authenticate or configure the local deploy/build control plane.
+# They must never enter an Agent runtime merely because they exist in global
+# config, the caller's shell, or a project .env file. A caller can still opt in
+# deliberately through explicit ``--env`` / ``--env-file`` values.
+_CONTROL_PLANE_ONLY_ENV_KEYS = frozenset(
     {
-        "E2B_API_KEY",
-        "E2B_API_URL",
-        "OPENAI_API_BASE",
-        "OPENAI_API_KEY",
-        "OPENAI_BASE_URL",
-        "OPENAI_MODEL_NAME",
-        "SKILL_SPACE_ID",
+        "KCR_PASSWORD",
+        "KCR_REGISTRY",
+        "KCR_USERNAME",
         "KSYUN_ACCESS_KEY",
         "KSYUN_ACCOUNT_ID",
-        "KSYUN_REGION",
         "KSYUN_SECRET_KEY",
     }
 )
-_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"}}
-) | frozenset(
-    {
-        "KSADK_GLOBAL_CONFIG_ENV_KEYS",
-        "KSADK_UPDATED_AT",
-        "KSADK_VERSION",
-    }
-)
-
-
-def _should_forward_process_env(name: str) -> bool:
-    if name in _DEPLOY_PROCESS_ENV_DENYLIST:
-        return False
-    return name in _DEPLOY_PROCESS_ENV_ALLOWLIST or name.startswith(_DEPLOY_PROCESS_ENV_PREFIXES)
 
 
 @DeployProviderRegistry.register("serverless")
@@ -212,11 +203,45 @@ class ServerlessProvider(BaseDeployProvider):
         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 {})
+        explicit = dict(explicit_env_vars or {})
+        for key in _CONTROL_PLANE_ONLY_ENV_KEYS:
+            if key not in explicit:
+                env_vars.pop(key, None)
+        # explicit --env/--env-file (显式 CLI 意图最高，可选择性注入运行时凭证)
+        env_vars.update(explicit)
         env_vars.setdefault("TZ", DEFAULT_RUNTIME_TIMEZONE)
+        env_vars.setdefault("KSADK_DEPLOYMENT_MODE", "ksadk_managed_cloud")
         return env_vars, env_file.exists(), project_env_count
 
+    @staticmethod
+    def _bind_managed_runtime_contract_env(
+        env_vars: Dict[str, str],
+        runtime_config: Optional[Dict[str, str]],
+    ) -> Dict[str, str]:
+        """Keep the deployed provider model aligned with the admitted manifest.
+
+        Credential env files are reusable across projects and commonly contain
+        ``OPENAI_MODEL_NAME``. For a ManagedRuntime declaration, however, the
+        manifest's ``model`` is the admitted source of truth. Letting a generic
+        credential file override it makes capability probing and the actual
+        provider request select different upstream protocols.
+        """
+
+        if not runtime_config:
+            return env_vars
+        try:
+            manifest = yaml.safe_load(str(runtime_config.get("manifest") or ""))
+        except yaml.YAMLError:
+            return env_vars
+        if not isinstance(manifest, dict):
+            return env_vars
+        model = str(manifest.get("model") or "").strip()
+        if not model:
+            return env_vars
+        bound = dict(env_vars)
+        bound["OPENAI_MODEL_NAME"] = model
+        return bound
+
     @staticmethod
     def _inject_ui_runtime_env(
         env_vars: Dict[str, str],
@@ -264,6 +289,18 @@ class ServerlessProvider(BaseDeployProvider):
         with open(metadata_file, "w", encoding="utf-8") as f:
             json.dump(payload, f, indent=2, ensure_ascii=False)
 
+    @staticmethod
+    def _sha256_file(path: Path) -> str:
+        digest = hashlib.sha256()
+        with path.open("rb") as source:
+            for chunk in iter(lambda: source.read(1024 * 1024), b""):
+                digest.update(chunk)
+        return digest.hexdigest()
+
+    @staticmethod
+    def _is_sha256_digest(value: str) -> bool:
+        return len(value) == 64 and all(char in "0123456789abcdef" for char in value.lower())
+
     @staticmethod
     def _serialize_network_config(
         target: DeployTarget, *, is_update: bool = False
@@ -412,9 +449,20 @@ class ServerlessProvider(BaseDeployProvider):
                 return package_info
 
             # 如果没有 no_cache 且有缓存，才使用缓存
-            if not no_cache and not repackage and cached_ks3_path:
+            cached_checksum = str(package_info.metadata.get("code_checksum") or "").strip()
+            if (
+                not no_cache
+                and not repackage
+                and cached_ks3_path
+                and self._is_sha256_digest(cached_checksum)
+            ):
                 logger.info(f"Using cached bundle: {cached_ks3_path}")
                 return package_info
+            if cached_ks3_path and not no_cache and not repackage:
+                # Older metadata had only a KS3 URI.  Re-upload instead of
+                # silently creating a legacy agent that cannot be admitted to
+                # the hosted Kernel path.
+                click.echo("   缓存代码包缺少 SHA-256，重新打包并上传以启用 Kernel 准入")
 
             # 2. 构建 ZIP 包
 
@@ -449,6 +497,7 @@ class ServerlessProvider(BaseDeployProvider):
             if zip_path is None:
                 raise RuntimeError("代码构建成功但未生成 artifact_path")
             package_info.metadata.update(build_result.metadata)
+            package_info.metadata["code_checksum"] = self._sha256_file(zip_path)
             if build_result.metadata.get("manifest_sha256"):
                 target.extra["manifest_sha256"] = build_result.metadata["manifest_sha256"]
             # click.echo(f"   ✅ ZIP 已生成: {zip_path}")
@@ -690,6 +739,9 @@ class ServerlessProvider(BaseDeployProvider):
                 "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(),
+                "manifest": str(
+                    package_info.metadata.get("managed_runtime_manifest") or ""
+                ),
             }
             missing = [key for key, value in runtime_config.items() if not value]
             if missing:
@@ -698,6 +750,11 @@ class ServerlessProvider(BaseDeployProvider):
                     + ", ".join(f"runtime_config.{key}" for key in missing)
                 )
 
+        code_checksum = str(package_info.metadata.get("code_checksum") or "").strip()
+        if not self._is_sha256_digest(code_checksum):
+            code_checksum = ""
+        code_command = list(_HOSTED_CODE_COMMAND) if code_backed and code_checksum else None
+
         try:
             # 获取 dry_run 标识
             is_dry_run = target.extra.get("dry_run", False)
@@ -769,34 +826,37 @@ class ServerlessProvider(BaseDeployProvider):
                             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)
-                        if existing_agent:
-                            agent_exists = True
-                    except Exception as e:
-                        # 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",
-                            )
-                            agent_exists = False
-                        # DryRun 异常表示真实请求被拦截，无法确认 Agent 是否存在。
-                        # 为安全起见，DryRun 假设它存在并走更新路径。
-                        elif "Dry Run" in str(e):
-                            click.secho(
-                                f"   [Dry Run] 假设 Agent {existing_agent_id} 存在", fg="cyan"
-                            )
-                            agent_exists = True
-                        else:
-                            # 其他错误，重新抛出
-                            raise
+                # ``agent_exists`` means the target has already been resolved
+                # (including an explicit ``--agent-id``). Both that path and
+                # the normal state-file lookup must enter the same hot-update
+                # branch. The explicit path must not need a second GetAgent
+                # request merely to enter that branch.
+                if existing_agent_id:
+                    if not agent_exists:
+                        # 有本地状态 → 先检查服务器上是否存在
+                        click.echo(f"   检测到本地状态: {existing_agent_id}")
+                        try:
+                            existing_agent = await client.get_agent(existing_agent_id)
+                            if existing_agent:
+                                agent_exists = True
+                        except Exception as e:
+                            err_msg = str(e).lower()
+                            if "not found" in err_msg or "404" in err_msg or "不存在" in err_msg:
+                                click.secho(
+                                    "   ⚠️  服务器上未找到 Agent "
+                                    f"{existing_agent_id}，将创建新 Agent",
+                                    fg="yellow",
+                                )
+                                agent_exists = False
+                            # DryRun 异常表示真实请求被拦截，无法确认 Agent 是否存在。
+                            # 为安全起见，DryRun 假设它存在并走更新路径。
+                            elif "Dry Run" in str(e):
+                                click.secho(
+                                    f"   [Dry Run] 假设 Agent {existing_agent_id} 存在", fg="cyan"
+                                )
+                                agent_exists = True
+                            else:
+                                raise
 
                     if agent_exists:
                         # Agent 存在 → 执行更新
@@ -828,6 +888,9 @@ class ServerlessProvider(BaseDeployProvider):
 
                         if ks3_config:
                             update_data["ks3"] = ks3_config
+                        if code_checksum:
+                            update_data["code_checksum"] = code_checksum
+                            update_data["code_command"] = code_command
                         elif artifact_type == "Container":
                             image_credential = self._image_credential_from_env(artifact_path)
                             if image_credential:
@@ -843,6 +906,10 @@ class ServerlessProvider(BaseDeployProvider):
                             project_dir,
                             target.extra.get("env_vars") or {},
                         )
+                        env_vars = self._bind_managed_runtime_contract_env(
+                            env_vars,
+                            runtime_config,
+                        )
                         env_vars = self._inject_ui_runtime_env(env_vars, ui_state, local_state)
                         if env_vars:
                             update_data["env_vars"] = env_vars
@@ -951,6 +1018,9 @@ class ServerlessProvider(BaseDeployProvider):
 
                     if ks3_config:
                         request_data["ks3"] = ks3_config
+                    if code_checksum:
+                        request_data["code_checksum"] = code_checksum
+                        request_data["code_command"] = code_command
 
                     # Container 模式: 传递镜像凭证
                     if artifact_type == "Container":
@@ -967,6 +1037,10 @@ class ServerlessProvider(BaseDeployProvider):
                         project_dir,
                         target.extra.get("env_vars") or {},
                     )
+                    env_vars = self._bind_managed_runtime_contract_env(
+                        env_vars,
+                        runtime_config,
+                    )
                     env_vars = self._inject_ui_runtime_env(env_vars, ui_state, local_state)
                     if env_vars:
                         if env_file_exists:

ksadk/evaluation/__init__.py

@@ -7,10 +7,27 @@ from .adapters import (
     TargetAdapterError,
     create_target_adapter,
 )
+from .cloud_binding import CloudBinding, CloudBindingError, CloudBindingStore
+from .cloud_converter import (
+    CloudDatasetColumn,
+    CloudDatasetRow,
+    CloudDatasetSnapshot,
+    EvalSetCloudConversionError,
+    evalset_from_dataset_snapshot,
+    evalset_to_dataset_snapshot,
+)
+from .cloud_service import (
+    CloudEvalSetPreviewError,
+    CloudEvalSetCatalogItem,
+    CloudEvalSetPublishResult,
+    CloudEvalSetPullResult,
+    CloudEvalSetService,
+)
 from .contracts import (
     AssertionSpec,
     AssertionType,
     CaseRun,
+    CloudDatasetRef,
     DataPolicy,
     EvalCase,
     EvalRunReport,
@@ -47,6 +64,18 @@ __all__ = [
     "AssertionType",
     "A2ATargetAdapter",
     "A2ATargetError",
+    "CloudBinding",
+    "CloudBindingError",
+    "CloudBindingStore",
+    "CloudDatasetRef",
+    "CloudDatasetColumn",
+    "CloudDatasetRow",
+    "CloudDatasetSnapshot",
+    "CloudEvalSetPreviewError",
+    "CloudEvalSetCatalogItem",
+    "CloudEvalSetPublishResult",
+    "CloudEvalSetPullResult",
+    "CloudEvalSetService",
     "CaseRun",
     "DataPolicy",
     "EvalCase",
@@ -60,6 +89,7 @@ __all__ = [
     "EvalTurn",
     "EvaluationConfig",
     "EvaluationExecutionError",
+    "EvalSetCloudConversionError",
     "EvaluationNotImplementedError",
     "EvaluationRequest",
     "EvaluationStorage",
@@ -80,5 +110,7 @@ __all__ = [
     "load_evalset",
     "parse_evalset",
     "execute_evaluation",
+    "evalset_from_dataset_snapshot",
+    "evalset_to_dataset_snapshot",
     "create_target_adapter",
 ]

ksadk/evaluation/a2a_adapter.py

@@ -93,7 +93,15 @@ class _ResponseCollector:
             self.context_id = update.context_id or self.context_id
             text = _parts_text(update.artifact.parts)
             if text:
-                self.artifact_chunks.append(text)
+                # canonical executor 的 replace 快照带 ksadk_output_snapshot 标记,
+                # 是权威全文;命中时重置而非继续拼接,避免 delta+快照翻倍。
+                if any(
+                    dict(part.metadata or {}).get("ksadk_output_snapshot")
+                    for part in update.artifact.parts
+                ):
+                    self.artifact_chunks = [text]
+                else:
+                    self.artifact_chunks.append(text)
 
         if response.message:
             self.task_id = response.message.task_id or self.task_id

ksadk/evaluation/adapters.py

@@ -2,10 +2,13 @@
 
 from __future__ import annotations
 
-from typing import Protocol
+from typing import TYPE_CHECKING, Protocol
 
 from .contracts import EvalCase, EvalRunSpec, TargetKind, TargetRef, TargetRun, TargetSnapshot
 
+if TYPE_CHECKING:
+    from .evidence import EvidenceStore
+
 
 class TargetAdapterError(RuntimeError):
     """Classified failure raised by a protocol adapter."""
@@ -27,19 +30,29 @@ class TargetAdapter(Protocol):
     async def snapshot(self, target: TargetRef) -> TargetSnapshot:
         """Resolve a target into an immutable snapshot."""
 
-    async def run_case(
-        self, spec: EvalRunSpec, case: EvalCase, *, attempt: int
-    ) -> TargetRun:
+    async def run_case(self, spec: EvalRunSpec, case: EvalCase, *, attempt: int) -> TargetRun:
         """Execute one case and return its normalized result."""
 
 
-def create_target_adapter(target: TargetRef, *, timeout_seconds: int) -> TargetAdapter:
+def create_target_adapter(
+    target: TargetRef,
+    *,
+    timeout_seconds: int,
+    evidence_store: EvidenceStore | None = None,
+) -> TargetAdapter:
     """Route a target reference to its protocol adapter."""
 
     if target.kind is TargetKind.A2A:
         from .a2a_adapter import A2ATargetAdapter
 
         return A2ATargetAdapter(timeout_seconds=timeout_seconds)
+    if target.kind is TargetKind.LOCAL_SOURCE:
+        from .local_adapter import LocalSourceTargetAdapter
+
+        return LocalSourceTargetAdapter(
+            timeout_seconds=timeout_seconds,
+            evidence_store=evidence_store,
+        )
     raise EvaluationNotImplementedError(
         f"{target.kind.value} target 的评测执行尚未实现；"
         "当前可使用 --validate-only 校验评测集和参数"