create-windy 0.2.19 → 0.2.21

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

@@ -26,8 +26,61 @@ describe("Server Module Composition", () => {
           { method: "POST", path: "/api/auth/users/:id/password" },
         ],
       }),
+    ).toThrow("API Route Handler Key 重复：POST /api/auth/users/:id/password");
+  });
+
+  test("Host 注册实现必须在 Manifest 声明", () => {
+    const app = new Elysia({ prefix: "/api" }).post(
+      "/auth/users/:id/password",
+      () => null,
+    );
+    const base = {
+      modules: [fixture()],
+      routes: app.routes,
+      tasks: [],
+      tools: new Map(),
+      providers: [],
+    };
+
+    expect(() =>
+      validateServerModuleComposition({
+        ...base,
+        moduleRegistrations: {
+          routes: ["POST /api/auth/users/:id/password"],
+        },
+      }),
+    ).not.toThrow();
+
+    expect(() =>
+      validateServerModuleComposition({
+        ...base,
+        moduleRegistrations: { routes: ["GET /api/auth/users"] },
+      }),
+    ).toThrow("模块路由已注册但未在 Manifest 声明：GET /api/auth/users");
+
+    expect(() =>
+      validateServerModuleComposition({
+        ...base,
+        moduleRegistrations: { tasks: ["system.unknown-task"] },
+      }),
+    ).toThrow(
+      "定时任务 Handler已注册但未在 Manifest 声明：system.unknown-task",
+    );
+
+    expect(() =>
+      validateServerModuleComposition({
+        ...base,
+        moduleRegistrations: { providers: ["system.unknown-search"] },
+      }),
+    ).toThrow("搜索 Provider已注册但未在 Manifest 声明：system.unknown-search");
+
+    expect(() =>
+      validateServerModuleComposition({
+        ...base,
+        moduleRegistrations: { aiOperations: ["system.unknown-operation"] },
+      }),
     ).toThrow(
-      "API Route Handler Key 重复：POST /api/auth/users/:id/password",
+      "AI Operation Handler已注册但未在 Manifest 声明：system.unknown-operation",
     );
   });
 });

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

@@ -8,12 +8,26 @@ interface RegisteredHttpRoute {
   path: string;
 }
 
+/**
+ * 模块经 Host 注册的实现 Key，用于校验“实现了但没在 Manifest 声明”。
+ * 反向（声明了没实现）由 validateModuleComposition 的实现绑定校验覆盖。
+ */
+export interface ModuleImplementationRegistrations {
+  routes?: readonly string[];
+  tasks?: readonly string[];
+  tools?: readonly string[];
+  aiOperations?: readonly string[];
+  providers?: readonly string[];
+}
+
 export interface ServerCompositionInput {
   modules: readonly ModuleManifest[];
   routes: readonly RegisteredHttpRoute[];
   tasks?: readonly { key: string }[];
   tools?: ReadonlyMap<string, unknown>;
+  aiOperations?: readonly string[];
   providers?: readonly string[];
+  moduleRegistrations?: ModuleImplementationRegistrations;
 }
 
 export function validateServerModuleComposition(
@@ -23,6 +37,50 @@ 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) {
+    validateRegistrationConsistency(input.modules, input.moduleRegistrations);
+  }
+}
+
+function validateRegistrationConsistency(
+  modules: readonly ModuleManifest[],
+  registrations: ModuleImplementationRegistrations,
+): void {
+  const declaredRoutes = new Set(
+    modules.flatMap((module) => module.apiPermissions.map(apiRouteKey)),
+  );
+  const declaredTasks = new Set(
+    modules.flatMap((module) => module.tasks.map(({ key }) => key)),
+  );
+  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)),
+  );
+  for (const [label, registered, declared] of [
+    ["模块路由", 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) {
+      if (!declared.has(key)) {
+        throw new Error(`${label}已注册但未在 Manifest 声明：${key}`);
+      }
+    }
+  }
 }

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

