《互联网产品的 AI 架构·多能力编排与任务闭环》2.2 交接成本与复用回本线

820 + 3,200 × (1 − r × 0.9) = 3,200
820 = 3,200 × 0.9 × r
r = 820 ÷ (3,200 × 0.9) = 28.47%

// file: src/orch/handoff-cost.ts
// tier: L2
// verify: node --test test/orch/handoff.test.ts

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

export type ContextMode = "copy" | "pass" | "share";

export interface HandoffStep {
  id: string;
  inputTokens: number;
  outputTokens: number;
  latencyMs: number;
  /** 单次尝试的失败率；重试会把有效失败率降到它的幂。 */
  failureRate: number;
}

export interface HandoffScenario {
  steps: readonly HandoffStep[];
  sharedContextTokens: number;
  /** 每次交接新增的增量上下文。 */
  handoffContextTokens: number;
  /** 每次交接携带的上一跳结果。 */
  resultTokensPerHop: number;
  prefixReuseRatio: number;
  /** 缓存输入价格占全价的比例，0.1 表示省 90%。 */
  cachedInputPriceRatio: number;
  retriesPerStep: number;
  handoffLatencyMs: number;
  /** 输入价格：微元 / 千 token。 */
  inputMicrosPerKTok: number;
  outputMicrosPerKTok: number;
}

export interface ModeCost {
  mode: ContextMode;
  contextTokensPerHop: number;
  contextCostMicrosPerHop: number;
  totalContextTokens: number;
  totalContextCostMicros: number;
  /** 相对 copy 模式的上下文成本变化；负数代表更省。 */
  vsCopyPct: number;
}

export interface OrchestrationAnalysis {
  steps: number;
  standaloneCostMicros: number;
  orchestratedCostMicros: number;
  handoffTokensPerHop: number;
  costDeltaPct: number;
  retryCostMicros: number;
  successProbability: number;
  costPerSuccessMicros: number;
  standaloneCostPerSuccessMicros: number;
  latencyMs: number;
  latencyTaxPct: number;
  /** 复用率低于此值时，share 模式比 copy 模式更贵。 */
  breakEvenReuseRatio: number | null;
  maxStepFailureForTarget: number;
  expectedWastedCostMicros: number;
  modes: ModeCost[];
}

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

function integer(value: number, field: string, min = 0): number {
  if (!Number.isInteger(value) || value < min) fail(`${field} must be an integer >= ${min}`);
  return value;
}

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

function cost(tokens: number, pricePerKTok: number): number {
  return Math.ceil((tokens * pricePerKTok) / 1_000);
}

function validate(scenario: HandoffScenario): void {
  if (scenario.steps.length === 0) fail("至少需要一个能力步骤");
  const seen = new Set<string>();
  for (const step of scenario.steps) {
    if (step.id.trim() === "") fail("step.id 不能为空");
    if (seen.has(step.id)) fail(`重复的 step.id ${step.id}`);
    seen.add(step.id);
    integer(step.inputTokens, `${step.id}.inputTokens`);
    integer(step.outputTokens, `${step.id}.outputTokens`);
    if (!Number.isFinite(step.latencyMs) || step.latencyMs < 0) fail(`${step.id}.latencyMs 非法`);
    ratio(step.failureRate, `${step.id}.failureRate`);
  }
  integer(scenario.sharedContextTokens, "sharedContextTokens");
  integer(scenario.handoffContextTokens, "handoffContextTokens");
  integer(scenario.resultTokensPerHop, "resultTokensPerHop");
  ratio(scenario.prefixReuseRatio, "prefixReuseRatio");
  ratio(scenario.cachedInputPriceRatio, "cachedInputPriceRatio");
  integer(scenario.retriesPerStep, "retriesPerStep");
  if (!Number.isFinite(scenario.handoffLatencyMs) || scenario.handoffLatencyMs < 0) fail("handoffLatencyMs 非法");
  integer(scenario.inputMicrosPerKTok, "inputMicrosPerKTok", 1);
  integer(scenario.outputMicrosPerKTok, "outputMicrosPerKTok", 1);
}

/** 每次交接的 token：增量上下文加上上一跳结果。 */
export function handoffTokensPerHop(scenario: HandoffScenario): number {
  return scenario.handoffContextTokens + scenario.resultTokensPerHop;
}

/** share 模式下，一个下游节点实际需要重算的共享上下文 token。 */
export function shareContextTokens(scenario: HandoffScenario, reuseRatio = scenario.prefixReuseRatio): number {
  ratio(reuseRatio, "reuseRatio");
  return Math.ceil(scenario.sharedContextTokens * (1 - reuseRatio * (1 - scenario.cachedInputPriceRatio)));
}

export function contextTokensForMode(
  mode: ContextMode,
  scenario: HandoffScenario,
  reuseRatio = scenario.prefixReuseRatio,
): number {
  if (mode === "copy") return scenario.sharedContextTokens;
  if (mode === "pass") return handoffTokensPerHop(scenario);
  return handoffTokensPerHop(scenario) + shareContextTokens(scenario, reuseRatio);
}

