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

ksadk/cli/cmd_hermes.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import os
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Callable, Optional, cast
 
@@ -14,6 +15,11 @@ from ksadk.api import AgentEngineClient
 from ksadk.cli.agent_ref import merge_agent_inputs, resolve_agent_ref
 from ksadk.cli.cmd_dashboard import _open_dashboard
 from ksadk.cli.dry_run import dry_run_option, effective_dry_run, run_async_with_dry_run
+from ksadk.cli.env_options import (
+    env_options,
+    inject_env_to_environ,
+    resolve_runtime_env_overrides,
+)
 from ksadk.cli.error_utils import remote_error, resolution_error
 from ksadk.cli.model_catalog import fetch_provider_model_metadata
 from ksadk.cli.network_options import build_network_payload, network_cli_kwargs, network_options
@@ -52,12 +58,11 @@ from ksadk.deployment.agent_access import (
     normalize_deployment_status,
 )
 from ksadk.deployment.state import clear_state, load_state, save_state
+from ksadk.cli.hermes_env import _build_hermes_env_vars
 from ksadk.hermes_terminal import (
     run_hermes_terminal_session,
-    validate_hermes_exec_argv,
     validate_hermes_pairing_argv,
 )
-from ksadk.model_policy import build_runtime_model_policy_env
 
 DEFAULT_HERMES_IMAGE = "ghcr.io/kingsoftcloud/hermes-agent:v2026.7.7.2-ksadk-v070"
 DEFAULT_HERMES_CONTEXT_LENGTHS = (("glm-5.1", "200000"),)
@@ -150,6 +155,7 @@ def _build_hermes_update_payload(
         "resources": payload["resources"],
         "scaling": payload["scaling"],
         "ui_config": payload["ui_config"],
+        "enable_observability": payload["enable_observability"],
     }
     if include_env:
         update_payload["env_vars"] = payload["env_vars"]
@@ -165,19 +171,6 @@ def hermes():
     """Hermes Agent 资源管理。"""
 
 
-def _load_dotenv_into_env(project_dir: Path) -> None:
-    env_path = project_dir / ".env"
-    if not env_path.exists():
-        return
-    try:
-        from dotenv import dotenv_values
-    except ImportError:
-        return
-    for key, value in dotenv_values(env_path).items():
-        if key and value is not None and os.getenv(key) is None:
-            os.environ[key] = str(value)
-
-
 def _get_hermes_global_env() -> dict[str, str]:
     global _HERMES_GLOBAL_ENV_CACHE
     if _HERMES_GLOBAL_ENV_CACHE is not None:
@@ -208,22 +201,6 @@ def _env_value(*names: str) -> str:
     return ""
 
 
-def _normalize_hermes_ui_locale(raw: Optional[str]) -> str:
-    """标准化 Hermes UI 语言代码，当前 upstream 只支持 en / zh。"""
-    text = str(raw or "").strip()
-    if not text:
-        return "zh"
-
-    base = text.split(".", 1)[0].replace("_", "-").strip().lower()
-    if base in {"c", "c-utf-8", "c.utf-8", "posix"}:
-        return "zh"
-    if base.startswith("en"):
-        return "en"
-    if base.startswith("zh"):
-        return "zh"
-    return "zh"
-
-
 async def _fetch_hermes_bootstrap_config(region: str) -> dict[str, Any] | None:
     """从服务端获取 Hermes 客户端启动配置。失败时返回 None。"""
     from ksadk.version import VERSION as CLI_VERSION
@@ -257,118 +234,6 @@ def _extract_hermes_bootstrap_image(bootstrap_cfg: dict[str, Any] | None) -> str
     return str(value or "").strip()
 
 
