create-windy 0.2.7 → 0.2.9

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

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { featureKey } from "@windy/shared";
+import { featureKey, licenseVersionKey } from "@southwind-ai/shared";
 import type { ModuleManifest } from "./manifest.js";
 import { validateModuleComposition } from "./composition.js";
 
@@ -50,10 +50,83 @@ describe("Module Composition 契约", () => {
     );
 
     const audit = fixture("audit");
-    audit.tools[0]!.auditAction = "security.denied";
+    audit.tools[0]!.auditAction = "audit.unknown";
     expect(() => validateModuleComposition([audit])).toThrow("未注册审计动作");
   });
 
+  test("业务模块可注册带展示信息的审计动作目录", () => {
+    const module = fixture("ticket");
+    module.auditActions.push({
+      key: "ticket.assign",
+      label: "工单指派",
+      description: "将工单指派给处理人。",
+    });
+    module.tools[0]!.auditAction = "ticket.assign";
+
+    expect(() => validateModuleComposition([module])).not.toThrow();
+
+    const unknown = fixture("unknown");
+    unknown.auditActions.push("unknown.action");
+    expect(() => validateModuleComposition([unknown])).toThrow(
+      "引用了未定义审计动作",
+    );
+  });
+
+  test("审计动作定义不可覆盖平台动作或重复注册", () => {
+    const platform = fixture("platform");
+    platform.auditActions.push({
+      key: "crud.create",
+      label: "覆盖动作",
+      description: "不允许覆盖平台定义。",
+    });
+    expect(() => validateModuleComposition([platform])).toThrow(
+      "审计动作定义重复：crud.create",
+    );
+
+    const first = fixture("first");
+    const second = fixture("second");
+    for (const module of [first, second]) {
+      module.auditActions.push({
+        key: "ticket.assign",
+        label: "工单指派",
+        description: "将工单指派给处理人。",
+      });
+    }
+    expect(() => validateModuleComposition([first, second])).toThrow(
+      "审计动作定义重复：ticket.assign",
+    );
+  });
+
+  test("Feature 依赖未知、自依赖和循环时 fail-fast", () => {
+    const unknown = fixture("unknown");
+    unknown.features[0]!.dependencies = [featureKey("missing.feature")];
+    expect(() => validateModuleComposition([unknown])).toThrow(
+      "引用了未注册依赖",
+    );
+
+    const self = fixture("self");
+    self.features[0]!.dependencies = [featureKey("self.feature")];
+    expect(() => validateModuleComposition([self])).toThrow("不能依赖自身");
+
+    const first = fixture("first");
+    const second = fixture("second");
+    first.features[0]!.dependencies = [featureKey("second.feature")];
+    second.features[0]!.dependencies = [featureKey("first.feature")];
+    expect(() => validateModuleComposition([first, second])).toThrow(
+      "Feature 依赖存在循环",
+    );
+  });
+
+  test("Feature 只能引用 License Catalog 中的版本", () => {
+    const module = fixture("license");
+    module.features[0]!.allowedLicenseVersions = [
+      licenseVersionKey("enterprise"),
+    ];
+    expect(() => validateModuleComposition([module])).toThrow(
+      "引用了未知 License 版本：enterprise",
+    );
+  });
+
   test("菜单 Guard 必须与 Admin Route 一致", () => {
     const module = fixture("system");
     module.adminRoutes[0]!.permissionKey = "system.manage";

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

@@ -1,9 +1,12 @@
-import type { MenuNode } from "@windy/shared";
+import type { MenuNode } from "@southwind-ai/shared";
 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";
 
 export interface ValidatedModuleComposition {
   modules: readonly ModuleManifest[];
@@ -31,7 +34,8 @@ export function validateModuleComposition(
     "Feature",
     modules.flatMap((module) => module.features.map(({ key }) => key)),
   );
-  const audits = new Set(modules.flatMap((module) => module.auditActions));
+  const catalogs = validateCapabilityCatalogs(modules);
+  const audits = new Set(catalogs.auditActions.map(({ key }) => key));
   const menus = composeModuleMenus(modules).flatMap((menu) =>
     flattenMenus([menu]),
   );
@@ -56,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",
@@ -90,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 };
@@ -316,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

@@ -1,23 +1,20 @@
 import type {
   ApiPermissionBinding,
+  AuditActionRegistration,
   AuditActionType,
   DataGovernancePolicyDefinition,
   FeatureFlagDefinition,
-  MigrationExecutionContext,
+  MigrationBundle,
+  MigrationDefinition,
   MenuNode,
   PermissionDefinition,
   SearchProviderManifestDefinition,
-} from "@windy/shared";
+} from "@southwind-ai/shared";
 
-export type MigrationDirection = "up" | "down";
-
-export interface MigrationDefinition {
-  id: string;
-  module: string;
-  description: string;
-  direction: MigrationDirection;
-  run(context: MigrationExecutionContext): Promise<void>;
-}
+export type {
+  MigrationDefinition,
+  MigrationDirection,
+} from "@southwind-ai/shared";
 
 export interface ModuleToolDefinition {
   key: string;
@@ -65,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;
@@ -77,12 +105,14 @@ export interface ModuleManifest {
   apiPermissions: ApiPermissionBinding[];
   features: FeatureFlagDefinition[];
   migrations: MigrationDefinition[];
+  migrationBundle?: MigrationBundle;
   schemaExports: ModuleSchemaExportDefinition[];
   tasks: ModuleScheduledTaskDefinition[];
   tools: ModuleToolDefinition[];
+  aiOperations?: ModuleAiOperationDefinition[];
   providers: Array<ModuleProviderDefinition | SearchProviderManifestDefinition>;
   dataPolicies?: DataGovernancePolicyDefinition[];
-  auditActions: AuditActionType[];
+  auditActions: AuditActionRegistration[];
   metadata?: Record<string, unknown>;
 }
 
@@ -93,5 +123,6 @@ export interface ModuleImplementationBindings {
   apiRoutes?: readonly string[];
   tasks?: readonly string[];
   tools?: readonly string[];
+  aiOperations?: readonly string[];
   providers?: readonly string[];
 }

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

@@ -1,4 +1,4 @@
-import type { MenuNode } from "@windy/shared";
+import type { MenuNode } from "@southwind-ai/shared";
 import type { ModuleManifest } from "./manifest.js";
 
 export function composeModuleMenus(

package/template/packages/modules/src/system-api-binding.ts

@@ -1,4 +1,4 @@
-import type { ApiPermissionBinding, HttpMethod } from "@windy/shared";
+import type { ApiPermissionBinding, HttpMethod } from "@southwind-ai/shared";
 
 interface ResourceBindingInput {
   path: string;

package/template/packages/modules/src/system-api-data-governance.ts

@@ -1,4 +1,4 @@
-import type { ApiPermissionBinding } from "@windy/shared";
+import type { ApiPermissionBinding } from "@southwind-ai/shared";
 import { binding } from "./system-api-binding.js";
 import { governedUserExportBindings } from "./system-governed-export-bindings.js";
 

package/template/packages/modules/src/system-api-permissions.ts

@@ -1,4 +1,4 @@
-import type { ApiPermissionBinding } from "@windy/shared";
+import type { ApiPermissionBinding } from "@southwind-ai/shared";
 import { binding, resourceBindings } from "./system-api-binding.js";
 // @windy-module system.data-governance begin
 import { dataGovernanceApiPermissionBindings } from "./system-api-data-governance.js";

package/template/packages/modules/src/system-data-governance.ts

@@ -1,4 +1,4 @@
-import { featureKey, type DataGovernancePolicyDefinition } from "@windy/shared";
+import { featureKey, type DataGovernancePolicyDefinition } from "@southwind-ai/shared";
 
 export const systemDataPolicies: DataGovernancePolicyDefinition[] = [
   {

package/template/packages/modules/src/system-features.ts

@@ -1,4 +1,4 @@
-import { featureKey, licenseVersionKey } from "@windy/shared";
+import { featureKey, licenseVersionKey } from "@southwind-ai/shared";
 import type { ModuleManifest } from "./manifest.js";
 
 // @windy-module system.scheduler begin

package/template/packages/modules/src/system-governed-export-bindings.ts

@@ -1,4 +1,4 @@
-import type { ApiPermissionBinding } from "@windy/shared";
+import type { ApiPermissionBinding } from "@southwind-ai/shared";
 import { binding } from "./system-api-binding.js";
 
 export function governedUserExportBindings(): ApiPermissionBinding[] {

package/template/packages/modules/src/system-module-catalog.ts

@@ -1,4 +1,4 @@
-import type { MenuNode } from "@windy/shared";
+import type { MenuNode } from "@southwind-ai/shared";
 import type { ModuleFactory, ModuleManifest } from "./manifest.js";
 import { systemFoundationModule } from "./system-modules.js";
 

package/template/packages/server-sdk/index.ts

@@ -0,0 +1,5 @@
+export type {
+  ModuleHost,
+  ModuleInitializer,
+  ModuleUploadPolicy,
+} from "./src/module-host.js";

package/template/packages/server-sdk/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@southwind-ai/server-sdk",
+  "version": "0.1.1",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "files": [
+    "index.ts",
+    "src/module-host.ts"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  },
+  "dependencies": {
+    "@southwind-ai/jobs": "workspace:*"
+  },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/template/packages/server-sdk/src/module-host.ts

@@ -0,0 +1,29 @@
+import type { DurableHandlerDefinition } from "@southwind-ai/jobs";
+
+export interface ModuleUploadPolicy {
+  purpose: string;
+  maxByteSize: number;
+  maxPartByteSize: number;
+  sessionTtlMs: number;
+  allowedTypes: Readonly<Record<string, readonly string[]>>;
+  signature?: "image" | "none";
+}
+
+/**
+ * 模块作用域 Host。注册的任务 Key 与上传用途必须使用初始化器模块名作为命名空间。
+ */
+export interface ModuleHost {
+  readonly moduleName: string;
+  registerUploadPolicy(policy: ModuleUploadPolicy): void;
+  registerDurableHandler<T>(definition: DurableHandlerDefinition<T>): void;
+}
+
+/**
+ * 已安装模块的 Server 初始化入口。
+ *
+ * 初始化器在 Storage 与 Durable Job 运行时创建前顺序执行；这里只注册定义，不启动 Worker。
+ */
+export interface ModuleInitializer {
+  readonly moduleName: string;
+  initialize(host: ModuleHost): Promise<void> | void;
+}

package/template/packages/server-sdk/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "lib": ["esnext", "dom"],
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noImplicitAny": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*", "index.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/template/packages/shared/index.ts

@@ -3,6 +3,8 @@ export * from "./src/database.js";
 export * from "./src/data-governance.js";
 export * from "./src/feature.js";
 export * from "./src/license.js";
+export * from "./src/license-catalog.js";
+export * from "./src/migration.js";
 export * from "./src/module-configuration.js";
 export * from "./src/correlation.js";
 export * from "./src/notification.js";

package/template/packages/shared/package.json

@@ -1,9 +1,20 @@
 {
-  "name": "@windy/shared",
-  "version": "0.1.0",
-  "private": true,
+  "name": "@southwind-ai/shared",
+  "version": "0.1.1",
+  "license": "UNLICENSED",
   "type": "module",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
   "exports": {
     ".": "./index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/template/packages/shared/src/audit.ts

@@ -1,5 +1,11 @@
 import type { EntityId, ISODateTime } from "./primitives.js";
 
+export interface AuditActionDefinition {
+  key: AuditActionType;
+  label: string;
+  description: string;
+}
+
 export const AUDIT_ACTION_DEFINITIONS = [
   { key: "auth.login", label: "账号登录", description: "用户登录平台。" },
   { key: "auth.logout", label: "账号退出", description: "用户退出平台。" },
@@ -200,7 +206,22 @@ export const AUDIT_ACTION_DEFINITIONS = [
   },
 ] as const;
 
-export type AuditActionType = (typeof AUDIT_ACTION_DEFINITIONS)[number]["key"];
+export type BuiltInAuditActionType =
+  (typeof AUDIT_ACTION_DEFINITIONS)[number]["key"];
+
+/**
+ * 审计日志持久化保持字符串协议；业务动作是否有效由 Module Composition
+ * 对 AuditActionDefinition 目录进行 fail-fast 校验。
+ */
+export type AuditActionType = BuiltInAuditActionType | (string & {});
+
+export type AuditActionRegistration = AuditActionType | AuditActionDefinition;
+
+export function isAuditActionDefinition(
+  registration: AuditActionRegistration,
+): registration is AuditActionDefinition {
+  return typeof registration !== "string";
+}
 
 export type AuditOutcome = "attempted" | "success" | "failure" | "denied";
 

package/template/packages/shared/src/license-catalog.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "bun:test";
+import { LICENSE_CATALOG } from "./license-catalog.js";
+
+describe("License Catalog", () => {
+  test("提供稳定且有序的默认产品版本", () => {
+    expect(LICENSE_CATALOG.map(({ key }) => key)).toEqual([
+      "free-trial",
+      "standard",
+      "advanced",
+    ]);
+    expect(
+      LICENSE_CATALOG.every(
+        ({ label, description }) => label.length > 0 && description.length > 0,
+      ),
+    ).toBe(true);
+  });
+});

package/template/packages/shared/src/license-catalog.ts

@@ -0,0 +1,33 @@
+import { licenseVersionKey, type LicenseVersionKey } from "./license.js";
+
+export interface LicenseCatalogDefinition {
+  key: LicenseVersionKey;
+  label: string;
+  description: string;
+  order: number;
+}
+
+export const LICENSE_CATALOG = [
+  {
+    key: licenseVersionKey("free-trial"),
+    label: "免费试用版",
+    description: "用于产品体验和非生产验证的基础版本。",
+    order: 10,
+  },
+  {
+    key: licenseVersionKey("standard"),
+    label: "标准版",
+    description: "面向常规企业业务场景的标准能力版本。",
+    order: 20,
+  },
+  {
+    key: licenseVersionKey("advanced"),
+    label: "高级版",
+    description: "包含高级治理、自动化和大批量处理能力。",
+    order: 30,
+  },
+] as const satisfies readonly LicenseCatalogDefinition[];
+
+export function licenseCatalogKeys(): ReadonlySet<LicenseVersionKey> {
+  return new Set(LICENSE_CATALOG.map(({ key }) => key));
+}

package/template/packages/shared/src/migration.ts

@@ -0,0 +1,39 @@
+import type { MigrationExecutionContext } from "./database.js";
+
+export const MIGRATION_BUNDLE_FORMAT_VERSION = "1" as const;
+
+export type MigrationDirection = "up" | "down";
+
+export interface MigrationDefinition {
+  id: string;
+  module: string;
+  description: string;
+  direction: MigrationDirection;
+  checksum?: string;
+  dependsOn?: readonly string[];
+  run(context: MigrationExecutionContext): Promise<void>;
+}
+
+export interface BundleMigrationDefinition extends MigrationDefinition {
+  checksum: string;
+}
+
+export interface MigrationBundle {
+  formatVersion: typeof MIGRATION_BUNDLE_FORMAT_VERSION;
+  module: string;
+  version: string;
+  dependencies?: readonly string[];
+  migrations: readonly BundleMigrationDefinition[];
+}
+
+export interface MigrationManifestSource {
+  name: string;
+  version: string;
+  dependencies?: readonly string[];
+  migrations: readonly MigrationDefinition[];
+  schemaExports?: readonly {
+    key: string;
+    migrationIds: readonly string[];
+  }[];
+  migrationBundle?: MigrationBundle;
+}