create-windy 0.2.19 → 0.2.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-windy",
-  "version": "0.2.19",
+  "version": "0.2.21",
   "description": "创建单组织、单租户、私有部署优先的 Windy 企业 Dashboard Starter",
   "type": "module",
   "bin": {

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "7b28912bcf1a776aa3328e0ea36c014cd494461f",
-  "generatorVersion": "0.2.19",
+  "templateCommit": "3b9b26fdc1160543df838b4d198a36c6ac3308d0",
+  "generatorVersion": "0.2.21",
   "modules": [
     {
       "name": "system",

package/template/README.md

@@ -52,6 +52,7 @@ bun run dev:server
 以终端输出为准。`dev:server` 不会自动启动 PostgreSQL 或执行 migration；未配置
 `DATABASE_URL` 时使用内存模式。
 
+
 ## 页面与登录
 
 全新数据库的初始平台账号为 `admin`。初始密码不是所有项目共用的固定值，而是

package/template/apps/agent-server/Dockerfile

@@ -0,0 +1,20 @@
+# syntax=docker/dockerfile:1
+
+FROM python:3.12-slim AS runtime
+WORKDIR /app/apps/agent-server
+
+RUN pip install --no-cache-dir uv==0.9.27 \
+  && useradd --create-home --uid 10001 windy
+COPY apps/agent-server/pyproject.toml apps/agent-server/uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project
+COPY apps/agent-server/src ./src
+RUN uv sync --frozen --no-dev
+
+ENV PATH="/app/apps/agent-server/.venv/bin:${PATH}"
+ENV PYTHONUNBUFFERED=1
+EXPOSE 8080
+RUN mkdir -p /app/data/agent && chown -R windy:windy /app/data
+USER windy
+HEALTHCHECK --interval=15s --timeout=5s --start-period=10s --retries=4 \
+  CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=3)"]
+CMD ["uvicorn", "southwind_agent_server.app:app", "--host", "0.0.0.0", "--port", "8080"]

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

@@ -0,0 +1,46 @@
+# Southwind AI Agent Server
+
+Python 3.12 Agent Runtime。HTTP 层只公开 Southwind AI canonical Agent
+contracts。当前可用 Adapter 连接 OpenAI-compatible `/chat/completions`；Google ADK
+仍只是未配置 Provider 时安全拒绝的内部 Adapter。
+
+```bash
+uv sync --frozen
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+```
+
+HTTP Interface：
+
+- `POST /api/agent/runs`
+- `GET /api/agent/runs/:runId/events`
+- `GET /api/agent/runs/:runId/result`
+- `POST /api/agent/runs/:runId/cancel`
+
+Run 创建使用 `Idempotency-Key`。事件以 SSE 传输，支持 `Last-Event-ID` 和 `after`
+断线重放，并周期发送 comment heartbeat。Provider 或框架异常只会映射为 canonical
+安全错误，不会把原始异常正文暴露给调用方。
+
+配置以下仅服务端可见的环境变量后，默认运行 OpenAI-compatible Adapter：
+
+```bash
+export AGENT_SERVER_INTERNAL_TOKEN='<random-token>'
+export QWEN_API_URL='https://dashscope-intl.aliyuncs.com/compatible-mode/v1'
+export QWEN_API_KEY='<server-secret>'
+export QWEN_MODEL='qwen-plus'
+export AGENT_RUN_STORE_PATH='.data/agent-runs.sqlite3'
+uv run uvicorn southwind_agent_server.app:app
+```
+
+公网 URL 必须使用 HTTPS，本机、容器服务名和内网地址允许 HTTP。Provider 请求包含连接
+和总超时、响应大小限制、错误脱敏与 `/models` readiness。缺少 URL/Model 时回退
+`AdkEngineAdapter` 并返回 unavailable，不调用模型。测试另使用
+`DeterministicEngineAdapter`。
+
+未设置 `AGENT_RUN_STORE_PATH` 时使用的 `InMemoryRunStore` **仅用于 deterministic
+测试**。配置路径后使用有界 SQLite Store，可在单副本重启后保留 Run/Event/Result 和
+cursor；多副本部署仍必须替换为共享 Store。Execution Grant 与 Tool 授权由
+Southwind AI Server 签发和复核，Agent Server 不能自行扩大 Operation 的
+`allowedToolKeys`。

package/template/apps/agent-server/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "southwind-agent-server"
+version = "0.1.0"
+description = "Southwind AI canonical Agent Runtime server"
+requires-python = ">=3.12,<3.13"
+dependencies = [
+  "fastapi==0.139.2",
+  "google-adk==2.5.0",
+  "httpx==0.28.1",
+  "pydantic==2.13.4",
+  "uvicorn==0.51.0",
+]
+
+[dependency-groups]
+dev = [
+  "mypy==2.3.0",
+  "pytest==9.1.1",
+  "pytest-asyncio==1.4.0",
+  "ruff==0.15.22",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src", "tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/southwind_agent_server"]

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

@@ -0,0 +1,5 @@
+"""Southwind AI Agent Server."""
+
+from .app import create_app
+
+__all__ = ["create_app"]

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

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Mapping
+
+from .engine import (
+    AgentEngineAdapter,
+    EngineRunRequest,
+    EngineSignal,
+    SafeEngineError,
+)
+
+
+class AdkEngineAdapter(AgentEngineAdapter):
+    """Google ADK implementation skeleton.
+
+    Agent objects remain opaque and internal. A later slice will create ADK Runners,
+    consume ADK Events, and translate them into EngineSignal values at this seam.
+    """
+
+    def __init__(self, agents: Mapping[str, object] | None = None) -> None:
+        self._agents = dict(agents or {})
+
+    def supports(self, operation_key: str) -> bool:
+        return operation_key in self._agents
+
+    async def execute(
+        self,
+        request: EngineRunRequest,
+    ) -> AsyncIterator[EngineSignal]:
+        del request
+        raise SafeEngineError(
+            "RUNTIME_UNAVAILABLE",
+            "Agent Runtime 尚未配置",
+            retryable=True,
+        )
+        yield  # pragma: no cover - keeps this method an async generator
+
+    async def cancel(self, run_id: str) -> None:
+        del run_id

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

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import hmac
+import os
+import uuid
+from typing import Annotated
+
+from fastapi import FastAPI, Header, Query, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse, StreamingResponse
+from pydantic import ValidationError
+
+from .adk_adapter import AdkEngineAdapter
+from .config import EnvironmentSecretResolver, OpenAiCompatibleConfig
+from .contracts import (
+    AgentError,
+    CancelRunRequest,
+    CancelRunResponse,
+    RunResultResponse,
+    StartRunRequest,
+    StartRunResponse,
+)
+from .engine import AgentEngineAdapter
+from .openai_engine import OpenAiCompatibleEngineAdapter
+from .openai_provider import OpenAiCompatibleProvider
+from .service import (
+    AgentRunService,
+    IdempotencyConflictError,
+    OperationNotFoundError,
+    RunNotFoundError,
+)
+from .sqlite_store import RunStoreCapacityError, SqliteRunStore
+from .sse import event_stream
+from .store import InMemoryRunStore, RunStore
+from .tool_host import ToolHostClient
+
+
+def create_app(
+    engine: AgentEngineAdapter | None = None,
+    *,
+    heartbeat_seconds: float = 15.0,
+    internal_token: str | None = None,
+    store: RunStore | None = None,
+) -> FastAPI:
+    runtime_engine = engine or default_engine()
+    runtime = AgentRunService(runtime_engine, store or default_store())
+    application = FastAPI(title="Southwind AI Agent Server", version="0.1.0")
+
+    @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, str] | JSONResponse:
+        health = getattr(runtime_engine, "health", None)
+        if not health:
+            return safe_error(
+                503,
+                "RUNTIME_UNAVAILABLE",
+                "Agent Runtime 尚未配置",
+                True,
+            )
+        try:
+            await health()
+            return {"status": "ready"}
+        except Exception:
+            return safe_error(
+                503,
+                "PROVIDER_UNAVAILABLE",
+                "模型服务暂不可用",
+                True,
+            )
+
+    @application.exception_handler(OperationNotFoundError)
+    async def operation_not_found(
+        _request: Request,
+        _error: OperationNotFoundError,
+    ) -> JSONResponse:
+        return safe_error(404, "OPERATION_NOT_FOUND", "Agent Operation 不存在", False)
+
+    @application.exception_handler(RunNotFoundError)
+    async def run_not_found(
+        _request: Request,
+        _error: RunNotFoundError,
+    ) -> JSONResponse:
+        return safe_error(404, "RUN_CONFLICT", "Agent Run 不存在", False)
+
+    @application.exception_handler(IdempotencyConflictError)
+    async def idempotency_conflict(
+        _request: Request,
+        _error: IdempotencyConflictError,
+    ) -> JSONResponse:
+        return safe_error(409, "RUN_CONFLICT", "幂等键已用于其他请求", False)
+
+    @application.exception_handler(RunStoreCapacityError)
+    async def run_store_capacity(
+        _request: Request,
+        _error: RunStoreCapacityError,
+    ) -> JSONResponse:
+        return safe_error(
+            429,
+            "BUDGET_EXCEEDED",
+            "Agent Run 存储容量已满",
+            True,
+        )
+
+    @application.exception_handler(ValidationError)
+    async def validation_error(
+        _request: Request,
+        _error: ValidationError,
+    ) -> JSONResponse:
+        return safe_error(400, "INVALID_INPUT", "请求格式无效", False)
+
+    @application.exception_handler(RequestValidationError)
+    async def request_validation_error(
+        _request: Request,
+        _error: RequestValidationError,
+    ) -> JSONResponse:
+        return safe_error(400, "INVALID_INPUT", "请求格式无效", False)
+
+    @application.post("/api/agent/runs", response_model=StartRunResponse)
+    async def start_run(
+        request: StartRunRequest,
+        idempotency_key: Annotated[str, Header(alias="Idempotency-Key")],
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> StartRunResponse | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        if not idempotency_key.strip():
+            return safe_error(400, "INVALID_INPUT", "幂等键不能为空", False)
+        record = await runtime.start(
+            request,
+            idempotency_key,
+        )
+        return StartRunResponse(
+            run_id=record.run_id,
+            status=record.status,
+            events_url=f"/api/agent/runs/{record.run_id}/events",
+        )
+
+    @application.get("/api/agent/runs/{run_id}/events", response_model=None)
+    async def get_events(
+        run_id: str,
+        after: Annotated[int | None, Query(ge=0)] = None,
+        last_event_id: Annotated[str | None, Header(alias="Last-Event-ID")] = None,
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> StreamingResponse | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        await runtime.get(run_id)
+        try:
+            cursor = parse_cursor(after, last_event_id)
+        except ValueError:
+            return safe_error(400, "INVALID_INPUT", "事件游标无效", False)
+        return StreamingResponse(
+            event_stream(runtime, run_id, cursor, heartbeat_seconds),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache, no-transform",
+                "X-Accel-Buffering": "no",
+            },
+        )
+
+    @application.get(
+        "/api/agent/runs/{run_id}/result",
+        response_model=RunResultResponse,
+    )
+    async def get_result(
+        run_id: str,
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> RunResultResponse | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        record = await runtime.get(run_id)
+        if record.status == "completed":
+            return RunResultResponse(
+                run_id=record.run_id,
+                status="completed",
+                output=record.output,
+            )
+        if record.status == "cancelled":
+            return safe_error(409, "RUN_CANCELLED", "Agent Run 已取消", False)
+        if record.status == "failed":
+            return safe_error(409, "RUNTIME_UNAVAILABLE", "Agent Run 执行失败", True)
+        return safe_error(409, "RUN_CONFLICT", "Agent Run 尚未完成", True)
+
+    @application.post(
+        "/api/agent/runs/{run_id}/cancel",
+        response_model=CancelRunResponse,
+    )
+    async def cancel_run(
+        run_id: str,
+        _request: CancelRunRequest,
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> CancelRunResponse | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        record = await runtime.cancel(run_id)
+        return CancelRunResponse(run_id=record.run_id, status=record.status)
+
+    application.state.run_service = runtime
+    return application
+
+
+def default_engine() -> AgentEngineAdapter:
+    config = OpenAiCompatibleConfig.from_environment()
+    if config is None:
+        return AdkEngineAdapter()
+    internal_token = os.environ.get("AGENT_SERVER_INTERNAL_TOKEN", "").strip()
+    if not internal_token:
+        raise ValueError("Agent Server Provider 已配置但内部 Token 缺失")
+    return OpenAiCompatibleEngineAdapter(
+        OpenAiCompatibleProvider(
+            config,
+            EnvironmentSecretResolver(os.environ),
+        ),
+        ToolHostClient(internal_token),
+    )
+
+
+def default_store() -> RunStore:
+    path = os.environ.get("AGENT_RUN_STORE_PATH", "").strip()
+    return SqliteRunStore(path) if path else InMemoryRunStore()
+
+
+def authorized(provided: str | None, expected: str | None) -> bool:
+    if expected is None:
+        return True
+    if not expected or not provided or not provided.startswith("Bearer "):
+        return False
+    return hmac.compare_digest(provided.removeprefix("Bearer "), expected)
+
+
+def parse_cursor(after: int | None, last_event_id: str | None) -> int:
+    header_cursor = 0
+    if last_event_id is not None:
+        if not last_event_id.isdigit():
+            raise ValueError
+        header_cursor = int(last_event_id)
+    return max(after or 0, header_cursor)
+
+
+def safe_error(
+    status_code: int,
+    code: str,
+    message: str,
+    retryable: bool,
+) -> JSONResponse:
+    error = AgentError.model_validate(
+        {
+            "code": code,
+            "message": message,
+            "requestId": f"request_{uuid.uuid4().hex}",
+            "retryable": retryable,
+        }
+    )
+    return JSONResponse(
+        status_code=status_code,
+        content=error.model_dump(by_alias=True),
+    )
+
+
+app = create_app(internal_token=os.environ.get("AGENT_SERVER_INTERNAL_TOKEN"))

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

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import ipaddress
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from urllib.parse import urlsplit, urlunsplit
+
+
+@dataclass(frozen=True)
+class SecretRef:
+    provider: str
+    locator: str
+
+    def __str__(self) -> str:
+        return "[SecretRef]"
+
+
+class EnvironmentSecretResolver:
+    def __init__(self, environment: Mapping[str, str]) -> None:
+        self._environment = environment
+
+    def resolve(self, ref: SecretRef) -> str | None:
+        if ref.provider != "env":
+            raise ValueError("Secret Provider 不匹配")
+        return self._environment.get(ref.locator)
+
+
+@dataclass(frozen=True)
+class OpenAiCompatibleConfig:
+    base_url: str
+    model: str
+    api_key_ref: SecretRef | None
+    connect_timeout_seconds: float = 5.0
+    request_timeout_seconds: float = 60.0
+    max_response_bytes: int = 2 * 1024 * 1024
+    max_tool_rounds: int = 8
+
+    @classmethod
+    def from_environment(
+        cls,
+        environment: Mapping[str, str] = os.environ,
+    ) -> OpenAiCompatibleConfig | None:
+        base_url = environment.get("QWEN_API_URL", "").strip()
+        model = environment.get("QWEN_MODEL", "").strip()
+        if not base_url and not model:
+            return None
+        if not base_url or not model:
+            raise ValueError("OpenAI-compatible Endpoint 与 Model 必须同时配置")
+        return cls(
+            base_url=normalize_base_url(base_url),
+            model=model,
+            api_key_ref=(
+                SecretRef("env", "QWEN_API_KEY")
+                if environment.get("QWEN_API_KEY", "").strip()
+                else None
+            ),
+            connect_timeout_seconds=read_milliseconds(
+                environment,
+                "AI_PROVIDER_CONNECT_TIMEOUT_MS",
+                5_000,
+                100,
+                30_000,
+            )
+            / 1_000,
+            request_timeout_seconds=read_milliseconds(
+                environment,
+                "AI_PROVIDER_REQUEST_TIMEOUT_MS",
+                60_000,
+                1_000,
+                300_000,
+            )
+            / 1_000,
+            max_response_bytes=read_integer(
+                environment,
+                "AI_PROVIDER_MAX_RESPONSE_BYTES",
+                2 * 1024 * 1024,
+                1_024,
+                16 * 1024 * 1024,
+            ),
+        )
+
+
+def normalize_base_url(raw: str) -> str:
+    parsed = urlsplit(raw.strip())
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        raise ValueError("OpenAI-compatible Endpoint 无效")
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise ValueError("OpenAI-compatible Endpoint 不允许凭据、查询串或片段")
+    hostname = parsed.hostname.lower()
+    if hostname in {
+        "169.254.169.254",
+        "metadata.google.internal",
+        "metadata.azure.internal",
+    }:
+        raise ValueError("OpenAI-compatible Endpoint 禁止访问云 metadata")
+    if parsed.scheme == "http" and not private_hostname(hostname):
+        raise ValueError("公网 OpenAI-compatible Endpoint 必须使用 HTTPS")
+    path = parsed.path.rstrip("/")
+    return urlunsplit((parsed.scheme, parsed.netloc, path, "", ""))
+
+
+def private_hostname(hostname: str) -> bool:
+    if (
+        hostname == "localhost"
+        or hostname.endswith((".localhost", ".internal", ".local"))
+        or "." not in hostname
+    ):
+        return True
+    try:
+        address = ipaddress.ip_address(hostname)
+    except ValueError:
+        return False
+    return address.is_private or address.is_loopback
+
+
+def read_milliseconds(
+    environment: Mapping[str, str],
+    key: str,
+    default: int,
+    minimum: int,
+    maximum: int,
+) -> int:
+    return read_integer(environment, key, default, minimum, maximum)
+
+
+def read_integer(
+    environment: Mapping[str, str],
+    key: str,
+    default: int,
+    minimum: int,
+    maximum: int,
+) -> int:
+    raw = environment.get(key)
+    try:
+        value = default if raw is None else int(raw)
+    except ValueError as error:
+        raise ValueError(f"{key} 必须是整数") from error
+    if not minimum <= value <= maximum:
+        raise ValueError(f"{key} 超出允许范围")
+    return value

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

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+type JsonValue = (
+    str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]
+)
+type RunStatus = Literal[
+    "accepted",
+    "running",
+    "awaiting-approval",
+    "completed",
+    "failed",
+    "cancelled",
+]
+type AgentErrorCode = Literal[
+    "OPERATION_NOT_FOUND",
+    "OPERATION_DISABLED",
+    "INVALID_INPUT",
+    "FORBIDDEN",
+    "LICENSE_NOT_ALLOWED",
+    "RUNTIME_UNAVAILABLE",
+    "MODEL_ROUTE_UNAVAILABLE",
+    "PROVIDER_UNAVAILABLE",
+    "RATE_LIMITED",
+    "BUDGET_EXCEEDED",
+    "TOOL_DENIED",
+    "APPROVAL_REQUIRED",
+    "OUTPUT_VALIDATION_FAILED",
+    "RUN_CONFLICT",
+    "RUN_TIMEOUT",
+    "RUN_CANCELLED",
+    "STREAM_INTERRUPTED",
+]
+
+
+def to_camel(value: str) -> str:
+    first, *rest = value.split("_")
+    return first + "".join(part.capitalize() for part in rest)
+
+
+class CanonicalModel(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        extra="forbid",
+    )
+
+
+class RuntimeToolDefinition(CanonicalModel):
+    key: str = Field(min_length=1)
+    label: str = Field(min_length=1)
+    description: str = Field(min_length=1)
+
+
+class RuntimeLimits(CanonicalModel):
+    max_duration_seconds: int = Field(default=60, ge=1, le=300)
+    max_output_bytes: int = Field(default=1_048_576, ge=1_024, le=16_777_216)
+
+
+class StartRunRequest(CanonicalModel):
+    operation_key: str = Field(min_length=1)
+    input: JsonValue
+    instructions: str = ""
+    user_prompt: str = ""
+    allowed_tools: list[RuntimeToolDefinition] = Field(default_factory=list)
+    limits: RuntimeLimits = Field(default_factory=RuntimeLimits)
+    execution_grant: str = ""
+    tool_host_url: str = ""
+
+
+class StartRunResponse(CanonicalModel):
+    run_id: str
+    status: RunStatus
+    events_url: str
+
+
+class RunResultResponse(CanonicalModel):
+    run_id: str
+    status: Literal["completed"]
+    output: JsonValue
+
+
+class CancelRunRequest(CanonicalModel):
+    reason: str | None = None
+
+
+class CancelRunResponse(CanonicalModel):
+    run_id: str
+    status: RunStatus
+
+
+class AgentError(CanonicalModel):
+    code: AgentErrorCode
+    message: str
+    request_id: str
+    retryable: bool