@southwind-ai/modules 0.1.2 → 0.1.4

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.4",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -12,7 +12,7 @@
     "!src/**/*.test.ts"
   ],
   "dependencies": {
-    "@southwind-ai/shared": "0.1.2"
+    "@southwind-ai/shared": "0.2.0"
   },
   "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

@@ -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",
@@ -56,6 +61,12 @@ export function systemApiPermissionBindings(): ApiPermissionBinding[] {
       "system.department.create",
       "system.rbac",
     ),
+    binding(
+      "POST",
+      "/api/system/departments/:id/transition",
+      "system.department.manage",
+      "system.rbac",
+    ),
     binding("GET", "/api/system/menus", "system.menu.read", "system.rbac"),
     binding(
       "GET",
@@ -221,12 +232,48 @@ export function systemApiPermissionBindings(): ApiPermissionBinding[] {
       "system.notification.read",
       "system.notification",
     ),
+    binding(
+      "GET",
+      "/api/notifications/preferences",
+      "system.notification.read",
+      "system.notification",
+    ),
+    binding(
+      "PUT",
+      "/api/notifications/preferences",
+      "system.notification.read",
+      "system.notification",
+    ),
     binding(
       "POST",
       "/api/notifications/:id/read",
       "system.notification.read",
       "system.notification",
     ),
+    binding(
+      "PUT",
+      "/api/notifications/:id/favorite",
+      "system.notification.read",
+      "system.notification",
+    ),
+    binding(
+      "DELETE",
+      "/api/notifications/:id/favorite",
+      "system.notification.read",
+      "system.notification",
+    ),
+    binding(
+      "GET",
+      "/api/system/notifications/audience-options",
+      "system.notification.manage",
+      "system.notification",
+    ),
+    binding(
+      "GET",
+      "/api/system/notifications/:id/deliveries",
+      "system.notification.manage",
+      "system.notification",
+    ),
     binding(
       "GET",
       "/api/system/notifications",
@@ -239,6 +286,18 @@ export function systemApiPermissionBindings(): ApiPermissionBinding[] {
       "system.notification.manage",
       "system.notification",
     ),
+    binding(
+      "PUT",
+      "/api/system/notifications/:id",
+      "system.notification.update",
+      "system.notification",
+    ),
+    binding(
+      "GET",
+      "/api/system/notifications/:id/revisions",
+      "system.notification.manage",
+      "system.notification",
+    ),
     binding(
       "DELETE",
       "/api/system/notifications/:id",

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",
@@ -17,9 +22,19 @@ export const systemAuditActions: ModuleManifest["auditActions"] = [
   // @windy-module system.license end
   "feature.update",
   "menu.structure.update",
+  {
+    key: "organization.department.transition",
+    label: "处置部门组织",
+    description: "迁移部门关联后停用或删除部门。",
+  },
   // @windy-module system.notification begin
   "notification.publish",
+  "notification.schedule",
+  "notification.preference.update",
+  "notification.update",
   "notification.read",
+  "notification.favorite",
+  "notification.unfavorite",
   "notification.archive",
   // @windy-module system.notification end
   // @windy-module system.workflow begin

package/src/system-features.ts

@@ -17,6 +17,11 @@ export const systemFeatures: ModuleManifest["features"] = [
     "RBAC 权限链路",
     "用户、角色、权限点与数据范围的统一访问控制链路。",
   ),
+  feature(
+    "system.user-directory",
+    "业务用户目录",
+    "向获授权业务模块提供受数据范围约束的启用用户最小只读投影。",
+  ),
   feature(
     "system.profile",
     "个人设置",
@@ -85,7 +90,7 @@ export const systemFeatures: ModuleManifest["features"] = [
   feature(
     "system.notification",
     "站内通知",
-    "站内通知发布、管理、阅读和已读状态闭环。",
+    "站内通知发布、修改历史、阅读、收藏和已读状态闭环。",
   ),
   // @windy-module system.notification end
   // @windy-module system.workflow 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
   {
@@ -116,7 +124,8 @@ export const systemModuleDefinitions = [
     name: "system.notification",
     version: "0.1.0",
     label: "站内通知",
-    description: "通知发布、阅读、归档与状态管理。",
+    description:
+      "通知定向与定时发布、用户偏好、外部渠道投递、修改历史、阅读、收藏和归档。",
     resources: ["notification"],
     featureKeys: ["system.notification"],
   },
@@ -218,6 +227,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 +235,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
       {
@@ -262,6 +270,18 @@ export function systemFoundationModule(): ModuleManifest {
         retryDelaySeconds: 30,
       },
       // @windy-module system.scheduler end
+      // @windy-module system.notification begin
+      {
+        key: "system.notification.dispatch",
+        label: "通知发布与外部投递",
+        description: "发布到期通知并领取持久投递队列，执行渠道重试。",
+        permissionKey: "system.notification.manage",
+        featureKey: "system.notification",
+        intervalSeconds: 5,
+        maxAttempts: 3,
+        retryDelaySeconds: 30,
+      },
+      // @windy-module system.notification end
       // @windy-module system.bulk-data begin
       {
         key: "system.bulk-data.dispatch",

package/src/system-permissions.ts

@@ -3,6 +3,7 @@ import type { ModuleManifest } from "./manifest.js";
 const systemResourceLabels = {
   admin: "管理面准入",
   user: "用户管理",
+  "user-directory": "业务用户目录",
   role: "角色与权限",
   department: "部门组织",
   menu: "菜单管理",
@@ -32,6 +33,7 @@ type SystemAction =
   | "approve"
   | "export"
   | "reveal"
+  | "update"
   | "manage";
 
 function permission(
@@ -53,11 +55,13 @@ function permission(
             ? "新建"
             : action === "approve"
               ? "处理"
-              : action === "reveal"
-                ? "查看明文"
-                : action === "export"
-                  ? "治理导出"
-                  : "管理",
+              : action === "update"
+                ? "修改"
+                : action === "reveal"
+                  ? "查看明文"
+                  : action === "export"
+                    ? "治理导出"
+                    : "管理",
     module: "system",
     moduleLabel: "系统基础设施",
     resource,
@@ -75,6 +79,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"),
@@ -123,6 +128,7 @@ export const systemPermissions: ModuleManifest["permissions"] = [
   // @windy-module system.scheduler end
   // @windy-module system.notification begin
   permission("notification", "read"),
+  permission("notification", "update"),
   permission("notification", "manage"),
   // @windy-module system.notification end
   // @windy-module system.bulk-data begin

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