create-windy 0.2.20 → 0.2.21

package/template/apps/server/src/index.ts

@@ -21,6 +21,7 @@ import {
   createSystemToolHandlers,
   registerAgentRoutes,
 } from "./agent/routes.js";
+import { registerAgentPlatformRuntime } from "./agent/runtime-bootstrap.js";
 // @windy-module system.agent end
 import { registerAuthRoutes, registerAuthSessionRoute } from "./auth/routes.js";
 import { createAuthRuntime } from "./auth/runtime.js";
@@ -55,7 +56,7 @@ import { registerNotificationRoutes } from "./notification/routes.js";
 import { createStorageRuntime } from "./storage/runtime.js";
 import { registerStorageRoutes } from "./storage/routes.js";
 // @windy-module system.storage end
-import { validateServerModuleComposition } from "./module-composition.js";
+import { validateInstalledRuntime } from "./module-runtime-validation.js";
 import {
   adaptModuleSearchProviders,
   createModuleTaskDefinitions,
@@ -288,6 +289,14 @@ const toolHandlers = new Map([
   ...createModuleToolHandlerMap(moduleHosts),
 ]);
 registerAgentRoutes(app, foundationModules, toolHandlers, runtime);
+registerAgentPlatformRuntime({
+  app,
+  platformConfig,
+  modules: foundationModules,
+  hosts: moduleHosts,
+  runtime,
+  toolHandlers,
+});
 // @windy-module system.agent end
 // @windy-module system.scheduler begin
 registerSchedulerRoutes(app, scheduler, runtime, foundationSnapshot.features);
@@ -312,30 +321,17 @@ installModuleRoutes(moduleHosts, app, {
 });
 // @windy-module work-order end
 
-validateServerModuleComposition({
+validateInstalledRuntime({
   modules: foundationModules,
   routes: app.routes,
   // @windy-module system.scheduler begin
   tasks: scheduledTaskDefinitions,
   // @windy-module system.scheduler end
-  // @windy-module system.agent begin
   tools: toolHandlers,
-  // @windy-module system.agent end
   // @windy-module system.search begin
   providers: searchHost.providerKeys,
   // @windy-module system.search end
-  moduleRegistrations: {
-    routes: moduleHosts.routes.map(
-      ({ definition }) => `${definition.method} ${definition.path}`,
-    ),
-    tasks: moduleHosts.taskHandlers.map(
-      ({ registration }) => registration.taskKey,
-    ),
-    tools: moduleHosts.toolHandlers.map(
-      ({ registration }) => registration.toolKey,
-    ),
-    providers: moduleHosts.searchProviders.map(({ provider }) => provider.key),
-  },
+  hosts: moduleHosts,
 });
 
 const port = process.env.PORT ? Number(process.env.PORT) : 9_747;

package/template/apps/server/src/module-composition.test.ts

@@ -73,6 +73,15 @@ describe("Server Module Composition", () => {
         moduleRegistrations: { providers: ["system.unknown-search"] },
       }),
     ).toThrow("搜索 Provider已注册但未在 Manifest 声明：system.unknown-search");
+
+    expect(() =>
+      validateServerModuleComposition({
+        ...base,
+        moduleRegistrations: { aiOperations: ["system.unknown-operation"] },
+      }),
+    ).toThrow(
+      "AI Operation Handler已注册但未在 Manifest 声明：system.unknown-operation",
+    );
   });
 });
 

package/template/apps/server/src/module-composition.ts

@@ -16,6 +16,7 @@ export interface ModuleImplementationRegistrations {
   routes?: readonly string[];
   tasks?: readonly string[];
   tools?: readonly string[];
+  aiOperations?: readonly string[];
   providers?: readonly string[];
 }
 
@@ -24,6 +25,7 @@ export interface ServerCompositionInput {
   routes: readonly RegisteredHttpRoute[];
   tasks?: readonly { key: string }[];
   tools?: ReadonlyMap<string, unknown>;
+  aiOperations?: readonly string[];
   providers?: readonly string[];
   moduleRegistrations?: ModuleImplementationRegistrations;
 }