@@ -0,0 +1,192 @@
+import { describe, expect, test } from "bun:test";
+import { DurableHandlerRegistry } from "@southwind-ai/jobs";
+import type { ModuleInitializer } from "@southwind-ai/server-sdk";
+import { initializeModuleHosts } from "./initialize.js";
+import { manifest } from "./test-fixtures.js";
+
+describe("模块 Host 初始化", () => {
+  test("按安装顺序完成初始化后再创建运行时注册表", async () => {
+    const events: string[] = [];
+    const first = initializer("alpha", async (host) => {
+      events.push("alpha:start");
+      await Promise.resolve();
+      host.registerDurableHandler({
+        key: "alpha.refresh",
+        payload: { parse: () => ({}) },
+        execute: () => undefined,
+      });
+      events.push("alpha:end");
+    });
+    const second = initializer("beta", () => {
+      events.push("beta");
+    });
+
+    const initialized = await initializeModuleHosts({
+      modules: [manifest("alpha"), manifest("beta")],
+      initializers: [first, second],
+    });
+    expect(events).toEqual(["alpha:start", "alpha:end", "beta"]);
+
+    const registry = new DurableHandlerRegistry();
+    initialized.installDurableHandlers(registry);
+    expect(registry.keys()).toEqual(["alpha.refresh"]);
+  });
+
+  test("未知模块、错误命名空间和重复注册立即失败", async () => {
+    await expect(
+      initializeModuleHosts({
+        modules: [manifest("known")],
+        initializers: [initializer("missing", () => undefined)],
+      }),
+    ).rejects.toThrow("模块初始化器与已安装模块不匹配：missing");
+
+    await expect(
+      initializeModuleHosts({
+        modules: [manifest("known")],
+        initializers: [
+          initializer("known", (host) => {
+            host.registerUploadPolicy(policy("other.attachment"));
+          }),
+        ],
+      }),
+    ).rejects.toThrow("上传用途不属于模块 known：other.attachment");
+
+    await expect(
+      initializeModuleHosts({
+        modules: [manifest("known")],
+        initializers: [
+          initializer("known", (host) => {
+            host.registerUploadPolicy(policy("known.attachment"));
+            host.registerUploadPolicy(policy("known.attachment"));
+          }),
+        ],
+      }),
+    ).rejects.toThrow("上传用途重复注册：known.attachment");
+
+    await expect(
+      initializeModuleHosts({
+        modules: [],
+        initializers: [],
+        baseUploadPolicies: [policy("platform.file"), policy("platform.file")],
+      }),
+    ).rejects.toThrow("上传用途重复注册：platform.file");
+
+    await expect(
+      initializeModuleHosts({
+        modules: [manifest("known")],
+        initializers: [
+          initializer("known", (host) => {
+            const definition = {
+              key: "known.refresh",
+              payload: { parse: () => ({}) },
+              execute: () => undefined,
+            };
+            host.registerDurableHandler(definition);
+            host.registerDurableHandler(definition);
+          }),
+        ],
+      }),
+    ).rejects.toThrow("任务 handler 重复注册：known.refresh");
+  });
+
+  test("安装单元的 Manifest 必须来自同一平台能力目录", async () => {
+    await expect(
+      initializeModuleHosts({
+        modules: [manifest("known")],
+        installations: [
+          {
+            manifest: manifest("known"),
+            setup: () => undefined,
+          },
+        ],
+      }),
+    ).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(
+  moduleName: string,
+  initialize: ModuleInitializer["initialize"],
+): ModuleInitializer {
+  return { moduleName, initialize };
+}
+
+function policy(purpose: string) {
+  return {
+    purpose,
+    maxByteSize: 1024,
+    maxPartByteSize: 512,
+    sessionTtlMs: 60_000,
+    allowedTypes: { "text/plain": ["txt"] },
+    signature: "none" as const,
+  };
+}