《互联网产品的 AI 架构·多能力编排与任务闭环》8.2 超支时的裁剪顺序

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

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

/** 超支时的裁剪动作，按「先无损、后有损、最后止损」排序。 */
export type TrimKind = "cache" | "context-trim" | "downgrade" | "skip-optional" | "reject";
export type Reversibility = "reversible" | "request-scoped" | "user-visible";

export interface TrimStep {
  id: string;
  kind: TrimKind;
  /** 该动作在当前请求上最多能省下的微元。 */
  savingMicros: number;
  /** 完全执行时的质量损失，百分点；1.5 表示 1.5%。 */
  qualityLossPct: number;
  reversibility: Reversibility;
  precondition?: string;
}

export interface TrimPolicy {
  /** 一条请求允许累计的质量损失上限，百分点。 */
  maxQualityLossPct: number;
  allowSkipOptional: boolean;
  allowReject: boolean;
}

export interface TrimDecision {
  stepId: string; kind: TrimKind;
  status: "applied" | "skipped" | "not-needed";
  reason?: "quality-floor" | "disabled";
  requestedMicros: number; appliedMicros: number;
  qualityLossPct: number; reversibility: Reversibility;
}

export interface TrimPlan {
  overrunMicros: number; coveredMicros: number; residualMicros: number;
  appliedMicros: number;
  /** 可逆动作省下的钱：下一次请求可以恢复。 */
  reversibleSavingMicros: number;
  /** 用户可见动作省下的钱：本请求已经交付了更少的东西。 */
  userVisibleSavingMicros: number;
  totalQualityLossPct: number;
  decisions: TrimDecision[];
  appliedKinds: TrimKind[];
  decision: "within-budget" | "trimmed" | "reject" | "over-budget";
  fallback?: string;
}

function fail(message: string): never {
  throw new AiError("invalid-request", `budget-trim: ${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 pct(value: number, field: string): number {
  if (!Number.isFinite(value) || value < 0 || value > 100) fail(`${field} must be in [0, 100]`);
  return value;
}

function validate(steps: readonly TrimStep[], policy: TrimPolicy): void {
  if (steps.length === 0) fail("至少需要一个裁剪动作");
  const ids = new Set<string>();
  for (const step of steps) {
    if (step.id.trim() === "" || ids.has(step.id)) fail(`step.id 非法或重复: ${step.id}`);
    ids.add(step.id);
    nonNegative(step.savingMicros, `${step.id}.savingMicros`);
    pct(step.qualityLossPct, `${step.id}.qualityLossPct`);
  }
  pct(policy.maxQualityLossPct, "maxQualityLossPct");
  const rejectIndex = steps.findIndex((step) => step.kind === "reject");
  if (rejectIndex >= 0 && rejectIndex !== steps.length - 1) fail("reject 必须是最后一个动作");
}

/**
 * 按顺序尝试裁剪，直到覆盖超支或用完动作。
 * 部分执行时质量损失按节省比例折算；下一步会突破质量下限就跳过，
 * 让后面的止损动作接管。
 */
export function planTrim(overrunMicros: number, steps: readonly TrimStep[], policy: TrimPolicy): TrimPlan {
  nonNegative(overrunMicros, "overrunMicros");
  validate(steps, policy);

  let remaining = overrunMicros;
  let qualityLoss = 0;
  let reversibleSaving = 0;
  let userVisibleSaving = 0;
  const decisions: TrimDecision[] = [];
  const record = (
    step: TrimStep, status: TrimDecision["status"], applied: number,
    reason?: TrimDecision["reason"],
  ): void => {
    decisions.push({
      stepId: step.id, kind: step.kind, status, reason,
      requestedMicros: status === "not-needed" ? 0 : step.kind === "reject" ? remaining : step.savingMicros,
      appliedMicros: applied,
      qualityLossPct: Number((step.savingMicros === 0 || step.kind === "reject"
        ? 0
        : (step.qualityLossPct * applied) / step.savingMicros).toFixed(4)),
      reversibility: step.reversibility,
    });
  };

  for (const step of steps) {
    if (remaining === 0) {
      record(step, "not-needed", 0);
      continue;
    }
    if (step.kind === "skip-optional" && !policy.allowSkipOptional) {
      record(step, "skipped", 0, "disabled");
      continue;
    }
    if (step.kind === "reject") {
      if (!policy.allowReject) {
        record(step, "skipped", 0, "disabled");
        continue;
      }
      record(step, "applied", remaining);
      decisions[decisions.length - 1].qualityLossPct = Number((100 - qualityLoss).toFixed(4));
      userVisibleSaving += remaining;
      qualityLoss = 100;
      remaining = 0;
      continue;
    }

    const applied = Math.min(step.savingMicros, remaining);
    const loss = step.savingMicros === 0 ? 0 : (step.qualityLossPct * applied) / step.savingMicros;
    if (qualityLoss + loss > policy.maxQualityLossPct) {
      record(step, "skipped", 0, "quality-floor");
      continue;
    }

    remaining -= applied;
    qualityLoss += loss;
    if (step.reversibility === "reversible") reversibleSaving += applied;
    else userVisibleSaving += applied;
    record(step, "applied", applied);
  }

  const covered = overrunMicros - remaining;
  const rejected = decisions.some((item) => item.kind === "reject" && item.status === "applied");
  const decision = overrunMicros === 0 ? "within-budget"
    : rejected ? "reject"
      : remaining > 0 ? "over-budget"
        : "trimmed";

  return {
    overrunMicros,
    coveredMicros: covered,
    residualMicros: remaining,
    appliedMicros: covered,
    reversibleSavingMicros: reversibleSaving,
    userVisibleSavingMicros: userVisibleSaving,
    totalQualityLossPct: Number(qualityLoss.toFixed(4)),
    decisions,
    appliedKinds: decisions.filter((item) => item.status === "applied").map((item) => item.kind),
    decision,
    fallback: decision === "reject"
      ? "返回排队提示与人工兜底入口；不要用降档结果冒充完整交付。"
      : decision === "over-budget"
        ? "本次不允许拒绝；必须回退到共享池、下调目标或在上游限流。"
        : undefined,
  };
}

/**
 * 回声的三节点样本：基础成本 3,786 微元。
 * 超支通常来自重试、上下文增长与重复执行，五步按伤害从低到高排列。
 */
export const ECHO_TRIM_STEPS: readonly TrimStep[] = [
  {
    id: "reuse-cache", kind: "cache", savingMicros: 320, qualityLossPct: 0,
    reversibility: "reversible", precondition: "上一跳结果仍在缓存窗口内",
  },
  {
    id: "trim-context", kind: "context-trim", savingMicros: 280, qualityLossPct: 1.5,
    reversibility: "reversible", precondition: "长尾上下文可以下一轮补回",
  },
  {
    id: "downgrade-model", kind: "downgrade", savingMicros: 420, qualityLossPct: 6,
    reversibility: "request-scoped", precondition: "经济档在能力边界内且通过质量门槛",
  },
  {
    id: "skip-optional", kind: "skip-optional", savingMicros: 671, qualityLossPct: 18,
    reversibility: "user-visible", precondition: "可选节点缺席时仍有可交付的部分结果",
  },
  {
    id: "reject-request", kind: "reject", savingMicros: 0, qualityLossPct: 100,
    reversibility: "user-visible", precondition: "已有排队、重试或人工兜底入口",
  },
];

export const ECHO_TRIM_POLICY: TrimPolicy = {
  maxQualityLossPct: 12, allowSkipOptional: true, allowReject: true,
};