@@ -35,6 +37,7 @@ export function validateServerModuleComposition(
     apiRoutes: input.routes.map(apiRouteKey),
     tasks: (input.tasks || []).map(({ key }) => key),
     tools: [...(input.tools?.keys() || [])],
+    aiOperations: input.aiOperations,
     providers: input.providers || [],
   });
   if (input.moduleRegistrations) {
@@ -55,6 +58,11 @@ function validateRegistrationConsistency(
   const declaredTools = new Set(
     modules.flatMap((module) => module.tools.map(({ key }) => key)),
   );
+  const declaredAiOperations = new Set(
+    modules.flatMap((module) =>
+      (module.aiOperations ?? []).map(({ key }) => key),
+    ),
+  );
   const declaredProviders = new Set(
     modules.flatMap((module) => module.providers.map(({ key }) => key)),
   );
@@ -62,6 +70,11 @@ function validateRegistrationConsistency(
     ["模块路由", registrations.routes || [], declaredRoutes],
     ["定时任务 Handler", registrations.tasks || [], declaredTasks],
     ["Agent Tool Handler", registrations.tools || [], declaredTools],
+    [
+      "AI Operation Handler",
+      registrations.aiOperations || [],
+      declaredAiOperations,
+    ],
     ["搜索 Provider", registrations.providers || [], declaredProviders],
   ] as const) {
     for (const key of registered) {

package/template/apps/server/src/module-host/initialize-contracts.ts

@@ -0,0 +1,67 @@
+import type { DurableHandlerRegistry } from "@southwind-ai/jobs";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  InstallableServerModule,
+  ModuleAiOperationHandlerRegistration,
+  ModuleInitializer,
+  ModuleRolePreset,
+  ModuleRouteDefinition,
+  ModuleSearchProvider,
+  ModuleTaskHandlerRegistration,
+  ModuleToolHandlerRegistration,
+  ModuleUploadPolicy,
+} from "@southwind-ai/server-sdk";
+
+export interface RegisteredModuleRoute {
+  readonly moduleName: string;
+  readonly definition: ModuleRouteDefinition;
+}
+
+export interface RegisteredModuleTaskHandler {
+  readonly moduleName: string;
+  readonly registration: ModuleTaskHandlerRegistration;
+}
+
+export interface RegisteredModuleToolHandler {
+  readonly moduleName: string;
+  readonly registration: ModuleToolHandlerRegistration;
+}
+
+export interface RegisteredModuleAiOperationHandler {
+  readonly moduleName: string;
+  readonly registration: ModuleAiOperationHandlerRegistration;
+}
+
+export interface RegisteredModuleRolePreset {
+  readonly moduleName: string;
+  readonly preset: ModuleRolePreset;
+}
+
+export interface RegisteredModuleSearchProvider {
+  readonly moduleName: string;
+  readonly provider: ModuleSearchProvider;
+}
+
+export interface InitializeModuleHostsInput {
+  modules: readonly ModuleManifest[];
+  /** Manifest 与 setup 由同一业务模块安装单元贡献。 */
+  installations?: readonly InstallableServerModule<ModuleManifest>[];
+  /** @deprecated 仅供旧模块迁移；新模块必须使用 installations。 */
+  initializers?: readonly ModuleInitializer[];
+  baseUploadPolicies?: readonly ModuleUploadPolicy[];
+}
+
+export interface InitializedModuleHosts {
+  readonly manifests: readonly ModuleManifest[];
+  readonly uploadPolicies: readonly ModuleUploadPolicy[];
+  readonly routes: readonly RegisteredModuleRoute[];
+  readonly taskHandlers: readonly RegisteredModuleTaskHandler[];
+  readonly toolHandlers: readonly RegisteredModuleToolHandler[];
+  readonly aiOperationHandlers: readonly RegisteredModuleAiOperationHandler[];
+  readonly rolePresets: readonly RegisteredModuleRolePreset[];
+  readonly searchProviders: readonly RegisteredModuleSearchProvider[];
+  manifestOf(moduleName: string): ModuleManifest;
+  /** 该模块经 Host 注册的上传用途集合（不含平台基础用途）。 */
+  uploadPurposesOf(moduleName: string): ReadonlySet<string>;
+  installDurableHandlers(registry: DurableHandlerRegistry): void;
+}

package/template/apps/server/src/module-host/initialize.test.ts

@@ -102,6 +102,75 @@ describe("模块 Host 初始化", () => {
       }),
     ).rejects.toThrow("Server Module Manifest 与能力目录不是同一声明：known");
   });
