@tokenbuddy/tokenbuddy 1.0.11 → 1.0.13

package/src/prewarm-cache.ts

@@ -10,36 +10,96 @@ const logger = createModuleLogger("tb-proxyd:prewarm-cache");
  */
 export const DEFAULT_PREWARM_TTL_MS = 10 * 60 * 1000;
 
+/**
+ * 缓存条目的状态机。
+ * - `warming`：调度中，候选尚未稳定
+ * - `warm`：上次 commit 成功且 TTL 内
+ * - `stale`：TTL 过期或连续 commit 失败
+ * - `empty`：commit 返回 0 候选（该 (model, protocol, payment) 在当前 registry 下无 seller）
+ */
 export type PrewarmState = "warming" | "warm" | "stale" | "empty";
 
+/**
+ * 单个 seller 在某次 prewarm commit 后的健康画像。
+ * 由 `PrewarmCache.commitWarm()` 归一化字段（score 0-100、latency 非负）后写入。
+ */
 export interface PrewarmCandidate {
+  /** seller 全局 ID */
   sellerId: string;
+  /** 去掉尾部斜杠后的 seller URL */
   url: string;
+  /** 综合健康分，0-100，0 表示彻底坏 */
   healthScore: number;          // 0-100
+  /** 上一次成功的 unix 毫秒时间戳；0 表示尚无成功 */
   lastSuccessAt: number;
+  /** 上一次失败的 unix 毫秒时间戳；0 表示尚无失败 */
   lastFailAt: number;
+  /** 平均延迟（毫秒），用于排序时的回退指标 */
   avgLatencyMs: number;
+  /** health probe 的延迟（毫秒），可选 */
+  healthProbeLatencyMs?: number;
+  /** 首 token 延迟（毫秒），可选；speed 排序的优先指标 */
+  ttftMs?: number;
+  /** 平均推理延迟（毫秒），可选 */
+  avgInferenceMs?: number;
+  /** 上游状态（与 seller 上报的语义对齐） */
+  upstreamStatus?: "healthy" | "degraded" | "unhealthy" | "unknown";
+  /** 上游错误类名（HTTP status / 错误码），仅在失败时存在 */
+  upstreamErrorClass?: string;
 }
 
+/**
+ * 缓存条目：以 `(modelId, protocol, paymentMethod)` 为键，存储一组候选 seller 的健康画像。
+ * `warmedAt` 是 TTL 的起点；`consecutiveWarmingFailures` 触发指数退避。
+ */
 export interface PrewarmEntry {
+  /** 模型 ID（已归一化） */
   modelId: string;
+  /** 协议名（已归一化） */
   protocol: string;
+  /** 支付方式（已归一化） */
   paymentMethod: string;
+  /** 当前条目状态 */
   state: PrewarmState;
+  /** 该 (model, protocol, payment) 命中的候选 seller 列表 */
   candidates: PrewarmCandidate[];
+  /** 本次成功的 commit 时间戳，TTL 起点 */
   warmedAt: number;
+  /** 本条目的 TTL（毫秒），commit 时可被显式覆盖 */
   ttlMs: number;
+  /** 连续 warming 失败次数；医生面板据此判断"长期坏" */
   consecutiveWarmingFailures: number;
+  /** 最近一次进入 warming 的时间戳，调试用 */
   lastInFlightAt?: number;
 }
 
+/**
+ * 调度器在 commit 时传入的"原始"候选数据：所有字段都可空，
+ * 由 `toCandidate()` 做归一化（score clamp、latency 截负等）。
+ */
 export interface PrewarmCandidateInput {
+  /** seller ID */
   sellerId: string;
+  /** seller URL */
   url: string;
+  /** 健康分（可选；缺省在归一化时落到 50） */
   healthScore?: number;
+  /** 上次成功时间戳（毫秒），可选 */
   lastSuccessAt?: number;
+  /** 上次失败时间戳（毫秒），可选 */
   lastFailAt?: number;
+  /** 平均延迟（毫秒），可选 */
   avgLatencyMs?: number;
+  /** health probe 延迟（毫秒），可选 */
+  healthProbeLatencyMs?: number;
+  /** TTFT（毫秒），可选 */
+  ttftMs?: number;
+  /** 平均推理延迟（毫秒），可选 */
+  avgInferenceMs?: number;
+  /** 上游状态，可选 */
+  upstreamStatus?: "healthy" | "degraded" | "unhealthy" | "unknown";
+  /** 上游错误类名，可选 */
+  upstreamErrorClass?: string;
 }
 
 /**
@@ -69,6 +129,11 @@ interface PrewarmCacheOptions {
   now?: () => number;
 }
 
+/**
+ * 进程内的 (model, protocol, payment) → 候选 seller 健康画像缓存。
+ * 单线程访问（Node JS 主线程），无内部锁；`commitWarm` 是写路径，
+ * `get/freshness` 是热路径读，TTL 由 `warmedAt + ttlMs` 决定。
+ */
 export class PrewarmCache {
   private readonly entries = new Map<string, PrewarmEntry>();
   private readonly defaultTtlMs: number;
@@ -327,24 +392,48 @@ export class PrewarmCache {
   }
 }
 
