企业级 AI Agent“主动澄清与混合主动权交互”（Active Clarification & Mixed-Initiative Interaction）架构实战：破解模糊意图幻觉臆断、关键槽位缺失与破坏性误调用

/**
 * 企业级 AI Agent 主动澄清与混合主动权调度引擎核心实现
 * 覆盖：槽位验证、歧义置信度分析、决策策略、交互卡片生成与上下文缝合
 */

// 业务操作风险等级定义
export enum ActionRiskTier {
  TIER0_READONLY = 0,   // 纯只读，容错率高，回滚成本为 0
  TIER1_SAFE_WRITE = 1, // 可逆轻量写，草稿/备忘
  TIER2_WORKFLOW = 2,   // 业务状态扭转，需走驳回流程
  TIER3_DESTRUCTIVE = 3 // 财务划扣/库存核销/合同作废，不可逆高危
}

// 槽位定义接口
export interface SlotDefinition {
  name: string;
  label: string;
  required: boolean;
  type: 'string' | 'number' | 'enum' | 'date';
  options?: string[]; // 枚举候选项
  description: string;
  defaultValue?: any;
}

// 实体匹配候选结构
export interface EntityCandidate {
  id: string;
  name: string;
  score: number; // 匹配置信度 0~1
  attributes: Record<string, any>;
}

// 澄清卡片类型枚举
export enum ClarificationCardType {
  DISAMBIGUATION = 'DISAMBIGUATION', // 歧义多选一
  SLOT_FILLING = 'SLOT_FILLING',     // 缺失字段微表单
  CONFIRMATION = 'CONFIRMATION'      // 高危操作最终确认
}

// 澄清卡片结构体
export interface ClarificationCard {
  cardId: string;
  type: ClarificationCardType;
  title: string;
  description: string;
  targetField: string;
  candidates?: EntityCandidate[];
  missingSlots?: SlotDefinition[];
  riskTier: ActionRiskTier;
  timeoutSeconds: number;
}

// 执行图中断检查点状态
export interface ExecutionCheckpoint {
  checkpointId: string;
  sessionId: string;
  toolName: string;
  riskTier: ActionRiskTier;
  validatedSlots: Record<string, any>;
  clarificationCard: ClarificationCard;
  createdAt: number;
  status: 'PENDING' | 'RESOLVED' | 'EXPIRED';
}

/**
 * 主动澄清策略与调度中枢引擎
 */
export class ClarificationPolicyEngine {
  private checkpoints: Map<string, ExecutionCheckpoint> = new Map();

  /**
   * 计算候选实体之间的歧义度与置信度差值
   * @param candidates 召回的实体列表（按得分降序排序）
   * @returns 是否存在严重混淆与推荐采取的动作
   */
  public evaluateAmbiguity(candidates: EntityCandidate[]): {
    isAmbiguous: boolean;
    bestCandidate?: EntityCandidate;
    confidenceMargin: number;
  } {
    if (!candidates || candidates.length === 0) {
      return { isAmbiguous: false, confidenceMargin: 0 };
    }

    if (candidates.length === 1) {
      return {
        isAmbiguous: candidates[0].score < 0.70,
        bestCandidate: candidates[0].score >= 0.70 ? candidates[0] : undefined,
        confidenceMargin: candidates[0].score
      };
    }

    // 计算 Top-1 与 Top-2 置信度差
    const top1 = candidates[0];
    const top2 = candidates[1];
    const margin = top1.score - top2.score;

    // 若 Top-1 得分足够高且与 Top-2 差距显著，判定为无歧义
    if (top1.score >= 0.88 && margin >= 0.30) {
      return { isAmbiguous: false, bestCandidate: top1, confidenceMargin: margin };
    }

    // 否则判定存在严重实体冲突，需要澄清
    return { isAmbiguous: true, bestCandidate: undefined, confidenceMargin: margin };
  }

