企业级多智能体“合同网协议”（Contract Net Protocol, CNP）与去中心化任务竞标实战：破解中心化编排瓶颈、多维度竞标打分与动态契约状态机

// contract-net-engine.ts
// 企业级多智能体合同网协议（CNP）核心调度引擎实现
// 遵循全中文注释规范与生产级防御性编程标准

import { EventEmitter } from 'node:events';

/**
 * 任务招标书（Call for Proposals, CFP）契约结构
 */
export interface TaskCFP {
  // 任务全局唯一标识符
  taskId: string;
  // 业务类型标签（如 'MES_RESCHEDULE', 'ERP_AUDIT'）
  taskType: string;
  // 自然语言意图说明
  intent: string;
  // 输入业务数据载荷
  payload: Record;
  // 期望的输出 JSON Schema 约束定义
  outputSchema: Record;
  // 必须具备的工具或能力标签清单
  requiredCapabilities: string[];
  // 竞标收集截止时间戳（Unix Epoch ms）
  bidDeadline: number;
  // 最大允许执行耗时 SLA（毫秒）
  slaTimeoutMs: number;
  // 权重配置偏好（可选）
  customWeights?: UtilityWeights;
}

/**
 * 承包方投标方案（Bidding Proposal）结构
 */
export interface AgentBid {
  // 投标唯一 ID
  bidId: string;
  // 关联的任务 ID
  taskId: string;
  // 投标智能体唯一标识符
  agentId: string;
  // 智能体声明的所属领域与模型规格
  agentModel: string;
  // 领域置信度自评得分（0.0 ~ 1.0）
  domainConfidence: number;
  // 预估执行耗时（毫秒）
  estimatedLatencyMs: number;
  // 预估消耗的 Token 总量
  estimatedTokens: number;
  // 当前私有化 GPU 显存负载率（0.0 ~ 1.0）
  gpuVramLoad: number;
  // 当前等待队列深度
  queueDepth: number;
  // 历史综合履约声誉得分（0.0 ~ 1.0）
  reputationScore: number;
  // 投标生成时间戳
  timestamp: number;
}

/**
 * 多目标效用评估权重配置
 */
export interface UtilityWeights {
  // 领域置信度权重
  confidence: number;
  // 执行延迟权重
  latency: number;
  // Token 成本权重
  tokenCost: number;
  // 显存与负载平滑权重
  resourceLoad: number;
  // 历史声誉权重
  reputation: number;
}

/**
 * 默认多目标效用权重基线（总和为 1.0）
 */
export const DEFAULT_UTILITY_WEIGHTS: UtilityWeights = {
  confidence: 0.35,
  latency: 0.25,
  tokenCost: 0.15,
  resourceLoad: 0.15,
  reputation: 0.10,
};

/**
 * 契约生命周期状态枚举
 */
export enum ContractState {
  // 初始空闲状态
  IDLE = 'IDLE',
  // 招标书已广播，正在收集竞标
  COLLECTING_BIDS = 'COLLECTING_BIDS',
  // 正在评估竞标方案
  EVALUATING = 'EVALUATING',
  // 授标已签署，等待执行
  AWARDED = 'AWARDED',
  // 正在执行中
  EXECUTING = 'EXECUTING',
  // 成功履约完成
  COMPLETED = 'COMPLETED',
  // 执行失败或校验违约
  FAILED = 'FAILED',
  // 流标（无有效竞标）
  DROPPED = 'DROPPED',
}

/**
 * 契约实例模型
 */
export interface ActiveContract {
  contractId: string;
  cfp: TaskCFP;
  state: ContractState;
  winningBid?: AgentBid;
  allBids: AgentBid[];
  awardedAt?: number;
  completedAt?: number;
  executionResult?: any;
  failureReason?: string;
}

/**
 * 多目标效用计算器
 */
