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

ksadk/memory/manager.py

@@ -1,9 +1,9 @@
 """Memory Manager - 统一记忆管理接口"""
 
-import os
 import logging
+import os
 from datetime import timedelta
-from typing import Any, Optional, List, Dict, Type
+from typing import Any, Dict, List, Optional, Type, cast
 
 from ksadk.memory.backends.base import BaseMemoryBackend
 from ksadk.memory.backends.memory import InMemoryBackend
@@ -24,26 +24,26 @@ def register_backend(name: str, backend_class: Type[BaseMemoryBackend]):
 
 class MemoryManager:
     """统一记忆管理器
-    
+
     支持可插拔后端，自动从环境变量读取配置。
-    
+
     使用示例:
         # 从环境变量自动配置
         memory = MemoryManager.from_env()
-        
+
         # 手动配置
         memory = MemoryManager(backend="redis", url="redis://localhost:6379")
-        
+
         # 存取数据
         memory.set("key", {"data": "value"}, session_id="sess-123")
         data = memory.get("key", session_id="sess-123")
-        
+
         # 消息历史
         memory.add_message("sess-123", "user", "你好")
         memory.add_message("sess-123", "assistant", "你好！有什么可以帮助你的？")
         messages = memory.get_messages("sess-123")
     """
-    
+
     def __init__(
         self,
         backend: str = "memory",
@@ -53,7 +53,7 @@ class MemoryManager:
         **kwargs,
     ):
         """初始化 Memory Manager
-        
+
         Args:
             backend: 后端类型 ("memory", "redis")
             url: 后端连接 URL
@@ -63,7 +63,7 @@ class MemoryManager:
         """
         self.backend_name = backend
         self._backend = self._create_backend(backend, url, prefix, default_ttl, **kwargs)
