企业级 AI Agent“Token 预算治理与自适应成本控制”（Token Budget Allocation & Adaptive Cost Governance）架构实战：破解长链路死循环失控、多租户配额超限与上下文截断难题

Fingerprint = SHA256(tool_name + ":" + JSON.stringify(sortKeys(arguments)))

阶梯水位降级运行状态机：

• 水位 1：正常执行区（消耗 < 60%）
  全量保留多轮历史工具调用的原始报文、完整的推理轨迹及高精度 Prompt 模板。
• 水位 2：上下文动态剪枝区（60% ≤ 消耗 < 80%）
  对历史工具返回的大型数据体（如 ERP 返回的几千行 JSON 明细）进行字段白名单提取与摘要剪枝（Context Pruning），仅保留主键、状态码及核心统计指标，释放 50% 以上的无用历史 Token。
• 水位 3：语义压缩与推理退行区（80% ≤ 消耗 < 95%）
  系统自动调用轻量级模型对前序历史轮次进行增量会话快照压缩（Working Memory Summarization）；同时动态将大模型的温度值从 0.7 调降至 0.1，抑制自由发挥；单步输出上限收缩至 512 Token。
• 水位 4：耗尽保护与优雅收尾区（消耗 ≥ 95%）
  剥夺所有外部工具调用权限，向模型发送终结态指令（Terminal Directive），强制模型基于当前所有已获取的事实，在保留的最后 5% 安全边际内生成完整的结论总结或结构化待办清单，确保输出合法的 JSON 闭合体或完整文本。

import { createHash } from 'node:crypto';

/**
 * 降级水位枚举
 */
export enum BudgetDegradationTier {
  NORMAL = 'NORMAL',           // 正常运行区 (< 60%)
  PRUNING = 'PRUNING',         // 动态剪枝区 (60% - 80%)
  COMPRESSION = 'COMPRESSION', // 语义压缩区 (80% - 95%)
  TERMINAL = 'TERMINAL',       // 终结收尾区 (>= 95%)
}

/**
 * 单步执行记录接口
 */
export interface StepExecutionRecord {
  stepIndex: number;           // 当前步数序号
  toolName?: string;           // 调用的工具名称
  argumentsPayload?: Record; // 工具入参载荷
  thoughtSnippet?: string;     // 思考链关键文本
  inputTokens: number;         // 本步输入 Token
  outputTokens: number;        // 本步输出 Token
  timestamp: number;           // 时间戳
}

/**
 * 租户配额配置
 */
export interface TenantBudgetConfig {
  tenantId: string;            // 租户唯一标识
  department: string;          // 所属业务部门
  priority: 'HIGH' | 'MEDIUM' | 'LOW'; // 优先级
  slidingWindowMinutes: number;// 滑动窗口时长（分钟）
  maxTokensPerWindow: number;  // 窗口内最大允许 Token 额度
}

/**
 * 任务级预算管理选项
 */
export interface TaskBudgetOptions {
  taskId: string;              // 任务唯一标识
  tenantConfig: TenantBudgetConfig; // 归属租户配置
  maxTaskTokens: number;       // 任务最大总 Token 预算（如 30,000）
  maxSteps: number;            // 任务最大执行步数（如 12 步）
  safetyBufferRatio?: number;  // 终结安全边际比例（默认 0.05 即 5%）
  loopThreshold?: number;      // 死循环判定阈值（默认 3 次重复）
}

/**
 * 生产级企业智能体 Token 预算治理控制器
 */
export class TokenBudgetGovernor {
  private readonly taskId: string;
  private readonly tenantConfig: TenantBudgetConfig;
  private readonly maxTaskTokens: number;
  private readonly maxSteps: number;
  private readonly safetyBufferRatio: number;
  private readonly loopThreshold: number;

  private totalInputTokensUsed = 0;
  private totalOutputTokensUsed = 0;
  private stepHistory: StepExecutionRecord[] = [];
  private actionFingerprintHistory: string[] = [];
  private circuitBreakerTripped = false;

  constructor(options: TaskBudgetOptions) {
    this.taskId = options.taskId;
    this.tenantConfig = options.tenantConfig;
    this.maxTaskTokens = options.maxTaskTokens;
    this.maxSteps = options.maxSteps;
    this.safetyBufferRatio = options.safetyBufferRatio ?? 0.05;
    this.loopThreshold = options.loopThreshold ?? 3;
  }

  /**
   * 生成工具调用规范化指纹哈希（用于检测原地死循环）
   */
  private generateFingerprint(toolName: string, args: Record): string {
    // 递归对入参键进行字典序排序，消除 JSON 字段无序导致的哈希抖动
    const sortObjectKeys = (obj: unknown): unknown => {
      if (typeof obj !== 'object' || obj === null) return obj;
      if (Array.isArray(obj)) return obj.map(sortObjectKeys);
      return Object.keys(obj as Record)
        .sort()
        .reduce((acc, key) => {
          acc[key] = sortObjectKeys((obj as Record)[key]);
          return acc;
        }, {} as Record);
    };

    const serialized = `${toolName}:${JSON.stringify(sortObjectKeys(args))}`;
    return createHash('sha256').update(serialized).digest('hex').slice(0, 16);
  }