-def _default_context_length_for_model(model: str | None) -> str:
-    normalized = str(model or "").strip().lower()
-    if not normalized:
-        return ""
-    for model_fragment, context_length in DEFAULT_HERMES_CONTEXT_LENGTHS:
-        if model_fragment in normalized:
-            return context_length
-    return ""
-
-
-def _build_hermes_env_vars(
-    *,
-    model_base_url: str | None = None,
-    model_api_key: str | None = None,
-    default_model: str | None = None,
-    model_metadata: dict[str, Any] | None = None,
-) -> list[dict[str, Any]]:
-    raw_model_base_url = model_base_url or _env_value("OPENAI_BASE_URL")
-    resolved_model_base_url = (
-        _normalize_hermes_runtime_base_url(raw_model_base_url)
-        if raw_model_base_url
-        else DEFAULT_HERMES_RUNTIME_BASE_URL
-    )
-    resolved_default_model = (
-        default_model or _env_value("OPENAI_MODEL_NAME") or DEFAULT_HERMES_MODEL_NAME
-    )
-    metadata_context_length = ""
-    if isinstance(model_metadata, dict):
-        metadata_context_length = str(model_metadata.get("context_window_tokens") or "").strip()
-    context_length = (
-        _env_value("HERMES_CONTEXT_LENGTH", "OPENAI_CONTEXT_LENGTH", "MODEL_CONTEXT_LENGTH")
-        or metadata_context_length
-        or _default_context_length_for_model(resolved_default_model)
-    )
-    ui_locale = _normalize_hermes_ui_locale(_env_value("HERMES_UI_LOCALE", "LANG", "LC_ALL"))
-    raw = {
-        "OPENAI_API_KEY": model_api_key or _env_value("OPENAI_API_KEY"),
-        "OPENAI_BASE_URL": resolved_model_base_url,
-        "OPENAI_MODEL_NAME": resolved_default_model,
-        "API_SERVER_ENABLED": "true",
-        "API_SERVER_HOST": "127.0.0.1",
-        "API_SERVER_PORT": "8642",
-        "HERMES_DASHBOARD_HOST": "127.0.0.1",
-        "HERMES_DASHBOARD_PORT": "9119",
-        "KSADK_RUNTIME_PORT": _env_value("PORT") or "8080",
-        "HERMES_UI_LOCALE": ui_locale,
-    }
-    if context_length:
-        raw["HERMES_CONTEXT_LENGTH"] = context_length
-    fallback_model = _env_value("HERMES_FALLBACK_MODEL", "OPENAI_FALLBACK_MODEL_NAME")
-    if fallback_model:
-        raw["HERMES_FALLBACK_PROVIDER"] = _env_value("HERMES_FALLBACK_PROVIDER") or "custom"
-        raw["HERMES_FALLBACK_MODEL"] = fallback_model
-        raw["HERMES_FALLBACK_BASE_URL"] = (
-            _env_value("HERMES_FALLBACK_BASE_URL") or resolved_model_base_url
-        )
-    api_server_key = _env_value("API_SERVER_KEY", "HERMES_API_SERVER_KEY")
-    if api_server_key:
-        raw["API_SERVER_KEY"] = api_server_key
-    langfuse_public_key = _env_value("HERMES_LANGFUSE_PUBLIC_KEY", "LANGFUSE_PUBLIC_KEY")
-    langfuse_secret_key = _env_value("HERMES_LANGFUSE_SECRET_KEY", "LANGFUSE_SECRET_KEY")
-    if langfuse_public_key and langfuse_secret_key:
-        raw["HERMES_LANGFUSE_PUBLIC_KEY"] = langfuse_public_key
-        raw["HERMES_LANGFUSE_SECRET_KEY"] = langfuse_secret_key
-        langfuse_base_url = _env_value(
-            "HERMES_LANGFUSE_BASE_URL", "LANGFUSE_BASE_URL", "LANGFUSE_HOST"
-        )
-        if langfuse_base_url:
-            raw["HERMES_LANGFUSE_BASE_URL"] = langfuse_base_url
-        for target_key, source_keys in {
-            "HERMES_LANGFUSE_ENV": ("HERMES_LANGFUSE_ENV", "LANGFUSE_ENV"),
-            "HERMES_LANGFUSE_RELEASE": ("HERMES_LANGFUSE_RELEASE", "LANGFUSE_RELEASE"),
-            "HERMES_LANGFUSE_SAMPLE_RATE": ("HERMES_LANGFUSE_SAMPLE_RATE",),
-            "HERMES_LANGFUSE_MAX_CHARS": ("HERMES_LANGFUSE_MAX_CHARS",),
-            "HERMES_LANGFUSE_DEBUG": ("HERMES_LANGFUSE_DEBUG",),
-        }.items():
-            value = _env_value(*source_keys)
-            if value:
-                raw[target_key] = value
-    for key in (
-        "WPSXIEZUO_APP_ID",
-        "WPSXIEZUO_APP_KEY",
-        "WPSXIEZUO_API_BASE",
-        "WPSXIEZUO_WS_ENDPOINT",
-        "WPSXIEZUO_GROUP_AT_ONLY",
-        "WPSXIEZUO_ALLOWED_USERS",
-        "WPSXIEZUO_ALLOW_ALL_USERS",
-        "WPSXIEZUO_HOME_CHANNEL",
-    ):
-        value = _env_value(key)
-        if value:
-            raw[key] = value
-    raw = build_runtime_model_policy_env(raw, runtime="hermes")
-    if raw.get("HERMES_FALLBACK_MODEL"):
-        raw.setdefault(
-            "HERMES_FALLBACK_PROVIDER", _env_value("HERMES_FALLBACK_PROVIDER") or "custom"
-        )
-        raw.setdefault(
-            "HERMES_FALLBACK_BASE_URL",
-            _env_value("HERMES_FALLBACK_BASE_URL") or resolved_model_base_url,
-        )
-    return [
-        {
-            "Key": key,
-            "Value": str(value),
-            "IsSensitive": any(token in key for token in ("KEY", "TOKEN", "SECRET")),
-        }
-        for key, value in raw.items()
-        if value is not None and str(value).strip() != ""
-    ]
-
-
 def _validate_hermes_model_config(
     *,
     model_base_url: str | None = None,
@@ -386,11 +251,6 @@ def _validate_hermes_model_config(
         print_info("未配置 OPENAI_API_KEY，将由服务端在需要时自动创建。")
 
 
-def _normalize_hermes_runtime_base_url(base_url: str | None) -> str:
-    normalized = str(base_url or "").strip()
-    return normalized
-
-
 _FAILURE_STATUSES = {"FAILED", "ERROR", "TERMINATED"}
 
 
@@ -500,6 +360,13 @@ def _split_terminal_agent_ref_and_argv(
     *,
     validator: Callable[[tuple[str, ...] | list[str]], list[str]],
 ) -> tuple[str | None, list[str]]:
+    """Split argv into (agent_ref, exec_argv).
+
+    The first token is treated as agent_ref when the validator rejects the
+    full argv (whitelist validators raise ValueError), or when the validator
+    is the passthrough one and the first token looks like an agent id
+    (``ar-`` prefix) with remaining tokens.
+    """
     raw = [str(item) for item in argv]
     try:
         return None, validator(raw)
@@ -512,6 +379,19 @@ def _split_terminal_agent_ref_and_argv(
         raise direct_error
 
 
+def _passthrough_exec_argv(argv: tuple[str, ...] | list[str]) -> list[str]:
+    """Local exec passes argv through unchanged; the pod enforces allowlists.
+
+    Raises ValueError when the first token looks like an agent id (``ar-``
+    prefix) and there are remaining tokens, so ``_split_terminal_agent_ref_and_argv``
+    falls back to splitting the first token as agent_ref.
+    """
+    items = [str(item) for item in argv]
+    if len(items) >= 2 and items[0].startswith("ar-"):
+        raise ValueError("first token looks like an agent ref")
+    return items
+
+
 def _render_hermes_dry_run(
     action: str, request: dict[str, Any], hints: tuple[str, ...] = ()
 ) -> None:
@@ -548,6 +428,21 @@ def _render_hermes_dry_run(
 @click.option("--storage-size-gi", type=int, default=20, show_default=True, help="PVC 容量（Gi）")
 @click.option("--storage-mount-path", default=None, help="PVC 挂载目录（默认: /home/node/.hermes）")
 @click.option("--no-storage", is_flag=True, help="禁用默认 PVC 挂载")
+@env_options
+@click.option(
+    "--observability/--no-observability",
+    default=True,
+    help="是否启用可观测性 (默认开启)",
+)
+@click.option(
+    "--agent-id",
+    "agent_id_opt",
+    default=None,
+    help=(
+        "指定要更新的已有 Agent ID；当前凭证有权限时会自动回填 "
+        ".agentengine.state 并走热更新（用于本地状态丢失后重新关联）"
+    ),
+)
 @network_options
 @dry_run_option()
 @cli_output_option()
@@ -563,6 +458,10 @@ def deploy(
     storage_size_gi: int,
     storage_mount_path: Optional[str],
     no_storage: bool,
+    extra_env: tuple[str, ...],
+    env_file: Optional[str],
+    observability: bool,
+    agent_id_opt: Optional[str],
     enable_public_access: Optional[bool],
     enable_vpc_access: bool,
     vpc_id: Optional[str],
@@ -578,6 +477,8 @@ def deploy(
     ctx = click.get_current_context(silent=True)
     include_env_on_update = any(
         (
+            bool(extra_env),
+            _option_was_explicit(ctx, "env_file"),
             _option_was_explicit(ctx, "model_base_url"),
             _option_was_explicit(ctx, "model_api_key"),
             _option_was_explicit(ctx, "default_model"),
@@ -603,8 +504,12 @@ def deploy(
             storage_size_gi=storage_size_gi,
             storage_mount_path=storage_mount_path,
             no_storage=no_storage,
+            observability=observability,
+            agent_id=agent_id_opt,
             include_env_on_update=include_env_on_update,
             include_storage_on_update=include_storage_on_update,
+            extra_env=extra_env,
+            env_file=env_file,
             **network_cli_kwargs(
                 enable_public_access=enable_public_access,
                 enable_vpc_access=enable_vpc_access,
@@ -634,22 +539,43 @@ async def _deploy_hermes(
     storage_size_gi: int,
     storage_mount_path: str | None,
     no_storage: bool,
+    observability: bool,
+    agent_id: str | None = None,
     include_env_on_update: bool,
     include_storage_on_update: bool,
-    enable_public_access: bool | None,
-    enable_vpc_access: bool,
-    vpc_id: str | None,
-    subnet_id: str | None,
-    security_group_id: str | None,
-    availability_zone: str | None,
-    dry_run: bool,
+    extra_env: tuple[str, ...] = (),
+    env_file: str | None = None,
+    enable_public_access: bool | None = None,
+    enable_vpc_access: bool = False,
+    vpc_id: str | None = None,
+    subnet_id: str | None = None,
+    security_group_id: str | None = None,
+    availability_zone: str | None = None,
+    dry_run: bool = False,
 ) -> None:
     project_dir = Path(".").resolve()
-    _load_dotenv_into_env(project_dir)
+    cli_env, auto_dotenv, shell_keys, env_source = resolve_runtime_env_overrides(
+        env_file=env_file,
+        extra_env=extra_env,
+        base_dir=project_dir,
+    )
+    loaded = inject_env_to_environ(cli_env, auto_dotenv, shell_keys)
+    if loaded:
+        print_info(f"已从 {env_source or '--env'} 注入环境变量: {loaded} 项")
+    if cli_env or auto_dotenv:
+        include_env_on_update = True
     state = load_state(project_dir)
     existing_agent_id = None
     if str(state.get("type") or state.get("framework") or "").strip().lower() == "hermes":
         existing_agent_id = str(state.get("agent_id") or "").strip() or None
+    explicit_agent_id = (agent_id or "").strip() or None
+    if explicit_agent_id:
+        if existing_agent_id and existing_agent_id != explicit_agent_id:
+            print_warn(
+                f"--agent-id ({explicit_agent_id}) 与本地状态 "
+                f"({existing_agent_id}) 不一致，以 --agent-id 为准"
+            )
+        existing_agent_id = explicit_agent_id
     agent_name = name or state.get("name") or project_dir.name.replace("-", "_")
     image_ref = image or _env_value("HERMES_IMAGE", "HERMES_DOCKER_IMAGE")
     if not image_ref:
@@ -676,6 +602,9 @@ async def _deploy_hermes(
         model_api_key=model_api_key,
         default_model=default_model,
         model_metadata=model_metadata,
+        cli_env=cli_env,
+        auto_dotenv=auto_dotenv,
+        shell_keys=shell_keys,
     )
     payload = {
         "name": agent_name,
@@ -686,6 +615,7 @@ async def _deploy_hermes(
         "region": region,
         "resources": {"cpu": cpu, "memory": memory},
         "scaling": {"min_replicas": 1, "max_replicas": 1, "concurrency": 1000},
+        "enable_observability": observability,
         "env_vars": env_vars,
         "ui_config": {"profile": "hermes", "path": "/", "url": None},
     }
@@ -723,6 +653,38 @@ async def _deploy_hermes(
     print_kv("镜像", image_ref)
 
     async with AgentEngineClient(region=region, dry_run=dry_run) as client:
+        if explicit_agent_id and not dry_run:
+            try:
+                detail = await client.get_agent(
+                    explicit_agent_id, include_api_key=True
+                )
+            except Exception as e:
+                raise click.ClickException(
+                    f"指定的 Agent ID '{explicit_agent_id}' 不存在，或当前凭证无权限访问。\n"
+                    f"   详情: {e}\n"
+                    "   👉 请确认 agent_id 正确，且当前 AK/SK / 账号有该 Agent 的权限。"
+                ) from e
+            qa = detail.get("quick_access", {}) or {}
+            basic = detail.get("basic", {}) or {}
+            recovered_state = state.copy()
+            recovered_state.update(
+                {
+                    "agent_id": explicit_agent_id,
+                    "name": basic.get("name") or agent_name,
+                    "type": "hermes",
+                    "region": region,
+                    "endpoint": qa.get("public_endpoint"),
+                    "updated_at": datetime.now(timezone.utc).isoformat(),
+                }
+            )
+            if qa.get("api_key"):
+                recovered_state["api_key"] = qa["api_key"]
+            recovered_state = {
+                k: v for k, v in recovered_state.items() if v is not None
+            }
+            save_state(project_dir, recovered_state)
+            state = recovered_state
+            print_info(f"已通过 --agent-id 关联已有 Agent: {explicit_agent_id}")
         if existing_agent_id:
             update_payload = _build_hermes_update_payload(
                 payload=payload,
@@ -815,7 +777,7 @@ async def _deploy_hermes(
     if dry_run:
         return
 
-    agent_id = res.get("agent_id")
+    final_agent_id = res.get("agent_id")
     endpoint = res.get("endpoint")
     api_key = res.get("api_key")
     deployment_status = normalize_deployment_status(res.get("status") or res.get("phase"))
@@ -824,7 +786,7 @@ async def _deploy_hermes(
         {
             "type": "hermes",
             "framework": "hermes",
-            "agent_id": agent_id,
+            "agent_id": final_agent_id,
             "name": res.get("name") or agent_name,
             "region": region,
             "endpoint": endpoint,
@@ -841,8 +803,8 @@ async def _deploy_hermes(
                 resource="hermes",
                 action="deploy",
                 result={
-                    "id": str(agent_id or ""),
-                    "agent_id": str(agent_id or ""),
+                    "id": str(final_agent_id or ""),
+                    "agent_id": str(final_agent_id or ""),
                     "name": str(res.get("name") or agent_name),
                     "status": deployment_status,
                     "framework": "hermes",
@@ -857,7 +819,7 @@ async def _deploy_hermes(
         )
         return
     print_success("Hermes 已提交部署")
-    print_kv("Agent ID", str(agent_id or "(创建中)"))
+    print_kv("Agent ID", str(final_agent_id or "(创建中)"))
     print_kv("当前状态", deployment_status, value_style=status_rich_style(deployment_status))
     if endpoint:
         print_kv("Endpoint", str(endpoint), value_style="#58a6ff")
@@ -1072,6 +1034,7 @@ def open_hermes(
 
 @hermes.command("exec", context_settings=CONTEXT_SETTINGS)
 @click.argument("argv", nargs=-1, required=True)
+@click.option("--agent", "agent_option", default=None, help="Hermes Agent 名称（显式指定）")
 @click.option("--region", "-r", default="cn-beijing-6", envvar="KSYUN_REGION", help="区域")
 @click.option("--endpoint", "-e", default=None, help="Agent Endpoint URL (覆盖自动获取)")
 @click.option("--api-key", default=None, help="AgentEngine API Key (覆盖自动获取)")
@@ -1081,6 +1044,7 @@ def open_hermes(
 @cli_output_option()
 def exec_hermes(
     argv: tuple[str, ...],
+    agent_option: Optional[str],
     region: str,
     endpoint: Optional[str],
     api_key: Optional[str],
@@ -1092,10 +1056,19 @@ def exec_hermes(
     """透传受限 Hermes 只读运维子命令。"""
     _ = output_mode
     try:
-        agent_ref, validated_argv = _split_terminal_agent_ref_and_argv(
+        if agent_option is not None:
+            agent_option = agent_option.strip()
+            if not agent_option:
+                raise click.ClickException("--agent 必须指定非空的 Hermes Agent 名称")
+        positional_agent_ref, validated_argv = _split_terminal_agent_ref_and_argv(
             argv,
-            validator=validate_hermes_exec_argv,
+            validator=_passthrough_exec_argv,
         )
+        if agent_option is not None and positional_agent_ref:
+            raise click.ClickException(
+                "--agent 不能与位置参数 Agent ID 同时使用: " f"{positional_agent_ref}"
+            )
+        agent_ref = agent_option if agent_option is not None else positional_agent_ref
         dry_run = effective_dry_run(dry_run)
         if dry_run:
             _render_hermes_dry_run(
@@ -1122,6 +1095,7 @@ def exec_hermes(
                 insecure=insecure,
                 mode="exec",
                 argv=validated_argv,
+                exec_argv_validator=_passthrough_exec_argv,
             )
         )
     except (KeyboardInterrupt, asyncio.CancelledError):

ksadk/cli/cmd_invoke.py

@@ -18,6 +18,7 @@ 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.invoke_payload import build_chat_request
 from ksadk.cli.cmd_files import (
     _build_sync_payload,
     _collect_local_files_report,
@@ -603,6 +604,9 @@ def run_invoke_command(
                 insecure,
                 model,
                 api_format_resolved,
+                default_model=(
+                    "openclaw" if _is_openclaw_target(next_state, latest_access) else None
+                ),
             )
         )
     else:
@@ -1286,6 +1290,7 @@ async def _invoke_once(
     insecure: bool = False,
     model: Optional[str] = None,
     api_format: str = "chat_completions",
+    default_model: Optional[str] = None,
 ):
     """单次调用"""
     click.echo(f"\n👤 你: {message}")
@@ -1306,7 +1311,7 @@ async def _invoke_once(
                     last_refresh_time = 0.0
                     full_reasoning = ""
                     async for chunk in _stream_chat(
-                        endpoint, message, api_key, session_id, True, insecure, model, api_format
+                        endpoint, message, api_key, session_id, True, insecure, model, api_format, default_model
                     ):
                         content, reasoning = _extract_content(chunk)
 
@@ -1336,7 +1341,7 @@ async def _invoke_once(
                     live.refresh()  # 确保最后一次刷新
             else:
                 async for chunk in _stream_chat(
-                    endpoint, message, api_key, session_id, True, insecure, model, api_format
+                    endpoint, message, api_key, session_id, True, insecure, model, api_format, default_model
                 ):
                     content, reasoning = _extract_content(chunk)
                     if reasoning:
@@ -1346,7 +1351,7 @@ async def _invoke_once(
             click.echo()  # 换行
         else:
             response = await _chat(
-                endpoint, message, api_key, session_id, insecure, model, api_format
+                endpoint, message, api_key, session_id, insecure, model, api_format, default_model
             )
             content = _extract_response_content(response)
             if console and Markdown:
@@ -1365,6 +1370,7 @@ async def _chat(
     insecure: bool = False,
     model: Optional[str] = None,
     api_format: str = "chat_completions",
+    default_model: Optional[str] = None,
 ) -> dict[str, Any]:
     """非流式调用 (OpenAI 兼容格式)"""
     try:
@@ -1373,25 +1379,15 @@ async def _chat(
         click.secho("❌ 请安装 httpx: pip install httpx", fg="red")
         raise SystemExit(1)
 
-    normalized_api_format = str(api_format or "chat_completions").strip().lower()
-    if normalized_api_format == "responses":
-        url = f"{endpoint.rstrip('/')}/v1/responses"
-        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,
-        }
-
-    if session_id:
-        payload["session_id"] = session_id
-
-    if model:
-        payload["model"] = model
+    url, payload = build_chat_request(
+        endpoint,
+        message,
+        session_id=session_id,
+        model=model,
+        api_format=api_format,
+        default_model=default_model,
+        stream=False,
+    )
 
     # 本地请求禁用系统代理 (ClashX 等会导致本地请求 502 错误)
     # trust_env=False 会禁用: 代理设置、SSL 证书环境变量、.netrc 文件
@@ -1431,6 +1427,7 @@ async def _stream_chat(
     insecure: bool = False,
     model: Optional[str] = None,
     api_format: str = "chat_completions",
+    default_model: Optional[str] = None,
 ):
     """流式调用 (SSE)"""
     try:
@@ -1439,22 +1436,15 @@ async def _stream_chat(
         click.secho("❌ 请安装 httpx: pip install httpx", fg="red")
         raise SystemExit(1)
 
-    normalized_api_format = str(api_format or "chat_completions").strip().lower()
-    if normalized_api_format == "responses":
-        url = f"{endpoint.rstrip('/')}/v1/responses"
-        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}
-
-    if session_id:
-        payload["session_id"] = session_id
-
-    if model:
-        payload["model"] = model
+    url, payload = build_chat_request(
+        endpoint,
+        message,
+        session_id=session_id,
+        model=model,
+        api_format=api_format,
+        default_model=default_model,
+        stream=True,
+    )
 
     # 本地请求禁用系统代理 (ClashX 等会导致本地请求 502 错误)
     # trust_env=False 会禁用: 代理设置、SSL 证书环境变量、.netrc 文件

ksadk/cli/cmd_launch.py

@@ -71,6 +71,14 @@ def _dict_or_none(value: object) -> dict[str, Any] | None:
     help="部署目标 (default: serverless)",
 )
 @click.option("--name", "-n", help="部署名称")
+@click.option(
+    "--agent-id",
+    default=None,
+    help=(
+        "指定要更新的已有 Agent ID；当前凭证有权限时会自动回填 "
+        ".agentengine.state 并走热更新（用于本地状态丢失后重新关联）"
+    ),
+)
 @click.option(
     "--region", "-r", default="cn-beijing-6", envvar="KSYUN_REGION", help="区域 (serverless)"
 )
@@ -142,6 +150,7 @@ def launch(
     no_version: bool,
     auto_rollback: bool,
     output_mode: str | None,
+    agent_id: str | None,
 ):
     """一键完成构建和部署 (Build + Deploy)
 
@@ -199,6 +208,7 @@ def launch(
             extra_env=extra_env,
             env_file=env_file,
             dry_run_context=dry_run_context,
+            agent_id=agent_id,
         ),
         dry_run=dry_run,
         on_dry_run=(
@@ -246,6 +256,7 @@ async def _launch_async(
     extra_env: tuple[str, ...] = (),
     env_file: str | None = None,
     dry_run_context: dict[str, object] | None = None,
+    agent_id: str | None = None,
 ):
     from ksadk.deployment import DeploymentManager, DeployTarget
     from ksadk.detection import FrameworkDetector
@@ -322,6 +333,7 @@ async def _launch_async(
             "ui_url": resolved_ui_url,
             "dry_run": dry_run,
             "env_vars": explicit_env_vars,
+            "agent_id": agent_id,
         },
     )