@tokenbuddy/tokenbuddy 1.0.11 → 1.0.13

package/src/cli.ts

@@ -3,7 +3,7 @@ import * as p from "@clack/prompts";
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
-import { execSync, spawn } from "child_process";
+import { execFileSync, spawn } from "child_process";
 import Table from "cli-table3";
 import { BuyerStore, PaymentConfig } from "./buyer-store.js";
 import {
@@ -25,8 +25,16 @@ import {
   filterCatalogBySeller,
   type ModelCatalogEntry,
   type SellerCatalogResult,
-  type SellerRoutingPreference,
 } from "./seller-catalog.js";
+import {
+  assertSellerRoutingConfig,
+  defaultSellerRoutingConfig,
+  normalizeSellerRoutingConfig,
+  parseSellerIdList,
+  ROUTING_CONFIG_KEY,
+  type BuyerSellerRoutingConfig,
+} from "./seller-routing-config.js";
+import type { SellerRoutingMode, SellerRoutingScorer } from "./seller-routing-strategy.js";
 import {
   collectDoctorDiagnostics,
   collectDoctorModelsSummary,
@@ -60,6 +68,11 @@ import qrcode from "qrcode-terminal";
 
 const CONTROL_PORT = 17820;
 const PROXY_PORT = 17821;
+const TOKENBUDDY_LAUNCHD_LABEL = "com.tokenbuddy.proxyd";
+const STALE_TOKENBUDDY_LAUNCHD_LABELS = [
+  "com.tokenbuddy.tb-proxyd",
+  "homebrew.mxcl.tokenbuddy",
+] as const;
 const logger = createModuleLogger("tokenbuddy-cli");
 const SUPPORTED_PAYMENT_METHODS = ["mock", "clawtip"] as const;
 type SupportedPaymentMethod = typeof SUPPORTED_PAYMENT_METHODS[number];
@@ -208,6 +221,107 @@ function tbProxydScriptPath(): string {
   return path.resolve(currentModuleDir(), "./tb-proxyd.js");
 }
 
+/**
+ * `buildLaunchdPlistContent` 的输入。
+ * 用于生成 macOS launchd plist，把 `tb-proxyd` 注册成 LaunchAgent。
+ */
+export interface LaunchdPlistOptions {
+  label: string;
+  nodePath: string;
+  scriptPath: string;
+  stdoutPath: string;
+  stderrPath: string;
+  controlPort: number;
+  proxyPort: number;
+  sellerRegistryUrl: string;
+  clawtipProofCommand?: string;
+  clawtipProofTimeoutMs?: number;
+}
+
+function escapeXmlText(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * 构造 macOS launchd plist 的 XML 文本，用于 `launchctl load` 注册 `tb-proxyd`。
+ * 已转义所有插值字段，避免 XML 注入；env 块只输出非空项。
+ *
+ * @param options plist 字段
+ * @returns 完整的 plist XML 字符串
+ */
+export function buildLaunchdPlistContent(options: LaunchdPlistOptions): string {
+  const env: Record<string, string> = {
+    TB_PROXYD_CONTROL_PORT: String(options.controlPort),
+    TB_PROXYD_PROXY_PORT: String(options.proxyPort),
+    TB_PROXYD_SELLER_REGISTRY_URL: options.sellerRegistryUrl,
+  };
+  if (options.clawtipProofCommand?.trim()) {
+    env.TB_PROXYD_CLAWTIP_PROOF_COMMAND = options.clawtipProofCommand.trim();
+  }
+  if (options.clawtipProofTimeoutMs !== undefined) {
+    env.TB_PROXYD_CLAWTIP_PROOF_TIMEOUT_MS = String(options.clawtipProofTimeoutMs);
+  }
+  const envEntries = Object.entries(env)
+    .map(([key, value]) => `        <key>${escapeXmlText(key)}</key>\n        <string>${escapeXmlText(value)}</string>`)
+    .join("\n");
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${escapeXmlText(options.label)}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${escapeXmlText(options.nodePath)}</string>
+        <string>${escapeXmlText(options.scriptPath)}</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+${envEntries}
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>${escapeXmlText(options.stdoutPath)}</string>
+    <key>StandardErrorPath</key>
+    <string>${escapeXmlText(options.stderrPath)}</string>
+</dict>
+</plist>`;
+}
+
+function launchdUserDomain(): string {
+  if (typeof process.getuid === "function") {
+    return `gui/${process.getuid()}`;
+  }
+  return "gui/501";
+}
+
+function runLaunchctl(args: string[], ignoreFailure = false): void {
+  try {
+    execFileSync("launchctl", args, { stdio: "ignore" });
+  } catch (error) {
+    if (!ignoreFailure) {
+      throw error;
+    }
+  }
+}
+
+function installLaunchAgent(plistPath: string, label: string): void {
+  const domain = launchdUserDomain();
+  for (const staleLabel of STALE_TOKENBUDDY_LAUNCHD_LABELS) {
+    runLaunchctl(["bootout", `${domain}/${staleLabel}`], true);
+  }
+  runLaunchctl(["bootout", `${domain}/${label}`], true);
+  runLaunchctl(["bootstrap", domain, plistPath]);
+  runLaunchctl(["kickstart", "-k", `${domain}/${label}`]);
+}
+
 async function repairDaemon(controlPort: number): Promise<{ repair: DaemonRepairResult; probe: DaemonProbeResult }> {
   const existing = await probeDaemonStatus(controlPort);
   if (existing.running) {
@@ -272,7 +386,7 @@ function rootActionName(command: Command): string {
 
 function commandRequiresDaemon(command: Command): boolean {
   const rootName = rootActionName(command);
-  return rootName !== "doctor" && rootName !== "init";
+  return rootName !== "doctor" && rootName !== "init" && rootName !== "routing";
 }
 
 async function enforceDaemonGate(command: Command): Promise<void> {
@@ -358,6 +472,14 @@ function printPaymentList(payments: PaymentConfig[], asJson: boolean): void {
   console.log(table.toString());
 }
 
+/**
+ * 调 wallet-bootstrap 的 `/payments/clawtip/bootstrap` 端点，拿到激活支付参数。
+ * 校验：HTTP 200、订单字段齐全、`payTo` 不是占位符。
+ *
+ * @param bootstrapUrl wallet-bootstrap 服务 base URL
+ * @returns bootstrap 响应（含 `payment` 字段）
+ * @throws Error 任何校验失败
+ */
 export async function fetchClawtipBootstrap(bootstrapUrl: string): Promise<ClawtipBootstrapResponse> {
   const response = await fetch(`${bootstrapUrl.replace(/\/+$/, "")}/payments/clawtip/bootstrap`, {
     method: "POST",
@@ -384,6 +506,15 @@ export async function fetchClawtipBootstrap(bootstrapUrl: string): Promise<Clawt
   return body;
 }
 
+/**
+ * 修正 Clawtip bootstrap 返回的 `resourceUrl`。
+ * 早期 bootstrap 返回 `/registry/sellers` 这种占位 URL，把它替换成当前 bootstrap URL 的 path，
+ * 让 buyer 正确指向 wallet-bootstrap。
+ *
+ * @param bootstrapUrl wallet-bootstrap base URL
+ * @param resourceUrl bootstrap 响应中的 `resourceUrl` 字段
+ * @returns 修正后的 resource URL（无法解析时返回原值）
+ */
 export function normalizeClawtipBootstrapResourceUrl(bootstrapUrl: string, resourceUrl: string): string {
   try {
     const bootstrap = new URL(bootstrapUrl);
@@ -442,64 +573,160 @@ function stableModelChoices(models: ModelCatalogEntry[]): SelectOption[] {
   });
 }
 
-async function promptSellerRoutingPreference(catalog: SellerCatalogResult): Promise<SellerRoutingPreference> {
+async function promptSellerRoutingPreference(catalog: SellerCatalogResult): Promise<BuyerSellerRoutingConfig> {
   const healthySellers = catalog.sellers.filter((seller) => seller.status === "ok");
   const mode = await p.select({
     message: "Choose seller routing mode for tb-proxyd:",
     options: [
       {
-        value: "auto",
-        label: "Auto",
-        hint: "Automatically choose a compatible seller based on the requested model.",
+        value: "fullAuto",
+        label: "Full Auto",
+        hint: "Use all compatible sellers and rank them by the selected scorer.",
       },
       {
         value: "fixed",
         label: "Fixed Seller",
         hint: "Pin tb-proxyd to one seller and only use models from that seller.",
       },
+      {
+        value: "fixedSet",
+        label: "Fixed Seller Set",
+        hint: "Use only a selected seller pool and rank within that pool.",
+      },
     ],
-  }) as SellerRoutingPreference["mode"] | symbol;
+  }) as SellerRoutingMode | symbol;
 
   if (typeof mode !== "string") {
     throw new Error("seller routing selection was cancelled");
   }
-  if (mode === "auto") {
-    return { mode };
-  }
-
-  if (healthySellers.length === 0) {
+  if ((mode === "fixed" || mode === "fixedSet") && healthySellers.length === 0) {
     throw new Error("no healthy sellers available for fixed routing");
   }
+  const scorer = await promptSellerRoutingScorer();
+  if (mode === "fullAuto") {
+    return { mode, scorer };
+  }
 
-  const sellerId = await p.select({
+  if (mode === "fixed") {
+    const sellerId = await p.select({
     message: "Choose the seller to pin tb-proxyd to:",
-    options: healthySellers.map((seller) => ({
-      value: seller.id,
-      label: seller.name ? `${seller.name} (${seller.id})` : seller.id,
-      hint: [
-        seller.discountRatio != null ? `discount x${seller.discountRatio}` : null,
-        seller.modelCount != null ? `${seller.modelCount} models` : null,
-        seller.supportedProtocols?.length ? seller.supportedProtocols.join(",") : null,
-        seller.paymentMethods?.length ? seller.paymentMethods.join(",") : null,
-      ]
-        .filter(Boolean)
-        .join(" · ") || seller.url,
-    })),
-  }) as string | symbol;
+      options: sellerChoices(healthySellers),
+    }) as string | symbol;
 
-  if (typeof sellerId !== "string") {
-    throw new Error("fixed seller selection was cancelled");
+    if (typeof sellerId !== "string") {
+      throw new Error("fixed seller selection was cancelled");
+    }
+    return {
+      mode,
+      sellerId,
+      scorer,
+    };
+  }
+
+  const sellerIds = await p.multiselect({
+    message: "Choose the seller pool for fixedSet routing:",
+    options: sellerChoices(healthySellers),
+    required: true
+  }) as string[] | symbol;
+
+  if (!Array.isArray(sellerIds)) {
+    throw new Error("fixedSet seller selection was cancelled");
   }
   return {
     mode,
-    sellerId,
+    sellerIds,
+    scorer,
   };
 }
 
+async function promptSellerRoutingScorer(): Promise<SellerRoutingScorer> {
+  const scorer = await p.select({
+    message: "Choose seller ranking preference:",
+    options: [
+      { value: "balanced", label: "Balanced", hint: "Balance health, latency, and discount." },
+      { value: "speed", label: "Speed", hint: "Prefer healthier, faster sellers." },
+      { value: "discount", label: "Discount", hint: "Prefer lower discount ratio first." },
+    ],
+  }) as SellerRoutingScorer | symbol;
+  if (typeof scorer !== "string") {
+    throw new Error("seller scorer selection was cancelled");
+  }
+  return scorer;
+}
+
+function sellerChoices(sellers: SellerCatalogResult["sellers"]): SelectOption[] {
+  return sellers.map((seller) => ({
+    value: seller.id,
+    label: seller.name ? `${seller.name} (${seller.id})` : seller.id,
+    hint: [
+      seller.discountRatio != null ? `discount x${seller.discountRatio}` : null,
+      seller.modelCount != null ? `${seller.modelCount} models` : null,
+      seller.supportedProtocols?.length ? seller.supportedProtocols.join(",") : null,
+      seller.paymentMethods?.length ? seller.paymentMethods.join(",") : null,
+    ]
+      .filter(Boolean)
+      .join(" · ") || seller.url,
+  }));
+}
+
+function buildRoutingConfigFromOptions(
+  modeValue: string,
+  options: { seller?: string; sellerSet?: string; scorer?: string }
+): BuyerSellerRoutingConfig {
+  const mode = parseRoutingModeValue(modeValue);
+  const scorer = parseRoutingScorerValue(options.scorer || "balanced");
+  if (mode === "fixed") {
+    return {
+      mode,
+      sellerId: options.seller?.trim(),
+      scorer
+    };
+  }
+  if (mode === "fixedSet") {
+    return {
+      mode,
+      sellerIds: parseSellerIdList(options.sellerSet || ""),
+      scorer
+    };
+  }
+  return {
+    mode,
+    scorer
+  };
+}
+
+function parseRoutingModeValue(value: string): SellerRoutingMode {
+  if (value === "fixed" || value === "fixedSet" || value === "fullAuto") {
+    return value;
+  }
+  throw new Error("routing mode must be fixed, fixedSet, or fullAuto");
+}
+
+function parseRoutingScorerValue(value: string): SellerRoutingScorer {
+  if (value === "balanced" || value === "speed" || value === "discount") {
+    return value;
+  }
+  throw new Error("routing scorer must be balanced, speed, or discount");
+}
+
+function printRoutingConfig(config: BuyerSellerRoutingConfig, updatedAt?: string): void {
+  console.log("=== TokenBuddy Seller Routing ===");
+  console.log(`Mode: ${config.mode}`);
+  console.log(`Scorer: ${config.scorer}`);
+  if (config.mode === "fixed") {
+    console.log(`Seller: ${config.sellerId || "(not configured)"}`);
+  }
+  if (config.mode === "fixedSet") {
+    console.log(`Seller Set: ${config.sellerIds?.join(",") || "(empty)"}`);
+  }
+  if (updatedAt) {
+    console.log(`Updated: ${updatedAt}`);
+  }
+}
+
 async function promptSingleModelSelection(
   providerId: ProviderId,
   models: ModelCatalogEntry[],
-  sellerRouting: SellerRoutingPreference,
 ): Promise<SingleModelProviderRuntimeConfig> {
   const protocolPreference = getProviderProtocolPreference(providerId);
   const protocolFiltered = protocolPreference
@@ -528,12 +755,10 @@ async function promptSingleModelSelection(
     throw new Error(`default model selection was cancelled for ${providerId}`);
   }
 
-  const selectedEntry = protocolFiltered.find((entry) => entry.id === selectedModel);
   return {
     selectionKind: "single-model",
     protocolPreference,
     defaultModel: selectedModel,
-    sellerId: sellerRouting.mode === "fixed" ? selectedEntry?.sellerId : undefined,
   };
 }
 
@@ -641,10 +866,12 @@ async function promptClaudeCodeModelSelection(
 async function promptProviderSelections(
   providerIds: ProviderId[],
   catalog: SellerCatalogResult,
-  sellerRouting: SellerRoutingPreference,
+  sellerRouting: BuyerSellerRoutingConfig,
 ): Promise<ProviderSelections> {
   const baseModels = sellerRouting.mode === "fixed"
     ? filterCatalogBySeller(catalog.models, sellerRouting.sellerId)
+    : sellerRouting.mode === "fixedSet"
+      ? catalog.models.filter((model) => sellerRouting.sellerIds?.includes(model.sellerId))
     : catalog.models;
 
   const selections: ProviderSelections = {};
@@ -657,12 +884,17 @@ async function promptProviderSelections(
     selections[providerId] = await promptSingleModelSelection(
       providerId,
       baseModels,
-      sellerRouting,
     );
   }
   return selections;
 }
 
+/**
+ * 构造 commander program，绑定所有 `tb` 子命令（doctor / init / config / provider 等）。
+ * 在 `preAction` 钩子里做 daemon gate：非 daemon-only 命令跳过，其余命令需要本地 `tb-proxyd` 在跑。
+ *
+ * @returns 配置完整的 commander Command 实例
+ */
 export function buildCli(): Command {
   const program = new Command();
   program
@@ -972,6 +1204,46 @@ export function buildCli(): Command {
       }
     });
 
+  // 3. tb routing
+  const routing = program.command("routing").description("Manage buyer-side seller routing strategy");
+
+  routing
+    .command("show")
+    .description("Show the configured seller routing strategy")
+    .option("--json", "Output routing config as JSON")
+    .action(async (options: { json?: boolean }) => {
+      const store = openBuyerStore();
+      try {
+        const record = store.getDaemonRuntimeConfig<unknown>(ROUTING_CONFIG_KEY);
+        const config = record ? normalizeSellerRoutingConfig(record.config) : defaultSellerRoutingConfig();
+        if (options.json) {
+          console.log(JSON.stringify({ routing: config, updatedAt: record?.updatedAt }, null, 2));
+          return;
+        }
+        printRoutingConfig(config, record?.updatedAt);
+      } finally {
+        store.close();
+      }
+    });
+
+  routing
+    .command("set <mode>")
+    .description("Set seller routing strategy: fullAuto, fixed, or fixedSet")
+    .option("--seller <id>", "Seller id for fixed routing")
+    .option("--seller-set <ids>", "Comma-separated seller ids for fixedSet routing")
+    .option("--scorer <scorer>", "Ranking scorer: balanced, speed, or discount", "balanced")
+    .action(async (mode: string, options: { seller?: string; sellerSet?: string; scorer?: string }) => {
+      const config = buildRoutingConfigFromOptions(mode, options);
+      assertSellerRoutingConfig(config);
+      const store = openBuyerStore();
+      try {
+        store.saveDaemonRuntimeConfig(ROUTING_CONFIG_KEY, config);
+      } finally {
+        store.close();
+      }
+      printRoutingConfig(config);
+    });
+
   // 3. tb models
   program
     .command("models")
@@ -1068,7 +1340,7 @@ export function buildCli(): Command {
 
         if (selectedProviders.length > 0) {
           spinner.start("Fetching seller-backed model catalog...");
-          const proxyUrl = `http://127.0.0.1:${PROXY_PORT}`;
+          const proxyUrl = `http://127.0.0.1:${configuredProxyPort()}`;
           const registryUrl = sellerRegistryUrlForInit();
           let catalog: SellerCatalogResult;
           try {
@@ -1100,11 +1372,11 @@ export function buildCli(): Command {
           spinner.start("Configuring proxy routing in selected terminals...");
           const store = openBuyerStore();
           try {
+            store.saveDaemonRuntimeConfig(ROUTING_CONFIG_KEY, sellerRouting);
             applyProviderInstall({
               providers: providerIds,
               proxyUrl,
               providerSelections,
-              sellerRouting,
             }, store);
           } finally {
             store.close();
@@ -1381,40 +1653,30 @@ export function buildCli(): Command {
             const plistDir = path.join(home, "Library", "LaunchAgents");
             if (!fs.existsSync(plistDir)) fs.mkdirSync(plistDir, { recursive: true });
 
-            const plistPath = path.join(plistDir, "com.tokenbuddy.proxyd.plist");
-            
-            // Resolve exact executable absolute path
-            const nodePath = execSync("which node", { encoding: "utf8" }).trim();
+            const plistPath = path.join(plistDir, `${TOKENBUDDY_LAUNCHD_LABEL}.plist`);
+            const controlPort = configuredControlPort();
+            const proxyPort = configuredProxyPort();
+            const sellerRegistryUrl = sellerRegistryUrlForInit();
+
+            const nodePath = process.execPath;
             const scriptPath = tbProxydScriptPath();
-            
-            const plistContent = `<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>Label</key>
-    <string>com.tokenbuddy.proxyd</string>
-    <key>ProgramArguments</key>
-    <array>
-        <string>${nodePath}</string>
-        <string>${scriptPath}</string>
-    </array>
-    <key>RunAtLoad</key>
-    <true/>
-    <key>KeepAlive</key>
-    <true/>
-    <key>StandardOutPath</key>
-    <string>${path.join(home, ".tokenbuddy-store", "tb-proxyd.stdout.log")}</string>
-    <key>StandardErrorPath</key>
-    <string>${path.join(home, ".tokenbuddy-store", "tb-proxyd.stderr.log")}</string>
-</dict>
-</plist>`;
+            const plistContent = buildLaunchdPlistContent({
+              label: TOKENBUDDY_LAUNCHD_LABEL,
+              nodePath,
+              scriptPath,
+              stdoutPath: path.join(home, ".tokenbuddy-store", "tb-proxyd.stdout.log"),
+              stderrPath: path.join(home, ".tokenbuddy-store", "tb-proxyd.stderr.log"),
+              controlPort,
+              proxyPort,
+              sellerRegistryUrl,
+              clawtipProofCommand: process.env.TB_PROXYD_CLAWTIP_PROOF_COMMAND,
+              clawtipProofTimeoutMs: process.env.TB_PROXYD_CLAWTIP_PROOF_TIMEOUT_MS
+                ? Number(process.env.TB_PROXYD_CLAWTIP_PROOF_TIMEOUT_MS)
+                : undefined,
+            });
             fs.writeFileSync(plistPath, plistContent, "utf8");
 
-            // Load the LaunchAgent
-            try {
-              execSync(`launchctl unload ${plistPath}`, { stdio: "ignore" });
-            } catch {}
-            execSync(`launchctl load ${plistPath}`);
+            installLaunchAgent(plistPath, TOKENBUDDY_LAUNCHD_LABEL);
             spinner.stop("LaunchAgent daemon successfully registered and started! 🚀");
             setupSummaryLines.push("Background tb-proxyd launchd service installed.");
           } catch (err: any) {

package/src/credit-tracker.ts

@@ -24,10 +24,17 @@ export const DEFAULT_FRESH_PURCHASE_THRESHOLD = 0.5;
  */
 export const DEFAULT_PURCHASE_BUDGET_PER_MINUTE = 3;
 
+/**
+ * `CreditTracker` 构造选项。
+ */
 export interface CreditTrackerOptions {
+  /** "新鲜购买" 判定窗口（毫秒），默认 30s */
   freshPurchaseWindowMs?: number;
+  /** "新鲜购买" 剩余比例阈值，默认 0.5（剩余 ≥ 50% 才算 fresh） */
   freshPurchaseThreshold?: number;
+  /** 单 session 每分钟自动购买上限，默认 3 */
   purchaseBudgetPerMinute?: number;
+  /** 时间源，默认 `Date.now`；测试可注入 */
   now?: () => number;
 }
 
@@ -51,6 +58,14 @@ interface SellerCredit {
  * The tracker is process-local: a buyer restart resets the session
  * counters. See §17.11.4 for the rationale.
  */
+/**
+ * buyer-driven-fallback 设计的"余额保护"决策器。
+ * 跟踪每个 seller 的余额、最近购买时间、累计浪费 micros，回答：
+ * - "该 seller 是否还在 fresh-purchase window 内？"
+ * - "本 session 是否还能自动购买？"
+ *
+ * 仅进程内状态（buyer 重启会重置 session 计数器；详见 §17.11.4）。
+ */
 export class CreditTracker {
   private readonly freshPurchaseWindowMs: number;
   private readonly freshPurchaseThreshold: number;
@@ -252,13 +267,24 @@ export class CreditTracker {
   }
 }
 
+/**
+ * `CreditTracker.summary()` 的返回结构，对应 design doc 的 "Credit Usage" 块。
+ * `tb doctor` 直接消费此结构展示给用户。
+ */
 export interface CreditSummary {
+  /** 自 tracker 创建以来累计浪费的 micros（含 failover 触发时的余额残留） */
   totalWastedMicros: number;
+  /** 上次 `resetDoctorRunCounter()` 之后又新产生的浪费 micros（doctor 显示 delta） */
   wastedSinceLastDoctorRun: number;
+  /** 过去 60 秒内自动购买次数 */
   purchasesInLastMinute: number;
+  /** 每分钟自动购买上限 */
   purchaseBudgetPerMinute: number;
+  /** 当前 fresh-purchase 窗口长度（毫秒） */
   freshPurchaseWindowMs: number;
+  /** 当前 fresh-purchase 比例阈值 */
   freshPurchaseThreshold: number;
+  /** 每个 seller 的余额快照 */
   perSeller: Array<{
     sellerId: string;
     currentBalanceMicros: number;