  /**
   * 检查是否陷入重复动作死循环或 A-B 振荡循环
   */
  public detectActionLoop(currentTool: string, currentArgs: Record): {
    isLoop: boolean;
    pattern?: 'IDENTICAL_REPEAT' | 'OSCILLATION';
    repeatCount: number;
  } {
    const currentFingerprint = this.generateFingerprint(currentTool, currentArgs);
    const window = [...this.actionFingerprintHistory, currentFingerprint];

    // 1. 检查连续相同指纹重试
    let identicalCount = 0;
    for (let i = window.length - 1; i >= 0; i--) {
      if (window[i] === currentFingerprint) {
        identicalCount++;
      } else {
        break;
      }
    }

    if (identicalCount >= this.loopThreshold) {
      return { isLoop: true, pattern: 'IDENTICAL_REPEAT', repeatCount: identicalCount };
    }

    // 2. 检查 A-B-A-B 周期性振荡循环 (长度至少为 4)
    if (window.length >= 4) {
      const len = window.length;
      const isOscillating =
        window[len - 1] === window[len - 3] &&
        window[len - 2] === window[len - 4] &&
        window[len - 1] !== window[len - 2];
      if (isOscillating) {
        return { isLoop: true, pattern: 'OSCILLATION', repeatCount: 2 };
      }
    }

    return { isLoop: false, repeatCount: identicalCount };
  }

  /**
   * 记录单步消耗并完成状态机转移
   */
  public recordStep(record: StepExecutionRecord): void {
    this.stepHistory.push(record);
    this.totalInputTokensUsed += record.inputTokens;
    this.totalOutputTokensUsed += record.outputTokens;

    if (record.toolName && record.argumentsPayload) {
      const fp = this.generateFingerprint(record.toolName, record.argumentsPayload);
      this.actionFingerprintHistory.push(fp);
    }
  }

  /**
   * 获取当前任务总体消耗量
   */
  public getTotalTokensUsed(): number {
    return this.totalInputTokensUsed + this.totalOutputTokensUsed;
  }

  /**
   * 计算当前预算水位与对应的自适应降级档位
   */
  public getDegradationTier(): BudgetDegradationTier {
    const currentUsageRatio = this.getTotalTokensUsed() / this.maxTaskTokens;
    const currentStep = this.stepHistory.length;

    // 步数或消耗超标进入终结收尾区
    if (currentUsageRatio >= (1 - this.safetyBufferRatio) || currentStep >= this.maxSteps) {
      return BudgetDegradationTier.TERMINAL;
    }
    if (currentUsageRatio >= 0.8) {
      return BudgetDegradationTier.COMPRESSION;
    }
    if (currentUsageRatio >= 0.6) {
      return BudgetDegradationTier.PRUNING;
    }
    return BudgetDegradationTier.NORMAL;
  }

  /**
   * 为下一步推理动态计算允许的单步最大生成 Tokens 与温度策略
   */
  public getNextStepInferenceConstraints(): {
    maxTokens: number;
    recommendedTemperature: number;
    allowToolCalls: boolean;
    tier: BudgetDegradationTier;
    systemInjectionPrompt?: string;
  } {
    const tier = this.getDegradationTier();
    const remainingTaskTokens = Math.max(0, this.maxTaskTokens - this.getTotalTokensUsed());

    switch (tier) {
      case BudgetDegradationTier.NORMAL:
        return {
          maxTokens: Math.min(2048, remainingTaskTokens),
          recommendedTemperature: 0.7,
          allowToolCalls: true,
          tier,
        };

      case BudgetDegradationTier.PRUNING:
        return {
          maxTokens: Math.min(1024, remainingTaskTokens),
          recommendedTemperature: 0.5,
          allowToolCalls: true,
          tier,
          systemInjectionPrompt: '【系统运行护栏】当前任务 Token 预算已消耗 60% 以上，请在调用工具时精简入参，聚焦核心数据。',
        };

      case BudgetDegradationTier.COMPRESSION:
        return {
          maxTokens: Math.min(512, remainingTaskTokens),
          recommendedTemperature: 0.2,
          allowToolCalls: true,
          tier,
          systemInjectionPrompt: '【系统运行护栏】当前任务预算消耗已达 80%，即将触碰上限。请立刻压缩思考过程，准备收敛并输出最终业务结果。',
        };

      case BudgetDegradationTier.TERMINAL:
      default:
        return {
          // 预留安全边际用于输出完整的收尾 JSON 或结论
          maxTokens: Math.min(512, Math.max(256, Math.floor(this.maxTaskTokens * this.safetyBufferRatio))),
          recommendedTemperature: 0.0,
          allowToolCalls: false, // 坚决切断工具调用权限
          tier,
          systemInjectionPrompt: '【硬性终止指令】任务总 Token 预算或步数上限已用尽！请勿再发起任何工具调用，基于现有全部信息直接生成完整结论总结或错误诊断报告。',
        };
    }
  }

  /**
   * 触发死循环熔断并记录状态
   */
  public tripCircuitBreaker(): void {
    this.circuitBreakerTripped = true;
  }

  /**
   * 导出结构化成本归因审计记录
   */
  public exportAuditRecord(): {
    taskId: string;
    tenantId: string;
    department: string;
    totalSteps: number;
    totalInputTokens: number;
    totalOutputTokens: number;
    totalTokens: number;
    budgetUtilization: string;
    finalTier: BudgetDegradationTier;
    circuitBreakerTripped: boolean;
  } {
    const total = this.getTotalTokensUsed();
    return {
      taskId: this.taskId,
      tenantId: this.tenantConfig.tenantId,
      department: this.tenantConfig.department,
      totalSteps: this.stepHistory.length,
      totalInputTokens: this.totalInputTokensUsed,
      totalOutputTokens: this.totalOutputTokensUsed,
      totalTokens: total,
      budgetUtilization: `${((total / this.maxTaskTokens) * 100).toFixed(2)}%`,
      finalTier: this.getDegradationTier(),
      circuitBreakerTripped: this.circuitBreakerTripped,
    };
  }
}