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

ksadk/studio/hosted_kernel.py

@@ -0,0 +1,317 @@
+"""Content-addressed preflight for Studio Code bundles hosted by Agent Kernel.
+
+This module deliberately proves only properties available in the local bundle:
+the frozen Agent Kernel wire-contract digest and the launch layout generated by
+Studio. Whether the target Server-selected image implements that digest remains
+a separate control-plane/readiness check.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import zipfile
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+from typing import Any
+
+from ksadk.studio.capabilities import canonical_json, sha256_digest
+from ksadk.studio.errors import StudioError
+
+AGENT_KERNEL_V1_CONTRACT_SET = "agent-kernel/v1"
+# This mirrors contracts/agent-kernel/v1/manifest.json. A Studio test compares
+# the two, so a frozen-contract update cannot leave packaged preflight stale.
+AGENT_KERNEL_V1_CONTRACT_DIGEST = "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
+HOSTED_KERNEL_REQUIREMENTS_PATH = "hosted-kernel-requirements.json"
+HOSTED_KERNEL_REQUIREMENTS_FORMAT = "agentkit.hosted-kernel-requirements/v1"
+HOSTED_KERNEL_RUNTIME_CONTRACT = "agentkit.runtime/v1"
+HOSTED_KERNEL_BUNDLE_FORMAT = "agentkit.bundle/v2"
+_RUNTIME_TYPES = frozenset({"adk", "codex", "langgraph"})
+
+
+@dataclass(frozen=True)
+class HostedKernelBundle:
+    """Facts proved from the exact ZIP bytes that will be uploaded."""
+
+    manifest: dict[str, Any]
+    provenance: dict[str, Any]
+    requirement: dict[str, Any]
+    requirement_digest: str
+
+
+def build_hosted_kernel_requirement(
+    *,
+    runtime_type: str,
+    entry_point: str | None,
+    agent_variable: str | None,
+    launch_config: bytes | None,
+) -> dict[str, Any]:
+    """Build the immutable local requirement embedded into every Studio ZIP."""
+
+    return {
+        "format": HOSTED_KERNEL_REQUIREMENTS_FORMAT,
+        "kernelContract": {
+            "set": AGENT_KERNEL_V1_CONTRACT_SET,
+            "digest": AGENT_KERNEL_V1_CONTRACT_DIGEST,
+        },
+        "bundleLayout": HOSTED_KERNEL_BUNDLE_FORMAT,
+        "runtimeContract": HOSTED_KERNEL_RUNTIME_CONTRACT,
+        "runtime": {
+            "type": runtime_type,
+            "entryPoint": entry_point or "",
+            "agentVariable": agent_variable or "",
+            "launchConfig": "runtime/agentengine.yaml" if launch_config is not None else "",
+            "launchConfigSha256": sha256_digest(launch_config) if launch_config is not None else "",
+        },
+    }
+
+
+def hosted_kernel_requirement_digest(requirement: dict[str, Any]) -> str:
+    return sha256_digest(canonical_json(requirement))
+
+
+def preflight_hosted_kernel_bundle(bundle: bytes) -> HostedKernelBundle:
+    """Reject a ZIP that cannot be proved compatible before CreateAgent.
+
+    This validates the uploaded bytes, including their file manifest, instead
+    of trusting a writable sibling directory from a local Build.
+    """
+
+    try:
+        with zipfile.ZipFile(io.BytesIO(bundle)) as archive:
+            names = _validated_zip_names(archive)
+            entries = {name: archive.read(name) for name in names}
+    except (OSError, zipfile.BadZipFile, zipfile.LargeZipFile) as error:
+        raise _integrity_error("Bundle 不是可验证的 ZIP 文件", reason="invalid_zip") from error
+
+    manifest = _json_object(entries, "manifest.json")
+    provenance = _json_object(entries, "provenance.json")
+    requirement = _json_object(entries, HOSTED_KERNEL_REQUIREMENTS_PATH)
+    requirement_digest = hosted_kernel_requirement_digest(requirement)
+
+    _validate_requirement(manifest, provenance, requirement, requirement_digest, entries)
+    _validate_content_manifest(manifest, entries)
+    _validate_declared_bundle_digest(manifest)
+    return HostedKernelBundle(
+        manifest=manifest,
+        provenance=provenance,
+        requirement=requirement,
+        requirement_digest=requirement_digest,
+    )
+
+
+def _validated_zip_names(archive: zipfile.ZipFile) -> list[str]:
+    names = archive.namelist()
+    if not names:
+        raise _integrity_error("Bundle 为空", reason="empty_zip")
+    if len(names) != len(set(names)):
+        raise _integrity_error("Bundle 含有重复文件名", reason="duplicate_path")
+    for name in names:
+        path = PurePosixPath(name)
+        if (
+            not name
+            or "\\" in name
+            or name.endswith("/")
+            or path.is_absolute()
+            or any(part in {"", ".", ".."} for part in path.parts)
+        ):
+            raise _integrity_error("Bundle 含有不安全文件路径", reason="unsafe_path")
+    return names
+
+
+def _json_object(entries: dict[str, bytes], path: str) -> dict[str, Any]:
+    raw = entries.get(path)
+    if raw is None:
+        raise _incompatible_error(f"Bundle 缺少 {path}", reason="missing_required_file")
+    try:
+        parsed = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise _incompatible_error(
+            f"Bundle 中的 {path} 不是 JSON 对象", reason="invalid_json"
+        ) from error
+    if not isinstance(parsed, dict):
+        raise _incompatible_error(f"Bundle 中的 {path} 不是 JSON 对象", reason="invalid_json")
+    return parsed
+
+
+def _validate_requirement(
+    manifest: dict[str, Any],
+    provenance: dict[str, Any],
+    requirement: dict[str, Any],
+    requirement_digest: str,
+    entries: dict[str, bytes],
+) -> None:
+    if manifest.get("bundleFormat") != HOSTED_KERNEL_BUNDLE_FORMAT:
+        raise _incompatible_error(
+            "Bundle 不是受支持的 Studio Code bundle 格式", reason="bundle_format"
+        )
+    if manifest.get("runtimeContract") != HOSTED_KERNEL_RUNTIME_CONTRACT:
+        raise _incompatible_error(
+            "Bundle runtime contract 不受 Hosted Agent Kernel 支持", reason="runtime_contract"
+        )
+    if requirement.get("format") != HOSTED_KERNEL_REQUIREMENTS_FORMAT:
+        raise _incompatible_error(
+            "Bundle 缺少 Hosted Agent Kernel requirement 格式声明", reason="requirement_format"
+        )
+    if requirement.get("bundleLayout") != manifest.get("bundleFormat"):
+        raise _incompatible_error(
+            "Bundle requirement 与 bundle layout 不一致", reason="bundle_layout"
+        )
+    if requirement.get("runtimeContract") != manifest.get("runtimeContract"):
+        raise _incompatible_error(
+            "Bundle requirement 与 runtime contract 不一致", reason="runtime_contract"
+        )
+
+    contract = requirement.get("kernelContract")
+    if not isinstance(contract, dict):
+        raise _incompatible_error(
+            "Bundle 缺少 Agent Kernel contract requirement", reason="missing_contract"
+        )
+    if contract.get("set") != AGENT_KERNEL_V1_CONTRACT_SET:
+        raise _incompatible_error(
+            "Bundle Agent Kernel contract set 不受支持", reason="contract_set"
+        )
+    if contract.get("digest") != AGENT_KERNEL_V1_CONTRACT_DIGEST:
+        raise _incompatible_error(
+            "Bundle Agent Kernel contract digest 与当前 KsADK 不一致，请重新 Build 后部署",
+            reason="contract_digest",
+        )
+
+    hosted = provenance.get("hostedKernel")
+    if not isinstance(hosted, dict):
+        raise _incompatible_error(
+            "Bundle provenance 缺少 Hosted Agent Kernel requirement", reason="missing_provenance"
+        )
+    if hosted.get("requirementsPath") != HOSTED_KERNEL_REQUIREMENTS_PATH:
+        raise _incompatible_error(
+            "Bundle provenance 的 requirement 路径不一致", reason="provenance_path"
+        )
+    if hosted.get("requirementDigest") != requirement_digest:
+        raise _incompatible_error(
+            "Bundle provenance 的 requirement digest 不一致", reason="provenance_digest"
+        )
+    if hosted.get("contractSet") != contract.get("set") or hosted.get(
+        "contractDigest"
+    ) != contract.get("digest"):
+        raise _incompatible_error(
+            "Bundle provenance 的 Agent Kernel contract 不一致", reason="provenance_contract"
+        )
+    if manifest.get("hostedKernelRequirementDigest") != requirement_digest:
+        raise _incompatible_error(
+            "Bundle manifest 的 requirement digest 不一致", reason="manifest_digest"
+        )
+
+    runtime = requirement.get("runtime")
+    if not isinstance(runtime, dict):
+        raise _incompatible_error(
+            "Bundle 缺少受支持的 runtime 启动 requirement", reason="missing_runtime"
+        )
+    runtime_type = str(runtime.get("type") or "").strip().lower()
+    entry_point = str(runtime.get("entryPoint") or "").strip()
+    agent_variable = str(runtime.get("agentVariable") or "").strip()
+    launch_path = str(runtime.get("launchConfig") or "").strip()
+    launch_digest = str(runtime.get("launchConfigSha256") or "").strip()
+    if runtime_type not in _RUNTIME_TYPES:
+        raise _incompatible_error(
+            "Bundle runtime 类型不受 Hosted Agent Kernel 支持", reason="runtime_type"
+        )
+    if (
+        runtime_type != str(manifest.get("runtimeType") or "").strip().lower()
+        or not entry_point
+        or not agent_variable
+        or launch_path != "runtime/agentengine.yaml"
+        or not launch_digest
+    ):
+        raise _incompatible_error("Bundle 缺少可验证的 runtime 启动配置", reason="runtime_launch")
+    if not _safe_relative_file(entry_point) or f"runtime/{entry_point}" not in entries:
+        raise _incompatible_error("Bundle runtime entryPoint 不存在或不安全", reason="entry_point")
+    launch_bytes = entries.get(launch_path)
+    if launch_bytes is None or sha256_digest(launch_bytes) != launch_digest:
+        raise _incompatible_error("Bundle runtime 启动配置 digest 不一致", reason="launch_digest")
+    launch = _json_object(entries, launch_path)
+    if (
+        str(launch.get("framework") or "").strip().lower() != runtime_type
+        or launch.get("entry_point") != entry_point
+        or launch.get("agent_variable") != agent_variable
+        or launch.get("package") != "."
+    ):
+        raise _incompatible_error(
+            "Bundle runtime 启动配置与 requirement 不一致", reason="launch_config"
+        )
+    runtime_lock = _json_object(entries, "runtime-lock.json")
+    if (
+        str(runtime_lock.get("type") or "").strip().lower() != runtime_type
+        or runtime_lock.get("entryPoint") != entry_point
+        or runtime_lock.get("agentVariable") != agent_variable
+    ):
+        raise _incompatible_error(
+            "Bundle runtime lock 与 requirement 不一致", reason="runtime_lock"
+        )
+
+
+def _validate_content_manifest(manifest: dict[str, Any], entries: dict[str, bytes]) -> None:
+    files = manifest.get("files")
+    if not isinstance(files, list):
+        raise _integrity_error("Bundle manifest 缺少文件清单", reason="missing_file_manifest")
+    recorded: dict[str, dict[str, Any]] = {}
+    for item in files:
+        if not isinstance(item, dict) or not isinstance(item.get("path"), str):
+            raise _integrity_error("Bundle manifest 的文件清单无效", reason="invalid_file_manifest")
+        path = item["path"]
+        if path in recorded or not _safe_relative_file(path) or path == "manifest.json":
+            raise _integrity_error("Bundle manifest 的文件路径无效", reason="invalid_file_manifest")
+        recorded[path] = item
+    if set(entries) != set(recorded) | {"manifest.json"}:
+        raise _integrity_error("Bundle ZIP 与 manifest 文件清单不一致", reason="file_membership")
+    for path, item in recorded.items():
+        content = entries[path]
+        if item.get("sha256") != sha256_digest(content) or item.get("size") != len(content):
+            raise _integrity_error("Bundle 文件摘要与 manifest 不一致", reason="file_digest")
+
+
+def _validate_declared_bundle_digest(manifest: dict[str, Any]) -> None:
+    declared = manifest.get("bundleDigest")
+    digest_payload = dict(manifest)
+    digest_payload.pop("bundleDigest", None)
+    if declared != sha256_digest(canonical_json(digest_payload)):
+        raise _integrity_error("Bundle manifest 的 bundle digest 不一致", reason="bundle_digest")
+
+
+def _safe_relative_file(value: str) -> bool:
+    path = PurePosixPath(value)
+    return (
+        bool(value)
+        and "\\" not in value
+        and not path.is_absolute()
+        and all(part not in {"", ".", ".."} for part in path.parts)
+    )
+
+
+def _incompatible_error(message: str, *, reason: str) -> StudioError:
+    return StudioError(
+        "HOSTED_KERNEL_BUNDLE_INCOMPATIBLE",
+        message,
+        status_code=422,
+        details={"reason": reason},
+    )
+
+
+def _integrity_error(message: str, *, reason: str) -> StudioError:
+    return StudioError(
+        "HOSTED_KERNEL_BUNDLE_INTEGRITY_INVALID",
+        message,
+        status_code=422,
+        details={"reason": reason},
+    )
+
+
+__all__ = [
+    "AGENT_KERNEL_V1_CONTRACT_DIGEST",
+    "AGENT_KERNEL_V1_CONTRACT_SET",
+    "HOSTED_KERNEL_REQUIREMENTS_FORMAT",
+    "HOSTED_KERNEL_REQUIREMENTS_PATH",
+    "HostedKernelBundle",
+    "build_hosted_kernel_requirement",
+    "hosted_kernel_requirement_digest",
+    "preflight_hosted_kernel_bundle",
+]

ksadk/studio/manifest_resolver.py

@@ -0,0 +1,131 @@
+"""ManifestResolver —— 统一识别工作区根 Manifest 的种类（方案 §6.1）。
+
+当前问题（方案 §2.4 第 1 点）：标准 LangGraph/ADK 项目作为 Studio workspace 启动后，根
+``agentengine.yaml`` 可能先进入 Codex Manifest 解析，导致 ``CODEX_MANIFEST_INVALID``。
+
+本模块提供统一入口：根 manifest 存在时先读 ``framework`` / ``runtime.type`` 字段决定 kind，
+只有明确 ``framework: codex`` 才走 ``CodexAgentManifest`` 解析；明确为 ADK/LangGraph 等框架时
+返回 framework kind（交给 ``FrameworkDetector`` 与标准 Code 项目导入）；无法判定时返回
+``MANIFEST_KIND_AMBIGUOUS``，列出候选，不猜测为 Codex。
+
+解析顺序（方案 §6.1）：
+1. 根 manifest 不存在 → ``none``
+2. 显式 ``framework: codex`` 或 ``runtime.name: codex`` → ``codex``
+3. 显式 ``framework: adk|langgraph|...`` 或 ``runtime.type: adk|langgraph|...`` → ``framework``
+4. 仍无法判定 → ``ambiguous``（列出已读到的关键字段，便于诊断）
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+
+ManifestKind = Literal["none", "codex", "framework", "ambiguous"]
+
+# framework/runtime 字段的已知 codex / framework 取值。
+_CODEX_FRAMEWORK_VALUES = frozenset({"codex"})
+_CODEX_RUNTIME_VALUES = frozenset({"codex"})
+_FRAMEWORK_VALUES = frozenset({"adk", "langgraph", "langchain", "deepagents", "hermes", "openclaw"})
+
+
+@dataclass(frozen=True)
+class ManifestKindResult:
+    """根 manifest 识别结果。"""
+
+    kind: ManifestKind
+    path: Path
+    framework: str = ""
+    runtime_type: str = ""
+    artifact_type: str = ""
+    # ambiguous 时列出已读字段，供诊断与错误返回。
+    detected_fields: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_codex(self) -> bool:
+        return self.kind == "codex"
+
+
+def _safe_yaml(path: Path) -> dict[str, Any]:
+    try:
+        with open(path, "r", encoding="utf-8-sig") as f:
+            payload = yaml.safe_load(f)
+    except (OSError, yaml.YAMLError):
+        return {}
+    if not isinstance(payload, dict):
+        return {}
+    return payload
+
+
+def detect_manifest_kind(workspace_root: Path | str) -> ManifestKindResult:
+    """识别工作区根 manifest 的种类（方案 §6.1）。
+
+    ``workspace_root`` 指工作区目录；本函数查其下的 ``agentengine.yaml``（不存在时返回 ``none``）。
+    """
+    root = Path(workspace_root)
+    path = root / "agentengine.yaml"
+    if not path.is_file():
+        return ManifestKindResult(kind="none", path=path)
+
+    payload = _safe_yaml(path)
+    if not payload:
+        # 文件存在但无法解析为 dict → ambiguous（不猜测为 codex）
+        return ManifestKindResult(kind="ambiguous", path=path, detected_fields={"unparsable": True})
+
+    framework = str(payload.get("framework") or "").strip().lower()
+    runtime = payload.get("runtime") or {}
+    runtime_type = (
+        str(runtime.get("type") or runtime.get("name") or "").strip().lower()
+        if isinstance(runtime, dict)
+        else ""
+    )
+    artifact_type = str(payload.get("artifact_type") or "").strip().lower()
+    detected = {
+        "framework": framework,
+        "runtimeType": runtime_type,
+        "artifactType": artifact_type,
+        "topLevelKeys": sorted(payload.keys()),
+    }
+
+    # 2. 显式 codex
+    if framework in _CODEX_FRAMEWORK_VALUES or runtime_type in _CODEX_RUNTIME_VALUES:
+        return ManifestKindResult(
+            kind="codex",
+            path=path,
+            framework=framework,
+            runtime_type=runtime_type,
+            artifact_type=artifact_type,
+        )
+    # 3. 显式 framework
+    if framework in _FRAMEWORK_VALUES or runtime_type in _FRAMEWORK_VALUES:
+        return ManifestKindResult(
+            kind="framework",
+            path=path,
+            framework=framework or runtime_type,
+            runtime_type=runtime_type,
+            artifact_type=artifact_type,
+        )
+    # 4. 无法判定（例如只有 name/version 但无 framework/runtime）
+    return ManifestKindResult(
+        kind="ambiguous",
+        path=path,
+        framework=framework,
+        runtime_type=runtime_type,
+        artifact_type=artifact_type,
+        detected_fields=detected,
+    )
+
+
+def root_manifest_is_codex(workspace_root: Path | str) -> bool:
+    """便捷判定：根 manifest 是否应走 Codex 解析（方案 §6.1）。"""
+    return detect_manifest_kind(workspace_root).is_codex
+
+
+__all__ = [
+    "ManifestKind",
+    "ManifestKindResult",
+    "detect_manifest_kind",
+    "root_manifest_is_codex",
+]

