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

ksadk/cli/cmd_replay.py

@@ -17,8 +17,13 @@ import json
 import click
 
 from ksadk.cli.resource_common import CONTEXT_SETTINGS
-from ksadk.events.replay import replay_transcript
+from ksadk.events.reducer import StreamReducer
 from ksadk.events.store import RuntimeEventStore
+from ksadk.events.v1_compat import (
+    RuntimeEventV1Parser,
+    RuntimeEventV1ProjectionContext,
+    project_to_v1,
+)
 
 _HELP = dict(help_option_names=["-h", "--help"])
 
@@ -43,9 +48,28 @@ async def _run(session_id: str, *, after_seq_id: int, before_seq_id: int | None,
     from ksadk.sessions import resolve_session_service
 
     store = RuntimeEventStore(resolve_session_service())
-    parser = await replay_transcript(
-        store, session_id, after_seq_id=after_seq_id, before_seq_id=before_seq_id
-    )
+    service = resolve_session_service()
+    session = await service.get_session(session_id)
+    events = await store.list(session_id)
+    parser = RuntimeEventV1Parser()
+    reducers: dict[str, StreamReducer] = {}
+    for event in events:
+        reducer = reducers.get(event.run_id)
+        if reducer is not None and reducer.snapshot().status in {"completed", "failed", "canceled"}:
+            reducer = None
+        if reducer is None:
+            reducer = StreamReducer()
+            reducers[event.run_id] = reducer
+        reducer.apply(event)
+        projection = reducer.snapshot()
+        context = RuntimeEventV1ProjectionContext(
+            agent_id=session.agent_id if session else "",
+            user_id=session.user_id if session else "",
+            session_id=session_id,
+            projection=projection,
+        )
+        for v1_event in project_to_v1(event, mode="identity_replace", context=context):
+            parser.feed(v1_event)
     transcript = parser.transcript()
     if fmt == "json":
         click.echo(json.dumps(transcript, ensure_ascii=False, sort_keys=True))

ksadk/cli/cmd_studio.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 import os
 import secrets
 import webbrowser
@@ -12,14 +13,67 @@ import uvicorn
 
 from ksadk.cli.env_options import load_env_file
 from ksadk.cli.ui import print_info, print_kv, print_success, print_title
+
+# veadk 风格：日志行带模块名与行号（filename:lineno），本地排障时能直接定位代码。
+_LOG_FORMAT = "%(asctime)s %(levelname)s %(name)s %(filename)s:%(lineno)d %(message)s"
+
+_STUDIO_LOG_CONFIG = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "default": {"format": _LOG_FORMAT},
+        "access": {"format": _LOG_FORMAT},
+    },
+    "handlers": {
+        "default": {
+            "class": "logging.StreamHandler",
+            "formatter": "default",
+            "stream": "ext://sys.stderr",
+        },
+        "access": {
+            "class": "logging.StreamHandler",
+            "formatter": "access",
+            "stream": "ext://sys.stdout",
+        },
+    },
+    "loggers": {
+        "uvicorn": {"handlers": ["default"], "level": "INFO", "propagate": False},
+        "uvicorn.error": {"level": "INFO"},
+        "uvicorn.access": {"handlers": ["access"], "level": "INFO", "propagate": False},
+    },
+    "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
+# /api.py 一致，方案 §2.4 第 5 点）。
 _MODEL_ENV_KEYS = (
+    "OPENAI_BASE_URL",
     "OPENAI_API_BASE",
     "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.
+_CLOUD_CONTROL_ENV_KEYS = (
+    "KSYUN_ACCESS_KEY",
+    "KSYUN_SECRET_KEY",
+    "KSYUN_REGION",
+    "AGENTENGINE_REGION",
+    "AGENTENGINE_SERVER_URL",
+    "AGENTENGINE_STREAM_SERVER_URL",
+    "AGENTENGINE_SIGN_SERVICE",
+    "KS3_BUCKET",
+    "KS3_ACCESS_KEY",
+    "KS3_SECRET_KEY",
+)
+_STUDIO_ENV_FILE_KEYS = (*_MODEL_ENV_KEYS, *_CLOUD_CONTROL_ENV_KEYS)
+# 别名归一：两者任一有值时，把另一个也设上，保证下游无论读哪个都命中。
+_MODEL_BASE_URL_ALIASES = ("OPENAI_BASE_URL", "OPENAI_API_BASE")
 
 
 @click.command(context_settings=dict(help_option_names=["-h", "--help"]))
@@ -29,7 +83,10 @@ _MODEL_ENV_KEYS = (
 @click.option(
     "--env-file",
     type=click.Path(exists=True, dir_okay=False),
-    help="模型环境文件；只读取 OPENAI_API_BASE/API_KEY/MODEL_NAME",
+    help=(
+        "本地模型与云端控制环境文件；只读取允许的 OPENAI/KSYUN/KS3 "
+        "字段，且仅保留在 Studio 进程"
+    ),
 )
 @click.option(
     "--codex-proxy",
@@ -52,7 +109,7 @@ def studio(
     """
 
     root = Path(workspace).expanduser().resolve()
-    managed_keys = (*_MODEL_ENV_KEYS, "KSADK_CODEX_USE_PROXY")
+    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}
     try:
@@ -61,14 +118,42 @@ def studio(
                 values = load_env_file(env_file)
             except ValueError as exc:
                 raise click.ClickException(str(exc)) from exc
-            loaded = 0
+            loaded_models = 0
+            loaded_cloud_control = 0
             for key, value in values.items():
-                if key not in _MODEL_ENV_KEYS or not value:
+                if key not in _STUDIO_ENV_FILE_KEYS or not value:
                     continue
-                loaded += 1
-                if key not in os.environ:
+                if key in _MODEL_ENV_KEYS:
+                    loaded_models += 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
-            print_kv("模型环境", f"已安全加载 {loaded}/{len(_MODEL_ENV_KEYS)} 个字段")
+            # 别名归一（方案 §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"
+            )
+            if resolved_base_url:
+                os.environ["OPENAI_BASE_URL"] = resolved_base_url
+                os.environ["OPENAI_API_BASE"] = resolved_base_url
+                # base_url 至少算一次，避免显示 0/4 误导。
+                loaded_models = max(loaded_models, 2)
+            print_kv(
+                "模型环境",
+                f"已安全加载 {loaded_models}/{len(_MODEL_ENV_KEYS)} 个字段",
+            )
+            if loaded_cloud_control:
+                print_kv(
+                    "云端控制",
+                    "已安全加载 "
+                    f"{loaded_cloud_control}/{len(_CLOUD_CONTROL_ENV_KEYS)} 个字段"
+                    "（仅本地进程）",
+                )
         if codex_proxy == "forced":
             os.environ["KSADK_CODEX_USE_PROXY"] = "1"
         elif codex_proxy == "direct":
@@ -95,12 +180,18 @@ def studio(
         print_info("按 Ctrl+C 停止")
         if not no_open:
             webbrowser.open(launch_url)
+        # 业务日志（ksadk.*）走 root handler，同样带 filename:lineno。
+        logging.basicConfig(level=logging.INFO, format=_LOG_FORMAT)
         uvicorn.run(
             app,
             host="127.0.0.1",
             port=port,
             log_level="info",
-            access_log=False,
+            # 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
+            # branch's richer diagnostic format.
+            log_config=_STUDIO_LOG_CONFIG,
         )
     finally:
         for key in managed_keys:

ksadk/cli/cmd_web.py

@@ -227,9 +227,14 @@ def configure_local_runtime_persistence(
 @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 端口")
+@click.option(
+    "--host",
+    default="127.0.0.1",
+    help="Web UI 绑定地址(容器部署用 0.0.0.0)",
+)
 @click.option("--model", help="指定模型名称 (覆盖 .env 配置)")
 @click.option("--no-open", is_flag=True, help="仅打印 URL，不自动打开浏览器")
-def web(agent_dir: str, port: int, model: str, no_open: bool):
+def web(agent_dir: str, port: int, host: str, model: str, no_open: bool):
     """启动本地统一 Web UI（Invoke UI）
 
     \b
@@ -249,6 +254,9 @@ def web(agent_dir: str, port: int, model: str, no_open: bool):
 
     agent_path = Path(agent_dir).resolve()
     command_args = ["web", str(agent_path), "--port", str(port)]
+    if host != "127.0.0.1":
+        # re-exec 进项目 venv 时透传非默认 host(容器/远端托管场景绑 0.0.0.0)
+        command_args.extend(["--host", host])
     if model:
         command_args.extend(["--model", model])
     if no_open:
@@ -357,7 +365,7 @@ def web(agent_dir: str, port: int, model: str, no_open: bool):
         webbrowser.open(launch_url)
 
     try:
-        uvicorn.run(runtime_app, host="127.0.0.1", port=port)
+        uvicorn.run(runtime_app, host=host, port=port)
     except KeyboardInterrupt:
         raise SystemExit(0)
     except Exception as e:

ksadk/cli/hermes_env.py

@@ -0,0 +1,151 @@
+"""Hermes deploy 的运行时环境变量构建。
+
+从 cmd_hermes.py 拆出（模块体积治理）；``_env_value`` 与全局 env 缓存仍留在
+cmd_hermes（测试 monkeypatch 点），此处通过延迟 import 访问。
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+from ksadk.cli.env_options import apply_explicit_env_with_shell_priority
+from ksadk.configs.env_registry import is_sensitive_env_var
+from ksadk.deployment.env_forward import forward_shell_process_env
+from ksadk.model_policy import build_runtime_model_policy_env
+
+
+def _env_value(*names: str) -> str:
+    from ksadk.cli import cmd_hermes
+
+    return cmd_hermes._env_value(*names)
+
+
+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"
+
+
+def _default_context_length_for_model(model: str | None) -> str:
+    from ksadk.cli import cmd_hermes
+
+    normalized = str(model or "").strip().lower()
+    if not normalized:
+        return ""
+    for model_fragment, context_length in cmd_hermes.DEFAULT_HERMES_CONTEXT_LENGTHS:
+        if model_fragment in normalized:
+            return context_length
+    return ""
+
+
+def _normalize_hermes_runtime_base_url(base_url: str | None) -> str:
+    normalized = str(base_url or "").strip()
+    return normalized
+
+
+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,
+    cli_env: dict[str, str] | None = None,
+    auto_dotenv: dict[str, str] | None = None,
+    shell_keys: set[str] | None = None,
+) -> list[dict[str, Any]]:
+    from ksadk.cli import cmd_hermes
+
+    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 cmd_hermes.DEFAULT_HERMES_RUNTIME_BASE_URL
+    )
+    resolved_default_model = (
+        default_model or _env_value("OPENAI_MODEL_NAME") or cmd_hermes.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
+    # Observability routes and credentials are platform-managed. The Hermes
+    # deploy CLI must not translate or forward legacy Langfuse SDK variables;
+    # server/runtime inject the standard OTLP primary and CloudMonitor secondary.
+    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")
+    # shell 前缀转发 (KSADK_/OPENAI_/KSYUN_/E2B_ + allowlist)，对齐通用 deploy；
+    # setdefault 语义不覆盖上面已 resolve 的固定键，--env/--env-file 仍可覆盖。
+    forward_shell_process_env(raw)
+    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,
+        )
+    if cli_env or auto_dotenv:
+        apply_explicit_env_with_shell_priority(
+            raw, cli_env or {}, auto_dotenv or {}, shell_keys or set(os.environ)
+        )
+    return [
+        {
+            "Key": key,
+            "Value": str(value),
+            "IsSensitive": is_sensitive_env_var(key),
+        }
+        for key, value in raw.items()
+        if value is not None and str(value).strip() != ""
+    ]

ksadk/cli/invoke_payload.py

@@ -0,0 +1,49 @@
+"""ksadk invoke 的 OpenAI 兼容请求载荷构造。
+
+从 cmd_invoke.py 抽出，避免 cli 模块继续膨胀（架构守护限制 1000 行，
+cmd_invoke 已处于 legacy 白名单，只许缩不许涨）。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+def build_chat_request(
+    endpoint: str,
+    message: str,
+    *,
+    session_id: Optional[str] = None,
+    model: Optional[str] = None,
+    api_format: str = "chat_completions",
+    default_model: Optional[str] = None,
+    stream: bool = False,
+) -> tuple[str, dict[str, Any]]:
+    """构造 (url, payload)，按 api_format 区分 chat/completions 与 responses。
+
+    OpenClaw gateway 2026.7.1+ 的 /v1/responses 特殊处理:
+    - input 传纯字符串，不再接受 {role, content} 对象数组（服务端自行包装 user turn）
+    - 拒绝顶层 session_id，会话标识放 metadata 传递
+    - model 必填且只接受 "openclaw"/"openclaw/<agentId>"（业务模型由 gateway 配置决定），
+      未显式传 --model 时用 default_model 补默认路由值，避免 400
+    """
+    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": message, "stream": stream}
+    else:
+        url = f"{endpoint.rstrip('/')}/v1/chat/completions"
+        payload = {"messages": [{"role": "user", "content": message}], "stream": stream}
+
+    if session_id:
+        if normalized_api_format == "responses":
+            payload.setdefault("metadata", {})["session_id"] = session_id
+        else:
+            payload["session_id"] = session_id
+
+    if model:
+        payload["model"] = model
+    elif default_model and normalized_api_format == "responses":
+        payload["model"] = default_model
+
+    return url, payload