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

ksadk/cli/cmd_version.py

@@ -1,14 +1,15 @@
 """agentengine version - Agent 版本资源管理。"""
 
 import os
-import click
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Optional
-from datetime import datetime, timedelta, timezone
+
+import click
 
 from ksadk.api.client import DryRunExit
 from ksadk.cli.agent_ref import merge_agent_inputs, resolve_agent_ref
-from ksadk.cli.dry_run import dry_run_option, run_async_with_dry_run, effective_dry_run
+from ksadk.cli.dry_run import dry_run_option, effective_dry_run, run_async_with_dry_run
 from ksadk.cli.error_utils import abort_with_cli_error, resolution_error
 from ksadk.cli.resource_common import (
     CONTEXT_SETTINGS,
@@ -23,7 +24,8 @@ from ksadk.cli.resource_common import (
     render_descriptor_list,
     render_descriptor_status,
 )
-from ksadk.cli.ui import get_console, output_option as cli_output_option, status_rich_style
+from ksadk.cli.ui import get_console, status_rich_style
+from ksadk.cli.ui import output_option as cli_output_option
 
 console = get_console()
 
@@ -94,8 +96,9 @@ def _extract_agent_id(agent: dict) -> Optional[str]:
     if isinstance(basic, dict):
         agent_id = basic.get("agent_id")
         if agent_id:
-            return agent_id
-    return agent.get("agent_id") or agent.get("id")
+            return str(agent_id)
+    fallback = agent.get("agent_id") or agent.get("id")
+    return str(fallback) if fallback else None
 
 
 async def _resolve_agent_id(agent_ref: str, client) -> Optional[str]:
@@ -147,9 +150,7 @@ async def _resolve_target_agent_id(
         include_project_config=True,
     )
     if not resolved:
-        raise ValueError(
-            "请指定 Agent（--agent 或位置参数），或在当前目录提供可解析的本地配置"
-        )
+        raise ValueError("请指定 Agent（--agent 或位置参数），或在当前目录提供可解析的本地配置")
 
     if resolved.source != "cli":
         console.print(
@@ -162,7 +163,9 @@ async def _resolve_target_agent_id(
     return agent_id
 
 
-@click.group("version", context_settings=CONTEXT_SETTINGS, help=build_resource_group_help(VERSION_RESOURCE))
+@click.group(
+    "version", context_settings=CONTEXT_SETTINGS, help=build_resource_group_help(VERSION_RESOURCE)
+)
 def version():
     pass
 
@@ -345,7 +348,9 @@ def release_version(
     dry_run = effective_dry_run(dry_run)
     try:
         run_async_with_dry_run(
-            _release_version_async(agent_ref, agent_option, name, region, tag, description, dry_run),
+            _release_version_async(
+                agent_ref, agent_option, name, region, tag, description, dry_run
+            ),
             dry_run=dry_run,
             dry_run_resource="version",
             dry_run_action="release",
@@ -437,7 +442,9 @@ def rollback_version(
     dry_run = effective_dry_run(dry_run)
     try:
         run_async_with_dry_run(
-            _rollback_version_async(agent_ref, agent_option, name, region, target, assume_yes, dry_run),
+            _rollback_version_async(
+                agent_ref, agent_option, name, region, target, assume_yes, dry_run
+            ),
             dry_run=dry_run,
             dry_run_resource="version",
             dry_run_action="rollback",
@@ -496,7 +503,7 @@ async def _rollback_version_async(
                     ks3_secret_key=secret_key,
                 )
 
-        fields = [
+        fields: list[tuple[str, str, str | None]] = [
             ("当前版本", str(result.get("current_tag") or "-"), "#58a6ff"),
         ]
         if result.get("message"):

ksadk/cli/cmd_web.py

@@ -1,23 +1,27 @@
 """ksadk web - 启动统一本地 Web UI。"""
 
-import click
+import asyncio
+import os
 import webbrowser
 from pathlib import Path
-import os
+
+import click
+import uvicorn
 import yaml
+
 from ksadk.cli.error_utils import ensure_json_output_supported, print_exception
 from ksadk.cli.local_runtime import reexec_with_project_venv_if_needed
+from ksadk.cli.runtime_bootstrap import create_runtime_web_app
 from ksadk.cli.ui import (
     print_error,
     print_info,
     print_kv,
     print_success,
     print_title,
+    print_warn,
 )
 from ksadk.configs import setup_environment
 from ksadk.detection import FrameworkDetector
-from ksadk.runners.factory import create_runner
-
 
 _PERSISTENT_STM_FRAMEWORKS = {"adk", "langgraph", "langchain", "deepagents"}
 _STM_ENV_NAMES = (
@@ -179,6 +183,47 @@ def _default_project_stm_if_unset(
         )
 
 
+def configure_local_runtime_persistence(
+    agent_path: Path,
+    framework: str,
+    *,
+    explicit_session_env_names: set[str] | None = None,
+    explicit_checkpoint_env_names: set[str] | None = None,
+    explicit_local_ui_env_names: set[str] | None = None,
+) -> None:
+    """Bind locally-run agent state to its project unless the shell overrides it."""
+
+    project_dotenv = _project_dotenv_values(agent_path)
+    if explicit_session_env_names is None:
+        explicit_session_env_names = _explicit_env_names_excluding_project_dotenv(
+            (*_STM_ENV_NAMES, *_SESSION_ENV_NAMES),
+            project_dotenv,
+        )
+    if explicit_checkpoint_env_names is None:
+        explicit_checkpoint_env_names = _explicit_env_names_excluding_project_dotenv(
+            _CHECKPOINT_ENV_NAMES,
+            project_dotenv,
+        )
+    if explicit_local_ui_env_names is None:
+        explicit_local_ui_env_names = _explicit_env_names_excluding_project_dotenv(
+            _LOCAL_UI_ENV_NAMES,
+            project_dotenv,
+        )
+
+    os.environ["KSADK_PROJECT_DIR"] = str(agent_path)
+    local_ui_dir = str(agent_path / ".agentengine" / "ui")
+    if "AGENTENGINE_UI_DIR" not in explicit_local_ui_env_names:
+        os.environ["AGENTENGINE_UI_DIR"] = local_ui_dir
+    else:
+        os.environ.setdefault("AGENTENGINE_UI_DIR", local_ui_dir)
+    _default_project_stm_if_unset(
+        framework,
+        agent_path,
+        explicit_session_env_names=explicit_session_env_names,
+        explicit_checkpoint_env_names=explicit_checkpoint_env_names,
+    )
+
+
 @click.command(context_settings=dict(help_option_names=["-h", "--help"]))
 @click.argument("agent_dir", default=".", type=click.Path(exists=True))
 @click.option("--port", "-p", default=8080, help="Web UI 端口")
@@ -197,13 +242,18 @@ def web(agent_dir: str, port: int, model: str, no_open: bool):
     """
     ensure_json_output_supported(
         "agentengine web",
-        suggestion="请改用 `agentengine dashboard open` 或 `agentengine agent status --output json`。",
+        suggestion=(
+            "请改用 `agentengine dashboard open` 或 " "`agentengine agent status --output json`。"
+        ),
     )
 
     agent_path = Path(agent_dir).resolve()
     command_args = ["web", str(agent_path), "--port", str(port)]
     if model:
         command_args.extend(["--model", model])
+    if no_open:
+        # re-exec 进项目 venv 时透传 --no-open,否则子进程仍会打开浏览器
+        command_args.append("--no-open")
     reexec_with_project_venv_if_needed(agent_path, command_args)
     project_dotenv = _project_dotenv_values(agent_path)
     explicit_session_env_names = _explicit_env_names_excluding_project_dotenv(
@@ -238,36 +288,63 @@ def web(agent_dir: str, port: int, model: str, no_open: bool):
         print_error("未检测到支持的框架")
         raise SystemExit(1)
 
+    if result.type.value == "codex":
+        raw_config = getattr(result, "raw_config", None) or {}
+        if str(raw_config.get("artifact_type") or "").strip().lower() == "managedruntime":
+            from ksadk.managed_runtime import (
+                ManagedRuntimeError,
+                resolve_local_managed_runtime,
+            )
+
+            try:
+                resolved_runtime = asyncio.run(
+                    resolve_local_managed_runtime(
+                        raw_config,
+                        region=os.getenv("KSYUN_REGION", "cn-beijing-6"),
+                    )
+                )
+            except ManagedRuntimeError as exc:
+                print_error(str(exc))
+                raise SystemExit(1) from exc
+            runtime_config = raw_config.setdefault("runtime", {})
+            if isinstance(runtime_config, dict):
+                runtime_config["version"] = resolved_runtime.version
+            print_kv(
+                "Runtime",
+                f"{resolved_runtime.name}@{resolved_runtime.version}",
+                value_style="#58a6ff",
+            )
+            if resolved_runtime.source == "installed-unlocked":
+                print_warn(
+                    "离线使用本机已安装 Runtime；云端构建前请显式锁定版本"
+                    "或连接 AgentEngine 获取默认版本"
+                )
+
     # Map framework types to display names
     framework_map = {
         "adk": "ADK",
         "langchain": "LangChain",
         "langgraph": "LangGraph",
         "deepagents": "DeepAgents",
+        "codex": "Codex",
     }
     display_name = framework_map.get(result.type.value, result.name)
     print_kv("框架", display_name, value_style="#2da44e")
 
-    # 本地 UI 的持久化目录与项目根绑定
-    os.environ["KSADK_PROJECT_DIR"] = str(agent_path)
-    local_ui_dir = str(agent_path / ".agentengine" / "ui")
-    if "AGENTENGINE_UI_DIR" not in explicit_local_ui_env_names:
-        os.environ["AGENTENGINE_UI_DIR"] = local_ui_dir
-    else:
-        os.environ.setdefault("AGENTENGINE_UI_DIR", local_ui_dir)
-    _default_project_stm_if_unset(
-        result.type.value,
+    configure_local_runtime_persistence(
         agent_path,
+        result.type.value,
         explicit_session_env_names=explicit_session_env_names,
         explicit_checkpoint_env_names=explicit_checkpoint_env_names,
+        explicit_local_ui_env_names=explicit_local_ui_env_names,
     )
     launch_path = _configure_custom_ui_env(agent_path)
 
     try:
-        print_info("初始化 Runner...")
-        runner = create_runner(result, str(agent_path))
+        print_info("初始化 RuntimeAdapter...")
+        runtime_app = create_runtime_web_app(result, agent_path)
     except Exception as e:
-        print_exception("Runner 初始化失败", e)
+        print_exception("RuntimeAdapter 初始化失败", e)
         raise SystemExit(1)
 
     print_success("启动统一 Web UI")
@@ -280,7 +357,7 @@ def web(agent_dir: str, port: int, model: str, no_open: bool):
         webbrowser.open(launch_url)
 
     try:
-        runner.run_server(port=port)
+        uvicorn.run(runtime_app, host="127.0.0.1", port=port)
     except KeyboardInterrupt:
         raise SystemExit(0)
     except Exception as e:

ksadk/cli/deploy_utils.py

@@ -1,28 +1,28 @@
 import os
+
 import click
+
 from ksadk.api import AgentEngineClient
 
+
 async def auto_release_version(agent_id: str, region: str, deploy_name: str):
     """部署成功后自动创建版本快照"""
-    from datetime import datetime
-    
+
     access_key = os.getenv("KSYUN_ACCESS_KEY") or os.getenv("KS3_ACCESS_KEY")
     secret_key = os.getenv("KSYUN_SECRET_KEY") or os.getenv("KS3_SECRET_KEY")
-    
+
     client = AgentEngineClient(
         access_key=access_key,
         secret_key=secret_key,
         region=region,
     )
-    
+
     try:
         description = "部署后自动发布"
         result = await client.release_version(
-            agent_id=agent_id,
-            tag=None,  # 自动生成
-            description=description
+            agent_id=agent_id, tag=None, description=description  # 自动生成
         )
-        
+
         click.echo("")
         click.secho(f"✓ 版本快照已创建: {result.get('tag')}", fg="green")
     except Exception as e:
@@ -34,53 +34,53 @@ async def auto_release_version(agent_id: str, region: str, deploy_name: str):
 
 async def auto_rollback_to_previous(agent_id: str, region: str):
     """部署失败时自动回滚到上一版本"""
-    
+
     access_key = os.getenv("KSYUN_ACCESS_KEY") or os.getenv("KS3_ACCESS_KEY")
     secret_key = os.getenv("KSYUN_SECRET_KEY") or os.getenv("KS3_SECRET_KEY")
-    
+
     client = AgentEngineClient(
         access_key=access_key,
         secret_key=secret_key,
         region=region,
     )
-    
+
     try:
         # 获取版本列表，找到最近的历史版本
         versions_result = await client.list_versions(agent_id, page=1, size=5)
         versions = versions_result.get("versions", [])
-        
+
         # 找到需要回滚的目标版本 (统一 snake_case)
         target_version = None
         for v in versions:
             if (v.get("status") or "").lower() == "current":
                 target_version = v
                 break
-        
+
         # 如果没有 Current，则找最新的 Historical
         if not target_version:
             for v in versions:
                 if (v.get("status") or "").lower() == "historical":
                     target_version = v
                     break
-        
+
         if not target_version:
             click.secho("⚠ 无可用稳定版本，跳过自动回滚", fg="yellow")
             return
-        
+
         target_tag = target_version.get("tag")
         click.echo("")
         click.secho(f"⏪ 正在自动回滚到版本: {target_tag}...", fg="yellow")
-        
+
         # 执行回滚
-        result = await client.rollback_version(
+        await client.rollback_version(
             agent_id=agent_id,
             target_tag=target_tag,
             ks3_access_key=access_key,
-            ks3_secret_key=secret_key
+            ks3_secret_key=secret_key,
         )
-        
+
         click.secho(f"✓ 已回滚到版本: {target_tag}", fg="green")
-        
+
     except Exception as e:
         click.secho(f"⚠ 自动回滚失败: {e}", fg="red")
     finally:

ksadk/cli/dry_run.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import asyncio
 import json
 import os
-from typing import Any, Awaitable, Callable, Optional, TypeVar
+from typing import Any, Callable, Coroutine, Optional, TypeVar
 
 import click
 from click.core import ParameterSource
@@ -13,6 +13,7 @@ from click.core import ParameterSource
 from ksadk.api.client import DryRunExit
 from ksadk.cli.resource_common import build_dry_run_envelope
 from ksadk.cli.ui import emit_json, is_json_output
+from ksadk.configs.env_registry import is_sensitive_env_var
 
 _T = TypeVar("_T")
 _DEFAULT_DONE_MSG = "✅ Dry Run Completed: 请求已打印，未执行实际变更。"
@@ -117,7 +118,7 @@ def _mask_if_sensitive(value: Any, *, sensitive: bool) -> Any:
 def _sanitize_dry_run_value(value: Any, *, parent_key: str | None = None) -> Any:
     if isinstance(value, dict):
         env_key = str(value.get("Key") or "")
-        env_sensitive = bool(value.get("IsSensitive")) or _is_sensitive_key(env_key)
+        env_sensitive = bool(value.get("IsSensitive")) or is_sensitive_env_var(env_key)
         sanitized: dict[str, Any] = {}
         for key, item in value.items():
             key_text = str(key)
@@ -172,7 +173,7 @@ def sanitize_dry_run_request(payload: dict[str, Any] | None) -> dict[str, Any]:
 
 
 def run_async_with_dry_run(
-    coro: Awaitable[_T],
+    coro: Coroutine[Any, Any, _T],
     *,
     dry_run: bool,
     done_message: str = _DEFAULT_DONE_MSG,
@@ -200,7 +201,9 @@ def run_async_with_dry_run(
             )
         elif safe_payload:
             click.echo("=" * 60)
-            click.echo(f"Dry Run Mode: {safe_payload.get('method', 'REQUEST')} {safe_payload.get('url', '')}")
+            method = safe_payload.get("method", "REQUEST")
+            url = safe_payload.get("url", "")
+            click.echo(f"Dry Run Mode: {method} {url}")
             click.echo("=" * 60)
             click.echo(f"Headers: {safe_payload.get('headers')}")
             if safe_payload.get("body") is not None:

ksadk/cli/env_options.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import os
 import re
 from pathlib import Path
 
@@ -62,11 +63,93 @@ def resolve_explicit_env_vars(
     env_pairs: tuple[str, ...] | list[str] | None,
     base_dir: Path,
 ) -> dict[str, str]:
+    """Resolve explicit env vars from ``--env-file``/``--env`` (no auto-``./.env``).
+
+    Used by the generic ``agentengine deploy``/``launch`` which read model
+    config from ``agentengine.yaml``, not from ``./.env``. Framework-specific
+    deploys (hermes/openclaw) use ``resolve_runtime_env_overrides`` instead,
+    which auto-discovers ``./.env`` and returns shell_keys for os.environ merge.
+    """
     env_vars = load_env_file(env_file, base_dir=base_dir)
     env_vars.update(parse_env_pairs(env_pairs))
     return env_vars
 
 
+def apply_explicit_env_with_shell_priority(
+    base_env: dict[str, str],
+    cli_env: dict[str, str],
+    auto_dotenv: dict[str, str],
+    shell_keys: set[str],
+) -> dict[str, str]:
+    """Merge env into base with precedence: cli_env > shell > auto_dotenv.
+
+    ``shell_keys`` is the snapshot of ``os.environ`` keys captured BEFORE any
+    env load. ``cli_env`` (``--env``/``--env-file``) is the highest explicit
+    CLI intent and overwrites everything. ``auto_dotenv`` (auto-discovered
+    ``./.env``) only fills keys not already set by shell.
+    """
+    for key, value in auto_dotenv.items():
+        if key in shell_keys:
+            continue
+        base_env.setdefault(key, value)
+    for key, value in cli_env.items():
+        base_env[key] = value
+    return base_env
+
+
+def inject_env_to_environ(
+    cli_env: dict[str, str],
+    auto_dotenv: dict[str, str],
+    shell_keys: set[str],
+) -> int:
+    """Apply env to ``os.environ`` with precedence: cli_env > shell > auto_dotenv.
+
+    ``auto_dotenv`` only fills keys absent from shell (shell wins over auto
+    ``./.env``). ``cli_env`` overwrites shell (explicit CLI intent wins).
+    Returns the number of keys injected from ``auto_dotenv`` (for user-facing
+    messages); ``cli_env`` overwrites are not counted.
+    """
+    loaded = 0
+    for key, value in auto_dotenv.items():
+        if key in shell_keys:
+            continue
+        os.environ.setdefault(key, value)
+        loaded += 1
+    for key, value in cli_env.items():
+        os.environ[key] = value
+    return loaded
+
+
+def resolve_runtime_env_overrides(
+    *,
+    env_file: str | None,
+    extra_env: tuple[str, ...] | list[str] | None,
+    base_dir: Path,
+) -> tuple[dict[str, str], dict[str, str], set[str], str | None]:
+    """Resolve runtime env overrides with precedence ``--env > --env-file > shell > auto ./.env``.
+
+    Returns ``(cli_env, auto_dotenv, shell_keys, source)``:
+    - ``cli_env``: merged ``--env-file`` + ``--env`` (``--env`` wins); explicit
+      CLI intent, overwrites shell at merge time.
+    - ``auto_dotenv``: auto-discovered ``./.env`` (only when ``env_file`` is
+      None); does NOT overwrite shell.
+    - ``shell_keys``: snapshot of ``os.environ`` captured before any load.
+    - ``source``: the file path used (for user-facing messages) or ``None``.
+    """
+    shell_keys = set(os.environ)
+    explicit_file_env = load_env_file(env_file, base_dir=base_dir) if env_file else {}
+    auto_dotenv: dict[str, str] = {}
+    auto_source: str | None = None
+    if not env_file:
+        auto_path = base_dir / ".env"
+        if auto_path.exists():
+            auto_dotenv = load_env_file(str(auto_path), base_dir=base_dir)
+            auto_source = str(auto_path)
+    pair_env = parse_env_pairs(extra_env)
+    cli_env = {**explicit_file_env, **pair_env}
+    return cli_env, auto_dotenv, shell_keys, env_file or auto_source
+
+
 def env_options(func):
     func = click.option(
         "--env-file",

ksadk/cli/error_utils.py

@@ -2,10 +2,10 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
 import os
 import re
 import sys
+from dataclasses import dataclass, field
 from typing import Any, Optional, Sequence, Tuple
 
 import click
@@ -128,9 +128,16 @@ def _looks_like_invalid_cloud_credentials(details: dict[str, Any], msg_lower: st
     return any(marker in msg_lower for marker in markers)
 
 
-def _looks_like_runtime_permission_error(details: dict[str, Any], msg_lower: str, code: int | None) -> bool:
+def _looks_like_runtime_permission_error(
+    details: dict[str, Any], msg_lower: str, code: int | None
+) -> bool:
     remote_code = str(details.get("remote_error_code") or "").strip().lower()
-    if remote_code in {"accessdenied", "accessdeniedexception", "unauthorized", "unauthorizedoperation"}:
+    if remote_code in {
+        "accessdenied",
+        "accessdeniedexception",
+        "unauthorized",
+        "unauthorizedoperation",
+    }:
         return True
     if code in {401, 403} and (
         ("权限" in msg_lower)
@@ -145,7 +152,8 @@ def _looks_like_runtime_permission_error(details: dict[str, Any], msg_lower: str
 
 def _credential_setup_hints() -> list[str]:
     return [
-        "请检查当前 shell 或项目 `.env` 中是否设置了 `KSYUN_ACCESS_KEY` / `KSYUN_SECRET_KEY`（兼容 `KS3_ACCESS_KEY` / `KS3_SECRET_KEY`）。",
+        "请检查当前 shell 或项目 `.env` 中是否设置了 `KSYUN_ACCESS_KEY` / "
+        "`KSYUN_SECRET_KEY`（兼容 `KS3_ACCESS_KEY` / `KS3_SECRET_KEY`）。",
         "先到 AgentEngine Runtime 控制台确认账号是否具备运行时权限: https://ksp.console.ksyun.com/#/agentEngineRuntime",
         "如当前子账号没有权限，请到 IAM 授权页授权: https://uc.console.ksyun.com/pro/iam/#/permission/authorize",
         "如果还没有金山云 AK/SK，请让主账号先到 IAM 控制台创建子账号并生成访问密钥: https://uc.console.ksyun.com/pro/iam/",
@@ -154,7 +162,8 @@ def _credential_setup_hints() -> list[str]:
 
 def _invalid_credential_hints() -> list[str]:
     return [
-        "请检查当前 shell 或项目 `.env` 中的 `KSYUN_ACCESS_KEY` / `KSYUN_SECRET_KEY` 是否填写正确，且没有多余空格。",
+        "请检查当前 shell 或项目 `.env` 中的 `KSYUN_ACCESS_KEY` / "
+        "`KSYUN_SECRET_KEY` 是否填写正确，且没有多余空格。",
         "确认该 AK/SK 未被禁用、删除或重置，并且属于当前要操作的金山云账号。",
         "如需确认账号是否具备 AgentEngine Runtime 权限，可先查看: https://ksp.console.ksyun.com/#/agentEngineRuntime",
         "如果凭证属于子账号但仍然被拒绝，请到 IAM 授权页检查授权: https://uc.console.ksyun.com/pro/iam/#/permission/authorize",
@@ -188,7 +197,9 @@ def _matches_resource_not_found(msg_lower: str, args: Sequence[str], *, resource
     return args[0] == resource
 
 
-def explain_exception(err: Exception, argv: Optional[Sequence[str]] = None) -> Tuple[str, list[str]]:
+def explain_exception(
+    err: Exception, argv: Optional[Sequence[str]] = None
+) -> Tuple[str, list[str]]:
     cli_error = cli_error_from_exception(err, argv=argv)
     return cli_error.message, cli_error.hints
 
@@ -384,7 +395,9 @@ def cli_error_from_exception(
 
     if code == 404 and len(args) >= 2 and args[0] == "dashboard" and args[1] == "share":
         summary = "未找到 Dashboard 分享链接或目标 Agent。"
-        hints.append("请先执行 `agentengine dashboard share list --agent <AgentName|AgentId>` 查看分享链接。")
+        hints.append(
+            "请先执行 `agentengine dashboard share list --agent <AgentName|AgentId>` 查看分享链接。"
+        )
         hints.append("如需先确认 Agent，请执行 `agentengine agent list`。")
         error_code = "resolution_error"
         exit_code = EXIT_CODE_RESOLUTION
@@ -396,22 +409,34 @@ def cli_error_from_exception(
         exit_code = EXIT_CODE_RESOLUTION
     elif code == 404 and _matches_resource_not_found(msg_lower, args, resource="agent"):
         summary = "未找到 Agent。"
-        hints.append("请确认 Agent 名称/ID 是否正确，可先执行 `agentengine agent list` 查看已部署 Agent。")
+        hints.append(
+            "请确认 Agent 名称/ID 是否正确，可先执行 `agentengine agent list` 查看已部署 Agent。"
+        )
         if len(args) >= 2 and args[0] == "dashboard" and args[1] == "list":
             hints.append("`agentengine dashboard list` 不是有效命令。")
-            hints.append("如果要查看分享链接，请使用 `agentengine dashboard share list --agent <AgentName|AgentId>`。")
+            hints.append(
+                "如果要查看分享链接，请使用 "
+                "`agentengine dashboard share list --agent <AgentName|AgentId>`。"
+            )
         elif args and args[0] == "dashboard":
-            hints.append("可显式指定 Agent：`agentengine dashboard open --agent <AgentName|AgentId>`。")
+            hints.append(
+                "可显式指定 Agent：`agentengine dashboard open --agent <AgentName|AgentId>`。"
+            )
         error_code = "resolution_error"
         exit_code = EXIT_CODE_RESOLUTION
     elif code == 404 and _matches_resource_not_found(msg_lower, args, resource="mcp"):
         summary = "未找到 MCP。"
-        hints.append("请确认 MCP 名称/ID 是否正确，可先执行 `agentengine mcp list` 查看已部署 MCP。")
+        hints.append(
+            "请确认 MCP 名称/ID 是否正确，可先执行 `agentengine mcp list` 查看已部署 MCP。"
+        )
         error_code = "resolution_error"
         exit_code = EXIT_CODE_RESOLUTION
     elif code == 404 and _matches_resource_not_found(msg_lower, args, resource="openclaw"):
         summary = "未找到 OpenClaw。"
-        hints.append("请确认 OpenClaw 名称/ID 是否正确，可先执行 `agentengine openclaw list` 查看已部署实例。")
+        hints.append(
+            "请确认 OpenClaw 名称/ID 是否正确，可先执行 "
+            "`agentengine openclaw list` 查看已部署实例。"
+        )
         error_code = "resolution_error"
         exit_code = EXIT_CODE_RESOLUTION
     elif _looks_like_missing_cloud_credentials(details, msg_lower):

ksadk/cli/global_options.py

@@ -10,8 +10,7 @@ from ksadk.cli.ui import build_no_color_click_option, build_output_click_option
 
 def _has_long_option(command: click.Command, option_name: str) -> bool:
     return any(
-        isinstance(param, click.Option) and option_name in param.opts
-        for param in command.params
+        isinstance(param, click.Option) and option_name in param.opts for param in command.params
     )
 
 
@@ -19,7 +18,9 @@ def ensure_global_cli_options(command: click.Command) -> click.Command:
     """Inject hidden common options into groups/commands that do not declare them locally."""
     if not _has_long_option(command, "--dry-run"):
         command.params.insert(0, build_dry_run_click_option(hidden=True, expose_value=False))
-    if not _has_long_option(command, "--output"):
+    if not getattr(command, "disable_global_output_option", False) and not _has_long_option(
+        command, "--output"
+    ):
         command.params.insert(0, build_output_click_option(hidden=True, expose_value=False))
     if not _has_long_option(command, "--no-color"):
         command.params.insert(0, build_no_color_click_option(hidden=True, expose_value=False))

ksadk/cli/local_runtime.py

@@ -3,12 +3,11 @@
 from __future__ import annotations
 
 import os
-from pathlib import Path
 import site
 import sys
+from pathlib import Path
 from typing import Sequence
 
-
 LOCAL_RUNTIME_VENV_REEXEC_ENV = "AGENTENGINE_LOCAL_RUNTIME_VENV_REEXEC"
 LEGACY_WEB_VENV_REEXEC_ENV = "AGENTENGINE_WEB_VENV_REEXEC"