企业级 AI Agent“影子模式与双跑比对”（Shadow Mode & Dual-Run Testing）生产准入实战：破解不确定性智能体上线风险、写操作沙箱隔离与差异对账矩阵

import { EventEmitter } from 'node:events';

/**
 * 工具操作类型枚举：区分只读与变更副作用
 */
export enum ToolOperationType {
  READ_ONLY = 'READ_ONLY',         // 只读操作：可安全访问生产只读副本
  MUTATING_WRITE = 'MUTATING_WRITE', // 写入变更：必须严格沙箱拦截
}

/**
 * 工具定义元数据契约接口
 */
export interface ToolContract {
  name: string;                   // 工具名称
  type: ToolOperationType;        // 操作类型分类
  schema: Record<string, unknown>; // JSON 验证契约
}

/**
 * 工具执行请求调用上下文
 */
export interface ToolInvocationContext {
  traceId: string;                // 分布式追踪链路标识符
  toolName: string;               // 目标工具名称
  arguments: Record<string, unknown>; // 工具入参对象
  isShadowRun: boolean;           // 是否处于影子双跑模式
}

/**
 * 双跑比对结果记录结构
 */
export interface DualRunReconciliationRecord {
  traceId: string;                // 追踪标识
  timestamp: string;              // 对账时间戳
  liveTrajectory: string[];       // 生产在线工具执行序列
  shadowTrajectory: string[];     // 影子候选工具执行序列
  trajectoryAlignmentScore: number; // 轨迹对齐相似度分值 (0~1.0)
  interceptedWriteCount: number;  // 拦截的可写工具调用次数
  criticalDiffDetected: boolean;  // 是否检测到严重业务分歧
  diffDetails: string[];          // 细粒度差异明细记录
}

/**
 * 生产级企业智能体影子对账与拦截网关核心引擎
 */
export class ShadowReconciliationGateway extends EventEmitter {
  // 注册的工具安全契约字典表
  private readonly toolRegistry: Map<string, ToolContract> = new Map();
  // 影子会话虚拟状态缓存字典表
  private readonly virtualStateCache: Map<string, Map<string, unknown>> = new Map();

  /**
   * 构造函数：初始化网关事件监听器
   */
  constructor() {
    super();
  }

  /**
   * 注册企业工具安全契约
   * @param contract 工具元数据契约定义
   */
  public registerTool(contract: ToolContract): void {
    this.toolRegistry.set(contract.name, contract);
  }

  /**
   * 执行工具调用拦截与路由决策
   * @param context 工具执行调用上下文
   * @returns 工具调用结果（真实执行或虚拟合成）
   */
  public async executeToolIntercept(
    context: ToolInvocationContext
  ): Promise<{ payload: unknown; intercepted: boolean }> {
    const contract = this.toolRegistry.get(context.toolName);
    if (!contract) {
      throw new Error(`[SecurityError] 未知工具调用拦截: ${context.toolName}`);
    }

    // 若非影子模式，直接透传由底层系统实际执行
    if (!context.isShadowRun) {
      return { payload: await this.invokeProductionTool(context), intercepted: false };
    }

    // 处于影子模式时：严格拦截写入变更操作
    if (contract.type === ToolOperationType.MUTATING_WRITE) {
      // 记录拦截审计日志并生成模拟沙箱返回值
      const syntheticResponse = this.generateSyntheticResponse(context);

      // 触发写入拦截审计事件
      this.emit('shadowWriteIntercepted', {
        traceId: context.traceId,
        tool: context.toolName,
        args: context.arguments,
        syntheticResponse,
      });

      return { payload: syntheticResponse, intercepted: true };
    }

    // 处于影子模式的只读工具：安全透传执行或访问只读副本
    return { payload: await this.invokeProductionReadOnlyReplica(context), intercepted: false };
  }

