《互联网产品的 AI 架构·多能力编排与任务闭环》4.1 共享上下文的三种形态

copy(i)          = S
shared-prefix(0) = S
shared-prefix(i) = H + S × (1 − r × (1 − c))
handle(i)        = Q + R

H + S × (1 − r × (1 − c)) < S
H < S × r × (1 − c)
r > H ÷ (S × (1 − c))

// file: src/orch/context-shape.ts
// tier: L1
// verify: node --test test/orch/context-budget.test.ts

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

/** 共享上下文的三种传递形态。 */
export type ContextMode = "copy" | "shared-prefix" | "handle";

/**
 * 三种共享形态的成本模型。token 都在输入侧，价格按千 token 的整数微元计。
 * - copy：每个节点都携带完整共享上下文。
 * - shared-prefix：首节点全价，后续节点复用前缀并只传增量交接包。
 * - handle：每个节点只收句柄，再按句柄解析出自己需要的片段。
 */
export interface ContextShapeSpec {
  nodes: number;
  sharedContextTokens: number;
  /** 共享前缀模式下，每次交接额外传的增量上下文与上一跳结果。 */
  handoffTokens: number;
  /** 句柄模式每次传递的引用 token。 */
  handleTokens: number;
  /** 句柄解析后节点真正读入的片段 token，用来把解析成本计入比较。 */
  resolvedSliceTokens: number;
  prefixReuseRatio: number;
  /** 缓存输入占全价的比例；0.1 表示 90% 折扣。 */
  cachedInputPriceRatio: number;
  inputMicrosPerKTok: number;
}

export interface ModeCost {
  mode: ContextMode;
  tokensPerNode: readonly number[];
  totalTokens: number;
  costMicros: number;
  deltaTokensPct: number;
  deltaCostMicros: number;
  deltaCostPct: number;
}

export interface ShapeComparison {
  nodes: number;
  handoffTokens: number;
  modes: readonly ModeCost[];
  copyCostMicros: number;
  cheapestMode: ContextMode;
  /** 共享前缀相对全量复制的回本复用率；null 表示无论复用多少都不划算。 */
  prefixBreakEvenReuseRatio: number | null;
  prefixProfitable: boolean;
}

const MODE_ORDER: readonly ContextMode[] = ["copy", "shared-prefix", "handle"];

function fail(message: string): never {
  throw new AiError("invalid-request", `context-shape: ${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 finite(value: number, field: string, min = 0): number {
  if (!Number.isFinite(value) || value < min) fail(`${field} must be a finite number >= ${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 tokenCost(tokens: number, pricePerKTok: number): number {
  return Math.ceil((tokens * pricePerKTok) / 1_000);
}

function validate(spec: ContextShapeSpec): void {
  integer(spec.nodes, "nodes", 1);
  integer(spec.sharedContextTokens, "sharedContextTokens");
  integer(spec.handoffTokens, "handoffTokens");
  integer(spec.handleTokens, "handleTokens");
  integer(spec.resolvedSliceTokens, "resolvedSliceTokens");
  ratio(spec.prefixReuseRatio, "prefixReuseRatio");
  ratio(spec.cachedInputPriceRatio, "cachedInputPriceRatio");
  integer(spec.inputMicrosPerKTok, "inputMicrosPerKTok", 1);
}

/**
 * 共享前缀相对全量复制的回本线：复用省下的钱要覆盖每次交接包的成本。
 * 公式与具体单价无关，只取决于 token 结构与缓存折扣。
 */
export function prefixBreakEvenReuseRatio(
  sharedContextTokens: number,
  handoffTokens: number,
  cachedInputPriceRatio: number,
): number | null {
  integer(sharedContextTokens, "sharedContextTokens");
  integer(handoffTokens, "handoffTokens");
  ratio(cachedInputPriceRatio, "cachedInputPriceRatio");
  const savedPerFullReuse = sharedContextTokens * (1 - cachedInputPriceRatio);
  if (savedPerFullReuse <= 0) return null;
  const breakEven = handoffTokens / savedPerFullReuse;
  return breakEven <= 1 ? Number(breakEven.toFixed(4)) : null;
}

function compareToCopy(mode: ContextMode, cost: number, tokens: number, copyCost: number, copyTokens: number): ModeCost {
  const deltaCostMicros = cost - copyCost;
  const deltaTokens = tokens - copyTokens;
  return {
    mode,
    tokensPerNode: [],
    totalTokens: tokens,
    costMicros: cost,
    deltaTokensPct: copyTokens === 0 ? 0 : Number(((deltaTokens / copyTokens) * 100).toFixed(4)),
    deltaCostMicros,
    deltaCostPct: copyCost === 0 ? 0 : Number(((deltaCostMicros / copyCost) * 100).toFixed(4)),
  };
}

/**
 * 在同一个场景、同一套单价下比较三种形态。
 * 共享前缀的后续节点按“交接包 + 未命中部分的全价上下文”计费；
 * 句柄模式按“句柄 + 解析片段”计费，不含上下文存储本身的运维成本。
 */
export function compareContextShapes(spec: ContextShapeSpec): ShapeComparison {
  validate(spec);
  const reuseFactor = 1 - spec.prefixReuseRatio * (1 - spec.cachedInputPriceRatio);
  const raw: Record<ContextMode, number[]> = {
    copy: Array.from({ length: spec.nodes }, () => spec.sharedContextTokens),
    "shared-prefix": [spec.sharedContextTokens],
    handle: Array.from({ length: spec.nodes }, () => spec.handleTokens + spec.resolvedSliceTokens),
  };
  for (let index = 1; index < spec.nodes; index += 1) {
    raw["shared-prefix"].push(spec.handoffTokens + Math.round(spec.sharedContextTokens * reuseFactor));
  }

  const copyTokens = raw.copy.reduce((sum, value) => sum + value, 0);
  const copyCost = raw.copy.reduce((sum, value) => sum + tokenCost(value, spec.inputMicrosPerKTok), 0);

  let cheapestMode: ContextMode = MODE_ORDER[0];
  let cheapestCost = Number.POSITIVE_INFINITY;
  const modes: ModeCost[] = MODE_ORDER.map((mode) => {
    const tokens = raw[mode].reduce((sum, value) => sum + value, 0);
    const cost = raw[mode].reduce((sum, value) => sum + tokenCost(value, spec.inputMicrosPerKTok), 0);
    if (cost < cheapestCost) {
      cheapestCost = cost;
      cheapestMode = mode;
    }
    return { ...compareToCopy(mode, cost, tokens, copyCost, copyTokens), tokensPerNode: raw[mode].slice() };
  });

  const breakEven = prefixBreakEvenReuseRatio(
    spec.sharedContextTokens,
    spec.handoffTokens,
    spec.cachedInputPriceRatio,
  );
  const rawBreakEven = spec.sharedContextTokens * (1 - spec.cachedInputPriceRatio) <= 0
    ? null
    : spec.handoffTokens / (spec.sharedContextTokens * (1 - spec.cachedInputPriceRatio));

  return {
    nodes: spec.nodes,
    handoffTokens: spec.handoffTokens,
    modes,
    copyCostMicros: copyCost,
    cheapestMode,
    prefixBreakEvenReuseRatio: breakEven,
    prefixProfitable: rawBreakEven !== null && spec.prefixReuseRatio >= rawBreakEven,
  };
}