@southwind-ai/modules 0.1.2 → 0.1.3

package/index.ts

@@ -6,3 +6,5 @@ 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";
+export * from "./src/ai-network-policy.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/modules",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/src/ai-network-policy.ts

@@ -0,0 +1,50 @@
+import type {
+  AiProviderEgressPolicy,
+  AiToolNetworkPolicy,
+  ModuleAiOperationDefinition,
+} from "./manifest.js";
+
+const providerForbidden: AiProviderEgressPolicy = Object.freeze({
+  mode: "forbidden",
+});
+const toolNetworkForbidden: AiToolNetworkPolicy = Object.freeze({
+  mode: "forbidden",
+});
+
+export function resolveProviderEgress(
+  operation: ModuleAiOperationDefinition,
+): AiProviderEgressPolicy {
+  return operation.providerEgress ?? providerForbidden;
+}
+
+export function resolveToolNetworkPolicy(
+  operation: ModuleAiOperationDefinition,
+): AiToolNetworkPolicy {
+  return operation.toolNetworkPolicy ?? toolNetworkForbidden;
+}
+
+export function validateAiNetworkPolicy(
+  operation: ModuleAiOperationDefinition,
+): void {
+  const provider = resolveProviderEgress(operation);
+  if (provider.mode === "configured-endpoint") {
+    if (!provider.deploymentKey.trim()) {
+      throw new Error(`${operation.key} Provider Deployment Key 不能为空`);
+    }
+  } else if (provider.mode !== "forbidden") {
+    throw new Error(`${operation.key} Provider 出网策略无效`);
+  }
+
+  const tool = resolveToolNetworkPolicy(operation);
+  if (tool.mode !== "forbidden") {
+    throw new Error(`${operation.key} Tool 网络策略无效`);
+  }
+  if (
+    operation.publicNetworkAccess === "allowed" &&
+    operation.providerEgress === undefined
+  ) {
+    throw new Error(
+      `${operation.key} 旧 publicNetworkAccess=allowed 不能安全映射，请声明 providerEgress`,
+    );
+  }
+}

package/src/ai-operation-composition.ts

@@ -2,12 +2,14 @@ import type {
   ModuleAiOperationDefinition,
   ModuleManifest,
 } from "./manifest.js";
+import { validateAiNetworkPolicy } from "./ai-network-policy.js";
 
 interface AiOperationCatalogs {
   permissions: ReadonlySet<string>;
   features: ReadonlySet<string>;
   audits: ReadonlySet<string>;
   tools: ReadonlySet<string>;
+  schemas: ReadonlySet<string>;
 }
 
 export function validateAiOperations(
@@ -85,11 +87,139 @@ 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);
+  validateAiNetworkPolicy(operation);
+  validateProviderDataPolicy(operation);
   validateLimits(operation);
 }
 