ksadk/studio/model_client.py

@@ -23,6 +23,12 @@ _DENIED_METADATA_HOSTS = {
     "fd00:ec2::254",
 }
 
+#: 表示输出被 token 上限截断的 finishReason 集合（chat 与 Responses 两种 wire）。
+_LENGTH_FINISH_REASONS = {"length", "incomplete", "max_output_tokens"}
+#: length 截断重试时把 max_tokens 提到的目标值；未配置 max_tokens 的 profile
+#: 首次截断重试也用该值兜底（authoring 输出完整 JSON 需要宽松上限）。
+_LENGTH_RETRY_TARGET_TOKENS = 16384
+
 
 @dataclass(frozen=True)
 class ToolCall:
@@ -325,36 +331,50 @@ class OpenAICompatibleModelClient:
         backoff_seconds: float,
         tools: list[dict[str, Any]] | None = None,
         allow_empty: bool = False,
+        response_format: dict[str, Any] | None = None,
+        retry_on_length: bool = False,
     ) -> ModelResponse:
         await self.network_guard.check(model.endpoint_url, network_policy)
         credential = self.credential_resolver.resolve(model.credential_ref)
         wire_api = (model.wire_api or "chat").strip().lower()
+        payload: dict[str, Any]
         if wire_api == "responses":
             payload = self._responses_payload(model, messages, tools)
         else:
             payload = {
                 "model": model.model,
                 "messages": messages,
-                "temperature": model.parameters.temperature,
-                "max_tokens": model.parameters.max_tokens,
                 "stream": False,
             }
