企业级 AI Agent 工具接口语义漂移检测与契约治理实战：应对外部 API 静默演进的自适应防御架构

/**
 * 企业级 AI Agent 工具接口契约守护与语义漂移检测中间件
 * 核心功能：
 * 1. 结构化 JSON Schema 严格校验与类型推导；
 * 2. 接口版本基线差分计算（Diff Engine），识别破坏性变更（Breaking Changes）；
 * 3. 运行时参数自适应标准化与语义投影映射；
 * 4. 契约失效熔断器（Circuit Breaker），杜绝外部接口静默突变引发生产灾难。
 */

// 契约字段定义接口
export interface ToolPropertySchema {
  // 字段数据类型
  type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
  // 面向大模型与开发者的自然语言语义说明
  description: string;
  // 允许的枚举值集合（可选）
  enum?: (string | number)[];
  // 默认值（可选）
  default?: unknown;
  // 嵌套对象或数组项规格
  items?: ToolPropertySchema;
  properties?: Record<string, ToolPropertySchema>;
}

// 工具接口完整契约规范
export interface ToolContractDefinition {
  // 工具唯一标识名称（对应 Function Calling name）
  name: string;
  // 工具全局业务功能描述（注入系统提示词）
  description: string;
  // 契约语义版本号（遵循 SemVer）
  version: string;
  // 参数 JSON Schema 定义
  parameters: {
    type: 'object';
    properties: Record<string, ToolPropertySchema>;
    // 必填字段列表
    required: string[];
  };
  // 是否包含不可逆外部系统写操作副作用
  isMutating: boolean;
}

// 契约变更严重度枚举
export enum DriftSeverity {
  // 破坏性变更：阻断调用并触发熔断
  CRITICAL = 'CRITICAL',
  // 潜在语义风险：允许自适应代偿投影并记录告警
  WARNING = 'WARNING',
  // 向后兼容平滑更新：自动同步
  INFO = 'INFO'
}

// 契约差分项记录
export interface ContractDiffItem {
  severity: DriftSeverity;
  fieldPath: string;
  changeType: 'ADDED_REQUIRED' | 'TYPE_MISMATCH' | 'ENUM_REMOVED' | 'DESCRIPTION_CHANGED' | 'ADDED_OPTIONAL';
  message: string;
}

// 契约守护与漂移检测核心引擎
export class ToolContractGuard {
  // 内存中维护的工具活跃契约注册表
  private activeContracts: Map<string, ToolContractDefinition> = new Map();
  // 工具熔断状态表（工具名映射为是否处于熔断保护）
  private circuitBreakers: Map<string, boolean> = new Map();

  /**
   * 注册或更新基线契约
   * @param contract 工具契约定义
   */
  public registerContract(contract: ToolContractDefinition): void {
    this.activeContracts.set(contract.name, contract);
    this.circuitBreakers.set(contract.name, false);
  }

  /**
   * 核心功能一：比对新旧契约，计算语义漂移（Schema Diff）
   * @param oldContract 基线契约
   * @param newContract 外部网关最新抓取的接口契约
   */
  public detectDrift(
    oldContract: ToolContractDefinition,
    newContract: ToolContractDefinition
  ): ContractDiffItem[] {
    const diffs: ContractDiffItem[] = [];

    const oldProps = oldContract.parameters.properties;
    const newProps = newContract.parameters.properties;
    const oldRequired = new Set(oldContract.parameters.required || []);
    const newRequired = new Set(newContract.parameters.required || []);

    // 1. 检查新增的必填项（破坏性变更）
    for (const reqField of newRequired) {
      if (!oldRequired.has(reqField)) {
        diffs.push({
          severity: DriftSeverity.CRITICAL,
          fieldPath: `parameters.${reqField}`,
          changeType: 'ADDED_REQUIRED',
          message: `外部系统将字段 [${reqField}] 设为强制必填项，大模型历史提示词未包含此项约束。`
        });
      }
    }

    // 2. 检查现有字段的类型与枚举漂移
    for (const [key, oldProp] of Object.entries(oldProps)) {
      const newProp = newProps[key];
      if (!newProp) {
        // 字段被删除
        const isCritical = oldRequired.has(key);
        diffs.push({
          severity: isCritical ? DriftSeverity.CRITICAL : DriftSeverity.WARNING,
          fieldPath: `parameters.${key}`,
          changeType: 'TYPE_MISMATCH',
          message: `字段 [${key}] 已在最新外部接口中移除。`
        });
        continue;
      }

      // 类型不一致校验
      if (oldProp.type !== newProp.type) {
        diffs.push({
          severity: DriftSeverity.CRITICAL,
          fieldPath: `parameters.${key}`,
          changeType: 'TYPE_MISMATCH',
          message: `字段 [${key}] 数据类型由 ${oldProp.type} 变更为 ${newProp.type}。`
        });
      }

      // 枚举收窄检查
      if (oldProp.enum && newProp.enum) {
        const newEnumSet = new Set(newProp.enum);
        const removedValues = oldProp.enum.filter(val => !newEnumSet.has(val));
        if (removedValues.length > 0) {
          diffs.push({
            severity: DriftSeverity.WARNING,
            fieldPath: `parameters.${key}.enum`,
            changeType: 'ENUM_REMOVED',
            message: `字段 [${key}] 枚举值已废弃或移除: [${removedValues.join(', ')}]。`
          });
        }
      }

      // 语义描述显著变动检查
      if (oldProp.description !== newProp.description) {
        diffs.push({
          severity: DriftSeverity.INFO,
          fieldPath: `parameters.${key}.description`,
          changeType: 'DESCRIPTION_CHANGED',
          message: `字段 [${key}] 语义描述更新，需要刷新系统提示词。`
        });
      }
    }

    return diffs;
  }

