《互联网产品的 AI 架构·模型接入与能力边界》13.1 能力清单与契约矩阵

// file: src/core/capability-matrix.ts
// tier: L1
// verify: node --test test/core/capability-matrix.test.ts

import type { CapabilitySpec, FailureMode } from "./capability-spec.ts";

/** 能力契约必须逐项填满的六个面，顺序就是评审时的阅读顺序。 */
export const MATRIX_FACETS = ["input", "output", "quality", "latency", "cost", "failure"] as const;
export type MatrixFacet = (typeof MATRIX_FACETS)[number];

/** 进入矩阵的字段。它们描述能力本身，不随单个租户变化。 */
export const MATRIX_FIELDS = [
  "id",
  "title",
  "inputs",
  "outputs",
  "qualityTier",
  "minPassRate",
  "latencyBudgetMs",
  "costCeilingMicros",
  "onFailure",
  "fallbacks",
] as const;
export type MatrixField = (typeof MATRIX_FIELDS)[number];

/** 这些字段属于租户配置，不能写进能力契约矩阵。 */
export const TENANT_CONFIG_FIELDS = [
  "quotaPerDay",
  "costBudgetMicros",
  "degradeCopy",
  "fallbackEnabled",
  "region",
  "modelAllowlist",
] as const;
export type TenantConfigField = (typeof TENANT_CONFIG_FIELDS)[number];

export type RiskLevel = "high" | "medium" | "low";

export interface MatrixCell {
  facet: MatrixFacet;
  /** 给评审直接看的摘要，不做机器解析。 */
  value: string;
  declared: boolean;
}

export interface MatrixRisk {
  score: number;
  level: RiskLevel;
  reasons: string[];
}

export interface MatrixRow {
  capability: string;
  title: string;
  cells: MatrixCell[];
  missing: MatrixFacet[];
  risk: MatrixRisk;
}

export interface CapabilityMatrix {
  rows: MatrixRow[];
  missingByCapability: Record<string, MatrixFacet[]>;
  /** 每个面在多少个能力上已声明，用于发现系统性缺口。 */
  facetCoverage: Record<MatrixFacet, number>;
}

const FAILURE_WEIGHT: Record<FailureMode, number> = {
  "fail-fast": 35,
  degrade: 12,
  queue: 20,
  "silent-skip": 25,
};

function failureDeclared(spec: CapabilitySpec): boolean {
  if (spec.onFailure === "degrade") return spec.fallbacks.length > 0;
  if (spec.onFailure === "fail-fast") return spec.fallbacks.length === 0;
  if (spec.onFailure === "queue") return spec.latencyBudgetMs >= 3_000;
  return false;
}

function failureText(spec: CapabilitySpec): string {
  if (spec.fallbacks.length === 0) return `${spec.onFailure}（无降级路径）`;
  return `${spec.onFailure} → ${spec.fallbacks.join(" / ")}`;
}

function assessRisk(spec: CapabilitySpec, missing: MatrixFacet[]): MatrixRisk {
  const reasons: string[] = [];
  let score = 0;

  score += FAILURE_WEIGHT[spec.onFailure];
  reasons.push(`失败姿态 ${spec.onFailure}`);

  if (spec.minPassRate >= 0.9) {
    score += 15;
    reasons.push(`质量下限 ${spec.minPassRate}`);
  }
  if (spec.latencyBudgetMs <= 500) {
    score += 15;
    reasons.push(`延迟预算 ${spec.latencyBudgetMs}ms`);
  } else if (spec.latencyBudgetMs <= 1_500) {
    score += 8;
    reasons.push(`延迟预算 ${spec.latencyBudgetMs}ms`);
  }
  if (spec.costCeilingMicros >= 3_000) {
    score += 10;
    reasons.push(`单次成本上限 ${spec.costCeilingMicros} 微元`);
  } else if (spec.costCeilingMicros >= 1_000) {
    score += 5;
    reasons.push(`单次成本上限 ${spec.costCeilingMicros} 微元`);
  }
  if (spec.qualityTier === "frontier") {
    score += 10;
    reasons.push("依赖前沿档模型");
  } else if (spec.qualityTier === "standard") {
    score += 5;
  }
  if (missing.length > 0) {
    score += missing.length * 20;
    reasons.push(`缺失面 ${missing.join(", ")}`);
  }

  score = Math.min(100, score);
  const level: RiskLevel = score >= 60 ? "high" : score >= 30 ? "medium" : "low";
  return { score, level, reasons };
}

function buildRow(spec: CapabilitySpec): MatrixRow {
  const cells: MatrixCell[] = MATRIX_FACETS.map((facet) => {
    if (facet === "input") {
      return { facet, value: spec.inputs.join(" + "), declared: spec.inputs.length > 0 };
    }
    if (facet === "output") {
      return { facet, value: spec.outputs.join(" + "), declared: spec.outputs.length > 0 };
    }
    if (facet === "quality") {
      return {
        facet,
        value: `通过率 ≥ ${spec.minPassRate}（${spec.qualityTier}）`,
        declared: spec.minPassRate > 0 && spec.minPassRate <= 1,
      };
    }
    if (facet === "latency") {
      return {
        facet,
        value: `P95 ≤ ${spec.latencyBudgetMs}ms`,
        declared: spec.latencyBudgetMs > 0,
      };
    }
    if (facet === "cost") {
      return {
        facet,
        value: `≤ ${spec.costCeilingMicros} 微元/次`,
        declared: spec.costCeilingMicros > 0,
      };
    }
    return { facet, value: failureText(spec), declared: failureDeclared(spec) };
  });

  const missing = cells.filter((cell) => !cell.declared).map((cell) => cell.facet);
  return {
    capability: spec.id,
    title: spec.title,
    cells,
    missing,
    risk: assessRisk(spec, missing),
  };
}

/** 输入能力清单，输出按风险从高到低排列的矩阵视图。 */
export function buildCapabilityMatrix(specs: readonly CapabilitySpec[]): CapabilityMatrix {
  const rows = specs
    .map(buildRow)
    .sort(
      (left, right) =>
        right.risk.score - left.risk.score ||
        right.missing.length - left.missing.length ||
        left.capability.localeCompare(right.capability),
    );

  const missingByCapability: Record<string, MatrixFacet[]> = {};
  const facetCoverage = Object.fromEntries(
    MATRIX_FACETS.map((facet) => [facet, 0]),
  ) as Record<MatrixFacet, number>;

  for (const row of rows) {
    missingByCapability[row.capability] = row.missing;
    for (const cell of row.cells) {
      if (cell.declared) facetCoverage[cell.facet] += 1;
    }
  }

  return { rows, missingByCapability, facetCoverage };
}

/** 发布门禁：任何能力缺面都不允许悄悄上线。 */
export function assertMatrixComplete(matrix: CapabilityMatrix): void {
  const gaps = matrix.rows.filter((row) => row.missing.length > 0);
  if (gaps.length > 0) {
    const detail = gaps.map((row) => `${row.capability}: ${row.missing.join(",")}`).join("; ");
    throw new Error(`能力矩阵存在缺失面: ${detail}`);
  }
}

node --test test/core/capability-matrix.test.ts

ℹ tests 6
ℹ pass 6
ℹ fail 0