《互联网产品的 AI 架构·多能力编排与任务闭环》8.3 编排经济性复核

// file: src/orch/budget-economics.ts
// tier: L2
// verify: node --test test/orch/budget.test.ts

import { AiError } from "../core/errors.ts";

/** 一次经济性复核的输入；成本用整数微元，比例用 0–1。 */
export interface EconomicsInput {
  name: string;
  /** 编排后的期望成本，含重试与失败浪费。 */
  orchestratedCostMicros: number;
  successProbability: number;
  /** 独立调用（或旧方案）每次成功交付的成本，用作对照。 */
  standaloneCostPerSuccessMicros: number;
  /** 复核窗口内按 token 加权的共享前缀复用率。 */
  reuseRatio: number;
  sharedContextTokens: number;
  handoffTokens: number;
  /** 缓存输入占全价的比例；0.1 表示 90% 折扣。 */
  cachedInputPriceRatio: number;
  /** 每个节点的单次失败率，不含重试。 */
  stepFailureRates: readonly number[];
  retriesPerStep: number;
  /** 整链目标成功率，用于反推单步失败预算。 */
  targetSuccess: number;
  /** 编排相对独立调用的质量提升，百分点；没有提升填 0。 */
  qualityLiftPct: number;
  maxCostPerSuccessMicros?: number;
}

export interface EconomicsCheck { name: string; passed: boolean; detail: string }

export interface EconomicsReview {
  name: string;
  costPerSuccessMicros: number;
  netCostMicros: number;
  netCostPct: number;
  breakEvenReuseRatio: number;
  reuseMarginPct: number;
  maxStepFailureRate: number;
  worstStepFailureRate: number;
  failureHeadroomPct: number;
  costPremiumPct: number;
  qualityJustified: boolean;
  checks: EconomicsCheck[];
  exitReasons: string[];
  verdict: "keep" | "watch" | "exit";
}

function fail(message: string): never {
  throw new AiError("invalid-request", `budget-economics: ${message}`);
}

function nonNegative(value: number, field: string): number {
  if (!Number.isFinite(value) || value < 0) fail(`${field} must be a finite number >= 0`);
  return value;
}

function ratio(value: number, field: string, allowZero = true): number {
  if (!Number.isFinite(value) || value < (allowZero ? 0 : Number.MIN_VALUE) || value > 1) {
    fail(`${field} must be in ${allowZero ? "[0, 1]" : "(0, 1]"}`);
  }
  return value;
}

function validate(input: EconomicsInput): void {
  if (input.name.trim() === "") fail("name 不能为空");
  nonNegative(input.orchestratedCostMicros, "orchestratedCostMicros");
  ratio(input.successProbability, "successProbability", false);
  nonNegative(input.standaloneCostPerSuccessMicros, "standaloneCostPerSuccessMicros");
  ratio(input.reuseRatio, "reuseRatio");
  nonNegative(input.sharedContextTokens, "sharedContextTokens");
  nonNegative(input.handoffTokens, "handoffTokens");
  ratio(input.cachedInputPriceRatio, "cachedInputPriceRatio");
  if (input.stepFailureRates.length === 0) fail("至少需要一个节点的失败率");
  for (const rate of input.stepFailureRates) ratio(rate, "stepFailureRate");
  nonNegative(input.retriesPerStep, "retriesPerStep");
  ratio(input.targetSuccess, "targetSuccess", false);
  nonNegative(input.qualityLiftPct, "qualityLiftPct");
  if (input.maxCostPerSuccessMicros !== undefined) {
    nonNegative(input.maxCostPerSuccessMicros, "maxCostPerSuccessMicros");
  }
}

/** 共享前缀相对全量复制的回本线；分母为 0 时返回 null。 */
export function breakEvenReuseRatio(
  sharedContextTokens: number, handoffTokens: number, cachedInputPriceRatio: number,
): number | null {
  nonNegative(sharedContextTokens, "sharedContextTokens");
  nonNegative(handoffTokens, "handoffTokens");
  ratio(cachedInputPriceRatio, "cachedInputPriceRatio");
  const saved = sharedContextTokens * (1 - cachedInputPriceRatio);
  if (saved <= 0) return null;
  const value = handoffTokens / saved;
  return value <= 1 ? Number(value.toFixed(4)) : null;
}

/**
 * 单步失败预算：给定节点数与每步重试次数，要让整链成功率达到目标，
 * 单个节点的单次失败率最多是多少。重试把有效失败率降到 f^(r+1)。
 */
export function maxStepFailureRate(steps: number, retriesPerStep: number, targetSuccess: number): number {
  if (!Number.isInteger(steps) || steps < 1) fail("steps 必须是 >= 1 的整数");
  nonNegative(retriesPerStep, "retriesPerStep");
  ratio(targetSuccess, "targetSuccess", false);
  const perStep = 1 - Math.pow(targetSuccess, 1 / steps);
  return Number(Math.pow(perStep, 1 / (1 + retriesPerStep)).toFixed(6));
}

