《互联网产品的 AI 架构·模型接入与能力边界》4.1 路由的五个维度

// file: src/routing/dimensions.ts
// tier: L1
// verify: node --test test/routing/dimensions.test.ts

import type { CapabilityId, QualityTier } from "../core/types.ts";

/** 路由必须同时回答的五个问题；顺序固定，便于比较与测试。 */
export type RoutingDimension = "task" | "tenant" | "region" | "cost" | "health";

/** 决策主权：业务侧声明意图，网关侧执行机制。 */
export type DecisionOwner = "business" | "gateway";

export type TenantPlan = "free" | "plus" | "enterprise";

export interface DimensionSpec {
  dimension: RoutingDimension;
  owner: DecisionOwner;
  /** 这一维回答的问题。 */
  question: string;
  /** 业务侧能提供的输入（可以为空）；网关负责补全运行时事实。 */
  businessInput: string;
  /** 放到错误一侧时最常见的后果。 */
  misplacedCost: string;
}

export const ROUTING_DIMENSIONS: readonly RoutingDimension[] = [
  "task",
  "tenant",
  "region",
  "cost",
  "health",
];

export const DIMENSION_SPECS: readonly DimensionSpec[] = [
  {
    dimension: "task",
    owner: "business",
    question: "这次请求要完成什么，质量下限与输出形态是什么",
    businessInput: "capability + qualityFloor + maxOutputTokens",
    misplacedCost: "网关按价格猜任务，长文摘要被短输出上限截断",
  },
  {
    dimension: "tenant",
    owner: "business",
    question: "哪个租户、买了什么档位、能否使用高成本模型",
    businessInput: "tenantPlan + tenant policy",
    misplacedCost: "网关自行推断租户等级，免费租户被误升到 frontier",
  },
  {
    dimension: "region",
    owner: "gateway",
    question: "请求应该落在哪个区域，哪些提供方在该区域可用",
    businessInput: "userRegion（可缺省，由边缘推断）",
    misplacedCost: "业务写死区域，跨境流量与合规区域发生漂移",
  },
  {
    dimension: "cost",
    owner: "gateway",
    question: "这次请求在预算内能选哪些模型，实际花费多少",
    businessInput: "costCeilingMicros（软上限）",
    misplacedCost: "业务自己算价，价格表更新后所有预算同时失真",
  },
  {
    dimension: "health",
    owner: "gateway",
    question: "哪些模型当下可用，熔断后何时允许再进入",
    businessInput: "无（由网关探测）",
    misplacedCost: "业务缓存健康状态，故障恢复后仍长期绕开可用模型",
  },
];

/** 按维度取规格；未知维度属于配置错误，直接抛出而不是静默返回 undefined。 */
export function dimensionSpec(dimension: RoutingDimension): DimensionSpec {
  const spec = DIMENSION_SPECS.find((item) => item.dimension === dimension);
  if (!spec) {
    throw new Error(`unknown routing dimension: ${dimension}`);
  }
  return spec;
}

export interface RoutingIntent {
  capability: CapabilityId;
  qualityFloor: QualityTier | null;
  tenantPlan: TenantPlan | null;
  /** 用户区域；业务侧可以缺省，由网关从边缘推断。 */
  userRegion: string | null;
  /** 单次请求的成本软上限；小于等于 0 表示未声明。 */
  costCeilingMicros: number;
}

export interface DimensionPlan {
  dimensions: DimensionSpec[];
  businessOwned: DimensionSpec[];
  gatewayOwned: DimensionSpec[];
  /** 业务侧声明缺失；网关不得用默认值掩盖。 */
  blockers: string[];
  /** 网关需要在请求时补齐的运行时事实。 */
  gatewayFacts: string[];
}

/**
 * 把业务意图拆成五个维度，并标出谁负责决策。
 * 业务侧缺失的输入进入 blockers，而不是被网关的默认值吸收。
 */
export function planDimensions(intent: RoutingIntent): DimensionPlan {
  const blockers: string[] = [];
  if (intent.capability.trim() === "") {
    blockers.push("task:capability-missing");
  }
  if (intent.qualityFloor === null) {
    blockers.push("task:quality-floor-missing");
  }
  if (intent.tenantPlan === null) {
    blockers.push("tenant:plan-missing");
  }
  if (!Number.isFinite(intent.costCeilingMicros) || intent.costCeilingMicros <= 0) {
    blockers.push("cost:ceiling-missing");
  }

  const specs = ROUTING_DIMENSIONS.map(dimensionSpec);
  const gatewayFacts = [
    "cost:live-price-sheet",
    "health:probe-window",
    "region:provider-region-table",
  ];
  if (intent.userRegion === null || intent.userRegion.trim() === "") {
    gatewayFacts.push("region:infer-from-edge");
  }

  return {
    dimensions: specs,
    businessOwned: specs.filter((spec) => spec.owner === "business"),
    gatewayOwned: specs.filter((spec) => spec.owner === "gateway"),
    blockers,
    gatewayFacts: gatewayFacts.sort(),
  };
}

export interface Placement {
  dimension: RoutingDimension;
  owner: DecisionOwner;
}

/**
 * 审计维度主权划分。返回空数组表示五个维度都恰好由正确的一侧决策。
 * 重复与缺失也会被记录，避免“只审了关心的两个维度”。
 */
export function auditPlacements(placements: readonly Placement[]): string[] {
  const issues: string[] = [];
  const seen = new Set<RoutingDimension>();
  for (const placement of placements) {
    if (seen.has(placement.dimension)) {
      issues.push(`${placement.dimension}:duplicate`);
      continue;
    }
    seen.add(placement.dimension);
    const spec = dimensionSpec(placement.dimension);
    if (placement.owner !== spec.owner) {
      issues.push(
        `${placement.dimension}:owned-by-${placement.owner}-expected-${spec.owner}`,
      );
    }
  }
  for (const dimension of ROUTING_DIMENSIONS) {
    if (!seen.has(dimension)) {
      issues.push(`${dimension}:missing`);
    }
  }
  return issues;
}

node --test test/routing/dimensions.test.ts

✔ 五个维度顺序固定且规格齐全 (0.74725ms)
✔ 任务与租户归业务侧，区域、成本、健康归网关 (0.147125ms)
✔ 完整意图没有阻断项，网关只补运行时事实 (0.067958ms)
✔ 业务侧声明缺失时逐项进入 blockers (0.066208ms)
✔ 区域可以缺省，由网关从边缘推断 (0.558042ms)
✔ 主权审计能发现放错侧、重复与遗漏 (0.263625ms)
✔ 同一份意图重复规划得到相同结果 (0.114584ms)
ℹ tests 7
ℹ suites 0
ℹ pass 7
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 146.467084