  /**
   * 双跑轨迹与决策对账比较算法
   * @param liveRecord 生产环境真实执行记录
   * @param shadowRecord 影子环境候选执行记录
   * @returns 结构化对账核验结果
   */
  public reconcileDualRun(
    traceId: string,
    liveTools: { name: string; args: Record<string, unknown> }[],
    shadowTools: { name: string; args: Record<string, unknown>; intercepted: boolean }[]
  ): DualRunReconciliationRecord {
    const liveNames = liveTools.map(t => t.name);
    const shadowNames = shadowTools.map(t => t.name);

    // 计算工具调用的 Jaccard 重合度系数
    const intersection = liveNames.filter(name => shadowNames.includes(name));
    const union = Array.from(new Set([...liveNames, ...shadowNames]));
    const trajectoryScore = union.length === 0 ? 1.0 : intersection.length / union.length;

    const diffs: string[] = [];
    let criticalMismatch = false;

    // 校验工具执行序列是否严重偏离
    if (trajectoryScore < 0.95) {
      criticalMismatch = true;
      diffs.push(`工具调用序列不匹配: 生产=[${liveNames.join(', ')}], 影子=[${shadowNames.join(', ')}]`);
    }

    // 针对重合的工具，递归对比关键参数对齐度
    for (const commonTool of intersection) {
      const liveInstance = liveTools.find(t => t.name === commonTool);
      const shadowInstance = shadowTools.find(t => t.name === commonTool);
      if (liveInstance && shadowInstance) {
        const argDiff = this.compareArguments(liveInstance.args, shadowInstance.args);
        if (argDiff.hasConflict) {
          criticalMismatch = true;
          diffs.push(`工具 [${commonTool}] 参数分歧: ${argDiff.reason}`);
        }
      }
    }

    const interceptedCount = shadowTools.filter(t => t.intercepted).length;

    const record: DualRunReconciliationRecord = {
      traceId,
      timestamp: new Date().toISOString(),
      liveTrajectory: liveNames,
      shadowTrajectory: shadowNames,
      trajectoryAlignmentScore: trajectoryScore,
      interceptedWriteCount: interceptedCount,
      criticalDiffDetected: criticalMismatch,
      diffDetails: diffs,
    };

    // 派发对账完成事件通知
    this.emit('reconciliationCompleted', record);
    return record;
  }

  /**
   * 递归对比工具参数差异
   */
  private compareArguments(
    liveArgs: Record<string, unknown>,
    shadowArgs: Record<string, unknown>
  ): { hasConflict: boolean; reason: string } {
    for (const key of Object.keys(liveArgs)) {
      if (!(key in shadowArgs)) {
        return { hasConflict: true, reason: `影子参数缺失关键键值: ${key}` };
      }
      if (typeof liveArgs[key] === 'number' || typeof liveArgs[key] === 'string') {
        if (liveArgs[key] !== shadowArgs[key]) {
          return {
            hasConflict: true,
            reason: `字段 [${key}] 值不一致: 生产=${String(liveArgs[key])}, 影子=${String(shadowArgs[key])}`,
          };
        }
      }
    }
    return { hasConflict: false, reason: '一致' };
  }

  /**
   * 模拟生成虚拟沙箱响应载荷
   */
  private generateSyntheticResponse(context: ToolInvocationContext): Record<string, unknown> {
    return {
      status: 'SYNTHETIC_SUCCESS',
      mocked: true,
      virtualId: `mock-id-${context.toolName}-${Date.now()}`,
      message: '影子模式虚拟拦截成功，未修改生产实体状态',
    };
  }

  /**
   * 调用生产主工具（内部模拟桩）
   */
  private async invokeProductionTool(context: ToolInvocationContext): Promise<unknown> {
    return { executed: true, target: context.toolName };
  }

  /**
   * 调用生产只读副本工具（内部模拟桩）
   */
  private async invokeProductionReadOnlyReplica(context: ToolInvocationContext): Promise<unknown> {
    return { readOnlyReplica: true, target: context.toolName };
  }
}