+/**
+ * `PrewarmCache.freshness()` 的返回：一次"是否还能信任现有 prewarm"的快速判断。
+ * 在每条 inference 请求的热路径上使用，避免直接遍历缓存。
+ */
 export interface PrewarmFreshness {
+  /** 是否存在对应条目（false 等价于 cold path） */
   present: boolean;
+  /** 当前是否已超过 TTL */
   expired: boolean;
+  /** TTL 剩余 ≤ 10% 时视为"即将过期"，调度器用此触发 idle 预热 */
   expiringSoon: boolean;
+  /** 剩余 TTL（毫秒），过期时省略 */
   remainingMs?: number;
+  /** 条目当前状态（过期时强制为 `stale`） */
   state: PrewarmState;
+  /** 关联的缓存条目（如果有） */
   entry?: PrewarmEntry;
 }
 
+/**
+ * `PrewarmCache.beginWarming()` 的返回值：标记一次预热进入 in-flight。
+ * `hadPrevious` 用于上层决定是否在 `warming` 期间对外暴露旧候选。
+ */
 export interface PrewarmBeginResult {
+  /** 缓存键（与 `prewarmKey()` 的输出等价） */
   key: string;
+  /** 当前写回缓存的 entry（state=`warming`） */
   entry: PrewarmEntry;
+  /** 调用前缓存里是否已有 entry，用于上层做"保留旧候选"判断 */
   hadPrevious: boolean;
 }
 
+/**
+ * `PrewarmCache.commitWarm()` 的返回值：成功提交一次候选集合。
+ * `replacedSellers` 用于上层做候选 churn 检测。
+ */
 export interface PrewarmCommitResult {
+  /** 缓存键 */
   key: string;
+  /** 提交后的新 entry（state=`warm` 或 `empty`） */
   entry: PrewarmEntry;
+  /** 上一版 entry 的候选 seller 列表（已不再缓存的 seller ID） */
   replacedSellers: string[];
 }
 
@@ -355,10 +444,19 @@ function toCandidate(input: PrewarmCandidateInput): PrewarmCandidate {
     healthScore: clampScore(input.healthScore ?? 50),
     lastSuccessAt: input.lastSuccessAt ?? 0,
     lastFailAt: input.lastFailAt ?? 0,
-    avgLatencyMs: Math.max(0, input.avgLatencyMs ?? 0)
+    avgLatencyMs: Math.max(0, input.avgLatencyMs ?? 0),
+    healthProbeLatencyMs: finiteNonNegative(input.healthProbeLatencyMs),
+    ttftMs: finiteNonNegative(input.ttftMs),
+    avgInferenceMs: finiteNonNegative(input.avgInferenceMs),
+    upstreamStatus: input.upstreamStatus,
+    upstreamErrorClass: input.upstreamErrorClass
   };
 }
 
