create-windy 0.2.23 → 0.2.25

package/dist/cli.js

@@ -231,14 +231,28 @@ var optionalModuleManifests = [
       "system",
       "system.audit"
     ]),
+    registryDependencies: [
+      {
+        sourceName: "@modelcontextprotocol/sdk",
+        name: "@modelcontextprotocol/sdk",
+        version: "^1.29.0"
+      },
+      {
+        sourceName: "ajv",
+        name: "ajv",
+        version: "^8.20.0"
+      }
+    ],
     fileRoots: [
       "apps/agent-server",
       "apps/server/src/agent",
+      "apps/server/src/mcp",
       "apps/server/src/module-host/tool-handlers.ts",
       "packages/modules/src/system-agent-tools.ts"
     ],
     documentation: [
       "docs/architecture/ai-runtime.md",
+      "docs/architecture/mcp-business-capabilities.md",
       "docs/platform/agent-runtime.md",
       "docs/platform/agent-tools.md"
     ]
@@ -1689,6 +1703,10 @@ bun run dev:agent
 公网 Provider URL 必须使用 HTTPS；本机、容器服务名和内网地址允许 HTTP。
 \`QWEN_API_KEY\` 只进入 Agent Server，不会进入 Web 环境或返回给客户端。运行与模块
 接入细节见 [Agent Runtime 接入](./docs/platform/agent-runtime.md)。
+
+MCP 客户端使用 \`http://localhost:9747/api/mcp\`，并通过平台 Bearer Token 或 Session
+Cookie 鉴权。该入口只发现当前账号获准的只读 Tool；每次调用都会重新执行 Feature、
+RBAC 和数据范围校验。
 ` : ""}
 
 ## 页面与登录
