create-windy 0.2.8 → 0.2.9

package/dist/cli.js

@@ -4001,7 +4001,8 @@ var recipes = [
   { id: "starter-0.2.4-to-0.2.5", from: "0.2.4", to: "0.2.5" },
   { id: "starter-0.2.5-to-0.2.6", from: "0.2.5", to: "0.2.6" },
   { id: "starter-0.2.6-to-0.2.7", from: "0.2.6", to: "0.2.7" },
-  { id: "starter-0.2.7-to-0.2.8", from: "0.2.7", to: "0.2.8" }
+  { id: "starter-0.2.7-to-0.2.8", from: "0.2.7", to: "0.2.8" },
+  { id: "starter-0.2.8-to-0.2.9", from: "0.2.8", to: "0.2.9" }
 ];
 function resolveRecipeChain(sourceVersion, targetVersion) {
   if (sourceVersion === targetVersion)

package/package.json

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

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "15872dffe825009568e3bb6319982435c1327f90",
-  "generatorVersion": "0.2.8",
+  "templateCommit": "52071fd54061fd9b5578a11d3b64f9d687122378",
+  "generatorVersion": "0.2.9",
   "modules": [
     {
       "name": "system",

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

@@ -126,6 +126,7 @@ const moduleHosts = await initializeModuleHosts({
     // @windy-module system.storage end
   ],
 });
+void moduleHosts;
 const systemRepositories = createSystemRepositories(foundationSnapshot, {
   db: persistence?.db,
 });

package/template/packages/modules/src/ai-operation-composition.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "./manifest.js";
+import { validateModuleComposition } from "./composition.js";
+
+describe("AI Operation Composition", () => {
+  test("统一注册 Agent、Document 与 Speech Operation 并绑定实现", () => {
+    const module = fixture("business");
+    module.aiOperations = [
+      operation("business.agent", "agent", ["business.tool"]),
+      operation("business.document", "document"),
+      operation("business.speech", "speech"),
+    ];
+
+    expect(() =>
+      validateModuleComposition([module], {
+        aiOperations: module.aiOperations.map(({ key }) => key),
+      }),
+    ).not.toThrow();
+  });
+
+  test("Operation Key 全局唯一且必须使用所属模块命名空间", () => {
+    const first = fixture("first");
+    const second = fixture("second");
+    first.aiOperations = [operation("first.generate")];
+    second.aiOperations = [operation("first.generate")];
+
+    expect(() => validateModuleComposition([first, second])).toThrow(
+      "AI Operation Key 重复：first.generate",
+    );
+
+    second.aiOperations = [operation("foreign.generate")];
+    expect(() => validateModuleComposition([second])).toThrow(
+      "必须使用模块命名空间 second",
+    );
+  });
+
+  test.each([
+    ["permissionKey", "missing.permission", "未注册权限"],
+    ["featureKey", "missing.feature", "未注册Feature"],
+    ["auditAction", "missing.audit", "未注册审计动作"],
+  ] as const)("拒绝未知 %s 引用", (field, value, message) => {
+    const module = fixture("business");
+    const definition = operation("business.generate");
+    module.aiOperations = [{ ...definition, [field]: value }];
+    expect(() => validateModuleComposition([module])).toThrow(message);
+  });
+
+  test("拒绝未知 Tool、空 capability 和非法限制", () => {
+    const module = fixture("business");
+    module.aiOperations = [
+      operation("business.generate", "agent", ["missing.tool"]),
+    ];
+    expect(() => validateModuleComposition([module])).toThrow(
+      "未注册Agent Tool",
+    );
+
+    module.aiOperations[0] = {
+      ...operation("business.generate"),
+      requiredCapabilities: [],
+    };
+    expect(() => validateModuleComposition([module])).toThrow(
+      "至少需要一个 capability",
+    );
+
+    module.aiOperations[0] = {
+      ...operation("business.generate"),
+      limits: { ...operation("business.generate").limits, maxInputBytes: 0 },
+    };
+    expect(() => validateModuleComposition([module])).toThrow(
+      "上限必须是正整数",
+    );
+  });
+
+  test("拒绝空 schema、capability 和 Tool Key", () => {
+    const module = fixture("business");
+    module.aiOperations = [
+      { ...operation("business.generate"), inputSchemaKey: " " },
+    ];
+    expect(() => validateModuleComposition([module])).toThrow(
+      "Key 与引用字段不能为空",
+    );
+
+    module.aiOperations[0] = {
+      ...operation("business.generate"),
+      requiredCapabilities: [" "],
+    };
+    expect(() => validateModuleComposition([module])).toThrow(
+      "capability 不能为空",
+    );
+
+    module.aiOperations[0] = {
+      ...operation("business.generate"),
+      allowedToolKeys: [" "],
+    };
+    expect(() => validateModuleComposition([module])).toThrow("Tool 不能为空");
+  });
+
+  test("Operation Handler 必须与 Manifest 声明一一对应", () => {
+    const module = fixture("business");
+    module.aiOperations = [operation("business.generate")];
+
+    expect(() =>
+      validateModuleComposition([module], { aiOperations: [] }),
+    ).toThrow("AI Operation business.generate 缺少 Handler");
+    expect(() =>
+      validateModuleComposition([module], {
+        aiOperations: ["business.generate", "business.undeclared"],
+      }),
+    ).toThrow("AI Operation Handler business.undeclared 缺少 Manifest 声明");
+  });
+});
+
+function operation(
+  key: string,
+  kind: ModuleAiOperationDefinition["kind"] = "agent",
+  allowedToolKeys: readonly string[] = [],
+): ModuleAiOperationDefinition {
+  const namespace = key.split(".")[0]!;
+  return {
+    key,
+    kind,
+    featureKey: `${namespace}.ai`,
+    permissionKey: `${namespace}.ai.execute`,
+    auditAction: `${namespace}.ai.execute`,
+    inputSchemaKey: `${namespace}.ai.input.v1`,
+    outputSchemaKey: `${namespace}.ai.output.v1`,
+    requiredCapabilities: ["text-generation"],
+    allowedToolKeys,
+    dataClassification: "internal",
+    execution: kind === "speech" ? "live" : "streaming",
+    publicNetworkAccess: "forbidden",
+    limits: {
+      maxDurationSeconds: 60,
+      maxInputBytes: 1_048_576,
+      maxOutputBytes: 1_048_576,
+    },
+  };
+}
+
+function fixture(name: string): ModuleManifest {
+  const permissionKey = `${name}.ai.execute`;
+  const featureKey = `${name}.ai`;
+  return {
+    name,
+    version: "0.1.0",
+    label: name,
+    description: name,
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      {
+        key: permissionKey,
+        label: "执行 AI",
+        module: name,
+        resource: "ai",
+        action: "manage",
+      },
+    ],
+    apiPermissions: [],
+    features: [
+      {
+        key: featureKey,
+        label: "AI",
+        module: name,
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [
+      {
+        key: `${name}.tool`,
+        label: "业务工具",
+        description: "AI Operation 测试工具。",
+        permissionKey,
+        featureKey,
+        auditAction: `${name}.ai.execute`,
+      },
+    ],
+    providers: [],
+    auditActions: [
+      {
+        key: `${name}.ai.execute`,
+        label: "执行 AI",
+        description: "执行 AI Operation。",
+      },
+    ],
+  };
+}

package/template/packages/modules/src/ai-operation-composition.ts

@@ -0,0 +1,145 @@
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "./manifest.js";
+
+interface AiOperationCatalogs {
+  permissions: ReadonlySet<string>;
+  features: ReadonlySet<string>;
+  audits: ReadonlySet<string>;
+  tools: ReadonlySet<string>;
+}
+
+export function validateAiOperations(
+  modules: readonly ModuleManifest[],
+  catalogs: AiOperationCatalogs,
+): ModuleAiOperationDefinition[] {
+  const operations = modules.flatMap((module) => module.aiOperations || []);
+  uniqueValues(
+    "AI Operation",
+    operations.map(({ key }) => key),
+  );
+  for (const module of modules) {
+    for (const operation of module.aiOperations || []) {
+      validateOperation(module.name, operation, catalogs);
+    }
+  }
+  return operations;
+}
+
+export function validateAiOperationImplementations(
+  declarations: readonly ModuleAiOperationDefinition[],
+  implementations: readonly string[] | undefined,
+): void {
+  if (!implementations) return;
+  const declared = new Set(declarations.map(({ key }) => key));
+  const registered = uniqueValues("AI Operation Handler", implementations);
+  for (const key of declared) {
+    if (!registered.has(key)) {
+      throw new Error(`AI Operation ${key} 缺少 Handler`);
+    }
+  }
+  for (const key of registered) {
+    if (!declared.has(key)) {
+      throw new Error(`AI Operation Handler ${key} 缺少 Manifest 声明`);
+    }
+  }
+}
+
+function validateOperation(
+  moduleName: string,
+  operation: ModuleAiOperationDefinition,
+  catalogs: AiOperationCatalogs,
+): void {
+  const strings = [
+    operation.key,
+    operation.featureKey,
+    operation.permissionKey,
+    operation.auditAction,
+    operation.inputSchemaKey,
+    operation.outputSchemaKey,
+  ];
+  if (strings.some((value) => !value.trim())) {
+    throw new Error("AI Operation Key 与引用字段不能为空");
+  }
+  if (!operation.key.startsWith(`${moduleName}.`)) {
+    throw new Error(
+      `AI Operation ${operation.key} 必须使用模块命名空间 ${moduleName}`,
+    );
+  }
+  requiredReference(
+    operation.key,
+    "权限",
+    operation.permissionKey,
+    catalogs.permissions,
+  );
+  requiredReference(
+    operation.key,
+    "Feature",
+    operation.featureKey,
+    catalogs.features,
+  );
+  requiredReference(
+    operation.key,
+    "审计动作",
+    operation.auditAction,
+    catalogs.audits,
+  );
+  validateCapabilities(operation);
+  validateTools(operation, catalogs.tools);
+  validateLimits(operation);
+}
+
+function validateCapabilities(operation: ModuleAiOperationDefinition): void {
+  if (!operation.requiredCapabilities.length) {
+    throw new Error(`${operation.key} 至少需要一个 capability`);
+  }
+  validateNonEmptyValues(
+    `${operation.key} capability`,
+    operation.requiredCapabilities,
+  );
+}
+
+function validateTools(
+  operation: ModuleAiOperationDefinition,
+  tools: ReadonlySet<string>,
+): void {
+  validateNonEmptyValues(`${operation.key} Tool`, operation.allowedToolKeys);
+  for (const toolKey of operation.allowedToolKeys) {
+    requiredReference(operation.key, "Agent Tool", toolKey, tools);
+  }
+}
+
+function validateLimits(operation: ModuleAiOperationDefinition): void {
+  const values = Object.values(operation.limits);
+  if (values.some((value) => !Number.isSafeInteger(value) || value <= 0)) {
+    throw new Error(`${operation.key} 运行与输入输出上限必须是正整数`);
+  }
+}
+
+function validateNonEmptyValues(label: string, values: readonly string[]) {
+  if (values.some((value) => !value.trim())) {
+    throw new Error(`${label} 不能为空`);
+  }
+  uniqueValues(label, values);
+}
+
+function requiredReference(
+  operationKey: string,
+  label: string,
+  key: string,
+  catalog: ReadonlySet<string>,
+): void {
+  if (!catalog.has(key)) {
+    throw new Error(`${operationKey} 引用了未注册${label}：${key}`);
+  }
+}
+
+function uniqueValues(label: string, values: readonly string[]): Set<string> {
+  const result = new Set<string>();
+  for (const value of values) {
+    if (result.has(value)) throw new Error(`${label} Key 重复：${value}`);
+    result.add(value);
+  }
+  return result;
+}

package/template/packages/modules/src/composition.ts

@@ -3,6 +3,8 @@ import type {
   ModuleImplementationBindings,
   ModuleManifest,
 } from "./manifest.js";
+import { validateAiOperations } from "./ai-operation-composition.js";
+import { validateImplementationBindings } from "./implementation-bindings.js";
 import { composeModuleMenus } from "./menu-composition.js";
 import { validateCapabilityCatalogs } from "./catalog-validation.js";
 
@@ -58,10 +60,16 @@ export function validateModuleComposition(
     tasks.map(({ key }) => key),
   );
   const tools = modules.flatMap((module) => module.tools);
-  unique(
+  const toolKeys = unique(
     "Agent Tool",
     tools.map(({ key }) => key),
   );
+  const aiOperations = validateAiOperations(modules, {
+    permissions,
+    features,
+    audits,
+    tools: toolKeys,
+  });
   const providers = modules.flatMap((module) => module.providers);
   unique(
     "Provider",
@@ -92,30 +100,16 @@ export function validateModuleComposition(
   }
   validateMenuRoutes(menus, adminRoutes);
   validateSchemaMigrations(schemas);
-  validateImplementations(
-    "Admin Route",
-    adminRoutes.map(({ key }) => key),
-    implementations.adminRoutes,
-  );
-  validateImplementations(
-    "API Route",
-    apiRoutes.map(apiRouteKey),
-    implementations.apiRoutes,
-  );
-  validateImplementations(
-    "定时任务",
-    tasks.map(({ key }) => key),
-    implementations.tasks,
-  );
-  validateImplementations(
-    "Agent Tool",
-    tools.map(({ key }) => key),
-    implementations.tools,
-  );
-  validateImplementations(
-    "Provider",
-    providers.map(({ key }) => key),
-    implementations.providers,
+  validateImplementationBindings(
+    {
+      adminRoutes: adminRoutes.map(({ key }) => key),
+      apiRoutes: apiRoutes.map(apiRouteKey),
+      tasks: tasks.map(({ key }) => key),
+      tools: tools.map(({ key }) => key),
+      providers: providers.map(({ key }) => key),
+    },
+    aiOperations,
+    implementations,
   );
 
   return { modules, moduleOrder };
@@ -318,18 +312,6 @@ function validateSchemaMigrations(
   }
 }
 
-function validateImplementations(
-  label: string,
-  declarations: readonly string[],
-  implementations: readonly string[] | undefined,
-): void {
-  if (!implementations) return;
-  const registered = unique(`${label} Handler`, implementations);
-  for (const key of declarations) {
-    if (!registered.has(key)) throw new Error(`${label} ${key} 缺少 Handler`);
-  }
-}
-
 function unique(label: string, values: readonly string[]): Set<string> {
   const result = new Set<string>();
   for (const value of values) {

package/template/packages/modules/src/implementation-bindings.ts

@@ -0,0 +1,70 @@
+import { validateAiOperationImplementations } from "./ai-operation-composition.js";
+import type {
+  ModuleAiOperationDefinition,
+  ModuleImplementationBindings,
+} from "./manifest.js";
+
+interface ModuleDeclarationKeys {
+  adminRoutes: readonly string[];
+  apiRoutes: readonly string[];
+  tasks: readonly string[];
+  tools: readonly string[];
+  providers: readonly string[];
+}
+
+export function validateImplementationBindings(
+  declarations: ModuleDeclarationKeys,
+  aiOperations: readonly ModuleAiOperationDefinition[],
+  implementations: ModuleImplementationBindings,
+): void {
+  validateImplementations(
+    "Admin Route",
+    declarations.adminRoutes,
+    implementations.adminRoutes,
+  );
+  validateImplementations(
+    "API Route",
+    declarations.apiRoutes,
+    implementations.apiRoutes,
+  );
+  validateImplementations(
+    "定时任务",
+    declarations.tasks,
+    implementations.tasks,
+  );
+  validateImplementations(
+    "Agent Tool",
+    declarations.tools,
+    implementations.tools,
+  );
+  validateAiOperationImplementations(
+    aiOperations,
+    implementations.aiOperations,
+  );
+  validateImplementations(
+    "Provider",
+    declarations.providers,
+    implementations.providers,
+  );
+}
+
+function validateImplementations(
+  label: string,
+  declarations: readonly string[],
+  implementations: readonly string[] | undefined,
+): void {
+  if (!implementations) return;
+  const registered = unique(`${label} Handler`, implementations);
+  for (const key of declarations) {
+    if (!registered.has(key)) throw new Error(`${label} ${key} 缺少 Handler`);
+  }
+}
+
+function unique(label: string, values: readonly string[]): Set<string> {
+  const result = new Set<string>();
+  for (const value of values) {
+    if (result.has(value)) throw new Error(`${label} Key 重复：${value}`);
+    result.add(value);
+  }
+  return result;
+}

package/template/packages/modules/src/manifest.ts

@@ -11,7 +11,10 @@ import type {
   SearchProviderManifestDefinition,
 } from "@southwind-ai/shared";
 
-export type { MigrationDefinition, MigrationDirection } from "@southwind-ai/shared";
+export type {
+  MigrationDefinition,
+  MigrationDirection,
+} from "@southwind-ai/shared";
 
 export interface ModuleToolDefinition {
   key: string;
@@ -59,6 +62,37 @@ export interface ModuleScheduledTaskDefinition {
   retryDelaySeconds: number;
 }
 
+export type AiOperationKind = "agent" | "document" | "speech";
+export type AiOperationDataClassification = "public" | "internal" | "sensitive";
+export type AiOperationExecution =
+  | "interactive"
+  | "streaming"
+  | "background"
+  | "live";
+export type AiOperationPublicNetworkAccess = "forbidden" | "allowed";
+
+export interface AiOperationLimits {
+  maxDurationSeconds: number;
+  maxInputBytes: number;
+  maxOutputBytes: number;
+}
+
+export interface ModuleAiOperationDefinition {
+  key: string;
+  kind: AiOperationKind;
+  featureKey: string;
+  permissionKey: string;
+  auditAction: AuditActionType;
+  inputSchemaKey: string;
+  outputSchemaKey: string;
+  requiredCapabilities: readonly string[];
+  allowedToolKeys: readonly string[];
+  dataClassification: AiOperationDataClassification;
+  execution: AiOperationExecution;
+  publicNetworkAccess: AiOperationPublicNetworkAccess;
+  limits: AiOperationLimits;
+}
+
 export interface ModuleManifest {
   name: string;
   version: string;
@@ -75,6 +109,7 @@ export interface ModuleManifest {
   schemaExports: ModuleSchemaExportDefinition[];
   tasks: ModuleScheduledTaskDefinition[];
   tools: ModuleToolDefinition[];
+  aiOperations?: ModuleAiOperationDefinition[];
   providers: Array<ModuleProviderDefinition | SearchProviderManifestDefinition>;
   dataPolicies?: DataGovernancePolicyDefinition[];
   auditActions: AuditActionRegistration[];
@@ -88,5 +123,6 @@ export interface ModuleImplementationBindings {
   apiRoutes?: readonly string[];
   tasks?: readonly string[];
   tools?: readonly string[];
+  aiOperations?: readonly string[];
   providers?: readonly string[];
 }