create-windy 0.2.20 → 0.2.22

package/README.md

@@ -68,7 +68,7 @@ npx create-windy@latest my-dashboard \
 
 选择 `system.license` 时，Server 与 Web 通过 npm 依赖
 `@southwind-ai/license@^0.1.1` 使用运行时能力；生成项目及 `create-windy` 模板快照都不包含
-`packages/license-sdk` 源码。公网 npm 已发布兼容的 `@southwind-ai/license@0.1.1`；
+`packages/license-sdk` 源码。公网 npm 已发布兼容的 `@southwind-ai/license@0.1.2`；
 发布包含该模块的新版创建器前，必须先确认目标 registry 中存在兼容版本，并完成真实
 安装回归。
 

package/dist/cli.js

@@ -213,7 +213,11 @@ var optionalModuleManifests = [
       "system",
       "system.settings"
     ]),
-    fileRoots: ["apps/server/src/storage"],
+    fileRoots: [
+      "apps/server/src/storage",
+      "apps/server/src/module-host/route-installer.test.ts",
+      "apps/server/src/module-host/storage-port.test.ts"
+    ],
     documentation: ["docs/architecture/object-storage.md"],
     schemaFiles: ["packages/database/src/schema/file-storage.ts"],
     databaseTables: [
@@ -228,10 +232,16 @@ var optionalModuleManifests = [
       "system.audit"
     ]),
     fileRoots: [
+      "apps/agent-server",
       "apps/server/src/agent",
+      "apps/server/src/module-host/tool-handlers.ts",
       "packages/modules/src/system-agent-tools.ts"
     ],