+function finiteNonNegative(value: number | undefined): number | undefined {
+  return Number.isFinite(value) ? Math.max(0, value as number) : undefined;
+}
+
 function clampScore(score: number): number {
   if (!Number.isFinite(score)) {
     return 50;

package/src/prewarm-scheduler.ts

@@ -5,45 +5,87 @@ import type { PrewarmCache, PrewarmCandidate } from "./prewarm-cache.js";
 
 const logger = createModuleLogger("tb-proxyd:prewarm-scheduler");
 
+/**
+ * 触发 prewarm 的原因，用于调度器决定并发与日志分组。
+ * - `startup`：daemon 启动时的批量预热，会受 startup jitter 影响
+ * - `lazy`：用户首次请求某 (model, protocol, payment) 时触发的预热
+ * - `idle`：后台 idle tick 触发的刷新
+ * - `explicit`：`tb doctor --prewarm` 之类的显式触发
+ */
 export type PrewarmReason = "startup" | "lazy" | "idle" | "explicit";
 
+/**
+ * 单次 health probe 的结果，由 `SellerProber` 返回。
+ * 调度器会基于 `ok` + `latencyMs` 推算 `healthScore`，并把 `upstreamStatus` 直接透传。
+ */
 export interface ProbeResult {
+  /** probe 是否成功（HTTP 2xx 且语义上代表"健康"） */
   ok: boolean;
+  /** probe 总耗时（毫秒），用于 healthScore 计算 */
   latencyMs: number;
+  /** HTTP status（如果 prober 能拿到） */
   httpStatus?: number;
+  /** 错误描述（仅当 `ok=false` 时存在，不携带敏感字段） */
   errorMessage?: string;
+  /** 上游报告的状态，与 health probe 端点或 fallback 推断的语义对齐 */
+  upstreamStatus?: "healthy" | "degraded" | "unhealthy" | "unknown";
+  /** 上游错误类名（status code / error code） */
+  upstreamErrorClass?: string;
+  /** 首 token 延迟（毫秒），可选；speed 排序时优先使用 */
+  ttftMs?: number;
+  /** 平均推理延迟（毫秒），可选 */
+  avgInferenceMs?: number;
 }
 
 /**
  * The probe function used by the scheduler. Decoupled so the scheduler can
  * be unit-tested without spinning up HTTP servers. The default
- * implementation in `health-probe.ts` (PR-2/PR-3) calls
- * `GET <seller.url>/healthz` with a 3s `AbortSignal.timeout`. Probers must
+ * implementation in `daemon.ts` calls `GET <seller.url>/health` with a 3s
+ * timeout. Probers must
  * observe the provided `AbortSignal` and reject when it aborts so the
  * scheduler can short-circuit in-flight probes on `stop()`.
  */
 export type SellerProber = (seller: RegistrySeller, signal: AbortSignal) => Promise<ProbeResult>;
 
+/**
+ * 构造 `PrewarmScheduler` 所需的依赖与可调参数。默认值见设计文档
+ * buyer-driven-fallback-design.md §18.5-§18.6：并发 4、per-seller 30s、
+ * 全局 30/min、startup jitter 5-10s。
+ */
 export interface PrewarmSchedulerOptions {
+  /** 共享的 model index，用于把 modelId 解析为 seller 列表 */
   modelIndex: ModelIndex;
+  /** 共享的 prewarm 缓存，调度器写入并由控制器读取 */
   cache: PrewarmCache;
+  /** 注入的 health prober，调度器不直接发 HTTP */
   prober: SellerProber;
   // Limits (defaults match buyer-driven-fallback-design.md §18.6).
+  /** 并发上限，默认 4 */
   concurrency?: number;
+  /** 同一 seller 两次 probe 之间的最小间隔（毫秒），默认 30000 */
   perSellerMinIntervalMs?: number;
+  /** 每分钟最多 probe 多少次（全局节流），默认 30 */
   maxPrewarmPerMinute?: number;
   // Idle loop cadence; the scheduler can also be driven externally
   // (PR-2.1 wires `tickIdle` into the existing registry-loop heartbeat).
+  /** idle 循环的间隔（毫秒），默认 60000 */
   idleIntervalMs?: number;
   // Startup jitter (5-10s by default per §18.5.1).
+  /** startup 抖动的下界（毫秒），默认 5000 */
   startupJitterMinMs?: number;
+  /** startup 抖动的上界（毫秒），默认 10000 */
   startupJitterMaxMs?: number;
   // Hooks for testing; defaults to Node's setTimeout / setImmediate.
+  /** 可注入的 sleep（支持 abort），默认 Node setTimeout */
   sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+  /** 可注入的随机源，默认 `Math.random` */
   random?: () => number;
+  /** 可注入的时钟，默认 `Date.now` */
   now?: () => number;
   // Optional filter applied to every probe (e.g. preferred protocol).
+  /** 全局默认协议 filter，可被 `schedulePrewarm` 覆盖 */
   protocol?: string;
+  /** 全局默认支付方式 filter，可被 `schedulePrewarm` 覆盖 */
   paymentMethod?: string;
 }
 
@@ -61,15 +103,28 @@ interface PrewarmTask {
   errorMessage?: string;
 }
 
+/**
+ * `PrewarmScheduler.stats()` 的返回：调度器当前的运行指标快照。
+ * `tb doctor` 据此判断调度是否过载、是否长期被限流。
+ */
 export interface PrewarmSchedulerStats {
+  /** 当前队列里尚未开始的 task 数 */
   queueDepth: number;
+  /** 正在 probe 的 task 数 */
   inFlight: number;
+  /** 累计入队的 task 数（包含 rate_limited） */
   totalScheduled: number;
+  /** 累计成功的 task 数 */
   totalSucceeded: number;
+  /** 累计失败的 task 数（所有候选 probe 都失败） */
   totalFailed: number;
+  /** 累计因全局节流被跳过的 task 数 */
   totalRateLimited: number;
+  /** 最近 60 秒内发起的 probe 总数（用于判断是否撞到 maxPrewarmPerMinute） */
   recentProbesInLastMinute: number;
+  /** 当前配置的并发上限 */
   concurrency: number;
+  /** 当前配置的每分钟 probe 上限 */
   maxPrewarmPerMinute: number;
 }
 
@@ -231,14 +286,15 @@ export class PrewarmScheduler {
    * the configured jitter window. Resolves once every scheduled task has
    * reached a terminal state.
    */
-  async runStartupPrewarm(modelIds: string[]): Promise<void> {
+  async runStartupPrewarm(inputs: Array<string | { modelId: string; protocol?: string; paymentMethod?: string }>): Promise<void> {
     await this.sleep(this.jitterMs(), this.abortController?.signal);
     if (this.abortController?.signal.aborted) {
       return;
     }
-    const tasks = modelIds.map((modelId) =>
-      this.schedulePrewarm({ modelId, reason: "startup" })
-    );
+    const tasks = inputs.map((input) => {
+      const task = typeof input === "string" ? { modelId: input } : input;
+      return this.schedulePrewarm({ ...task, reason: "startup" });
+    });
     await Promise.all(tasks);
   }
 
@@ -429,21 +485,32 @@ export class PrewarmScheduler {
       }
       this.lastProbeAtBySeller.set(seller.id, this.now());
       if (result.ok) {
-        anyOk = true;
+        const healthScore = scoreProbeResult(result);
+        anyOk = anyOk || healthScore > 0;
         candidates.push({
           sellerId: seller.id,
           url: seller.url,
-          healthScore: scoreFromLatency(result.latencyMs),
+          healthScore,
           lastSuccessAt: this.now(),
           lastFailAt: 0,
-          avgLatencyMs: result.latencyMs
+          avgLatencyMs: result.latencyMs,
+          healthProbeLatencyMs: result.latencyMs,
+          ttftMs: result.ttftMs,
+          avgInferenceMs: result.avgInferenceMs,
+          upstreamStatus: result.upstreamStatus,
+          upstreamErrorClass: result.upstreamErrorClass
         });
         logger.info("prewarm.succeeded", "seller probe succeeded", {
           taskId: task.id,
           sellerId: seller.id,
           modelId: task.modelId,
           latencyMs: result.latencyMs,
-          httpStatus: result.httpStatus
+          httpStatus: result.httpStatus,
+          healthScore,
+          upstreamStatus: result.upstreamStatus,
+          upstreamErrorClass: result.upstreamErrorClass,
+          ttftMs: result.ttftMs,
+          avgInferenceMs: result.avgInferenceMs
         });
       } else {
         candidates.push({
@@ -452,14 +519,21 @@ export class PrewarmScheduler {
           healthScore: 0,
           lastSuccessAt: 0,
           lastFailAt: this.now(),
-          avgLatencyMs: result.latencyMs
+          avgLatencyMs: result.latencyMs,
+          healthProbeLatencyMs: result.latencyMs,
+          ttftMs: result.ttftMs,
+          avgInferenceMs: result.avgInferenceMs,
+          upstreamStatus: result.upstreamStatus,
+          upstreamErrorClass: result.upstreamErrorClass
         });
         logger.warn("prewarm.failed", "seller probe failed", {
           taskId: task.id,
           sellerId: seller.id,
           modelId: task.modelId,
           errorMessage: result.errorMessage,
-          httpStatus: result.httpStatus
+          httpStatus: result.httpStatus,
+          upstreamStatus: result.upstreamStatus,
+          upstreamErrorClass: result.upstreamErrorClass
         });
       }
     }
@@ -579,3 +653,14 @@ function scoreFromLatency(latencyMs: number): number {
   if (latencyMs <= 3000) return 40;
   return 20;
 }
+
+function scoreProbeResult(result: ProbeResult): number {
+  if (result.upstreamStatus === "unhealthy") {
+    return 0;
+  }
+  const base = scoreFromLatency(result.latencyMs);
+  if (result.upstreamStatus === "degraded") {
+    return Math.min(base, 40);
+  }
+  return base;
+}