create-windy 0.6.9 → 0.6.10

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

@@ -1,6 +1,7 @@
-import type { MenuNode } from "@southwind-ai/shared";
 import type { ModuleFactory, ModuleManifest } from "./manifest.js";
+import { selectSystemMenus } from "./system-module-menu-selection.js";
 import { systemFoundationModule } from "./system-modules.js";
+import { selectSystemJsonSchemas } from "./system-module-schema-catalog.js";
 
 export interface SystemModuleDefinition {
   name: string;
@@ -118,7 +119,7 @@ export const systemModuleDefinitions = [
   // @windy-module system.agent begin
   {
     name: "system.agent",
-    version: "0.1.0",
+    version: "0.1.1",
     label: "Agent Tool",
     description: "受 Feature、RBAC 和审计保护的 Agent 工具调用。",
     dependencies: [
@@ -265,7 +266,7 @@ function createSystemCapabilityModule(
     label: definition.label,
     description: definition.description,
     dependencies: [...(definition.dependencies ?? (isCore ? [] : ["system"]))],
-    menus: selectMenus(aggregate.menus, ownsGuard),
+    menus: selectSystemMenus(aggregate.menus, ownsGuard),
     adminRoutes: aggregate.adminRoutes.filter((route) =>
       route.key === "system.settings"
         ? definition.name === "system.settings"
@@ -284,7 +285,10 @@ function createSystemCapabilityModule(
       .map((feature) => ({ ...feature, module: definition.name })),
     migrations: isCore ? aggregate.migrations : [],
     schemaExports: isCore ? aggregate.schemaExports : [],
-    jsonSchemas: isCore ? aggregate.jsonSchemas : [],
+    jsonSchemas: selectSystemJsonSchemas(
+      definition.name,
+      aggregate.jsonSchemas,
+    ),
     tasks: aggregate.tasks.filter(ownsGuard),
     tools: aggregate.tools.filter(ownsGuard),
     providers: aggregate.providers.filter(ownsGuard),
@@ -332,17 +336,3 @@ function permissionResource(permissionKey: string): string {
   const parts = permissionKey.split(".");
   return parts.length >= 3 ? parts.slice(1, -1).join(".") : "";
 }
-
-function selectMenus(
-  menus: readonly MenuNode[],
-  ownsGuard: (guard: {
-    permissionKey?: string;
-    featureKey?: string;
-  }) => boolean,
-): MenuNode[] {
-  return menus.flatMap((menu) => {
-    const children = selectMenus(menu.children || [], ownsGuard);
-    if (!children.length && !ownsGuard(menu)) return [];
-    return [{ ...menu, children: children.length ? children : undefined }];
-  });
-}

package/template/packages/modules/src/system-module-menu-selection.ts

@@ -0,0 +1,15 @@
+import type { MenuNode } from "@southwind-ai/shared";
+
+export function selectSystemMenus(
+  menus: readonly MenuNode[],
+  ownsGuard: (guard: {
+    permissionKey?: string;
+    featureKey?: string;
+  }) => boolean,
+): MenuNode[] {
+  return menus.flatMap((menu) => {
+    const children = selectSystemMenus(menu.children || [], ownsGuard);
+    if (!children.length && !ownsGuard(menu)) return [];
+    return [{ ...menu, children: children.length ? children : undefined }];
+  });
+}

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

@@ -0,0 +1,14 @@
+import type { ModuleManifest } from "./manifest.js";
+
+export function selectSystemJsonSchemas(
+  moduleName: string,
+  schemas: ModuleManifest["jsonSchemas"],
+): ModuleManifest["jsonSchemas"] {
+  if (moduleName === "system.agent") {
+    return schemas?.filter(({ key }) => key.startsWith("system.agent."));
+  }
+  if (moduleName === "system") {
+    return schemas?.filter(({ key }) => !key.startsWith("system.agent."));
+  }
+  return [];
+}

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

@@ -4,6 +4,7 @@ import {
   systemAgentToolSchemas,
   systemAgentTools,
 } from "./system-agent-tools.js";
+import { systemAgentSupervisorSchemas } from "./system-agent-supervisor.js";
 // @windy-module system.agent end
 import { systemAdminRoutes } from "./system-admin-routes.js";
 import { systemApiPermissionBindings } from "./system-api-permissions.js";
@@ -281,6 +282,7 @@ export function systemFoundationModule(): ModuleManifest {
     jsonSchemas: [
       // @windy-module system.agent begin
       ...systemAgentToolSchemas,
+      ...systemAgentSupervisorSchemas,
       // @windy-module system.agent end
     ],
     tasks: systemModuleTasks,

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

@@ -246,3 +246,8 @@ export type {
   ModuleDocumentOperationPlan,
   ModuleSpeechOperationPlan,
 } from "./src/ai-operation-registration.js";
+export {
+  defineSystemAgentSupervisorHandler,
+  type SystemAgentSupervisorBusinessRelease,
+  type SystemAgentSupervisorHandlerOptions,
+} from "./src/system-agent-supervisor.js";

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

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/server-sdk",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -44,6 +44,7 @@
     "src/secret-binding.ts",
     "src/secret-port.ts",
     "src/storage-port.ts",
+    "src/system-agent-supervisor.ts",
     "src/task-registration.ts",
     "src/tool-registration.ts",
     "src/tool-host-port.ts",
@@ -56,6 +57,7 @@
   },
   "dependencies": {
     "@southwind-ai/jobs": "workspace:^",
+    "@southwind-ai/modules": "workspace:^",
     "@southwind-ai/shared": "workspace:^0.2.5",
     "@southwind-ai/storage": "workspace:^"
   },

package/template/packages/server-sdk/src/ai-operation-registration.ts

@@ -40,6 +40,10 @@ export interface ModuleEmbeddingOperationPlan {
 
 export interface ModuleAiOperationHandlerRegistration {
   readonly operationKey: string;
+  readonly supervisor?: {
+    readonly contractVersion: 1;
+    readonly finalAnswerSchemaVersion: 1;
+  };
   /**
    * 不可变发布坐标。修改 Workflow、Prompt 或 Route 时必须提升对应版本；
    * 宿主以这些坐标和 Manifest/Tool Schema 摘要固定每个 Run。

package/template/packages/server-sdk/src/system-agent-supervisor.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import {
+  composeSystemAgentFinalAnswerSchemaV1,
+  SYSTEM_AGENT_SUPERVISOR_INSTRUCTIONS,
+} from "@southwind-ai/modules";
+import { defineSystemAgentSupervisorHandler } from "./system-agent-supervisor.js";
+
+describe("system.agent Supervisor handler seam", () => {
+  test("平台指令、业务指令与发布坐标共同冻结", async () => {
+    const schema = composeSystemAgentFinalAnswerSchemaV1();
+    const handler = defineSystemAgentSupervisorHandler({
+      operationKey: "business.copilot",
+      release: {
+        workflowVersion: "business-w2",
+        promptVersion: "business-p3",
+        routeVersion: "business-r4",
+      },
+      prepare: () => ({
+        instructions: "只使用当前案件的数据。",
+        userPrompt: "汇总案件事实",
+        outputSchema: schema,
+      }),
+    });
+    const plan = await handler.prepare?.(
+      {},
+      {
+        actor: {
+          id: "actor-1",
+          type: "user",
+          name: "用户",
+          roleCodes: ["user"],
+          permissionKeys: [],
+        },
+        requestId: "request-1",
+      },
+    );
+
+    expect(plan?.instructions).toBe(
+      `${SYSTEM_AGENT_SUPERVISOR_INSTRUCTIONS}\n\n只使用当前案件的数据。`,
+    );
+    expect(plan?.outputSchema).toEqual(schema);
+    expect(handler.supervisor).toEqual({
+      contractVersion: 1,
+      finalAnswerSchemaVersion: 1,
+    });
+    expect(handler.release).toEqual({
+      workflowVersion:
+        "system-agent-supervisor-workflow-1+business-business-w2",
+      promptVersion: "system-agent-supervisor-prompt-1+business-business-p3",
+      routeVersion: "system-agent-supervisor-route-1+business-business-r4",
+    });
+  });
+
+  test("拒绝没有 canonical finalAnswer 的业务输出 Schema", async () => {
+    const handler = defineSystemAgentSupervisorHandler({
+      operationKey: "business.copilot",
+      release: {
+        workflowVersion: "1",
+        promptVersion: "1",
+        routeVersion: "1",
+      },
+      prepare: () => ({
+        instructions: "业务指令",
+        userPrompt: "问题",
+        outputSchema: {
+          type: "object",
+          properties: { text: { type: "string" } },
+        },
+      }),
+    });
+    await expect(
+      handler.prepare?.(
+        {},
+        {
+          actor: {
+            id: "actor-1",
+            type: "user",
+            name: "用户",
+            roleCodes: ["user"],
+            permissionKeys: [],
+          },
+          requestId: "request-1",
+        },
+      ),
+    ).rejects.toThrow("canonical finalAnswer V1");
+  });
+});

package/template/packages/server-sdk/src/system-agent-supervisor.ts

@@ -0,0 +1,89 @@
+import {
+  assertSystemAgentFinalAnswerSchemaV1,
+  SYSTEM_AGENT_FINAL_ANSWER_SCHEMA_VERSION,
+  SYSTEM_AGENT_SUPERVISOR_INSTRUCTIONS,
+  SYSTEM_AGENT_SUPERVISOR_PROMPT_VERSION,
+  SYSTEM_AGENT_SUPERVISOR_ROUTE_VERSION,
+  SYSTEM_AGENT_SUPERVISOR_WORKFLOW_VERSION,
+} from "@southwind-ai/modules";
+import type {
+  ModuleAiOperationContext,
+  ModuleAiOperationHandlerRegistration,
+  ModuleAiOperationPlan,
+  ModuleAiJsonValue,
+} from "./ai-operation-registration.js";
+
+export interface SystemAgentSupervisorBusinessRelease {
+  readonly workflowVersion: string;
+  readonly promptVersion: string;
+  readonly routeVersion: string;
+}
+
+export interface SystemAgentSupervisorHandlerOptions {
+  readonly operationKey: string;
+  readonly release: SystemAgentSupervisorBusinessRelease;
+  prepare(
+    input: ModuleAiJsonValue,
+    context: ModuleAiOperationContext,
+  ): Promise<ModuleAiOperationPlan> | ModuleAiOperationPlan;
+}
+
+/**
+ * 把业务 Operation 接入 system.agent 的通用规划、Tool 汇总和 typed final-answer 协议。
+ * 业务仍拥有输入、权限、数据范围与附加输出字段；平台拥有 Supervisor 指令和发布坐标。
+ */
+export function defineSystemAgentSupervisorHandler(
+  options: SystemAgentSupervisorHandlerOptions,
+): ModuleAiOperationHandlerRegistration {
+  requireVersion(options.operationKey, "Operation Key");
+  requireVersion(options.release.workflowVersion, "业务 workflowVersion");
+  requireVersion(options.release.promptVersion, "业务 promptVersion");
+  requireVersion(options.release.routeVersion, "业务 routeVersion");
+  return {
+    operationKey: options.operationKey,
+    release: {
+      workflowVersion: coordinate(
+        "workflow",
+        SYSTEM_AGENT_SUPERVISOR_WORKFLOW_VERSION,
+        options.release.workflowVersion,
+      ),
+      promptVersion: coordinate(
+        "prompt",
+        SYSTEM_AGENT_SUPERVISOR_PROMPT_VERSION,
+        options.release.promptVersion,
+      ),
+      routeVersion: coordinate(
+        "route",
+        SYSTEM_AGENT_SUPERVISOR_ROUTE_VERSION,
+        options.release.routeVersion,
+      ),
+    },
+    supervisor: {
+      contractVersion: 1,
+      finalAnswerSchemaVersion: SYSTEM_AGENT_FINAL_ANSWER_SCHEMA_VERSION,
+    },
+    async prepare(input, context) {
+      const plan = await options.prepare(input, context);
+      assertSystemAgentFinalAnswerSchemaV1(plan.outputSchema);
+      return {
+        ...plan,
+        instructions: [
+          SYSTEM_AGENT_SUPERVISOR_INSTRUCTIONS,
+          plan.instructions.trim(),
+        ]
+          .filter(Boolean)
+          .join("\n\n"),
+      };
+    },
+  };
+}
+
+function coordinate(kind: string, platform: string, business: string) {
+  return `system-agent-supervisor-${kind}-${platform}+business-${business}`;
+}
+
+function requireVersion(value: string, label: string): void {
+  if (!value.trim() || value.length > 32 || !/^[A-Za-z0-9._-]+$/.test(value)) {
+    throw new Error(`${label} 无效`);
+  }
+}