-    documentation: ["docs/platform/agent-tools.md"]
+    documentation: [
+      "docs/architecture/ai-runtime.md",
+      "docs/platform/agent-runtime.md",
+      "docs/platform/agent-tools.md"
+    ]
   },
   {
     ...module("system.scheduler", "任务调度", "任务、重试、历史和恢复。", [
@@ -242,6 +252,7 @@ var optionalModuleManifests = [
       "apps/server/src/scheduler",
       "apps/server/src/jobs",
       "apps/server/src/application-services.ts",
+      "apps/server/src/module-host/task-definitions.ts",
       "apps/web/src/pages/system/components/SchedulerOperationsPanel.vue",
       "apps/web/src/pages/system/components/SchedulerOperationsPanel.webtest.ts",
       "apps/web/src/pages/system/components/SchedulerRunTable.vue",
@@ -328,6 +339,7 @@ var optionalModuleManifests = [
     ]),
     fileRoots: [
       "apps/server/src/search",
+      "apps/server/src/module-host/search-providers.ts",
       "apps/web/src/layout/NavigationSearchDialog.vue",
       "apps/web/src/layout/NavigationSearchDialog.webtest.ts"
     ],
@@ -881,7 +893,10 @@ async function initializeLocalEnvironment(projectRoot, generateSecret = defaultS
   if (!gitignore.split(/\r?\n/).some((line) => line.trim() === ".env")) {
     throw new Error("生成项目的 .gitignore 未排除 .env，拒绝写入本地密码");
   }
-  const content = setEmptyVariable(setEmptyVariable(example, "POSTGRES_PASSWORD", generateSecret()), "WINDY_BOOTSTRAP_ADMIN_PASSWORD", generateSecret());
+  let content = setEmptyVariable(setEmptyVariable(example, "POSTGRES_PASSWORD", generateSecret()), "WINDY_BOOTSTRAP_ADMIN_PASSWORD", generateSecret());
+  if (/^AGENT_SERVER_INTERNAL_TOKEN=[ \t\r]*$/m.test(content)) {
+    content = setEmptyVariable(content, "AGENT_SERVER_INTERNAL_TOKEN", generateSecret());
+  }
   let handle;
   try {
     handle = await open(target, "wx", 384);
@@ -1441,8 +1456,8 @@ function isMissing2(error) {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
 
-// src/project-files.ts
-var starterCompose = `services:
+// src/runtime-profile-files.ts
+var starterComposeBase = `services:
   postgres:
     image: postgres:17-alpine
     environment:
@@ -1486,6 +1501,10 @@ var starterCompose = `services:
       WINDY_CONTAINERIZED: "1"
       BUN_CONFIG_NO_CLEAR_TERMINAL_ON_RELOAD: "true"
       WINDY_SYSTEM_USAGE_PATHS: /app/data/audit
+      PLATFORM_ENABLE_AI: \${PLATFORM_ENABLE_AI:-false}
+      AGENT_SERVER_URL: http://agent-server:8080
+      AGENT_TOOL_HOST_URL: http://server:9747
+      AGENT_SERVER_INTERNAL_TOKEN: \${AGENT_SERVER_INTERNAL_TOKEN:-}
     ports:
       - "9747:9747"
     volumes:
@@ -1529,11 +1548,50 @@ var starterCompose = `services:
 volumes:
   postgres-data:
   server-audit-data:
+__AGENT_VOLUME__
+`;
+var agentComposeService = `  agent-server:
+    profiles: ["agent"]
+    build:
+      context: .
+      dockerfile: apps/agent-server/Dockerfile
+    environment:
+      AGENT_SERVER_INTERNAL_TOKEN: \${AGENT_SERVER_INTERNAL_TOKEN:-}
+      AGENT_RUN_STORE_PATH: /app/data/agent/runs.sqlite3
+      QWEN_API_URL: \${QWEN_API_URL:-}
+      QWEN_API_KEY: \${QWEN_API_KEY:-}
+      QWEN_MODEL: \${QWEN_MODEL:-}
+      AI_PROVIDER_CONNECT_TIMEOUT_MS: \${AI_PROVIDER_CONNECT_TIMEOUT_MS:-5000}
+      AI_PROVIDER_REQUEST_TIMEOUT_MS: \${AI_PROVIDER_REQUEST_TIMEOUT_MS:-60000}
+      AI_PROVIDER_MAX_RESPONSE_BYTES: \${AI_PROVIDER_MAX_RESPONSE_BYTES:-2097152}
+    volumes:
+      - agent-run-data:/app/data/agent
+    depends_on:
+      server:
+        condition: service_started
+
 `;
-function environmentExample(includeExample) {
+function starterComposeFor(includeAgent) {
+  return starterComposeBase.replace(`  web:
+`, `${includeAgent ? agentComposeService : ""}  web:
+`).replace("__AGENT_VOLUME__", includeAgent ? "  agent-run-data:" : "");
+}
+var starterCompose = starterComposeFor(true);
+function environmentExample(includeExample, includeAgent = true) {
   return `# 复制为 .env 后填写。不要提交真实密码。
 POSTGRES_PASSWORD=
 WINDY_BOOTSTRAP_ADMIN_PASSWORD=
+${includeAgent ? `
+# Agent profile 仅由 Server 读取；不要使用 VITE_ 前缀。
+PLATFORM_ENABLE_AI=false
+AGENT_SERVER_INTERNAL_TOKEN=
+QWEN_API_URL=
+QWEN_API_KEY=
+QWEN_MODEL=
+# AI_PROVIDER_CONNECT_TIMEOUT_MS=5000
+# AI_PROVIDER_REQUEST_TIMEOUT_MS=60000
+# AI_PROVIDER_MAX_RESPONSE_BYTES=2097152
+` : ""}
 
 # 可选搜索配置；不配置时启用 Manifest 中默认开启的 Provider。${includeExample ? `
 # SEARCH_PROVIDER_KEYS=work-order.ticket.search` : `
@@ -1543,7 +1601,8 @@ WINDY_BOOTSTRAP_ADMIN_PASSWORD=
 # SEARCH_MAX_REQUESTS_PER_MINUTE=30
 `;
 }
-function starterDocsReadme(includeOfflineLicense = true) {
+// src/project-files.ts
+function starterDocsReadme(includeOfflineLicense = true, includeAgent = true) {
   return `# Windy Starter 文档
 
 本目录只包含客户运行项目需要的平台架构、开发接入和运维可观测性文档。
@@ -1554,11 +1613,13 @@ License 签发中心、独立签名服务、Vault、发布治理、内部任务
 - 平台开发：从 [系统 CRUD API](./platform/system-crud-api.md) 和 [CRUD 生成器](./development/crud-generator.md) 开始。
 ${includeOfflineLicense ? "- License 消费端：[离线激活与安装协议](./license/license-offline-activation-code.md)；运行时能力由 npm 依赖 `@southwind-ai/license` 提供。" : ""}
 - 运维：[可观测性](./operations/observability.md) 与 [运维总览](./platform/operations-overview.md)。
+${includeAgent ? "- Agent：[Agent Runtime 接入](./platform/agent-runtime.md) 与 [受控工具](./platform/agent-tools.md)。" : ""}
 - 兼容：[RuoYi-Vue Adapter](./adapters/ruoyi-vue-compatibility.md)。
 `;
 }
 function starterReadme(projectName, includeExample = true, includeOxc = true, projectLicense = "UNLICENSED", selectedModules = []) {
   const selected = new Set(selectedModules);
+  const includeAgent = selected.has("system.agent");
   const moduleRows = moduleDistributionCatalog.map(({ name, description, selection }) => `| \`${name}\` | ${selected.has(name) ? "已包含" : "未包含"} | ${selection === "required" ? "H0" : "H2"} | ${description} |`).join(`
 `);
   return `# ${projectName}
@@ -1614,6 +1675,21 @@ bun run dev:server
 直接输出已有地址，其它服务占用时会自动使用后续端口，最多检查 100 个。实际地址始终
 以终端输出为准。\`dev:server\` 不会自动启动 PostgreSQL 或执行 migration；未配置
 \`DATABASE_URL\` 时使用内存模式。
+${includeAgent ? `
+## OpenAI-compatible Agent profile
+
+Agent Runtime 默认不启动。先在仅供本机使用的 \`.env\` 中设置
+\`PLATFORM_ENABLE_AI=true\`、\`AGENT_SERVER_INTERNAL_TOKEN\`、\`QWEN_API_URL\`、
+\`QWEN_API_KEY\` 与 \`QWEN_MODEL\`，再运行：
+
+\`\`\`bash
+bun run dev:agent
+\`\`\`
+
+公网 Provider URL 必须使用 HTTPS；本机、容器服务名和内网地址允许 HTTP。
+\`QWEN_API_KEY\` 只进入 Agent Server，不会进入 Web 环境或返回给客户端。运行与模块
+接入细节见 [Agent Runtime 接入](./docs/platform/agent-runtime.md)。
+` : ""}
 
 ## 页面与登录
 
@@ -1738,6 +1814,7 @@ function createStarterPackage(source, projectName, includeOxc = true, projectLic
       dev: "docker compose up",
       "docker:sync": "create-windy sync-docker",
       "dev:build": "bun run docker:sync && docker compose up --build",
+      ...selectedModules.includes("system.agent") ? { "dev:agent": "docker compose --profile agent up --build" } : {},
       ...generatorVersion ? { windy: "create-windy" } : {},
       "dev:web": "bun run --cwd apps/web dev",
       "dev:server": "bun run --cwd apps/server dev",
@@ -1785,6 +1862,7 @@ var templateRootFiles = [
 ];
 var templateDirectories = [
   "apps/server",
+  "apps/agent-server",
   "apps/web",
   "examples",
   "packages/ai-client",
@@ -1801,6 +1879,7 @@ var templateDirectories = [
 var templateDocumentationFiles = [
   "docs/adapters/ruoyi-vue-compatibility.md",
   "docs/architecture/admin-surface-boundary.md",
+  "docs/architecture/ai-runtime.md",
   "docs/architecture/data-scope-query-enforcement.md",
   "docs/architecture/durable-jobs.md",
   "docs/architecture/minimal-approval-workflow.md",
@@ -1811,6 +1890,7 @@ var templateDocumentationFiles = [
   "docs/license/license-offline-activation-code.md",
   "docs/operations/observability.md",
   "docs/platform/agent-tools.md",
+  "docs/platform/agent-runtime.md",
   "docs/platform/audit-reliability.md",
   "docs/platform/bulk-data-jobs.md",
   "docs/platform/data-access-control.md",
@@ -2025,10 +2105,10 @@ async function generateProject(input) {
   const packageJson = JSON.parse(await readFile10(packagePath, "utf8"));
   await writeFile9(packagePath, `${JSON.stringify(createStarterPackage(packageJson, input.projectName, includeOxc, projectLicense, selectedModules, templateMetadata.generatorVersion), null, 2)}
 `);
-  await writeFile9(join10(input.targetDirectory, "docker-compose.yml"), starterCompose);
-  await writeFile9(join10(input.targetDirectory, ".env.example"), environmentExample(includeExample));
+  await writeFile9(join10(input.targetDirectory, "docker-compose.yml"), starterComposeFor(selectedModules.includes("system.agent")));
+  await writeFile9(join10(input.targetDirectory, ".env.example"), environmentExample(includeExample, selectedModules.includes("system.agent")));
   await writeFile9(join10(input.targetDirectory, "README.md"), starterReadme(input.projectName, includeExample, includeOxc, projectLicense, selectedModules));
-  await writeFile9(join10(input.targetDirectory, "docs/README.md"), starterDocsReadme(selectedModules.includes("system.license")));
+  await writeFile9(join10(input.targetDirectory, "docs/README.md"), starterDocsReadme(selectedModules.includes("system.license"), selectedModules.includes("system.agent")));
   await reflectCodeQualityChoice(input.targetDirectory, includeOxc);
   await applyWindyBaseLicense(input.targetDirectory);
   await applyProjectLicense(input.targetDirectory, projectLicense, input.licenseHolder);
@@ -4205,7 +4285,9 @@ var recipes = [
   { id: "starter-0.2.16-to-0.2.17", from: "0.2.16", to: "0.2.17" },
   { id: "starter-0.2.17-to-0.2.18", from: "0.2.17", to: "0.2.18" },
   { id: "starter-0.2.18-to-0.2.19", from: "0.2.18", to: "0.2.19" },
-  { id: "starter-0.2.19-to-0.2.20", from: "0.2.19", to: "0.2.20" }
+  { id: "starter-0.2.19-to-0.2.20", from: "0.2.19", to: "0.2.20" },
+  { id: "starter-0.2.20-to-0.2.21", from: "0.2.20", to: "0.2.21" },
+  { id: "starter-0.2.21-to-0.2.22", from: "0.2.21", to: "0.2.22" }
 ];
 function resolveRecipeChain(sourceVersion, targetVersion) {
   if (sourceVersion === targetVersion)

package/package.json

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

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "0219ad152473b48f39df25b3ea261dcef52171c7",
-  "generatorVersion": "0.2.20",
+  "templateCommit": "0888f6c444ba594106e747c8f3114545f24b3bc7",
+  "generatorVersion": "0.2.22",
   "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