+            # 未显式配置的采样参数一律不携带字段，交给服务端默认，
+            # 避免触碰各模型族的硬约束（kimi 温度、各家 max_tokens 上限等）。
+            if model.parameters.temperature is not None:
+                payload["temperature"] = model.parameters.temperature
+            if model.parameters.max_tokens is not None:
+                payload["max_tokens"] = model.parameters.max_tokens
             if model.parameters.top_p is not None:
                 payload["top_p"] = model.parameters.top_p
             if tools:
                 payload["tools"] = tools
                 payload["tool_choice"] = "auto"
+            if response_format and model.parameters.allow_json_response_format:
+                payload["response_format"] = response_format
         headers = {
             "Authorization": f"Bearer {credential}",
             "Content-Type": "application/json",
         }
         timeout = httpx.Timeout(timeout_seconds, connect=min(10, timeout_seconds))
+        dropped_response_format = False
+        length_retried = False
+        last_length_error: StudioError | None = None
         async with httpx.AsyncClient(
             transport=self.transport,
             timeout=timeout,
             follow_redirects=False,
         ) as client:
-            for attempt in range(1, max_attempts + 1):
+            # 额外 1 次迭代仅用于 response_format 400 降级重发，
+            # 其余失败路径仍受 max_attempts 约束（会在原上限处 raise）。
+            for attempt in range(1, max_attempts + 2):
                 try:
                     response = await client.post(
                         model.endpoint_url,
@@ -382,18 +402,83 @@ class OpenAICompatibleModelClient:
                     if attempt < max_attempts:
                         await self.sleep(backoff_seconds * attempt)
                         continue
+                if (
+                    response.status_code == 400
+                    and "response_format" in payload
+                    and not dropped_response_format
+                ):
+                    # 网关不支持 response_format：去掉该字段重发一次。
+                    dropped_response_format = True
+                    payload.pop("response_format")
+                    continue
                 if response.status_code >= 400:
+                    if response.status_code == 429:
+                        # A selected authoring profile must not silently fall
+                        # back to a different model.  Preserve the actual
+                        # upstream condition so Studio can offer the user a
+                        # useful retry/switch decision instead of reporting a
+                        # misleading generic 502.
+                        raise StudioError(
+                            "MODEL_RATE_LIMITED",
+                            "所选生成模型当前限流，请稍后重试或切换模型 Profile",
+                            status_code=429,
+                            details={"upstreamStatus": response.status_code},
+                        )
+                    upstream_detail = ""
+                    try:
+                        upstream_detail = response.text[:200]
+                    except Exception:  # noqa: BLE001 - 诊断信息尽力而为
+                        upstream_detail = ""
                     raise StudioError(
                         "MODEL_REQUEST_FAILED",
                         "模型服务返回错误",
                         status_code=502,
-                        details={"upstreamStatus": response.status_code},
+                        details={
+                            "upstreamStatus": response.status_code,
+                            "upstreamError": upstream_detail,
+                        },
                     )
-                if wire_api == "responses":
-                    return self._parse_responses_response(response, allow_empty=allow_empty)
-                return self._parse_response(response, allow_empty=allow_empty)
+                try:
+                    if wire_api == "responses":
+                        parsed = self._parse_responses_response(response, allow_empty=allow_empty)
+                    else:
+                        parsed = self._parse_response(response, allow_empty=allow_empty)
+                except StudioError as exc:
+                    # finishReason=length 的空响应（大 JSON 被 max_tokens 截断）：
+                    # 一次性扩容 max_tokens 重发；再次截断则按原错误上抛。
+                    if retry_on_length and not length_retried and self._is_length_truncation(exc):
+                        length_retried = True
+                        last_length_error = exc
+                        payload = self._expand_length_budget(payload)
+                        continue
+                    raise
+                if (
+                    retry_on_length
+                    and not length_retried
+                    and parsed.finish_reason in _LENGTH_FINISH_REASONS
+                ):
+                    # 有内容但被 length 截断（结构化输出必然残缺），同样扩容重发一次。
+                    length_retried = True
+                    payload = self._expand_length_budget(payload)
+                    continue
+                return parsed
+        if last_length_error is not None:
+            raise last_length_error
         raise AssertionError("unreachable")
 
+    @staticmethod
+    def _is_length_truncation(exc: StudioError) -> bool:
+        if exc.code != "MODEL_EMPTY_RESPONSE":
+            return False
+        return str(exc.details.get("finishReason") or "") in _LENGTH_FINISH_REASONS
+
+    @staticmethod
+    def _expand_length_budget(payload: dict[str, Any]) -> dict[str, Any]:
+        key = "max_output_tokens" if "max_output_tokens" in payload else "max_tokens"
+        current = int(payload.get(key) or 0)
+        payload[key] = max(current, _LENGTH_RETRY_TARGET_TOKENS)
+        return payload
+
     @staticmethod
     def _responses_payload(
         model: ResolvedModel,
@@ -420,8 +505,9 @@ class OpenAICompatibleModelClient:
         payload: dict[str, Any] = {
             "model": model.model,
             "input": items,
-            "max_output_tokens": model.parameters.max_tokens,
         }
+        if model.parameters.max_tokens is not None:
+            payload["max_output_tokens"] = model.parameters.max_tokens
         if instructions:
             payload["instructions"] = "\n\n".join(instructions)
         return payload
@@ -460,7 +546,7 @@ class OpenAICompatibleModelClient:
                 "MODEL_EMPTY_RESPONSE",
                 "模型未返回可用内容",
                 status_code=502,
-                details={"status": status},
+                details={"status": status, "finishReason": status},
             )
         raw_usage = payload.get("usage") or {}
         usage = Usage(

ksadk/studio/model_profile_service.py

@@ -32,7 +32,7 @@ async def test_model_profile_connection(
     resolved.parameters = resolved.parameters.model_copy(
         update={
             "temperature": 0,
-            "max_tokens": min(resolved.parameters.max_tokens, 64),
+            "max_tokens": min(resolved.parameters.max_tokens or 2048, 64),
         }
     )
     host = (urlparse(resolved.endpoint_url).hostname or "").lower().rstrip(".")