export class UtilityCalculator {
  /**
   * 计算单一投标的综合效用得分
   * @param bid 智能体竞标方案
   * @param cfp 原始招标书
   * @param weights 权重配置
   */
  public static calculateScore(
    bid: AgentBid,
    cfp: TaskCFP,
    weights: UtilityWeights = DEFAULT_UTILITY_WEIGHTS
  ): number {
    // 1. 置信度评分（越接近 1.0 越好）
    const confidenceScore = Math.max(0, Math.min(1, bid.domainConfidence));

    // 2. 延迟归一化评分（以 SLA 超时时间为基准，耗时越短得分越高）
    const maxLatency = cfp.slaTimeoutMs || 10000;
    const latencyScore = Math.max(0, 1 - (bid.estimatedLatencyMs / maxLatency));

    // 3. Token 开销评分（以 8000 Token 为标准上限进行线性惩罚）
    const maxTokens = 8000;
    const tokenScore = Math.max(0, 1 - (bid.estimatedTokens / maxTokens));

    // 4. 节点物理资源平滑评分（显存与队列越低越好）
    const loadScore = Math.max(0, 1 - (bid.gpuVramLoad * 0.7 + (bid.queueDepth / 10) * 0.3));

    // 5. 历史履约声誉评分
    const reputationScore = Math.max(0, Math.min(1, bid.reputationScore));

    // 6. 加权多目标线性融合
    const totalScore =
      weights.confidence * confidenceScore +
      weights.latency * latencyScore +
      weights.tokenCost * tokenScore +
      weights.resourceLoad * loadScore +
      weights.reputation * reputationScore;

    return Number(totalScore.toFixed(4));
  }
}

/**
 * 生产级多智能体合同网调度引擎
 */
export class ContractNetEngine extends EventEmitter {
  // 活跃契约注册表
  private activeContracts: Map = new Map();
  // 智能体声誉状态库（维护长期履约记录）
  private reputationRegistry: Map = new Map();

  constructor() {
    super();
  }

  /**
   * 发起方发起新任务招标（CFP）
   * @param cfp 任务招标书参数
   */
  public async publishCFP(cfp: TaskCFP): Promise {
    const contract: ActiveContract = {
      contractId: `contract-${Date.now()}-${Math.random().toString(36).substring(2, 7)}`,
      cfp,
      state: ContractState.COLLECTING_BIDS,
      allBids: [],
    };

    this.activeContracts.set(contract.contractId, contract);

    // 广播招标事件，通知所有在线且具备能力的智能体
    this.emit('cfp:broadcast', { contractId: contract.contractId, cfp });

    // 设定招标收集截止定时器
    const waitTime = Math.max(100, cfp.bidDeadline - Date.now());
    setTimeout(() => {
      this.closeBiddingAndEvaluate(contract.contractId).catch((err) => {
        console.error(`[CNP 错误] 竞标结算异常: ${err.message}`);
      });
    }, waitTime);

    return contract;
  }

  /**
   * 承包方 Agent 提交竞标方案
   * @param contractId 关联的契约 ID
   * @param bid 竞标详情
   */
  public submitBid(contractId: string, bid: AgentBid): boolean {
    const contract = this.activeContracts.get(contractId);
    if (!contract) {
      console.warn(`[CNP 警告] 投标被拒：未找到对应契约 ${contractId}`);
      return false;
    }

    if (contract.state !== ContractState.COLLECTING_BIDS) {
      console.warn(`[CNP 警告] 投标被拒：当前契约不在收集竞标阶段（状态: ${contract.state}）`);
      return false;
    }

    if (Date.now() > contract.cfp.bidDeadline) {
      console.warn(`[CNP 警告] 投标被拒：已超出竞标截止时间`);
      return false;
    }

    // 自动挂载历史声誉分（如无记录则默认为 0.85）
    const storedRep = this.reputationRegistry.get(bid.agentId) ?? 0.85;
    bid.reputationScore = storedRep;

    contract.allBids.push(bid);
    this.emit('bid:received', { contractId, bid });
    return true;
  }

  /**
   * 截止时间到期，关闭竞标并执行多目标决策授标
   * @param contractId 契约 ID
   */
  private async closeBiddingAndEvaluate(contractId: string): Promise {
    const contract = this.activeContracts.get(contractId);
    if (!contract || contract.state !== ContractState.COLLECTING_BIDS) {
      return;
    }

    contract.state = ContractState.EVALUATING;

    // 检查是否存在有效投标
    if (contract.allBids.length === 0) {
      contract.state = ContractState.DROPPED;
      contract.failureReason = '流标：截止时间内未收到任何智能体有效投标';
      this.emit('contract:dropped', { contractId, reason: contract.failureReason });
      return;
    }

    // 对所有竞标方案进行效用打分与排序
    const weights = contract.cfp.customWeights || DEFAULT_UTILITY_WEIGHTS;
    const scoredBids = contract.allBids.map((b) => ({
      bid: b,
      score: UtilityCalculator.calculateScore(b, contract.cfp, weights),
    }));

    // 按得分从高到低排序
    scoredBids.sort((a, b) => b.score - a.score);
    const bestCandidate = scoredBids[0];

    // 设定合格基准线（如 0.40 分），防止低质滥造
    const MIN_ACCEPTABLE_SCORE = 0.40;
    if (bestCandidate.score < MIN_ACCEPTABLE_SCORE) {
      contract.state = ContractState.DROPPED;
      contract.failureReason = `流标：最佳竞标方案得分 (${bestCandidate.score}) 低于系统基准线 (${MIN_ACCEPTABLE_SCORE})`;
      this.emit('contract:dropped', { contractId, reason: contract.failureReason });
      return;
    }

    // 正式签署授标
    contract.state = ContractState.AWARDED;
    contract.winningBid = bestCandidate.bid;
    contract.awardedAt = Date.now();

    // 广播授标与拒绝结果
    this.emit('contract:awarded', {
      contractId,
      winner: bestCandidate.bid,
      winningScore: bestCandidate.score,
    });

    // 通知落选 Agent 释放预锁定的临时资源
    const rejectedBids = scoredBids.slice(1).map((s) => s.bid);
    this.emit('contract:rejected', { contractId, rejectedBids });
  }

