《互联网产品的 AI 架构·模型接入与能力边界》10.1 模型不可用时产品该做什么

// file: src/degrade/plan.ts
// tier: L1
// verify: node --test test/degrade/plan.test.ts

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

/** 健康检查与错误率共同得出的三档信号，业务方只消费这三个值。 */
export type Availability = "healthy" | "degraded" | "unavailable";

/** 能力对主流程的约束级别：可缺、可弱、必须阻塞。 */
export type Criticality = "optional" | "degradable" | "blocking";

export interface CapabilityPolicy {
  capability: string;
  criticality: Criticality;
  /** 是否允许降级到备用通道（小模型、规则或模板）。 */
  fallbackAllowed: boolean;
  /** 不可用时是否中断主流程；只有 blocking 可以设为 true。 */
  blocksFlow: boolean;
  /** 用户能看到的两种文案：降级仍在服务、完全不可用。 */
  copy: { degraded: string; unavailable: string };
}

export type PlanAction = "serve" | "degrade" | "hide" | "block";

export interface DegradationPlan {
  capability: string;
  action: PlanAction;
  criticality: Criticality;
  continueFlow: boolean;
  /** 面向用户的文案；serve 时为 undefined。 */
  message?: string;
  reason?: "capability-unavailable" | "policy-blocked";
}

export interface AvailabilitySignal {
  capability: string;
  availability: Availability;
}

export interface DegradationReport {
  plans: DegradationPlan[];
  counts: Record<PlanAction, number>;
  flowBlocked: boolean;
}

/**
 * 校验策略本身，而不是等到线上才发现。
 * 可缺能力不允许阻断流程，阻断型能力必须声明阻断，可弱能力必须有备胎。
 */
export function validatePolicy(policy: CapabilityPolicy): void {
  if (policy.capability.trim() === "") {
    throw new AiError("invalid-request", "capability 不能为空");
  }
  if (policy.copy.degraded.trim() === "" || policy.copy.unavailable.trim() === "") {
    throw new AiError("invalid-request", `${policy.capability}: 降级与不可用文案都必须提供`);
  }
  if (policy.criticality === "optional" && policy.blocksFlow) {
    throw new AiError("invalid-request", `${policy.capability}: 可选能力不得中断主流程`);
  }
  if (policy.criticality === "blocking" && !policy.blocksFlow) {
    throw new AiError("invalid-request", `${policy.capability}: 阻断型能力必须声明中断主流程`);
  }
  if (policy.criticality === "degradable" && !policy.fallbackAllowed) {
    throw new AiError("invalid-request", `${policy.capability}: 可弱能力必须允许备用通道`);
  }
}

function serve(policy: CapabilityPolicy): DegradationPlan {
  return {
    capability: policy.capability,
    action: "serve",
    criticality: policy.criticality,
    continueFlow: true,
  };
}

/**
 * 单一决策点：同一份策略在不同信号下只有一个结果。
 * 文案跟着 action 走，避免调用方各自拼提示语。
 */
export function planFor(policy: CapabilityPolicy, availability: Availability): DegradationPlan {
  validatePolicy(policy);
  if (availability === "healthy") {
    return serve(policy);
  }

  if (availability === "degraded") {
    return {
      capability: policy.capability,
      action: "degrade",
      criticality: policy.criticality,
      continueFlow: true,
      message: policy.copy.degraded,
    };
  }

  if (policy.criticality === "blocking") {
    return {
      capability: policy.capability,
      action: "block",
      criticality: policy.criticality,
      continueFlow: !policy.blocksFlow,
      message: policy.copy.unavailable,
      reason: "policy-blocked",
    };
  }

  if (policy.criticality === "degradable") {
    return {
      capability: policy.capability,
      action: "degrade",
      criticality: policy.criticality,
      continueFlow: true,
      message: policy.copy.degraded,
      reason: "capability-unavailable",
    };
  }

  return {
    capability: policy.capability,
    action: "hide",
    criticality: policy.criticality,
    continueFlow: true,
    message: policy.copy.unavailable,
    reason: "capability-unavailable",
  };
}

/**
 * 批量编排：缺少信号的能力按 unavailable 处理（失败关闭），
 * 并统计有多少条主流程会被阻断。
 */
export function planCapabilities(
  policies: CapabilityPolicy[],
  signals: AvailabilitySignal[],
): DegradationReport {
  const seen = new Set<string>();
  const byCapability = new Map(signals.map((signal) => [signal.capability, signal.availability]));
  const plans = policies.map((policy) => {
    if (seen.has(policy.capability)) {
      throw new AiError("invalid-request", `${policy.capability}: 策略重复声明`);
    }
    seen.add(policy.capability);
    return planFor(policy, byCapability.get(policy.capability) ?? "unavailable");
  });
  const counts: Record<PlanAction, number> = { serve: 0, degrade: 0, hide: 0, block: 0 };
  for (const plan of plans) {
    counts[plan.action] += 1;
  }
  return {
    plans,
    counts,
    flowBlocked: plans.some((plan) => !plan.continueFlow),
  };
}

node --test test/degrade/plan.test.ts

✔ 健康时所有能力直接服务 (1.080875ms)
✔ 可缺能力不可用时隐藏，主流程继续 (0.093875ms)
✔ 可弱能力不可用时降级到备用通道 (0.06125ms)
✔ 阻断型能力不可用时阻塞流程并给出用户文案 (0.063208ms)
✔ 阻断型能力只是变弱时仍可服务，不提前阻塞 (0.064583ms)
✔ 策略矛盾在声明期被拒绝 (0.3085ms)
✔ 批量编排按能力聚合，缺失信号按不可用处理 (0.547541ms)
✔ 重复能力声明被拒绝 (0.120041ms)
ℹ tests 8
ℹ pass 8
ℹ fail 0