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

ksadk/cli/cmd_plugin.py

@@ -41,10 +41,9 @@ def _codex_home() -> Path:
 
 
 def _dsh_home() -> Path:
-    configured = os.environ.get(DSH_HOME_ENV, "").strip()
-    if configured:
-        return Path(configured).expanduser()
-    return Path.cwd() / ".agentkit" / "dsh-home"
+    from ksadk.plugins.dsh_home import studio_dsh_home
+
+    return studio_dsh_home(Path.cwd())
 
 
 def _dsh_command() -> tuple[str, ...] | None:
@@ -55,7 +54,7 @@ def _dsh_command() -> tuple[str, ...] | None:
 
 
 def _dsh_profile() -> str:
-    return os.environ.get(DSH_PROFILE_ENV, "").strip() or "ksadk"
+    return os.environ.get(DSH_PROFILE_ENV, "").strip() or "web"
 
 
 def _codex_inventory_payload(value: Any) -> dict[str, Any]:
@@ -125,14 +124,24 @@ def _call_codex(operation):
         )
 
 
-def _call_dsh(operation):
+def _call_dsh(operation, *, write: bool = False):
     """Run one bounded DSH Profile lifecycle request from the synchronous CLI."""
 
     from ksadk.plugins.bridges.dsh import DshProfilePluginBridge
+    from ksadk.plugins.dsh_home import (
+        DshHomeVersionError,
+        dsh_home_diagnostic,
+        prepare_studio_dsh_home,
+    )
 
     try:
+        home = _dsh_home()
+        # The bridge creates Profile lock directories even for catalog reads.
+        # Fence a fresh home first; an existing legacy catalog remains readable.
+        if write or dsh_home_diagnostic(home)["status"] == "new":
+            prepare_studio_dsh_home(home)
         with DshProfilePluginBridge(
-            dsh_home=_dsh_home(),
+            dsh_home=home,
             profile=_dsh_profile(),
             dsh_command=_dsh_command(),
         ) as bridge:
@@ -140,7 +149,30 @@ def _call_dsh(operation):
     except (KeyboardInterrupt, SystemExit):
         raise
     except Exception as err:
+        if isinstance(err, DshHomeVersionError):
+            abort_with_cli_error(
+                CLIError(
+                    code=err.code,
+                    message=f"DSH 目录版本未经验证。{err.diagnostic['recovery']}",
+                    exit_code=EXIT_CODE_VALIDATION,
+                    details=err.diagnostic,
+                ),
+                context="Plugin",
+            )
         name = type(err).__name__
+        if name == "DshToolchainUnavailableError":
+            abort_with_cli_error(
+                CLIError(
+                    code="dsh_toolchain_unavailable",
+                    message="DSH 插件开发工具链不可用",
+                    exit_code=EXIT_CODE_VALIDATION,
+                    details={
+                        "hint": "运行 `agentengine plugin toolchain install` 安装受管理 DSH 工具链",
+                        "reason": str(err),
+                    },
+                ),
+                context="Plugin",
+            )
         code = (
             "dsh_plugin_not_found"
             if name == "DshPluginNotFoundError"
@@ -165,6 +197,7 @@ def _call_dsh(operation):
                 exit_code=(
                     EXIT_CODE_RESOLUTION if code == "dsh_plugin_not_found" else EXIT_CODE_VALIDATION
                 ),
+                details={"reason": str(err)},
             ),
             context="Plugin",
         )
@@ -173,6 +206,8 @@ def _call_dsh(operation):
 def _call_dsh_developer(operation):
     """Run one bounded standard DSH bundle development operation."""
 
+    import re
+
     from ksadk.plugins.dsh_toolchain import (
         DshPluginPackError,
         DshPluginSourceError,
@@ -182,8 +217,28 @@ def _call_dsh_developer(operation):
         DshToolchainVersionMismatchError,
     )
 