+
+  test("AI Operation Handler 只注册本模块 Manifest 声明", async () => {
+    const operation = {
+      key: "known.summarize",
+      kind: "agent" as const,
+      featureKey: "known.ai",
+      permissionKey: "known.ai.execute",
+      auditAction: "known.ai.execute",
+      inputSchemaKey: "known.input.v1",
+      outputSchemaKey: "known.output.v1",
+      requiredCapabilities: ["text-generation"],
+      allowedToolKeys: [],
+      dataClassification: "internal" as const,
+      execution: "streaming" as const,
+      publicNetworkAccess: "forbidden" as const,
+      limits: {
+        maxDurationSeconds: 60,
+        maxInputBytes: 4096,
+        maxOutputBytes: 4096,
+      },
+    };
+    const known = manifest("known", { aiOperations: [operation] });
+    const initialized = await initializeModuleHosts({
+      modules: [known],
+      installations: [
+        {
+          manifest: known,
+          setup(host) {
+            host.registerAiOperationHandlers([
+              {
+                operationKey: operation.key,
+                prepare: () => ({
+                  instructions: "按要求回答。",
+                  userPrompt: "你好",
+                }),
+              },
+            ]);
+          },
+        },
+      ],
+    });
+    expect(
+      initialized.aiOperationHandlers.map(
+        ({ registration }) => registration.operationKey,
+      ),
+    ).toEqual(["known.summarize"]);
+
+    await expect(
+      initializeModuleHosts({
+        modules: [known],
+        installations: [
+          {
+            manifest: known,
+            setup(host) {
+              host.registerAiOperationHandlers([
+                {
+                  operationKey: "known.unknown",
+                  prepare: () => ({
+                    instructions: "x",
+                    userPrompt: "x",
+                  }),
+                },
+              ]);
+            },
+          },
+        ],
+      }),
+    ).rejects.toThrow("AI Operation Handler 未在 Manifest 声明");
+  });
 });
 
 function initializer(

package/template/apps/server/src/module-host/initialize.ts

@@ -5,64 +5,31 @@ import {
 import type { ModuleManifest } from "@southwind-ai/modules";
 import {
   requireModuleNamespace,
-  type InstallableServerModule,
   type ModuleHost,
-  type ModuleInitializer,
-  type ModuleRolePreset,
   type ModuleRouteDefinition,
-  type ModuleSearchProvider,
-  type ModuleTaskHandlerRegistration,
-  type ModuleToolHandlerRegistration,
   type ModuleUploadPolicy,
 } from "@southwind-ai/server-sdk";
+import type {
+  InitializedModuleHosts,
+  InitializeModuleHostsInput,
+  RegisteredModuleAiOperationHandler,
+  RegisteredModuleRolePreset,
+  RegisteredModuleRoute,
+  RegisteredModuleSearchProvider,
+  RegisteredModuleTaskHandler,
+  RegisteredModuleToolHandler,
+} from "./initialize-contracts.js";
 
-export interface RegisteredModuleRoute {
-  readonly moduleName: string;
-  readonly definition: ModuleRouteDefinition;
-}
-
-export interface RegisteredModuleTaskHandler {
-  readonly moduleName: string;
-  readonly registration: ModuleTaskHandlerRegistration;
-}
-
-export interface RegisteredModuleToolHandler {
-  readonly moduleName: string;
-  readonly registration: ModuleToolHandlerRegistration;
-}
-
-export interface RegisteredModuleRolePreset {
-  readonly moduleName: string;
-  readonly preset: ModuleRolePreset;
-}
-
-export interface RegisteredModuleSearchProvider {
-  readonly moduleName: string;
-  readonly provider: ModuleSearchProvider;
-}
-
-export interface InitializeModuleHostsInput {
-  modules: readonly ModuleManifest[];
-  /** Manifest 与 setup 由同一业务模块安装单元贡献。 */
-  installations?: readonly InstallableServerModule<ModuleManifest>[];
-  /** @deprecated 仅供旧模块迁移；新模块必须使用 installations。 */
-  initializers?: readonly ModuleInitializer[];
-  baseUploadPolicies?: readonly ModuleUploadPolicy[];
-}
-
-export interface InitializedModuleHosts {
-  readonly manifests: readonly ModuleManifest[];
-  readonly uploadPolicies: readonly ModuleUploadPolicy[];
-  readonly routes: readonly RegisteredModuleRoute[];
-  readonly taskHandlers: readonly RegisteredModuleTaskHandler[];
-  readonly toolHandlers: readonly RegisteredModuleToolHandler[];
-  readonly rolePresets: readonly RegisteredModuleRolePreset[];
-  readonly searchProviders: readonly RegisteredModuleSearchProvider[];
-  manifestOf(moduleName: string): ModuleManifest;
-  /** 该模块经 Host 注册的上传用途集合（不含平台基础用途）。 */
-  uploadPurposesOf(moduleName: string): ReadonlySet<string>;
-  installDurableHandlers(registry: DurableHandlerRegistry): void;
-}
+export type {
+  InitializedModuleHosts,
+  InitializeModuleHostsInput,
+  RegisteredModuleAiOperationHandler,
+  RegisteredModuleRolePreset,
+  RegisteredModuleRoute,
+  RegisteredModuleSearchProvider,
+  RegisteredModuleTaskHandler,
+  RegisteredModuleToolHandler,
+} from "./initialize-contracts.js";
 
 type HandlerInstaller = (registry: DurableHandlerRegistry) => void;
 
@@ -94,6 +61,8 @@ export async function initializeModuleHosts(
     taskKeys: new Set<string>(),
     toolHandlers: [],
     toolKeys: new Set<string>(),
+    aiOperationHandlers: [],
+    aiOperationKeys: new Set<string>(),
     rolePresets: [],
     rolePresetKeys: new Set<string>(),
     searchProviders: [],
@@ -142,6 +111,7 @@ export async function initializeModuleHosts(
     routes: [...state.routes],
     taskHandlers: [...state.taskHandlers],
     toolHandlers: [...state.toolHandlers],
+    aiOperationHandlers: [...state.aiOperationHandlers],
     rolePresets: [...state.rolePresets],
     searchProviders: [...state.searchProviders],
     manifestOf(moduleName) {
@@ -170,6 +140,8 @@ interface HostCollections {
   taskKeys: Set<string>;
   toolHandlers: RegisteredModuleToolHandler[];
   toolKeys: Set<string>;
+  aiOperationHandlers: RegisteredModuleAiOperationHandler[];
+  aiOperationKeys: Set<string>;
   rolePresets: RegisteredModuleRolePreset[];
   rolePresetKeys: Set<string>;
   searchProviders: RegisteredModuleSearchProvider[];
@@ -253,6 +225,31 @@ function createScopedHost(
         state.toolHandlers.push({ moduleName, registration });
       }
     },
+    registerAiOperationHandlers(registrations) {
+      for (const registration of registrations) {
+        requireModuleNamespace(
+          "AI Operation",
+          registration.operationKey,
+          moduleName,
+        );
+        if (
+          !manifest.aiOperations?.some(
+            ({ key }) => key === registration.operationKey,
+          )
+        ) {
+          throw new Error(
+            `AI Operation Handler 未在 Manifest 声明：${registration.operationKey}`,
+          );
+        }
+        if (state.aiOperationKeys.has(registration.operationKey)) {
+          throw new Error(
+            `AI Operation Handler 重复注册：${registration.operationKey}`,
+          );
+        }
+        state.aiOperationKeys.add(registration.operationKey);
+        state.aiOperationHandlers.push({ moduleName, registration });
+      }
+    },
     registerRolePresets(presets) {
       for (const preset of presets) {
         requireModuleNamespace("角色预设", preset.key, moduleName);

package/template/apps/server/src/module-host.ts

@@ -7,6 +7,7 @@ export {
   type RegisteredModuleSearchProvider,
   type RegisteredModuleTaskHandler,
   type RegisteredModuleToolHandler,
+  type RegisteredModuleAiOperationHandler,
 } from "./module-host/initialize.js";
 export {
   buildModuleRequestContext,

package/template/apps/server/src/module-runtime-validation.ts

@@ -0,0 +1,40 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { ModuleToolHandlers } from "./agent/routes.js";
+import { validateServerModuleComposition } from "./module-composition.js";
+import type { InitializedModuleHosts } from "./module-host.js";
+
+export function validateInstalledRuntime(input: {
+  modules: ModuleManifest[];
+  routes: readonly { method: string; path: string }[];
+  tasks: readonly { key: string }[];
+  tools: ModuleToolHandlers;
+  providers: readonly string[];
+  hosts: InitializedModuleHosts;
+}): void {
+  const aiOperations = input.hosts.aiOperationHandlers.map(
+    ({ registration }) => registration.operationKey,
+  );
+  validateServerModuleComposition({
+    modules: input.modules,
+    routes: input.routes,
+    tasks: input.tasks,
+    tools: input.tools,
+    aiOperations,
+    providers: input.providers,
+    moduleRegistrations: {
+      routes: input.hosts.routes.map(
+        ({ definition }) => `${definition.method} ${definition.path}`,
+      ),
+      tasks: input.hosts.taskHandlers.map(
+        ({ registration }) => registration.taskKey,
+      ),
+      tools: input.hosts.toolHandlers.map(
+        ({ registration }) => registration.toolKey,
+      ),
+      aiOperations,
+      providers: input.hosts.searchProviders.map(
+        ({ provider }) => provider.key,
+      ),
+    },
+  });
+}

package/template/docker-compose.yml

@@ -42,6 +42,10 @@ 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:
@@ -52,6 +56,26 @@ services:
       migrate:
         condition: service_completed_successfully
 
+  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
+
   web:
     build:
       context: .
@@ -85,3 +109,4 @@ services:
 volumes:
   postgres-data:
   server-audit-data:
+  agent-run-data: