@tokenbuddy/tokenbuddy 1.0.12 → 1.0.14

package/src/seller-route-planner.ts

@@ -0,0 +1,323 @@
+import type { RegistrySeller } from "./seller-catalog.js";
+import {
+  planSellerRoutes,
+  type RoutingCandidate,
+  type SellerRoutingPlan,
+  type SellerRoutingStrategyConfig
+} from "./seller-routing-strategy.js";
+
+/**
+ * `planSellerRouteSet` 候选来源：走了 prewarm cache 还是回退到 registry 顺序。
+ */
+export type SellerRouteSource = "prewarm_cache" | "registry_fallback";
+/** 路由层使用的熔断状态枚举，与 `seller-pool.CircuitState` 语义一致。 */
+export type SellerCircuitState = "closed" | "half_open" | "open";
+
+/**
+ * 路由规划器在合并多个数据源时使用的"实时指标"维度。
+ * 由 `SellerPool` 快照聚合；可空字段表示该维度暂未采集。
+ */
+export interface SellerRouteMetric {
+  /** seller ID */
+  sellerId: string;
+  /** 综合健康分 0-100，可选 */
+  healthScore?: number;
+  /** 平均延迟（毫秒），可选 */
+  avgLatencyMs?: number;
+  /** 折扣系数（0-1），可选；缺省时 scoring 视为"无折扣信息" */
+  discountRatio?: number;
+  /** 当前熔断状态，可选；`open` 的 seller 直接被剔除候选 */
+  circuit?: SellerCircuitState;
+}
+
+/**
+ * 路由规划器视角的 prewarm 候选：比 `PrewarmCandidate` 少调度内部状态，只保留打分需要的字段。
+ */
+export interface SellerRoutePrewarmCandidate {
+  /** seller ID */
+  sellerId: string;
+  /** seller URL（去尾部斜杠） */
+  url: string;
+  /** 综合健康分，可选 */
+  healthScore?: number;
+  /** 平均延迟（毫秒），可选 */
+  avgLatencyMs?: number;
+}
+
+/**
+ * 路由规划器视角的 seller 元数据：折扣系数和 manifest 刷新时间。
+ * 用于在 `discount` 排序时把"无折扣"和"折扣已知"区分开。
+ */
+export interface SellerRouteMetadata {
+  sellerId: string;
+  discountRatio?: number;
+  manifestVersion?: string;
+  lastRefreshAt?: number;
+  source: "manifest_selection";
+  errorMessage?: string;
+}
+
+/**
+ * `planSellerRouteSet()` 的入参：把"模型 + 协议 + 支付" + 三类数据源（registry / prewarm / 指标）+ 路由策略打包传入。
+ */
+export interface SellerRoutePlannerInput {
+  /** 目标模型 ID */
+  modelId: string;
+  /** 协议偏好（`chat_completions` / `responses` / `messages`） */
+  protocol: string;
+  /** 支付方式（`mock` / `clawtip`） */
+  paymentMethod: string;
+  /** seller 注册表快照 */
+  registrySellers: RegistrySeller[];
+  /** buyer 路由策略配置（fixed / fixedSet / fullAuto + 评分器） */
+  routing: SellerRoutingStrategyConfig;
+  /** 来自 prewarm cache 的候选（可选；提供时优先使用） */
+  prewarmCandidates?: SellerRoutePrewarmCandidate[];
+  /** seller 实时指标（可选；`circuit=open` 的 seller 被剔除） */
+  sellerMetrics?: SellerRouteMetric[];
+}
+
+/**
+ * 单条规划后的路由：含 seller 描述、URL、聚合后的指标。
+ */
+export interface PlannedSellerRoute {
+  /** seller 注册表描述（用于后续转发） */
+  seller: RegistrySeller;
+  /** seller URL（去尾部斜杠） */
+  url: string;
+  /** 聚合指标：健康分、平均延迟、折扣、registry 声明顺序 */
+  metrics: {
+    healthScore?: number;
+    avgLatencyMs?: number;
+    discountRatio?: number;
+    /** 在 registry 里的声明顺序（0-based，tie-breaker） */
+    registryOrder: number;
+  };
+}
+
+/**
+ * `planSellerRouteSet()` 的返回结果：路由列表 + 来源 + 决策原因 + 模式 / 评分器。
+ */
+export interface SellerRoutePlan {
+  /** 已排好序的可选 seller 列表（按路由策略打分） */
+  routes: PlannedSellerRoute[];
+  /** 候选来源：`prewarm_cache` 或 `registry_fallback` */
+  source: SellerRouteSource;
+  /** 候选来源的细化原因（用于诊断 / 稳定事件断言） */
+  sourceReason: string;
+  /** 路由策略输出的整体决策原因 */
+  reason: string;
+  /** 路由模式（`fixed` / `fixedSet` / `fullAuto`） */
+  mode: SellerRoutingPlan["mode"];
+  /** 使用的评分器（`speed` / `discount` / `balanced`） */
+  scorer: SellerRoutingPlan["scorer"];
+  /** 候选总数（prewarm 阶段剔除了不支持模型 / 协议 / 支付的 seller 之前） */
+  candidateCount: number;
+}
+
+interface CandidateSourceResult {
+  source: SellerRouteSource;
+  sourceReason: string;
+  candidates: RoutingCandidate[];
+}
+
+interface IndexedSeller {
+  seller: RegistrySeller;
+  registryOrder: number;
+}
+
+interface MetricIndex {
+  bySellerId: Map<string, SellerRouteMetric>;
+  openSellerIds: Set<string>;
+}
+
+/**
+ * 给定 (model, protocol, payment) + 三类数据源，规划出有序的 seller 路由列表。
+ * 决策流程：
+ * 1. 索引 registry sellers（按声明顺序）。
+ * 2. 索引 `sellerMetrics`，把 `circuit=open` 的 seller 标记为剔除。
+ * 3. 优先从 `prewarmCandidates` 构造候选；都不可用时回退 registry 顺序。
+ * 4. 调 `planSellerRoutes`（`seller-routing-strategy`）做策略评分。
+ * 5. 把 `RoutingCandidate` 转回 `PlannedSellerRoute`，加上 `registryOrder`。
+ *
+ * @param input 规划入参
+ * @returns 规划后的路由计划
+ */
+export function planSellerRouteSet(input: SellerRoutePlannerInput): SellerRoutePlan {
+  const indexed = indexRegistrySellers(input.registrySellers);
+  const metrics = indexMetrics(input.sellerMetrics);
+  const source = chooseCandidateSource(input, indexed, metrics);
+  const strategyPlan = planSellerRoutes(source.candidates, input.routing);
+  const routes = strategyPlan.routes.map((candidate) => {
+    const seller = indexed.bySellerId.get(candidate.sellerId)?.seller;
+    if (!seller) {
+      throw new Error(`planned seller ${candidate.sellerId} is missing from registry index`);
+    }
+    return {
+      seller,
+      url: candidate.url,
+      metrics: {
+        healthScore: candidate.healthScore,
+        avgLatencyMs: candidate.avgLatencyMs,
+        discountRatio: candidate.discountRatio,
+        registryOrder: candidate.registryOrder
+      }
+    };
+  });
+
+  return {
+    routes,
+    source: source.source,
+    sourceReason: source.sourceReason,
+    reason: strategyPlan.reason,
+    mode: strategyPlan.mode,
+    scorer: strategyPlan.scorer,
+    candidateCount: source.candidates.length
+  };
+}
+
+function chooseCandidateSource(
+  input: SellerRoutePlannerInput,
+  indexed: ReturnType<typeof indexRegistrySellers>,
+  metrics: MetricIndex
+): CandidateSourceResult {
+  const prewarm = input.prewarmCandidates ?? [];
+  if (prewarm.length > 0) {
+    const prewarmCandidates = prewarm
+      .map((candidate) => {
+        const indexedSeller = indexed.bySellerId.get(candidate.sellerId);
+        if (!indexedSeller) {
+          return undefined;
+        }
+        if (metrics.openSellerIds.has(indexedSeller.seller.id)) {
+          return undefined;
+        }
+        return buildCandidate({
+          seller: indexedSeller.seller,
+          registryOrder: indexedSeller.registryOrder,
+          modelId: input.modelId,
+          protocol: input.protocol,
+          paymentMethod: input.paymentMethod,
+          metric: mergeMetric(metrics.bySellerId.get(candidate.sellerId), candidate)
+        });
+      })
+      .filter((candidate): candidate is RoutingCandidate => Boolean(candidate))
+      .filter(isSelectableCandidate);
+
+    if (prewarmCandidates.length > 0) {
+      return {
+        source: "prewarm_cache",
+        sourceReason: "prewarm_candidates_compatible",
+        candidates: prewarmCandidates
+      };
+    }
+  }
+
+  return {
+    source: "registry_fallback",
+    sourceReason: prewarm.length > 0 ? "prewarm_no_compatible_candidates" : "prewarm_missing",
+    candidates: indexed.ordered
+      .filter((entry) => !metrics.openSellerIds.has(entry.seller.id))
+      .map((entry) => buildCandidate({
+        seller: entry.seller,
+        registryOrder: entry.registryOrder,
+        modelId: input.modelId,
+        protocol: input.protocol,
+        paymentMethod: input.paymentMethod,
+        metric: metrics.bySellerId.get(entry.seller.id)
+      }))
+      .filter(isSelectableCandidate)
+  };
+}
+
+function buildCandidate(input: {
+  seller: RegistrySeller;
+  registryOrder: number;
+  modelId: string;
+  protocol: string;
+  paymentMethod: string;
+  metric?: SellerRouteMetric;
+}): RoutingCandidate {
+  return {
+    sellerId: input.seller.id,
+    url: trimTrailingSlashes(input.seller.url),
+    supportsModel: sellerSupportsModel(input.seller, input.modelId),
+    supportsProtocol: sellerSupportsProtocol(input.seller, input.protocol),
+    supportsPayment: sellerSupportsPayment(input.seller, input.paymentMethod),
+    healthScore: input.metric?.healthScore,
+    avgLatencyMs: input.metric?.avgLatencyMs,
+    discountRatio: input.metric?.discountRatio,
+    registryOrder: input.registryOrder
+  };
+}
+
+function isSelectableCandidate(candidate: RoutingCandidate): boolean {
+  return candidate.supportsModel && candidate.supportsProtocol && candidate.supportsPayment;
+}
+
+function indexRegistrySellers(sellers: RegistrySeller[]): {
+  ordered: IndexedSeller[];
+  bySellerId: Map<string, IndexedSeller>;
+} {
+  const ordered = sellers
+    .filter((seller) => Boolean(seller?.id && seller.url))
+    .map((seller, registryOrder) => ({ seller, registryOrder }));
+  return {
+    ordered,
+    bySellerId: new Map(ordered.map((entry) => [entry.seller.id, entry]))
+  };
+}
+
+function indexMetrics(metrics: SellerRouteMetric[] | undefined): MetricIndex {
+  const openSellerIds = new Set((metrics ?? [])
+    .filter((metric) => metric.circuit === "open")
+    .map((metric) => metric.sellerId));
+  return {
+    bySellerId: new Map((metrics ?? [])
+      .filter((metric) => metric.circuit !== "open")
+      .map((metric) => [metric.sellerId, metric])),
+    openSellerIds
+  };
+}
+
+function mergeMetric(
+  metric: SellerRouteMetric | undefined,
+  prewarm: SellerRoutePrewarmCandidate
+): SellerRouteMetric {
+  return {
+    sellerId: prewarm.sellerId,
+    healthScore: prewarm.healthScore ?? metric?.healthScore,
+    avgLatencyMs: prewarm.avgLatencyMs ?? metric?.avgLatencyMs,
+    discountRatio: metric?.discountRatio,
+    circuit: metric?.circuit
+  };
+}
+
+function sellerSupportsModel(seller: RegistrySeller, modelId: string): boolean {
+  const normalized = normalizeLookupValue(modelId);
+  return (seller.models ?? []).some((model) => normalizeLookupValue(model) === normalized);
+}
+
+function sellerSupportsProtocol(seller: RegistrySeller, protocol: string): boolean {
+  const normalized = normalizeLookupValue(protocol);
+  return protocolAliases(seller.supportedProtocols ?? []).some((entry) => normalizeLookupValue(entry) === normalized);
+}
+
+function sellerSupportsPayment(seller: RegistrySeller, paymentMethod: string): boolean {
+  const normalized = normalizeLookupValue(paymentMethod);
+  return (seller.paymentMethods ?? []).some((entry) => normalizeLookupValue(entry) === normalized);
+}
+
+function protocolAliases(protocols: string[]): string[] {
+  return protocols.includes("anthropic_messages") && !protocols.includes("messages")
+    ? [...protocols, "messages"]
+    : protocols;
+}
+
+function normalizeLookupValue(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+function trimTrailingSlashes(value: string): string {
+  return value.replace(/\/+$/, "");
+}

package/src/seller-routing-config.ts

@@ -0,0 +1,198 @@
+import type {
+  SellerRoutingMode,
+  SellerRoutingScorer,
+  SellerRoutingStrategyConfig
+} from "./seller-routing-strategy.js";
+
+/** buyer 配置存盘时使用的顶层 key，对应 `BuyerStore.set("routing", ...)` */
+export const ROUTING_CONFIG_KEY = "routing";
+/** 缺省 scorer：健康 + 速度 + 折扣三方面均衡 */
+export const DEFAULT_ROUTING_SCORER: SellerRoutingScorer = "balanced";
+
+/**
+ * buyer 端的 seller 路由配置，继承策略层 `SellerRoutingStrategyConfig`，
+ * 在此基础上强制 `mode` 和 `scorer` 都必须存在（策略层允许省略）。
+ */
+export interface BuyerSellerRoutingConfig extends SellerRoutingStrategyConfig {
+  /** 路由模式：`fixed` / `fixedSet` / `fullAuto` */
+  mode: SellerRoutingMode;
+  /** 评分器：`speed` / `discount` / `balanced` */
+  scorer: SellerRoutingScorer;
+}
+
+/**
+ * 返回 buyer 默认的 seller 路由配置：`fullAuto` + `balanced`。
+ * 用于首次启动没有持久化配置时的兜底。
+ *
+ * @returns buyer 默认路由配置
+ */
+export function defaultSellerRoutingConfig(): BuyerSellerRoutingConfig {
+  return {
+    mode: "fullAuto",
+    scorer: DEFAULT_ROUTING_SCORER
+  };
+}
+
+/**
+ * 把任意 `unknown`（通常来自 buyer-store 读盘或外部输入）归一化为合法的
+ * `BuyerSellerRoutingConfig`。非法 `mode` / `scorer` 抛错，缺字段则回退到默认。
+ *
+ * @param value 任意输入值（对象 / undefined / 字符串等）
+ * @returns 归一化后的路由配置
+ * @throws 当 `value.mode` 是非 `fixed` / `fixedSet` / `fullAuto` 时
+ * @throws 当 `value.scorer` 是非 `speed` / `discount` / `balanced` 时
+ */
+export function normalizeSellerRoutingConfig(value: unknown): BuyerSellerRoutingConfig {
+  if (!isObject(value)) {
+    return defaultSellerRoutingConfig();
+  }
+
+  const mode = readMode(value.mode);
+  const scorer = readScorer(value.scorer);
+  if (mode === "fixed") {
+    return {
+      mode,
+      sellerId: readOptionalString(value.sellerId),
+      scorer
+    };
+  }
+  if (mode === "fixedSet") {
+    return {
+      mode,
+      sellerIds: readSellerIds(value.sellerIds),
+      scorer
+    };
+  }
+  return {
+    mode: "fullAuto",
+    scorer
+  };
+}
+
+/**
+ * 从 `process.env`（可注入）里解析出 `TB_PROXYD_ROUTING_*` 覆盖项。
+ * 至少有一个变量非空时才返回 `Partial<BuyerSellerRoutingConfig>`，否则返回 `undefined`。
+ * 当 `mode` 未指定时，会根据 `sellerId` / `sellerIds` 是否存在自动选择 `fixed` / `fixedSet` / `fullAuto`。
+ *
+ * @param env 进程环境变量（默认 `process.env`，测试可注入）
+ * @returns 解析出的覆盖项；无任何相关变量时返回 `undefined`
+ * @throws 当 `TB_PROXYD_ROUTING_MODE` 或 `TB_PROXYD_ROUTING_SCORER` 取值非法时
+ */
+export function parseSellerRoutingEnv(env: NodeJS.ProcessEnv = process.env): Partial<BuyerSellerRoutingConfig> | undefined {
+  const modeRaw = env.TB_PROXYD_ROUTING_MODE?.trim();
+  const scorerRaw = env.TB_PROXYD_ROUTING_SCORER?.trim();
+  const sellerId = env.TB_PROXYD_ROUTING_SELLER_ID?.trim();
+  const sellerIdsRaw = env.TB_PROXYD_ROUTING_SELLER_IDS?.trim();
+
+  if (!modeRaw && !scorerRaw && !sellerId && !sellerIdsRaw) {
+    return undefined;
+  }
+
+  const mode = modeRaw
+    ? readMode(modeRaw)
+    : sellerId
+      ? "fixed"
+      : sellerIdsRaw
+        ? "fixedSet"
+        : "fullAuto";
+  const scorer = scorerRaw ? readScorer(scorerRaw) : DEFAULT_ROUTING_SCORER;
+
+  if (mode === "fixed") {
+    return { mode, scorer, sellerId: sellerId || undefined };
+  }
+  if (mode === "fixedSet") {
+    return { mode, scorer, sellerIds: parseSellerIdList(sellerIdsRaw || "") };
+  }
+  return { mode: "fullAuto", scorer };
+}
+
+/**
+ * 合并"buyer-store 持久化值"和"运行时 override"：override 字段优先，
+ * 但合并结果会再次走 `normalizeSellerRoutingConfig` 校验。
+ *
+ * @param stored buyer-store 读出的原始值（可能是 undefined 或非法对象）
+ * @param override 运行时 override（CLI / 临时开关）
+ * @returns 合并并归一化后的配置
+ * @throws 当合并结果包含非法 `mode` / `scorer` 时
+ */
+export function mergeSellerRoutingConfig(
+  stored: unknown,
+  override?: Partial<BuyerSellerRoutingConfig>
+): BuyerSellerRoutingConfig {
+  const base = normalizeSellerRoutingConfig(stored);
+  if (!override) {
+    return base;
+  }
+  return normalizeSellerRoutingConfig({
+    ...base,
+    ...override
+  });
+}
+
+/**
+ * 把逗号分隔的 seller ID 列表解析为去重、trim、过滤空串后的字符串数组。
+ *
+ * @param value 原始字符串，例：`"a,b,b, c,,"`
+ * @returns 去重后的 seller ID 列表
+ */
+export function parseSellerIdList(value: string): string[] {
+  return value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry, index, all) => entry.length > 0 && all.indexOf(entry) === index);
+}
+
+/**
+ * 校验 `BuyerSellerRoutingConfig` 是否满足当前模式的必要字段。
+ * `fixed` 模式必须有非空 `sellerId`；`fixedSet` 模式必须有非空 `sellerIds`。
+ *
+ * @param config 待校验的路由配置
+ * @throws 当 `fixed` 模式缺少 `sellerId` 时
+ * @throws 当 `fixedSet` 模式缺少 `sellerIds` 时
+ */
+export function assertSellerRoutingConfig(config: BuyerSellerRoutingConfig): void {
+  if (config.mode === "fixed" && !config.sellerId?.trim()) {
+    throw new Error("fixed routing requires --seller <sellerId>");
+  }
+  if (config.mode === "fixedSet" && (!config.sellerIds || config.sellerIds.length === 0)) {
+    throw new Error("fixedSet routing requires --seller-set <sellerId[,sellerId...]>");
+  }
+}
+
+function readMode(value: unknown): SellerRoutingMode {
+  if (value === "fixed" || value === "fixedSet" || value === "fullAuto") {
+    return value;
+  }
+  throw new Error("seller routing mode must be fixed, fixedSet, or fullAuto");
+}
+
+function readScorer(value: unknown): SellerRoutingScorer {
+  if (value === undefined || value === null || value === "") {
+    return DEFAULT_ROUTING_SCORER;
+  }
+  if (value === "speed" || value === "discount" || value === "balanced") {
+    return value;
+  }
+  throw new Error("seller routing scorer must be speed, discount, or balanced");
+}
+
+function readOptionalString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function readSellerIds(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value
+      .filter((entry): entry is string => typeof entry === "string")
+      .map((entry) => entry.trim())
+      .filter((entry, index, all) => entry.length > 0 && all.indexOf(entry) === index);
+  }
+  if (typeof value === "string") {
+    return parseSellerIdList(value);
+  }
+  return [];
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}