@southwind-ai/modules 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/modules",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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-operation-composition.ts

@@ -0,0 +1,145 @@
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "./manifest.js";
+
+interface AiOperationCatalogs {
+  permissions: ReadonlySet<string>;
+  features: ReadonlySet<string>;
+  audits: ReadonlySet<string>;
+  tools: 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,
+  );
+  validateCapabilities(operation);
+  validateTools(operation, catalogs.tools);
+  validateLimits(operation);
+}
+
+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,6 +3,8 @@ 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";
 
@@ -58,10 +60,16 @@ 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,
+  });
   const providers = modules.flatMap((module) => module.providers);
   unique(
     "Provider",
@@ -92,30 +100,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 +312,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

@@ -11,7 +11,10 @@ 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;
@@ -59,6 +62,37 @@ 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 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;
+  publicNetworkAccess: AiOperationPublicNetworkAccess;
+  limits: AiOperationLimits;
+}
+
 export interface ModuleManifest {
   name: string;
   version: string;
@@ -75,6 +109,7 @@ export interface ModuleManifest {
   schemaExports: ModuleSchemaExportDefinition[];
   tasks: ModuleScheduledTaskDefinition[];
   tools: ModuleToolDefinition[];
+  aiOperations?: ModuleAiOperationDefinition[];
   providers: Array<ModuleProviderDefinition | SearchProviderManifestDefinition>;
   dataPolicies?: DataGovernancePolicyDefinition[];
   auditActions: AuditActionRegistration[];
@@ -88,5 +123,6 @@ export interface ModuleImplementationBindings {
   apiRoutes?: readonly string[];
   tasks?: readonly string[];
   tools?: readonly string[];
+  aiOperations?: readonly string[];
   providers?: readonly string[];
 }

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
@@ -109,6 +112,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-features.ts

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