create-windy 0.2.22 → 0.2.24

package/template/packages/modules/index.ts

@@ -6,3 +6,4 @@ 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/tool-composition.js";

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

@@ -172,15 +172,45 @@ function fixture(name: string): ModuleManifest {
     ],
     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: [],

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

@@ -8,6 +8,7 @@ interface AiOperationCatalogs {
   features: ReadonlySet<string>;
   audits: ReadonlySet<string>;
   tools: ReadonlySet<string>;
+  schemas: ReadonlySet<string>;
 }
 
 export function validateAiOperations(
@@ -85,6 +86,18 @@ function validateOperation(
     operation.auditAction,
     catalogs.audits,
   );
+  requiredReference(
+    operation.key,
+    " JSON Schema",
+    operation.inputSchemaKey,
+    catalogs.schemas,
+  );
+  requiredReference(
+    operation.key,
+    " JSON Schema",
+    operation.outputSchemaKey,
+    catalogs.schemas,
+  );
   validateCapabilities(operation);
   validateTools(operation, catalogs.tools);
   validateLimits(operation);

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

@@ -170,6 +170,26 @@ describe("Module Composition 契约", () => {
     );
   });
 
+  test("Agent Tool 必须引用已注册 object Schema 并声明正数限制", () => {
+    const missing = fixture("system");
+    missing.tools[0]!.inputSchemaKey = "system.missing.v1";
+    expect(() => validateModuleComposition([missing])).toThrow(
+      "引用了未注册 JSON Schema",
+    );
+
+    const invalidSchema = fixture("system");
+    invalidSchema.jsonSchemas![0]!.schema = { type: "array" };
+    expect(() => validateModuleComposition([invalidSchema])).toThrow(
+      "顶层类型必须是 object",
+    );
+
+    const invalidLimit = fixture("system");
+    invalidLimit.tools[0]!.limits.maxInputBytes = 0;
+    expect(() => validateModuleComposition([invalidLimit])).toThrow(
+      "上限必须是正整数",
+    );
+  });
+
   test("字段治理策略校验唯一资源、权限风险和已注册字段", () => {
     const module = fixture("system");
     module.permissions.push({
@@ -266,6 +286,16 @@ function fixture(name: string, dependencies: string[] = []): ModuleManifest {
         migrationIds: [`${name}.001`],
       },
     ],
+    jsonSchemas: [
+      {
+        key: `${name}.tool.input.v1`,
+        schema: { type: "object" },
+      },
+      {
+        key: `${name}.tool.output.v1`,
+        schema: { type: "object" },
+      },
+    ],
     tasks: [
       {
         key: `${name}.task`,
@@ -283,9 +313,21 @@ function fixture(name: string, dependencies: string[] = []): ModuleManifest {
         key: `${name}.tool`,
         label: name,
         description: name,
+        inputSchemaKey: `${name}.tool.input.v1`,
+        outputSchemaKey: `${name}.tool.output.v1`,
+        operation: "query",
         permissionKey: readPermission,
         featureKey,
         auditAction: "agent.tool.execute",
+        scopeMode: "request",
+        dataClassification: "internal",
+        idempotency: "none",
+        approval: "none",
+        limits: {
+          maxDurationSeconds: 10,
+          maxInputBytes: 4096,
+          maxOutputBytes: 4096,
+        },
       },
     ],
     providers: [

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

@@ -7,6 +7,7 @@ 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";
+import { validateToolContracts } from "./tool-composition.js";
 
 export interface ValidatedModuleComposition {
   modules: readonly ModuleManifest[];
@@ -35,6 +36,7 @@ export function validateModuleComposition(
     modules.flatMap((module) => module.features.map(({ key }) => key)),
   );
   const catalogs = validateCapabilityCatalogs(modules);
+  const jsonSchemas = validateToolContracts(modules);
   const audits = new Set(catalogs.auditActions.map(({ key }) => key));
   const menus = composeModuleMenus(modules).flatMap((menu) =>
     flattenMenus([menu]),
@@ -69,6 +71,7 @@ export function validateModuleComposition(
     features,
     audits,
     tools: toolKeys,
+    schemas: new Set(jsonSchemas.keys()),
   });
   const providers = modules.flatMap((module) => module.providers);
   unique(

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

@@ -4,6 +4,7 @@ import type {
   AuditActionType,
   DataGovernancePolicyDefinition,
   FeatureFlagDefinition,
+  JsonObject,
   MigrationBundle,
   MigrationDefinition,
   MenuNode,
@@ -20,9 +21,26 @@ export interface ModuleToolDefinition {
   key: string;
   label: string;
   description: string;
+  inputSchemaKey: string;
+  outputSchemaKey: string;
+  operation: "query" | "command" | "background";
   permissionKey: string;
-  featureKey?: string;
+  featureKey: string;
   auditAction: AuditActionType;
+  scopeMode: "platform" | "request";
+  dataClassification: "public" | "internal" | "sensitive";
+  idempotency: "none" | "supported" | "required";
+  approval: "none" | "required";
+  limits: {
+    maxDurationSeconds: number;
+    maxInputBytes: number;
+    maxOutputBytes: number;
+  };
+}
+
+export interface ModuleJsonSchemaDefinition {
+  key: string;
+  schema: JsonObject;
 }
 
 export type AdminRouteSurface = "sidebar" | "account" | "hidden";
@@ -107,6 +125,7 @@ export interface ModuleManifest {
   migrations: MigrationDefinition[];
   migrationBundle?: MigrationBundle;
   schemaExports: ModuleSchemaExportDefinition[];
+  jsonSchemas?: ModuleJsonSchemaDefinition[];
   tasks: ModuleScheduledTaskDefinition[];
   tools: ModuleToolDefinition[];
   aiOperations?: ModuleAiOperationDefinition[];

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

@@ -1,15 +1,66 @@
-import type { ModuleManifest } from "./manifest.js";
+import type { ModuleJsonSchemaDefinition, ModuleManifest } from "./manifest.js";
+
+export const systemAgentToolSchemas: ModuleJsonSchemaDefinition[] = [
+  {
+    key: "system.pagination.input.v1",
+    schema: {
+      type: "object",
+      properties: {
+        page: { type: "integer", minimum: 1, default: 1 },
+        pageSize: {
+          type: "integer",
+          minimum: 1,
+          maximum: 50,
+          default: 10,
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    key: "system.page.output.v1",
+    schema: {
+      type: "object",
+      properties: {
+        items: { type: "array", items: { type: "object" } },
+        total: { type: "integer", minimum: 0 },
+        page: { type: "integer", minimum: 1 },
+        pageSize: { type: "integer", minimum: 1 },
+      },
+      required: ["items", "total", "page", "pageSize"],
+      additionalProperties: false,
+    },
+  },
+];
+
+const queryContract = {
+  inputSchemaKey: "system.pagination.input.v1",
+  outputSchemaKey: "system.page.output.v1",
+  operation: "query" as const,
+  scopeMode: "platform" as const,
+  dataClassification: "internal" as const,
+  idempotency: "none" as const,
+  approval: "none" as const,
+  limits: {
+    maxDurationSeconds: 10,
+    maxInputBytes: 4_096,
+    maxOutputBytes: 1_048_576,
+  },
+};
 
 export const systemAgentTools: ModuleManifest["tools"] = [
   {
+    ...queryContract,
     key: "system.users.list",
     label: "查询用户",
     description: "分页查询平台用户账号。",
     permissionKey: "system.user.read",
     featureKey: "system.rbac",
     auditAction: "agent.tool.execute",
+    scopeMode: "request",
   },
   {
+    ...queryContract,
     key: "system.features.list",
     label: "查询功能开关",
     description: "分页查询平台功能开关状态。",
@@ -18,6 +69,7 @@ export const systemAgentTools: ModuleManifest["tools"] = [
     auditAction: "agent.tool.execute",
   },
   {
+    ...queryContract,
     key: "system.audit.list",
     label: "查询审计日志",
     description: "分页查询平台审计事件。",

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

@@ -25,6 +25,11 @@ export function systemApiPermissionBindings(): ApiPermissionBinding[] {
     ),
     binding("POST", "/api/search", "system.search.read", "system.search"),
     // @windy-module system.search end
+    // @windy-module system.agent begin
+    binding("GET", "/api/mcp", "system.agent.read", "system.agent"),
+    binding("POST", "/api/mcp", "system.agent.read", "system.agent"),
+    binding("DELETE", "/api/mcp", "system.agent.read", "system.agent"),
+    // @windy-module system.agent end
     ...resourceBindings({
       path: "users",
       permissionResource: "user",

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

@@ -218,6 +218,7 @@ function createSystemCapabilityModule(
       .map((feature) => ({ ...feature, module: definition.name })),
     migrations: isCore ? aggregate.migrations : [],
     schemaExports: isCore ? aggregate.schemaExports : [],
+    jsonSchemas: isCore ? aggregate.jsonSchemas : [],
     tasks: aggregate.tasks.filter(ownsGuard),
     tools: aggregate.tools.filter(ownsGuard),
     providers: aggregate.providers.filter(ownsGuard),

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

@@ -326,6 +326,38 @@ describe("系统模块能力注册", () => {
       anonymous: undefined,
     });
   });
+
+  // @windy-module system.agent begin
+  test("MCP Streamable HTTP 入口统一绑定 Agent Feature 与读取权限", () => {
+    const bindings = systemFoundationModule().apiPermissions.filter(
+      ({ path }) => path === "/api/mcp",
+    );
+
+    expect(bindings).toEqual([
+      {
+        method: "GET",
+        path: "/api/mcp",
+        permissionKey: "system.agent.read",
+        featureKey: "system.agent",
+        anonymous: undefined,
+      },
+      {
+        method: "POST",
+        path: "/api/mcp",
+        permissionKey: "system.agent.read",
+        featureKey: "system.agent",
+        anonymous: undefined,
+      },
+      {
+        method: "DELETE",
+        path: "/api/mcp",
+        permissionKey: "system.agent.read",
+        featureKey: "system.agent",
+        anonymous: undefined,
+      },
+    ]);
+  });
+  // @windy-module system.agent end
 });
 
 function flattenMenuKeys(

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

@@ -1,6 +1,9 @@
 import type { ModuleManifest } from "./manifest.js";
 // @windy-module system.agent begin
-import { systemAgentTools } from "./system-agent-tools.js";
+import {
+  systemAgentToolSchemas,
+  systemAgentTools,
+} from "./system-agent-tools.js";
 // @windy-module system.agent end
 import { systemAdminRoutes } from "./system-admin-routes.js";
 import { systemApiPermissionBindings } from "./system-api-permissions.js";
@@ -249,6 +252,11 @@ export function systemFoundationModule(): ModuleManifest {
         migrationIds: ["0000..0028"],
       },
     ],
+    jsonSchemas: [
+      // @windy-module system.agent begin
+      ...systemAgentToolSchemas,
+      // @windy-module system.agent end
+    ],
     tasks: [
       // @windy-module system.scheduler begin
       {

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

@@ -0,0 +1,86 @@
+import type {
+  ModuleJsonSchemaDefinition,
+  ModuleManifest,
+  ModuleToolDefinition,
+} from "./manifest.js";
+
+export function validateToolContracts(
+  modules: readonly ModuleManifest[],
+): ReadonlyMap<string, ModuleJsonSchemaDefinition> {
+  const schemas = new Map<string, ModuleJsonSchemaDefinition>();
+  for (const module of modules) {
+    for (const definition of module.jsonSchemas ?? []) {
+      validateSchema(module.name, definition);
+      if (schemas.has(definition.key)) {
+        throw new Error(`JSON Schema Key 重复：${definition.key}`);
+      }
+      schemas.set(definition.key, definition);
+    }
+  }
+  for (const module of modules) {
+    for (const tool of module.tools) {
+      validateTool(module.name, tool, schemas);
+    }
+  }
+  return schemas;
+}
+
+function validateSchema(
+  moduleName: string,
+  definition: ModuleJsonSchemaDefinition,
+): void {
+  if (!definition.key.trim()) throw new Error("JSON Schema Key 不能为空");
+  if (!definition.key.startsWith(`${moduleName}.`)) {
+    throw new Error(
+      `JSON Schema ${definition.key} 必须使用模块命名空间 ${moduleName}`,
+    );
+  }
+  if (definition.schema.type !== "object") {
+    throw new Error(`JSON Schema ${definition.key} 顶层类型必须是 object`);
+  }
+}
+
+function validateTool(
+  moduleName: string,
+  tool: ModuleToolDefinition,
+  schemas: ReadonlyMap<string, ModuleJsonSchemaDefinition>,
+): void {
+  const fields: Array<string | undefined> = [
+    tool.key,
+    tool.label,
+    tool.description,
+    tool.inputSchemaKey,
+    tool.outputSchemaKey,
+    tool.featureKey,
+    tool.permissionKey,
+    tool.auditAction,
+  ];
+  if (fields.some((value) => !value?.trim())) {
+    throw new Error("Agent Tool Key、展示信息与引用字段不能为空");
+  }
+  const rootNamespace = moduleName.split(".")[0]!;
+  if (!tool.key.startsWith(`${rootNamespace}.`)) {
+    throw new Error(
+      `Agent Tool ${tool.key} 必须使用模块根命名空间 ${rootNamespace}`,
+    );
+  }
+  requireSchema(tool.key, tool.inputSchemaKey, schemas);
+  requireSchema(tool.key, tool.outputSchemaKey, schemas);
+  if (tool.operation === "query" && tool.approval !== "none") {
+    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} 运行与输入输出上限必须是正整数`);
+  }
+}
+
+function requireSchema(
+  toolKey: string,
+  schemaKey: string,
+  schemas: ReadonlyMap<string, ModuleJsonSchemaDefinition>,
+): void {
+  if (!schemas.has(schemaKey)) {
+    throw new Error(`${toolKey} 引用了未注册 JSON Schema：${schemaKey}`);
+  }
+}

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

@@ -48,6 +48,7 @@ export type {
 export type {
   ModuleToolContext,
   ModuleToolHandlerRegistration,
+  ModuleToolInput,
   ModuleToolResult,
 } from "./src/tool-registration.js";
 export type {

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

@@ -29,6 +29,7 @@
   },
   "dependencies": {
     "@southwind-ai/jobs": "workspace:*",
+    "@southwind-ai/shared": "workspace:*",
     "@southwind-ai/storage": "workspace:*"
   },
   "exports": {

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

@@ -1,12 +1,7 @@
+import type { JsonValue } from "@southwind-ai/shared";
 import type { ModuleActor } from "./actor.js";
 
-export type ModuleAiJsonValue =
-  | string
-  | number
-  | boolean
-  | null
-  | ModuleAiJsonValue[]
-  | { [key: string]: ModuleAiJsonValue };
+export type ModuleAiJsonValue = JsonValue;
 
 export interface ModuleAiOperationContext {
   readonly actor: ModuleActor;

package/template/packages/server-sdk/src/tool-registration.ts

@@ -1,16 +1,15 @@
 import type { ModuleActor } from "./actor.js";
+import type { ModuleAiJsonValue } from "./ai-operation-registration.js";
 
 export interface ModuleToolContext {
   readonly actor: ModuleActor;
   readonly requestId: string;
+  readonly signal: AbortSignal;
 }
 
-export interface ModuleToolResult {
-  readonly items: unknown[];
-  readonly total: number;
-  readonly page: number;
-  readonly pageSize: number;
-}
+export type ModuleToolInput = Readonly<Record<string, ModuleAiJsonValue>>;
+
+export type ModuleToolResult = Readonly<Record<string, ModuleAiJsonValue>>;
 
 /**
  * 模块 Agent Tool 的 Handler 注册。
@@ -23,7 +22,7 @@ export interface ModuleToolHandlerRegistration {
   readonly toolKey: string;
   readonly scopeMode: "platform" | "request";
   execute(
-    query: Record<string, string | undefined>,
+    input: ModuleToolInput,
     context: ModuleToolContext,
   ): Promise<ModuleToolResult> | ModuleToolResult;
 }

package/template/packages/shared/index.ts

@@ -4,6 +4,7 @@ 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/json.js";
 export * from "./src/migration.js";
 export * from "./src/migration-bundle-validation.js";
 export * from "./src/module-configuration.js";

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

@@ -0,0 +1,8 @@
+export type JsonPrimitive = string | number | boolean | null;
+
+export type JsonValue =
+  | JsonPrimitive
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export type JsonObject = { [key: string]: JsonValue };