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

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

ksadk/model_proxy/demo_webui.py

@@ -0,0 +1,115 @@
+"""极简 codex 对话 webui(端到端验证用,非生产入口)。
+
+绕过 ksadk web 的框架检测(它不认 codex):直接用 AsyncCodexClient + 一个
+最小 FastAPI 提供 HTML 页 + /chat SSE,在浏览器里展示 codex runtime 经
+model_proxy 代理跑星流 chat 模型的真实对话流。
+
+用法:
+  KSADK_CODEX_USE_PROXY=1 OPENAI_API_BASE=https://kspmas.ksyun.com/v1 \
+  OPENAI_API_KEY=xxx CODEX_HOME=/tmp/codex_clean_runtime \
+  uv run python -m ksadk.model_proxy.demo_webui --port 8877
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+
+import uvicorn
+from fastapi import FastAPI, Request
+from fastapi.responses import HTMLResponse, StreamingResponse
+
+logger = logging.getLogger(__name__)
+
+# ruff: noqa: E501  内联 HTML/CSS/JS 演示字面量,长行不拆
+
+_PAGE = """<!doctype html><html lang="zh"><head><meta charset="utf-8">
+<title>codex runtime e2e</title>
+<style>
+body{font-family:system-ui,sans-serif;max-width:760px;margin:2rem auto;padding:0 1rem}
+#log{border:1px solid #ddd;border-radius:8px;padding:1rem;min-height:200px;white-space:pre-wrap;font-family:ui-monospace,monospace}
+.u{color:#0969da}.a{color:#1a7f37}.t{color:#666}
+input{width:70%;padding:.5rem}button{padding:.5rem 1rem}
+</style></head><body>
+<h3>codex runtime → model_proxy → 星流 chat</h3>
+<form id="f"><input id="q" placeholder="说点什么..." autocomplete="off">
+<button>发送</button></form>
+<div id="log"></div>
+<script>
+const log=document.getElementById('log');
+function add(cls,text){const d=document.createElement('div');d.className=cls;d.textContent=text;log.appendChild(d);log.scrollTop=log.scrollHeight;}
+document.getElementById('f').onsubmit=async e=>{
+  e.preventDefault();const q=document.getElementById('q').value;if(!q)return;
+  add('u','你: '+q);document.getElementById('q').value='';const t=document.createElement('div');t.className='t';t.textContent='(流式中...)';log.appendChild(t);
+  const r=await fetch('/chat',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({q})});
+  const reader=r.body.getReader();const dec=new TextDecoder();t.remove();let buf='';
+  while(true){const{value,done}=await reader.read();if(done)break;buf+=dec.decode(value);const lines=buf.split('\\n');buf=lines.pop();
+    for(const ln of lines){if(!ln.startsWith('data:'))continue;try{const ev=JSON.parse(ln.slice(5).trim());
+      if(ev.delta)add('a',ev.delta);if(ev.reply)add('a','✅ '+ev.reply);if(ev.error)add('t','❌ '+ev.error);}catch{}}}
+};
+</script></body></html>"""
+
+
+def create_demo_app() -> FastAPI:
+    from ksadk.codex.client import AsyncCodexClient
+
+    app = FastAPI()
+    client: dict = {"c": None, "tid": None}
+
+    @app.get("/", response_class=HTMLResponse)
+    def index():
+        return _PAGE
+
+    @app.post("/chat")
+    async def chat(req: Request):
+        body = await req.json()
+        q = body.get("q", "")
+
+        async def gen():
+            if client["c"] is None:
+                c = AsyncCodexClient()
+                client["c"] = c
+                client["tid"] = await c.start_thread(
+                    config={
+                        "model": os.environ.get("OPENAI_MODEL_NAME", "glm-5.2"),
+                        "sandbox_read_only": True,
+                    }
+                )
+            try:
+                async for ev in client["c"].run_turn(client["tid"], q):
+                    m = ev.get("method", "")
+                    if m == "item/agentMessage/delta":
+                        yield f"data: {json.dumps({'delta': ev['params'].get('delta', '')}, ensure_ascii=False)}\n\n"
+                    elif m == "item/completed":
+                        it = ev["params"]["item"]
+                        if it.get("type") == "agentMessage" and it.get("text"):
+                            yield f"data: {json.dumps({'reply': it['text']}, ensure_ascii=False)}\n\n"
+                    elif m == "error":
+                        logger.warning("Codex demo runtime reported an error")
+                        yield 'data: {"error":"Codex runtime failed; see local logs."}\n\n'
+            except Exception as e:  # noqa: BLE001
+                logger.warning("Codex demo runtime failed", exc_info=e)
+                yield 'data: {"error":"Codex runtime failed; see local logs."}\n\n'
+
+        return StreamingResponse(gen(), media_type="text/event-stream")
+
+    @app.on_event("shutdown")
+    async def shutdown():
+        if client["c"] is not None:
+            await client["c"].close()
+
+    return app
+
+
+def main():
+    import argparse
+
+    p = argparse.ArgumentParser()
+    p.add_argument("--port", type=int, default=8877)
+    args = p.parse_args()
+    uvicorn.run(create_demo_app(), host="127.0.0.1", port=args.port, log_level="warning")
+
+
+if __name__ == "__main__":
+    main()

ksadk/model_proxy/detect.py

@@ -0,0 +1,145 @@
+"""模型能力矩阵探测(v2.3):替代简单 responses/chat 二分。
+
+"支持 responses" 不等于 "该直通"——glm-5.1 原生 responses 丢增量 delta + 拒 namespace 工具,
+经转换层反而更好。本模块用能力矩阵描述一个 (model, base_url, credential) 的真实能力,
+供路由决策(直通 responses / 走转换层 chat / …)。
+
+探测铁律(review v1):
+- **功能性 probe 而非状态码 probe**:发最小真请求打 /v1/responses,校验返回是否为
+  合法 responses 结构(有 ``output``/``status``),不只看 HTTP 200——网关对不支持的
+  端点有时也返回 200 但内容是错误页。
+- **只在 "确凿协议否定" 时翻案**:`404/405/400 unknown endpoint` 才判 "不支持 responses";
+  超时/5xx/429/401/403 一律 "unknown",不改变判定(故障 ≠ 能力缺失)。
+- ``stream_delta_ok`` 需真发流式请求才能判定,成本高,本模块默认 None(不探),
+  由调用方按需触发或默认走转换层(转换层自己生成完整 delta)。
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+import httpx
+
+Verdict = Literal["supported", "unsupported", "unknown"]
+
+
+@dataclass
+class ModelCapabilities:
+    """一个 (model, base_url, credential_scope) 的协议能力矩阵。"""
+
+    responses_supported: bool | None = None  # None = 未知(未探/不确定)
+    stream_delta_ok: bool | None = None  # 流式增量 delta;None = 未探
+    tool_types: set[str] = field(default_factory=set)  # 支持的工具 namespace
+    preferred_protocol: str = "chat"  # "responses" | "chat":路由该走哪条
+    checked_at: float = 0.0
+    verdict: Verdict = "unknown"  # 最近一次探测结论
+
+
+def _classify_responses_error(status: int, body: str) -> Verdict:
+    """把非 200 响应分类成 supported/unsupported/unknown。
+
+    只有 "确凿协议否定" 才判 unsupported;故障类一律 unknown(不误固化)。
+    """
+    if status in (404, 405):
+        return "unsupported"
+    if status == 400:
+        low = (body or "").lower()
+        # 400 且 body 含 "unknown/not supported/endpoint" -> endpoint 不支持
+        if any(k in low for k in ("unknown", "not supported", "endpoint", "unrecognized")):
+            return "unsupported"
+        return "unknown"  # 400 但不像协议级否定(可能是请求字段问题)
+    # 401/403:鉴权/权限问题,不代表 endpoint 不存在(同 key 不同能力,见 glm-5.1 403)
+    if status in (401, 403):
+        return "unknown"
+    return "unknown"  # 5xx/429/其他:故障类
+
+
+def probe_responses_capability(
+    client: httpx.Client | httpx.AsyncClient,
+    base: str,
+    key: str,
+    model: str,
+    timeout: float = 30.0,
+):
+    """功能性 probe /v1/responses,返回能力矩阵(sync) 或 coroutine(async)。
+
+    - 200 且结构合法(output+status)→ supported,preferred_protocol=responses
+    - 200 但非 responses 结构(网关伪 200)→ unsupported,preferred_protocol=chat
+    - 404/405/400 unknown → unsupported,preferred_protocol=chat
+    - 超时/5xx/429/401/403 → unknown,preferred_protocol 保持默认 chat(保守走转换层)
+
+    按 client 类型分发:``httpx.Client`` 同步返回 ``ModelCapabilities``;
+    ``httpx.AsyncClient`` 返回 coroutine(调用方 await)。
+    """
+    if isinstance(client, httpx.AsyncClient):
+        return _probe_async(client, base, key, model, timeout)
+    if isinstance(client, httpx.Client):
+        return _probe_sync(client, base, key, model, timeout)
+    raise TypeError(f"client 必须是 httpx.Client/AsyncClient,不是 {type(client).__name__}")
+
+
+def _probe_sync(
+    client: httpx.Client, base: str, key: str, model: str, timeout: float
+) -> ModelCapabilities:
+    caps = ModelCapabilities(checked_at=time.time(), verdict="unknown")
+    url = f"{base.rstrip('/')}/responses"
+    headers = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}
+    payload = {"model": model, "input": "hi", "max_output_tokens": 1, "stream": False}
+    try:
+        r = client.post(url, json=payload, headers=headers, timeout=timeout)
+    except (httpx.TimeoutException, httpx.ConnectError, httpx.HTTPError):
+        return _finalize(caps)
+    try:
+        data = r.json()
+    except ValueError:
+        data = None
+    return _apply_response(caps, r.status_code, r.text, data)
+
+
+async def _probe_async(
+    client: httpx.AsyncClient, base: str, key: str, model: str, timeout: float
+) -> ModelCapabilities:
+    caps = ModelCapabilities(checked_at=time.time(), verdict="unknown")
+    url = f"{base.rstrip('/')}/responses"
+    headers = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}
+    payload = {"model": model, "input": "hi", "max_output_tokens": 1, "stream": False}
+    try:
+        r = await client.post(url, json=payload, headers=headers, timeout=timeout)
+    except (httpx.TimeoutException, httpx.ConnectError, httpx.HTTPError):
+        return _finalize(caps)
+    try:
+        data = r.json()
+    except ValueError:
+        data = None
+    return _apply_response(caps, r.status_code, r.text, data)
+
+
+def _apply_response(
+    caps: ModelCapabilities, status: int, text: str, data: Any
+) -> ModelCapabilities:
+    if status == 200:
+        # 功能性校验:合法 responses 结构有 output + status(不只看 200)
+        if isinstance(data, dict) and "output" in data and "status" in data:
+            caps.responses_supported = True
+            caps.verdict = "supported"
+        else:
+            # 200 但不是 responses 结构(网关伪 200 / 错误页)
+            caps.responses_supported = False
+            caps.verdict = "unsupported"
+        return _finalize(caps)
+    caps.verdict = _classify_responses_error(status, text)
+    caps.responses_supported = False if caps.verdict == "unsupported" else None
+    return _finalize(caps)
+
+
+def _finalize(caps: ModelCapabilities) -> ModelCapabilities:
+    """根据 verdict 定 preferred_protocol(保守:不确定也走转换层 chat)。"""
+    if caps.verdict == "supported" and caps.responses_supported:
+        caps.preferred_protocol = "responses"
+    else:
+        # unsupported 或 unknown 都默认 chat(走转换层):unknown 时走转换层更安全,
+        # 因为转换层对 chat 模型是确定可用的,而直连 responses 在 unknown 下有风险
+        caps.preferred_protocol = "chat"
+    return caps

