《互联网产品的 AI 架构·模型接入与能力边界》10.3 降级演练与用户可见性

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

import { AiError } from "../core/errors.ts";
import type { AiErrorKind } from "../core/errors.ts";
import type { ChatRequest, ChatResponse, Clock, ModelProfile } from "../core/types.ts";
import type { ChatProvider } from "../protocol/chat.ts";
import { planFor } from "./plan.ts";
import type { Availability, CapabilityPolicy, DegradationPlan } from "./plan.ts";

export interface FaultPlan {
  /** 只对该能力注入；省略表示全局故障。 */
  capability?: string;
  kind: AiErrorKind;
  /** 前 N 次调用放行，用于演练“故障发生前的成功路径”。 */
  skipCalls?: number;
}

export interface FaultProvider extends ChatProvider {
  readonly calls: number;
  setFault(plan: FaultPlan | null): void;
}

/** 在真实提供方外面套一层确定性故障注入，演练不依赖网络与 sleep。 */
export function createFaultProvider(
  inner: ChatProvider,
  initial: FaultPlan | null = null,
): FaultProvider {
  let fault = initial;
  let calls = 0;
  let matched = 0;

  return {
    id: `drill:${inner.id}`,
    get calls() {
      return calls;
    },
    setFault(next: FaultPlan | null) {
      fault = next;
      matched = 0;
    },
    async complete(request: ChatRequest, model: ModelProfile): Promise<ChatResponse> {
      calls += 1;
      if (fault && (fault.capability === undefined || fault.capability === request.capability)) {
        matched += 1;
        if (matched > (fault.skipCalls ?? 0)) {
          throw new AiError(fault.kind, `演练注入 ${fault.kind}`, {
            retryAfterMs: fault.kind === "rate-limit" ? 1_000 : undefined,
          });
        }
      }
      return inner.complete(request, model);
    },
  };
}

/** content-blocked 说明模型可用但结果不可用，属于“变弱”而不是“不可用”。 */
export function signalFromError(error: unknown): Availability {
  if (error instanceof AiError && error.kind === "content-blocked") {
    return "degraded";
  }
  return "unavailable";
}

/** 跑一次探针：成功看响应的 degraded 标记，失败按错误类别归并。 */
export async function probe(
  provider: ChatProvider,
  request: ChatRequest,
  model: ModelProfile,
): Promise<Availability> {
  try {
    const response = await provider.complete(request, model);
    return response.degraded ? "degraded" : "healthy";
  } catch (error) {
    return signalFromError(error);
  }
}

export interface SwitchInput {
  id: string;
  enabled: boolean;
  /** 相对当前时间的有效期；演练开关不允许永不过期。 */
  ttlMs: number;
  owner: string;
}

export interface FeatureSwitch {
  id: string;
  enabled: boolean;
  expiresAt: number;
  owner: string;
}

export interface SwitchBoard {
  set(input: SwitchInput): FeatureSwitch;
  isEnabled(id: string): boolean;
  /** 关闭所有已到期开关并返回其 id，供演练报告记录。 */
  expire(): string[];
  snapshot(): FeatureSwitch[];
}

export interface SwitchBoardOptions {
  clock: Clock;
  /** 单个开关允许的最长有效期，默认 15 分钟。 */
  maxTtlMs?: number;
}

export function createSwitchBoard(options: SwitchBoardOptions): SwitchBoard {
  const maxTtlMs = options.maxTtlMs ?? 15 * 60_000;
  const switches = new Map<string, FeatureSwitch>();

  const autoOff = (current: FeatureSwitch): FeatureSwitch => {
    if (current.enabled && current.expiresAt <= options.clock.now()) {
      const next = { ...current, enabled: false };
      switches.set(next.id, next);
      return next;
    }
    return current;
  };

  return {
    set(input: SwitchInput): FeatureSwitch {
      if (input.owner.trim() === "") {
        throw new AiError("invalid-request", `${input.id}: 开关必须有负责人`);
      }
      if (input.ttlMs <= 0 || input.ttlMs > maxTtlMs) {
        throw new AiError("invalid-request", `${input.id}: TTL 必须在 1..${maxTtlMs}ms`);
      }
      const next: FeatureSwitch = {
        id: input.id,
        enabled: input.enabled,
        expiresAt: options.clock.now() + input.ttlMs,
        owner: input.owner,
      };
      switches.set(next.id, next);
      return next;
    },
    isEnabled(id: string): boolean {
      const current = switches.get(id);
      if (!current) {
        return false;
      }
      return autoOff(current).enabled;
    },
    expire(): string[] {
      const expired: string[] = [];
      for (const current of switches.values()) {
        const next = autoOff(current);
        if (current.enabled && !next.enabled) {
          expired.push(next.id);
        }
      }
      return expired;
    },
    snapshot(): FeatureSwitch[] {
      return [...switches.values()].map(autoOff);
    },
  };
}

export interface DrillCase {
  name: string;
  fault: FaultPlan | null;
  /** 演练脚本写死的期望信号，而不是从结果反推。 */
  expect: Availability;
}

export interface DrillCheck {
  name: string;
  expected: Availability;
  actual: Availability;
  action: DegradationPlan["action"];
  /** 用户实际会看到的文案；演练不能只断言动作。 */
  message?: string;
  ok: boolean;
}

export interface DrillReport {
  passed: boolean;
  checks: DrillCheck[];
}

export interface DrillOptions {
  provider: FaultProvider;
  model: ModelProfile;
  request: ChatRequest;
  policy: CapabilityPolicy;
}

/**
 * 按脚本注入故障、探测信号、映射到产品动作，并在末尾强制恢复。
 * 恢复检查是报告的一部分，不能靠人工记得关开关。
 */
export async function runDrill(cases: DrillCase[], options: DrillOptions): Promise<DrillReport> {
  const checks: DrillCheck[] = [];
  for (const item of cases) {
    options.provider.setFault(item.fault);
    const actual = await probe(options.provider, options.request, options.model);
    const plan = planFor(options.policy, actual);
    checks.push({
      name: item.name,
      expected: item.expect,
      actual,
      action: plan.action,
      message: plan.message,
      ok: actual === item.expect,
    });
  }

  options.provider.setFault(null);
  const recovered = await probe(options.provider, options.request, options.model);
  const recoveryPlan = planFor(options.policy, recovered);
  checks.push({
    name: "移除故障后回到正常路径",
    expected: "healthy",
    actual: recovered,
    action: recoveryPlan.action,
    message: recoveryPlan.message,
    ok: recovered === "healthy",
  });

  return { passed: checks.every((check) => check.ok), checks };
}

node --test test/degrade/drill.test.ts

✔ 故障只注入指定能力，skipCalls 之前的调用放行 (0.772333ms)
✔ content-blocked 归为变弱，其余错误归为不可用 (0.118958ms)
✔ 开关到期自动关闭，expire 记录被关闭的 id (0.476791ms)
✔ 演练开关必须有负责人且在有效期上限内 (0.126833ms)
✔ 演练按脚本注入故障并强制做恢复断言 (0.244167ms)
✔ 期望写错时演练失败，但恢复检查仍然执行 (0.099458ms)
✔ 注入内容拦截时走降级而不是阻塞 (0.107208ms)
ℹ tests 7
ℹ pass 7
ℹ fail 0