@tokenbuddy/tokenbuddy 1.0.35 → 1.0.37

package/src/seller-routing-config.ts

@@ -1,211 +0,0 @@
-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;
-  /** fixed 模式下按模型固定 seller；缺省时回退到全局 sellerId。 */
-  fixedByModel?: Record<string, string>;
-}
-
-/**
- * 返回 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),
-      fixedByModel: readFixedByModel(value.fixedByModel),
-      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() && Object.keys(config.fixedByModel ?? {}).length === 0) {
-    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 readFixedByModel(value: unknown): Record<string, string> | undefined {
-  if (!isObject(value)) {
-    return undefined;
-  }
-  const entries = Object.entries(value)
-    .map(([modelId, sellerId]) => [modelId.trim(), typeof sellerId === "string" ? sellerId.trim() : ""] as const)
-    .filter(([modelId, sellerId]) => modelId.length > 0 && sellerId.length > 0);
-  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
-}
-
-function isObject(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}

package/src/seller-routing-strategy.ts

@@ -1,362 +0,0 @@
-/**
- * seller 路由模式：
- * - `fixed`：强制使用单个 seller（`sellerId`）
- * - `fixedSet`：在指定 seller 集合内挑选
- * - `fullAuto`：根据指标和 scorer 自动排序
- */
-export type SellerRoutingMode = "fixed" | "fixedSet" | "fullAuto";
-/**
- * 评分器：决定如何把候选的健康/延迟/折扣分折算成总分。
- * - `speed`：TTFT / 输出吞吐优先
- * - `discount`：折扣系数优先
- * - `balanced`：三方面加权均衡
- */
-export type SellerRoutingScorer = "speed" | "discount" | "balanced";
-
-/**
- * seller 路由策略配置：模式 + 可选的目标 seller 列表 + 可选评分器。
- * 策略层不强制 `scorer` 必填（缺省走 `balanced`）；buyer 配置层
- * `BuyerSellerRoutingConfig` 会进一步收紧。
- */
-export interface SellerRoutingStrategyConfig {
-  /** 路由模式 */
-  mode: SellerRoutingMode;
-  /** `fixed` 模式下唯一允许的 seller ID */
-  sellerId?: string;
-  /** `fixedSet` 模式下的候选 seller ID 列表（去重） */
-  sellerIds?: string[];
-  /** 评分器；省略时按 `balanced` 处理 */
-  scorer?: SellerRoutingScorer;
-}
-
-/**
- * 路由规划阶段的中间数据结构：聚合了"兼容性 + 健康画像 + 折扣"。
- * `supportsModel/Protocol/Payment` 由 `sellerSupports*` 系列函数计算，
- * 任一为 `false` 的 candidate 都会被策略层过滤。
- */
-export interface RoutingCandidate {
-  /** seller ID */
-  sellerId: string;
-  /** 去掉尾部斜杠的 seller URL */
-  url: string;
-  /** 是否在 seller 的 `models` 列表里 */
-  supportsModel: boolean;
-  /** 是否在 seller 的 `supportedProtocols` 列表里（含 `messages` alias） */
-  supportsProtocol: boolean;
-  /** 是否在 seller 的 `paymentMethods` 列表里 */
-  supportsPayment: boolean;
-  /** 综合健康分 0-100，可选 */
-  healthScore?: number;
-  /** 平均延迟（毫秒），可选 */
-  avgLatencyMs?: number;
-  /** health probe 延迟（毫秒），可选 */
-  healthProbeLatencyMs?: number;
-  /** TTFT（毫秒），可选 */
-  ttftMs?: number;
-  /** 平均推理延迟（毫秒），可选 */
-  avgInferenceMs?: number;
-  /** 最近 10 分钟窗口内的平均输出吞吐（tokens/s），可选 */
-  avgTokensPerSecond?: number;
-  /** 折扣系数 0-1，可选；缺省视为"无折扣信息" */
-  discountRatio?: number;
-  /** 上游状态，可选 */
-  upstreamStatus?: "healthy" | "degraded" | "unhealthy" | "unknown";
-  /** 上游错误类名，可选 */
-  upstreamErrorClass?: string;
-  /** 在 registry 里的声明顺序（0-based），用于打分平局时的 deterministic 兜底 */
-  registryOrder: number;
-}
-
-/**
- * `planSellerRoutes()` 的输出：选中的候选列表（已按 scorer 排序）+ 决策溯源。
- */
-export interface SellerRoutingPlan {
-  /** 已按策略排序的候选 seller 列表 */
-  routes: RoutingCandidate[];
-  /** 路由模式（来自 config） */
-  mode: SellerRoutingMode;
-  /** 实际生效的评分器（config 缺省时为 `balanced`） */
-  scorer: SellerRoutingScorer;
-  /** 决策原因，例：`fullAuto:balanced:routes_3`、`fixed_seller_not_compatible` */
-  reason: string;
-}
-
-/**
- * 单个 candidate 在某 scorer 下的打分拆解：总分 + 各维度分量 + 缺失的输入。
- * 用于路由诊断 / `tb doctor` 面板展示。
- */
-export interface CandidateScoreBreakdown {
-  /** 评分器 */
-  scorer: SellerRoutingScorer;
-  /** 总分（按 scorer 权重加和） */
-  totalScore: number;
-  /** 健康分量（仅 `speed` / `balanced` 有意义） */
-  healthComponent?: number;
-  /** TTFT 分量（仅 `speed` / `balanced` 有意义） */
-  ttftComponent?: number;
-  /** 输出吞吐分量（仅 `speed` / `balanced` 有意义） */
-  avgTokensPerSecondComponent?: number;
-  /** 折扣分量（仅 `discount` / `balanced` 有意义） */
-  discountComponent?: number;
-  /** 打分时缺失的输入项；缺越多则越说明"无依据" */
-  missingInputs: Array<"healthScore" | "ttftMs" | "avgTokensPerSecond" | "discountRatio">;
-}
-
-type SortableCandidate = RoutingCandidate & { score: number };
-
-const DEFAULT_SCORER: SellerRoutingScorer = "balanced";
-
-/**
- * 根据 `config.mode` 和 `config.scorer` 把候选 seller 过滤、排序并返回路由计划。
- * - `fixed` / `fixedSet` 模式只保留命中的 seller（命中为空时返回空 routes + 决策原因）
- * - `fullAuto` 模式使用所有兼容候选
- * - 排序时按 scorer 计算分数，分数相同时按 `registryOrder` 兜底
- *
- * @param candidates 候选列表（已包含兼容性布尔位）
- * @param config 路由策略配置
- * @returns 路由计划，含 routes / mode / scorer / reason
- */
-export function planSellerRoutes(
-  candidates: RoutingCandidate[],
-  config: SellerRoutingStrategyConfig
-): SellerRoutingPlan {
-  const scorer = config.scorer ?? DEFAULT_SCORER;
-  const compatible = candidates.filter(isCompatibleCandidate);
-  const selected = selectCandidates(compatible, config);
-
-  if (selected.reason !== "ok") {
-    return {
-      routes: [],
-      mode: config.mode,
-      scorer,
-      reason: selected.reason
-    };
-  }
-
-  return {
-    routes: sortCandidates(selected.candidates, scorer),
-    mode: config.mode,
-    scorer,
-    reason: routeReason(config.mode, scorer, selected.candidates.length)
-  };
-}
-
-function selectCandidates(
-  compatible: RoutingCandidate[],
-  config: SellerRoutingStrategyConfig
-): { candidates: RoutingCandidate[]; reason: string } {
-  if (config.mode === "fixed") {
-    const sellerId = normalizeSellerId(config.sellerId);
-    if (!sellerId) {
-      return { candidates: [], reason: "fixed_seller_missing" };
-    }
-    const matched = compatible.filter((candidate) => normalizeSellerId(candidate.sellerId) === sellerId);
-    return matched.length > 0
-      ? { candidates: matched, reason: "ok" }
-      : { candidates: [], reason: "fixed_seller_not_compatible" };
-  }
-
-  if (config.mode === "fixedSet") {
-    const sellerIds = normalizedSellerIdSet(config.sellerIds);
-    if (sellerIds.size === 0) {
-      return { candidates: [], reason: "fixed_set_empty" };
-    }
-    const matched = compatible.filter((candidate) => sellerIds.has(normalizeSellerId(candidate.sellerId)));
-    return matched.length > 0
-      ? { candidates: matched, reason: "ok" }
-      : { candidates: [], reason: "fixed_set_no_compatible_seller" };
-  }
-
-  if (config.mode === "fullAuto") {
-    return compatible.length > 0
-      ? { candidates: compatible, reason: "ok" }
-      : { candidates: [], reason: "no_compatible_seller" };
-  }
-
-  return { candidates: [], reason: "unsupported_routing_mode" };
-}
-
-function isCompatibleCandidate(candidate: RoutingCandidate): boolean {
-  return candidate.supportsModel && candidate.supportsProtocol && candidate.supportsPayment;
-}
-
-function normalizedSellerIdSet(ids: string[] | undefined): Set<string> {
-  return new Set((ids ?? []).map(normalizeSellerId).filter(Boolean));
-}
-
-function normalizeSellerId(id: string | undefined): string {
-  return id?.trim().toLowerCase() ?? "";
-}
-
-function sortCandidates(candidates: RoutingCandidate[], scorer: SellerRoutingScorer): RoutingCandidate[] {
-  return candidates
-    .map((candidate) => ({ ...candidate, score: scoreCandidateBreakdown(candidate, scorer).totalScore }))
-    .sort((a, b) => compareCandidates(a, b, scorer))
-    .map(({ score: _score, ...candidate }) => candidate);
-}
-
-function compareCandidates(a: SortableCandidate, b: SortableCandidate, scorer: SellerRoutingScorer): number {
-  const scoreDiff = b.score - a.score;
-  if (scoreDiff !== 0) {
-    return scoreDiff;
-  }
-
-  if (scorer === "speed") {
-    return compareFiniteAsc(effectiveTtftMs(a), effectiveTtftMs(b))
-      || compareFiniteDesc(a.avgTokensPerSecond, b.avgTokensPerSecond)
-      || compareFiniteDesc(a.healthScore, b.healthScore)
-      || compareRegistryOrder(a, b);
-  }
-
-  if (scorer === "discount") {
-    return compareFiniteAsc(a.discountRatio, b.discountRatio)
-      || compareFiniteDesc(a.healthScore, b.healthScore)
-      || compareRegistryOrder(a, b);
-  }
-
-  return compareRegistryOrder(a, b);
-}
-
-/**
- * 计算单个 candidate 在指定 scorer 下的完整打分拆解（含各维度分量和缺失项）。
- * 不会修改输入 candidate，常用于 doctor 面板和调试日志。
- *
- * 权重设计理由：
- * - **Speed 评分器**：TTFT 65% + Tok/s 25% + Health 10%
- *   - TTFT 占主导是因为首 token 延迟直接影响用户感知的响应速度
- *   - Tok/s 次要，因为大多数场景下吞吐差异不如延迟显著
- *   - Health 最低，只作为平局时的兜底
- *
- * - **Discount 评分器**：折扣 100%
- *   - 纯成本优先，忽略性能指标
- *   - 平局时按健康分和注册顺序兜底
- *
- * - **Balanced 评分器**：Health 35% + TTFT 20% + Tok/s 20% + Discount 25%
- *   - Health 占比最高是为了避免选择不稳定的 seller
- *   - 速度（TTFT + Tok/s）合计 40%，与折扣 25% 形成平衡
- *   - 这是默认评分器，适合大多数生产场景
- *
- * @param candidate 待打分的候选
- * @param scorer 评分器：`speed` / `discount` / `balanced`
- * @returns 打分拆解
- */
-export function scoreCandidateBreakdown(candidate: RoutingCandidate, scorer: SellerRoutingScorer): CandidateScoreBreakdown {
-  const missingInputs = missingScoreInputs(candidate);
-  if (scorer === "speed") {
-    const ttftComponent = latencyScore(effectiveTtftMs(candidate)) * 0.65;
-    const avgTokensPerSecondComponent = tokensPerSecondScore(candidate.avgTokensPerSecond) * 0.25;
-    const healthComponent = finiteOr(candidate.healthScore, 0) * 0.1;
-    return {
-      scorer,
-      totalScore: ttftComponent + avgTokensPerSecondComponent + healthComponent,
-      healthComponent,
-      ttftComponent,
-      avgTokensPerSecondComponent,
-      missingInputs
-    };
-  }
-
-  if (scorer === "discount") {
-    const totalScore = -finiteOr(candidate.discountRatio, Number.POSITIVE_INFINITY);
-    return {
-      scorer,
-      totalScore,
-      discountComponent: totalScore,
-      missingInputs
-    };
-  }
-
-  const healthComponent = finiteOr(candidate.healthScore, 0) * 0.35;
-  const ttftComponent = latencyScore(effectiveTtftMs(candidate)) * 0.2;
-  const avgTokensPerSecondComponent = tokensPerSecondScore(candidate.avgTokensPerSecond) * 0.2;
-  const discountComponent = discountScore(candidate.discountRatio) * 0.25;
-  return {
-    scorer,
-    totalScore: healthComponent + ttftComponent + avgTokensPerSecondComponent + discountComponent,
-    healthComponent,
-    ttftComponent,
-    avgTokensPerSecondComponent,
-    discountComponent,
-    missingInputs
-  };
-}
-
-/**
- * 将延迟（毫秒）转换为 0-100 分数。
- * 公式：`100 - latency_ms / 10`
- *
- * 设计理由：
- * - 0ms → 100分，1000ms → 0分（线性递减）
- * - 除以 10 的比例来自经验：100ms 是"优秀"延迟，1000ms 是"不可接受"延迟
- * - 线性公式的局限：100ms vs 200ms 的差异被等同于 900ms vs 1000ms
- *   实际用户体验可能不是线性的，未来可考虑对数或分段函数
- *
- * @param latencyMs 延迟（毫秒），undefined 或非有限值返回 0 分
- * @returns 0-100 分数
- */
-function latencyScore(latencyMs: number | undefined): number {
-  if (!Number.isFinite(latencyMs)) {
-    return 0;
-  }
-  return Math.max(0, 100 - Math.max(0, latencyMs as number) / 10);
-}
-
-/**
- * 将输出吞吐（tokens/s）转换为 0-100 分数。
- * 公式：直接取值并限制在 0-100 范围内
- *
- * 设计理由：
- * - 假设大多数 seller 的吞吐在 0-100 tok/s 范围内
- * - 100 tok/s 及以上都得满分（上界问题）
- * - 这种线性映射的局限：无法区分 100 tok/s 和 200 tok/s 的差异
- *   未来可考虑对数缩放，例如 `100 * log(1 + value) / log(101)`
- *
- * @param value 吞吐（tokens/s），undefined 或非有限值返回 0 分
- * @returns 0-100 分数
- */
-function tokensPerSecondScore(value: number | undefined): number {
-  if (!Number.isFinite(value)) {
-    return 0;
-  }
-  return Math.max(0, Math.min(100, value as number));
-}
-
-function discountScore(discountRatio: number | undefined): number {
-  if (!Number.isFinite(discountRatio)) {
-    return 0;
-  }
-  return Math.max(0, 100 * (1 - Math.max(0, discountRatio as number)));
-}
-
-function finiteOr(value: number | undefined, fallback: number): number {
-  return Number.isFinite(value) ? value as number : fallback;
-}
-
-function compareFiniteAsc(a: number | undefined, b: number | undefined): number {
-  return finiteOr(a, Number.POSITIVE_INFINITY) - finiteOr(b, Number.POSITIVE_INFINITY);
-}
-
-function compareFiniteDesc(a: number | undefined, b: number | undefined): number {
-  return finiteOr(b, Number.NEGATIVE_INFINITY) - finiteOr(a, Number.NEGATIVE_INFINITY);
-}
-
-function effectiveTtftMs(candidate: RoutingCandidate): number | undefined {
-  return candidate.ttftMs ?? candidate.healthProbeLatencyMs ?? candidate.avgLatencyMs;
-}
-
-function compareRegistryOrder(a: RoutingCandidate, b: RoutingCandidate): number {
-  return a.registryOrder - b.registryOrder;
-}
-
-function routeReason(mode: SellerRoutingMode, scorer: SellerRoutingScorer, count: number): string {
-  return `${mode}:${scorer}:routes_${count}`;
-}
-
-function missingScoreInputs(candidate: RoutingCandidate): CandidateScoreBreakdown["missingInputs"] {
-  const missing: CandidateScoreBreakdown["missingInputs"] = [];
-  if (!Number.isFinite(candidate.healthScore)) missing.push("healthScore");
-  if (!Number.isFinite(candidate.ttftMs)) missing.push("ttftMs");
-  if (!Number.isFinite(candidate.avgTokensPerSecond)) missing.push("avgTokensPerSecond");
-  if (!Number.isFinite(candidate.discountRatio)) missing.push("discountRatio");
-  return missing;
-}