create-windy 0.3.17 → 0.3.19

package/package.json

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

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "267cc4a82fec7fa39819029ce6e967f93b4f0463",
-  "generatorVersion": "0.3.17",
+  "templateCommit": "45fdbe8e2a55dff118933af58a60976e9bfe318c",
+  "generatorVersion": "0.3.19",
   "modules": [
     {
       "name": "system",

package/template/AGENTS.md

@@ -59,6 +59,10 @@
   `providerDataPolicy.inputFields` JSON Pointer allowlist 与
   `envelopeFields`；raw input 会在进入 `prepare` 前裁剪并执行 DLP。接入与升级
   诊断见 `docs/platform/agent-runtime.md`。
+- 开发期用 ADK Web 调试真实数据时，只在 project-owned 的
+  `apps/agent-server/project/adk-web-debug.json` 绑定满足文本契约的 Operation 与
+  当前启用的真实开发数据用户；Compose、权限收窄、Scope 复核、专用审计主体与
+  canonical Run bridge 由 Windy 基线提供。
 
 ## 常用入口
 
@@ -72,6 +76,8 @@
 - `bun run dev:build`：依赖、Dockerfile 或 lockfile 变化后重建并启动开发环境；Web 与 Server 并发复用 BuildKit Bun 下载缓存，冷安装会周期输出不含凭据的心跳。
 - `bun run dev:web`：启动 Web 开发服务。
 - `bun run dev:server`：启动 Server 开发服务。
+- `bun run dev:adk-web`：选择 Agent 模块后，一条命令启动真实 canonical Run
+  调试链；生产环境不提供该入口。
 - `bun run lint`、`bun run typecheck`、`bun run test`、`bun run build`：执行基础验证；未选择 Oxc 时没有 lint 脚本。
 - `docs/README.md`：平台架构、模块接入和运维文档入口。
 - `.windy/generation.json`：本次生成器版本、所选模块和选项记录。

package/template/README.md

@@ -150,24 +150,19 @@ bun run windy update --dry-run
 bun run windy module list
 bun run windy module add work-order --dry-run
 bun run windy module remove work-order --dry-run
-bun run windy reconcile --to <精确目标版本>
 bun run lint
 bun run format
 ```
 
 提交时 Husky 会通过 lint-staged 与 Oxfmt 格式化暂存文件，不会把未暂存内容带入提交。lint、typecheck 和 test 保留为需要时显式运行的命令。
 
-更新前必须保持 Git 工作区干净。`--dry-run` 只生成计划，不写项目；正式更新先备份，
-再做 package 字段级合并、共享脚手架三方合并与完整验证。任何冲突都会在写入前中止，
+更新前无需提交、暂存或清理业务改动。`--dry-run` 只生成计划，不写项目；无关 WIP
+保持原样，命中同一路径时按冻结快照与三方合并 fail closed。正式更新先备份，再做
+package 字段级合并、共享脚手架三方合并与完整验证。任何冲突都会在写入前中止，
 无并发变化的验证失败会自动回滚；中断恢复使用
 `bun run windy doctor --repair`。该命令在提交点前保留并发编辑并回滚其余路径，
 在 committed 提交点后只完成事务状态与备份清理，不回滚项目文件。
 
-仅当 Windy 发布说明提供确定性 proof 时使用
-`reconcile --to <精确目标版本>`。它默认只演练；显式增加 `--apply` 后也只更新
-受管清单元数据与无正文报告，不修改项目源码或推进 Project Lock。project-owned、
-缺失和未知语义差异始终保守未决；shared-scaffold 只有精确命中已发布 proof 才可对账。
-
 ## 开发约束
 
 - 新增路由默认需要登录；只有显式 public 的页面允许匿名访问。
@@ -185,8 +180,8 @@ bun run format
 create-windy 默认建立 `main` 分支并创建 `chore: initialize project` 首次提交。若当时
 没有配置 Git 用户身份，文件会保留在暂存区；配置身份后手动提交即可。
 
-当前已交付的 Windy 更新器会根据 Project Lock 和文件所有权，从 npm 历史 artifact
-重建 Base 并执行三方合并；它不连接私有源仓库，也不会静默覆盖项目代码。模块
+当前已交付的 Windy 更新器会根据 Project Lock 和文件所有权，从 Project Lock 指向的
+精确 npm artifact 重建 Base 并执行三方合并；它不连接私有源仓库，也不会静默覆盖项目代码。模块
 生命周期命令复用同一计划、事务、验证与恢复边界；卸载默认保留数据库数据，并要求
 显式确认数据处置计划。
 

package/template/apps/agent-server/Dockerfile

@@ -14,7 +14,8 @@ 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
+RUN mkdir -p /app/data/agent /app/apps/agent-server/project \
+  && chown -R windy:windy /app/data /app/apps/agent-server/project
 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)"]

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

@@ -61,13 +61,21 @@ SQLite append-only 表。审计不保存 prompt、请求正文或 Secret；审
 `GET /health/provider-governance` 查看。SQLite 实现仅支持单副本；多副本部署必须替换
 为共享、并发安全的审计 Adapter。
 
-开发者可单独启动 ADK Web：
+项目在 `project/adk-web-debug.json` 绑定一个满足
+`{ question: string } -> { text: string }` 的真实 Agent Operation 和当前启用的开发
+数据用户后，可启动 ADK Web：
 
 ```bash
 bun run dev:adk-web
 ```
 
-访问 `http://127.0.0.1:8000`。该 `agent-debug` profile 不读取 Qwen、内部 Token 或
-业务配置，只加载无 Provider、无业务 Tool 的确定性调试 Agent。它用于检查 ADK Web、
-Session 和 Event 交互，不能复现带 Actor/Execution Grant 的真实 Operation，也不能
-作为生产调用入口。
+访问 `http://127.0.0.1:8000` 并选择 `canonical_debug`。该命令会拉起完整开发
+Runtime；Windy 启动脚本读取项目选择的 Operation，ADK Web 使用 create-windy 自动生成
+的随机调试 Token，经 canonical HTTP/SSE 执行真实 Operation。Server 把它解析成仅限
+Run 路径的专用服务身份，向业务 Module 投影真实用户的成员 ID 和当前 Scope，并把权限
+收窄到该用户已有权限与 Operation/allowed Tools 闭包。Provider、业务 Tool、
+Execution Grant 和审计仍由正式 Server/Agent Server 负责，ADK 容器不持有 Provider
+Key 或内部服务 Token。
+
+`safe_debug` 只用于纯 ADK UI smoke。生产 Compose 不包含 ADK Web；当前桥显示的是
+canonical Run 及有界事件摘要，不是内部完整 Workflow 图。

package/template/apps/agent-server/adk_web_agents/canonical_debug/__init__.py

@@ -0,0 +1 @@
+"""Developer-only canonical Run bridge for ADK Web."""

package/template/apps/agent-server/adk_web_agents/canonical_debug/agent.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncGenerator
+from typing import cast
+
+from google.adk.agents import LlmAgent
+from google.adk.models.base_llm import BaseLlm
+from google.adk.models.llm_request import LlmRequest
+from google.adk.models.llm_response import LlmResponse
+from google.genai import types
+
+from southwind_agent_server.adk_debug import (
+    CanonicalRunDebugClient,
+    TextOperationDebugConfig,
+    load_text_operation_debug_config,
+)
+
+TOOL_NAME = "run_canonical_operation"
+PROJECT_OPERATION = load_text_operation_debug_config()
+
+
+async def run_canonical_operation(question: str) -> dict[str, object]:
+    """Run the project-selected text Operation through canonical platform APIs."""
+    if PROJECT_OPERATION is None:
+        raise RuntimeError("项目尚未选择可调试的文本 Operation")
+    return await CanonicalRunDebugClient.from_environment(
+        PROJECT_OPERATION.operation_key
+    ).run(question)
+
+
+class CanonicalDebugLlm(BaseLlm):
+    """ADK dispatcher; real model and Tool execution stay in canonical Run."""
+
+    def __init__(self, operation: TextOperationDebugConfig | None) -> None:
+        super().__init__(model="windy-canonical-run-bridge")
+        self._operation = operation
+
+    async def generate_content_async(
+        self,
+        llm_request: LlmRequest,
+        stream: bool = False,
+    ) -> AsyncGenerator[LlmResponse, None]:
+        del stream
+        tool_response = latest_tool_response(llm_request)
+        if tool_response is not None:
+            yield text_response(render_result(tool_response))
+            return
+        if self._operation is None:
+            yield text_response(
+                "项目尚未在 apps/agent-server/project/adk-web-debug.json "
+                "选择真实文本 Operation。"
+            )
+            return
+        question = latest_user_text(llm_request)
+        if not question:
+            yield text_response("请输入要交给真实 Agent Runtime 调试的业务问题。")
+            return
+        yield LlmResponse(
+            content=types.Content(
+                role="model",
+                parts=[
+                    types.Part(
+                        function_call=types.FunctionCall(
+                            name=TOOL_NAME,
+                            args={"question": question},
+                        )
+                    )
+                ],
+            ),
+            partial=False,
+        )
+
+
+def latest_user_text(request: LlmRequest) -> str:
+    for content in reversed(request.contents):
+        if content.role != "user":
+            continue
+        text = "".join(part.text or "" for part in content.parts or [])
+        if text.strip():
+            return text.strip()
+    return ""
+
+
+def latest_tool_response(request: LlmRequest) -> dict[str, object] | None:
+    for content in reversed(request.contents):
+        for part in content.parts or []:
+            response = part.function_response
+            if response and response.name == TOOL_NAME:
+                return cast(dict[str, object], response.response or {})
+    return None
+
+
+def render_result(value: dict[str, object]) -> str:
+    answer = value.get("answer")
+    run_id = value.get("runId")
+    events = value.get("events")
+    if not isinstance(answer, str) or not isinstance(run_id, str):
+        return "真实 Agent 调试 Run 返回了无效结果。"
+    trace = json.dumps(events if isinstance(events, list) else [], ensure_ascii=False)
+    return f"{answer}\n\n---\n调试 Run：{run_id}\n事件摘要：{trace}"
+
+
+def text_response(text: str) -> LlmResponse:
+    return LlmResponse(
+        content=types.Content(role="model", parts=[types.Part(text=text)]),
+        partial=False,
+    )
+
+
+def build_root_agent(
+    operation: TextOperationDebugConfig | None,
+) -> LlmAgent:
+    return LlmAgent(
+        name="canonical_debug",
+        model=CanonicalDebugLlm(operation),
+        instruction=(
+            "每个业务问题都必须经 run_canonical_operation 交给 canonical Run；"
+            "不得自行回答、不得访问数据库或绕过平台授权。"
+        ),
+        tools=[run_canonical_operation] if operation else [],
+    )
+
+
+root_agent = build_root_agent(PROJECT_OPERATION)

package/template/apps/agent-server/project/adk-web-debug.json

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 1,
+  "textOperation": null
+}

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

@@ -0,0 +1,348 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import uuid
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, cast
+
+import httpx
+
+from .config import normalize_base_url
+
+MAX_QUESTION_LENGTH = 4_000
+MAX_VISIBLE_EVENTS = 64
+MAX_EVENT_FRAME_BYTES = 64 * 1024
+DEFAULT_RESULT_POLL_TIMEOUT_SECONDS = 60.0
+DEFAULT_RESULT_POLL_INTERVAL_SECONDS = 0.5
+
+
+@dataclass(frozen=True)
+class TextOperationDebugConfig:
+    operation_key: str
+    data_actor_id: str | None = None
+
+
+def load_text_operation_debug_config(
+    path: str | Path | None = None,
+) -> TextOperationDebugConfig | None:
+    if path is None:
+        environment_key = os.environ.get("ADK_DEBUG_OPERATION_KEY", "").strip()
+        if environment_key:
+            return TextOperationDebugConfig(
+                operation_key=validate_operation_key(environment_key)
+            )
+    config_path = Path(path) if path else project_debug_config_path()
+    try:
+        value = json.loads(config_path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return None
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise RuntimeError("ADK Web 项目调试配置不可读") from error
+    if not isinstance(value, dict) or set(value) != {
+        "schemaVersion",
+        "textOperation",
+    }:
+        raise RuntimeError("ADK Web 项目调试配置格式无效")
+    schema_version = value.get("schemaVersion")
+    if (
+        not isinstance(schema_version, int)
+        or isinstance(schema_version, bool)
+        or schema_version != 1
+    ):
+        raise RuntimeError("ADK Web 项目调试配置版本不受支持")
+    operation = value.get("textOperation")
+    if operation is None:
+        return None
+    if not isinstance(operation, dict) or set(operation) != {
+        "key",
+        "dataActorId",
+    }:
+        raise RuntimeError("ADK Web 文本 Operation 配置格式无效")
+    return TextOperationDebugConfig(
+        operation_key=validate_identifier(
+            operation.get("key"), "ADK Web 文本 Operation Key 无效"
+        ),
+        data_actor_id=validate_identifier(
+            operation.get("dataActorId"), "ADK Web 真实开发数据用户无效"
+        ),
+    )
+
+
+def validate_operation_key(value: object) -> str:
+    return validate_identifier(value, "ADK Web 文本 Operation Key 无效")
+
+
+def validate_identifier(value: object, message: str) -> str:
+    if (
+        not isinstance(value, str)
+        or not value.strip()
+        or len(value) > 200
+        or any(character.isspace() for character in value)
+    ):
+        raise RuntimeError(message)
+    return value
+
+
+def project_debug_config_path() -> Path:
+    configured = os.environ.get("ADK_DEBUG_PROJECT_CONFIG", "").strip()
+    if configured:
+        return Path(configured)
+    return Path(__file__).resolve().parents[2] / "project" / "adk-web-debug.json"
+
+
+class CanonicalRunDebugClient:
+    def __init__(
+        self,
+        operation_key: str,
+        base_url: str,
+        bearer_token: str,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+        result_poll_timeout_seconds: float = DEFAULT_RESULT_POLL_TIMEOUT_SECONDS,
+        result_poll_interval_seconds: float = DEFAULT_RESULT_POLL_INTERVAL_SECONDS,
+    ) -> None:
+        self._operation_key = operation_key
+        self._base_url = normalize_base_url(base_url)
+        self._bearer_token = bearer_token.strip()
+        self._transport = transport
+        if not 0 <= result_poll_timeout_seconds <= 120:
+            raise ValueError("result_poll_timeout_seconds 必须在 0 到 120 秒之间")
+        if not 0 < result_poll_interval_seconds <= 1:
+            raise ValueError("result_poll_interval_seconds 必须大于 0 且不超过 1 秒")
+        self._result_poll_timeout_seconds = result_poll_timeout_seconds
+        self._result_poll_interval_seconds = result_poll_interval_seconds
+        if not self._bearer_token:
+            raise RuntimeError("ADK_DEBUG_PLATFORM_TOKEN 未配置，拒绝启动真实调试 Run")
+
+    @classmethod
+    def from_environment(
+        cls,
+        operation_key: str,
+    ) -> CanonicalRunDebugClient:
+        return cls(
+            operation_key,
+            os.environ.get("ADK_DEBUG_PLATFORM_URL", "http://server:9747"),
+            os.environ.get("ADK_DEBUG_PLATFORM_TOKEN", ""),
+        )
+
+    async def run(self, question: str) -> dict[str, object]:
+        prompt = question.strip()
+        if not prompt or len(prompt) > MAX_QUESTION_LENGTH:
+            raise RuntimeError("调试问题不能为空且最长 4000 字")
+        headers = {
+            "authorization": f"Bearer {self._bearer_token}",
+            "idempotency-key": f"adk-web-{uuid.uuid4()}",
+            "user-agent": "Windy-ADK-Web-Dev",
+        }
+        async with httpx.AsyncClient(
+            base_url=f"{self._base_url}/",
+            headers=headers,
+            timeout=httpx.Timeout(120),
+            transport=self._transport,
+        ) as client:
+            started = await client.post(
+                "api/agent/runs",
+                json={
+                    "operationKey": self._operation_key,
+                    "input": {"question": prompt},
+                },
+            )
+            run_id = read_run_id(started)
+            events = await collect_compact_events(self._events(client, run_id))
+            try:
+                async with asyncio.timeout(self._result_poll_timeout_seconds):
+                    while True:
+                        result = await client.get(
+                            f"api/agent/runs/{run_id}/result",
+                            params={"operationKey": self._operation_key},
+                        )
+                        if result.is_success:
+                            break
+                        try:
+                            error = result.json()
+                        except json.JSONDecodeError:
+                            error = None
+                        if (
+                            result.status_code != 409
+                            or not isinstance(error, dict)
+                            or error.get("code") != "RUN_CONFLICT"
+                            or error.get("retryable") is not True
+                        ):
+                            raise RuntimeError("平台 Agent Run 永久失败或结果读取失败")
+                        await asyncio.sleep(self._result_poll_interval_seconds)
+            except TimeoutError as error:
+                raise RuntimeError("平台 Agent Run 结果等待超时") from error
+        answer = read_text_output(result, run_id)
+        if not any(event.get("type") == "run.completed" for event in events):
+            events = [*events[: MAX_VISIBLE_EVENTS - 1], {"type": "run.completed"}]
+        return {
+            "runId": run_id,
+            "answer": answer,
+            "events": events,
+        }
+
+    async def _events(
+        self,
+        client: httpx.AsyncClient,
+        run_id: str,
+    ) -> AsyncIterator[dict[str, object]]:
+        async with client.stream(
+            "GET",
+            f"api/agent/runs/{run_id}/events",
+            params={"operationKey": self._operation_key, "after": 0},
+        ) as response:
+            if not response.is_success:
+                raise RuntimeError("平台 Agent Run 事件读取失败")
+            async for event in sse_events(response):
+                yield summarize_event(event)
+
+
+async def sse_events(response: httpx.Response) -> AsyncIterator[dict[str, object]]:
+    buffer = bytearray()
+    async for chunk in response.aiter_bytes(chunk_size=4096):
+        buffer.extend(chunk)
+        while separator := frame_separator(buffer):
+            index, width = separator
+            if index > MAX_EVENT_FRAME_BYTES:
+                raise RuntimeError("平台 Agent Run 单个事件超过调试上限")
+            frame = bytes(buffer[:index])
+            del buffer[: index + width]
+            event = parse_sse_frame(frame)
+            if event is not None:
+                yield event
+        if len(buffer) > MAX_EVENT_FRAME_BYTES:
+            raise RuntimeError("平台 Agent Run 单个事件超过调试上限")
+    if buffer:
+        event = parse_sse_frame(bytes(buffer))
+        if event is not None:
+            yield event
+
+
+def frame_separator(buffer: bytearray) -> tuple[int, int] | None:
+    candidates = [
+        (index, len(separator))
+        for separator in (b"\n\n", b"\r\n\r\n")
+        if (index := buffer.find(separator)) >= 0
+    ]
+    return min(candidates) if candidates else None
+
+
+def parse_sse_frame(frame: bytes) -> dict[str, object] | None:
+    try:
+        lines = frame.decode("utf-8").splitlines()
+    except UnicodeDecodeError as error:
+        raise RuntimeError("平台 Agent Run 事件格式无效") from error
+    event_name = "message"
+    data: list[str] = []
+    for line in lines:
+        if not line or line.startswith(":"):
+            continue
+        if line.startswith("event:"):
+            event_name = line.removeprefix("event:").strip()
+        elif line.startswith("data:"):
+            value = line.removeprefix("data:")
+            data.append(value[1:] if value.startswith(" ") else value)
+    return parse_event(event_name, "\n".join(data)) if data else None
+
+
+def parse_event(event_name: str, data: str) -> dict[str, object]:
+    try:
+        value = json.loads(data)
+    except json.JSONDecodeError as error:
+        raise RuntimeError("平台 Agent Run 事件格式无效") from error
+    if not isinstance(value, dict) or value.get("type") != event_name:
+        raise RuntimeError("平台 Agent Run 事件格式无效")
+    return cast(dict[str, object], value)
+
+
+def summarize_event(event: dict[str, object]) -> dict[str, object]:
+    fields = ("sequence", "type", "toolKey", "toolCallId", "workItemId", "outcome")
+    return {field: event[field] for field in fields if field in event}
+
+
+def compact_events(events: list[dict[str, object]]) -> list[dict[str, object]]:
+    compactor = EventCompactor()
+    for event in events:
+        compactor.add(event)
+    return compactor.finish()
+
+
+async def collect_compact_events(
+    events: AsyncIterator[dict[str, object]],
+) -> list[dict[str, object]]:
+    compactor = EventCompactor()
+    async for event in events:
+        compactor.add(event)
+    return compactor.finish()
+
+
+@dataclass
+class EventCompactor:
+    visible: list[dict[str, object]] | None = None
+    output_deltas: int = 0
+    hidden_events: int = 0
+
+    def add(self, event: dict[str, object]) -> None:
+        if event.get("type") == "output.delta":
+            self.output_deltas += 1
+            return
+        if self.visible is None:
+            self.visible = []
+        if len(self.visible) < MAX_VISIBLE_EVENTS:
+            self.visible.append(event)
+        else:
+            self.hidden_events += 1
+
+    def finish(self) -> list[dict[str, object]]:
+        visible = list(self.visible or [])
+        while True:
+            trailers = self._trailers()
+            if len(visible) + len(trailers) <= MAX_VISIBLE_EVENTS:
+                return [*visible, *trailers]
+            visible.pop()
+            self.hidden_events += 1
+
+    def _trailers(self) -> list[dict[str, object]]:
+        trailers: list[dict[str, object]] = []
+        if self.output_deltas:
+            trailers.append({"type": "output.delta", "count": self.output_deltas})
+        if self.hidden_events:
+            trailers.append({"type": "events.truncated", "count": self.hidden_events})
+        return trailers
+
+
+def read_run_id(response: httpx.Response) -> str:
+    value = response_json(response, "平台 Agent Run 启动失败")
+    run_id = value.get("runId")
+    if not isinstance(run_id, str) or not run_id:
+        raise RuntimeError("平台 Agent Run 启动响应无效")
+    return run_id
+
+
+def read_text_output(response: httpx.Response, expected_run_id: str) -> str:
+    value = response_json(response, "平台 Agent Run 未完成")
+    if value.get("runId") != expected_run_id or value.get("status") != "completed":
+        raise RuntimeError("平台 Agent Run 结果身份或状态无效")
+    output = value.get("output")
+    if not isinstance(output, dict):
+        raise RuntimeError("平台 Agent Run 输出不符合文本调试契约")
+    text = output.get("text")
+    if not isinstance(text, str):
+        raise RuntimeError("平台 Agent Run 输出不符合文本调试契约")
+    return text
+
+
+def response_json(response: httpx.Response, message: str) -> dict[str, Any]:
+    if not response.is_success:
+        raise RuntimeError(message)
+    try:
+        value = response.json()
+    except json.JSONDecodeError as error:
+        raise RuntimeError(message) from error
+    if not isinstance(value, dict):
+        raise RuntimeError(message)
+    return cast(dict[str, Any], value)