create-windy 0.2.18 → 0.2.20

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

@@ -26,9 +26,53 @@ 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(
-      "API Route Handler Key 重复：POST /api/auth/users/:id/password",
+      "定时任务 Handler已注册但未在 Manifest 声明：system.unknown-task",
     );
+
+    expect(() =>
+      validateServerModuleComposition({
+        ...base,
+        moduleRegistrations: { providers: ["system.unknown-search"] },
+      }),
+    ).toThrow("搜索 Provider已注册但未在 Manifest 声明：system.unknown-search");
   });
 });
 

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

@@ -8,12 +8,24 @@ interface RegisteredHttpRoute {
   path: string;
 }
 
+/**
+ * 模块经 Host 注册的实现 Key，用于校验“实现了但没在 Manifest 声明”。
+ * 反向（声明了没实现）由 validateModuleComposition 的实现绑定校验覆盖。
+ */
+export interface ModuleImplementationRegistrations {
+  routes?: readonly string[];
+  tasks?: readonly string[];
+  tools?: readonly string[];
+  providers?: readonly string[];
+}
+
 export interface ServerCompositionInput {
   modules: readonly ModuleManifest[];
   routes: readonly RegisteredHttpRoute[];
   tasks?: readonly { key: string }[];
   tools?: ReadonlyMap<string, unknown>;
   providers?: readonly string[];
+  moduleRegistrations?: ModuleImplementationRegistrations;
 }
 
 export function validateServerModuleComposition(
@@ -25,4 +37,37 @@ export function validateServerModuleComposition(
     tools: [...(input.tools?.keys() || [])],
     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 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],
+    ["搜索 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.test.ts

@@ -0,0 +1,123 @@
+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");
+  });
+});
+
+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,
+  };
+}

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