@@ -1861,6 +1879,7 @@ var templateRootFiles = [
   "package.json"
 ];
 var templateDirectories = [
+  ".agents/skills/windy-business-module",
   "apps/server",
   "apps/agent-server",
   "apps/web",
@@ -4288,7 +4307,9 @@ var recipes = [
   { 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" },
-  { id: "starter-0.2.22-to-0.2.23", from: "0.2.22", to: "0.2.23" }
+  { id: "starter-0.2.22-to-0.2.23", from: "0.2.22", to: "0.2.23" },
+  { id: "starter-0.2.23-to-0.2.24", from: "0.2.23", to: "0.2.24" },
+  { id: "starter-0.2.24-to-0.2.25", from: "0.2.24", to: "0.2.25" }
 ];
 function resolveRecipeChain(sourceVersion, targetVersion) {
   if (sourceVersion === targetVersion)
@@ -4380,13 +4401,39 @@ import { access as access3, readFile as readFile15 } from "node:fs/promises";
 import { join as join16 } from "node:path";
 
 // src/update/known-repairs.ts
+import { createHash as createHash2 } from "node:crypto";
 var wrongTextVersions = new Set(["0.2.12", "0.2.13"]);
 var formattedBaselineVersions = new Set(["0.2.14", "0.2.15"]);
+var known023DownstreamHashes = new Map([
+  [
+    "apps/server/src/http-app.ts",
+    "9fca4e4ef68d942993f8176f2d6c508607d7c54c71d80982c966132b3a2572ce"
+  ],
+  [
+    "apps/server/src/observability/http-observability.test.ts",
+    "55598b65792606fe80bb5355b2004440ee05aa64f5eedc2662680219d3678fe2"
+  ],
+  [
+    "apps/server/src/observability/http-observability.ts",
+    "90a2ee14a2b905c705deb086d8fbeeded5c1e9d345e7f83141c33fcd73f794f3"
+  ],
+  [
+    "docs/operations/observability.md",
+    "f7618d173f9f985b15bf71f0c1c00338dad53395ba6c249c3ce3f9443e5e756f"
+  ],
+  [
+    "packages/modules/src/system-modules.ts",
+    "81fb08f26e5baa3238606d62b9c46761a68c90f3967ea639b178c80c74c69fc1"
+  ]
+]);
 var wrongExampleDescription = "创建时包含了 `work-order` 示例模块，用于演示 Module Manifest 接入；它不是生产工单产品，可以在正式开发前替换。";
 var correctCoreDescription = "创建时未选择 `work-order` 示例模块，当前项目只包含平台模块。";
 var wrongExampleRow = /^\|\s*示例工单\s*\|\s*已包含\s*\|$/m;
 var correctCoreRow = /^\|\s*示例工单\s*\|\s*未包含\s*\|$/m;
 function repairKnownDerivedFile(input) {
+  const downstreamRepair = repairKnown023Downstream(input);
+  if (downstreamRepair !== undefined)
+    return downstreamRepair;
   if (input.path !== "README.md" || input.includeExample || !input.targetContent.includes(correctCoreDescription) || !correctCoreRow.test(input.targetContent)) {
     return;
   }
@@ -4404,6 +4451,57 @@ function repairKnownDerivedFile(input) {
   }
   return input.content.replace(wrongExampleDescription, correctCoreDescription).replace(wrongExampleRow, targetRow);
 }
+function repairKnown023Downstream(input) {
+  if (input.sourceVersion !== "0.2.23" || known023DownstreamHashes.get(input.path) !== contentHash(input.content)) {
+    return;
+  }
+  if (input.path === "apps/server/src/http-app.ts" || input.path === "packages/modules/src/system-modules.ts") {
+    return input.targetContent;
+  }
+  if (input.path === "apps/server/src/observability/http-observability.ts") {
+    return replaceKnown(input.content, `    if (!isImportantRequest(input.request.method, statusCode, durationMs)) {`, `    if (durationMs === undefined) return;
+    if (!isImportantRequest(input.request.method, statusCode, durationMs)) {`);
+  }
+  if (input.path === "apps/server/src/observability/http-observability.test.ts") {
+    const targetTest = extractTest(input.targetContent, "同一次 observation 重复完成时不重复记录日志");
+    return targetTest ? replaceKnown(input.content, `
+});
+`, `
+${targetTest}
+});
+`) : undefined;
+  }
+  if (input.path === "docs/operations/observability.md") {
+    const lifecycle = extractSectionLead(input.targetContent, "请求观测在全局 `onRequest` 建立", "## Server 指标");
+    const verification = extractSectionLead(input.targetContent, "已验证：共享关联标识校验", "尚未由本页证明");
+    const withLifecycle = lifecycle ? replaceKnown(input.content, `
+## Server 指标`, `
+${lifecycle}
+## Server 指标`) : undefined;
+    return withLifecycle && verification ? replaceKnown(withLifecycle, /^已验证：共享关联标识校验.*Dockerfile 已声明 readiness `HEALTHCHECK`。$/m, verification.trim()) : undefined;
+  }
+}
+function contentHash(content) {
+  return createHash2("sha256").update(content).digest("hex");
+}
+function replaceKnown(content, search, replacement) {
+  const replaced = content.replace(search, replacement);
+  return replaced === content ? undefined : replaced;
+}
+function extractTest(content, title) {
+  const marker = `  test("${title}"`;
+  const start = content.indexOf(marker);
+  if (start < 0)
+    return;
+  const end = content.indexOf(`
+  });`, start);
+  return end < 0 ? undefined : content.slice(start, end + 6);
+}
+function extractSectionLead(content, startText, endText) {
+  const start = content.indexOf(startText);
+  const end = content.indexOf(endText, start);
+  return start < 0 || end < 0 ? undefined : content.slice(start, end);
+}
 function normalizeMarkdownTables(content) {
   return content.split(`
 `).map((line) => {
@@ -4960,7 +5058,7 @@ async function planFile(path2, project, baseRoot, targetRoot, source, target, pr
     targetContent: new TextDecoder().decode(theirs)
   }) : undefined;
   if (repaired !== undefined) {
-    return ready(path2, ownership, "update", "修复已发布版本的模块选择派生文本", new TextEncoder().encode(repaired));
+    return ready(path2, ownership, "update", "修复已发布版本的确定性派生差异", new TextEncoder().encode(repaired));
   }
   if (path2.startsWith("packages/database/drizzle/") && path2.endsWith(".sql")) {
     if (source && !target)

package/package.json

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

package/template/.agents/skills/windy-business-module/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: windy-business-module
+description: "Windy 业务模块、Manifest、Repository、Service、Agent Tool 与 MCP 接入开发。"
+---
+
+# Windy 业务模块开发
+
+用于新增或修改业务能力。先读取仓库 `AGENTS.md`、`CONTEXT.md` 和直接相关的
+`docs/architecture/`、`docs/development/`、`docs/platform/` 文档。
+
+## 工作流
+
+1. 选择一个稳定的能力基础 Key 和模块命名空间。先定义业务边界、Actor、数据归属与
+   失败语义，再改代码。
+2. 在业务 package 的 Module Manifest 一次性注册 Feature、Permission、API、
+   菜单/入口、审计动作，以及需要的 Task、Provider、JSON Schema 和 Tool。
+3. 数据层使用 Drizzle Schema、前向 Migration 和 Repository；Service 持有业务规则，
+   其它模块只能通过 Service、公开 Port 或模块注册机制协作。
+4. Server 通过 `InstallableServerModule` 和 `ModuleHost` 注册 Guarded Route、Task、
+   Provider 或 Tool Handler。Handler 调用 Service，不直接访问其它模块 Repository。
+5. Tool 输入输出只使用 Manifest 已注册的顶层 object JSON Schema。Actor、Permission、
+   Feature、License 和 Data Scope 只来自 `ModuleToolContext` 与平台 Runtime。
+6. 若项目包含 `system.agent`，`operation=query` 的 Tool 会由同一 Registry 自动进入
+   MCP；不要编辑 MCP Adapter 或复制 Tool 定义。写操作在幂等、审批和结果追踪闭环前
+   不通过 MCP 暴露。
+7. 补 Manifest/Composition、Repository/Service、Guard 拒绝和 Handler 契约测试。
+   涉及 Tool 时还要覆盖 Schema 拒绝、数据范围与未授权发现/调用；涉及可选模块时覆盖
+   Starter 的文件、依赖和数据库裁剪。
+8. 更新长期文档，运行受影响测试、`bun run typecheck` 和 `bun run lint`，按一个完整
+   小切片提交。
+
+## 代码事实源
+
+- Manifest 与 Tool 类型：`packages/modules/src/manifest.ts`
+- Tool 组合校验：`packages/modules/src/tool-composition.ts`
+- 模块 Host 契约：`packages/server-sdk/src/module-host.ts`
+- Tool Handler 契约：`packages/server-sdk/src/tool-registration.ts`
+- 可移除业务示例：`packages/example-work-order/`、`apps/server/src/work-order/`
+- 业务模块安装入口：`apps/server/src/installed-business-modules.ts`
+- MCP 与统一执行边界：`docs/architecture/mcp-business-capabilities.md`
+
+缺少 `system.agent` 或某个事实源文件时，先说明当前生成组合的物理边界，不在业务层补一套
+替代实现。

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "f2654d540f41983bc830c0333211223bf6578444",
-  "generatorVersion": "0.2.23",
+  "templateCommit": "02fc178560c17d0e17022dd785ff1f11e5350179",
+  "generatorVersion": "0.2.25",
   "modules": [
     {
       "name": "system",

package/template/AGENTS.md

@@ -42,6 +42,8 @@
 
 ## 常用入口
 
+- `.agents/skills/windy-business-module/SKILL.md`：新增或修改业务模块、Agent Tool
+  或 MCP 暴露时使用的仓库内开发流程。
 - `bun run dev`：复用 Docker 镜像启动 PostgreSQL、自动 migration、Server 与支持热更新的 Web。
 - `bun run dev:build`：依赖、Dockerfile 或 lockfile 变化后重建并启动开发环境。
 - `bun run dev:web`：启动 Web 开发服务。

package/template/apps/server/package.json

@@ -10,6 +10,8 @@
   },
   "dependencies": {
     "@elysiajs/swagger": "^1.3.1",
+    "@modelcontextprotocol/sdk": "^1",
+    "@noble/ed25519": "^3.1.0",
     "@southwind-ai/config": "workspace:*",
     "@southwind-ai/database": "workspace:*",
     "@southwind-ai/example-work-order": "workspace:*",
@@ -19,7 +21,7 @@
     "@southwind-ai/server-sdk": "workspace:*",
     "@southwind-ai/shared": "workspace:*",
     "@southwind-ai/storage": "workspace:*",
-    "@noble/ed25519": "^3.1.0",
+    "ajv": "^8.20.0",
     "argon2": "^0.44.0",
     "drizzle-orm": "^0.45.2",
     "elysia": "^1.4.29",

package/template/apps/server/src/agent/data-scope-routes.test.ts

@@ -12,6 +12,7 @@ import {
   type ModuleToolHandlers,
   registerAgentRoutes,
 } from "./routes.js";
+import { GovernedToolRegistry } from "./tool-registry.js";
 
 describe("Agent Tool data scope", () => {
   test("启动时拒绝 Manifest 与 Handler 不一致", () => {
@@ -27,21 +28,16 @@ describe("Agent Tool data scope", () => {
       execute: () => ({ items: [], total: 0, page: 1, pageSize: 10 }),
     });
 
-    expect(() =>
-      registerAgentRoutes(
-        new FakeRouteApp(),
-        loadFoundationModules(),
-        missing as ModuleToolHandlers,
-        runtime,
-      ),
+    expect(
+      () =>
+        new GovernedToolRegistry(
+          loadFoundationModules(),
+          missing as ModuleToolHandlers,
+          runtime,
+        ),
     ).toThrow("缺少 Handler");
-    expect(() =>
-      registerAgentRoutes(
-        new FakeRouteApp(),
-        loadFoundationModules(),
-        extra,
-        runtime,
-      ),
+    expect(
+      () => new GovernedToolRegistry(loadFoundationModules(), extra, runtime),
     ).toThrow("Handler 未声明");
   });
 
@@ -70,9 +66,11 @@ describe("Agent Tool data scope", () => {
     );
     registerAgentRoutes(
       app,
-      loadFoundationModules(),
-      createSystemToolHandlers(repositories, runtime),
-      runtime,
+      new GovernedToolRegistry(
+        loadFoundationModules(),
+        createSystemToolHandlers(repositories, runtime),
+        runtime,
+      ),
     );
     guardContext.actor = {
       ...guardContext.actor,
@@ -103,9 +101,11 @@ describe("Agent Tool data scope", () => {
     const app = new FakeRouteApp();
     registerAgentRoutes(
       app,
-      loadFoundationModules(),
-      createSystemToolHandlers(createSystemRepositories(snapshot), runtime),
-      runtime,
+      new GovernedToolRegistry(
+        loadFoundationModules(),
+        createSystemToolHandlers(createSystemRepositories(snapshot), runtime),
+        runtime,
+      ),
     );
     const guardContext = await runtime.createGuardContext(
       authenticatedRequest(),

package/template/apps/server/src/agent/remote-runtime.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import type { AgentRuntimeOperation } from "./run-contracts.js";
+import { RemoteAgentRuntime } from "./remote-runtime.js";
+
+const servers: Bun.Server<unknown>[] = [];
+
+afterEach(() => {
+  for (const server of servers.splice(0)) server.stop(true);
+});
+
+describe("RemoteAgentRuntime", () => {
+  test("只向 Agent Server 序列化远端支持的运行限制", async () => {
+    let received: unknown;
+    const server = Bun.serve({
+      port: 0,
+      async fetch(request) {
+        received = await request.json();
+        return Response.json({
+          runId: "run_1",
+          status: "accepted",
+          eventsUrl: "/api/agent/runs/run_1/events",
+        });
+      },
+    });
+    servers.push(server);
+
+    const manifestLimits = {
+      maxDurationSeconds: 60,
+      maxInputBytes: 4_096,
+      maxOutputBytes: 8_192,
+    };
+    const operation: AgentRuntimeOperation = {
+      operationKey: "business.answer",
+      input: { question: "你好" },
+      instructions: "只回答当前业务问题。",
+      userPrompt: "你好",
+      allowedTools: [],
+      limits: manifestLimits,
+      executionGrant: "grant_1",
+    };
+    const runtime = new RemoteAgentRuntime({
+      baseUrl: server.url.toString(),
+      internalToken: "test-token",
+      toolHostUrl: "http://server.internal/api/agent/tools",
+    });
+
+    await runtime.start(operation, "request-1");
+
+    expect(received).toMatchObject({
+      limits: {
+        maxDurationSeconds: 60,
+        maxOutputBytes: 8_192,
+      },
+    });
+    expect(
+      (received as { limits: Record<string, unknown> }).limits,
+    ).not.toHaveProperty("maxInputBytes");
+  });
+});

package/template/apps/server/src/agent/remote-runtime.ts

@@ -27,16 +27,26 @@ export class RemoteAgentRuntime implements AgentRuntimePort {
     request: AgentRuntimeOperation,
     idempotencyKey: string,
   ): Promise<AgentRuntimeStartResponse> {
+    const remoteRequest: RemoteStartRunRequest = {
+      operationKey: request.operationKey,
+      input: request.input,
+      instructions: request.instructions,
+      userPrompt: request.userPrompt,
+      allowedTools: request.allowedTools,
+      limits: {
+        maxDurationSeconds: request.limits.maxDurationSeconds,
+        maxOutputBytes: request.limits.maxOutputBytes,
+      },
+      executionGrant: request.executionGrant,
+      toolHostUrl: this.options.toolHostUrl,
+    };
     const response = await this.request("/api/agent/runs", {
       method: "POST",
       headers: {
         "content-type": "application/json",
         "idempotency-key": idempotencyKey,
       },
-      body: JSON.stringify({
-        ...request,
-        toolHostUrl: this.options.toolHostUrl,
-      }),
+      body: JSON.stringify(remoteRequest),
     });
     if (!response.ok) throw await remoteError(response);
     return (await response.json()) as AgentRuntimeStartResponse;
@@ -96,6 +106,14 @@ export class RemoteAgentRuntime implements AgentRuntimePort {
   }
 }
 
+interface RemoteStartRunRequest extends Omit<AgentRuntimeOperation, "limits"> {
+  limits: {
+    maxDurationSeconds: number;
+    maxOutputBytes: number;
+  };
+  toolHostUrl: string;
+}
+
 function normalizeInternalUrl(raw: string): string {
   const url = new URL(raw);
   if (!["http:", "https:"].includes(url.protocol)) {

package/template/apps/server/src/agent/routes.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, test } from "bun:test";
-import { entitlementKey, type FeatureFlagDefinition } from "@southwind-ai/shared";
+import {
+  entitlementKey,
+  type FeatureFlagDefinition,
+} from "@southwind-ai/shared";
 import {
   createFoundationSnapshot,
   loadFoundationModules,
@@ -8,6 +11,7 @@ import { createServerRuntime } from "../runtime.js";
 import type { RouteApp } from "../system/routes.js";
 import { createSystemRepositories } from "../system/seed.js";
 import { createSystemToolHandlers, registerAgentRoutes } from "./routes.js";
+import { GovernedToolRegistry } from "./tool-registry.js";
 
 class FakeRouteApp implements RouteApp {
   readonly handlers = new Map<string, (context: unknown) => unknown>();
@@ -44,12 +48,14 @@ function routeFixture(features?: FeatureFlagDefinition[]) {
   }
   registerAgentRoutes(
     app,
-    modules,
-    createSystemToolHandlers(
-      createSystemRepositories(createFoundationSnapshot()),
+    new GovernedToolRegistry(
+      modules,
+      createSystemToolHandlers(
+        createSystemRepositories(createFoundationSnapshot()),
+        runtime,
+      ),
       runtime,
     ),
-    runtime,
   );
   return { app, runtime };
 }
@@ -191,9 +197,11 @@ describe("agent routes", () => {
     const app = new FakeRouteApp();
     registerAgentRoutes(
       app,
-      loadFoundationModules(),
-      createSystemToolHandlers(repositories, runtime),
-      runtime,
+      new GovernedToolRegistry(
+        loadFoundationModules(),
+        createSystemToolHandlers(repositories, runtime),
+        runtime,
+      ),
     );
     const request = () =>
       new Request(