agentengine-sdk-python 0.6.9__py3-none-any.whl → 0.8.0__py3-none-any.whl

ksadk/cli/cmd_invoke.py

@@ -4,16 +4,18 @@ agentengine invoke - 与已部署的 Agent 进行交互
 支持 OpenAI 兼容格式调用，支持流式输出
 """
 
-import click
 import asyncio
 import io
 import json
 import os
+import time
+import uuid
 from datetime import datetime
 from pathlib import Path
 from typing import Any, Callable, Dict, Optional
-import time
-import uuid
+
+import click
+
 from ksadk.api import AgentEngineAPIError, AgentEngineClient
 from ksadk.cli.agent_ref import merge_agent_inputs, resolve_agent_ref, resolve_openclaw_ref
 from ksadk.cli.cmd_files import (
@@ -24,20 +26,28 @@ from ksadk.cli.cmd_files import (
     _normalize_workspace_dir,
     _push_workspace_files,
 )
-from ksadk.cli.resource_common import CONTEXT_SETTINGS, CompatibilityAliasCommand, print_compatibility_hint
+from ksadk.cli.resource_common import (
+    CONTEXT_SETTINGS,
+    CompatibilityAliasCommand,
+    print_compatibility_hint,
+)
 from ksadk.hermes_terminal import run_hermes_terminal_session
 from ksadk.terminal_client import run_terminal_session
 from ksadk_runtime_common.workspace_files.constants import DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES
 
+console: Any = None
+Markdown: Any = None
+Live: Any = None
 try:
-    from rich.console import Console
-    from rich.markdown import Markdown
-    from rich.live import Live
-    console = Console()
+    from rich.console import Console as RichConsole
+    from rich.live import Live as RichLive
+    from rich.markdown import Markdown as RichMarkdown
+
+    console = RichConsole()
+    Markdown = RichMarkdown
+    Live = RichLive
 except ImportError:
-    console = None
-    Markdown = None
-    Live = None
+    pass
 
 
 @click.command(
@@ -84,6 +94,20 @@ except ImportError:
 )
 @click.option("--model", help="指定模型名称")
 @click.option("--show-thinking", is_flag=True, help="显示模型思考过程")
+@click.option(
+    "--api-format",
+    "api_format",
+    type=click.Choice(["auto", "responses", "chat_completions"], case_sensitive=False),
+    default="auto",
+    show_default=True,
+    help="HTTP 协议: auto(优先 responses,不通回退 chat), responses, chat_completions",
+)
+@click.option(
+    "--no-alt-screen",
+    "no_alt_screen",
+    is_flag=True,
+    help="兼容参数；TUI 已默认使用 inline viewport 并保留终端 scrollback",
+)
 def invoke(
     agent_ref: str,
     agent_option: str,
@@ -101,6 +125,8 @@ def invoke(
     verbose_workspace_sync: bool,
     model: str,
     show_thinking: bool,
+    api_format: str,
+    no_alt_screen: bool,
 ):
     """与 Agent 进行交互 (本地或远程)。"""
     run_invoke_command(
@@ -121,6 +147,8 @@ def invoke(
         model=model,
         show_thinking=show_thinking,
         compatibility_alias=True,
+        api_format=None if (api_format or "auto").lower() == "auto" else api_format,
+        no_alt_screen=no_alt_screen,
     )
 
 
@@ -129,9 +157,9 @@ def _resolve_remote_workspace_seed_path(
     remote_workspace_path: str | None,
 ) -> str:
     if remote_workspace_path:
-        return _normalize_workspace_dir(remote_workspace_path)
+        return str(_normalize_workspace_dir(remote_workspace_path))
     default_name = local_workspace.resolve().name or local_workspace.name or "workspace"
-    return _normalize_workspace_dir(default_name)
+    return str(_normalize_workspace_dir(default_name))
 
 
 def _summarize_local_workspace_dir(
@@ -182,10 +210,12 @@ def _describe_workspace_sync_phase(event: dict[str, Any] | None) -> str:
     return "同步 workspace"
 
 
-def _render_workspace_sync_progress_bar(current: object | None, total: object | None, *, width: int = 20) -> str:
+def _render_workspace_sync_progress_bar(
+    current: object | None, total: object | None, *, width: int = 20
+) -> str:
     try:
-        current_value = int(current or 0)
-        total_value = max(int(total or 0), 1)
+        current_value = int(str(current or 0))
+        total_value = max(int(str(total or 0)), 1)
     except (TypeError, ValueError):
         current_value = 0
         total_value = 1
@@ -196,8 +226,8 @@ def _render_workspace_sync_progress_bar(current: object | None, total: object |
 
 def _format_workspace_sync_percent(current: object | None, total: object | None) -> str:
     try:
-        current_value = float(current or 0)
-        total_value = max(float(total or 0), 1.0)
+        current_value = float(str(current or 0))
+        total_value = max(float(str(total or 0)), 1.0)
     except (TypeError, ValueError):
         current_value = 0.0
         total_value = 1.0
@@ -226,7 +256,8 @@ def _build_workspace_sync_progress_emitter(*, verbose: bool) -> Callable[[dict[s
             click.secho(
                 "📂 准备同步 workspace: "
                 f"{event.get('total_files', 0)} 个文件，"
-                f"{_format_size(event.get('total_bytes', 0))} -> workspace:/{event.get('remote_path', '.')}",
+                f"{_format_size(event.get('total_bytes', 0))} -> "
+                f"workspace:/{event.get('remote_path', '.')}",
                 fg="blue",
             )
             ignored_artifacts = list(event.get("ignored_artifacts") or [])
@@ -306,7 +337,7 @@ def _extract_workspace_upload_limit(bootstrap: dict[str, Any] | None) -> int | N
         return None
     raw_limit = workspace.get("max_upload_bytes") or workspace.get("MaxUploadBytes")
     try:
-        limit = int(raw_limit)
+        limit = int(str(raw_limit))
     except (TypeError, ValueError):
         return None
     return limit if limit > 0 else None
@@ -318,7 +349,7 @@ async def _lookup_workspace_upload_limit(
     region: str,
 ) -> int:
     if not agent_ref:
-        return DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES
+        return int(DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES)
 
     try:
         async with AgentEngineClient(region=region) as client:
@@ -327,9 +358,9 @@ async def _lookup_workspace_upload_limit(
             else:
                 payload = await client.get_agent_ui_bootstrap(name=agent_ref)
     except Exception:
-        return DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES
+        return int(DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES)
 
-    return _extract_workspace_upload_limit(payload) or DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES
+    return int(_extract_workspace_upload_limit(payload) or DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES)
 
 
 async def _sync_local_workspace_for_hermes_invoke(
@@ -376,7 +407,8 @@ async def _sync_local_workspace_for_hermes_invoke(
         if item["size_bytes"] > max_upload_bytes:
             raise click.ClickException(
                 "本地目录中存在超过远端 workspace 上传上限的文件："
-                f"{item['path']}（{_format_size(item['size_bytes'])} > {_format_size(max_upload_bytes)}）"
+                f"{item['path']}（{_format_size(item['size_bytes'])} > "
+                f"{_format_size(max_upload_bytes)}）"
             )
 
     if summary["total_bytes"] > max_upload_bytes:
@@ -394,7 +426,7 @@ async def _sync_local_workspace_for_hermes_invoke(
             progress_callback(event)
 
     try:
-        return await _push_workspace_files(
+        result = await _push_workspace_files(
             agent_ref=agent_ref,
             local_dir=local_dir,
             remote_path=remote_path,
@@ -406,11 +438,12 @@ async def _sync_local_workspace_for_hermes_invoke(
             ignore_dev_artifacts=True,
             ignore_git_artifacts=".git" in list(summary.get("ignored_artifacts") or []),
         )
+        if not isinstance(result, dict):
+            raise click.ClickException("同步远端 workspace 返回了无效响应")
+        return result
     except AgentEngineAPIError as exc:
         phase = _describe_workspace_sync_phase(last_progress)
-        raise click.ClickException(
-            f"同步远端 workspace 失败（{phase}）：{exc.message}"
-        ) from exc
+        raise click.ClickException(f"同步远端 workspace 失败（{phase}）：{exc.message}") from exc
 
 
 def run_invoke_command(
@@ -432,6 +465,8 @@ def run_invoke_command(
     show_thinking: bool,
     openclaw_gateway_token: str | None = None,
     compatibility_alias: bool = False,
+    api_format: str | None = None,
+    no_alt_screen: bool = False,
 ):
     """与 Agent 进行交互 (本地或远程)。"""
     if compatibility_alias:
@@ -458,9 +493,8 @@ def run_invoke_command(
     # 加载本地状态
     state = _load_state()
     latest_access: dict[str, Any] = {}
-    reuse_state_session = True
     target_agent: str | None = None
-    
+
     normalized_transport = (transport or "auto").strip().lower() or "auto"
 
     # 确定 Endpoint
@@ -493,25 +527,24 @@ def run_invoke_command(
             state=state,
             persist=_state_matches_target(state, target_agent),
         )
-        reuse_state_session = not agent_input or _state_matches_target(state, target_agent)
 
         # 优先使用 state 里的 endpoint (如果是对应的 agent)
         if latest_access.get("endpoint"):
             endpoint = latest_access["endpoint"]
         elif not agent_input or _state_matches_target(state, target_agent):
             endpoint = state.get("endpoint")
-            
+
         if not endpoint:
             # 自动获取
             endpoint = _get_endpoint(target_agent, region)
 
     # API Key
     api_key = api_key or latest_access.get("api_key") or state.get("api_key")
-    session_id = (
-        session
-        or (state.get("session_id") if reuse_state_session else None)
-        or str(uuid.uuid4())[:8]
-    )
+    # 单次 --message 调用默认开新 session，避免复用 .agentengine.state 里长上下文
+    # 默认每次调用开新 session（单次 -m 与交互 TUI 都是），不复用 .agentengine.state
+    # 里的上次 session，避免长上下文累积导致首包变慢。TUI 内多轮续聊由
+    # InteractionLoop.session_id 维持；跨次想续聊上次会话用显式 --session 指定。
+    session_id = session or str(uuid.uuid4())[:8]
 
     next_state = _load_state() or dict(state)
     for key in ("agent_id", "name", "endpoint", "api_key", "framework"):
@@ -530,7 +563,7 @@ def run_invoke_command(
         latest_access=latest_access,
     )
 
-    click.secho(f"🤖 连接到 Agent", fg="blue", bold=True)
+    click.secho("🤖 连接到 Agent", fg="blue", bold=True)
     click.echo(f"   Endpoint: {endpoint}")
     if _is_openclaw_target(next_state, latest_access):
         if runtime_api_key:
@@ -543,13 +576,13 @@ def run_invoke_command(
         click.echo(f"   Auth:     Bearer {_mask_secret(api_key)}")
     else:
         click.secho("   ⚠️  未发现 API Key，尝试匿名调用", fg="yellow")
-    
+
     if insecure:
         click.secho("   ⚠️  SSL 证书验证已禁用", fg="yellow")
 
     if message:
         # 单次调用模式
-        api_format = asyncio.run(
+        api_format_resolved = asyncio.run(
             _resolve_remote_api_format(
                 endpoint=endpoint,
                 api_key=api_key,
@@ -557,12 +590,23 @@ def run_invoke_command(
                 insecure=insecure,
                 state=next_state,
                 latest_access=latest_access,
+                api_format=api_format,
+            )
+        )
+        asyncio.run(
+            _invoke_once(
+                endpoint,
+                message,
+                runtime_api_key,
+                session_id,
+                True,
+                insecure,
+                model,
+                api_format_resolved,
             )
         )
-        asyncio.run(_invoke_once(endpoint, message, runtime_api_key, session_id, True, insecure, model, api_format))
     else:
         is_hermes_target = _is_hermes_target(next_state, latest_access)
-        is_openclaw_target = _is_openclaw_target(next_state, latest_access)
         if normalized_transport == "chat" and is_hermes_target:
             click.secho("❌ Hermes 不再支持 ksadk 通用 chat TUI。", fg="red")
             click.echo("   浏览器聊天页请改用: agentengine hermes open --chat")
@@ -634,7 +678,7 @@ def run_invoke_command(
                 insecure=insecure,
             )
         else:
-            api_format = asyncio.run(
+            api_format_resolved = asyncio.run(
                 _resolve_remote_api_format(
                     endpoint=endpoint,
                     api_key=api_key,
@@ -642,8 +686,16 @@ def run_invoke_command(
                     insecure=insecure,
                     state=next_state,
                     latest_access=latest_access,
+                    api_format=api_format,
                 )
             )
+            tui_agent_id = (
+                latest_access.get("agent_id")
+                or next_state.get("agent_id")
+                or target_agent
+                or latest_access.get("name")
+                or next_state.get("name")
+            )
             _invoke_tui(
                 endpoint,
                 runtime_api_key,
@@ -651,28 +703,34 @@ def run_invoke_command(
                 insecure,
                 model,
                 show_thinking,
-                api_format=api_format,
+                api_format=api_format_resolved,
                 responses_session_header=(
-                    "x-openclaw-session-key" if _is_openclaw_target(next_state, latest_access) else None
+                    "x-openclaw-session-key"
+                    if _is_openclaw_target(next_state, latest_access)
+                    else None
                 ),
+                no_alt_screen=no_alt_screen,
+                region=region,
+                agent_id=tui_agent_id,
             )
 
 
-
-
 def _invoke_tui(
     endpoint: str,
-    api_key: str = None,
-    session_id: str = None,
+    api_key: Optional[str] = None,
+    session_id: Optional[str] = None,
     insecure: bool = False,
-    model: str = None,
+    model: Optional[str] = None,
     show_thinking: bool = False,
     api_format: str = "chat_completions",
     responses_session_header: str | None = None,
+    no_alt_screen: bool = False,
+    region: str = "cn-beijing-6",
+    agent_id: str | None = None,
 ):
     """使用 TUI 模式调用"""
     from ksadk.runners.remote_runner import RemoteRunner
-    from ksadk.tui import AgentTUI
+    from ksadk.tui.loop import run_tui
 
     runner = RemoteRunner(
         endpoint=endpoint,
@@ -683,22 +741,102 @@ def _invoke_tui(
         api_format=api_format,
         responses_session_header=responses_session_header,
     )
+    # 优先用 ListAgentModels（控制面 action，server 侧封装 runtime catalog，
+    # 避开 CLI 直连 runtime /v1/models 对 openclaw/hermes 的鉴权坑）拿模型列表 +
+    # 当前模型 metadata。失败 fallback 到 _fetch_tui_model_metadata（直连 /v1/models）。
+    model_list = asyncio.run(_fetch_tui_model_list(region=region, agent_id=agent_id))
+    if model_list:
+        runner.available_models = model_list.get("models") or []
+        current_id = model_list.get("current")
+        matched = None
+        if current_id:
+            matched = next((m for m in runner.available_models if m.get("id") == current_id), None)
+        if matched is None and runner.available_models:
+            matched = runner.available_models[0]
+        if matched:
+            setattr(runner, "model_metadata", matched)
+            # 用户未指定 --model 时，用 ListAgentModels 的 current 作为 runner.model，
+            # 让 TUI 启动即显示真实模型名（而非 unknown）。
+            if not runner.model and matched.get("id"):
+                runner.model = str(matched["id"])
+    else:
+        # fallback：直连 runtime /v1/models（旧路径，托管 runtime 常失败但不阻断）
+        model_metadata = asyncio.run(
+            _fetch_tui_model_metadata(endpoint=endpoint, api_key=api_key, model=model)
+        )
+        if model_metadata:
+            setattr(runner, "model_metadata", model_metadata)
 
-    app = AgentTUI(
-        runner=runner,
-        show_thinking=show_thinking,
-        project_dir=".",
-    )
-    app.run()
+    run_tui(runner, show_thinking=show_thinking, project_dir=".", no_alt_screen=no_alt_screen)
+
+
+async def _fetch_tui_model_list(
+    *,
+    region: str,
+    agent_id: str | None,
+) -> dict[str, Any] | None:
+    """通过控制面 ListAgentModels action 拿 Agent 可选模型列表（对标 hosted UI）。
+
+    需 KSYUN access/secret key（env），与 _fetch_remote_access 同套鉴权。
+    失败返回 None（不阻断 TUI，由 _fetch_tui_model_metadata fallback）。
+    """
+    if not agent_id:
+        return None
+    try:
+        from ksadk.api.client import AgentEngineClient
+
+        async with AgentEngineClient(region=region) as client:
+            payload = await client.list_agent_models(agent_id=agent_id)
+            return payload if isinstance(payload, dict) else None
+    except Exception:
+        return None
+
+
+async def _fetch_tui_model_metadata(
+    *,
+    endpoint: str,
+    api_key: str | None,
+    model: str | None,
+) -> dict[str, Any] | None:
+    try:
+        from ksadk.cli.model_catalog import (
+            fetch_provider_model_catalog,
+            find_model_in_catalog,
+        )
+        from ksadk.conversations.model_context import normalize_model_metadata
+
+        catalog = await fetch_provider_model_catalog(
+            api_base=endpoint,
+            api_key=api_key,
+            timeout=3.0,
+        )
+    except Exception:
+        return None
+
+    if not catalog:
+        return None
+    raw_models = [item.get("_provider_raw_model") or item for item in catalog]
+    matched = find_model_in_catalog(raw_models, model)
+    if matched is not None:
+        metadata = normalize_model_metadata(matched)
+        return metadata if isinstance(metadata, dict) else None
+    if model:
+        return None
+    if len(catalog) == 1:
+        item = dict(catalog[0])
+        item.pop("_provider_raw_model", None)
+        return item
+    return None
 
 
 def _load_state() -> dict:
     """从 .agentengine.state 加载状态"""
     import yaml
+
     state_file = Path(".") / ".agentengine.state"
     if state_file.exists():
         try:
-            with open(state_file, 'r', encoding='utf-8') as f:
+            with open(state_file, "r", encoding="utf-8") as f:
                 return yaml.safe_load(f) or {}
         except Exception:
             pass
@@ -726,15 +864,13 @@ def _extract_remote_access(detail: Dict[str, Any]) -> Dict[str, Any]:
     if not isinstance(detail, dict):
         return {}
 
-    basic = detail.get("basic") if isinstance(detail.get("basic"), dict) else {}
-    quick = detail.get("quick_access") if isinstance(detail.get("quick_access"), dict) else {}
-
-    deployment = detail.get("deployment") if isinstance(detail.get("deployment"), dict) else {}
-    framework = (
-        deployment.get("framework")
-        or basic.get("framework")
-        or detail.get("framework")
-    )
+    basic_value = detail.get("basic")
+    quick_value = detail.get("quick_access")
+    deployment_value = detail.get("deployment")
+    basic: Dict[str, Any] = basic_value if isinstance(basic_value, dict) else {}
+    quick: Dict[str, Any] = quick_value if isinstance(quick_value, dict) else {}
+    deployment: Dict[str, Any] = deployment_value if isinstance(deployment_value, dict) else {}
+    framework = deployment.get("framework") or basic.get("framework") or detail.get("framework")
 
     return {
         "agent_id": basic.get("agent_id") or detail.get("agent_id"),
@@ -752,9 +888,13 @@ async def _fetch_remote_access(target_agent: str, region: str) -> Dict[str, Any]
 
     async with AgentEngineClient(region=region) as client:
         try:
-            return _extract_remote_access(await client.get_agent(agent_id=target_agent, include_api_key=True))
+            return _extract_remote_access(
+                await client.get_agent(agent_id=target_agent, include_api_key=True)
+            )
         except Exception:
-            return _extract_remote_access(await client.get_agent(name=target_agent, include_api_key=True))
+            return _extract_remote_access(
+                await client.get_agent(name=target_agent, include_api_key=True)
+            )
 
 
 def _refresh_remote_access(
@@ -783,22 +923,20 @@ def _refresh_remote_access(
 
 
 def _is_hermes_target(state: dict, latest_access: dict) -> bool:
-    framework = str(
-        latest_access.get("framework")
-        or state.get("framework")
-        or state.get("type")
-        or ""
-    ).strip().lower()
+    framework = (
+        str(latest_access.get("framework") or state.get("framework") or state.get("type") or "")
+        .strip()
+        .lower()
+    )
     return framework == "hermes"
 
 
 def _is_openclaw_target(state: dict, latest_access: dict) -> bool:
-    framework = str(
-        latest_access.get("framework")
-        or state.get("framework")
-        or state.get("type")
-        or ""
-    ).strip().lower()
+    framework = (
+        str(latest_access.get("framework") or state.get("framework") or state.get("type") or "")
+        .strip()
+        .lower()
+    )
     return framework == "openclaw"
 
 
@@ -812,13 +950,17 @@ def _mask_secret(secret: str | None) -> str:
 
 
 def _openclaw_auth_mode(state: dict, latest_access: dict) -> str:
-    return str(
-        latest_access.get("openclaw_auth_mode")
-        or latest_access.get("gateway_auth_mode")
-        or state.get("openclaw_auth_mode")
-        or state.get("gateway_auth_mode")
-        or ""
-    ).strip().lower()
+    return (
+        str(
+            latest_access.get("openclaw_auth_mode")
+            or latest_access.get("gateway_auth_mode")
+            or state.get("openclaw_auth_mode")
+            or state.get("gateway_auth_mode")
+            or ""
+        )
+        .strip()
+        .lower()
+    )
 
 
 def _select_runtime_api_key(
@@ -846,26 +988,28 @@ def _select_runtime_api_key(
     auth_mode = _openclaw_auth_mode(state, latest_access)
     if auth_mode in {"token", "password"}:
         raise click.ClickException(
-            "当前 OpenClaw Gateway 为 token/password 模式，agentengine invoke 需要 OpenClaw Gateway token。\n"
+            "当前 OpenClaw Gateway 为 token/password 模式，"
+            "agentengine invoke 需要 OpenClaw Gateway token。\n"
             "请使用: agentengine invoke --gateway-token <token>\n"
             "或设置: OPENCLAW_GATEWAY_TOKEN=<token> agentengine invoke\n"
-            "如果部署时传过 OPENCLAW_GATEWAY_TOKEN，请重新运行部署让本地 .agentengine.state 记录该 token。\n"
-            "注意：这里不是 AgentEngine API Key（ak-*），而是 OPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORD。"
+            "如果部署时传过 OPENCLAW_GATEWAY_TOKEN，请重新运行部署让本地 "
+            ".agentengine.state 记录该 token。\n"
+            "注意：这里不是 AgentEngine API Key（ak-*），而是 "
+            "OPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORD。"
         )
 
     return api_key
 
 
 def _select_remote_api_format(state: dict, latest_access: dict) -> str:
-    framework = str(
-        latest_access.get("framework")
-        or state.get("framework")
-        or state.get("type")
-        or ""
-    ).strip().lower()
-    if framework in {"openclaw", "hermes"}:
-        return "responses"
-    return "chat_completions"
+    """auto 模式下所有框架首选 responses（probe 不通再回退 chat_completions）。"""
+    return "responses"
+
+
+# probe 结果进程内短缓存，key=endpoint，value=(过期时间戳, 是否暴露 responses)。
+# 避免每次 invoke 都多打一跳 GET /v1/responses。
+_RESPONSES_ROUTE_CACHE: dict[tuple, tuple[float, bool]] = {}
+_RESPONSES_ROUTE_CACHE_TTL = 30.0
 
 
 async def _resolve_remote_api_format(
@@ -876,23 +1020,65 @@ async def _resolve_remote_api_format(
     insecure: bool,
     state: dict,
     latest_access: dict,
+    api_format: str | None = None,
 ) -> str:
-    api_format = _select_remote_api_format(state, latest_access)
-    if api_format != "responses" or not _is_openclaw_target(state, latest_access):
-        return api_format
-
+    # 显式指定 api_format（非 auto）时直接用，不 probe。
+    explicit = str(api_format or "").strip().lower()
+    if explicit in {"responses", "chat_completions"}:
+        return explicit
+
+    # auto：按框架决定首选格式，probe /v1/responses 不通回退 chat_completions。
+    preferred = _select_remote_api_format(state, latest_access)
+    if preferred != "responses":
+        return preferred
     probe_api_key = runtime_api_key if runtime_api_key is not None else api_key
-    if await _probe_openclaw_responses_route(endpoint=endpoint, api_key=probe_api_key, insecure=insecure):
-        return api_format
+    # openclaw/hermes 的 responses 用独立 gateway 鉴权头，GET 401 不代表 POST 401，
+    # 保留 401=可用的既有行为；普通框架 401=鉴权不通，回退 chat。
+    treat_401 = _is_openclaw_target(state, latest_access) or _is_hermes_target(state, latest_access)
+    if await _probe_responses_route_cached(
+        endpoint=endpoint,
+        api_key=probe_api_key,
+        insecure=insecure,
+        treat_401_as_available=treat_401,
+    ):
+        return "responses"
+    return "chat_completions"
+
 
-    raise click.ClickException(
-        "当前 OpenClaw endpoint 未暴露 /v1/responses，不能使用 agentengine invoke 的 HTTP TUI。\n"
-        "可先使用: agentengine dashboard open\n"
-        "如果要命令行交互，请升级/修复 OpenClaw 镜像或 bootstrap，使 Gateway 暴露 OpenResponses API。"
+# probe 结果进程内短缓存。cache key 含 treat_401：同一 endpoint 在 openclaw/hermes
+# 与普通框架下对 401 的解读不同，分开缓存避免串味。
+async def _probe_responses_route_cached(
+    *,
+    endpoint: str,
+    api_key: str | None,
+    insecure: bool,
+    treat_401_as_available: bool = False,
+) -> bool:
+    import time as _time
+
+    cache_key = (endpoint.rstrip("/"), treat_401_as_available)
+    now = _time.time()
+    cached = _RESPONSES_ROUTE_CACHE.get(cache_key)
+    if cached and cached[0] > now:
+        return cached[1]
+
+    available = await _probe_responses_route(
+        endpoint=endpoint,
+        api_key=api_key,
+        insecure=insecure,
+        treat_401_as_available=treat_401_as_available,
     )
+    _RESPONSES_ROUTE_CACHE[cache_key] = (now + _RESPONSES_ROUTE_CACHE_TTL, available)
+    return available
 
 
-async def _probe_openclaw_responses_route(*, endpoint: str, api_key: str | None, insecure: bool) -> bool:
+async def _probe_responses_route(
+    *,
+    endpoint: str,
+    api_key: str | None,
+    insecure: bool,
+    treat_401_as_available: bool = False,
+) -> bool:
     try:
         import httpx
     except ImportError:
@@ -912,12 +1098,19 @@ async def _probe_openclaw_responses_route(*, endpoint: str, api_key: str | None,
     except Exception:
         return False
 
-    # POST-only API routes usually answer GET with 405/422/400. A 404 or HTML 200
-    # means the request fell through to the OpenClaw UI/router instead of the API.
-    return response.status_code in {400, 401, 405, 422}
+    # POST-only API routes usually answer GET with 405/422/400 = 路由存在且鉴权通过。
+    # 401 = 未鉴权：带 key 仍 401 说明该 key 不被 responses 路由接受，走 responses 也会 401，
+    # 应回退 chat。openclaw/hermes 的 responses 用独立 gateway 鉴权头，GET 401 不代表 POST 401，
+    # 由 treat_401_as_available 保留其既有行为。404/HTML 200 = 路由不存在。
+    available = response.status_code in {400, 405, 422}
+    if treat_401_as_available and response.status_code == 401:
+        available = True
+    return available
 
 
-def _should_use_hermes_native_tui(*, transport: str, local: bool, state: dict, latest_access: dict) -> bool:
+def _should_use_hermes_native_tui(
+    *, transport: str, local: bool, state: dict, latest_access: dict
+) -> bool:
     if transport == "chat":
         return False
     if transport == "native":
@@ -927,7 +1120,9 @@ def _should_use_hermes_native_tui(*, transport: str, local: bool, state: dict, l
     return _is_hermes_target(state, latest_access)
 
 
-def _should_use_openclaw_native_tui(*, transport: str, local: bool, state: dict, latest_access: dict) -> bool:
+def _should_use_openclaw_native_tui(
+    *, transport: str, local: bool, state: dict, latest_access: dict
+) -> bool:
     if transport == "chat":
         return False
     if transport == "native":
@@ -939,14 +1134,16 @@ def _should_use_openclaw_native_tui(*, transport: str, local: bool, state: dict,
 
 def _invoke_hermes_terminal_tui(
     endpoint: str,
-    api_key: str = None,
-    session_id: str = None,
+    api_key: Optional[str] = None,
+    session_id: Optional[str] = None,
     insecure: bool = False,
     cwd: str | None = None,
 ):
     click.secho("🖥️  Hermes Native Remote TUI", fg="blue", bold=True)
     click.echo("   退出: Ctrl-D 或 Ctrl-C")
-    click.echo("   新 Pod 首次启动会加载 Hermes tools/skills，可能需要几十秒到 1 分钟；后续进入会更快。")
+    click.echo(
+        "   新 Pod 首次启动会加载 Hermes tools/skills，可能需要几十秒到 1 分钟；后续进入会更快。"
+    )
     try:
         _warmup_hermes_terminal(
             endpoint=endpoint,
@@ -1005,8 +1202,8 @@ def _warmup_hermes_terminal(
 
 def _invoke_openclaw_terminal_tui(
     endpoint: str,
-    api_key: str = None,
-    session_id: str = None,
+    api_key: Optional[str] = None,
+    session_id: Optional[str] = None,
     insecure: bool = False,
 ):
     click.secho("🖥️  OpenClaw Native Remote TUI", fg="blue", bold=True)
@@ -1039,15 +1236,16 @@ def _get_api_key() -> Optional[str]:
 
 def _get_endpoint(agent_ref: str, region: str) -> str:
     """获取 Agent Endpoint（先按 ID，再按名称）"""
-    from ksadk.api import AgentEngineClient
     import asyncio
 
-    async def _get():
+    from ksadk.api import AgentEngineClient
+
+    async def _get() -> str:
         async with AgentEngineClient(region=region) as client:
             # 1) 优先按 ID 查询
             try:
                 res = await client.get_agent(agent_id=agent_ref)
-                endpoint = _extract_remote_access(res).get("endpoint", "")
+                endpoint = str(_extract_remote_access(res).get("endpoint") or "").strip()
                 if endpoint:
                     return endpoint
             except Exception:
@@ -1055,13 +1253,14 @@ def _get_endpoint(agent_ref: str, region: str) -> str:
 
             # 2) 回退按名称查询
             res = await client.get_agent(name=agent_ref)
-            endpoint = _extract_remote_access(res).get("endpoint", "")
+            endpoint = str(_extract_remote_access(res).get("endpoint") or "").strip()
             if endpoint:
                 return endpoint
 
             # endpoint 为空时，尽量提取真实 ID 供默认域名拼接
-            basic = res.get("basic", {})
-            return basic.get("agent_id") or res.get("agent_id") or ""
+            basic_value = res.get("basic")
+            basic = basic_value if isinstance(basic_value, dict) else {}
+            return str(basic.get("agent_id") or res.get("agent_id") or "")
 
     try:
         resolved = asyncio.run(_get())
@@ -1081,16 +1280,16 @@ def _get_endpoint(agent_ref: str, region: str) -> str:
 async def _invoke_once(
     endpoint: str,
     message: str,
-    api_key: str = None,
-    session_id: str = None,
+    api_key: Optional[str] = None,
+    session_id: Optional[str] = None,
     stream: bool = True,
     insecure: bool = False,
-    model: str = None,
+    model: Optional[str] = None,
     api_format: str = "chat_completions",
 ):
     """单次调用"""
     click.echo(f"\n👤 你: {message}")
-    click.echo(f"🤖 Agent: ", nl=False)
+    click.echo("🤖 Agent: ", nl=False)
 
     try:
         if stream:
@@ -1098,12 +1297,19 @@ async def _invoke_once(
             if Live and Markdown:
                 # 降低刷新率减少闪烁，vertical_overflow="visible"防止回滚丢失
                 # 手动控制刷新以减少闪烁
-                with Live(Markdown("", justify="left"), console=console, auto_refresh=False, vertical_overflow="visible") as live:
-                    last_refresh_time = 0
+                with Live(
+                    Markdown("", justify="left"),
+                    console=console,
+                    auto_refresh=False,
+                    vertical_overflow="visible",
+                ) as live:
+                    last_refresh_time = 0.0
                     full_reasoning = ""
-                    async for chunk in _stream_chat(endpoint, message, api_key, session_id, True, insecure, model, api_format):
+                    async for chunk in _stream_chat(
+                        endpoint, message, api_key, session_id, True, insecure, model, api_format
+                    ):
                         content, reasoning = _extract_content(chunk)
-                        
+
                         updated = False
                         if reasoning:
                             full_reasoning += reasoning
@@ -1111,25 +1317,27 @@ async def _invoke_once(
                         if content:
                             full_response += content
                             updated = True
-                            
+
                         if updated:
                             # 构造显示文本
                             display_text = ""
                             if full_reasoning:
-                                formatted_reasoning = full_reasoning.replace('\n', '\n> ')
+                                formatted_reasoning = full_reasoning.replace("\n", "\n> ")
                                 display_text += f"> 🧠 **Thinking:**\n> {formatted_reasoning}\n\n"
                             display_text += full_response
-                            
+
                             live.update(Markdown(display_text, justify="left"))
-                            
+
                             # 基于时间限流刷新 (每0.2秒一次 = 5 FPS)
                             now = time.time()
                             if now - last_refresh_time > 0.2:
                                 live.refresh()
                                 last_refresh_time = now
-                    live.refresh() # 确保最后一次刷新
+                    live.refresh()  # 确保最后一次刷新
             else:
-               async for chunk in _stream_chat(endpoint, message, api_key, session_id, True, insecure, model, api_format):
+                async for chunk in _stream_chat(
+                    endpoint, message, api_key, session_id, True, insecure, model, api_format
+                ):
                     content, reasoning = _extract_content(chunk)
                     if reasoning:
                         click.secho(reasoning, fg="bright_black", nl=False)
@@ -1137,7 +1345,9 @@ async def _invoke_once(
                         print(content, end="", flush=True)
             click.echo()  # 换行
         else:
-            response = await _chat(endpoint, message, api_key, session_id, insecure, model, api_format)
+            response = await _chat(
+                endpoint, message, api_key, session_id, insecure, model, api_format
+            )
             content = _extract_response_content(response)
             if console and Markdown:
                 console.print(Markdown(content))
@@ -1147,16 +1357,15 @@ async def _invoke_once(
         click.secho(f"\n❌ 调用失败: {e}", fg="red")
 
 
-
 async def _chat(
     endpoint: str,
     message: str,
-    api_key: str = None,
-    session_id: str = None,
+    api_key: Optional[str] = None,
+    session_id: Optional[str] = None,
     insecure: bool = False,
-    model: str = None,
+    model: Optional[str] = None,
     api_format: str = "chat_completions",
-) -> dict:
+) -> dict[str, Any]:
     """非流式调用 (OpenAI 兼容格式)"""
     try:
         import httpx
@@ -1167,10 +1376,16 @@ async def _chat(
     normalized_api_format = str(api_format or "chat_completions").strip().lower()
     if normalized_api_format == "responses":
         url = f"{endpoint.rstrip('/')}/v1/responses"
-        payload = {"input": [{"role": "user", "content": message}], "stream": False}
+        payload: dict[str, Any] = {
+            "input": [{"role": "user", "content": message}],
+            "stream": False,
+        }
     else:
         url = f"{endpoint.rstrip('/')}/v1/chat/completions"
-        payload = {"messages": [{"role": "user", "content": message}], "stream": False}
+        payload = {
+            "messages": [{"role": "user", "content": message}],
+            "stream": False,
+        }
 
     if session_id:
         payload["session_id"] = session_id
@@ -1184,31 +1399,37 @@ async def _chat(
     is_local = "localhost" in url or "127.0.0.1" in url or "0.0.0.0" in url
 
     # 构造 httpx client 配置
-    client_kwargs = {"timeout": 60, "trust_env": not is_local}
+    client_kwargs: dict[str, Any] = {
+        "timeout": 60,
+        "trust_env": not is_local,
+    }
 
     # 如果指定了 --insecure 参数，跳过 SSL 证书验证（类似 curl -k）
     if insecure:
         client_kwargs["verify"] = False
 
     # 构造 Headers
-    headers = {}
+    headers: dict[str, str] = {}
     if api_key:
         headers["Authorization"] = f"Bearer {api_key}"
 
     async with httpx.AsyncClient(**client_kwargs) as client:
         response = await client.post(url, json=payload, headers=headers)
         response.raise_for_status()
-        return response.json()
+        response_payload = response.json()
+        if not isinstance(response_payload, dict):
+            raise ValueError("Agent response must be a JSON object")
+        return response_payload
 
 
 async def _stream_chat(
     endpoint: str,
     message: str,
-    api_key: str = None,
-    session_id: str = None,
+    api_key: Optional[str] = None,
+    session_id: Optional[str] = None,
     is_once: bool = False,
     insecure: bool = False,
-    model: str = None,
+    model: Optional[str] = None,
     api_format: str = "chat_completions",
 ):
     """流式调用 (SSE)"""
@@ -1221,7 +1442,10 @@ async def _stream_chat(
     normalized_api_format = str(api_format or "chat_completions").strip().lower()
     if normalized_api_format == "responses":
         url = f"{endpoint.rstrip('/')}/v1/responses"
-        payload = {"input": [{"role": "user", "content": message}], "stream": True}
+        payload: dict[str, Any] = {
+            "input": [{"role": "user", "content": message}],
+            "stream": True,
+        }
     else:
         url = f"{endpoint.rstrip('/')}/v1/chat/completions"
         payload = {"messages": [{"role": "user", "content": message}], "stream": True}
@@ -1238,14 +1462,17 @@ async def _stream_chat(
     is_local = "localhost" in url or "127.0.0.1" in url or "0.0.0.0" in url
 
     # 构造 httpx client 配置
-    client_kwargs = {"timeout": 60, "trust_env": not is_local}
+    client_kwargs: dict[str, Any] = {
+        "timeout": 60,
+        "trust_env": not is_local,
+    }
 
     # 如果指定了 --insecure 参数，跳过 SSL 证书验证（类似 curl -k）
     if insecure:
         client_kwargs["verify"] = False
 
     # 构造 Headers
-    headers = {}
+    headers: dict[str, str] = {}
     if api_key:
         headers["Authorization"] = f"Bearer {api_key}"
 
@@ -1270,6 +1497,8 @@ async def _stream_chat(
 
                         try:
                             data = json.loads(data_str)
+                            if not isinstance(data, dict):
+                                continue
                             if current_event and isinstance(data, dict):
                                 data = {**data, "_event": current_event}
                             # 直接 yield 解析后的 JSON 数据，让 _extract_content 处理
@@ -1330,7 +1559,7 @@ def _extract_response_content(response: dict) -> str:
         choices = response.get("choices", [])
         if choices:
             message = choices[0].get("message", {})
-            return message.get("content", "")
+            return str(message.get("content") or "")
     except (KeyError, IndexError):
         pass
     return str(response)