create-windy 0.3.2 → 0.3.5

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

@@ -0,0 +1,165 @@
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "./manifest.js";
+
+export 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,
+      ...(kind === "agent" ? {} : { maxUnits: 500 }),
+      ...(kind === "speech" ? { maxMediaDurationSeconds: 3_600 } : {}),
+    },
+  };
+}
+
+export function providerDataPolicy() {
+  return {
+    inputFields: [
+      {
+        jsonPointer: "/question",
+        classification: "internal" as const,
+        dlpAction: "redact" as const,
+      },
+    ],
+    envelopeFields: [
+      {
+        field: "instructions" as const,
+        classification: "internal" as const,
+        dlpAction: "reject" as const,
+      },
+      {
+        field: "user-prompt" as const,
+        classification: "internal" as const,
+        dlpAction: "redact" as const,
+      },
+    ],
+  };
+}
+
+export function documentProviderDataPolicy() {
+  return {
+    inputFields: [
+      {
+        jsonPointer: "/outputs",
+        classification: "internal" as const,
+        dlpAction: "reject" as const,
+      },
+    ],
+    envelopeFields: [
+      {
+        field: "artifact-content" as const,
+        classification: "sensitive" as const,
+        dlpAction: "reject" as const,
+      },
+      {
+        field: "provider-output" as const,
+        classification: "sensitive" as const,
+        dlpAction: "reject" as const,
+      },
+    ],
+  };
+}
+
+export 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: [],
+    jsonSchemas: [
+      {
+        key: `${name}.tool.input.v1`,
+        schema: { type: "object" },
+      },
+      {
+        key: `${name}.tool.output.v1`,
+        schema: { type: "object" },
+      },
+      {
+        key: `${name}.ai.input.v1`,
+        schema: { type: "object" },
+      },
+      {
+        key: `${name}.ai.output.v1`,
+        schema: { type: "object" },
+      },
+    ],
+    tasks: [],
+    tools: [
+      {
+        key: `${name}.tool`,
+        label: "业务工具",
+        description: "AI Operation 测试工具。",
+        inputSchemaKey: `${name}.tool.input.v1`,
+        outputSchemaKey: `${name}.tool.output.v1`,
+        operation: "query",
+        permissionKey,
+        featureKey,
+        auditAction: `${name}.ai.execute`,
+        scopeMode: "request",
+        dataClassification: "internal",
+        idempotency: "none",
+        approval: "none",
+        limits: {
+          maxDurationSeconds: 10,
+          maxInputBytes: 4096,
+          maxOutputBytes: 4096,
+        },
+      },
+    ],
+    providers: [],
+    auditActions: [
+      {
+        key: `${name}.ai.execute`,
+        label: "执行 AI",
+        description: "执行 AI Operation。",
+      },
+    ],
+  };
+}

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

@@ -1,9 +1,12 @@
 import { describe, expect, test } from "bun:test";
-import type {
-  ModuleAiOperationDefinition,
-  ModuleManifest,
-} from "./manifest.js";
+import type { ModuleAiOperationDefinition } from "./manifest.js";
 import { validateModuleComposition } from "./composition.js";