@@ -0,0 +1,331 @@
+import {
+  DurableHandlerRegistry,
+  type DurableHandlerDefinition,
+} from "@southwind-ai/jobs";
+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";
+
+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;
+}
+
+type HandlerInstaller = (registry: DurableHandlerRegistry) => void;
+
+export async function initializeModuleHosts(
+  input: InitializeModuleHostsInput,
+): Promise<InitializedModuleHosts> {
+  const manifests = new Map(
+    input.modules.map((module) => [module.name, module]),
+  );
+  const initializedNames = new Set<string>();
+  const uploadPolicies: ModuleUploadPolicy[] = [];
+  const uploadPurposes = new Set<string>();
+  for (const policy of input.baseUploadPolicies ?? []) {
+    if (uploadPurposes.has(policy.purpose)) {
+      throw new Error(`上传用途重复注册：${policy.purpose}`);
+    }
+    uploadPurposes.add(policy.purpose);
+    uploadPolicies.push(policy);
+  }
+  const state: HostCollections = {
+    uploadPolicies,
+    uploadPurposes,
+    modulePurposes: new Map<string, Set<string>>(),
+    handlerKeys: new Set<string>(),
+    handlerInstallers: [],
+    routes: [],
+    routeKeys: new Set<string>(),
+    taskHandlers: [],
+    taskKeys: new Set<string>(),
+    toolHandlers: [],
+    toolKeys: new Set<string>(),
+    rolePresets: [],
+    rolePresetKeys: new Set<string>(),
+    searchProviders: [],
+    searchProviderKeys: new Set<string>(),
+  };
+
+  const installations = [
+    ...(input.installations ?? []).map((installation) => ({
+      moduleName: installation.manifest.name.trim(),
+      manifest: installation.manifest,
+      setup: installation.setup,
+      legacy: false,
+    })),
+    ...(input.initializers ?? []).map((initializer) => ({
+      moduleName: initializer.moduleName.trim(),
+      manifest: undefined,
+      setup: initializer.initialize,
+      legacy: true,
+    })),
+  ];
+  for (const installation of installations) {
+    const moduleName = installation.moduleName;
+    const manifest = manifests.get(moduleName);
+    if (!manifest) {
+      throw new Error(
+        installation.legacy
+          ? `模块初始化器与已安装模块不匹配：${moduleName}`
+          : `Server Module 与已安装模块不匹配：${moduleName}`,
+      );
+    }
+    if (initializedNames.has(moduleName)) {
+      throw new Error(`模块初始化器重复注册：${moduleName}`);
+    }
+    initializedNames.add(moduleName);
+    if (installation.manifest && installation.manifest !== manifest) {
+      throw new Error(
+        `Server Module Manifest 与能力目录不是同一声明：${moduleName}`,
+      );
+    }
+    await installation.setup(createScopedHost(manifest, state));
+  }
+
+  return {
+    manifests: input.modules,
+    uploadPolicies: [...state.uploadPolicies],
+    routes: [...state.routes],
+    taskHandlers: [...state.taskHandlers],
+    toolHandlers: [...state.toolHandlers],
+    rolePresets: [...state.rolePresets],
+    searchProviders: [...state.searchProviders],
+    manifestOf(moduleName) {
+      const manifest = manifests.get(moduleName);
+      if (!manifest) throw new Error(`模块未安装：${moduleName}`);
+      return manifest;
+    },
+    uploadPurposesOf(moduleName) {
+      return state.modulePurposes.get(moduleName) ?? new Set<string>();
+    },
+    installDurableHandlers(registry) {
+      for (const install of state.handlerInstallers) install(registry);
+    },
+  };
+}
+
+interface HostCollections {
+  uploadPolicies: ModuleUploadPolicy[];
+  uploadPurposes: Set<string>;
+  modulePurposes: Map<string, Set<string>>;
+  handlerKeys: Set<string>;
+  handlerInstallers: HandlerInstaller[];
+  routes: RegisteredModuleRoute[];
+  routeKeys: Set<string>;
+  taskHandlers: RegisteredModuleTaskHandler[];
+  taskKeys: Set<string>;
+  toolHandlers: RegisteredModuleToolHandler[];
+  toolKeys: Set<string>;
+  rolePresets: RegisteredModuleRolePreset[];
+  rolePresetKeys: Set<string>;
+  searchProviders: RegisteredModuleSearchProvider[];
+  searchProviderKeys: Set<string>;
+}
+
+function createScopedHost(
+  manifest: ModuleManifest,
+  state: HostCollections,
+): ModuleHost {
+  const moduleName = manifest.name;
+  return {
+    moduleName,
+    registerUploadPolicy(policy) {
+      requireModuleNamespace("上传用途", policy.purpose, moduleName);
+      if (state.uploadPurposes.has(policy.purpose)) {
+        throw new Error(`上传用途重复注册：${policy.purpose}`);
+      }
+      state.uploadPurposes.add(policy.purpose);
+      state.uploadPolicies.push(policy);
+      const purposes =
+        state.modulePurposes.get(moduleName) ?? new Set<string>();
+      purposes.add(policy.purpose);
+      state.modulePurposes.set(moduleName, purposes);
+    },
+    registerDurableHandler<T>(definition: DurableHandlerDefinition<T>) {
+      requireModuleNamespace("任务 handler", definition.key, moduleName);
+      if (state.handlerKeys.has(definition.key)) {
+        throw new Error(`任务 handler 重复注册：${definition.key}`);
+      }
+      state.handlerKeys.add(definition.key);
+      state.handlerInstallers.push((registry) => {
+        registry.register(definition);
+      });
+    },
+    registerRoutes(routes) {
+      for (const definition of routes) {
+        requireModuleNamespace(
+          "路由权限",
+          definition.permissionKey,
+          moduleName,
+        );
+        validateRouteDeclaration(manifest, definition);
+        const key = `${definition.method} ${definition.path}`;
+        if (state.routeKeys.has(key)) {
+          throw new Error(`模块路由重复注册：${key}`);
+        }
+        state.routeKeys.add(key);
+        state.routes.push({ moduleName, definition });
+      }
+    },
+    registerTaskHandlers(registrations) {
+      for (const registration of registrations) {
+        requireModuleNamespace("定时任务", registration.taskKey, moduleName);
+        if (!manifest.tasks.some(({ key }) => key === registration.taskKey)) {
+          throw new Error(
+            `定时任务 Handler 未在 Manifest 声明：${registration.taskKey}`,
+          );
+        }
+        if (state.taskKeys.has(registration.taskKey)) {
+          throw new Error(`定时任务 Handler 重复注册：${registration.taskKey}`);
+        }
+        state.taskKeys.add(registration.taskKey);
+        state.taskHandlers.push({ moduleName, registration });
+      }
+    },
+    registerToolHandlers(registrations) {
+      for (const registration of registrations) {
+        requireModuleNamespace("Agent Tool", registration.toolKey, moduleName);
+        if (!manifest.tools.some(({ key }) => key === registration.toolKey)) {
+          throw new Error(
+            `Agent Tool Handler 未在 Manifest 声明：${registration.toolKey}`,
+          );
+        }
+        if (state.toolKeys.has(registration.toolKey)) {
+          throw new Error(
+            `Agent Tool Handler 重复注册：${registration.toolKey}`,
+          );
+        }
+        state.toolKeys.add(registration.toolKey);
+        state.toolHandlers.push({ moduleName, registration });
+      }
+    },
+    registerRolePresets(presets) {
+      for (const preset of presets) {
+        requireModuleNamespace("角色预设", preset.key, moduleName);
+        if (state.rolePresetKeys.has(preset.key)) {
+          throw new Error(`角色预设重复注册：${preset.key}`);
+        }
+        for (const permissionKey of preset.permissionKeys) {
+          requireModuleNamespace("角色预设权限", permissionKey, moduleName);
+          if (!manifest.permissions.some(({ key }) => key === permissionKey)) {
+            throw new Error(
+              `角色预设引用了模块 ${moduleName} 未声明权限：${permissionKey}`,
+            );
+          }
+        }
+        state.rolePresetKeys.add(preset.key);
+        state.rolePresets.push({ moduleName, preset });
+      }
+    },
+    registerSearchProviders(providers) {
+      for (const provider of providers) {
+        requireModuleNamespace("搜索 Provider", provider.key, moduleName);
+        if (!manifest.providers.some(({ key }) => key === provider.key)) {
+          throw new Error(`搜索 Provider 未在 Manifest 声明：${provider.key}`);
+        }
+        if (state.searchProviderKeys.has(provider.key)) {
+          throw new Error(`搜索 Provider 重复注册：${provider.key}`);
+        }
+        state.searchProviderKeys.add(provider.key);
+        state.searchProviders.push({ moduleName, provider });
+      }
+    },
+  };
+}
+
+function validateRouteDeclaration(
+  manifest: ModuleManifest,
+  definition: ModuleRouteDefinition,
+): void {
+  const binding = manifest.apiPermissions.find(
+    (item) =>
+      item.method === definition.method && item.path === definition.path,
+  );
+  const route = `${definition.method} ${definition.path}`;
+  if (!binding) {
+    throw new Error(`模块路由未在 Manifest 声明：${route}`);
+  }
+  if (binding.permissionKey !== definition.permissionKey) {
+    throw new Error(`模块路由权限与 Manifest 声明不一致：${route}`);
+  }
+  if (
+    definition.featureKey !== undefined &&
+    binding.featureKey !== definition.featureKey
+  ) {
+    throw new Error(`模块路由 Feature 与 Manifest 声明不一致：${route}`);
+  }
+  if (
+    binding.featureKey &&
+    !manifest.features.some(({ key }) => key === binding.featureKey)
+  ) {
+    throw new Error(
+      `模块路由 Feature 未在 Manifest 注册：${binding.featureKey}`,
+    );
+  }
+  if (
+    definition.auditAction &&
+    !manifest.auditActions.some((action) =>
+      typeof action === "string"
+        ? action === definition.auditAction
+        : action.key === definition.auditAction,
+    )
+  ) {
+    throw new Error(
+      `模块路由审计动作未在 Manifest 注册：${definition.auditAction}`,
+    );
+  }
+}

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

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+import { buildScopeContext } from "../data-access/context.js";
+import type { RequestActor } from "../guards.js";
+import { requestActorFromModule, toModuleActor } from "./request-context.js";
+
+describe("模块 Actor 运行时边界", () => {
+  test("只下发 SDK 白名单字段并保留宿主内部身份映射", () => {
+    const requestActor: RequestActor = {
+      id: "user-1",
+      type: "user",
+      name: "测试用户",
+      username: "tester",
+      displayName: "测试用户",
+      email: "private@example.test",
+      phone: "13800000000",
+      credentialState: "active",
+      passwordChangedAt: "2026-07-25T00:00:00.000Z",
+      roleCodes: ["operator"],
+      permissionKeys: ["work-order.ticket.read"],
+      scopeContext: buildScopeContext("user-1", undefined, [
+        {
+          id: "role-1",
+          code: "operator",
+          dataScope: "self",
+          departmentIds: [],
+        },
+      ]),
+    };
+
+    const actor = toModuleActor(requestActor);
+
+    expect(actor).toEqual({
+      id: "user-1",
+      type: "user",
+      name: "测试用户",
+      username: "tester",
+      displayName: "测试用户",
+      roleCodes: ["operator"],
+      permissionKeys: ["work-order.ticket.read"],
+    });
+    expect(Object.keys(actor).sort()).toEqual([
+      "displayName",
+      "id",
+      "name",
+      "permissionKeys",
+      "roleCodes",
+      "type",
+      "username",
+    ]);
+    expect(Object.isFrozen(actor)).toBe(true);
+    expect(Object.isFrozen(actor.roleCodes)).toBe(true);
+    expect(requestActorFromModule(actor)).toBe(requestActor);
+  });
+
+  test("拒绝业务模块自行构造的 Actor", () => {
+    expect(() =>
+      requestActorFromModule({
+        id: "forged",
+        type: "user",
+        name: "伪造用户",
+        roleCodes: [],
+        permissionKeys: [],
+      }),
+    ).toThrow("不是由当前宿主颁发");
+  });
+});