+const providerDataFields = new Set([
+  "instructions",
+  "user-prompt",
+  "tool-definitions",
+  "provider-output",
+  "tool-results",
+]);
+
+export function validateProviderDataPolicy(
+  operation: ModuleAiOperationDefinition,
+): void {
+  const policy = operation.providerDataPolicy;
+  if (operation.providerEgress?.mode !== "configured-endpoint") {
+    if (policy) {
+      throw new Error(
+        `${operation.key} 禁止 Provider 出网时不能声明字段发送策略`,
+      );
+    }
+    return;
+  }
+  if (!policy?.inputFields.length || !policy.envelopeFields.length) {
+    throw new Error(`${operation.key} Provider 字段发送 allowlist 缺失`);
+  }
+  validateInputFields(operation.key, policy.inputFields);
+  const fields = new Set<string>();
+  for (const rule of policy.envelopeFields) {
+    if (!providerDataFields.has(rule.field)) {
+      throw new Error(
+        `${operation.key} Provider 字段发送 allowlist 含未知字段`,
+      );
+    }
+    if (fields.has(rule.field)) {
+      throw new Error(
+        `${operation.key} Provider 字段发送规则重复：${rule.field}`,
+      );
+    }
+    fields.add(rule.field);
+    if (!["public", "internal", "sensitive"].includes(rule.classification)) {
+      throw new Error(`${operation.key} Provider 字段分类无效：${rule.field}`);
+    }
+    if (!["reject", "redact"].includes(rule.dlpAction)) {
+      throw new Error(`${operation.key} Provider DLP 动作无效：${rule.field}`);
+    }
+  }
+  for (const field of ["instructions", "user-prompt"]) {
+    if (!fields.has(field)) {
+      throw new Error(
+        `${operation.key} Provider 字段发送 allowlist 缺少 ${field}`,
+      );
+    }
+  }
+  if (operation.allowedToolKeys.length) {
+    for (const field of [
+      "tool-definitions",
+      "provider-output",
+      "tool-results",
+    ]) {
+      if (!fields.has(field)) {
+        throw new Error(
+          `${operation.key} 使用 Tool 时 Provider 字段发送 allowlist 缺少 ${field}`,
+        );
+      }
+    }
+  }
+}
+
+function validateInputFields(
+  operationKey: string,
+  fields: NonNullable<
+    ModuleAiOperationDefinition["providerDataPolicy"]
+  >["inputFields"],
+): void {
+  const pointers = new Set<string>();
+  for (const rule of fields) {
+    const segments = rule.jsonPointer
+      .slice(1)
+      .split("/")
+      .map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~"));
+    if (
+      !rule.jsonPointer.startsWith("/") ||
+      rule.jsonPointer === "/" ||
+      rule.jsonPointer.endsWith("/") ||
+      rule.jsonPointer.includes("//") ||
+      /~(?:[^01]|$)/u.test(rule.jsonPointer) ||
+      segments.some((segment) =>
+        ["__proto__", "prototype", "constructor"].includes(segment),
+      )
+    ) {
+      throw new Error(`${operationKey} Provider 输入字段 JSON Pointer 无效`);
+    }
+    if (
+      [...pointers].some(
+        (pointer) =>
+          pointer.startsWith(`${rule.jsonPointer}/`) ||
+          rule.jsonPointer.startsWith(`${pointer}/`),
+      )
+    ) {
+      throw new Error(`${operationKey} Provider 输入字段规则不能父子重叠`);
+    }
+    if (pointers.has(rule.jsonPointer)) {
+      throw new Error(
+        `${operationKey} Provider 输入字段规则重复：${rule.jsonPointer}`,
+      );
+    }
+    pointers.add(rule.jsonPointer);
+    if (!["public", "internal", "sensitive"].includes(rule.classification)) {
+      throw new Error(`${operationKey} Provider 输入字段分类无效`);
+    }
+    if (!["reject", "redact"].includes(rule.dlpAction)) {
+      throw new Error(`${operationKey} Provider 输入字段 DLP 动作无效`);
+    }
+  }
+}
+
 function validateCapabilities(operation: ModuleAiOperationDefinition): void {
   if (!operation.requiredCapabilities.length) {
     throw new Error(`${operation.key} 至少需要一个 capability`);

package/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/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";
@@ -70,6 +88,40 @@ export type AiOperationExecution =
   | "background"
   | "live";
 export type AiOperationPublicNetworkAccess = "forbidden" | "allowed";
+export type AiProviderEgressPolicy =
+  | { mode: "forbidden" }
+  | {
+      mode: "configured-endpoint";
+      deploymentKey: string;
+    };
+export interface AiToolNetworkPolicy {
+  mode: "forbidden";
+}
+
+export type AiProviderDataField =
+  | "instructions"
+  | "user-prompt"
+  | "tool-definitions"
+  | "provider-output"
+  | "tool-results";
+export type AiProviderDlpAction = "reject" | "redact";
+
+export interface AiProviderFieldPolicy {
+  field: AiProviderDataField;
+  classification: AiOperationDataClassification;
+  dlpAction: AiProviderDlpAction;
+}
+
+export interface AiProviderInputFieldPolicy {
+  jsonPointer: string;
+  classification: AiOperationDataClassification;
+  dlpAction: AiProviderDlpAction;
+}
+
+export interface AiProviderDataPolicy {
+  inputFields: readonly AiProviderInputFieldPolicy[];
+  envelopeFields: readonly AiProviderFieldPolicy[];
+}
 
 export interface AiOperationLimits {
   maxDurationSeconds: number;
@@ -89,7 +141,11 @@ export interface ModuleAiOperationDefinition {
   allowedToolKeys: readonly string[];
   dataClassification: AiOperationDataClassification;
   execution: AiOperationExecution;
-  publicNetworkAccess: AiOperationPublicNetworkAccess;
+  /** @deprecated 使用 providerEgress 与 toolNetworkPolicy 拆分两类网络边界。 */
+  publicNetworkAccess?: AiOperationPublicNetworkAccess;
+  providerEgress?: AiProviderEgressPolicy;
+  providerDataPolicy?: AiProviderDataPolicy;
+  toolNetworkPolicy?: AiToolNetworkPolicy;
   limits: AiOperationLimits;
 }
 
@@ -107,6 +163,7 @@ export interface ModuleManifest {
   migrations: MigrationDefinition[];
   migrationBundle?: MigrationBundle;
   schemaExports: ModuleSchemaExportDefinition[];
+  jsonSchemas?: ModuleJsonSchemaDefinition[];
   tasks: ModuleScheduledTaskDefinition[];
   tools: ModuleToolDefinition[];
   aiOperations?: ModuleAiOperationDefinition[];

package/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/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/src/system-audit-actions.ts

@@ -8,6 +8,11 @@ export const systemAuditActions: ModuleManifest["auditActions"] = [
   "crud.create",
   "crud.update",
   "crud.delete",
+  {
+    key: "system.user-directory.query",
+    label: "查询业务用户目录",
+    description: "业务模块在平台授权与数据范围内查询启用用户最小投影。",
+  },
   // @windy-module system.configuration begin
   "config.update",
   "config.rollback",

package/src/system-features.ts

@@ -17,6 +17,11 @@ export const systemFeatures: ModuleManifest["features"] = [
     "RBAC 权限链路",
     "用户、角色、权限点与数据范围的统一访问控制链路。",
   ),
+  feature(
+    "system.user-directory",
+    "业务用户目录",
+    "向获授权业务模块提供受数据范围约束的启用用户最小只读投影。",
+  ),
   feature(
     "system.profile",
     "个人设置",

package/src/system-module-catalog.ts

@@ -27,9 +27,17 @@ export const systemModuleDefinitions = [
     version: "0.1.0",
     label: "身份与权限",
     description: "用户、角色、部门、菜单、字典、个人资料和数据范围。",
-    resources: ["user", "role", "department", "menu", "dict", "profile"],
+    resources: [
+      "user",
+      "user-directory",
+      "role",
+      "department",
+      "menu",
+      "dict",
+      "profile",
+    ],
     excludedPermissionKeys: ["system.user.reveal", "system.user.export"],
-    featureKeys: ["system.rbac", "system.profile"],
+    featureKeys: ["system.rbac", "system.user-directory", "system.profile"],
   },
   // @windy-module system.settings begin
   {
@@ -218,6 +226,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),
@@ -225,11 +234,26 @@ function createSystemCapabilityModule(
       definition.name === "system.data-governance"
         ? aggregate.dataPolicies
         : [],
-    auditActions: isCore ? aggregate.auditActions : [],
+    auditActions: isCore
+      ? aggregate.auditActions.filter(
+          (action) => auditActionKey(action) !== "system.user-directory.query",
+        )
+      : definition.name === "system.identity"
+        ? aggregate.auditActions.filter(
+            (action) =>
+              auditActionKey(action) === "system.user-directory.query",
+          )
+        : [],
     metadata: { kind: "platform-capability" },
   };
 }
 
+function auditActionKey(
+  action: ModuleManifest["auditActions"][number],
+): string {
+  return typeof action === "string" ? action : action.key;
+}
+
 function permissionResource(permissionKey: string): string {
   const parts = permissionKey.split(".");
   return parts.length >= 3 ? parts.slice(1, -1).join(".") : "";

package/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/src/system-permissions.ts

@@ -3,6 +3,7 @@ import type { ModuleManifest } from "./manifest.js";
 const systemResourceLabels = {
   admin: "管理面准入",
   user: "用户管理",
+  "user-directory": "业务用户目录",
   role: "角色与权限",
   department: "部门组织",
   menu: "菜单管理",
@@ -75,6 +76,7 @@ export const systemPermissions: ModuleManifest["permissions"] = [
   permission("user", "export", "governed-export"),
   // @windy-module system.data-governance end
   permission("user", "manage"),
+  permission("user-directory", "read"),
   permission("role", "read"),
   permission("role", "manage"),
   permission("department", "read"),

package/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}`);
+  }
+}