  /**
   * 核心功能二：运行时拦截大模型生成的调用参数并执行校验与投影适配
   * @param toolName 工具名称
   * @param rawParams 大语言模型 Function Calling 输出的原始入参
   * @returns 处理清洗后的合格参数，若阻断则抛出明确契约异常
   */
  public validateAndAdaptInvocation(
    toolName: string,
    rawParams: Record<string, unknown>
  ): Record<string, unknown> {
    const contract = this.activeContracts.get(toolName);
    if (!contract) {
      throw new Error(`[契约守护] 未知工具名称: ${toolName}，拒绝未知端点调用。`);
    }

    // 检查熔断器状态
    if (this.circuitBreakers.get(toolName)) {
      throw new Error(`[契约熔断] 工具 [${toolName}] 因外部接口发生严重破坏性漂移已熔断，请人工介入。`);
    }

    const adaptedParams: Record<string, unknown> = { ...rawParams };
    const { properties, required } = contract.parameters;

    // 1. 严格必填项检查
    for (const reqField of required) {
      if (adaptedParams[reqField] === undefined || adaptedParams[reqField] === null || adaptedParams[reqField] === '') {
        // 尝试使用默认值补齐
        if (properties[reqField]?.default !== undefined) {
          adaptedParams[reqField] = properties[reqField].default;
        } else {
          throw new Error(`[契约校验失败] 工具 [${toolName}] 缺少必需参数: [${reqField}]。`);
        }
      }
    }

    // 2. 字段类型适配与数据清洗
    for (const [key, propDef] of Object.entries(properties)) {
      const val = adaptedParams[key];
      if (val === undefined || val === null) continue;

      // 整型自动纠偏（防范大模型输出浮点或字符串数值）
      if (propDef.type === 'integer' || propDef.type === 'number') {
        const num = Number(val);
        if (Number.isNaN(num)) {
          throw new Error(`[契约类型错误] 参数 [${key}] 期望数值类型，实际输入: ${String(val)}`);
        }
        adaptedParams[key] = propDef.type === 'integer' ? Math.floor(num) : num;
      }

      // 枚举归一化适配（兼容大小写或同义缩写）
      if (propDef.enum && typeof val === 'string') {
        const match = propDef.enum.find(e => String(e).toLowerCase() === val.toLowerCase());
        if (match !== undefined) {
          adaptedParams[key] = match; // 自动转换为官方规范枚举格式
        } else {
          throw new Error(`[契约枚举失效] 参数 [${key}] 取值 [${val}] 不在有效枚举范围内: [${propDef.enum.join(', ')}]`);
        }
      }
    }

    return adaptedParams;
  }

  /**
   * 触发工具熔断隔离
   */
  public tripCircuitBreaker(toolName: string, reason: string): void {
    this.circuitBreakers.set(toolName, true);
    console.error(`[契约守护紧急熔断] 工具 [${toolName}] 契约守护激活，原因: ${reason}`);
  }
}