+    _VERSION_PAIR = re.compile(
+        r"expected (?:pnpm|DSH) (?P<expected>[0-9A-Za-z.\-]+), got (?P<actual>[0-9A-Za-z.\-]+)"
+    )
+
+    def _toolchain_error_details(err: Exception) -> dict:
+        details: dict = {}
+        if isinstance(err, DshToolchainVersionMismatchError):
+            match = _VERSION_PAIR.search(str(err))
+            if match:
+                details["expected"] = match.group("expected")
+                details["actual"] = match.group("actual")
+            details["hint"] = (
+                "使用 corepack 启用固定版本 pnpm（corepack enable 后重试），"
+                "或安装 pnpm 11.7.0 并设置 AGENTENGINE_PNPM_BIN 指向该可执行文件"
+            )
+        elif isinstance(err, DshToolchainUnavailableError):
+            details["hint"] = "运行 `agentengine plugin toolchain install` 安装受管理 DSH 工具链"
+        return details
+
     try:
         return operation()
+
     except (KeyboardInterrupt, SystemExit):
         raise
     except Exception as err:
@@ -211,6 +266,12 @@ def _call_dsh_developer(operation):
         stage = getattr(err, "stage", None)
         if isinstance(stage, str) and stage:
             details["stage"] = stage
+        details.update(_toolchain_error_details(err))
+        diagnostic = getattr(err, "diagnostic", None)
+        if isinstance(err, DshPluginSourceError):
+            diagnostic = str(err)
+        if isinstance(diagnostic, str) and diagnostic:
+            details["reason"] = diagnostic
         abort_with_cli_error(
             CLIError(
                 code=code,
@@ -528,7 +589,7 @@ def install_dsh_plugin(source: str, accept_host_permissions: bool) -> None:
             context="Plugin",
         )
     host, item = _call_dsh(
-        lambda bridge: bridge.install_plugin(source, accept_host_permissions=True)
+        lambda bridge: bridge.install_plugin(source, accept_host_permissions=True), write=True
     )
     payload = {
         "item": _dsh_inventory_payload(item),
@@ -545,7 +606,7 @@ def install_dsh_plugin(source: str, accept_host_permissions: bool) -> None:
 def enable_dsh_plugin(plugin_name: str) -> None:
     """在 DSH Profile 中启用已安装的 bundle。"""
 
-    host, item = _call_dsh(lambda bridge: bridge.set_enabled(plugin_name, enabled=True))
+    host, item = _call_dsh(lambda bridge: bridge.set_enabled(plugin_name, enabled=True), write=True)
     payload = {
         "item": _dsh_inventory_payload(item),
         "host": {"id": host.host_id, "version": host.version, "available": True},
@@ -561,7 +622,9 @@ def enable_dsh_plugin(plugin_name: str) -> None:
 def disable_dsh_plugin(plugin_name: str) -> None:
     """从 DSH Profile 组合中停用 bundle，但保留已安装包。"""
 
-    host, item = _call_dsh(lambda bridge: bridge.set_enabled(plugin_name, enabled=False))
+    host, item = _call_dsh(
+        lambda bridge: bridge.set_enabled(plugin_name, enabled=False), write=True
+    )
     payload = {
         "item": _dsh_inventory_payload(item),
         "host": {"id": host.host_id, "version": host.version, "available": True},
@@ -592,7 +655,7 @@ def update_dsh_plugin(plugin_name: str, accept_host_permissions: bool) -> None:
             context="Plugin",
         )
     host, item = _call_dsh(
-        lambda bridge: bridge.update_plugin(plugin_name, accept_host_permissions=True)
+        lambda bridge: bridge.update_plugin(plugin_name, accept_host_permissions=True), write=True
     )
     payload = {
         "item": _dsh_inventory_payload(item),
@@ -609,7 +672,7 @@ def update_dsh_plugin(plugin_name: str, accept_host_permissions: bool) -> None:
 def uninstall_dsh_plugin(plugin_name: str) -> None:
     """从 DSH Profile 卸载一个 bundle。"""
 
-    host, _ = _call_dsh(lambda bridge: bridge.uninstall_plugin(plugin_name))
+    host, _ = _call_dsh(lambda bridge: bridge.uninstall_plugin(plugin_name), write=True)
     payload = {
         "ecosystem": "dsh",
         "integrationMode": "bridged",
@@ -629,7 +692,7 @@ def uninstall_dsh_plugin(plugin_name: str) -> None:
 def dsh_profile_info() -> None:
     """预检并显示当前 DSH Profile 的无 Secret 配置摘要。"""
 
-    host, projection = _call_dsh(lambda bridge: bridge.project_profile())
+    host, projection = _call_dsh(lambda bridge: bridge.project_profile(), write=True)
     payload = {
         "profile": projection.model_dump(mode="json", by_alias=True),
         "host": {"id": host.host_id, "version": host.version, "available": True},

ksadk/cli/cmd_studio.py

@@ -5,6 +5,9 @@ from __future__ import annotations
 import logging
 import os
 import secrets
+import socket
+import threading
+import time
 import webbrowser
 from pathlib import Path
 
@@ -13,6 +16,8 @@ import uvicorn
 
 from ksadk.cli.env_options import load_env_file
 from ksadk.cli.ui import print_info, print_kv, print_success, print_title
+from ksadk.studio.api import create_studio_app
+from ksadk.studio.service import StudioService
 
 # veadk 风格：日志行带模块名与行号（filename:lineno），本地排障时能直接定位代码。
 _LOG_FORMAT = "%(asctime)s %(levelname)s %(name)s %(filename)s:%(lineno)d %(message)s"
@@ -44,8 +49,6 @@ _STUDIO_LOG_CONFIG = {
     "root": {"handlers": ["default"], "level": "INFO"},
 }
 
-from ksadk.studio.api import create_studio_app
-from ksadk.studio.service import StudioService
 
 # 模型环境变量白名单。OPENAI_BASE_URL 与 OPENAI_API_BASE 互为别名，两者都接受；
 # 加载时做别名归一（见 studio()），运行时统一 OPENAI_BASE_URL 优先（与 cmd_config/cmd_model
@@ -56,12 +59,12 @@ _MODEL_ENV_KEYS = (
     "OPENAI_API_KEY",
     "OPENAI_MODEL_NAME",
 )
-# Cloud-control credentials are intentionally process-only as well.  Studio
-# needs them to use the Server Action API for a deployed Agent, but they must
-# never become browser settings, workspace files, or runtime environment.
+# Explicit env-file credentials are process-only overrides. They are never
+# copied into the workspace store or exposed as browser settings.
 _CLOUD_CONTROL_ENV_KEYS = (
     "KSYUN_ACCESS_KEY",
     "KSYUN_SECRET_KEY",
+    "KSYUN_ACCOUNT_ID",
     "KSYUN_REGION",
     "AGENTENGINE_REGION",
     "AGENTENGINE_SERVER_URL",
@@ -71,11 +74,30 @@ _CLOUD_CONTROL_ENV_KEYS = (
     "KS3_ACCESS_KEY",
     "KS3_SECRET_KEY",
 )
-_STUDIO_ENV_FILE_KEYS = (*_MODEL_ENV_KEYS, *_CLOUD_CONTROL_ENV_KEYS)
+_WEB_SEARCH_ENV_KEYS = (
+    "KSADK_WEB_SEARCH_PROVIDER",
+    "KSADK_WEB_SEARCH_API_KEY",
+    "KSADK_WEB_SEARCH_BASE_URL",
+    "KSADK_WEB_SEARCH_SCOPE",
+)
+_STUDIO_ENV_FILE_KEYS = (*_MODEL_ENV_KEYS, *_CLOUD_CONTROL_ENV_KEYS, *_WEB_SEARCH_ENV_KEYS)
 # 别名归一：两者任一有值时，把另一个也设上，保证下游无论读哪个都命中。
 _MODEL_BASE_URL_ALIASES = ("OPENAI_BASE_URL", "OPENAI_API_BASE")
 
 
+def _open_browser_when_ready(url: str, port: int, *, timeout: float = 90.0) -> None:
+    """Open Studio only after Uvicorn accepts loopback connections."""
+
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            with socket.create_connection(("127.0.0.1", port), timeout=0.5):
+                webbrowser.open(url)
+                return
+        except OSError:
+            time.sleep(0.2)
+
+
 @click.command(context_settings=dict(help_option_names=["-h", "--help"]))
 @click.argument("workspace", default=".", type=click.Path())
 @click.option("--port", "-p", default=8080, type=click.IntRange(1, 65535))
@@ -84,7 +106,7 @@ _MODEL_BASE_URL_ALIASES = ("OPENAI_BASE_URL", "OPENAI_API_BASE")
     "--env-file",
     type=click.Path(exists=True, dir_okay=False),
     help=(
-        "本地模型与云端控制环境文件；只读取允许的 OPENAI/KSYUN/KS3 "
+        "本地模型、云端控制与搜索环境文件；只读取允许的 OPENAI/KSYUN/KS3/KSADK_WEB_SEARCH "
         "字段，且仅保留在 Studio 进程"
     ),
 )
@@ -112,6 +134,7 @@ def studio(
     managed_keys = (*_STUDIO_ENV_FILE_KEYS, "KSADK_CODEX_USE_PROXY")
     previous = {key: os.environ.get(key) for key in managed_keys}
     previously_present = {key for key in managed_keys if key in os.environ}
+    configuration_overrides: dict[str, str] = {}
     try:
         if env_file:
             try:
@@ -120,27 +143,36 @@ def studio(
                 raise click.ClickException(str(exc)) from exc
             loaded_models = 0
             loaded_cloud_control = 0
+            loaded_search = 0
             for key, value in values.items():
                 if key not in _STUDIO_ENV_FILE_KEYS or not value:
                     continue
                 if key in _MODEL_ENV_KEYS:
                     loaded_models += 1
+                elif key in _WEB_SEARCH_ENV_KEYS:
+                    loaded_search += 1
                 else:
                     loaded_cloud_control += 1
                 # An explicit --env-file is the operator's selected cloud
-                # identity.  Do not silently reuse inherited AK/SK from the
-                # shell, which can point Studio at another tenant.  Model
-                # values keep their historical shell-first precedence.
-                if key in _CLOUD_CONTROL_ENV_KEYS or key not in os.environ:
-                    os.environ[key] = value
+                # identity and model configuration; it overrides inherited
+                # and saved values consistently for this process.
+                os.environ[key] = value
+                configuration_overrides[key] = os.environ[key]
             # 别名归一（方案 §2.4 第 5 点）：OPENAI_BASE_URL 与 OPENAI_API_BASE 互为别名。
             # 加载后任一有值则把另一个也设上，保证下游无论读哪个都命中；OPENAI_BASE_URL 优先。
-            resolved_base_url = os.environ.get("OPENAI_BASE_URL") or os.environ.get(
-                "OPENAI_API_BASE"
+            resolved_base_url = (
+                configuration_overrides.get("OPENAI_BASE_URL")
+                or configuration_overrides.get("OPENAI_API_BASE")
+                or os.environ.get("OPENAI_BASE_URL")
+                or os.environ.get("OPENAI_API_BASE")
             )
             if resolved_base_url:
                 os.environ["OPENAI_BASE_URL"] = resolved_base_url
                 os.environ["OPENAI_API_BASE"] = resolved_base_url
+                if any(key in configuration_overrides for key in _MODEL_BASE_URL_ALIASES):
+                    configuration_overrides.update(
+                        dict.fromkeys(_MODEL_BASE_URL_ALIASES, resolved_base_url)
+                    )
                 # base_url 至少算一次，避免显示 0/4 误导。
                 loaded_models = max(loaded_models, 2)
             print_kv(
@@ -154,15 +186,23 @@ def studio(
                     f"{loaded_cloud_control}/{len(_CLOUD_CONTROL_ENV_KEYS)} 个字段"
                     "（仅本地进程）",
                 )
+            if loaded_search:
+                print_kv("联网搜索", f"已安全加载 {loaded_search} 个字段（仅本地进程）")
         if codex_proxy == "forced":
             os.environ["KSADK_CODEX_USE_PROXY"] = "1"
         elif codex_proxy == "direct":
             os.environ["KSADK_CODEX_USE_PROXY"] = "0"
         elif codex_proxy == "auto":
             os.environ.pop("KSADK_CODEX_USE_PROXY", None)
+        if codex_proxy != "inherit":
+            configuration_overrides["KSADK_CODEX_USE_PROXY"] = {
+                "forced": "1",
+                "direct": "0",
+                "auto": "",
+            }[codex_proxy]
         session_token = os.environ.get("KSADK_STUDIO_SESSION_TOKEN") or secrets.token_urlsafe(32)
         csrf_token = secrets.token_urlsafe(24)
-        service = StudioService(root)
+        service = StudioService(root, configuration_overrides=configuration_overrides)
         app = create_studio_app(
             root,
             service=service,
@@ -179,7 +219,12 @@ def studio(
         print_success("构建与运行均在本地执行")
         print_info("按 Ctrl+C 停止")
         if not no_open:
-            webbrowser.open(launch_url)
+            threading.Thread(
+                target=_open_browser_when_ready,
+                args=(launch_url, port),
+                daemon=True,
+                name="studio-browser-launcher",
+            ).start()
         # 业务日志（ksadk.*）走 root handler，同样带 filename:lineno。
         logging.basicConfig(level=logging.INFO, format=_LOG_FORMAT)
         uvicorn.run(
@@ -187,6 +232,9 @@ def studio(
             host="127.0.0.1",
             port=port,
             log_level="info",
+            # Lifespan cleanup releases local authority only after HTTP draining.
+            # Bound long-lived/stalled streams so a restart can acquire that authority.
+            timeout_graceful_shutdown=10,
             # Access logging stays enabled through the Studio log config while
             # retaining filename/line-number context for both API and business
             # logs.  This preserves master's observability intent and the

ksadk/cli/cmd_web.py

@@ -40,7 +40,6 @@ _SESSION_ENV_NAMES = (
 _CHECKPOINT_ENV_NAMES = (
     "KSADK_CHECKPOINT_BACKEND",
     "KSADK_CHECKPOINT_PATH",
-    "KSADK_LANGGRAPH_CHECKPOINT_DSN",
 )
 _LOCAL_UI_ENV_NAMES = ("AGENTENGINE_UI_DIR",)
 
@@ -124,8 +123,6 @@ def _ensure_langgraph_sqlite_checkpoint_available() -> None:
             "或显式设置 KSADK_CHECKPOINT_BACKEND=memory/postgres。"
         )
         raise SystemExit(1)
-
-
 def _configure_langgraph_checkpoint_env(
     agent_path: Path,
     *,
@@ -138,11 +135,11 @@ def _configure_langgraph_checkpoint_env(
 
     if checkpoint_backend == "sqlite":
         _ensure_langgraph_sqlite_checkpoint_available()
+        os.environ.pop("KSADK_LANGGRAPH_CHECKPOINT_DSN", None)
         os.environ.setdefault(
             "KSADK_CHECKPOINT_PATH",
             str(agent_path / ".agentengine" / "ui" / "checkpoints.sqlite"),
         )
-        os.environ.pop("KSADK_LANGGRAPH_CHECKPOINT_DSN", None)
         return
 
     if explicit_checkpoint_env_names.intersection(_CHECKPOINT_ENV_NAMES):
@@ -150,10 +147,10 @@ def _configure_langgraph_checkpoint_env(
 
     _ensure_langgraph_sqlite_checkpoint_available()
     os.environ["KSADK_CHECKPOINT_BACKEND"] = "sqlite"
+    os.environ.pop("KSADK_LANGGRAPH_CHECKPOINT_DSN", None)
     os.environ["KSADK_CHECKPOINT_PATH"] = str(
         agent_path / ".agentengine" / "ui" / "checkpoints.sqlite"
     )
-    os.environ.pop("KSADK_LANGGRAPH_CHECKPOINT_DSN", None)
 
 
 def _default_project_stm_if_unset(

ksadk/cli/openclaw_env.py

@@ -248,7 +248,7 @@ def _build_openclaw_env_vars(
     api_key = model_api_key or _resolve_env(
         "OPENCLAW_MODEL_API_KEY", "OPENAI_API_KEY", "LLM_API_KEY", "MODEL_API_KEY"
     )
-    model = model_preference or "glm-5.2"
+    model = model_preference or "deepseek-v4.1-flash"
     explicit_provider_id = model_provider_id or _resolve_env("OPENCLAW_MODEL_PROVIDER_ID")
     inferred_provider_id = explicit_provider_id
     if not inferred_provider_id and model and "/" in model:

ksadk/cli/resource_common.py

@@ -26,6 +26,32 @@ CONTEXT_SETTINGS = dict(help_option_names=["-h", "--help"])
 _CONSOLE = get_console()
 
 
+def build_component_config(
+    *,
+    skill_space_ids: Sequence[str] = (),
+    sandbox_template_id: str | None = None,
+    sandbox_api_key: str | None = None,
+) -> dict[str, dict[str, str]] | None:
+    """Build component_config payload for skill center + sandbox injection.
+
+    When the CLI passes this dict in the deploy/update payload, the server-side
+    build_component_runtime_env injects SKILL_SPACE_ID, KSADK_SKILL_RUNTIME_BACKEND,
+    KSADK_SANDBOX_* and E2B_* environment variables into the runtime pod.
+    """
+    # Keys MUST be PascalCase to match the server-side ComponentConfigSchema
+    # (Pydantic v2 is case-sensitive; snake_case keys are silently ignored).
+    component_config: dict[str, dict[str, str]] = {}
+    resolved = [sid.strip() for sid in skill_space_ids if sid and sid.strip()]
+    if resolved:
+        component_config["SkillWorkspace"] = {"Id": ",".join(resolved)}
+    if sandbox_template_id:
+        sandbox: dict[str, str] = {"Id": sandbox_template_id}
+        if sandbox_api_key:
+            sandbox["ApiKey"] = sandbox_api_key
+        component_config["Sandbox"] = sandbox
+    return component_config or None
+
+
 @dataclass(frozen=True)
 class ResourceActionDescriptor:
     """Explicit resource action metadata shared by help, hints and JSON output."""

ksadk/cli/runtime_bootstrap.py

@@ -31,11 +31,33 @@ def _managed_a2a_card() -> Any:
 def create_runtime_web_app(detection: Any, agent_path: Path) -> FastAPI:
     """Compose one detected project around the canonical RuntimeExecutor."""
 
+    config = dict(getattr(detection, "raw_config", None) or {})
+    managed_runtime = os.getenv("AGENTENGINE_MANAGED_RUNTIME") == "1"
+    if managed_runtime:
+        from ksadk.resource_runtime.managed_projection import native_codex_plugin_bindings
+
+    if managed_runtime and native_codex_plugin_bindings(config):
+        import hashlib
+        import json
+
+        from ksadk.builders.managed_runtime_builder import serialize_managed_runtime_manifest
+
+        launch = json.loads((agent_path / ".agentkit/cloud-plugin-launch.json").read_text())
+        if (
+            launch["manifest_sha256"]
+            != hashlib.sha256(serialize_managed_runtime_manifest(config)).hexdigest()
+        ):
+            raise ValueError("Restored plugin launch does not match the runtime declaration")
+        config.update(launch["config"])
+    if managed_runtime:
+        from ksadk.resource_runtime.managed_projection import apply_managed_platform_resources
+
+        apply_managed_platform_resources(config)
     context = RuntimeLaunchContext(
         runtime_type=str(detection.type.value),
         project_dir=agent_path,
         detection=detection,
-        config=dict(getattr(detection, "raw_config", None) or {}),
+        config=config,
     )
     return create_runtime_app(
         RuntimeAppConfig(