create-windy 0.6.9 → 0.6.11

package/template/packages/modules/src/system-api-control-plane.ts

@@ -29,6 +29,43 @@ export function systemControlPlaneApiPermissionBindings(): ApiPermissionBinding[
       "system.license",
       "license.update",
     ),
+    binding(
+      "POST",
+      "/api/license/runtime/pairing/sessions",
+      "system.license.manage",
+      "system.license",
+      "license.verify",
+    ),
+    binding(
+      "GET",
+      "/api/license/runtime/pairing/sessions/:sessionId",
+      "system.license.manage",
+      "system.license",
+      "license.verify",
+    ),
+    binding(
+      "POST",
+      "/api/license/runtime/pairing/sessions/:sessionId/confirm",
+      "system.license.manage",
+      "system.license",
+      "license.update",
+    ),
+    binding(
+      "OPTIONS",
+      "/api/license/runtime/pairing/sessions/:sessionId/deliver",
+      "system.license.manage",
+      "system.license",
+      undefined,
+      true,
+    ),
+    binding(
+      "POST",
+      "/api/license/runtime/pairing/sessions/:sessionId/deliver",
+      "system.license.manage",
+      "system.license",
+      undefined,
+      true,
+    ),
     // @windy-module system.license end
     // @windy-module system.agent begin
     binding(

package/template/packages/modules/src/system-license-pairing.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { systemControlPlaneApiPermissionBindings } from "./system-api-control-plane.js";
+
+describe("License 手机配对 API 注册", () => {
+  test("完整绑定创建、状态、确认与匿名回传入口", () => {
+    const bindings = systemControlPlaneApiPermissionBindings().filter(
+      ({ path }) => path.startsWith("/api/license/runtime/pairing/"),
+    );
+
+    expect(bindings).toEqual([
+      expect.objectContaining({
+        method: "POST",
+        path: "/api/license/runtime/pairing/sessions",
+        permissionKey: "system.license.manage",
+        featureKey: "system.license",
+        auditAction: "license.verify",
+      }),
+      expect.objectContaining({
+        method: "GET",
+        path: "/api/license/runtime/pairing/sessions/:sessionId",
+        permissionKey: "system.license.manage",
+        featureKey: "system.license",
+        auditAction: "license.verify",
+      }),
+      expect.objectContaining({
+        method: "POST",
+        path: "/api/license/runtime/pairing/sessions/:sessionId/confirm",
+        permissionKey: "system.license.manage",
+        featureKey: "system.license",
+        auditAction: "license.update",
+      }),
+      expect.objectContaining({
+        method: "OPTIONS",
+        path: "/api/license/runtime/pairing/sessions/:sessionId/deliver",
+        anonymous: true,
+      }),
+      expect.objectContaining({
+        method: "POST",
+        path: "/api/license/runtime/pairing/sessions/:sessionId/deliver",
+        anonymous: true,
+      }),
+    ]);
+  });
+});

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.2",
   "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} 无效`);
+  }
+}

package/template/packages/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/shared",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/shared/src/ai-runtime-report.ts

@@ -93,6 +93,18 @@ export interface AiRuntimeRunUsage {
   totalTokens: number | null;
 }
 
+/**
+ * 一个 Run 中实际观察到的模型与 deployment 组合。
+ *
+ * `model` 优先采用 Provider 回报的模型名；Provider 未回报时才保留请求模型。
+ * 排序遵循该组合首次出现的 Attempt 顺序，避免在报表投影时伪造执行顺序。
+ */
+export interface AiRuntimeRunModelDeployment {
+  deploymentKey: string;
+  model: string;
+  attemptCount: number;
+}
+
 export interface AiRuntimeRunListItem {
   runId: string;
   operationKey: string;
@@ -102,6 +114,8 @@ export interface AiRuntimeRunListItem {
   finishedAt: ISODateTime | null;
   durationMs: number | null;
   attemptCount: number;
+  modelDeployments: AiRuntimeRunModelDeployment[];
+  /** @deprecated 请使用包含 deployment 的 modelDeployments。 */
   models: string[];
   cacheStatus: AiRuntimeCacheStatus;
   usage: AiRuntimeRunUsage;
@@ -112,6 +126,11 @@ export interface AiRuntimeAttemptDetail extends AiRuntimeRunUsage {
   sequence: number;
   toolRound: number;
   deploymentKey: string;
+  /** 请求发送给 Provider 的模型名。 */
+  requestedModel: string;
+  /** Provider 响应中实际回报的模型名；缺失时不能推断。 */
+  reportedModel: string | null;
+  /** @deprecated 优先使用 reportedModel，缺失时使用 requestedModel。 */
   model: string;
   outcome: AiRuntimeAttemptOutcome;
   cacheStatus: AiRuntimeCacheStatus;