+import {
+  documentProviderDataPolicy,
+  fixture,
+  operation,
+  providerDataPolicy,
+} from "./ai-operation-composition.test-support.js";
 
 describe("AI Operation Composition", () => {
   test("统一注册 Agent、Document 与 Speech Operation 并绑定实现", () => {
@@ -205,139 +208,100 @@ describe("AI Operation Composition", () => {
       }),
     ).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 providerDataPolicy() {
-  return {
-    inputFields: [
-      {
-        jsonPointer: "/question",
-        classification: "internal" as const,
-        dlpAction: "redact" as const,
-      },
-    ],
-    envelopeFields: [
-      {
-        field: "instructions" as const,
-        classification: "internal" as const,
-        dlpAction: "reject" as const,
-      },
+  test("Document Operation 强制页数上限和专用 Provider Envelope", () => {
+    const module = fixture("business");
+    const definition = operation("business.document", "document");
+    module.aiOperations = [
       {
-        field: "user-prompt" as const,
-        classification: "internal" as const,
-        dlpAction: "redact" as const,
+        ...definition,
+        providerEgress: {
+          mode: "configured-endpoint",
+          deploymentKey: "document.private",
+        },
+        providerDataPolicy: documentProviderDataPolicy(),
       },
-    ],
-  };
-}
+    ];
+    expect(() => validateModuleComposition([module])).not.toThrow();
 
-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: [],
-    jsonSchemas: [
-      {
-        key: `${name}.tool.input.v1`,
-        schema: { type: "object" },
-      },
-      {
-        key: `${name}.tool.output.v1`,
-        schema: { type: "object" },
+    module.aiOperations[0] = {
+      ...definition,
+      limits: {
+        maxDurationSeconds: 60,
+        maxInputBytes: 1_048_576,
+        maxOutputBytes: 1_048_576,
       },
-      {
-        key: `${name}.ai.input.v1`,
-        schema: { type: "object" },
+    };
+    expect(() => validateModuleComposition([module])).toThrow(
+      "必须声明 maxUnits",
+    );
+
+    module.aiOperations[0] = {
+      ...definition,
+      providerEgress: {
+        mode: "configured-endpoint",
+        deploymentKey: "document.private",
       },
-      {
-        key: `${name}.ai.output.v1`,
-        schema: { type: "object" },
+      providerDataPolicy: providerDataPolicy(),
+    };
+    expect(() => validateModuleComposition([module])).toThrow(
+      "缺少 artifact-content",
+    );
+  });
+
+  test("图片输入必须声明 Artifact 数量与像素上限", () => {
+    const module = fixture("business");
+    const definition = operation("business.vision");
+    module.aiOperations = [
+      { ...definition, inputModalities: ["text", "image"] },
+    ];
+    expect(() => validateModuleComposition([module])).toThrow(
+      "图片输入必须声明数量与像素上限",
+    );
+
+    module.aiOperations[0] = {
+      ...definition,
+      inputModalities: ["text", "image"],
+      limits: {
+        ...definition.limits,
+        maxArtifacts: 4,
+        maxPixelsPerArtifact: 20_000_000,
       },
-    ],
-    tasks: [],
-    tools: [
+    };
+    expect(() => validateModuleComposition([module])).not.toThrow();
+  });
+
+  test("多图文档允许 100 个 Artifact，Agent 仍限制为 16 个", () => {
+    const module = fixture("business");
+    const document = operation("business.compose", "document");
+    module.aiOperations = [
       {
-        key: `${name}.tool`,
-        label: "业务工具",
-        description: "AI Operation 测试工具。",
-        inputSchemaKey: `${name}.tool.input.v1`,
-        outputSchemaKey: `${name}.tool.output.v1`,
-        operation: "query",
-        permissionKey,
-        featureKey,
-        auditAction: `${name}.ai.execute`,
-        scopeMode: "request",
-        dataClassification: "internal",
-        idempotency: "none",
-        approval: "none",
+        ...document,
+        inputModalities: ["image"],
         limits: {
-          maxDurationSeconds: 10,
-          maxInputBytes: 4096,
-          maxOutputBytes: 4096,
+          ...document.limits,
+          maxUnits: 500,
+          maxArtifacts: 100,
+          maxPixelsPerArtifact: 40_000_000,
         },
       },
-    ],
-    providers: [],
-    auditActions: [
+    ];
+    expect(() => validateModuleComposition([module])).not.toThrow();
+
+    const agent = operation("business.vision");
+    module.aiOperations = [
       {
-        key: `${name}.ai.execute`,
-        label: "执行 AI",
-        description: "执行 AI Operation。",
+        ...agent,
+        inputModalities: ["image"],
+        limits: {
+          ...agent.limits,
+          maxArtifacts: 17,
+          maxPixelsPerArtifact: 40_000_000,
+        },
       },
-    ],
-  };
-}
+    ];
+    expect(() => validateModuleComposition([module])).toThrow(
+      "图片输入上限超过 Runtime 安全边界",
+    );
+  });
+});

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

@@ -110,6 +110,9 @@ const providerDataFields = new Set([
   "instructions",
   "user-prompt",
   "tool-definitions",
+  "artifact-content",
+  "embedding-input",
+  "output-schema",
   "provider-output",
   "tool-results",
 ]);
@@ -150,13 +153,27 @@ export function validateProviderDataPolicy(
       throw new Error(`${operation.key} Provider DLP 动作无效：${rule.field}`);
     }
   }
-  for (const field of ["instructions", "user-prompt"]) {
+  const requiredFields =
+    operation.kind === "agent"
+      ? ["instructions", "user-prompt"]
+      : operation.kind === "embedding"
+        ? ["embedding-input", "provider-output"]
+        : ["artifact-content", "provider-output"];
+  for (const field of requiredFields) {
     if (!fields.has(field)) {
       throw new Error(
         `${operation.key} Provider 字段发送 allowlist 缺少 ${field}`,
       );
     }
   }
+  if (
+    operation.inputModalities?.includes("image") &&
+    !fields.has("artifact-content")
+  ) {
+    throw new Error(
+      `${operation.key} 图片输入的 Provider allowlist 缺少 artifact-content`,
+    );
+  }
   if (operation.allowedToolKeys.length) {
     for (const field of [
       "tool-definitions",
@@ -170,6 +187,9 @@ export function validateProviderDataPolicy(
       }
     }
   }
+  if (operation.kind !== "agent" && operation.allowedToolKeys.length) {
+    throw new Error(`${operation.key} 非 Agent Operation 不允许声明 Tool`);
+  }
 }
 
 function validateInputFields(
@@ -245,6 +265,44 @@ function validateLimits(operation: ModuleAiOperationDefinition): void {
   if (values.some((value) => !Number.isSafeInteger(value) || value <= 0)) {
     throw new Error(`${operation.key} 运行与输入输出上限必须是正整数`);
   }
+  if (operation.kind !== "agent" && !operation.limits.maxUnits) {
+    throw new Error(`${operation.key} 非 Agent Operation 必须声明 maxUnits`);
+  }
+  if (
+    operation.kind === "embedding" &&
+    (operation.limits.maxUnits ?? 0) > 256
+  ) {
+    throw new Error(`${operation.key} Embedding 批量上限超过 Runtime 安全边界`);
+  }
+  if (
+    operation.kind === "speech" &&
+    !operation.limits.maxMediaDurationSeconds
+  ) {
+    throw new Error(`${operation.key} Speech Operation 必须声明媒体时长上限`);
+  }
+  const modalities = operation.inputModalities ?? ["text"];
+  validateNonEmptyValues(`${operation.key} 输入模态`, modalities);
+  if (
+    modalities.some(
+      (modality) =>
+        !["text", "image", "audio", "video", "document"].includes(modality),
+    )
+  ) {
+    throw new Error(`${operation.key} 输入模态无效`);
+  }
+  if (
+    modalities.includes("image") &&
+    (!operation.limits.maxArtifacts || !operation.limits.maxPixelsPerArtifact)
+  ) {
+    throw new Error(`${operation.key} 图片输入必须声明数量与像素上限`);
+  }
+  const maxArtifactsLimit = operation.kind === "document" ? 100 : 16;
+  if (
+    (operation.limits.maxArtifacts ?? 0) > maxArtifactsLimit ||
+    (operation.limits.maxPixelsPerArtifact ?? 0) > 100_000_000
+  ) {
+    throw new Error(`${operation.key} 图片输入上限超过 Runtime 安全边界`);
+  }
 }
 
 function validateNonEmptyValues(label: string, values: readonly string[]) {

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

@@ -10,6 +10,7 @@ import type {
   MenuNode,
   PermissionDefinition,
   SearchProviderManifestDefinition,
+  CandidateRole,
 } from "@southwind-ai/shared";
 
 export type {
@@ -31,6 +32,10 @@ export interface ModuleToolDefinition {
   dataClassification: "public" | "internal" | "sensitive";
   idempotency: "none" | "supported" | "required";
   approval: "none" | "required";
+  /** `approval=required` 时显式指定候选审批角色。 */
+  approvalRoles?: readonly CandidateRole[];
+  /** 审批等待上限；到期由 Workflow 转为 timed-out。 */
+  approvalTimeoutSeconds?: number;
   limits: {
     maxDurationSeconds: number;
     maxInputBytes: number;
@@ -80,7 +85,13 @@ export interface ModuleScheduledTaskDefinition {
   retryDelaySeconds: number;
 }
 
-export type AiOperationKind = "agent" | "document" | "speech";
+export type AiOperationKind = "agent" | "document" | "speech" | "embedding";
+export type AiOperationInputModality =
+  | "text"
+  | "image"
+  | "audio"
+  | "video"
+  | "document";
 export type AiOperationDataClassification = "public" | "internal" | "sensitive";
 export type AiOperationExecution =
   | "interactive"
@@ -102,6 +113,9 @@ export type AiProviderDataField =
   | "instructions"
   | "user-prompt"
   | "tool-definitions"
+  | "artifact-content"
+  | "embedding-input"
+  | "output-schema"
   | "provider-output"
   | "tool-results";
 export type AiProviderDlpAction = "reject" | "redact";
@@ -127,6 +141,14 @@ export interface AiOperationLimits {
   maxDurationSeconds: number;
   maxInputBytes: number;
   maxOutputBytes: number;
+  /** Document/Speech 等批处理 Operation 的最大页数或分段数。 */
+  maxUnits?: number;
+  /** Speech 等媒体 Operation 可接受的素材时长上限。 */
+  maxMediaDurationSeconds?: number;
+  /** Agent/Vision 等多模态 Operation 单次最多接收的 Artifact 数量。 */
+  maxArtifacts?: number;
+  /** 图片输入解码后的单件像素上限，不能仅依赖压缩字节数。 */
+  maxPixelsPerArtifact?: number;
 }
 
 export interface ModuleAiOperationDefinition {
@@ -137,6 +159,8 @@ export interface ModuleAiOperationDefinition {
   auditAction: AuditActionType;
   inputSchemaKey: string;
   outputSchemaKey: string;
+  /** 缺省为 text；声明 image 后才能提交图片 Artifact。 */
+  inputModalities?: readonly AiOperationInputModality[];
   requiredCapabilities: readonly string[];
   allowedToolKeys: readonly string[];
   dataClassification: AiOperationDataClassification;

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

@@ -69,6 +69,24 @@ function validateTool(
   if (tool.operation === "query" && tool.approval !== "none") {
     throw new Error(`${tool.key} 查询能力不能要求执行审批`);
   }
+  if (
+    tool.approval === "required" &&
+    (!tool.approvalRoles?.length ||
+      !Number.isSafeInteger(tool.approvalTimeoutSeconds) ||
+      (tool.approvalTimeoutSeconds ?? 0) <= 0)
+  ) {
+    throw new Error(`${tool.key} 审批 Tool 必须声明候选角色与等待上限`);
+  }
+  if (tool.approval === "required" && tool.idempotency !== "required") {
+    throw new Error(`${tool.key} 审批 Tool 必须要求幂等`);
+  }
+  if (
+    tool.approvalRoles?.some(({ code }) => !code.trim()) ||
+    new Set(tool.approvalRoles?.map(({ code }) => code)).size !==
+      (tool.approvalRoles?.length ?? 0)
+  ) {
+    throw new Error(`${tool.key} 审批候选角色无效或重复`);
+  }
   const limits = Object.values(tool.limits);
   if (limits.some((value) => !Number.isSafeInteger(value) || value <= 0)) {
     throw new Error(`${tool.key} 运行与输入输出上限必须是正整数`);

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

@@ -1,14 +1,57 @@
 export type { ModuleActor } from "./src/actor.js";
+export type {
+  ModuleAiArtifactPort,
+  ModuleAiArtifactRef,
+} from "./src/ai-artifact-port.js";
+export { ModuleAiArtifactError } from "./src/ai-artifact-port.js";
+export type {
+  ModuleAiOperationPort,
+  ModuleAiRunReceipt,
+  ModuleEmbeddingItem,
+} from "./src/ai-operation-port.js";
+export { ModuleAiOperationError } from "./src/ai-operation-port.js";
+export type {
+  ModuleBackgroundAiErrorCode,
+  ModuleBackgroundAiOperationInput,
+  ModuleBackgroundAiOperationResult,
+  ModuleBackgroundAiPort,
+} from "./src/background-ai-port.js";
+export { ModuleBackgroundAiError } from "./src/background-ai-port.js";
 export type {
   ModuleAuditEmitter,
   ModuleAuditEmitInput,
   ModuleAuditTarget,
 } from "./src/audit-port.js";
 export type {
+  ModuleJobCancelInput,
+  ModuleJobControlErrorCode,
+  ModuleJobPort,
+  ModuleJobProgressView,
+  ModuleJobRecoverInput,
+  ModuleJobStatus,
   ModuleJobSubmitter,
   ModuleJobSubmitInput,
   ModuleJobSubmitResult,
+  ModuleJobView,
 } from "./src/jobs-port.js";
+export { ModuleJobControlError } from "./src/jobs-port.js";
+export type {
+  ModuleDurableHandlerContext,
+  ModuleDurableHandlerDefinition,
+  ModuleDurableStoragePort,
+} from "./src/durable-handler.js";
+export type {
+  GovernedExportRenderedArtifact,
+  GovernedExportWatermarkContext,
+  ModuleGovernedExportPage,
+  ModuleGovernedExportPageInput,
+  ModuleGovernedExportQuery,
+  ModuleGovernedExportRegistration,
+  ModuleGovernedExportRendererRegistration,
+  ModuleGovernedRecord,
+  ModuleGovernedResourceContext,
+  ModuleGovernedResourceRegistration,
+} from "./src/data-governance-registration.js";
 export type {
   InstallableServerModule,
   ModuleHost,
@@ -18,6 +61,11 @@ export type {
 export { requireModuleNamespace } from "./src/namespace.js";
 export type { ModuleRequestContext } from "./src/request-context.js";
 export type { ModuleRolePreset } from "./src/role-preset.js";
+export type {
+  ModuleSandboxToolContext,
+  ModuleSandboxToolHandlerRegistration,
+  ModuleSandboxToolHost,
+} from "./src/sandbox-tool.js";
 export type {
   ModuleRouteDefinition,
   ModuleRouteHandler,
@@ -67,4 +115,6 @@ export type {
   ModuleAiOperationContext,
   ModuleAiOperationHandlerRegistration,
   ModuleAiOperationPlan,
+  ModuleDocumentOperationPlan,
+  ModuleSpeechOperationPlan,
 } from "./src/ai-operation-registration.js";