/** 复制、传递、共享三种模式的 token 与现金成本；首跳没有交接成本。 */
export function compareContextModes(scenario: HandoffScenario): ModeCost[] {
  validate(scenario);
  const hops = scenario.steps.length - 1;
  const copyCost = cost(contextTokensForMode("copy", scenario), scenario.inputMicrosPerKTok);
  return (["copy", "pass", "share"] as const).map((mode) => {
    const tokens = contextTokensForMode(mode, scenario);
    const perHop = cost(tokens, scenario.inputMicrosPerKTok);
    const baseline = copyCost * hops;
    return {
      mode,
      contextTokensPerHop: tokens,
      contextCostMicrosPerHop: perHop,
      totalContextTokens: tokens * hops,
      totalContextCostMicros: perHop * hops,
      vsCopyPct: baseline === 0 ? 0 : ((perHop * hops - baseline) / baseline) * 100,
    };
  });
}

/**
 * share 相对 copy 的回本复用率：
 * handoff ÷ (共享上下文 × (1 − 缓存价比例))。
 */
export function breakEvenReuseRatio(scenario: HandoffScenario): number | null {
  const handoff = handoffTokensPerHop(scenario);
  if (handoff === 0) return 0;
  if (scenario.sharedContextTokens === 0 || scenario.cachedInputPriceRatio === 1) return null;
  const value = handoff / (scenario.sharedContextTokens * (1 - scenario.cachedInputPriceRatio));
  return value <= 1 ? Number(value.toFixed(4)) : null;
}

/**
 * 把独立调用与顺序编排放在同一套单价下比较。
 * 编排默认使用 share 模式；失败路径按到达概率乘进每一步。
 */
export function analyzeOrchestration(scenario: HandoffScenario, successTarget = 0.95): OrchestrationAnalysis {
  validate(scenario);
  if (!(successTarget > 0 && successTarget < 1)) fail("successTarget 必须落在 (0, 1)");
  const handoffTokens = handoffTokensPerHop(scenario);
  const shareTokens = shareContextTokens(scenario);

  let standaloneCost = 0;
  let standaloneFullCost = 0;
  let orchestratedCost = 0;
  let fullCost = 0;
  let expectedCost = 0;
  let expectedWithoutRetry = 0;
  let reach = 1;
  let success = 1;
  let latency = 0;
  let standaloneLatency = 0;

  scenario.steps.forEach((step, index) => {
    const standaloneStep =
      cost(scenario.sharedContextTokens + step.inputTokens, scenario.inputMicrosPerKTok) +
      cost(step.outputTokens, scenario.outputMicrosPerKTok);
    standaloneCost += standaloneStep;
    standaloneLatency += step.latencyMs;

    const sharedCost = index === 0
      ? cost(scenario.sharedContextTokens, scenario.inputMicrosPerKTok)
      : cost(shareTokens, scenario.inputMicrosPerKTok);
    const handoffCost = index === 0 ? 0 : cost(handoffTokens, scenario.inputMicrosPerKTok);
    const stepCost = sharedCost + handoffCost +
      cost(step.inputTokens, scenario.inputMicrosPerKTok) +
      cost(step.outputTokens, scenario.outputMicrosPerKTok);
    orchestratedCost += stepCost;

    const attemptFactor = 1 + scenario.retriesPerStep * step.failureRate;
    const effectiveFailure = Math.pow(step.failureRate, 1 + scenario.retriesPerStep);
    standaloneFullCost += standaloneStep * attemptFactor;
    fullCost += stepCost * attemptFactor;
    expectedCost += reach * stepCost * attemptFactor;
    expectedWithoutRetry += reach * stepCost;
    latency += reach * (step.latencyMs + (index === 0 ? 0 : scenario.handoffLatencyMs));
    reach *= 1 - effectiveFailure;
    success *= 1 - effectiveFailure;
  });

  const maxStepFailure = Math.pow(
    1 - Math.pow(successTarget, 1 / scenario.steps.length),
    1 / (1 + scenario.retriesPerStep),
  );

  return {
    steps: scenario.steps.length,
    standaloneCostMicros: standaloneCost,
    orchestratedCostMicros: orchestratedCost,
    handoffTokensPerHop: handoffTokens,
    costDeltaPct: standaloneCost === 0 ? 0 : ((orchestratedCost - standaloneCost) / standaloneCost) * 100,
    retryCostMicros: Math.round(expectedCost - expectedWithoutRetry),
    successProbability: success,
    costPerSuccessMicros: Math.round(expectedCost / success),
    standaloneCostPerSuccessMicros: Math.round(standaloneFullCost / success),
    latencyMs: Math.round(latency),
    latencyTaxPct: standaloneLatency === 0 ? 0 : ((latency - standaloneLatency) / standaloneLatency) * 100,
    breakEvenReuseRatio: breakEvenReuseRatio(scenario),
    maxStepFailureForTarget: Number(maxStepFailure.toFixed(4)),
    expectedWastedCostMicros: Math.round(expectedCost - success * fullCost),
    modes: compareContextModes(scenario),
  };
}