《互联网产品的 AI 架构·模型接入与能力边界》3.2 统一契约与流式协议

// file: src/core/errors.ts
// tier: L1
// verify: node --test test/core/foundation.test.ts

/** 网关对外只暴露这一组错误类别，避免把提供方的私有错误码泄漏给业务方。 */
export type AiErrorKind =
  | "auth"
  | "quota"
  | "rate-limit"
  | "timeout"
  | "unavailable"
  | "invalid-request"
  | "invalid-output"
  | "content-blocked"
  | "provider";

const RETRYABLE: Record<AiErrorKind, boolean> = {
  auth: false,
  quota: false,
  "rate-limit": true,
  timeout: true,
  unavailable: true,
  "invalid-request": false,
  "invalid-output": true,
  "content-blocked": false,
  provider: true,
};

export interface AiErrorOptions {
  cause?: unknown;
  retryAfterMs?: number;
  /** 已经消耗的预算，失败也要计量。 */
  usage?: { inputTokens: number; outputTokens: number; costMicros: number };
}

export class AiError extends Error {
  readonly kind: AiErrorKind;
  readonly retryable: boolean;
  readonly retryAfterMs?: number;
  readonly usage?: { inputTokens: number; outputTokens: number; costMicros: number };

  constructor(kind: AiErrorKind, message: string, options: AiErrorOptions = {}) {
    super(message);
    this.name = "AiError";
    this.kind = kind;
    this.retryable = RETRYABLE[kind];
    this.retryAfterMs = options.retryAfterMs;
    this.usage = options.usage;
    if (options.cause !== undefined) {
      this.cause = options.cause;
    }
  }
}

/** 未知异常统一收敛为 provider 类错误，保留原始 cause 供日志使用。 */
export function normalizeError(error: unknown): AiError {
  if (error instanceof AiError) {
    return error;
  }
  const message = error instanceof Error ? error.message : String(error);
  return new AiError("provider", message, { cause: error });
}

export function isRetryable(error: unknown): boolean {
  return normalizeError(error).retryable;
}

// file: src/protocol/chat.ts
// tier: L1
// verify: node --test test/core/foundation.test.ts

import { AiError } from "../core/errors.ts";
import type { ChatRequest, ChatResponse, ModelProfile } from "../core/types.ts";

/** provider 只能用统一契约实现，网关不关心它背后是哪家厂商。 */
export interface ChatProvider {
  readonly id: string;
  complete(request: ChatRequest, model: ModelProfile): Promise<ChatResponse>;
}

/** 请求进入网关的第一道检查：结构错误不消耗模型预算。 */
export function validateRequest(request: ChatRequest): void {
  if (request.requestId.trim() === "") {
    throw new AiError("invalid-request", "requestId is required");
  }
  if (request.capability.trim() === "") {
    throw new AiError("invalid-request", "capability is required");
  }
  if (request.messages.length === 0) {
    throw new AiError("invalid-request", "messages must not be empty");
  }
  if (request.maxOutputTokens <= 0) {
    throw new AiError("invalid-request", "maxOutputTokens must be positive");
  }
  if (request.deadlineMs <= 0) {
    throw new AiError("invalid-request", "deadlineMs must be positive");
  }
}

/** 成本按整数微元计算，向上取整，避免把一次请求算成零成本。 */
export function estimateCostMicros(
  model: ModelProfile,
  inputTokens: number,
  outputTokens: number,
): number {
  const input = Math.ceil((inputTokens * model.inputMicrosPerMTok) / 1_000_000);
  const output = Math.ceil((outputTokens * model.outputMicrosPerMTok) / 1_000_000);
  return input + output;
}

// file: src/gateway/mock-provider.ts
// tier: L1
// verify: node --test test/gateway/server.test.ts

import { AiError } from "../core/errors.ts";
import type { AiErrorKind } from "../core/errors.ts";
import type { ChatRequest, ChatResponse, ModelProfile, Usage } from "../core/types.ts";
import { estimateCostMicros } from "../protocol/chat.ts";
import type { ChatProvider } from "../protocol/chat.ts";
import type { StreamChunk, StreamingChatProvider } from "./server.ts";