  /**
   * 评估槽位完整度与风险，生成自适应决策
   */
  public evaluateExecutionReadiness(
    toolName: string,
    riskTier: ActionRiskTier,
    slotDefs: SlotDefinition[],
    providedSlots: Record<string, any>,
    ambiguousCandidatesMap?: Record<string, EntityCandidate[]>
  ): {
    action: 'PROCEED' | 'CLARIFY';
    clarificationCard?: ClarificationCard;
  } {
    const missingRequiredSlots: SlotDefinition[] = [];
    const ambiguousFields: { field: string; candidates: EntityCandidate[] }[] = [];

    // 1. 检查歧义实体
    if (ambiguousCandidatesMap) {
      for (const [field, candidates] of Object.entries(ambiguousCandidatesMap)) {
        const ambResult = this.evaluateAmbiguity(candidates);
        if (ambResult.isAmbiguous) {
          ambiguousFields.push({ field, candidates });
        } else if (ambResult.bestCandidate && !providedSlots[field]) {
          providedSlots[field] = ambResult.bestCandidate.id;
        }
      }
    }

    // 2. 检查必填槽位
    for (const def of slotDefs) {
      const val = providedSlots[def.name];
      const isMissing = val === undefined || val === null || val === '';
      if (def.required && isMissing) {
        missingRequiredSlots.push(def);
      }
    }

    // 3. 制定执行策略
    // 优先解决歧义实体（因为实体确定后可能衍生出默认槽位）
    if (ambiguousFields.length > 0) {
      const target = ambiguousFields[0];
      return {
        action: 'CLARIFY',
        clarificationCard: {
          cardId: `card-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
          type: ClarificationCardType.DISAMBIGUATION,
          title: `请选择明确的${target.field}`,
          description: `系统检索到多个相似对象，请点击确认您要操作的具体项：`,
          targetField: target.field,
          candidates: target.candidates,
          riskTier,
          timeoutSeconds: 300
        }
      };
    }

    // 若存在缺失必填槽位
    if (missingRequiredSlots.length > 0) {
      // 若为纯只读操作且存在默认值，可走推测执行
      if (riskTier === ActionRiskTier.TIER0_READONLY) {
        let allHaveDefaults = true;
        for (const slot of missingRequiredSlots) {
          if (slot.defaultValue !== undefined) {
            providedSlots[slot.name] = slot.defaultValue;
          } else {
            allHaveDefaults = false;
          }
        }
        if (allHaveDefaults) {
          return { action: 'PROCEED' };
        }
      }

      // 高危写操作必须阻断并生成槽位补填表单
      return {
        action: 'CLARIFY',
        clarificationCard: {
          cardId: `card-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
          type: ClarificationCardType.SLOT_FILLING,
          title: `缺少关键操作参数`,
          description: `调用【${toolName}】需要补充以下信息以保证业务执行安全：`,
          targetField: missingRequiredSlots.map(s => s.name).join(','),
          missingSlots: missingRequiredSlots,
          riskTier,
          timeoutSeconds: 300
        }
      };
    }

    // 高危 Tier 3 操作即使参数齐全，亦须弹出最终防呆确认卡片
    if (riskTier === ActionRiskTier.TIER3_DESTRUCTIVE) {
      return {
        action: 'CLARIFY',
        clarificationCard: {
          cardId: `card-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
          type: ClarificationCardType.CONFIRMATION,
          title: `高危操作确认`,
          description: `此操作将直接影响企业账目/库存状态，不可物理撤销，请核对参数后确认：`,
          targetField: '_global_confirmation',
          riskTier,
          timeoutSeconds: 180
        }
      };
    }

    return { action: 'PROCEED' };
  }

  /**
   * 挂起工作流并持久化不可变检查点
   */
  public suspendWorkflow(
    sessionId: string,
    toolName: string,
    riskTier: ActionRiskTier,
    validatedSlots: Record<string, any>,
    card: ClarificationCard
  ): ExecutionCheckpoint {
    const checkpointId = `ckpt-${sessionId}-${Date.now()}`;
    const checkpoint: ExecutionCheckpoint = {
      checkpointId,
      sessionId,
      toolName,
      riskTier,
      validatedSlots: { ...validatedSlots },
      clarificationCard: card,
      createdAt: Date.now(),
      status: 'PENDING'
    };
    this.checkpoints.set(checkpointId, checkpoint);
    return checkpoint;
  }

  /**
   * 上下文无缝缝合（Context Splicing）与原地恢复
   * @param checkpointId 挂起的检查点 ID
   * @param userInput 用户在卡片上提交的结构化数据
   */
  public resumeWithSplicing(
    checkpointId: string,
    userInput: Record<string, any>
  ): {
    success: boolean;
    toolName: string;
    finalExecutionPayload: Record<string, any>;
    message: string;
  } {
    const ckpt = this.checkpoints.get(checkpointId);
    if (!ckpt) {
      throw new Error(`未找到指定检查点: ${checkpointId}`);
    }
    if (ckpt.status !== 'PENDING') {
      throw new Error(`检查点状态已失效: ${ckpt.status}`);
    }

    // 检查超时
    const elapsedSeconds = (Date.now() - ckpt.createdAt) / 1000;
    if (elapsedSeconds > ckpt.clarificationCard.timeoutSeconds) {
      ckpt.status = 'EXPIRED';
      throw new Error('澄清卡片已超时过期，请重新发起指令');
    }

    // 执行状态浅合并打补丁（Context Splicing）
    const mergedSlots = {
      ...ckpt.validatedSlots,
      ...userInput
    };

    // 标记检查点完成
    ckpt.status = 'RESOLVED';

    return {
      success: true,
      toolName: ckpt.toolName,
      finalExecutionPayload: mergedSlots,
      message: `成功缝合澄清上下文，已恢复【${ckpt.toolName}】原地执行`
    };
  }
}