create-windy 0.2.7 → 0.2.9

package/template/packages/jobs/package.json

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

package/template/packages/jobs/src/handlers.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  DurableHandlerError,
+  DurableHandlerRegistry,
+  type DurableHandlerContext,
+} from "./handlers.js";
+
+describe("DurableHandlerRegistry", () => {
+  test("解析 payload 后执行已注册 handler", async () => {
+    const received: string[] = [];
+    const registry = new DurableHandlerRegistry().register({
+      key: "example.report.generate",
+      payload: {
+        parse(input) {
+          if (
+            typeof input !== "object" ||
+            input === null ||
+            !("reportId" in input) ||
+            typeof input.reportId !== "string"
+          ) {
+            throw new DurableHandlerError(
+              "INVALID_PAYLOAD",
+              "reportId 无效",
+              false,
+            );
+          }
+          return { reportId: input.reportId };
+        },
+      },
+      execute(payload) {
+        received.push(payload.reportId);
+      },
+    });
+
+    await registry
+      .get("example.report.generate")
+      ?.execute({ reportId: "report-1" }, createContext());
+
+    expect(received).toEqual(["report-1"]);
+    expect(registry.keys()).toEqual(["example.report.generate"]);
+  });
+
+  test("拒绝空 key 和重复注册", () => {
+    const registry = new DurableHandlerRegistry();
+    const definition = {
+      key: "example.sync",
+      payload: { parse: () => ({}) },
+      execute: () => undefined,
+    };
+
+    expect(() => registry.register({ ...definition, key: " " })).toThrow(
+      "任务 handler key 不能为空",
+    );
+    registry.register(definition);
+    expect(() => registry.register(definition)).toThrow(
+      "任务 handler 重复注册：example.sync",
+    );
+  });
+});
+
+function createContext(): DurableHandlerContext {
+  return {
+    jobId: "job-1",
+    stageKey: "main",
+    attemptNumber: 1,
+    signal: new AbortController().signal,
+    heartbeat: async () => undefined,
+    progress: async () => undefined,
+    publishArtifact: async () => undefined,
+  };
+}

package/template/{apps/server/src/jobs/handler-registry.ts → packages/jobs/src/handlers.ts}