  /**
   * 中标 Agent 提交最终执行成果并完成验收结算
   * @param contractId 契约 ID
   * @param agentId 提交的智能体 ID
   * @param result 执行结果产物
   * @param actualLatencyMs 实际执行耗时
   */
  public reportExecutionResult(
    contractId: string,
    agentId: string,
    result: any,
    actualLatencyMs: number
  ): void {
    const contract = this.activeContracts.get(contractId);
    if (!contract || contract.state !== ContractState.AWARDED) {
      throw new Error(`无法提交成果：契约不存在或未处在已授标状态`);
    }

    if (contract.winningBid?.agentId !== agentId) {
      throw new Error(`越权提交：当前智能体非本契约中标方`);
    }

    contract.state = ContractState.EXECUTING;

    // 检查是否超出 SLA 超时限制
    const isSlaViolated = actualLatencyMs > contract.cfp.slaTimeoutMs;
    // 简化的契约产物非空校验（生产环境结合 ajv 做 JSON Schema 强校验）
    const isSchemaValid = result && typeof result === 'object';

    if (!isSlaViolated && isSchemaValid) {
      contract.state = ContractState.COMPLETED;
      contract.completedAt = Date.now();
      contract.executionResult = result;

      // 履约成功：奖励声誉分（上限 1.0）
      const currentRep = this.reputationRegistry.get(agentId) ?? 0.85;
      this.reputationRegistry.set(agentId, Math.min(1.0, currentRep + 0.02));

      this.emit('contract:completed', { contractId, result, actualLatencyMs });
    } else {
      contract.state = ContractState.FAILED;
      contract.failureReason = isSlaViolated
        ? `违约：实际耗时 (${actualLatencyMs}ms) 超出承诺 SLA (${contract.cfp.slaTimeoutMs}ms)`
        : '违约：输出产物不符合 JSON Schema 契约规范';

      // 履约违约：惩罚扣除声誉分并施加反冲衰减
      const currentRep = this.reputationRegistry.get(agentId) ?? 0.85;
      this.reputationRegistry.set(agentId, Math.max(0.1, currentRep - 0.15));

      this.emit('contract:failed', {
        contractId,
        reason: contract.failureReason,
        slashedReputation: this.reputationRegistry.get(agentId),
      });
    }
  }

  /**
   * 获取指定智能体的实时声誉值
   * @param agentId 智能体标识
   */
  public getAgentReputation(agentId: string): number {
    return this.reputationRegistry.get(agentId) ?? 0.85;
  }
}

合同网协议（CNP）企业级生产部署自查清单：

• 严禁无上限广播风暴：在大型私有化内网中，CFP 广播必须基于能力标签（Capability Tags）进行前置路由过滤，严禁向无关的数百个 Agent 全量广播无界报文；
• 投标倒计时设置黄金区间：bidDeadline 应设置为本地网络 P99 延迟的 2~3 倍（通常为 150ms ~ 300ms）。过短易导致优质竞标丢失，过长则拉大端到端响应时间；
• 真实上报物理水位指标：各 Agent 节点的显存率与队列深度必须读取底层真实探测器（如 NVML 显存探针与系统进程队列），严禁通过 LLM 意图自行脑补硬件参数；
• 严格实行契约输出 JSON Schema 校验：中标并不等于信任，承包方提交的结果必须经由发起方校验网关严格核对 Schema，不合格者坚决触发声誉扣减与备用节点切换；
• 冷启动声誉平滑处理：新接入集群的微服务 Agent 初始声誉分应赋予合理的默认中值（如 0.80），并限制其在试用期内承担最高风险等级核心工单的权限，建立平滑积累机制。