create-windy 0.5.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-windy",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "创建单组织、单租户、私有部署优先的 Windy 企业 Dashboard Starter",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
   ],
   "scripts": {
     "build": "bun build src/cli.ts --target=bun --format=esm --outdir=dist",
+    "regression:update-candidate": "bun run src/candidate-update-regression.ts",
     "template:sync": "bun run src/sync-template.ts",
     "prepack": "bun run template:sync && bun run build",
     "postpack": "bun run src/clean-template.ts",

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "25b98ed98562c416c6dcfe48940cd0cae43252d4",
-  "generatorVersion": "0.5.1",
+  "templateCommit": "6149af754e862b43ca2fe344c354dcb07149bbc2",
+  "generatorVersion": "0.6.0",
   "modules": [
     {
       "name": "system",

package/template/apps/agent-server/README.md

@@ -1,9 +1,9 @@
 # Southwind AI Agent Server
 
-Python 3.12 Agent Runtime。HTTP 层只公开 Southwind AI canonical Agent
-contracts。真实业务 Run 在内部通过 Google ADK 2.5 的 Runner、Session、LlmAgent 和
-Event 执行；ADK 类型不会越过 `AgentEngineAdapter`。模型调用继续复用受治理的
-OpenAI-compatible `/chat/completions` Provider。
+Python 3.12 Agent 运行时。HTTP 层只公开 Southwind AI 的 canonical Agent 契约；真实业务
+Run 在内部通过 Google ADK 2.5 的 Runner、Session、LlmAgent 和 Event 执行，ADK 类型不会
+越过 `AgentEngineAdapter`。模型调用继续复用受治理的 OpenAI-compatible
+`/chat/completions` Provider。
 
 ```bash
 uv sync --frozen
@@ -13,7 +13,7 @@ uv run ruff format --check .
 uv run mypy
 ```
 
-HTTP Interface：
+HTTP 接口：
 
 - `POST /api/agent/runs`
 - `GET /api/agent/runs/:runId/events`
@@ -40,8 +40,27 @@ export AI_PROVIDER_AUDIT_RETENTION_DAYS='90'
 uv run uvicorn southwind_agent_server.app:app
 ```
 
+VLM Operation readiness 比 Endpoint 可达性更严格。必须固定 Deployment 事实并声明
+图片 offer；否则 `/health/vlm-ready` 返回 V1 `unavailable` snapshot，视觉 Operation 保持
+关闭：
+
+```bash
+export AI_PROVIDER_CAPABILITIES='text-generation,vision'
+export AI_PROVIDER_INPUT_MODALITIES='text,image'
+export AI_PROVIDER_DEPLOYMENT_IDENTITY='windy-deployment-v1_<uuid-v4>'
+export AI_PROVIDER_RELEASE_DIGEST='sha256:<64-lowercase-hex>'
+export AI_PROVIDER_READINESS_TTL_SECONDS='60'
+export AI_PROVIDER_MAX_CONCURRENT_RUNS='1'
+export AI_PROVIDER_MAX_QUEUE_DEPTH='0'
+```
+
+Readiness 请求用固定的一像素合成图片调用已配置的 `/chat/completions`，并要求有界
+结构化结果。它不会调用 `/models`，不会读取客户截图，也不会把用户 Artifact、URL、Run
+ID、Prompt 或 Provider 输出放进 health payload。`offersDigest` 始终按公开 V1 算法由
+实际 offer 计算，不能由环境变量伪造。
+
 公网 URL 必须使用 HTTPS 且 Host 精确命中 allowlist；本机、容器服务名和内网地址允许
-HTTP。Provider 请求包含连接和总超时、响应大小限制、错误脱敏与 `/models`
+HTTP。Provider 请求包含连接和总超时、响应大小限制、错误脱敏与 VLM 合成图片
 readiness。缺少 URL/Model 时回退
 未配置的 `AdkEngineAdapter` 并返回 unavailable，不调用模型。测试另使用
 `DeterministicEngineAdapter`。每个 ADK Tool 只声明 Operation 已允许的 Key；其执行

package/template/apps/agent-server/src/southwind_agent_server/adk_adapter.py

@@ -32,6 +32,7 @@ from .provider_governance import ProviderRequestGovernance
 from .report_store import AgentRuntimeReportStore
 from .report_types import CacheStatus, UsageFacts, UsageSource
 from .tool_host import ToolHostClient, canonical_tool_call_id
+from .vlm_readiness import VlmReadinessProbe, unavailable_vlm_snapshot
 
 
 class AdkEngineAdapter(AgentEngineAdapter):
@@ -58,6 +59,14 @@ class AdkEngineAdapter(AgentEngineAdapter):
     def input_modalities(self) -> tuple[str, ...]:
         return self._provider.config.input_modalities if self._provider else ()
 
+    @property
+    def max_concurrent_runs(self) -> int:
+        return self._provider.config.max_concurrent_runs if self._provider else 1
+
+    @property
+    def max_queue_depth(self) -> int:
+        return self._provider.config.max_queue_depth if self._provider else 0
+
     def supports(self, operation_key: str) -> bool:
         return bool(operation_key.strip())
 
@@ -183,8 +192,12 @@ class AdkEngineAdapter(AgentEngineAdapter):
             cancellation.set()
 
     async def health(self) -> None:
-        provider, _, _ = self._configured()
-        await provider.health()
+        self._configured()
+
+    async def readiness(self) -> dict[str, object]:
+        if not self._provider:
+            return unavailable_vlm_snapshot(configured=False)
+        return await VlmReadinessProbe(self._provider.config, self._provider).inspect()
 
     def governance_health(self) -> dict[str, int | float | str | None]:
         _, _, governance = self._configured()

package/template/apps/agent-server/src/southwind_agent_server/app.py

@@ -23,6 +23,8 @@ from .contracts import (
     StartRunResponse,
 )
 from .engine import AgentEngineAdapter, SafeEngineError
+from .engine_capacity import engine_capacity
+from .health_routes import install_health_routes
 from .http_helpers import (
     authorized,
     parse_cursor,
@@ -36,15 +38,13 @@ from .runtime_factory import (
     default_report_store,
     default_store,
 )
-from .service import (
-    AgentRunService,
-    OperationNotFoundError,
-    RunNotFoundError,
-)
+from .service import AgentRunService
+from .service_errors import OperationNotFoundError, RunNotFoundError
 from .sqlite_store import RunStoreCapacityError
 from .sse import event_stream
 from .store import IdempotencyConflictError, ReleaseNotFoundError, RunStore
 from .telemetry import configure_telemetry
+from .vision_requirement import require_vision_readiness
 
 
 def create_app(
@@ -58,6 +58,7 @@ def create_app(
     configure_telemetry()
     runtime_report_store = report_store or default_report_store()
     runtime_engine = engine or default_engine(runtime_report_store)
+    capacity = engine_capacity(runtime_engine)
     runtime = AgentRunService(
         runtime_engine,
         store or default_store(),
@@ -73,6 +74,8 @@ def create_app(
             if internal_token
             else None
         ),
+        max_concurrent_runs=capacity.max_concurrent_runs,
+        max_queue_depth=capacity.max_queue_depth,
     )
 
     @asynccontextmanager
@@ -92,35 +95,7 @@ def create_app(
         create_report_router(runtime_report_store, internal_token)
     )
 
-    @application.get("/health/live")
-    async def live() -> dict[str, str]:
-        return {"status": "live"}
-
-    @application.get("/health/ready", response_model=None)
-    async def ready() -> dict[str, object] | JSONResponse:
-        health = getattr(runtime_engine, "health", None)
-        if not health:
-            return safe_error(
-                503,
-                "RUNTIME_UNAVAILABLE",
-                "Agent Runtime 尚未配置",
-                True,
-            )
-        try:
-            await runtime.probe()
-            await health()
-            return {
-                "status": "ready",
-                "capabilities": list(runtime_engine.capabilities),
-                "inputModalities": list(runtime_engine.input_modalities),
-            }
-        except Exception:
-            return safe_error(
-                503,
-                "PROVIDER_UNAVAILABLE",
-                "模型服务暂不可用",
-                True,
-            )
+    install_health_routes(application, runtime, runtime_engine)
 
     @application.get("/health/provider-governance", response_model=None)
     async def provider_governance_health(
@@ -219,6 +194,10 @@ def create_app(
             return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
         if not idempotency_key.strip():
             return safe_error(400, "INVALID_INPUT", "幂等键不能为空", False)
+        try:
+            await require_vision_readiness(runtime_engine, request)
+        except SafeEngineError as error:
+            return safe_error(503, error.code, error.safe_message, error.retryable)
         record = await runtime.start(
             request,
             idempotency_key,

package/template/apps/agent-server/src/southwind_agent_server/config.py

@@ -35,11 +35,20 @@ class OpenAiCompatibleConfig:
     connect_timeout_seconds: float = 5.0
     request_timeout_seconds: float = 60.0
     max_response_bytes: int = 2 * 1024 * 1024
+    max_duration_seconds: int = 300
+    max_input_bytes: int = 67_108_864
+    max_artifacts: int = 16
+    max_pixels_per_artifact: int = 100_000_000
     max_tool_rounds: int = 8
     https_host_allowlist: tuple[str, ...] = ()
     deployment_key: str = "ai.openai-compatible"
     capabilities: tuple[str, ...] = ("text-generation",)
     input_modalities: tuple[str, ...] = ("text",)
+    readiness_deployment_identity: str | None = None
+    readiness_release_digest: str | None = None
+    readiness_ttl_seconds: int = 60
+    max_concurrent_runs: int = 1
+    max_queue_depth: int = 0
 
     def __post_init__(self) -> None:
         normalized = normalize_base_url(self.base_url)
@@ -91,6 +100,26 @@ class OpenAiCompatibleConfig:
                 1_024,
                 16 * 1024 * 1024,
             ),
+            max_duration_seconds=read_integer(
+                environment, "AI_PROVIDER_MAX_DURATION_SECONDS", 300, 1, 300
+            ),
+            max_input_bytes=read_integer(
+                environment,
+                "AI_PROVIDER_MAX_INPUT_BYTES",
+                67_108_864,
+                1_024,
+                67_108_864,
+            ),
+            max_artifacts=read_integer(
+                environment, "AI_PROVIDER_MAX_ARTIFACTS", 16, 1, 16
+            ),
+            max_pixels_per_artifact=read_integer(
+                environment,
+                "AI_PROVIDER_MAX_PIXELS_PER_ARTIFACT",
+                100_000_000,
+                1,
+                100_000_000,
+            ),
             capabilities=read_csv(
                 environment,
                 "AI_PROVIDER_CAPABILITIES",
@@ -101,6 +130,21 @@ class OpenAiCompatibleConfig:
                 "AI_PROVIDER_INPUT_MODALITIES",
                 ("text",),
             ),
+            readiness_deployment_identity=optional_value(
+                environment, "AI_PROVIDER_DEPLOYMENT_IDENTITY"
+            ),
+            readiness_release_digest=optional_value(
+                environment, "AI_PROVIDER_RELEASE_DIGEST"
+            ),
+            readiness_ttl_seconds=read_integer(
+                environment, "AI_PROVIDER_READINESS_TTL_SECONDS", 60, 1, 300
+            ),
+            max_concurrent_runs=read_integer(
+                environment, "AI_PROVIDER_MAX_CONCURRENT_RUNS", 1, 1, 1_000
+            ),
+            max_queue_depth=read_integer(
+                environment, "AI_PROVIDER_MAX_QUEUE_DEPTH", 0, 0, 10_000
+            ),
         )
 
 
@@ -216,3 +260,8 @@ def read_csv(
     if not values or len(values) > 32:
         raise ValueError(f"{key} 无效")
     return values
+
+
+def optional_value(environment: Mapping[str, str], key: str) -> str | None:
+    value = environment.get(key, "").strip()
+    return value or None

package/template/apps/agent-server/src/southwind_agent_server/contracts.py

@@ -139,6 +139,18 @@ class RuntimeRelease(CanonicalModel):
     manifest_digest: str = Field(pattern=r"^[a-f0-9]{64}$")
 
 
+class VlmReadinessPin(CanonicalModel):
+    key: str = Field(min_length=1, max_length=160)
+    identity: str = Field(
+        pattern=(
+            r"^windy-deployment-v1_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-"
+            r"[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+        )
+    )
+    release_digest: str = Field(pattern=r"^sha256:[a-f0-9]{64}$")
+    offers_digest: str = Field(pattern=r"^sha256:[a-f0-9]{64}$")
+
+
 class RunReportingContext(CanonicalModel):
     """Trusted platform metadata for reporting, never an authorization fact."""
 
@@ -180,6 +192,7 @@ class StartRunRequest(CanonicalModel):
     tool_network_policy: ToolNetworkPolicy = Field(default_factory=ToolNetworkPolicy)
     execution_grant: str = ""
     tool_host_url: str = ""
+    readiness_pin: VlmReadinessPin | None = None
     release: RuntimeRelease = Field(default_factory=legacy_release)
     trace_id: str = Field(default="", max_length=160)
     reporting: RunReportingContext | None = None

package/template/apps/agent-server/src/southwind_agent_server/engine_capacity.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+from .engine import AgentEngineAdapter
+
+
+@dataclass(frozen=True)
+class EngineCapacity:
+    max_concurrent_runs: int
+    max_queue_depth: int
+
+
+@runtime_checkable
+class ResourceLimitedEngine(Protocol):
+    @property
+    def max_concurrent_runs(self) -> int: ...
+
+    @property
+    def max_queue_depth(self) -> int: ...
+
+
+def engine_capacity(engine: AgentEngineAdapter) -> EngineCapacity:
+    if not isinstance(engine, ResourceLimitedEngine):
+        return EngineCapacity(1, 0)
+    concurrent = engine.max_concurrent_runs
+    queued = engine.max_queue_depth
+    if concurrent < 1 or queued < 0:
+        raise ValueError("Agent Engine 容量声明无效")
+    return EngineCapacity(concurrent, queued)

package/template/apps/agent-server/src/southwind_agent_server/fingerprint.py

@@ -33,6 +33,11 @@ def request_fingerprint(request: StartRunRequest) -> str:
             "outputSchemaKey": request.output_schema_key,
             "outputSchema": request.output_schema,
             "release": resolved_release(request),
+            "readinessPin": (
+                request.readiness_pin.model_dump(by_alias=True)
+                if request.readiness_pin
+                else None
+            ),
         },
         ensure_ascii=False,
         separators=(",", ":"),

package/template/apps/agent-server/src/southwind_agent_server/health_routes.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+
+from .http_helpers import safe_error
+from .service import AgentRunService
+from .vlm_readiness import unavailable_vlm_snapshot
+
+
+def install_health_routes(
+    application: FastAPI, runtime: AgentRunService, engine: object
+) -> None:
+    @application.get("/health/live")
+    async def live() -> dict[str, str]:
+        return {"status": "live"}
+
+    @application.get("/health/ready", response_model=None)
+    async def ready() -> dict[str, object] | JSONResponse:
+        try:
+            await runtime.probe()
+            return {"status": "ready"}
+        except Exception:
+            return safe_error(
+                503,
+                "RUNTIME_UNAVAILABLE",
+                "Agent Run 存储暂不可用",
+                True,
+            )
+
+    @application.get("/health/vlm-ready", response_model=None)
+    async def vlm_ready() -> dict[str, object] | JSONResponse:
+        readiness = getattr(engine, "readiness", None)
+        if not readiness:
+            return JSONResponse(
+                unavailable_vlm_snapshot(configured=False), status_code=503
+            )
+        try:
+            await runtime.probe()
+            snapshot = await readiness()
+            status = 200 if snapshot.get("status") == "ready" else 503
+            return JSONResponse(snapshot, status_code=status)
+        except Exception:
+            return JSONResponse(
+                unavailable_vlm_snapshot(
+                    configured=True,
+                    failure_code="CONNECTION_FAILED",
+                ),
+                status_code=503,
+            )

package/template/apps/agent-server/src/southwind_agent_server/openai_engine.py

@@ -49,6 +49,7 @@ from .tool_host import (
     ToolInvocation,
     canonical_tool_call_id,
 )
+from .vlm_readiness import VlmReadinessProbe
 
 
 class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
@@ -73,6 +74,14 @@ class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
     def input_modalities(self) -> tuple[str, ...]:
         return self._provider.config.input_modalities
 
+    @property
+    def max_concurrent_runs(self) -> int:
+        return self._provider.config.max_concurrent_runs
+
+    @property
+    def max_queue_depth(self) -> int:
+        return self._provider.config.max_queue_depth
+
     def supports(self, operation_key: str) -> bool:
         return bool(operation_key.strip())
 
@@ -293,8 +302,8 @@ class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
         if event is not None:
             event.set()
 
-    async def health(self) -> None:
-        await self._provider.health()
+    async def readiness(self) -> dict[str, object]:
+        return await VlmReadinessProbe(self._provider.config, self._provider).inspect()
 
     def governance_health(self) -> dict[str, int | float | str | None]:
         return self._governance.health()

package/template/apps/agent-server/src/southwind_agent_server/openai_provider.py

@@ -15,6 +15,7 @@ from .contracts import AgentErrorCode, JsonValue, RuntimeToolDefinition
 from .engine import SafeEngineError
 from .multimodal import response_format
 from .report_types import UsageFacts
+from .vision_probe import probe_vision
 
 
 @dataclass
@@ -48,15 +49,8 @@ class OpenAiCompatibleProvider:
         self._resolver = resolver
         self._transport = transport
 
-    async def health(self) -> None:
-        async with self._client() as client:
-            try:
-                response = await client.get("/models")
-                await self._bounded_body(response)
-            except httpx.HTTPError as error:
-                raise provider_failure(error) from None
-        if not response.is_success:
-            raise provider_status_failure(response.status_code)
+    async def probe_vision(self) -> None:
+        await probe_vision(self)
 
     async def complete_turn(
         self,

package/template/apps/agent-server/src/southwind_agent_server/postgres_store.py

@@ -124,6 +124,11 @@ class PostgresRunStore:
         async with self._pool.connection() as connection:
             return await self._backend.read(connection, run_id)
 
+    async def get_by_idempotency(self, idempotency_key: str) -> RunRecord | None:
+        await self._backend.ready()
+        async with self._pool.connection() as connection:
+            return await self._backend.by_idempotency(connection, idempotency_key)
+
     async def append(
         self,
         run_id: str,

package/template/apps/agent-server/src/southwind_agent_server/readiness_pin.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class ReadinessEngine(Protocol):
+    async def readiness(self) -> dict[str, object]: ...
+
+
+async def readiness_pin_matches(engine: object, expected: dict[str, object]) -> bool:
+    readiness = getattr(engine, "readiness", None)
+    if not readiness:
+        return False
+    try:
+        snapshot = await readiness()
+    except Exception:
+        return False
+    deployment = snapshot.get("deployment") if isinstance(snapshot, dict) else None
+    probe = snapshot.get("downstreamProbe") if isinstance(snapshot, dict) else None
+    probe_names = {
+        "identity": "deploymentIdentity",
+        "releaseDigest": "releaseDigest",
+        "offersDigest": "offersDigest",
+    }
+    return bool(
+        isinstance(snapshot, dict)
+        and snapshot.get("status") == "ready"
+        and isinstance(deployment, dict)
+        and isinstance(probe, dict)
+        and probe.get("status") == "passed"
+        and all(deployment.get(key) == value for key, value in expected.items())
+        and all(
+            probe.get(probe_names[key]) == value
+            for key, value in expected.items()
+            if key in probe_names
+        )
+    )

package/template/apps/agent-server/src/southwind_agent_server/run_admission.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+
+from .contracts import JsonValue
+from .engine import SafeEngineError
+from .run_capacity import (
+    RunCapacity,
+    RunCapacityReservation,
+    RunCapacityUnavailable,
+)
+from .store import IdempotencyConflictError, RunRecord, RunStore
+
+
+@dataclass(frozen=True)
+class RunAdmissionResult:
+    record: RunRecord
+    reservation: RunCapacityReservation | None
+
+
+class RunAdmission:
+    def __init__(self, store: RunStore, capacity: RunCapacity) -> None:
+        self._store = store
+        self._capacity = capacity
+        self._lock = asyncio.Lock()
+
+    async def admit(
+        self,
+        candidate: RunRecord,
+        invocation: JsonValue,
+    ) -> RunAdmissionResult:
+        async with self._lock:
+            current = await self._store.get_by_idempotency(candidate.idempotency_key)
+            if current:
+                if current.fingerprint != candidate.fingerprint:
+                    raise IdempotencyConflictError
+                return RunAdmissionResult(current, None)
+            try:
+                reservation = await self._capacity.reserve()
+            except RunCapacityUnavailable:
+                raise SafeEngineError(
+                    "RUNTIME_UNAVAILABLE",
+                    "VLM Runtime 容量已满",
+                    retryable=True,
+                ) from None
+            try:
+                record, created = await self._store.create_or_get(
+                    candidate,
+                    invocation,
+                )
+            except Exception:
+                await reservation.release()
+                raise
+            if not created:
+                await reservation.release()
+                return RunAdmissionResult(record, None)
+            return RunAdmissionResult(record, reservation)
+
+    async def reserve_recovery(self) -> RunCapacityReservation | None:
+        try:
+            return await self._capacity.reserve()
+        except RunCapacityUnavailable:
+            return None

package/template/apps/agent-server/src/southwind_agent_server/run_capacity.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import asyncio
+
+
+class RunCapacityUnavailable(Exception):
+    pass
+
+
+class RunCapacity:
+    def __init__(self, max_concurrent_runs: int, max_queue_depth: int) -> None:
+        if max_concurrent_runs < 1 or max_queue_depth < 0:
+            raise ValueError("Agent Run 容量配置无效")
+        self._maximum = max_concurrent_runs
+        self._queue_maximum = max_queue_depth
+        self._active = 0
+        self._queued = 0
+        self._condition = asyncio.Condition()
+
+    async def reserve(self) -> RunCapacityReservation:
+        async with self._condition:
+            if self._active + self._queued >= self._maximum + self._queue_maximum:
+                raise RunCapacityUnavailable
+            self._queued += 1
+            return RunCapacityReservation(self)
+
+    async def enter(self, reservation: RunCapacityReservation) -> None:
+        async with self._condition:
+            while self._active >= self._maximum:
+                await self._condition.wait()
+            if reservation.released or reservation.entered:
+                raise RuntimeError("Agent Run 容量票据状态无效")
+            self._queued -= 1
+            self._active += 1
+            reservation.entered = True
+
+    async def release(self, reservation: RunCapacityReservation) -> None:
+        async with self._condition:
+            if reservation.released:
+                return
+            if reservation.entered:
+                self._active -= 1
+            else:
+                self._queued -= 1
+            reservation.released = True
+            self._condition.notify_all()
+
+
+class RunCapacityReservation:
+    def __init__(self, capacity: RunCapacity) -> None:
+        self._capacity = capacity
+        self.entered = False
+        self.released = False
+
+    async def enter(self) -> None:
+        await self._capacity.enter(self)
+
+    async def release(self) -> None:
+        await self._capacity.release(self)