/**
 * 复核不是重算一遍成本，而是回答四个是非题：
 * 复用率过线没有、失败率守预算没有、每次成功交付是否更便宜、质量提升是否配得上溢价。
 * 任何一条硬条件不满足就退出；都满足但余量很薄则进入观察。
 */
export function reviewEconomics(input: EconomicsInput): EconomicsReview {
  validate(input);

  const costPerSuccess = Math.round(input.orchestratedCostMicros / input.successProbability);
  const netCost = costPerSuccess - input.standaloneCostPerSuccessMicros;
  const netCostPct = input.standaloneCostPerSuccessMicros === 0
    ? 0 : Number(((netCost / input.standaloneCostPerSuccessMicros) * 100).toFixed(4));

  const breakEven = breakEvenReuseRatio(
    input.sharedContextTokens, input.handoffTokens, input.cachedInputPriceRatio);
  const reuseMarginPct = breakEven === null || breakEven === 0
    ? 0 : Number((((input.reuseRatio - breakEven) / breakEven) * 100).toFixed(4));

  const maxStep = maxStepFailureRate(
    input.stepFailureRates.length, input.retriesPerStep, input.targetSuccess);
  const worstStep = Math.max(...input.stepFailureRates);
  const failureHeadroomPct = maxStep === 0
    ? 0 : Number((((maxStep - worstStep) / maxStep) * 100).toFixed(4));

  const costPremiumPct = netCostPct;
  const qualityJustified = netCost <= 0 || input.qualityLiftPct >= costPremiumPct;

  const checks: EconomicsCheck[] = [
    {
      name: "复用率过回本线",
      passed: breakEven !== null && input.reuseRatio >= breakEven,
      detail: breakEven === null
        ? "缓存折扣为 0，共享前缀无法回本"
        : `复用率 ${(input.reuseRatio * 100).toFixed(2)}%，回本线 ${(breakEven * 100).toFixed(2)}%`,
    },
    {
      name: "单步失败率守预算",
      passed: worstStep <= maxStep,
      detail: `最差节点 ${(worstStep * 100).toFixed(2)}%，预算 ${(maxStep * 100).toFixed(2)}%`,
    },
    {
      name: "每次成功交付不更贵",
      passed: netCost <= 0 || qualityJustified,
      detail: `编排 ${costPerSuccess} 微元，独立 ${input.standaloneCostPerSuccessMicros} 微元，差 ${netCostPct.toFixed(2)}%`,
    },
  ];

  if (input.maxCostPerSuccessMicros !== undefined) {
    checks.push({
      name: "不超过业务成本上限",
      passed: costPerSuccess <= input.maxCostPerSuccessMicros,
      detail: `每次成功 ${costPerSuccess} 微元，上限 ${input.maxCostPerSuccessMicros} 微元`,
    });
  }

  const exitReasons: string[] = [];
  if (breakEven === null) exitReasons.push("缓存折扣为 0，共享前缀无法回本");
  else if (input.reuseRatio < breakEven) {
    exitReasons.push(`复用率 ${(input.reuseRatio * 100).toFixed(2)}% 低于回本线 ${(breakEven * 100).toFixed(2)}%`);
  }
  if (worstStep > maxStep) {
    exitReasons.push(`最差节点失败率 ${(worstStep * 100).toFixed(2)}% 超过单步预算 ${(maxStep * 100).toFixed(2)}%`);
  }
  if (netCost > 0 && !qualityJustified) {
    exitReasons.push(
      `每次成功交付贵 ${netCostPct.toFixed(2)}%，质量提升 ${input.qualityLiftPct.toFixed(2)} 个百分点不足以覆盖`);
  }
  if (input.maxCostPerSuccessMicros !== undefined && costPerSuccess > input.maxCostPerSuccessMicros) {
    exitReasons.push(`每次成功交付 ${costPerSuccess} 微元超过业务上限 ${input.maxCostPerSuccessMicros} 微元`);
  }

  const thin = reuseMarginPct < 10 || failureHeadroomPct < 10 || (netCostPct > -5 && netCostPct < 0);
  const verdict = exitReasons.length > 0 ? "exit" : thin ? "watch" : "keep";

  return {
    name: input.name,
    costPerSuccessMicros: costPerSuccess,
    netCostMicros: netCost,
    netCostPct,
    breakEvenReuseRatio: breakEven ?? 0,
    reuseMarginPct,
    maxStepFailureRate: maxStep,
    worstStepFailureRate: worstStep,
    failureHeadroomPct,
    costPremiumPct,
    qualityJustified,
    checks,
    exitReasons,
    verdict,
  };
}