《互联网产品的 AI 架构·模型接入与能力边界》1.1 产品里的 AI 能力到底是什么

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

/** 产品对外承诺的 AI 能力标识，例如 "chat.reply"、"search.rerank"。 */
export type CapabilityId = string;
export type ProviderId = string;
export type TenantId = string;

export type QualityTier = "frontier" | "standard" | "economy";

/** 模型档案是选型与路由的唯一事实来源，成本一律用整数微元表示。 */
export interface ModelProfile {
  id: string;
  provider: ProviderId;
  capabilities: CapabilityId[];
  qualityTier: QualityTier;
  contextWindow: number;
  maxOutputTokens: number;
  /** 输入价格：微元 / 百万 token，避免浮点误差。 */
  inputMicrosPerMTok: number;
  /** 输出价格：微元 / 百万 token。 */
  outputMicrosPerMTok: number;
  /** 该模型在目标区域的 P95 延迟，用于预算分配，不是 SLA。 */
  p95LatencyMs: number;
  regions: string[];
  healthy: boolean;
}

export type Role = "system" | "user" | "assistant" | "tool";

export interface ChatMessage {
  role: Role;
  content: string;
  name?: string;
}

/** 网关收到的统一请求。业务方只描述能力与预算，不指定具体模型。 */
export interface ChatRequest {
  requestId: string;
  capability: CapabilityId;
  tenantId: TenantId;
  region?: string;
  messages: ChatMessage[];
  maxOutputTokens: number;
  /** 端到端剩余预算；网关必须在预算内给出结果或明确失败。 */
  deadlineMs: number;
  stream?: boolean;
  /** 业务幂等键：同一键在窗口内允许复用结果。 */
  idempotencyKey?: string;
  metadata?: Record<string, string>;
}

export interface Usage {
  inputTokens: number;
  outputTokens: number;
  costMicros: number;
}

export type DegradeReason =
  | "model-unavailable"
  | "deadline-exceeded"
  | "budget-exceeded"
  | "content-blocked"
  | "fallback-template";

export interface ChatResponse {
  requestId: string;
  modelId: string;
  output: string;
  usage: Usage;
  finishReason: "stop" | "length" | "tool_call" | "content_filter";
  degraded?: DegradeReason;
}

/** 时钟注入让超时与预算逻辑可以被确定性测试。 */
export interface Clock {
  now(): number;
}

export const systemClock: Clock = {
  now: () => Date.now(),
};

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

import assert from "node:assert/strict";
import test from "node:test";

import { AiError, isRetryable, normalizeError } from "../../src/core/errors.ts";
import { systemClock } from "../../src/core/types.ts";
import type { ChatRequest, ModelProfile } from "../../src/core/types.ts";
import { estimateCostMicros, validateRequest } from "../../src/protocol/chat.ts";
import { decodeStreamEvent, encodeStreamEvent } from "../../src/protocol/stream.ts";

const model: ModelProfile = {
  id: "mock-small",
  provider: "mock",
  capabilities: ["chat.reply"],
  qualityTier: "economy",
  contextWindow: 8_000,
  maxOutputTokens: 1_024,
  inputMicrosPerMTok: 250_000,
  outputMicrosPerMTok: 1_000_000,
  p95LatencyMs: 400,
  regions: ["cn"],
  healthy: true,
};

function request(overrides: Partial<ChatRequest> = {}): ChatRequest {
  return {
    requestId: "req-1",
    capability: "chat.reply",
    tenantId: "tenant-a",
    messages: [{ role: "user", content: "你好" }],
    maxOutputTokens: 128,
    deadlineMs: 2_000,
    ...overrides,
  };
}

test("合法请求通过校验", () => {
  assert.doesNotThrow(() => validateRequest(request()));
});

test("空消息被归为 invalid-request 且不可重试", () => {
  try {
    validateRequest(request({ messages: [] }));
    assert.fail("应当抛出错误");
  } catch (error) {
    const aiError = normalizeError(error);
    assert.equal(aiError.kind, "invalid-request");
    assert.equal(isRetryable(aiError), false);
  }
});

test("超时与限流可重试，鉴权错误不可重试", () => {
  assert.equal(isRetryable(new AiError("timeout", "slow")), true);
  assert.equal(isRetryable(new AiError("rate-limit", "busy")), true);
  assert.equal(isRetryable(new AiError("auth", "bad key")), false);
});

test("成本按微元向上取整", () => {
  assert.equal(estimateCostMicros(model, 1_000_000, 1_000_000), 1_250_000);
  assert.equal(estimateCostMicros(model, 1, 1), 2);
});

test("流式事件可往返编解码", () => {
  const frame = encodeStreamEvent({ type: "delta", text: "回声" });
  assert.deepEqual(decodeStreamEvent(frame), { type: "delta", text: "回声" });
  assert.equal(decodeStreamEvent("data: [DONE]\n\n"), null);
});

test("系统时钟返回毫秒时间戳", () => {
  assert.equal(typeof systemClock.now(), "number");
});

node --test test/core/foundation.test.ts

✔ 合法请求通过校验 (0.530459ms)
✔ 空消息被归为 invalid-request 且不可重试 (0.790084ms)
✔ 超时与限流可重试，鉴权错误不可重试 (0.06675ms)
✔ 成本按微元向上取整 (0.075083ms)
✔ 流式事件可往返编解码 (0.488958ms)
✔ 系统时钟返回毫秒时间戳 (0.065583ms)
ℹ tests 6
ℹ suites 0
ℹ pass 6
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 155.229