@@ -1,4 +1,4 @@
-import type { ArtifactRef } from "@windy/storage";
+import type { ArtifactRef } from "@southwind-ai/storage";
 
 export interface PayloadParser<T> {
   parse(input: unknown): T;
@@ -45,7 +45,7 @@ export interface RegisteredDurableHandler {
 export class DurableHandlerRegistry {
   private readonly handlers = new Map<string, RegisteredDurableHandler>();
 
-  register<T>(definition: DurableHandlerDefinition<T>) {
+  register<T>(definition: DurableHandlerDefinition<T>): this {
     if (!definition.key.trim()) throw new Error("任务 handler key 不能为空");
     if (this.handlers.has(definition.key)) {
       throw new Error(`任务 handler 重复注册：${definition.key}`);
@@ -59,11 +59,11 @@ export class DurableHandlerRegistry {
     return this;
   }
 
-  get(key: string) {
+  get(key: string): RegisteredDurableHandler | undefined {
     return this.handlers.get(key);
   }
 
-  keys() {
+  keys(): string[] {
     return [...this.handlers.keys()].sort();
   }
 }

package/template/{apps/server/src/jobs → packages/jobs/src}/types.ts

@@ -1,4 +1,4 @@
-import type { ArtifactRef } from "@windy/storage";
+import type { ArtifactRef } from "@southwind-ai/storage";
 
 export type DurableJobStatus =
   | "queued"
@@ -178,3 +178,9 @@ export interface SubmitDurableJobResult {
   job: DurableJob;
   created: boolean;
 }
+
+export interface DurableJobs {
+  submit(input: SubmitDurableJob): Promise<SubmitDurableJobResult>;
+  get(id: string): Promise<DurableJobSnapshot | undefined>;
+  list(requestedBy: string, limit?: number): Promise<DurableJob[]>;
+}

package/template/packages/{license-sdk → jobs}/tsconfig.json

@@ -7,7 +7,6 @@
     "strict": true,
     "noImplicitAny": true,
     "esModuleInterop": true,
-    "resolveJsonModule": true,
     "skipLibCheck": true,
     "outDir": "dist",
     "types": ["bun"]

package/template/packages/modules/index.ts

@@ -1,8 +1,8 @@
 export * from "./src/manifest.js";
 export * from "./src/composition.js";
+export * from "./src/catalog-validation.js";
 export * from "./src/menu-composition.js";
 export * from "./src/registry.js";
 export * from "./src/system-modules.js";
 export * from "./src/system-module-catalog.js";
 export * from "./src/system-api-permissions.js";
-export * from "./src/installed-business-modules.js";

package/template/packages/modules/package.json

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

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/catalog-validation.ts

@@ -0,0 +1,123 @@
+import {
+  AUDIT_ACTION_DEFINITIONS,
+  isAuditActionDefinition,
+  LICENSE_CATALOG,
+  type AuditActionDefinition,
+  type FeatureFlagDefinition,
+  type LicenseCatalogDefinition,
+} from "@southwind-ai/shared";
+import type { ModuleManifest } from "./manifest.js";
+
+export interface PlatformCapabilityCatalogs {
+  auditActions: readonly AuditActionDefinition[];
+  licenseVersions: readonly LicenseCatalogDefinition[];
+}
+
+export function validateCapabilityCatalogs(
+  modules: readonly ModuleManifest[],
+): PlatformCapabilityCatalogs {
+  const auditActions = composeAuditActionCatalog(modules);
+  validateFeatureCatalog(modules, LICENSE_CATALOG);
+  return {
+    auditActions,
+    licenseVersions: LICENSE_CATALOG,
+  };
+}
+
+export function composeAuditActionCatalog(
+  modules: readonly ModuleManifest[],
+): AuditActionDefinition[] {
+  const definitions = new Map<string, AuditActionDefinition>(
+    AUDIT_ACTION_DEFINITIONS.map((definition) => [
+      definition.key,
+      { ...definition },
+    ]),
+  );
+  const registrations = modules.flatMap((module) => module.auditActions);
+
+  for (const registration of registrations) {
+    if (!isAuditActionDefinition(registration)) continue;
+    validateAuditDefinition(registration);
+    if (definitions.has(registration.key)) {
+      throw new Error(`审计动作定义重复：${registration.key}`);
+    }
+    definitions.set(registration.key, { ...registration });
+  }
+
+  for (const registration of registrations) {
+    const key =
+      typeof registration === "string" ? registration : registration.key;
+    if (!definitions.has(key)) {
+      throw new Error(`引用了未定义审计动作：${key}`);
+    }
+  }
+
+  return [...definitions.values()].sort((left, right) =>
+    left.key.localeCompare(right.key),
+  );
+}
+
+export function validateFeatureCatalog(
+  modules: readonly ModuleManifest[],
+  licenseCatalog: readonly LicenseCatalogDefinition[],
+): void {
+  const features = modules.flatMap((module) => module.features);
+  const byKey = new Map(features.map((feature) => [feature.key, feature]));
+  const licenseKeys = new Set(licenseCatalog.map(({ key }) => key));
+
+  for (const feature of features) {
+    for (const dependency of feature.dependencies || []) {
+      if (dependency === feature.key) {
+        throw new Error(`Feature ${feature.key} 不能依赖自身`);
+      }
+      if (!byKey.has(dependency)) {
+        throw new Error(
+          `Feature ${feature.key} 引用了未注册依赖：${dependency}`,
+        );
+      }
+    }
+    for (const version of feature.allowedLicenseVersions || []) {
+      if (!licenseKeys.has(version)) {
+        throw new Error(
+          `Feature ${feature.key} 引用了未知 License 版本：${version}`,
+        );
+      }
+    }
+  }
+
+  validateFeatureCycles(features, byKey);
+}
+
+function validateAuditDefinition(definition: AuditActionDefinition): void {
+  if (
+    !definition.key.trim() ||
+    !definition.label.trim() ||
+    !definition.description.trim()
+  ) {
+    throw new Error("审计动作 Key、名称和说明不能为空");
+  }
+}
+
+function validateFeatureCycles(
+  features: readonly FeatureFlagDefinition[],
+  byKey: ReadonlyMap<string, FeatureFlagDefinition>,
+): void {
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+
+  const visit = (feature: FeatureFlagDefinition): void => {
+    if (visited.has(feature.key)) return;
+    if (visiting.has(feature.key)) {
+      throw new Error(`Feature 依赖存在循环：${feature.key}`);
+    }
+    visiting.add(feature.key);
+    for (const dependency of feature.dependencies || []) {
+      const target = byKey.get(dependency);
+      if (target) visit(target);
+    }
+    visiting.delete(feature.key);
+    visited.add(feature.key);
+  };
+
+  for (const feature of features) visit(feature);
+}