/** 固定档案，让实验里的 token 与成本口径可重复。 */
export const mockModel: ModelProfile = {
  id: "mock-echo-1",
  provider: "mock",
  capabilities: ["chat.reply", "search.rerank"],
  qualityTier: "economy",
  contextWindow: 8_192,
  maxOutputTokens: 1_024,
  inputMicrosPerMTok: 100_000,
  outputMicrosPerMTok: 400_000,
  p95LatencyMs: 50,
  regions: ["cn"],
  healthy: true,
};

const FAILURE_KINDS: readonly AiErrorKind[] = [
  "rate-limit",
  "timeout",
  "unavailable",
  "content-blocked",
  "provider",
];

/** 案例估算：两个字符约一个 token；真实口径必须用分词器，这里只要确定性。 */
export function estimateTokens(text: string): number {
  return Math.max(1, Math.ceil([...text.replace(/\s+/g, "")].length / 2));
}

interface MockPlan {
  output: string;
  usage: Usage;
  finishReason: ChatResponse["finishReason"];
}

function buildPlan(request: ChatRequest, model: ModelProfile): MockPlan {
  const injected = request.metadata?.mockFail;
  if (injected !== undefined && FAILURE_KINDS.includes(injected as AiErrorKind)) {
    throw new AiError(injected as AiErrorKind, `mock provider 注入错误: ${injected}`, {
      retryAfterMs: injected === "rate-limit" ? 1_000 : undefined,
    });
  }

  const lastUser = [...request.messages].reverse().find((message) => message.role === "user");
  const blocked = request.metadata?.mockFinish === "content_filter";
  const full = blocked
    ? ""
    : `【回声 mock】收到 ${request.messages.length} 条消息。回应：${lastUser?.content ?? ""}`;
  const chars = [...full];
  const maxChars = Math.max(1, request.maxOutputTokens * 2);
  const output = chars.length > maxChars ? chars.slice(0, maxChars).join("") : full;

  const inputTokens = request.messages.reduce(
    (sum, message) => sum + estimateTokens(message.content) + 4,
    0,
  );
  const outputTokens = output === "" ? 0 : estimateTokens(output);
  return {
    output,
    usage: { inputTokens, outputTokens, costMicros: estimateCostMicros(model, inputTokens, outputTokens) },
    finishReason: blocked ? "content_filter" : output.length < full.length ? "length" : "stop",
  };
}

export interface MockProviderOptions {
  /** 流式切片大小，按字符计。 */
  chunkSize?: number;
}

/**
 * 确定性 mock：同样的请求一定得到同样的文本、token 与成本。
 * 不访问网络、不 sleep，测试因此不需要等待真实模型。
 */
export function createMockProvider(options: MockProviderOptions = {}): StreamingChatProvider {
  const chunkSize = Math.max(1, options.chunkSize ?? 3);
  const provider: ChatProvider & StreamingChatProvider = {
    id: "mock",

    async complete(request: ChatRequest, model: ModelProfile): Promise<ChatResponse> {
      const plan = buildPlan(request, model);
      return {
        requestId: request.requestId,
        modelId: model.id,
        output: plan.output,
        usage: plan.usage,
        finishReason: plan.finishReason,
        ...(plan.finishReason === "content_filter"
          ? { degraded: "content-blocked" as const }
          : {}),
      };
    },

    async *stream(request: ChatRequest, model: ModelProfile): AsyncIterable<StreamChunk> {
      const plan = buildPlan(request, model);
      const chars = [...plan.output];
      const failAfter = Number(request.metadata?.mockFailAfter ?? "0");
      let emitted = 0;

      for (let offset = 0; offset < chars.length; offset += chunkSize) {
        yield { text: chars.slice(offset, offset + chunkSize).join("") };
        emitted += 1;
        if (Number.isFinite(failAfter) && failAfter > 0 && emitted >= failAfter) {
          throw new AiError("provider", "mock provider 在流中途断开");
        }
      }
      yield { text: "", done: true, usage: plan.usage, finishReason: plan.finishReason };
    },
  };
  return provider;
}