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

ksadk/cli/cmd_openclaw.py

@@ -81,7 +81,7 @@ from ksadk.cli.ui import (
 from ksadk.configs.env_registry import is_sensitive_env_var
 from ksadk.conversations.model_context import normalize_model_metadata
 from ksadk.deployment.agent_access import get_latest_agent_access
-from ksadk.model_policy import build_runtime_model_policy_env
+from ksadk.cli.openclaw_env import _build_openclaw_env_vars, _normalize_openclaw_gateway_auth_env
 from ksadk.openclaw_gateway import (
     OpenClawGatewayClient,
     OpenClawGatewayError,
@@ -97,15 +97,6 @@ DEFAULT_OPENCLAW_REPO = "openclaw"
 DEFAULT_OPENCLAW_VERSION = "2026.6.1"
 DEFAULT_OPENCLAW_REGISTRY = "ghcr.io/kingsoftcloud"
 DEFAULT_OPENCLAW_NAME = "openclaw-gateway"
-DEFAULT_TRUSTED_PROXY_USER_HEADER = "x-forwarded-user"
-DEFAULT_TRUSTED_PROXY_CIDRS = [
-    "127.0.0.1",
-    "::1",
-    "10.0.0.0/8",
-    "172.16.0.0/12",
-    "192.168.0.0/16",
-    "35.0.0.0/8",
-]
 _GLOBAL_ENV_CACHE: Optional[Dict[str, str]] = None
 OPENCLAW_SECURITY_PROFILES = ("relaxed", "strict", "strictest")
 OPENCLAW_CHANNELS = ("weixin", "feishu", "wps-xiezuo")
@@ -386,33 +377,6 @@ def _openclaw_registry_env() -> dict[str, str]:
     return env
 
 
-def _resolve_model_base_url(cli_value: Optional[str]) -> Optional[str]:
-    """解析模型 Base URL，缺失时回退到 settings.model.api_base（KSPMAS 自动探测）。"""
-    if cli_value and str(cli_value).strip():
-        return str(cli_value).strip()
-
-    from_env = _resolve_env(
-        "OPENCLAW_MODEL_BASE_URL",
-        "OPENAI_BASE_URL",
-        "OPENAI_API_BASE",
-        "LLM_API_BASE",
-        "MODEL_API_BASE",
-    )
-    if from_env:
-        return from_env
-
-    try:
-        from ksadk.configs.settings import settings
-
-        api_base = settings.model.api_base
-        if api_base and str(api_base).strip():
-            return str(api_base).strip()
-    except Exception:
-        pass
-
-    return None
-
-
 def _summarize_openclaw_account(agents: list[Dict[str, Any]]) -> str:
     """汇总列表所属账号，优先使用响应字段，缺失时回退当前 CLI 上下文。"""
     accounts = sorted(
@@ -455,88 +419,6 @@ def _print_openclaw_list_summary(table: RichTable, summary_text: str) -> None:
     console.print(f"[muted]{summary_text}[/]")
 
 
-def _normalize_ui_locale(raw: Optional[str]) -> str:
-    """标准化 UI 语言代码，默认 zh-CN。"""
-    text = str(raw or "").strip()
-    if not text:
-        return "zh-CN"
-
-    base = text.split(".", 1)[0].replace("_", "-").strip()
-    low = base.lower()
-
-    if low in {"c", "c-utf-8", "c.utf-8", "posix"}:
-        return "zh-CN"
-    if (
-        low.startswith("zh-tw")
-        or low.startswith("zh-hk")
-        or low.startswith("zh-mo")
-        or low.startswith("zh-hant")
-    ):
-        return "zh-TW"
-    if low.startswith("zh"):
-        return "zh-CN"
-    if low.startswith("pt"):
-        return "pt-BR"
-    if low.startswith("de"):
-        return "de"
-    if low.startswith("en"):
-        return "en"
-
-    return "zh-CN"
-
-
-def _is_truthy(raw: Optional[str]) -> bool:
-    text = str(raw or "").strip().lower()
-    return text in {"1", "true", "yes", "on"}
-
-
-def _resolve_exec_profile_overrides(security_profile: Optional[str]) -> Dict[str, str]:
-    """根据 CLI 安全预设返回 OpenClaw 运行时环境变量覆盖项。"""
-    profile = str(security_profile or "").strip().lower()
-    if not profile:
-        return {}
-
-    common = {
-        "OPENCLAW_EXEC_HOST": "gateway",
-        "OPENCLAW_EXEC_AUTO_ALLOW_SKILLS": "false",
-        "OPENCLAW_ELEVATED_ENABLED": "false",
-    }
-    if profile == "relaxed":
-        return {
-            **common,
-            "OPENCLAW_EXEC_STRICT_MODE": "false",
-            "OPENCLAW_EXEC_UNSAFE_MODE": "true",
-            "OPENCLAW_EXEC_SECURITY": "full",
-            "OPENCLAW_EXEC_ASK": "off",
-            "OPENCLAW_EXEC_ASK_FALLBACK": "full",
-            "OPENCLAW_EXEC_DEFAULT_ALLOWLIST_ENABLED": "false",
-            "OPENCLAW_FS_WORKSPACE_ONLY": "false",
-        }
-    if profile == "strict":
-        return {
-            **common,
-            "OPENCLAW_EXEC_STRICT_MODE": "true",
-            "OPENCLAW_EXEC_UNSAFE_MODE": "false",
-            "OPENCLAW_EXEC_SECURITY": "allowlist",
-            "OPENCLAW_EXEC_ASK": "off",
-            "OPENCLAW_EXEC_ASK_FALLBACK": "allowlist",
-            "OPENCLAW_EXEC_DEFAULT_ALLOWLIST_ENABLED": "true",
-            "OPENCLAW_FS_WORKSPACE_ONLY": "false",
-        }
-    if profile == "strictest":
-        return {
-            **common,
-            "OPENCLAW_EXEC_STRICT_MODE": "true",
-            "OPENCLAW_EXEC_UNSAFE_MODE": "false",
-            "OPENCLAW_EXEC_SECURITY": "deny",
-            "OPENCLAW_EXEC_ASK": "off",
-            "OPENCLAW_EXEC_ASK_FALLBACK": "deny",
-            "OPENCLAW_EXEC_DEFAULT_ALLOWLIST_ENABLED": "false",
-            "OPENCLAW_FS_WORKSPACE_ONLY": "true",
-        }
-    raise ValueError(f"unsupported OpenClaw security profile: {security_profile}")
-
-
 def _strip_provider_prefix(provider_id: str, model_id: str) -> str:
     provider = str(provider_id or "").strip()
     model = str(model_id or "").strip()
@@ -739,322 +621,6 @@ def _filter_openclaw_provider_catalog(
     return selected
 
 
-def _build_openclaw_env_vars(
-    *,
-    model_base_url: Optional[str] = None,
-    model_api_key: Optional[str] = None,
-    default_model: Optional[str] = None,
-    model_provider_id: Optional[str] = None,
-    gateway_port: Optional[str] = None,
-    public_port: Optional[str] = None,
-    security_profile: Optional[str] = None,
-) -> dict:
-    """构建 OpenClaw 所需的环境变量，自动复用 OPENAI_* 环境变量"""
-    env = {}
-    default_provider_id = "ksyun"
-    default_model_api = "openai-completions"
-    default_model_base_url = "https://kspmas.ksyun.com/v1"
-    exec_profile_overrides = _resolve_exec_profile_overrides(security_profile)
-
-    # 模型配置：客户端只透传用户显式配置和可选的 API Key；
-    # 其余默认值交给镜像 bootstrap 兜底，避免创建请求把服务端默认行为短路掉。
-    openclaw_explicit_model = default_model or _resolve_env("OPENCLAW_DEFAULT_MODEL")
-    generic_model_preference = _resolve_env("OPENAI_MODEL_NAME", "MODEL_NAME", "LLM_MODEL")
-    model_preference = openclaw_explicit_model or generic_model_preference
-    explicit_base_url = model_base_url or _resolve_env(
-        "OPENCLAW_MODEL_BASE_URL", "OPENAI_BASE_URL", "OPENAI_API_BASE"
-    )
-    base_url = _resolve_model_base_url(explicit_base_url)
-    api_key = model_api_key or _resolve_env(
-        "OPENCLAW_MODEL_API_KEY", "OPENAI_API_KEY", "LLM_API_KEY", "MODEL_API_KEY"
-    )
-    model = model_preference or "glm-5.2"
-    explicit_provider_id = model_provider_id or _resolve_env("OPENCLAW_MODEL_PROVIDER_ID")
-    inferred_provider_id = explicit_provider_id
-    if not inferred_provider_id and model and "/" in model:
-        inferred_provider_id = model.split("/", 1)[0].strip()
-    provider_id = inferred_provider_id or default_provider_id
-    resolved_gateway_port = gateway_port or _resolve_env("OPENCLAW_GATEWAY_PORT", "PORT") or "8080"
-    resolved_public_port = public_port or _resolve_env("OPENCLAW_PUBLIC_PORT") or "80"
-    explicit_model_api = _resolve_env("OPENCLAW_MODEL_API")
-    model_api = explicit_model_api or default_model_api
-    trusted_proxy_user_header = (
-        (
-            _resolve_env(
-                "OPENCLAW_TRUSTED_PROXY_USER_HEADER",
-                "OPENCLAW_GATEWAY_TRUSTED_PROXY_USER_HEADER",
-            )
-            or DEFAULT_TRUSTED_PROXY_USER_HEADER
-        )
-        .strip()
-        .lower()
-    )
-    internal_trusted_proxy_user = (
-        _resolve_env("OPENCLAW_INTERNAL_TRUSTED_PROXY_USER") or "openclaw-backend"
-    )
-    internal_trusted_proxy_user_header = (
-        (
-            _resolve_env("OPENCLAW_INTERNAL_TRUSTED_PROXY_USER_HEADER")
-            or trusted_proxy_user_header
-            or DEFAULT_TRUSTED_PROXY_USER_HEADER
-        )
-        .strip()
-        .lower()
-    )
-    trusted_proxies = _normalize_csv_list(
-        _resolve_env("OPENCLAW_TRUSTED_PROXIES") or "",
-        default_items=DEFAULT_TRUSTED_PROXY_CIDRS,
-    )
-    browser_enabled = _resolve_env("OPENCLAW_BROWSER_ENABLED")
-    browser_no_sandbox = _resolve_env("OPENCLAW_BROWSER_NO_SANDBOX") or "true"
-    browser_headless = _resolve_env("OPENCLAW_BROWSER_HEADLESS") or "true"
-    browser_executable = _resolve_env(
-        "OPENCLAW_BROWSER_EXECUTABLE_PATH", "OPENCLAW_BROWSER_EXECUTABLE"
-    )
-    ui_locale = _normalize_ui_locale(_resolve_env("OPENCLAW_UI_LOCALE", "LANG", "LC_ALL"))
-    exec_strict_mode_raw = (
-        exec_profile_overrides.get("OPENCLAW_EXEC_STRICT_MODE")
-        or _resolve_env("OPENCLAW_EXEC_STRICT_MODE", "OPENCLAW_EXEC_SAFE_MODE")
-        or "false"
-    )
-    exec_strict_mode = _is_truthy(exec_strict_mode_raw)
-
-    exec_host = (
-        exec_profile_overrides.get("OPENCLAW_EXEC_HOST")
-        or _resolve_env("OPENCLAW_EXEC_HOST")
-        or "gateway"
-    )
-    exec_security = (
-        exec_profile_overrides.get("OPENCLAW_EXEC_SECURITY")
-        or _resolve_env("OPENCLAW_EXEC_SECURITY")
-        or ("allowlist" if exec_strict_mode else "full")
-    )
-    exec_ask = (
-        exec_profile_overrides.get("OPENCLAW_EXEC_ASK")
-        or _resolve_env("OPENCLAW_EXEC_ASK")
-        or "off"
-    )
-    exec_ask_fallback = (
-        exec_profile_overrides.get("OPENCLAW_EXEC_ASK_FALLBACK")
-        or _resolve_env("OPENCLAW_EXEC_ASK_FALLBACK")
-        or ("allowlist" if exec_strict_mode else "full")
-    )
-    exec_auto_allow_skills = (
-        exec_profile_overrides.get("OPENCLAW_EXEC_AUTO_ALLOW_SKILLS")
-        or _resolve_env("OPENCLAW_EXEC_AUTO_ALLOW_SKILLS")
-        or "false"
-    )
-    elevated_enabled = (
-        exec_profile_overrides.get("OPENCLAW_ELEVATED_ENABLED")
-        or _resolve_env("OPENCLAW_ELEVATED_ENABLED")
-        or "false"
-    )
-    exec_default_allowlist_enabled = (
-        exec_profile_overrides.get("OPENCLAW_EXEC_DEFAULT_ALLOWLIST_ENABLED")
-        or _resolve_env("OPENCLAW_EXEC_DEFAULT_ALLOWLIST_ENABLED")
-        or ("true" if exec_strict_mode else "false")
-    )
-    exec_allowlist = _resolve_env("OPENCLAW_EXEC_ALLOWLIST")
-    fs_workspace_only = (
-        exec_profile_overrides.get("OPENCLAW_FS_WORKSPACE_ONLY")
-        or _resolve_env("OPENCLAW_FS_WORKSPACE_ONLY")
-        or "false"
-    )
-    model_api_key_secret_source = _resolve_env("OPENCLAW_MODEL_API_KEY_SECRET_SOURCE") or "file"
-    model_api_key_secret_file_path = _resolve_env("OPENCLAW_MODEL_API_KEY_SECRET_FILE_PATH")
-    gateway_auth_mode = _resolve_env("OPENCLAW_GATEWAY_AUTH_MODE")
-    gateway_token = _resolve_env("OPENCLAW_GATEWAY_TOKEN")
-    gateway_password = _resolve_env("OPENCLAW_GATEWAY_PASSWORD")
-
-    env["OPENCLAW_GATEWAY_BIND"] = "lan"
-    if gateway_auth_mode:
-        env["OPENCLAW_GATEWAY_AUTH_MODE"] = gateway_auth_mode
-    env["OPENCLAW_TRUSTED_PROXY_USER_HEADER"] = (
-        trusted_proxy_user_header or DEFAULT_TRUSTED_PROXY_USER_HEADER
-    )
-    env["OPENCLAW_INTERNAL_TRUSTED_PROXY_USER"] = internal_trusted_proxy_user
-    env["OPENCLAW_INTERNAL_TRUSTED_PROXY_USER_HEADER"] = (
-        internal_trusted_proxy_user_header
-        or trusted_proxy_user_header
-        or DEFAULT_TRUSTED_PROXY_USER_HEADER
-    )
-    env["OPENCLAW_TRUSTED_PROXIES"] = trusted_proxies
-    env["OPENCLAW_GATEWAY_PORT"] = str(resolved_gateway_port)
-    env["OPENCLAW_PUBLIC_PORT"] = str(resolved_public_port)
-    if browser_enabled:
-        env["OPENCLAW_BROWSER_ENABLED"] = browser_enabled
-    env["OPENCLAW_BROWSER_NO_SANDBOX"] = browser_no_sandbox
-    env["OPENCLAW_BROWSER_HEADLESS"] = browser_headless
-    if browser_executable:
-        env["OPENCLAW_BROWSER_EXECUTABLE_PATH"] = browser_executable
-    env["OPENCLAW_UI_LOCALE"] = ui_locale
-    env["OPENCLAW_EXEC_HOST"] = exec_host
-    env["OPENCLAW_EXEC_STRICT_MODE"] = "true" if exec_strict_mode else "false"
-    env["OPENCLAW_EXEC_UNSAFE_MODE"] = "false" if exec_strict_mode else "true"
-    env["OPENCLAW_EXEC_SECURITY"] = exec_security
-    env["OPENCLAW_EXEC_ASK"] = exec_ask
-    env["OPENCLAW_EXEC_ASK_FALLBACK"] = exec_ask_fallback
-    env["OPENCLAW_EXEC_AUTO_ALLOW_SKILLS"] = exec_auto_allow_skills
-    env["OPENCLAW_ELEVATED_ENABLED"] = elevated_enabled
-    env["OPENCLAW_EXEC_DEFAULT_ALLOWLIST_ENABLED"] = exec_default_allowlist_enabled
-    env["OPENCLAW_FS_WORKSPACE_ONLY"] = fs_workspace_only
-    env["OPENCLAW_MODEL_API_KEY_SECRET_SOURCE"] = model_api_key_secret_source
-    if exec_allowlist:
-        env["OPENCLAW_EXEC_ALLOWLIST"] = exec_allowlist
-    if model_api_key_secret_file_path:
-        env["OPENCLAW_MODEL_API_KEY_SECRET_FILE_PATH"] = model_api_key_secret_file_path
-
-    if explicit_provider_id and provider_id != default_provider_id:
-        env["OPENCLAW_MODEL_PROVIDER_ID"] = provider_id
-    elif not explicit_provider_id and provider_id and provider_id != default_provider_id:
-        env["OPENCLAW_MODEL_PROVIDER_ID"] = provider_id
-    if explicit_model_api and model_api != default_model_api:
-        env["OPENCLAW_MODEL_API"] = model_api
-    if explicit_base_url and base_url and base_url != default_model_base_url:
-        env["OPENCLAW_MODEL_BASE_URL"] = base_url
-    if api_key:
-        env["OPENCLAW_MODEL_API_KEY"] = api_key
-    normalized_model = model.strip() if model else None
-    catalog_model_id = None
-    resolved_model = None
-    if normalized_model:
-        if "/" in normalized_model:
-            _, catalog_model_id = normalized_model.split("/", 1)
-            resolved_model = normalized_model
-        else:
-            resolved_model = (
-                f"{provider_id}/{normalized_model}" if provider_id else normalized_model
-            )
-        if openclaw_explicit_model:
-            env["OPENCLAW_DEFAULT_MODEL"] = resolved_model
-        elif generic_model_preference:
-            env["OPENAI_MODEL_NAME"] = resolved_model
-
-    # 额外的可选配置
-    catalog = _resolve_env("OPENCLAW_MODEL_CATALOG_JSON")
-    if catalog:
-        env["OPENCLAW_MODEL_CATALOG_JSON"] = catalog
-    openclaw_model_allowlist = _resolve_env("OPENCLAW_MODEL_ALLOWLIST")
-    agentengine_model_allowlist = _resolve_env("AGENTENGINE_MODEL_ALLOWLIST")
-    if openclaw_model_allowlist:
-        env["OPENCLAW_MODEL_ALLOWLIST"] = openclaw_model_allowlist
-    elif agentengine_model_allowlist:
-        env["AGENTENGINE_MODEL_ALLOWLIST"] = agentengine_model_allowlist
-    origins = _resolve_env("OPENCLAW_ALLOWED_ORIGINS")
-    if origins:
-        env["OPENCLAW_ALLOWED_ORIGINS"] = _normalize_allowed_origins(origins)
-    else:
-        # 统一输出 JSON 数组字符串，兼容旧版 bootstrap（仅支持 JSON.parse）。
-        env["OPENCLAW_ALLOWED_ORIGINS"] = json.dumps(["*"])
-    allow_insecure_auth = _resolve_env("OPENCLAW_ALLOW_INSECURE_AUTH")
-    env["OPENCLAW_ALLOW_INSECURE_AUTH"] = allow_insecure_auth if allow_insecure_auth else "true"
-    disable_device_auth = _resolve_env("OPENCLAW_DISABLE_DEVICE_AUTH")
-    env["OPENCLAW_DISABLE_DEVICE_AUTH"] = disable_device_auth if disable_device_auth else "true"
-    if gateway_token:
-        env["OPENCLAW_GATEWAY_TOKEN"] = gateway_token
-    if gateway_password:
-        env["OPENCLAW_GATEWAY_PASSWORD"] = gateway_password
-    for passthrough_key in [
-        "OPENCLAW_CHANNEL_BOOTSTRAP_JSON",
-        "OPENCLAW_BROWSER_SSRF_POLICY_JSON",
-        "OPENCLAW_WEB_FETCH_ENABLED",
-        "OPENCLAW_WEB_SEARCH_PROVIDER",
-        "OPENCLAW_WEB_SEARCH_BASE_URL",
-        "OPENCLAW_WEB_SEARCH_MODEL",
-        "OPENCLAW_WEB_SEARCH_API_KEY",
-        "OPENCLAW_WEB_SEARCH_API_KEY_SECRET_SOURCE",
-        "OPENCLAW_WEB_SEARCH_API_KEY_SECRET_PROVIDER",
-        "OPENCLAW_WEB_SEARCH_API_KEY_SECRET_ID",
-    ]:
-        passthrough_value = _resolve_env(passthrough_key)
-        if passthrough_value:
-            env[passthrough_key] = passthrough_value
-
-    env = _normalize_openclaw_gateway_auth_env(env)
-    return build_runtime_model_policy_env(env, runtime="openclaw")
-
-
-def _normalize_allowed_origins(raw: str) -> str:
-    """标准化 OPENCLAW_ALLOWED_ORIGINS，统一输出 JSON 数组字符串。"""
-    text = (raw or "").strip()
-    if not text:
-        return ""
-
-    origins = []
-    try:
-        parsed = json.loads(text)
-        if isinstance(parsed, list):
-            origins = [str(x).strip() for x in parsed if str(x).strip()]
-    except Exception:
-        # Backward compatible: 支持逗号/分号/空白分隔字符串。
-        parts = [p.strip() for p in text.replace(";", ",").replace(" ", ",").split(",")]
-        origins = [p.strip() for p in parts if p.strip()]
-
-    if not origins:
-        origins = [text]
-
-    deduped = list(dict.fromkeys(origins))
-    return json.dumps(deduped, ensure_ascii=False)
-
-
-def _normalize_csv_list(raw: str, *, default_items: Optional[list[str]] = None) -> str:
-    """标准化字符串列表为逗号分隔格式。"""
-    text = (raw or "").strip()
-    items: list[str] = []
-    if text:
-        try:
-            parsed = json.loads(text)
-            if isinstance(parsed, list):
-                items = [str(x).strip() for x in parsed if str(x).strip()]
-        except Exception:
-            parts = [p.strip() for p in text.replace(";", ",").replace(" ", ",").split(",")]
-            items = [p for p in parts if p]
-
-    if not items:
-        items = [str(x).strip() for x in (default_items or []) if str(x).strip()]
-
-    return ",".join(list(dict.fromkeys(items)))
-
-
-def _normalize_openclaw_gateway_auth_env(env: dict[str, str]) -> dict[str, str]:
-    """标准化 OpenClaw gateway 鉴权模式与共享密钥配置。"""
-    normalized_env = dict(env or {})
-    raw_mode = str(normalized_env.get("OPENCLAW_GATEWAY_AUTH_MODE") or "").strip().lower()
-    raw_token = str(normalized_env.get("OPENCLAW_GATEWAY_TOKEN") or "").strip()
-    raw_password = str(normalized_env.get("OPENCLAW_GATEWAY_PASSWORD") or "").strip()
-
-    if raw_mode and raw_mode not in {"trusted-proxy", "token", "none"}:
-        raise ValueError("OPENCLAW_GATEWAY_AUTH_MODE 仅支持 trusted-proxy、token 或 none")
-
-    auth_mode = raw_mode or ("token" if raw_token or raw_password else "trusted-proxy")
-    if auth_mode == "token":
-        if raw_token and raw_password and raw_token != raw_password:
-            raise ValueError(
-                "OPENCLAW_GATEWAY_TOKEN 与 OPENCLAW_GATEWAY_PASSWORD 同时提供时必须一致"
-            )
-        shared_secret = raw_token or raw_password
-        if not shared_secret:
-            raise ValueError(
-                "OPENCLAW_GATEWAY_AUTH_MODE=token 时必须提供 "
-                "OPENCLAW_GATEWAY_TOKEN 或 OPENCLAW_GATEWAY_PASSWORD"
-            )
-        normalized_env["OPENCLAW_GATEWAY_AUTH_MODE"] = "token"
-        normalized_env["OPENCLAW_GATEWAY_TOKEN"] = shared_secret
-        normalized_env["OPENCLAW_GATEWAY_PASSWORD"] = shared_secret
-        return normalized_env
-
-    if raw_token or raw_password:
-        raise ValueError(
-            "仅在 OPENCLAW_GATEWAY_AUTH_MODE=token 时支持 "
-            "OPENCLAW_GATEWAY_TOKEN 或 OPENCLAW_GATEWAY_PASSWORD"
-        )
-
-    normalized_env["OPENCLAW_GATEWAY_AUTH_MODE"] = auth_mode
-    normalized_env.pop("OPENCLAW_GATEWAY_TOKEN", None)
-    normalized_env.pop("OPENCLAW_GATEWAY_PASSWORD", None)
-    return normalized_env
-
-
 def _parse_extra_openclaw_env_pairs(items: tuple[str, ...] | list[str] | None) -> dict[str, str]:
     """解析 deploy --env 传入的自定义环境变量，并对 gateway 鉴权模式做早期归一化。"""
     parsed = parse_env_pairs(items)

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: