create-windy 0.2.34 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-windy",
-  "version": "0.2.34",
+  "version": "0.3.1",
   "description": "创建单组织、单租户、私有部署优先的 Windy 企业 Dashboard Starter",
   "type": "module",
   "bin": {
@@ -13,14 +13,14 @@
     "README.md"
   ],
   "scripts": {
-    "build": "bun build src/cli.ts --target=node --format=esm --outdir=dist",
+    "build": "bun build src/cli.ts --target=bun --format=esm --outdir=dist",
     "template:sync": "bun run src/sync-template.ts",
     "prepack": "bun run template:sync && bun run build",
     "postpack": "bun run src/clean-template.ts",
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "engines": {
-    "node": ">=20"
+    "bun": ">=1.3.14"
   },
   "keywords": [
     "dashboard",

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "28f6b738276d5138a514a4ab374d60884b94e769",
-  "generatorVersion": "0.2.34",
+  "templateCommit": "74bc602b85aa40bdd11761507d8d9821ecd5bb50",
+  "generatorVersion": "0.3.1",
   "modules": [
     {
       "name": "system",

package/template/AGENTS.md

@@ -44,6 +44,9 @@
   `apps/web/src/pages/auth/LoginPage.vue` 或 Router。业务页面复用
   `useLoginFlow`、`DevelopmentAuthWarning` 和平台品牌设置，保留安全
   `returnTo`、真实认证与开发认证提示。
+- 定制 404、500、维护中或网络异常页时，只修改 project-owned 的
+  `apps/web/src/app/error-pages.ts`，并把业务 SFC 放在 `apps/web/src/app/`；
+  保留四个类型化注册项，不要为换视觉修改 Router、HTTP 核心或平台默认错误页。
 - 业务 Agent Operation 开启 Provider 出网时，必须在 Manifest 同时声明最小
   `providerDataPolicy.inputFields` JSON Pointer allowlist 与
   `envelopeFields`；raw input 会在进入 `prepare` 前裁剪并执行 DLP。接入与升级
@@ -55,6 +58,8 @@
   或 MCP 暴露时使用的仓库内开发流程。
 - `docs/development/custom-login-page.md`：完整替换登录页的 ownership、认证复用和
   升级迁移说明。
+- `docs/development/custom-error-pages.md`：统一错误语义、Request ID 与业务页面
+  替换方式。
 - `bun run dev`：复用 Docker 镜像启动 PostgreSQL、自动 migration、Server 与支持热更新的 Web。
 - `bun run dev:build`：依赖、Dockerfile 或 lockfile 变化后重建并启动开发环境。
 - `bun run dev:web`：启动 Web 开发服务。

package/template/README.md

@@ -52,6 +52,20 @@ bun run dev:server
 以终端输出为准。`dev:server` 不会自动启动 PostgreSQL 或执行 migration；未配置
 `DATABASE_URL` 时使用内存模式。
 
+## Agent、MCP 与仓库 Skill
+
+仓库始终包含 `.agents/skills/windy-business-module/SKILL.md`。新增或修改业务模块、
+Agent Tool 或 MCP 暴露时，可以明确要求代码 Agent“使用 `windy-business-module`
+Skill 完成该能力”。Skill 只指导开发流程；Feature、Permission、Schema 和 Tool 的
+运行时事实仍以 Module Manifest 与平台 Registry 为准。
+
+当前组合未包含 `system.agent`，MCP Server、Agent Tool Host 和相关文档已被
+物理裁剪。若项目尚可重新生成，请在创建时增加 `--module system.agent` 或使用
+`--all-modules`；部署后的通用 `module add` 尚未交付，不要手工复制 MCP Adapter
+或另建授权链。仓库 Skill 仍可用于普通业务模块开发。
+
+
+
 
 ## 页面与登录
 
@@ -100,7 +114,7 @@ create-windy 在本机 `.env` 中随机生成的 `WINDY_BOOTSTRAP_ADMIN_PASSWORD
 | `system.storage` | 未包含 | H2 | 上传、下载和对象生命周期。 |
 | `system.agent` | 未包含 | H2 | 受控 Agent 工具宿主。 |
 | `system.scheduler` | 未包含 | H2 | 任务、重试、历史和恢复。 |
-| `system.notification` | 未包含 | H2 | 通知发布、阅读和归档。 |
+| `system.notification` | 未包含 | H2 | 通知定向与定时发布、用户偏好、外部渠道投递、修改历史、阅读、收藏和归档。 |
 | `system.workflow` | 未包含 | H2 | 审批、转交、超时和补偿。 |
 | `system.bulk-data` | 未包含 | H2 | 批量导入导出与结果留存。 |
 | `system.search` | 未包含 | H2 | 权限感知搜索与 Provider 聚合。 |
@@ -121,12 +135,14 @@ bun run dev
 bun run dev:build
 bun run dev:web
 bun run dev:server
+
 bun run typecheck
 bun run test
 bun run build
 bun run windy doctor
 bun run windy update --check
 bun run windy update --dry-run
+bun run windy reconcile --to <精确目标版本>
 bun run lint
 bun run format
 ```
@@ -135,7 +151,14 @@ bun run format
 
 更新前必须保持 Git 工作区干净。`--dry-run` 只生成计划，不写项目；正式更新先备份，
 再做 package 字段级合并、共享脚手架三方合并与完整验证。任何冲突都会在写入前中止，
-验证失败会自动回滚；中断恢复使用 `bun run windy doctor --repair`。
+无并发变化的验证失败会自动回滚；中断恢复使用
+`bun run windy doctor --repair`。该命令在提交点前保留并发编辑并回滚其余路径，
+在 committed 提交点后只完成事务状态与备份清理，不回滚项目文件。
+
+仅当 Windy 发布说明提供确定性 proof 时使用
+`reconcile --to <精确目标版本>`。它默认只演练；显式增加 `--apply` 后也只更新
+受管清单元数据与无正文报告，不修改项目源码或推进 Project Lock。project-owned、
+缺失和未知语义差异始终保守未决；shared-scaffold 只有精确命中已发布 proof 才可对账。
 
 ## 开发约束
 
@@ -154,8 +177,9 @@ bun run format
 create-windy 默认建立 `main` 分支并创建 `chore: initialize project` 首次提交。若当时
 没有配置 Git 用户身份，文件会保留在暂存区；配置身份后手动提交即可。
 
-未来的 Windy 更新器会根据 project lock 和文件所有权执行三方合并，不会要求连接
-私有源仓库，也不会静默覆盖项目代码。该更新引擎当前尚未交付。
+当前已交付的 Windy 更新器会根据 Project Lock 和文件所有权，从 npm 历史 artifact
+重建 Base 并执行三方合并；它不连接私有源仓库，也不会静默覆盖项目代码。部署期通用
+`module add/update/remove` 尚未交付。
 
 ## License
 

package/template/_gitignore

@@ -1,4 +1,8 @@
 .env
+.env.*
+!.env.example
+!.env.sample
+!.env.template
 .DS_Store
 node_modules/
 dist/

package/template/apps/agent-server/Dockerfile

@@ -8,6 +8,7 @@ RUN pip install --no-cache-dir uv==0.9.27 \
 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
+COPY apps/agent-server/adk_web_agents ./adk_web_agents
 RUN uv sync --frozen --no-dev
 
 ENV PATH="/app/apps/agent-server/.venv/bin:${PATH}"

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

@@ -1,8 +1,9 @@
 # Southwind AI Agent Server
 
 Python 3.12 Agent Runtime。HTTP 层只公开 Southwind AI canonical Agent
-contracts。当前可用 Adapter 连接 OpenAI-compatible `/chat/completions`；Google ADK
-仍只是未配置 Provider 时安全拒绝的内部 Adapter。
+contracts。真实业务 Run 在内部通过 Google ADK 2.5 的 Runner、Session、LlmAgent 和
+Event 执行；ADK 类型不会越过 `AgentEngineAdapter`。模型调用继续复用受治理的
+OpenAI-compatible `/chat/completions` Provider。
 
 ```bash
 uv sync --frozen
@@ -23,7 +24,7 @@ Run 创建使用 `Idempotency-Key`。事件以 SSE 传输，支持 `Last-Event-I
 断线重放，并周期发送 comment heartbeat。Provider 或框架异常只会映射为 canonical
 安全错误，不会把原始异常正文暴露给调用方。
 
-配置以下仅服务端可见的环境变量后，默认运行 OpenAI-compatible Adapter：
+配置以下仅服务端可见的环境变量后，默认运行 ADK Adapter：
 
 ```bash
 export AGENT_SERVER_INTERNAL_TOKEN='<random-token>'
@@ -40,8 +41,9 @@ uv run uvicorn southwind_agent_server.app:app
 公网 URL 必须使用 HTTPS 且 Host 精确命中 allowlist；本机、容器服务名和内网地址允许
 HTTP。Provider 请求包含连接和总超时、响应大小限制、错误脱敏与 `/models`
 readiness。缺少 URL/Model 时回退
-`AdkEngineAdapter` 并返回 unavailable，不调用模型。测试另使用
-`DeterministicEngineAdapter`。
+未配置的 `AdkEngineAdapter` 并返回 unavailable，不调用模型。测试另使用
+`DeterministicEngineAdapter`。每个 ADK Tool 只声明 Operation 已允许的 Key；其执行
+函数只回调 Southwind AI Tool Host，并携带当前 Run 的 opaque Execution Grant。
 
 未设置 `AGENT_RUN_STORE_PATH` 时使用的 `InMemoryRunStore` **仅用于 deterministic
 测试**。配置路径后使用有界 SQLite Store，可在单副本重启后保留 Run/Event/Result 和
@@ -56,3 +58,14 @@ SQLite append-only 表。审计不保存 prompt、请求正文或 Secret；审
 出网。记录到期后只由配置的 TTL 清理，清理计数可通过需内部 Token 的
 `GET /health/provider-governance` 查看。SQLite 实现仅支持单副本；多副本部署必须替换
 为共享、并发安全的审计 Adapter。
+
+开发者可单独启动 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，也不能
+作为生产调用入口。

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

@@ -0,0 +1 @@
+"""Developer-only ADK Web agents."""

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

@@ -0,0 +1,3 @@
+from .agent import root_agent
+
+__all__ = ["root_agent"]

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

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+
+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
+
+
+class SafeDebugLlm(BaseLlm):
+    async def generate_content_async(
+        self,
+        llm_request: LlmRequest,
+        stream: bool = False,
+    ) -> AsyncGenerator[LlmResponse, None]:
+        del llm_request, stream
+        text = (
+            "这是 Windy 的 ADK 开发调试 Agent。"
+            "它不连接业务 Repository、Tool Host 或模型 Provider，"
+            "不能代表生产业务 Operation。"
+        )
+        yield LlmResponse(
+            content=types.Content(
+                role="model",
+                parts=[types.Part(text=text)],
+            ),
+            partial=False,
+        )
+
+
+root_agent = LlmAgent(
+    name="safe_debug",
+    model=SafeDebugLlm(model="windy-safe-debug"),
+    instruction=(
+        "仅说明开发调试边界；不访问业务数据，不调用 Tool，不连接模型 Provider。"
+    ),
+    tools=[],
+)

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

@@ -21,7 +21,7 @@ dev = [
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
-pythonpath = ["src"]
+pythonpath = [".", "src"]
 testpaths = ["tests"]
 
 [tool.ruff]

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

@@ -1,39 +1,214 @@
 from __future__ import annotations
 
-from collections.abc import AsyncIterator, Mapping
+import asyncio
+from collections.abc import AsyncIterator
 
+from google.adk.agents import LlmAgent
+from google.adk.agents.run_config import RunConfig, StreamingMode
+from google.adk.events import Event
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+from google.genai import types
+
+from .adk_failure import AdkFailureState
+from .adk_model import GovernedOpenAiLlm
+from .adk_tools import GovernedTool
+from .contracts import JsonValue
 from .engine import (
     AgentEngineAdapter,
+    EngineCompleted,
     EngineRunRequest,
     EngineSignal,
+    OutputDelta,
     SafeEngineError,
+    ToolCompleted,
+    ToolRequested,
+    UsageReported,
 )
+from .openai_engine import cancelled, validate_runtime_request
+from .openai_provider import OpenAiCompatibleProvider
+from .provider_governance import ProviderRequestGovernance
+from .tool_host import ToolHostClient
 
 
 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.
-    """
+    """Google ADK Runner implementation behind the stable engine seam."""
 
-    def __init__(self, agents: Mapping[str, object] | None = None) -> None:
-        self._agents = dict(agents or {})
+    def __init__(
+        self,
+        provider: OpenAiCompatibleProvider | None = None,
+        tool_host: ToolHostClient | None = None,
+        governance: ProviderRequestGovernance | None = None,
+    ) -> None:
+        self._provider = provider
+        self._tool_host = tool_host
+        self._governance = governance
+        self._cancellations: dict[str, asyncio.Event] = {}
 
     def supports(self, operation_key: str) -> bool:
-        return operation_key in self._agents
+        return bool(operation_key.strip())
 
     async def execute(
         self,
         request: EngineRunRequest,
     ) -> AsyncIterator[EngineSignal]:
-        del request
-        raise SafeEngineError(
-            "RUNTIME_UNAVAILABLE",
-            "Agent Runtime 尚未配置",
-            retryable=True,
+        provider, tool_host, governance = self._configured()
+        validate_runtime_request(request, provider.config.deployment_key)
+        cancellation = self._cancellations.setdefault(
+            request.run_id,
+            asyncio.Event(),
         )
-        yield  # pragma: no cover - keeps this method an async generator
+        output = ""
+        output_bytes = 0
+        failures = AdkFailureState()
+        event_failure: SafeEngineError | None = None
+        try:
+            session_service = InMemorySessionService()  # type: ignore[no-untyped-call]
+            await session_service.create_session(
+                app_name="southwind_runtime",
+                user_id="platform",
+                session_id=request.run_id,
+            )
+            runner = Runner(
+                app_name="southwind_runtime",
+                agent=LlmAgent(
+                    name="southwind_operation",
+                    model=GovernedOpenAiLlm(
+                        request,
+                        provider,
+                        governance,
+                        cancellation,
+                        failures,
+                    ),
+                    instruction=request.instructions,
+                    tools=[
+                        GovernedTool(
+                            tool,
+                            request,
+                            tool_host,
+                            cancellation,
+                            failures,
+                        )
+                        for tool in request.allowed_tools
+                    ],
+                ),
+                session_service=session_service,
+            )
+            async for event in runner.run_async(
+                user_id="platform",
+                session_id=request.run_id,
+                new_message=types.Content(
+                    role="user",
+                    parts=[types.Part(text=request.user_prompt)],
+                ),
+                run_config=RunConfig(
+                    streaming_mode=StreamingMode.SSE,
+                    max_llm_calls=provider.config.max_tool_rounds,
+                ),
+            ):
+                cancelled(cancellation)
+                if event.error_code:
+                    event_failure = failures.failure or SafeEngineError(
+                        "PROVIDER_UNAVAILABLE",
+                        "模型服务暂不可用",
+                        retryable=True,
+                    )
+                    continue
+                async for signal in signals_for_event(event):
+                    if isinstance(signal, OutputDelta):
+                        output_bytes += len(signal.text.encode())
+                        if output_bytes > request.limits.max_output_bytes:
+                            raise SafeEngineError(
+                                "BUDGET_EXCEEDED",
+                                "Agent 输出超过 Operation 上限",
+                                retryable=False,
+                            )
+                        output += signal.text
+                    yield signal
+            if event_failure is not None:
+                raise event_failure
+            cancelled(cancellation)
+            yield EngineCompleted({"text": output})
+        except SafeEngineError:
+            raise
+        except asyncio.CancelledError:
+            raise SafeEngineError(
+                "RUN_CANCELLED",
+                "Agent Run 已取消",
+                retryable=False,
+            ) from None
+        except Exception:
+            raise SafeEngineError(
+                "RUNTIME_UNAVAILABLE",
+                "Agent Runtime 执行失败",
+                retryable=True,
+            ) from None
+        finally:
+            self._cancellations.pop(request.run_id, None)
 
     async def cancel(self, run_id: str) -> None:
-        del run_id
+        cancellation = self._cancellations.get(run_id)
+        if cancellation is not None:
+            cancellation.set()
+
+    async def health(self) -> None:
+        provider, _, _ = self._configured()
+        await provider.health()
+
+    def governance_health(self) -> dict[str, int | float | str | None]:
+        _, _, governance = self._configured()
+        return governance.health()
+
+    def _configured(
+        self,
+    ) -> tuple[
+        OpenAiCompatibleProvider,
+        ToolHostClient,
+        ProviderRequestGovernance,
+    ]:
+        if not self._provider or not self._tool_host or not self._governance:
+            raise SafeEngineError(
+                "RUNTIME_UNAVAILABLE",
+                "Agent Runtime 尚未配置",
+                retryable=True,
+            )
+        return self._provider, self._tool_host, self._governance
+
+
+async def signals_for_event(event: Event) -> AsyncIterator[EngineSignal]:
+    for call in event.get_function_calls():
+        if not call.id or not call.name:
+            raise SafeEngineError(
+                "TOOL_DENIED",
+                "模型请求了无效 Tool",
+                retryable=False,
+            )
+        yield ToolRequested(call.id, call.name)
+    for response in event.get_function_responses():
+        if not response.id:
+            raise SafeEngineError(
+                "TOOL_DENIED",
+                "Agent Tool 响应缺少稳定标识",
+                retryable=False,
+            )
+        yield ToolCompleted(response.id)
+    if event.partial and event.content:
+        for part in event.content.parts or []:
+            if part.text and not part.thought:
+                yield OutputDelta(part.text)
+    usage = southwind_usage(event)
+    if usage is not None:
+        yield UsageReported(usage)
+
+
+def southwind_usage(event: Event) -> dict[str, JsonValue] | None:
+    metadata = event.custom_metadata or {}
+    value = metadata.get("southwindUsage")
+    if not isinstance(value, dict):
+        return None
+    return {
+        key: item
+        for key, item in value.items()
+        if isinstance(key, str)
+        and (item is None or isinstance(item, str | int | float | bool | list | dict))
+    }

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

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .engine import SafeEngineError
+
+
+@dataclass
+class AdkFailureState:
+    failure: SafeEngineError | None = None
+
+    def capture(self, error: SafeEngineError) -> None:
+        self.failure = error