@southwind-ai/modules 0.1.1 → 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.1",
+  "version": "0.1.3",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -12,7 +12,7 @@
     "!src/**/*.test.ts"
   ],
   "dependencies": {
-    "@southwind-ai/shared": "0.1.1"
+    "@southwind-ai/shared": "0.1.2"
   },
   "exports": {
     ".": "./index.ts"

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

@@ -0,0 +1,275 @@
+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(
+  modules: readonly ModuleManifest[],
+  catalogs: AiOperationCatalogs,
+): ModuleAiOperationDefinition[] {
+  const operations = modules.flatMap((module) => module.aiOperations || []);
+  uniqueValues(
+    "AI Operation",
+    operations.map(({ key }) => key),
+  );
+  for (const module of modules) {
+    for (const operation of module.aiOperations || []) {
+      validateOperation(module.name, operation, catalogs);
+    }
+  }
+  return operations;
+}
+
+export function validateAiOperationImplementations(
+  declarations: readonly ModuleAiOperationDefinition[],
+  implementations: readonly string[] | undefined,
+): void {
+  if (!implementations) return;
+  const declared = new Set(declarations.map(({ key }) => key));
+  const registered = uniqueValues("AI Operation Handler", implementations);
+  for (const key of declared) {
+    if (!registered.has(key)) {
+      throw new Error(`AI Operation ${key} 缺少 Handler`);
+    }
+  }
+  for (const key of registered) {
+    if (!declared.has(key)) {
+      throw new Error(`AI Operation Handler ${key} 缺少 Manifest 声明`);
+    }
+  }
+}
+
+function validateOperation(
+  moduleName: string,
+  operation: ModuleAiOperationDefinition,
+  catalogs: AiOperationCatalogs,
+): void {
+  const strings = [
+    operation.key,
+    operation.featureKey,
+    operation.permissionKey,
+    operation.auditAction,
+    operation.inputSchemaKey,
+    operation.outputSchemaKey,
+  ];
+  if (strings.some((value) => !value.trim())) {
+    throw new Error("AI Operation Key 与引用字段不能为空");
+  }
+  if (!operation.key.startsWith(`${moduleName}.`)) {
+    throw new Error(
+      `AI Operation ${operation.key} 必须使用模块命名空间 ${moduleName}`,
+    );
+  }
+  requiredReference(
+    operation.key,
+    "权限",
+    operation.permissionKey,
+    catalogs.permissions,
+  );
+  requiredReference(
+    operation.key,
+    "Feature",
+    operation.featureKey,
+    catalogs.features,
+  );
+  requiredReference(
+    operation.key,
+    "审计动作",
+    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`);
+  }
+  validateNonEmptyValues(
+    `${operation.key} capability`,
+    operation.requiredCapabilities,
+  );
+}
+
+function validateTools(
+  operation: ModuleAiOperationDefinition,
+  tools: ReadonlySet<string>,
+): void {
+  validateNonEmptyValues(`${operation.key} Tool`, operation.allowedToolKeys);
+  for (const toolKey of operation.allowedToolKeys) {
+    requiredReference(operation.key, "Agent Tool", toolKey, tools);
+  }
+}
+
+function validateLimits(operation: ModuleAiOperationDefinition): void {
+  const values = Object.values(operation.limits);
+  if (values.some((value) => !Number.isSafeInteger(value) || value <= 0)) {
+    throw new Error(`${operation.key} 运行与输入输出上限必须是正整数`);
+  }
+}
+
+function validateNonEmptyValues(label: string, values: readonly string[]) {
+  if (values.some((value) => !value.trim())) {
+    throw new Error(`${label} 不能为空`);
+  }
+  uniqueValues(label, values);
+}
+
+function requiredReference(
+  operationKey: string,
+  label: string,
+  key: string,
+  catalog: ReadonlySet<string>,
+): void {
+  if (!catalog.has(key)) {
+    throw new Error(`${operationKey} 引用了未注册${label}：${key}`);
+  }
+}
+
+function uniqueValues(label: string, values: readonly string[]): Set<string> {
+  const result = new Set<string>();
+  for (const value of values) {
+    if (result.has(value)) throw new Error(`${label} Key 重复：${value}`);
+    result.add(value);
+  }
+  return result;
+}

package/src/catalog-validation.ts

@@ -2,6 +2,9 @@ import {
   AUDIT_ACTION_DEFINITIONS,
   isAuditActionDefinition,
   LICENSE_CATALOG,
+  normalizeManifestBundles,
+  validateAndOrderBundles,
+  validateLicenseCatalog,
   type AuditActionDefinition,
   type FeatureFlagDefinition,
   type LicenseCatalogDefinition,
@@ -15,15 +18,29 @@ export interface PlatformCapabilityCatalogs {
 
 export function validateCapabilityCatalogs(
   modules: readonly ModuleManifest[],
+  licenseCatalog: readonly LicenseCatalogDefinition[] = LICENSE_CATALOG,
 ): PlatformCapabilityCatalogs {
   const auditActions = composeAuditActionCatalog(modules);
-  validateFeatureCatalog(modules, LICENSE_CATALOG);
+  validateLicenseCatalog(licenseCatalog);
+  validateFeatureCatalog(modules, licenseCatalog);
+  validateMigrationBundleCatalog(modules);
   return {
     auditActions,
-    licenseVersions: LICENSE_CATALOG,
+    licenseVersions: licenseCatalog,
   };
 }
 
+/**
+ * 启动期结构校验显式声明 migrationBundle 的模块；无 bundle 的旧式模块
+ * 由 drizzle 规范迁移管理，不参与模块级 Bundle 校验。
+ */
+export function validateMigrationBundleCatalog(
+  modules: readonly ModuleManifest[],
+): void {
+  const bundled = modules.filter((module) => module.migrationBundle);
+  validateAndOrderBundles(normalizeManifestBundles(bundled));
+}
+
 export function composeAuditActionCatalog(
   modules: readonly ModuleManifest[],
 ): AuditActionDefinition[] {

package/src/composition.ts

@@ -3,8 +3,11 @@ import type {
   ModuleImplementationBindings,
   ModuleManifest,
 } from "./manifest.js";
+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[];
@@ -33,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]),
@@ -58,10 +62,17 @@ export function validateModuleComposition(
     tasks.map(({ key }) => key),
   );
   const tools = modules.flatMap((module) => module.tools);
-  unique(
+  const toolKeys = unique(
     "Agent Tool",
     tools.map(({ key }) => key),
   );
+  const aiOperations = validateAiOperations(modules, {
+    permissions,
+    features,
+    audits,
+    tools: toolKeys,
+    schemas: new Set(jsonSchemas.keys()),
+  });
   const providers = modules.flatMap((module) => module.providers);
   unique(
     "Provider",
@@ -92,30 +103,16 @@ export function validateModuleComposition(
   }
   validateMenuRoutes(menus, adminRoutes);
   validateSchemaMigrations(schemas);
-  validateImplementations(
-    "Admin Route",
-    adminRoutes.map(({ key }) => key),
-    implementations.adminRoutes,
-  );
-  validateImplementations(
-    "API Route",
-    apiRoutes.map(apiRouteKey),
-    implementations.apiRoutes,
-  );
-  validateImplementations(
-    "定时任务",
-    tasks.map(({ key }) => key),
-    implementations.tasks,
-  );
-  validateImplementations(
-    "Agent Tool",
-    tools.map(({ key }) => key),
-    implementations.tools,
-  );
-  validateImplementations(
-    "Provider",
-    providers.map(({ key }) => key),
-    implementations.providers,
+  validateImplementationBindings(
+    {
+      adminRoutes: adminRoutes.map(({ key }) => key),
+      apiRoutes: apiRoutes.map(apiRouteKey),
+      tasks: tasks.map(({ key }) => key),
+      tools: tools.map(({ key }) => key),
+      providers: providers.map(({ key }) => key),
+    },
+    aiOperations,
+    implementations,
   );
 
   return { modules, moduleOrder };
@@ -318,18 +315,6 @@ function validateSchemaMigrations(
   }
 }
 
-function validateImplementations(
-  label: string,
-  declarations: readonly string[],
-  implementations: readonly string[] | undefined,
-): void {
-  if (!implementations) return;
-  const registered = unique(`${label} Handler`, implementations);
-  for (const key of declarations) {
-    if (!registered.has(key)) throw new Error(`${label} ${key} 缺少 Handler`);
-  }
-}
-
 function unique(label: string, values: readonly string[]): Set<string> {
   const result = new Set<string>();
   for (const value of values) {

package/src/implementation-bindings.ts

@@ -0,0 +1,70 @@
+import { validateAiOperationImplementations } from "./ai-operation-composition.js";
+import type {
+  ModuleAiOperationDefinition,
+  ModuleImplementationBindings,
+} from "./manifest.js";
+
+interface ModuleDeclarationKeys {
+  adminRoutes: readonly string[];
+  apiRoutes: readonly string[];
+  tasks: readonly string[];
+  tools: readonly string[];
+  providers: readonly string[];
+}
+
+export function validateImplementationBindings(
+  declarations: ModuleDeclarationKeys,
+  aiOperations: readonly ModuleAiOperationDefinition[],
+  implementations: ModuleImplementationBindings,
+): void {
+  validateImplementations(
+    "Admin Route",
+    declarations.adminRoutes,
+    implementations.adminRoutes,
+  );
+  validateImplementations(
+    "API Route",
+    declarations.apiRoutes,
+    implementations.apiRoutes,
+  );
+  validateImplementations(
+    "定时任务",
+    declarations.tasks,
+    implementations.tasks,
+  );
+  validateImplementations(
+    "Agent Tool",
+    declarations.tools,
+    implementations.tools,
+  );
+  validateAiOperationImplementations(
+    aiOperations,
+    implementations.aiOperations,
+  );
+  validateImplementations(
+    "Provider",
+    declarations.providers,
+    implementations.providers,
+  );
+}
+
+function validateImplementations(
+  label: string,
+  declarations: readonly string[],
+  implementations: readonly string[] | undefined,
+): void {
+  if (!implementations) return;
+  const registered = unique(`${label} Handler`, implementations);
+  for (const key of declarations) {
+    if (!registered.has(key)) throw new Error(`${label} ${key} 缺少 Handler`);
+  }
+}
+
+function unique(label: string, values: readonly string[]): Set<string> {
+  const result = new Set<string>();
+  for (const value of values) {
+    if (result.has(value)) throw new Error(`${label} Key 重复：${value}`);
+    result.add(value);
+  }
+  return result;
+}

package/src/manifest.ts

@@ -4,6 +4,7 @@ import type {
   AuditActionType,
   DataGovernancePolicyDefinition,
   FeatureFlagDefinition,
+  JsonObject,
   MigrationBundle,
   MigrationDefinition,
   MenuNode,
@@ -11,15 +12,35 @@ import type {
   SearchProviderManifestDefinition,
 } from "@southwind-ai/shared";
 
-export type { MigrationDefinition, MigrationDirection } from "@southwind-ai/shared";
+export type {
+  MigrationDefinition,
+  MigrationDirection,
+} from "@southwind-ai/shared";
 
 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";
@@ -59,6 +80,75 @@ export interface ModuleScheduledTaskDefinition {
   retryDelaySeconds: number;
 }
 
+export type AiOperationKind = "agent" | "document" | "speech";
+export type AiOperationDataClassification = "public" | "internal" | "sensitive";
+export type AiOperationExecution =
+  | "interactive"
+  | "streaming"
+  | "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;
+  maxInputBytes: number;
+  maxOutputBytes: number;
+}
+
+export interface ModuleAiOperationDefinition {
+  key: string;
+  kind: AiOperationKind;
+  featureKey: string;
+  permissionKey: string;
+  auditAction: AuditActionType;
+  inputSchemaKey: string;
+  outputSchemaKey: string;
+  requiredCapabilities: readonly string[];
+  allowedToolKeys: readonly string[];
+  dataClassification: AiOperationDataClassification;
+  execution: AiOperationExecution;
+  /** @deprecated 使用 providerEgress 与 toolNetworkPolicy 拆分两类网络边界。 */
+  publicNetworkAccess?: AiOperationPublicNetworkAccess;
+  providerEgress?: AiProviderEgressPolicy;
+  providerDataPolicy?: AiProviderDataPolicy;
+  toolNetworkPolicy?: AiToolNetworkPolicy;
+  limits: AiOperationLimits;
+}
+
 export interface ModuleManifest {
   name: string;
   version: string;
@@ -73,8 +163,10 @@ export interface ModuleManifest {
   migrations: MigrationDefinition[];
   migrationBundle?: MigrationBundle;
   schemaExports: ModuleSchemaExportDefinition[];
+  jsonSchemas?: ModuleJsonSchemaDefinition[];
   tasks: ModuleScheduledTaskDefinition[];
   tools: ModuleToolDefinition[];
+  aiOperations?: ModuleAiOperationDefinition[];
   providers: Array<ModuleProviderDefinition | SearchProviderManifestDefinition>;
   dataPolicies?: DataGovernancePolicyDefinition[];
   auditActions: AuditActionRegistration[];
@@ -88,5 +180,6 @@ export interface ModuleImplementationBindings {
   apiRoutes?: readonly string[];
   tasks?: readonly string[];
   tools?: readonly string[];
+  aiOperations?: readonly string[];
   providers?: readonly string[];
 }

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

@@ -1,5 +1,8 @@
 import type { ApiPermissionBinding } from "@southwind-ai/shared";
 import { binding, resourceBindings } from "./system-api-binding.js";
+// @windy-module system.settings begin
+import { watermarkApiPermissionBindings } from "./system-api-watermark.js";
+// @windy-module system.settings end
 // @windy-module system.data-governance begin
 import { dataGovernanceApiPermissionBindings } from "./system-api-data-governance.js";
 // @windy-module system.data-governance end
@@ -22,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",
@@ -109,6 +117,7 @@ export function systemApiPermissionBindings(): ApiPermissionBinding[] {
       "system.settings.manage",
       "system.settings",
     ),
+    ...watermarkApiPermissionBindings(),
     // @windy-module system.settings end
     // @windy-module system.configuration begin
     binding(

package/src/system-api-watermark.ts

@@ -0,0 +1,26 @@
+import type { ApiPermissionBinding } from "@southwind-ai/shared";
+import { binding } from "./system-api-binding.js";
+
+export function watermarkApiPermissionBindings(): ApiPermissionBinding[] {
+  return [
+    binding(
+      "GET",
+      "/api/platform/watermark-policy",
+      "system.watermark.read",
+      undefined,
+      true,
+    ),
+    binding(
+      "GET",
+      "/api/system/settings/watermark",
+      "system.watermark.read",
+      "system.watermark",
+    ),
+    binding(
+      "PUT",
+      "/api/system/settings/watermark",
+      "system.watermark.manage",
+      "system.watermark",
+    ),
+  ];
+}

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",
     "个人设置",
@@ -43,7 +48,7 @@ export const systemFeatures: ModuleManifest["features"] = [
   feature(
     "system.watermark",
     "页面水印",
-    "带身份信息的页面水印与用户显示偏好。",
+    "由平台统一管理并覆盖 Admin 与业务页面的身份水印策略。",
   ),
   // @windy-module system.settings end
   // @windy-module system.license begin

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