ksadk/model_proxy/gate.py

@@ -0,0 +1,68 @@
+"""开关与灰度配置(v2.5):默认关闭,按需启用,一键回退直连。
+
+review v1 要求:全局默认关,支持按 agent/按模型白名单开启,故障一键回退。
+设计为纯配置判定(env/agentengine.yaml 解析后传入),不含网络/proxy 生命周期——
+后者由 v2.1(codex)/v2.2(env 框架)各自接线时调用。
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ProxyGate:
+    """协议转换层的开关/灰度判定(纯函数,不持有运行时状态)。
+
+    - ``enabled``:全局开关,默认 False。
+    - ``agent_allowlist``/``model_allowlist``:细粒度白名单;空=不按此维度放行。
+    - ``denylist``:显式拒绝(优先级最高),用于故障一键回退某 agent/模型。
+
+    判定优先级:denylist > 全局 enabled > 白名单。
+    """
+
+    enabled: bool = False
+    agent_allowlist: set[str] = field(default_factory=set)
+    model_allowlist: set[str] = field(default_factory=set)
+    denylist: set[str] = field(default_factory=set)
+
+    def is_on(self, agent: str | None = None, model: str | None = None) -> bool:
+        """是否对该 (agent, model) 启用转换层。
+
+        - denylist 命中(agent 或 model)→ False(一键回退)
+        - 全局 enabled=False → False(默认关)
+        - 全局 enabled=True → True(除非 denylist)
+        - 全局关但白名单命中(agent 或 model)→ True(灰度放行)
+        """
+        if agent and agent in self.denylist:
+            return False
+        if model and model in self.denylist:
+            return False
+        if self.enabled:
+            return True
+        if agent and agent in self.agent_allowlist:
+            return True
+        if model and model in self.model_allowlist:
+            return True
+        return False
+
+    @classmethod
+    def from_env(cls) -> "ProxyGate":
+        """从 env 读开关与白名单(逗号分隔)。
+
+        - ``KSADK_MODEL_PROXY_ENABLED=1`` 全局开
+        - ``KSADK_MODEL_PROXY_AGENTS=a,b`` agent 白名单
+        - ``KSADK_MODEL_PROXY_MODELS=glm-5.2`` model 白名单
+        - ``KSADK_MODEL_PROXY_DENY=c`` 一键回退
+        """
+        def _split(name: str) -> set[str]:
+            v = os.environ.get(name, "").strip()
+            return {x.strip() for x in v.split(",") if x.strip()} if v else set()
+
+        return cls(
+            enabled=os.environ.get("KSADK_MODEL_PROXY_ENABLED") == "1",
+            agent_allowlist=_split("KSADK_MODEL_PROXY_AGENTS"),
+            model_allowlist=_split("KSADK_MODEL_PROXY_MODELS"),
+            denylist=_split("KSADK_MODEL_PROXY_DENY"),
+        )