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

ksadk/builders/code_builder.py

@@ -9,6 +9,7 @@ Code Builder - zip 打包模式构建
 
 import ast
 import hashlib
+import importlib.metadata as importlib_metadata
 import json
 import os
 import re
@@ -19,8 +20,9 @@ import threading
 import time
 import zipfile
 from concurrent.futures import ThreadPoolExecutor, as_completed
+from datetime import datetime, timezone
 from pathlib import Path
-from typing import List, Optional, Set
+from typing import Any, List, Optional, Set
 from urllib.parse import urlparse
 from urllib.request import Request, urlopen
 
@@ -39,6 +41,154 @@ from ksadk.builders.requirements_utils import (
     parse_requirements_text,
 )
 
+BUILD_INFO_SCHEMA = "ksadk-build-info/v1"
+BUILD_INFO_ARCNAME = "ksadk/BUILD-INFO.json"
+
+
+def _sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _bundled_content_fingerprint(files: List[Any]) -> str:
+    """对 (relative, file_path) 列表计算确定性内容指纹。
+
+    指纹只依赖相对路径与逐文件 sha256，同一来源目录重复打包结果一致，
+    可用于在线上快速判断 zip 里的源码快照是否与某次构建/提交一致。
+    """
+
+    digest = hashlib.sha256()
+    digest.update(f"fingerprint:{BUILD_INFO_SCHEMA}\n".encode("utf-8"))
+    for relative, file_path in sorted(files, key=lambda item: item[0]):
+        digest.update(relative.encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(_sha256_file(file_path).encode("ascii"))
+        digest.update(b"\n")
+    return digest.hexdigest()
+
+
+def _git_provenance(start: Path) -> Optional[dict]:
+    """返回 start 所在 git 仓库的提交信息;非 git 目录返回 None。"""
+
+    def _git(*args: str) -> Optional[str]:
+        try:
+            proc = subprocess.run(
+                ["git", "-C", str(start), *args],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+        except Exception:
+            return None
+        if proc.returncode != 0:
+            return None
+        return proc.stdout.strip()
+
+    toplevel = _git("rev-parse", "--show-toplevel")
+    if not toplevel:
+        return None
+    commit = _git("rev-parse", "HEAD")
+    branch = _git("rev-parse", "--abbrev-ref", "HEAD")
+    status = _git("status", "--porcelain")
+    return {
+        "repo_root": toplevel,
+        "commit": commit,
+        "branch": branch or None,
+        "dirty": bool(status),
+    }
+
+
+def _package_provenance(package_name: str, package_root: Path) -> dict:
+    """采集被 vendored 包的安装来源:dist 元信息 / 本地路径 / git 提交。"""
+
+    info: dict[str, Any] = {
+        "source_dir": str(package_root),
+        "dist_version": None,
+        "installer": None,
+        "direct_url": None,
+        "source_type": "unknown",
+        "git": None,
+    }
+    try:
+        dist = importlib_metadata.distribution(package_name)
+    except Exception:
+        dist = None
+    if dist is not None:
+        info["dist_version"] = dist.version
+        installer = (dist.read_text("INSTALLER") or "").strip()
+        info["installer"] = installer or None
+        raw_direct_url = dist.read_text("direct_url.json")
+        if raw_direct_url:
+            try:
+                direct_url = json.loads(raw_direct_url)
+            except ValueError:
+                direct_url = None
+            if isinstance(direct_url, dict):
+                info["direct_url"] = direct_url.get("url")
+                url = str(direct_url.get("url") or "")
+                dir_info = direct_url.get("dir_info") or {}
+                archive_info = direct_url.get("archive_info") or {}
+                if url.startswith("file://"):
+                    if dir_info.get("editable"):
+                        info["source_type"] = "editable-install"
+                    elif url.endswith(".whl"):
+                        info["source_type"] = "local-wheel"
+                    else:
+                        info["source_type"] = "local-path"
+                elif archive_info:
+                    info["source_type"] = "remote-dist"
+    if info["direct_url"] is None and info["dist_version"] is not None:
+        # pip 从 index 安装的常规 dist 通常不写 direct_url.json
+        info["source_type"] = "installed-dist"
+    if info["source_type"] in {"editable-install", "local-path", "unknown"}:
+        info["git"] = _git_provenance(package_root)
+    return info
+
+
+def build_bundled_source_manifest(
+    package_roots: dict,
+    bundled_files: List[Any],
+) -> dict:
+    """生成随 zip 下发的 BUILD-INFO 内容。
+
+    - ``package_roots``: {package_name: 源码目录}
+    - ``bundled_files``: _iter_bundled_source_files() 的 (name, relative, path) 三元组
+    """
+
+    grouped: dict[str, List[Any]] = {}
+    for package_name, relative, file_path in bundled_files:
+        grouped.setdefault(package_name, []).append((relative, file_path))
+
+    packages: dict[str, Any] = {}
+    for package_name, files in sorted(grouped.items()):
+        package_root = package_roots.get(package_name)
+        provenance = (
+            _package_provenance(package_name, package_root)
+            if package_root is not None
+            else {"source_dir": None, "source_type": "unknown"}
+        )
+        packages[package_name] = {
+            **provenance,
+            "file_count": len(files),
+            "content_fingerprint_sha256": _bundled_content_fingerprint(files),
+        }
+
+    return {
+        "schema": BUILD_INFO_SCHEMA,
+        "built_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "packages": packages,
+    }
+
+
+_NONRELEASE_SOURCE_TYPES = {"editable-install", "local-path", "local-wheel", "unknown"}
+
+
+def _is_release_like_source(provenance: dict) -> bool:
+    return provenance.get("source_type") in {"installed-dist", "remote-dist"}
+
 
 class CodeBuilder(BaseBuilder):
     """Code 模式构建器 - 打包 zip + 依赖"""
@@ -229,6 +379,7 @@ class CodeBuilder(BaseBuilder):
                 self._save_input_fingerprint(zip_path, detection_result)
                 zip_size = zip_path.stat().st_size / (1024 * 1024)
                 click.secho(f"\n✅ 使用已有构建: {zip_path.name} ({zip_size:.2f} MB)", fg="green")
+                self._emit_bundled_ksadk_identity(zip_path)
                 click.echo(
                     "   (如需只重新打包当前代码/runtime，请使用 --repackage；"
                     "如需重装依赖，请使用 --no-cache)"
@@ -275,6 +426,7 @@ class CodeBuilder(BaseBuilder):
         package_started_at = time.monotonic()
         self._package_zip(zip_path, detection_result)
         click.echo(f"   ✓ 打包耗时: {self._format_elapsed(package_started_at)}")
+        self._emit_bundled_ksadk_identity(zip_path)
         self._save_input_fingerprint(zip_path, detection_result)
 
         zip_size = zip_path.stat().st_size
@@ -657,15 +809,18 @@ class CodeBuilder(BaseBuilder):
             "file_digests": file_digests,
         }
 
-    def _iter_bundled_source_files(self):
+    def _bundled_source_package_roots(self) -> dict:
         import ksadk
         import ksadk_runtime_common
 
-        yield from self._iter_bundled_source_package("ksadk", Path(ksadk.__file__).resolve().parent)
-        yield from self._iter_bundled_source_package(
-            "ksadk_runtime_common",
-            Path(ksadk_runtime_common.__file__).resolve().parent,
-        )
+        return {
+            "ksadk": Path(ksadk.__file__).resolve().parent,
+            "ksadk_runtime_common": Path(ksadk_runtime_common.__file__).resolve().parent,
+        }
+
+    def _iter_bundled_source_files(self):
+        for package_name, package_root in self._bundled_source_package_roots().items():
+            yield from self._iter_bundled_source_package(package_name, package_root)
 
     def _iter_bundled_source_package(self, package_name: str, package_root: Path):
         for file_path in sorted(package_root.rglob("*")):
@@ -685,6 +840,32 @@ class CodeBuilder(BaseBuilder):
         parts = relative_path.parts
         return len(parts) >= 2 and parts[0] == "server" and parts[1] == "web-ui"
 
+    def _warn_on_nonrelease_bundled_source(self, build_info: dict) -> None:
+        """vendored ksadk 源码来自本地路径/editable/来源不明时给出醒目提示。
+
+        历史事故:打包机 environment 里的 ksadk 是正式 release 之前的 dev 快照,
+        vendored 进 zip 上线后 runtime 行为与正式版不一致且无从追溯。
+        """
+
+        for package_name, package_info in (build_info.get("packages") or {}).items():
+            if _is_release_like_source(package_info):
+                continue
+            source_desc = (
+                f"type={package_info.get('source_type')} " f"dir={package_info.get('source_dir')}"
+            )
+            git_info = package_info.get("git") or {}
+            if git_info.get("commit"):
+                dirty = " (有未提交改动)" if git_info.get("dirty") else ""
+                source_desc += (
+                    f" git={git_info.get('branch') or '?'}@{str(git_info['commit'])[:12]}{dirty}"
+                )
+            click.secho(
+                f"   ⚠ 打包进 zip 的 {package_name} 不是正式发行版来源 ({source_desc})。"
+                "若这不是有意为之,请先用官方渠道的正式版本重装后再打包; "
+                f"解压 zip 后查看 {BUILD_INFO_ARCNAME} 可核对来源与内容指纹。",
+                fg="yellow",
+            )
+
     def _iter_project_files(self):
         for item in sorted(self.project_dir.iterdir(), key=lambda p: p.name):
             if self._should_skip_root_path(item):
@@ -1617,6 +1798,26 @@ class CodeBuilder(BaseBuilder):
                 )
             self._finish_package_progress()
 
+            # This provenance module is written after the bundled source so a
+            # Code archive can attest to the KsADK source it actually imports.
+            # It deliberately comes from local package bytes / Git only; no
+            # environment value is copied into the archive.
+            zf.writestr(
+                "ksadk/_bundle_identity.py",
+                self._bundle_runtime_identity_source(bundled_source_files),
+            )
+            # 写入 runtime 来源清单:排查"zip 里 vendored 的 ksadk 到底是什么快照"时,
+            # 解压 ksadk/BUILD-INFO.json 即可看到来源/版本/commit/内容指纹,不用进 pod 翻文件。
+            build_info = build_bundled_source_manifest(
+                self._bundled_source_package_roots(),
+                bundled_source_files,
+            )
+            zf.writestr(
+                BUILD_INFO_ARCNAME,
+                json.dumps(build_info, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+            )
+            self._warn_on_nonrelease_bundled_source(build_info)
+
             click.echo(f"   ✓ 打包运行时源码: {bundled_source_count} 个文件")
 
             # 添加 entrypoint
@@ -1626,6 +1827,75 @@ class CodeBuilder(BaseBuilder):
         click.echo(f"   ✓ 打包完成: {len(project_files)} 个项目文件 + {deps_count} 个依赖文件")
         self._emit_package_size_report(zip_path)
 
+    def _bundle_runtime_identity_source(self, bundled_source_files) -> str:
+        """Generate package-local provenance for a Code archive."""
+
+        digest = hashlib.sha256()
+        for package_name, relative, file_path in bundled_source_files:
+            if package_name != "ksadk":
+                continue
+            digest.update(relative.encode("utf-8"))
+            digest.update(b"\0")
+            digest.update(file_path.read_bytes())
+            digest.update(b"\0")
+
+        import ksadk
+        from ksadk.version import VERSION
+
+        source_root = Path(ksadk.__file__).resolve().parent
+        commit = ""
+        try:
+            result = subprocess.run(
+                ["git", "-C", str(source_root.parent), "rev-parse", "HEAD"],
+                capture_output=True,
+                check=True,
+                text=True,
+                timeout=3,
+            )
+            candidate = result.stdout.strip().lower()
+            if re.fullmatch(r"[0-9a-f]{40,64}", candidate):
+                commit = candidate
+        except (OSError, subprocess.SubprocessError):
+            pass
+
+        payload = {
+            "ksadk_version": VERSION,
+            "ksadk_commit": commit,
+            "ksadk_source_digest": digest.hexdigest(),
+        }
+        return (
+            "# Generated by KsADK CodeBuilder; do not edit.\n"
+            f"BUNDLE_IDENTITY = {payload!r}\n"
+        )
+
+    def _emit_bundled_ksadk_identity(self, zip_path: Path) -> None:
+        """Print the KsADK provenance embedded in *this exact* Code archive.
+
+        The code archive shadows packages from the base image.  Reading the
+        generated archive back here prevents a build log from accidentally
+        describing the local CLI environment instead of what will run in the
+        workload.
+        """
+
+        try:
+            with zipfile.ZipFile(zip_path) as zf:
+                source = zf.read("ksadk/_bundle_identity.py").decode("utf-8")
+            _prefix, raw_payload = source.split("=", 1)
+            identity = ast.literal_eval(raw_payload.strip())
+        except (OSError, KeyError, UnicodeDecodeError, ValueError, SyntaxError):
+            click.secho("   ⚠ 未能读取 ZIP 内的 KsADK 来源信息", fg="yellow")
+            return
+
+        if not isinstance(identity, dict):
+            click.secho("   ⚠ ZIP 内的 KsADK 来源信息格式无效", fg="yellow")
+            return
+        version = str(identity.get("ksadk_version") or "unknown")
+        commit = str(identity.get("ksadk_commit") or "unavailable")
+        source_digest = str(identity.get("ksadk_source_digest") or "unavailable")
+        click.echo(f"   KsADK: version={version}")
+        click.echo(f"   KsADK source: commit={commit}")
+        click.echo(f"   KsADK source digest: sha256={source_digest}")
+
     def _emit_package_size_report(self, zip_path: Path, *, limit: int = 8) -> None:
         try:
             with zipfile.ZipFile(zip_path, "r") as zf:
@@ -1741,6 +2011,9 @@ class CodeBuilder(BaseBuilder):
     def _generate_entrypoint(self, detection_result) -> str:
         """生成 entrypoint.py"""
         package_name = Path(detection_result.package_path).name
+        runtime_config_json = json.dumps(
+            self._load_config(), ensure_ascii=False, separators=(",", ":"), default=str
+        )
         return f'''"""
 AgentEngine Code 模式入口
 
@@ -1754,6 +2027,7 @@ zip 包结构:
 import sys
 import os
 import logging
+import json
 from pathlib import Path
 
 # ========== 日志配置 ==========
@@ -1878,13 +2152,15 @@ if has_otlp or has_cloud_monitor_otlp:
         logger.warning(f"Tracing 初始化失败: {{e}}")
 
 # 只装配统一 RuntimeAdapter 执行链；具体 Adapter 在请求开始时由 Registry 创建。
+runtime_build_config = json.loads({runtime_config_json!r})
 runtime_context = RuntimeLaunchContext(
     runtime_type=detection_result.type.value,
     project_dir=Path(CODE_ROOT),
     detection=detection_result,
-    config=dict(getattr(detection_result, "raw_config", None) or {{}}),
+    config=dict(runtime_build_config),
 )
 # managed A2A:KSADK_A2A_RUNTIME_ID 非空时挂 discovery card + 完整数据面 route。
+_managed_a2a_card = None
 _a2a_config = None
 _a2a_adapter = None
 if os.environ.get("KSADK_A2A_RUNTIME_ID", "").strip():

ksadk/builders/container_builder.py

@@ -2,6 +2,7 @@
 Container Builder - Docker 镜像构建
 """
 
+import json
 import os
 import platform
 import shutil
@@ -441,6 +442,9 @@ CMD ["python", "entrypoint.py"]
 
     def _generate_entrypoint(self, detection_result, package_name: str) -> str:
         """生成 entrypoint.py"""
+        runtime_config_json = json.dumps(
+            self._load_config(), ensure_ascii=False, separators=(",", ":"), default=str
+        )
         return f'''"""
 AgentEngine Container 模式入口
 """
@@ -448,6 +452,7 @@ AgentEngine Container 模式入口
 import sys
 import os
 import logging
+import json
 from pathlib import Path
 
 # ========== 日志配置 ==========
@@ -549,15 +554,17 @@ if has_otlp or has_cloud_monitor_otlp:
         logger.warning(f"Tracing 初始化失败: {{e}}")
 
 # 只装配统一 RuntimeAdapter 执行链；具体 Adapter 在请求开始时由 Registry 创建。
+runtime_build_config = json.loads({runtime_config_json!r})
 runtime_context = RuntimeLaunchContext(
     runtime_type=detection_result.type.value,
     project_dir=Path("/app"),
     detection=detection_result,
-    config=dict(getattr(detection_result, "raw_config", None) or {{}}),
+    config=dict(runtime_build_config),
 )
 # managed A2A:KSADK_A2A_RUNTIME_ID 非空时挂 discovery card + 完整数据面 route。
 # discovery card 让 server 探测；数据面 route 让 gateway 转发的 JSON-RPC/REST
 # 能真正落到本 runtime 的 A2A 协议端点（路线 C 直连）。
+_managed_a2a_card = None
 _a2a_config = None
 _a2a_adapter = None
 if os.environ.get("KSADK_A2A_RUNTIME_ID", "").strip():

ksadk/builders/managed_runtime_builder.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import hashlib
 import json
-import zipfile
 from pathlib import Path
 from typing import Any
 
@@ -22,35 +21,47 @@ _MANIFEST_KEYS = (
     "model",
     "models",
     "prompt",
+    "task_prompt",
     "skills",
     "mcp_servers",
     "sandbox",
     "approval_mode",
+    "context",
+    "memory",
 )
 
 
-class _RuntimeManifestDumper(yaml.SafeDumper):
-    """Keep multi-line prompts readable while preserving deterministic bytes."""
-
-
-def _represent_manifest_string(dumper: yaml.SafeDumper, value: str):
-    style = "|" if "\n" in value else None
-    return dumper.represent_scalar("tag:yaml.org,2002:str", value, style=style)
+def managed_runtime_lock_path(manifest_path: Path) -> Path:
+    """Return the immutable lock that accompanies a YAML-only declaration.
 
+    ``ManagedRuntime`` is not a user-code artifact.  Keeping its two small
+    declaration files next to one another makes that visible in both the
+    workspace and the build receipt, while still preserving a historical
+    manifest for rollback.
+    """
 
-_RuntimeManifestDumper.add_representer(str, _represent_manifest_string)
+    return manifest_path.with_suffix(".lock.json")
 
 
 def serialize_managed_runtime_manifest(manifest: dict[str, Any]) -> bytes:
-    """Serialize the canonical ManagedRuntime manifest used by every client."""
+    """Serialize the Server-canonical ManagedRuntime declaration.
+
+    The Server validates ``ManifestSHA256`` after parsing and re-dumping YAML
+    with sorted keys.  Clients must hash those exact canonical bytes instead
+    of the editable source formatting, otherwise a valid Studio/CLI build is
+    rejected during ``CreateAgent``/``UpdateAgent`` admission.
+    """
 
-    return yaml.dump(
+    canonical = yaml.safe_dump(
         manifest,
-        Dumper=_RuntimeManifestDumper,
         allow_unicode=True,
-        sort_keys=False,
+        sort_keys=True,
         default_flow_style=False,
-    ).encode("utf-8")
+        width=10_000,
+    )
+    if not canonical.endswith("\n"):
+        canonical += "\n"
+    return canonical.encode("utf-8")
 
 
 class ManagedRuntimeBuilder(BaseBuilder):
@@ -102,25 +113,28 @@ class ManagedRuntimeBuilder(BaseBuilder):
             "runtime": runtime,
             "manifest_sha256": manifest_sha256,
         }
-        lock_bytes = (
-            json.dumps(lock, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
-        ).encode("utf-8")
+        lock_bytes = (json.dumps(lock, ensure_ascii=False, indent=2, sort_keys=True) + "\n").encode(
+            "utf-8"
+        )
 
         self.build_dir.mkdir(parents=True, exist_ok=True)
         name = str(config.get("name") or self.project_dir.name).strip() or self.project_dir.name
         project_version = str(config.get("version") or "1.0.0").strip() or "1.0.0"
-        artifact_path = self.build_dir / f"{name}-{project_version}-runtime.zip"
-        self._write_bundle(
-            artifact_path,
-            {
-                "agentengine.yaml": manifest_bytes,
-                "runtime-lock.json": lock_bytes,
-            },
+        # This local declaration receipt is retained for Studio rollback.
+        # It is deliberately *not* a ZIP: YAML agents have no user code, no
+        # KS3 artifact and no code-downloader path.  Version alone is mutable
+        # in an editable Agent, so retain the exact canonical YAML plus its
+        # lock under the content digest.
+        artifact_path = self.build_dir / (
+            f"{name}-{project_version}-{manifest_sha256[:16]}-runtime.yaml"
         )
+        lock_path = managed_runtime_lock_path(artifact_path)
+        artifact_path.write_bytes(manifest_bytes)
+        lock_path.write_bytes(lock_bytes)
         return BuildResult(
             success=True,
             artifact_path=artifact_path,
-            artifact_size=artifact_path.stat().st_size,
+            artifact_size=artifact_path.stat().st_size + lock_path.stat().st_size,
             metadata={
                 "agent_name": name,
                 "framework": str(config.get("framework") or ""),
@@ -161,13 +175,3 @@ class ManagedRuntimeBuilder(BaseBuilder):
             elif key in config:
                 normalized[key] = config[key]
         return normalized
-
-    @staticmethod
-    def _write_bundle(path: Path, files: dict[str, bytes]) -> None:
-        with zipfile.ZipFile(path, "w", compression=zipfile.ZIP_DEFLATED) as archive:
-            for name in sorted(files):
-                info = zipfile.ZipInfo(name)
-                info.date_time = (1980, 1, 1, 0, 0, 0)
-                info.compress_type = zipfile.ZIP_DEFLATED
-                info.external_attr = 0o100644 << 16
-                archive.writestr(info, files[name])

ksadk/cli/__init__.py

@@ -68,11 +68,14 @@ ROOT_HELP_COMMANDS = {
     "dashboard",
     "deploy",
     "eval",
+    "evalset",
     "files",
     "init",
     "hermes",
     "launch",
+    "managed-runtime",
     "mcp",
+    "observe",
     "openclaw",
     "run",
     "studio",
@@ -90,11 +93,14 @@ SHORT_HELP_MAP = {
     "dashboard": "打开云端 Agent Dashboard",
     "deploy": "部署到云端",
     "eval": "评测本地、A2A 或 Codex Agent",
+    "evalset": "预览或上传 EvalSet 云端快照",
     "files": "管理 workspace 文件",
     "hermes": "Hermes Agent 资源管理",
     "init": "创建新项目",
     "launch": "一键构建+部署",
+    "managed-runtime": "启动平台托管的 YAML Agent",
     "mcp": "MCP 资源管理",
+    "observe": "导出本地 Agent 观测数据",
     "openclaw": "OpenClaw 资源管理",
     "run": "运行 Agent",
     "studio": "启动本地 Agent 构建控制台",
@@ -179,12 +185,19 @@ class ColoredHelpGroup(click.Group):
         _write_colored_help_row(formatter, "agentengine web", "本地调试 Agent Invoke UI")
         _write_colored_help_row(formatter, "agentengine studio", "本地 Agent 构建控制台")
         _write_colored_help_row(formatter, "agentengine eval", "评测本地、A2A 或 Codex Agent")
+        _write_colored_help_row(formatter, "agentengine evalset", "预览或上传 EvalSet 云端快照")
+        _write_colored_help_row(formatter, "agentengine observe", "导出本地 Agent 观测数据")
 
         # 云端部署
         formatter.write(click.style("  🚀  云端部署:\n\n", fg="blue", bold=True))
         _write_colored_help_row(formatter, "agentengine build", "构建部署制品")
         _write_colored_help_row(formatter, "agentengine deploy", "部署到云端")
         _write_colored_help_row(formatter, "agentengine launch", "一键构建+部署")
+        _write_colored_help_row(
+            formatter,
+            "agentengine managed-runtime",
+            "启动平台托管的 YAML Agent",
+        )
         _write_colored_help_row(formatter, "agentengine agent", "Agent 资源管理")
         _write_colored_help_row(formatter, "agentengine version", "Agent 版本管理")
         _write_colored_help_row(formatter, "agentengine mcp", "MCP 资源管理")
@@ -325,6 +338,7 @@ def _register_optional_command(cli: click.Group, module_path: str, *cmd_names: s
 def _register_commands():
     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
 
@@ -332,6 +346,7 @@ def _register_commands():
     _add_command_once(cli, run)
     _add_command_once(cli, deploy)
     _add_command_once(cli, web)
+    _add_command_once(cli, managed_runtime)
 
     # init 作为主命令 (PRD 规范)
     _add_command_once(cli, create, name="init")
@@ -344,6 +359,8 @@ def _register_commands():
     _register_optional_command(cli, "ksadk.cli.cmd_build", "build")
     _register_optional_command(cli, "ksadk.cli.cmd_studio", "studio")
     _register_optional_command(cli, "ksadk.cli.cmd_eval", "eval")
+    _register_optional_command(cli, "ksadk.cli.cmd_evalset", "evalset")
+    _register_optional_command(cli, "ksadk.cli.cmd_observe", "observe")
     _register_optional_command(cli, "ksadk.cli.cmd_launch", "launch")
     _register_optional_command(cli, "ksadk.cli.cmd_agent", "agent")
     _register_optional_command(cli, "ksadk.cli.cmd_status", "status")

ksadk/cli/cmd_dashboard.py

@@ -64,6 +64,10 @@ _PATH_EMBEDDED_OPTION_HINTS = (
 DEFAULT_PRIVATE_LINK_EXPIRES_SECONDS = 24 * 60 * 60
 MAX_PRIVATE_LINK_EXPIRES_SECONDS = 365 * 24 * 60 * 60
 DEFAULT_REGION = "cn-beijing-6"
+# Hosted UI is the shared interaction surface for platform-managed Agents.
+# The access link keeps the user/session/Agent binding while this path keeps
+# the Web release independent from the Agent runtime image.
+HOSTED_INTERACTION_UI_PATH = "/hosted-ui/chat"
 
 DASHBOARD_RESOURCE = ResourceDescriptor(
     name="Dashboard",
@@ -528,7 +532,17 @@ def _open_dashboard(
     )
     normalized_path = _normalize_ui_path(resolved_ui.path or "/")
     custom_ui_enabled = str(resolved_ui.profile or "").strip().lower() == "custom"
-    link_path = normalized_path if ui_path is not None or custom_ui_enabled else None
+    # Hermes owns its own dashboard surface and OpenClaw takes its gateway
+    # branch below.  The shared Hosted UI is the default only for the generic
+    # ADK/LangChain-compatible profiles; an explicit/custom path always wins.
+    use_hosted_interaction_ui = resolved_ui.profile in {"adk", "langchain"}
+    link_path = (
+        normalized_path
+        if ui_path is not None or custom_ui_enabled
+        else HOSTED_INTERACTION_UI_PATH
+        if use_hosted_interaction_ui
+        else None
+    )
     base_url = _build_base_ui_url(endpoint, normalized_path)
 
     if direct:

ksadk/cli/cmd_deploy.py

@@ -328,7 +328,7 @@ async def _deploy_async(
     agent_id: str | None = None,
 ):
     """异步部署流程"""
-    from ksadk.deployment import DeploymentManager, DeployTarget
+    from ksadk.deployment import DeploymentManager, DeployStatus, DeployTarget
     from ksadk.detection import FrameworkDetector
 
     agent_path = Path(agent_dir).resolve()
@@ -606,7 +606,15 @@ async def _deploy_async(
             result = await provider.deploy(package_info, deploy_target)
 
         if result.is_success():
-            print_success("部署成功")
+            # ``DEPLOYING`` only acknowledges that the control plane accepted
+            # the request.  Runtime creation and the asynchronous
+            # CreateAgent callback may still be pending, so presenting it as a
+            # completed deployment is misleading (and hides a broken
+            # callback/data-plane handoff).
+            if result.status == DeployStatus.RUNNING:
+                print_success("部署成功")
+            else:
+                print_info("部署请求已提交，等待实例就绪")
             print_rule()
             print_kv("名称", result.agent_name or deploy_name)
             if result.agent_id: