企业级 AI Agent 双向人机协同与动态控制权交接实战：超越单点审批的人机接管、上下文保真移交与干预轨迹回流架构

/**
 * 企业级 AI Agent 双向人机交接与控制权协调引擎
 * 遵循严格上下文保真移交、非侵入式干预与全中文注释规范
 */

// 交接触发原因类型枚举
export enum HandoverTriggerType {
  CONFIDENCE_DECAY = 'CONFIDENCE_DECAY',     // 模型置信度低于阈值
  LOOP_DETECTED = 'LOOP_DETECTED',           // 反思死循环或连续工具调用失败
  POLICY_GUARDRAIL = 'POLICY_GUARDRAIL',     // 触碰高危业务红线或敏感操作
  AMBIGUOUS_INTENT = 'AMBIGUOUS_INTENT',     // 核心实体歧义或必要参数缺失
  USER_REQUESTED = 'USER_REQUESTED',         // 人类专家主动紧急接管
}

// 人机交接状态机枚举
export enum HandoverStatus {
  AUTONOMOUS_RUNNING = 'AUTONOMOUS_RUNNING', // 智能体完全自主运行中
  HANDOVER_PENDING = 'HANDOVER_PENDING',     // 已触发交接，任务挂起等待专家
  HUMAN_INTERVENING = 'HUMAN_INTERVENING',   // 人类专家接管并正在干预中
  RESUMED_TO_AGENT = 'RESUMED_TO_AGENT',     // 干预完毕，已交还智能体续跑
  ABORTED_BY_HUMAN = 'ABORTED_BY_HUMAN',     // 被人类专家彻底驳回并中止
}

// 专家干预动作类型
export enum HumanActionType {
  PATCH_PARAMETERS = 'PATCH_PARAMETERS',     // 原地微调参数
  INJECT_FACT = 'INJECT_FACT',               // 人工代理执行并注入事实
  REDIRECT_BRANCH = 'REDIRECT_BRANCH',       // 规划分支重定向
  REJECT_AND_CANCEL = 'REJECT_AND_CANCEL',   // 拒绝并触发回滚
}

// 结构化决策档案接口（State Dossier）
export interface HandoverDossier {
  handoverId: string;                        // 本次交接全局唯一标识
  agentId: string;                           // 发生交接的智能体标识
  sessionId: string;                         // 业务会话标识
  timestamp: string;                         // 挂起时间戳
  overallGoal: string;                       // 用户原始业务总目标
  currentStepIndex: number;                  // 当前发生阻塞的步骤索引
  triggerType: HandoverTriggerType;          // 触发交接的原因
  triggerRationale: string;                  // 模型自反思或规则引擎的详细说明
  confidenceScore: number;                   // 当前综合置信度得分 (0.0 ~ 1.0)
  committedSideEffects: Array<{              // 已经生效的持久化副作用清单
    step: string;
    tool: string;
    system: string;
    payloadSummary: string;
  }>;
  proposedToolCall: {                        // 智能体原本拟执行但被挂起的动作
    toolName: string;
    proposedArguments: Record<string, any>;
    argumentSchema: Record<string, any>;     // 参数校验规范，指示哪些字段可编辑
  };
  alternativeSuggestions: string[];          // 智能体推演出的备选方案建议
}

// 人类专家提交的干预载荷
export interface HumanInterventionPayload {
  handoverId: string;
  expertUserId: string;
  expertName: string;
  actionType: HumanActionType;
  patchedArguments?: Record<string, any>;    // 专家修正后的工具参数
  injectedFactOutput?: any;                  // 专家手动执行后的权威返回值
  redirectTargetNodeId?: string;             // 专家指定重定向的目标节点
  interventionNotes: string;                 // 专家干预理由与备注（用于数据沉淀）
}

/**
 * 双向人机协作协调器核心类
 */
export class AgentHandoverCoordinator {
  private status: HandoverStatus = HandoverStatus.AUTONOMOUS_RUNNING;
  private currentDossier: HandoverDossier | null = null;
  private resumeCallback: ((payload: HumanInterventionPayload) => Promise<void>) | null = null;

  /**
   * 智能体触发主动挂起并移交决策权
   * @param dossier 封装好的高解释性决策档案
   * @param onResume 人工干预完成后的异步回调通知函数
   */
  public async suspendForHandover(
    dossier: HandoverDossier,
    onResume: (payload: HumanInterventionPayload) => Promise<void>
  ): Promise<void> {
    this.status = HandoverStatus.HANDOVER_PENDING;
    this.currentDossier = dossier;
    this.resumeCallback = onResume;

    console.log('[人机交接] 智能体已挂起任务: ' + dossier.sessionId + ' 原因: ' + dossier.triggerType);
  }

  /**
   * 接收人类专家的干预指令并恢复智能体流转
   * @param intervention 人类专家提交的干预载荷
   */
  public async applyHumanIntervention(intervention: HumanInterventionPayload): Promise<{ success: boolean; message: string }> {
    if (this.status !== HandoverStatus.HANDOVER_PENDING) {
      return { success: false, message: '当前任务未处于待交接状态' };
    }

    if (!this.currentDossier || this.currentDossier.handoverId !== intervention.handoverId) {
      return { success: false, message: '交接标识符不匹配或档案已过期' };
    }

    this.status = HandoverStatus.HUMAN_INTERVENING;

    try {
      switch (intervention.actionType) {
        case HumanActionType.PATCH_PARAMETERS:
          console.log('[人机交接] 专家修正了工具参数: ' + intervention.expertName);
          break;
        case HumanActionType.INJECT_FACT:
          console.log('[人机交接] 专家手工注入了执行事实数据: ' + intervention.expertName);
          break;
        case HumanActionType.REDIRECT_BRANCH:
          console.log('[人机交接] 专家重定向任务分支至: ' + (intervention.redirectTargetNodeId || '未知分支'));
          break;
        case HumanActionType.REJECT_AND_CANCEL:
          this.status = HandoverStatus.ABORTED_BY_HUMAN;
          console.log('[人机交接] 专家驳回任务，启动补偿事务回滚');
          return { success: true, message: '任务已被人类专家中止并安全回滚' };
      }

      if (this.resumeCallback) {
        await this.resumeCallback(intervention);
      }

      this.status = HandoverStatus.RESUMED_TO_AGENT;
      this.currentDossier = null;
      this.resumeCallback = null;

      return { success: true, message: '干预指令已应用，智能体已恢复自主流转' };
    } catch (err: any) {
      return { success: false, message: '恢复智能体执行失败: ' + (err.message || '未知错误') };
    }
  }

  /**
   * 获取当前交接状态
   */
  public getStatus(): HandoverStatus {
    return this.status;
  }

  /**
   * 获取当前等待中的决策档案
   */
  public getCurrentDossier(): HandoverDossier | null {
    return this.currentDossier;
  }
}