-    
+
     def _create_backend(
         self,
         backend: str,
@@ -76,25 +76,29 @@ class MemoryManager:
         # 延迟导入 Redis backend
         if backend == "redis":
             from ksadk.memory.backends.redis import RedisBackend
+
             _BACKENDS["redis"] = RedisBackend
-        
+
         if backend not in _BACKENDS:
             raise ValueError(f"Unknown backend: {backend}. Available: {list(_BACKENDS.keys())}")
-        
-        backend_class = _BACKENDS[backend]
-        
+
+        backend_class: Any = _BACKENDS[backend]
+
         # 根据后端类型传递参数
         if backend == "memory":
-            return backend_class()
+            return cast(BaseMemoryBackend, backend_class())
         elif backend == "redis":
-            return backend_class(url=url, prefix=prefix, default_ttl=default_ttl, **kwargs)
+            return cast(
+                BaseMemoryBackend,
+                backend_class(url=url, prefix=prefix, default_ttl=default_ttl, **kwargs),
+            )
         else:
-            return backend_class(**kwargs)
-    
+            return cast(BaseMemoryBackend, backend_class(**kwargs))
+
     @classmethod
     def from_env(cls) -> "MemoryManager":
         """从环境变量创建 MemoryManager
-        
+
         环境变量:
             KSADK_MEMORY_BACKEND: 后端类型 (默认 "memory")
             KSADK_MEMORY_URL: 连接 URL (如 redis://localhost:6379)
@@ -104,27 +108,27 @@ class MemoryManager:
         backend = os.environ.get("KSADK_MEMORY_BACKEND", "memory")
         url = os.environ.get("KSADK_MEMORY_URL", "")
         prefix = os.environ.get("KSADK_MEMORY_PREFIX", "ksadk:memory:")
-        
+
         ttl = None
         ttl_str = os.environ.get("KSADK_MEMORY_TTL", "")
         if ttl_str:
             ttl = timedelta(seconds=int(ttl_str))
-        
+
         logger.debug(f"MemoryManager.from_env: backend={backend}, url={url[:20]}...")
-        
+
         return cls(
             backend=backend,
             url=url or None,
             prefix=prefix,
             default_ttl=ttl,
         )
-    
+
     # ===== 键值操作 =====
-    
+
     def get(self, key: str, session_id: Optional[str] = None) -> Optional[Any]:
         """获取值"""
         return self._backend.get(key, session_id)
-    
+
     def set(
         self,
         key: str,
@@ -133,24 +137,24 @@ class MemoryManager:
         ttl: Optional[timedelta] = None,
     ) -> bool:
         """设置值"""
-        return self._backend.set(key, value, session_id, ttl)
-    
+        return bool(self._backend.set(key, value, session_id, ttl))
+
     def delete(self, key: str, session_id: Optional[str] = None) -> bool:
         """删除键"""
-        return self._backend.delete(key, session_id)
-    
+        return bool(self._backend.delete(key, session_id))
+
     def exists(self, key: str, session_id: Optional[str] = None) -> bool:
         """检查键是否存在"""
-        return self._backend.exists(key, session_id)
-    
+        return bool(self._backend.exists(key, session_id))
+
     # ===== 会话操作 =====
-    
+
     def clear_session(self, session_id: str) -> bool:
         """清除会话所有数据"""
-        return self._backend.clear_session(session_id)
-    
+        return bool(self._backend.clear_session(session_id))
+
     # ===== 消息历史 =====
-    
+
     def add_message(
         self,
         session_id: str,
@@ -159,39 +163,40 @@ class MemoryManager:
         metadata: Optional[Dict] = None,
     ) -> bool:
         """添加消息"""
-        return self._backend.add_message(session_id, role, content, metadata)
-    
+        return bool(self._backend.add_message(session_id, role, content, metadata))
+
     def get_messages(
         self,
         session_id: str,
         limit: Optional[int] = None,
     ) -> List[Dict]:
         """获取消息历史"""
-        return self._backend.get_messages(session_id, limit)
-    
+        messages = self._backend.get_messages(session_id, limit)
+        return list(messages)
+
     # ===== 便捷方法 =====
-    
+
     def get_state(self, session_id: str) -> Dict:
         """获取会话状态 (短期记忆)"""
         return self.get("__state__", session_id) or {}
-    
+
     def set_state(self, session_id: str, state: Dict, ttl: Optional[timedelta] = None) -> bool:
         """设置会话状态"""
         return self.set("__state__", state, session_id, ttl)
-    
+
     def update_state(self, session_id: str, updates: Dict) -> bool:
         """更新会话状态 (合并)"""
         current = self.get_state(session_id)
         current.update(updates)
         return self.set_state(session_id, current)
-    
+
     def close(self) -> None:
         """关闭连接"""
         self._backend.close()
-    
+
     def __enter__(self):
         return self
-    
+
     def __exit__(self, exc_type, exc_val, exc_tb):
         self.close()
 
@@ -202,10 +207,10 @@ _global_manager: Optional[MemoryManager] = None
 
 def get_memory_manager() -> MemoryManager:
     """获取全局 MemoryManager 单例
-    
+
     在 Agent 代码中使用:
         from ksadk.memory import get_memory_manager
-        
+
         memory = get_memory_manager()
         memory.set("key", "value")
     """

ksadk/memory/service.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import json
 import logging
 import os
-from typing import Any
+from typing import Any, cast
 
 from ksadk.common.aicp_env import resolve_aicp_connection
 from ksadk.memory.adk.backends.base_ltm_backend import BaseLongTermMemoryBackend
@@ -49,7 +49,9 @@ class LongTermMemoryService:
         self.backend_config = dict(backend_config or {})
         self.top_k = top_k
         self.app_name = app_name
-        backend_index = getattr(backend, "index", "") if isinstance(backend, BaseLongTermMemoryBackend) else ""
+        backend_index = (
+            getattr(backend, "index", "") if isinstance(backend, BaseLongTermMemoryBackend) else ""
+        )
         self.index = index or backend_index or app_name or "default_app"
         self._backend = self._resolve_backend()
 
@@ -75,12 +77,10 @@ class LongTermMemoryService:
             connection = resolve_aicp_connection("KSADK_LTM")
             backend_config = {
                 "access_key": (
-                    os.environ.get("KSADK_LTM_ACCESS_KEY")
-                    or os.environ.get("KSYUN_ACCESS_KEY", "")
+                    os.environ.get("KSADK_LTM_ACCESS_KEY") or os.environ.get("KSYUN_ACCESS_KEY", "")
                 ),
                 "secret_key": (
-                    os.environ.get("KSADK_LTM_SECRET_KEY")
-                    or os.environ.get("KSYUN_SECRET_KEY", "")
+                    os.environ.get("KSADK_LTM_SECRET_KEY") or os.environ.get("KSYUN_SECRET_KEY", "")
                 ),
                 "region": connection["region"],
                 "endpoint": connection["endpoint"],
@@ -109,7 +109,7 @@ class LongTermMemoryService:
         backend_cls = get_long_term_memory_backend_cls(str(self.backend))
         config = dict(self.backend_config)
         config.setdefault("index", self.index)
-        return backend_cls(**config)
+        return cast(BaseLongTermMemoryBackend, backend_cls(**config))
 
     def search_entries(self, *, user_id: str, query: str, top_k: int | None = None) -> list[str]:
         return self._backend.search_memory(
@@ -142,7 +142,9 @@ class LongTermMemoryService:
             )
         )
 
-    def save_text(self, *, user_id: str, content: str, metadata: dict[str, Any] | None = None) -> bool:
+    def save_text(
+        self, *, user_id: str, content: str, metadata: dict[str, Any] | None = None
+    ) -> bool:
         payload = {
             "role": "user",
             "parts": [{"text": content}],

ksadk/model_policy.py

@@ -58,10 +58,7 @@ DEFAULT_MODEL_POLICY: dict[str, Any] = {
 def _deep_merge(base: dict[str, Any], override: Mapping[str, Any]) -> dict[str, Any]:
     merged = copy.deepcopy(base)
     for key, value in override.items():
-        if (
-            isinstance(value, Mapping)
-            and isinstance(merged.get(key), dict)
-        ):
+        if isinstance(value, Mapping) and isinstance(merged.get(key), dict):
             merged[key] = _deep_merge(merged[key], value)
         else:
             merged[key] = copy.deepcopy(value)
@@ -196,7 +193,12 @@ def build_runtime_model_policy_env(
     multimodal = _role_model(normalized, "multimodal")
     has_primary = any(
         str(env.get(key) or "").strip()
-        for key in ("OPENCLAW_DEFAULT_MODEL", "HERMES_DEFAULT_MODEL", "OPENAI_MODEL_NAME", "MODEL_NAME")
+        for key in (
+            "OPENCLAW_DEFAULT_MODEL",
+            "HERMES_DEFAULT_MODEL",
+            "OPENAI_MODEL_NAME",
+            "MODEL_NAME",
+        )
     )
     runtime_name = str(runtime or "").strip().lower()
     if runtime_name == "openclaw":
@@ -206,7 +208,10 @@ def build_runtime_model_policy_env(
             env.setdefault("OPENCLAW_FALLBACK_MODEL", _provider_ref(fallback))
         if multimodal:
             env.setdefault("OPENCLAW_IMAGE_MODEL", _provider_ref(multimodal))
-        env.setdefault("OPENCLAW_MODEL_CATALOG_JSON", json.dumps(_catalog_from_policy(normalized), ensure_ascii=False))
+        env.setdefault(
+            "OPENCLAW_MODEL_CATALOG_JSON",
+            json.dumps(_catalog_from_policy(normalized), ensure_ascii=False),
+        )
         return env
     if runtime_name == "hermes":
         if primary and not has_primary:
@@ -214,7 +219,10 @@ def build_runtime_model_policy_env(
             env["HERMES_DEFAULT_MODEL"] = primary
         if fallback:
             env.setdefault("HERMES_FALLBACK_MODEL", fallback)
-        env.setdefault("HERMES_MODEL_CATALOG_JSON", json.dumps(_catalog_from_policy(normalized), ensure_ascii=False))
+        env.setdefault(
+            "HERMES_MODEL_CATALOG_JSON",
+            json.dumps(_catalog_from_policy(normalized), ensure_ascii=False),
+        )
         return env
     if primary and not has_primary:
         env["OPENAI_MODEL_NAME"] = primary

ksadk/model_proxy/__init__.py

@@ -0,0 +1,51 @@
+"""ksadk 模型出口协议转换层(P1 草案,待 codex review).
+
+把 OpenAI Responses API <-> Chat Completions API 的转换内化为 ksadk 的模型出口中间层,
+让只发 responses 的 runtime(codex)能透明使用所有 chat 协议模型,用户零感知。
+
+设计见 docs/responses-chat-protocol-proxy-plan.md。
+
+模块边界:
+- transform: 纯转换器(无环境依赖),请求/响应/流式状态机。
+- config:    ProxyConfig 显式注入,不在导入时读 env。
+- server:    create_app(config) app factory + ProxyServer 生命周期管理。
+- protocol_proxy: 可独立运行的入口(读 env → config → uvicorn)。
+"""
+
+from .bootstrap import setup_proxy_redirect_if_enabled, teardown_proxy_redirect
+from .cache import CapabilityCache
+from .config import ProxyConfig
+from .detect import ModelCapabilities, probe_responses_capability
+from .gate import ProxyGate
+from .namespace import build_restore_map, flatten_namespace_tool_name, flatten_request_namespaces
+from .server import ProxyServer  # noqa: F401  (re-export)
+from .transform import (
+    Streamer,
+    chat_to_response,
+    convert_tool_choice,
+    convert_tools,
+    convert_usage,
+    input_to_messages,
+    responses_to_chat,
+)
+
+__all__ = [
+    "CapabilityCache",
+    "ModelCapabilities",
+    "ProxyConfig",
+    "ProxyGate",
+    "ProxyServer",
+    "Streamer",
+    "build_restore_map",
+    "chat_to_response",
+    "convert_tool_choice",
+    "convert_tools",
+    "convert_usage",
+    "flatten_namespace_tool_name",
+    "flatten_request_namespaces",
+    "input_to_messages",
+    "probe_responses_capability",
+    "responses_to_chat",
+    "setup_proxy_redirect_if_enabled",
+    "teardown_proxy_redirect",
+]

ksadk/model_proxy/bootstrap.py

@@ -0,0 +1,80 @@
+"""env 型框架接线(v2.2):按需懒起 ProxyServer 并重定向 OPENAI_BASE_URL。
+
+review v1 约束:setup_environment 在框架检测之前执行,无法判断 runtime。
+故本模块用 :class:`ProxyGate`(模型白名单,不依赖 runtime 判断)控制:
+gate.is_on(model) 为真时起一个进程内 ProxyServer,把 OPENAI_BASE_URL/
+OPENAI_API_BASE 重定向到它;env 框架(ADK/langchain/deepagents 发 chat)经代理
+的 /v1/chat/completions 直通上游(字节级,缓存不受影响),codex 走 v2.1 不经此。
+
+默认 gate 关(ProxyGate.enabled=False),不重定向,历史路径零影响。
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from .config import ProxyConfig
+from .gate import ProxyGate
+from .server import ProxyServer
+
+# 进程级单例:setup_environment 多次调用只起一个 proxy
+_proxy: Optional[ProxyServer] = None
+_original_base: Optional[str] = None
+
+
+def setup_proxy_redirect_if_enabled(
+    gate: ProxyGate | None = None,
+    model: str | None = None,
+    upstream_base: str | None = None,
+    api_key: str | None = None,
+    local_token: str | None = None,
+) -> str | None:
+    """gate 开启且模型在白名单时起 ProxyServer 并重定向 OPENAI_BASE_URL。
+
+    返回 proxy base_url(已重定向)或 None(未启用)。多次调用幂等(单例)。
+    上游凭证来自 ProxyConfig(从 env 读),不下发给子进程(凭证闭合)。
+    """
+    global _proxy, _original_base
+    if _proxy is not None:
+        return _proxy.base_url  # 幂等:已起
+    gate = gate or ProxyGate.from_env()
+    model = model or os.environ.get("OPENAI_MODEL_NAME") or os.environ.get("MODEL_NAME") or ""
+    if not gate.is_on(model=model or None):
+        return None
+    upstream = (
+        upstream_base
+        or os.environ.get("OPENAI_BASE_URL")
+        or os.environ.get("OPENAI_API_BASE")
+        or ""
+    )
+    key = (
+        api_key or os.environ.get("OPENAI_API_KEY") or os.environ.get("LLM_API_KEY") or ""
+    )
+    token = local_token or os.environ.get("KSADK_PROXY_TOKEN") or ""
+    if not upstream or not key:
+        return None  # 缺凭证/上游,不启用(保持原 env)
+    cfg = ProxyConfig(upstream_base=upstream, api_key=key, local_token=token)
+    srv = ProxyServer(cfg)
+    srv.start()
+    _proxy = srv
+    # 记录原 base 并重定向(双别名都指向 proxy)
+    _original_base = os.environ.get("OPENAI_BASE_URL") or os.environ.get("OPENAI_API_BASE")
+    os.environ["OPENAI_BASE_URL"] = srv.base_url
+    os.environ["OPENAI_API_BASE"] = srv.base_url
+    if not token:
+        # 非 codex 路径(env 框架)无 token:代理 local_token 为空,仅回环监听才允许
+        os.environ["KSADK_PROXY_TOKEN"] = ""
+    return srv.base_url
+
+
+def teardown_proxy_redirect() -> None:
+    """回收 proxy 并恢复原 OPENAI_BASE_URL(进程退出/卸载时调)。"""
+    global _proxy, _original_base
+    if _proxy is not None:
+        _proxy.stop()
+        _proxy = None
+    if _original_base is not None:
+        os.environ["OPENAI_BASE_URL"] = _original_base
+        os.environ["OPENAI_API_BASE"] = _original_base
+        _original_base = None

ksadk/model_proxy/cache.py

@@ -0,0 +1,165 @@
+"""能力探测缓存(v2.4):租户隔离键 + TTL + singleflight + 主动失效。
+
+review v1 指出 ``(model, base_url)`` 缺 credential/tenant 维度:同一网关不同 key
+能力可能不同(如星流 glm-5.1 的 responses 403 按 consumer 鉴权),404 也可能是
+"模型不存在"而非"endpoint 不存在"。本模块:
+
+- 键 = ``(model, base_url, credential_scope)``;credential_scope 用进程内 HMAC
+  标识符，避免明文 key 入键/日志，又能区分不同 key。
+- **明确判定**(supported/unsupported)长缓存(TTL);**不确定**(unknown)不缓存,
+  下次重探——避免把一次抖动固化成长期误判。
+- **singleflight**:并发同键只探一次,其余等结果(用 per-key Future)。
+- **主动失效**:`invalidate(model, base_url, scope)` 与 `clear()` 入口。
+- 撞名/模型不存在的结构化区分由 detect.py 的错误分类负责,本缓存只存结论。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import secrets
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from .detect import ModelCapabilities
+
+# The capability cache is process-local, so its credential namespace need not
+# survive a restart.  A random salt prevents cache identifiers from being used
+# as an offline oracle for API keys and avoids retaining the original credential.
+_SCOPE_SALT = secrets.token_bytes(16)
+_SCOPE_ITERATIONS = 100_000
+
+
+def credential_scope(credential: str) -> str:
+    """Return a process-local, non-secret cache scope for a credential."""
+    return hashlib.pbkdf2_hmac(
+        "sha256", credential.encode("utf-8"), _SCOPE_SALT, _SCOPE_ITERATIONS, dklen=16
+    ).hex()
+
+
+@dataclass
+class _Entry:
+    caps: ModelCapabilities
+    expires_at: float  # 0 = 永不过期(明确判定)
+
+
+class CapabilityCache:
+    """能力矩阵缓存:线程安全 + asyncio 安全(单进程内)。"""
+
+    def __init__(self, ttl: float = 3600.0):
+        self._ttl = ttl
+        self._lock = threading.Lock()
+        self._entries: dict[tuple[str, str, str], _Entry] = {}
+        # singleflight:sync per-key Event,async per-key Future
+        self._inflight_sync: dict[tuple[str, str, str], threading.Event] = {}
+        self._inflight_async: dict[tuple[str, str, str], asyncio.Future] = {}
+
+    def _key(self, model: str, base: str, scope: str) -> tuple[str, str, str]:
+        return (model, base.rstrip("/"), scope)
+
+    def get(self, model: str, base: str, scope: str) -> ModelCapabilities | None:
+        """命中且未过期返回 caps;过期/不存在/不确定(不缓存)返回 None。"""
+        k = self._key(model, base, scope)
+        with self._lock:
+            e = self._entries.get(k)
+            if e is None:
+                return None
+            if e.expires_at and time.time() > e.expires_at:
+                self._entries.pop(k, None)
+                return None
+            return e.caps
+
+    def put(self, model: str, base: str, scope: str, caps: ModelCapabilities) -> None:
+        """只缓存明确判定(supported/unsupported);unknown 不缓存。"""
+        if caps.verdict == "unknown":
+            return
+        k = self._key(model, base, scope)
+        expires = time.time() + self._ttl if self._ttl > 0 else 0
+        with self._lock:
+            self._entries[k] = _Entry(caps=caps, expires_at=expires)
+
+    def invalidate(self, model: str, base: str, scope: str) -> None:
+        k = self._key(model, base, scope)
+        with self._lock:
+            self._entries.pop(k, None)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._entries.clear()
+
+    # ---- singleflight:并发同键只探一次 ----
+    def get_or_probe(
+        self,
+        model: str,
+        base: str,
+        scope: str,
+        probe: Callable[[str, str], ModelCapabilities],
+    ) -> ModelCapabilities:
+        """命中直接返回;否则 singleflight 探测(并发同键只探一次),结果入缓存。
+
+        ``scope`` is a pre-derived credential namespace. ``probe`` is a sync
+        callable(model, base) -> ModelCapabilities and closes over credentials.
+        """
+        cached = self.get(model, base, scope)
+        if cached is not None:
+            return cached
+        k = self._key(model, base, scope)
+        with self._lock:
+            ev = self._inflight_sync.get(k)
+            if ev is not None:
+                # 已有并发探测在进行:等它完成,读缓存(探测方负责 put)
+                pass
+            else:
+                ev = threading.Event()
+                self._inflight_sync[k] = ev
+                ev = None  # 标记本线程负责探测
+        if ev is not None:
+            ev.wait(timeout=30.0)
+            return self.get(model, base, scope) or ModelCapabilities(verdict="unknown")
+        # 本线程负责探测
+        try:
+            caps = probe(model, base)
+            self.put(model, base, scope, caps)
+            return caps
+        finally:
+            with self._lock:
+                ev_done = self._inflight_sync.pop(k, None)
+            if ev_done is not None:
+                ev_done.set()
+
+    async def aget_or_probe(
+        self,
+        model: str,
+        base: str,
+        scope: str,
+        probe: Callable[[str, str], Any],
+    ) -> ModelCapabilities:
+        """async singleflight 版:probe 是 async callable -> ModelCapabilities。"""
+        cached = self.get(model, base, scope)
+        if cached is not None:
+            return cached
+        k = self._key(model, base, scope)
+        loop = asyncio.get_running_loop()
+        with self._lock:
+            fut = self._inflight_async.get(k)
+            if fut is None:
+                fut = loop.create_future()
+                self._inflight_async[k] = fut
+                own = True
+            else:
+                own = False
+        if not own:
+            await fut  # type: ignore[no-any-return]
+            # owner 已 put 入缓存;从缓存读结果(不用 fut 的值,它是 None 占位)
+            return self.get(model, base, scope) or ModelCapabilities(verdict="unknown")
+        try:
+            caps: ModelCapabilities = await probe(model, base)
+            self.put(model, base, scope, caps)
+            return caps
+        finally:
+            with self._lock:
+                self._inflight_async.pop(k, None)
+            if not fut.done():
+                fut.set_result(None)  # 唤醒等待者(它们会读缓存)

ksadk/model_proxy/config.py

@@ -0,0 +1,45 @@
+"""ProxyConfig:转换 proxy 的配置(显式注入,不在模块导入时读 env,便于内化与测试)。"""
+
+import os
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+# HTTPS(凭证安全):不再用明文 HTTP 携带 Bearer key。
+DEFAULT_UPSTREAM_BASE = "https://kspmas.ksyun.com/v1"
+
+_LOOPBACK_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+@dataclass
+class ProxyConfig:
+    upstream_base: str = DEFAULT_UPSTREAM_BASE
+    api_key: str = ""  # 上游凭证(proxy -> 上游)
+    local_token: str = ""  # 本地 proxy 鉴权 token(codex -> proxy);空则不校验(仅本地调试)
+    timeout: float = 180.0
+
+    def __post_init__(self) -> None:
+        self.upstream_base = _require_secure_upstream(self.upstream_base.rstrip("/"))
+
+    @classmethod
+    def from_env(cls) -> "ProxyConfig":
+        return cls(
+            upstream_base=os.environ.get("UPSTREAM_BASE", DEFAULT_UPSTREAM_BASE),
+            api_key=os.environ.get("KSPMAS_API_KEY", ""),
+            local_token=os.environ.get("KSADK_PROXY_TOKEN", ""),
+            timeout=float(os.environ.get("UPSTREAM_TIMEOUT", "180")),
+        )
+
+
+def _require_secure_upstream(upstream: str) -> str:
+    """凭证安全:scheme 仅 http/https;非回环主机必须 https(避免明文携带 Bearer)。
+
+    用 urlsplit 规范化 scheme/hostname,堵 `HTTP://`(大小写)与 `ftp://` 绕过。
+    """
+    parts = urlsplit(upstream)
+    scheme = parts.scheme.lower()
+    host = (parts.hostname or "").lower()
+    if scheme not in ("http", "https"):
+        raise ValueError(f"不支持的上游 scheme(仅 http/https): {upstream}")
+    if scheme == "http" and host not in _LOOPBACK_HOSTS:
+        raise ValueError(f"上游必须使用 https(携带凭证,禁明文 http): {upstream}")
+    return upstream