@tokenbuddy/tokenbuddy 1.0.16 → 1.0.18

package/src/daemon.ts

@@ -33,6 +33,7 @@ import {
   manifestModelIds,
   manifestPaymentMethods,
   manifestProtocols,
+  isBuyerVisibleRegistrySeller,
   normalizeSellerUrl,
   RegistryTooLargeError,
   type RegistrySeller,
@@ -56,6 +57,16 @@ import {
   ROUTING_CONFIG_KEY,
   type BuyerSellerRoutingConfig
 } from "./seller-routing-config.js";
+import {
+  assertInitSetupSteps,
+  buildCompletedInitSetupMarker,
+  INIT_SETUP_CONFIG_KEY,
+  INIT_SETUP_STEPS,
+  type InitSetupMarker,
+  isFreshInitMachine,
+  normalizeInitSetupMarker,
+  resolveInitRecommendedModels,
+} from "./init-setup.js";
 
 const logger = createModuleLogger("tb-proxyd");
 const FOCUS_SET_CONFIG_KEY = "focus-set";
@@ -99,6 +110,31 @@ interface ClientToolStatus {
   };
 }
 
+type InitDoctorCheckStatus = "passed" | "warning" | "failed" | "skipped";
+type InitDoctorStatus = "passed" | "warning" | "failed";
+
+interface InitDoctorCheck {
+  id: string;
+  label: string;
+  status: InitDoctorCheckStatus;
+  message: string;
+  details: string[];
+}
+
+interface InitDoctorReport {
+  status: InitDoctorStatus;
+  generatedAt: string;
+  checks: InitDoctorCheck[];
+}
+
+interface InitDoctorCatalogSnapshot {
+  available: boolean;
+  models: Array<{ id: string; sellerId: string; sellerName?: string; sellerUrl: string; supportedProtocols: string[]; paymentMethods: string[] }>;
+  sellers: Array<{ id: string; name?: string; url: string; status: string; manifestSellerId?: string; errorMessage?: string }>;
+  source: "live" | "cached" | "unavailable";
+  errorMessage?: string;
+}
+
 function clientToolStatusFromProvider(provider: ProviderCandidate): ClientToolStatus {
   return {
     id: provider.id,
@@ -192,6 +228,8 @@ export interface DaemonConfig {
    * 缺省时由 BuyerStore 历史模型使用情况 + `TB_BUYER_WARMUP_MODELS` env 推导。
    */
   warmupModels?: string[];
+  /** Web init wizard recommended model ids. Env override: TB_PROXYD_INIT_RECOMMENDED_MODELS. */
+  initRecommendedModels?: string[];
   /** 预热模型目录刷新间隔（秒） */
   warmupRefreshIntervalSecs?: number;
   /** 预热探测超时（毫秒） */
@@ -843,6 +881,229 @@ export class TokenbuddyDaemon {
     };
   }
 
+  private livePayments(): PaymentConfig[] {
+    return this.tokenStore.listPayments().map((payment) => withLiveClawtipWalletState(payment, this.config.clawtipHomeDir));
+  }
+
+  private clientToolsSummary(): { clients: ClientToolStatus[]; summary: { configuredCount: number; detectedCount: number; totalCount: number; installCommand: string } } {
+    const providerStatuses = detectProviders({ home: this.config.providerHomeDir }).map(clientToolStatusFromProvider);
+    const clients = [
+      ...providerStatuses,
+      buildCustomClientToolStatus(this.activeProxyPort()),
+    ];
+    const configuredCount = clients.filter((client) => client.configured).length;
+    const detectedCount = clients.filter((client) => client.detected && client.status !== "manual").length;
+    return {
+      clients,
+      summary: {
+        configuredCount,
+        detectedCount,
+        totalCount: clients.length,
+        installCommand: "tb init"
+      }
+    };
+  }
+
+  private initRepairStatus(input: {
+    setup: InitSetupMarker;
+    payments: PaymentConfig[];
+    clientsSummary: { configuredCount: number };
+    focusSet: string[];
+  }): { repairMode: boolean; repairReasons: string[] } {
+    if (input.setup.status !== "completed") {
+      return { repairMode: false, repairReasons: [] };
+    }
+    const completedSteps = new Set(input.setup.completedSteps);
+    const missingSteps = INIT_SETUP_STEPS.filter((step) => !completedSteps.has(step));
+    const repairReasons: string[] = [];
+    if (missingSteps.length > 0) {
+      repairReasons.push(`missing_steps:${missingSteps.join(",")}`);
+    }
+    if (input.focusSet.length === 0) {
+      repairReasons.push("missing_focus_models");
+    }
+    if (!input.payments.some((payment) => payment.enabled)) {
+      repairReasons.push("missing_payment_method");
+    }
+    if (input.clientsSummary.configuredCount === 0) {
+      repairReasons.push("missing_connected_tools");
+    }
+    return {
+      repairMode: repairReasons.length > 0,
+      repairReasons,
+    };
+  }
+
+  private initStateSnapshot() {
+    const record = this.tokenStore.getDaemonRuntimeConfig<unknown>(INIT_SETUP_CONFIG_KEY);
+    const setup = normalizeInitSetupMarker(record?.config);
+    const storedRouting = this.tokenStore.getDaemonRuntimeConfig<unknown>(ROUTING_CONFIG_KEY)?.config;
+    const routingSource: "store" | "config" | "default" =
+      storedRouting !== undefined ? "store" : this.config.sellerRouting ? "config" : "default";
+    const clients = this.clientToolsSummary();
+    const payments = this.livePayments();
+    const focusSet = this.resolveFocusSet();
+    const recommendedModels = resolveInitRecommendedModels({
+      configuredModels: this.config.initRecommendedModels,
+      env: process.env,
+    });
+    const repair = this.initRepairStatus({
+      setup,
+      payments,
+      clientsSummary: clients.summary,
+      focusSet,
+    });
+    return {
+      setup: {
+        ...setup,
+        createdAt: record?.createdAt,
+        updatedAt: record?.updatedAt ?? setup.updatedAt,
+      },
+      freshMachine: isFreshInitMachine(setup),
+      repairMode: repair.repairMode,
+      repairReasons: repair.repairReasons,
+      runtime: this.runtimeSummary(),
+      payments,
+      clients: clients.clients,
+      clientsSummary: clients.summary,
+      routing: {
+        strategy: this.sellerRouting,
+        source: routingSource,
+      },
+      focusSet,
+      recommendedModels,
+    };
+  }
+
+  private async buildInitDoctorReport(): Promise<InitDoctorReport> {
+    const catalog = await this.initDoctorCatalogSnapshot();
+    const currentRouting = this.refreshSellerRoutingConfig();
+    const payments = this.livePayments().filter((payment) => payment.enabled);
+    const clients = this.clientToolsSummary();
+    const routeModelId = this.resolveFocusSet()[0] || catalog.models[0]?.id;
+    const routingPreview = routeModelId ? this.buildRoutingPreview({ modelId: routeModelId, routing: currentRouting }) : undefined;
+    const checks: InitDoctorCheck[] = [
+      {
+        id: "local_service",
+        label: "本地服务",
+        status: this.controlServer && this.proxyServer ? "passed" : "failed",
+        message: this.controlServer && this.proxyServer
+          ? "tb-proxyd 正在运行，控制面和代理端口已经打开。"
+          : "tb-proxyd 本地服务尚未完全启动。",
+        details: [
+          `控制面：http://127.0.0.1:${this.activeControlPort()}`,
+          `代理：http://127.0.0.1:${this.activeProxyPort()}`
+        ]
+      },
+      {
+        id: "proxy_interface",
+        label: "代理接口",
+        status: this.proxyServer ? "passed" : "failed",
+        message: this.proxyServer
+          ? "OpenAI 和 Anthropic 兼容本地接口已就绪。"
+          : "本地代理接口尚未就绪。",
+        details: [
+          `OpenAI 兼容 Base URL：http://127.0.0.1:${this.activeProxyPort()}/v1`,
+          `Anthropic 兼容 Base URL：http://127.0.0.1:${this.activeProxyPort()}`
+        ]
+      },
+      {
+        id: "seller_registry",
+        label: "供应商注册表",
+        status: catalog.available && catalog.sellers.length > 0 ? "passed" : "failed",
+        message: catalog.available && catalog.sellers.length > 0
+          ? `已加载 ${catalog.sellers.length} 个供应商。`
+          : "TokenBuddy 还没有可用供应商注册表。",
+        details: [
+          `来源：${formatInitDoctorCatalogSource(catalog.source)}`,
+          ...(catalog.errorMessage ? [catalog.errorMessage] : [])
+        ]
+      },
+      {
+        id: "model_catalog",
+        label: "模型目录",
+        status: catalog.available && catalog.models.length > 0 ? "passed" : "failed",
+        message: catalog.available && catalog.models.length > 0
+          ? `已发现 ${new Set(catalog.models.map((model) => model.id)).size} 个可用模型。`
+          : "TokenBuddy 还没有加载到供应商支持的模型。",
+        details: catalog.models.slice(0, 5).map((model) => model.id)
+      },
+      {
+        id: "routing_strategy",
+        label: "路由策略",
+        status: routingPreview && !("error" in routingPreview.plan) && routingPreview.plan.routes.length > 0 ? "passed" : "failed",
+        message: routingPreview && !("error" in routingPreview.plan) && routingPreview.plan.routes.length > 0
+          ? `当前策略可以为 ${routingPreview.modelId} 找到 ${routingPreview.plan.routes.length} 条供应商路径。`
+          : "当前模型和路由策略下没有可用供应商。",
+        details: routingPreview
+          ? ["error" in routingPreview.plan
+              ? `原因：${routingPreview.plan.error}`
+              : `策略：${routingPreview.plan.mode}:${routingPreview.plan.scorer}`]
+          : ["没有可用于路由验证的模型。"]
+      },
+      {
+        id: "payment_method",
+        label: "支付方式",
+        status: payments.length > 0 ? "passed" : "warning",
+        message: payments.length > 0
+          ? `已启用 ${payments.length} 个支付方式。`
+          : "尚未启用支付方式；自动购买会在绑定支付前暂停。",
+        details: payments.map((payment) => payment.method)
+      },
+      {
+        id: "connected_tools",
+        label: "已连接工具",
+        status: clients.summary.configuredCount > 0 ? "passed" : "warning",
+        message: clients.summary.configuredCount > 0
+          ? `已配置 ${clients.summary.configuredCount} 个 AI 工具。`
+          : "尚未检测到已接入 TokenBuddy 的 AI 工具。",
+        details: clients.clients
+          .filter((client) => client.configured)
+          .map((client) => client.name)
+      }
+    ];
+    const status: InitDoctorStatus = checks.some((check) => check.status === "failed")
+      ? "failed"
+      : checks.some((check) => check.status === "warning" || check.status === "skipped")
+        ? "warning"
+        : "passed";
+    return {
+      status,
+      generatedAt: new Date().toISOString(),
+      checks
+    };
+  }
+
+  private async initDoctorCatalogSnapshot(): Promise<InitDoctorCatalogSnapshot> {
+    try {
+      const catalog = await this.listSellerBackedModels();
+      return {
+        available: true,
+        models: catalog.models,
+        sellers: catalog.sellers,
+        source: "live"
+      };
+    } catch (error: unknown) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      if (this.lastRegistrySnapshot) {
+        const cached = catalogSnapshotFromRegistry(this.lastRegistrySnapshot);
+        return {
+          ...cached,
+          available: cached.sellers.length > 0,
+          source: "cached",
+          errorMessage
+        };
+      }
+      return {
+        available: false,
+        models: [],
+        sellers: [],
+        source: "unavailable",
+        errorMessage
+      };
+    }
+  }
+
   private endpointProtocol(endpoint: string): string | undefined {
     if (endpoint === "/v1/chat/completions") {
       return "chat_completions";
@@ -1273,6 +1534,7 @@ export class TokenbuddyDaemon {
     sellers: Array<{ id: string; name?: string; url: string; status: string; manifestSellerId?: string; errorMessage?: string }>;
   }> {
     const catalog = await discoverSellerBackedModels(this.config.sellerRegistryUrl);
+    this.lastRegistrySnapshot = sellerCatalogResultToRegistrySnapshot(catalog);
     return {
       models: catalog.models,
       sellers: catalog.sellers
@@ -2320,10 +2582,75 @@ export class TokenbuddyDaemon {
     controlApp.get("/payments", (req, res) => {
       logger.info("control.payments.requested", "control payments requested", {});
       res.status(200).json({
-        payments: this.tokenStore.listPayments().map((payment) => withLiveClawtipWalletState(payment, this.config.clawtipHomeDir))
+        payments: this.livePayments()
       });
     });
 
+    controlApp.get("/init/state", (req, res) => {
+      try {
+        const state = this.initStateSnapshot();
+        logger.info("init.state.requested", "init setup state requested", {
+          setupStatus: state.setup.status,
+          freshMachine: state.freshMachine,
+          configuredClientCount: state.clientsSummary.configuredCount,
+          paymentCount: state.payments.length
+        });
+        res.status(200).json(state);
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("init.state.failed", "init setup state failed", { errorMessage });
+        res.status(500).json({
+          error: {
+            code: "init_state_failed",
+            message: errorMessage
+          }
+        });
+      }
+    });
+
+    controlApp.post("/init/complete", (req, res) => {
+      try {
+        const completedSteps = assertInitSetupSteps(req.body?.completedSteps);
+        const setup = buildCompletedInitSetupMarker(completedSteps);
+        this.tokenStore.saveDaemonRuntimeConfig(INIT_SETUP_CONFIG_KEY, setup);
+        const state = this.initStateSnapshot();
+        logger.info("init.setup.completed", "init setup marker completed", {
+          completedStepCount: setup.completedSteps.length
+        });
+        res.status(200).json(state);
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("init.setup.complete_failed", "init setup complete failed", { errorMessage });
+        res.status(400).json({
+          error: {
+            code: "init_setup_complete_failed",
+            message: errorMessage
+          }
+        });
+      }
+    });
+
+    controlApp.post("/init/doctor/run", async (_req, res) => {
+      try {
+        const report = await this.buildInitDoctorReport();
+        logger.info("init.doctor.completed", "init doctor completed", {
+          status: report.status,
+          failedCount: report.checks.filter((check) => check.status === "failed").length,
+          warningCount: report.checks.filter((check) => check.status === "warning").length
+        });
+        res.status(200).json(report);
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("init.doctor.failed", "init doctor failed", { errorMessage });
+        res.status(500).json({
+          error: {
+            code: "init_doctor_failed",
+            message: errorMessage
+          }
+        });
+      }
+    });
+
     controlApp.post("/payments/clawtip/activate", async (req, res) => {
       try {
         const qr = await this.startClawtipActivationQr();
@@ -2499,27 +2826,13 @@ export class TokenbuddyDaemon {
 
     controlApp.get("/providers/status", (_req, res) => {
       try {
-        const providerStatuses = detectProviders({ home: this.config.providerHomeDir }).map(clientToolStatusFromProvider);
-        const clients = [
-          ...providerStatuses,
-          buildCustomClientToolStatus(this.activeProxyPort()),
-        ];
-        const configuredCount = clients.filter((client) => client.configured).length;
-        const detectedCount = clients.filter((client) => client.detected && client.status !== "manual").length;
+        const status = this.clientToolsSummary();
         logger.info("provider.status.requested", "provider status requested", {
-          clientCount: clients.length,
-          configuredCount,
-          detectedCount
-        });
-        res.status(200).json({
-          clients,
-          summary: {
-            configuredCount,
-            detectedCount,
-            totalCount: clients.length,
-            installCommand: "tb init"
-          }
+          clientCount: status.clients.length,
+          configuredCount: status.summary.configuredCount,
+          detectedCount: status.summary.detectedCount
         });
+        res.status(200).json(status);
       } catch (error: unknown) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         logger.warn("provider.status.failed", "provider status failed", { errorMessage });
@@ -3098,6 +3411,58 @@ function routingKey(routing: BuyerSellerRoutingConfig): string {
   ].join("\u0001");
 }
 
+function formatInitDoctorCatalogSource(source: InitDoctorCatalogSnapshot["source"]): string {
+  if (source === "live") {
+    return "实时注册表";
+  }
+  if (source === "cached") {
+    return "本机缓存";
+  }
+  return "不可用";
+}
+
+function sellerCatalogResultToRegistrySnapshot(catalog: Awaited<ReturnType<typeof discoverSellerBackedModels>>): SellerRegistryDocument {
+  return {
+    version: catalog.version,
+    defaultSeller: catalog.defaultSeller,
+    sellers: catalog.sellers
+      .filter((seller) => seller.status === "ok")
+      .map((seller) => ({
+        id: seller.id,
+        name: seller.name,
+        status: "active",
+        url: seller.url,
+        supportedProtocols: seller.supportedProtocols,
+        paymentMethods: seller.paymentMethods,
+        models: catalog.models
+          .filter((model) => model.sellerId === seller.id)
+          .map((model) => model.id)
+      }))
+  };
+}
+
+function catalogSnapshotFromRegistry(registry: SellerRegistryDocument): InitDoctorCatalogSnapshot {
+  const visibleSellers = registry.sellers.filter(isBuyerVisibleRegistrySeller);
+  return {
+    available: visibleSellers.length > 0,
+    source: "cached",
+    models: visibleSellers.flatMap((seller) => (seller.models ?? []).map((modelId) => ({
+      id: modelId,
+      sellerId: seller.id,
+      sellerName: seller.name,
+      sellerUrl: seller.url,
+      supportedProtocols: seller.supportedProtocols ?? [],
+      paymentMethods: seller.paymentMethods ?? []
+    }))),
+    sellers: visibleSellers.map((seller) => ({
+      id: seller.id,
+      name: seller.name,
+      url: seller.url,
+      status: seller.status ?? "active"
+    }))
+  };
+}
+
 /**
  * 从 query string 构造 `BuyerSellerRoutingConfig` override（用于 GET /routing/preview）。
  * 接受 `mode` / `scorer` / `sellerId` / `sellerIds`（逗号分隔）。

package/src/init-setup.ts

@@ -0,0 +1,165 @@
+export const INIT_SETUP_CONFIG_KEY = "init-setup";
+
+export const INIT_SETUP_VERSION = 1;
+
+export const INIT_SETUP_STEPS = [
+  "gateway_intro",
+  "model_access",
+  "supplier_routing",
+  "auto_purchase",
+  "connect_tools",
+  "verify_gateway",
+  "install_app",
+] as const;
+
+export const DEFAULT_INIT_RECOMMENDED_MODELS = [
+  "deepseek-v4-flash",
+  "kimi-2.6",
+  "gpt-5.5",
+  "gpt-5.4",
+  "claude-opus-4.7",
+  "claude-opus-4.8",
+  "claude-sonnet-4.6",
+  "gemma-4-26b-a4b-it",
+  "qwen3-235b-a22b",
+  "google/gemini-3.5-flash",
+  "google/gemini-3.1-pro-preview",
+  "qwen/qwen3.7-max",
+  "qwen/qwen3.7-plus",
+] as const;
+
+export type InitSetupStep = typeof INIT_SETUP_STEPS[number];
+export type InitSetupStatus = "not_started" | "in_progress" | "completed";
+
+export interface InitSetupMarker {
+  status: InitSetupStatus;
+  version: typeof INIT_SETUP_VERSION;
+  completedSteps: InitSetupStep[];
+  startedAt?: string;
+  updatedAt?: string;
+  completedAt?: string;
+}
+
+const INIT_SETUP_STEP_SET = new Set<string>(INIT_SETUP_STEPS);
+
+export function normalizeInitSetupMarker(value: unknown): InitSetupMarker {
+  if (!value || typeof value !== "object") {
+    return defaultInitSetupMarker();
+  }
+  const raw = value as {
+    status?: unknown;
+    completedSteps?: unknown;
+    startedAt?: unknown;
+    updatedAt?: unknown;
+    completedAt?: unknown;
+  };
+  const status = normalizeInitSetupStatus(raw.status);
+  return {
+    status,
+    version: INIT_SETUP_VERSION,
+    completedSteps: normalizeInitSetupSteps(raw.completedSteps),
+    startedAt: typeof raw.startedAt === "string" ? raw.startedAt : undefined,
+    updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : undefined,
+    completedAt: typeof raw.completedAt === "string" ? raw.completedAt : undefined,
+  };
+}
+
+export function buildInProgressInitSetupMarker(
+  previous: InitSetupMarker = defaultInitSetupMarker(),
+  now: Date = new Date(),
+): InitSetupMarker {
+  const updatedAt = now.toISOString();
+  return {
+    ...previous,
+    status: previous.status === "completed" ? "completed" : "in_progress",
+    version: INIT_SETUP_VERSION,
+    startedAt: previous.startedAt || updatedAt,
+    updatedAt,
+  };
+}
+
+export function buildCompletedInitSetupMarker(
+  completedSteps: readonly string[] = INIT_SETUP_STEPS,
+  now: Date = new Date(),
+): InitSetupMarker {
+  const normalizedSteps = normalizeInitSetupSteps(completedSteps);
+  const updatedAt = now.toISOString();
+  return {
+    status: "completed",
+    version: INIT_SETUP_VERSION,
+    completedSteps: normalizedSteps.length > 0 ? normalizedSteps : [...INIT_SETUP_STEPS],
+    startedAt: updatedAt,
+    updatedAt,
+    completedAt: updatedAt,
+  };
+}
+
+export function assertInitSetupSteps(value: unknown): InitSetupStep[] {
+  if (value === undefined) {
+    return [...INIT_SETUP_STEPS];
+  }
+  if (!Array.isArray(value)) {
+    throw new Error("completedSteps must be an array");
+  }
+  const steps: InitSetupStep[] = [];
+  for (const entry of value) {
+    if (typeof entry !== "string" || !INIT_SETUP_STEP_SET.has(entry)) {
+      throw new Error(`unknown init setup step: ${String(entry)}`);
+    }
+    if (!steps.includes(entry as InitSetupStep)) {
+      steps.push(entry as InitSetupStep);
+    }
+  }
+  return steps;
+}
+
+export function isFreshInitMachine(marker: InitSetupMarker): boolean {
+  return marker.status !== "completed";
+}
+
+export function normalizeInitRecommendedModels(value: readonly string[] | string | undefined): string[] {
+  const entries = typeof value === "string"
+    ? value.split(",")
+    : value ?? [];
+  return Array.from(new Set(entries.map((entry) => entry.trim()).filter(Boolean)));
+}
+
+export function resolveInitRecommendedModels(input?: {
+  configuredModels?: readonly string[];
+  env?: Record<string, string | undefined>;
+}): string[] {
+  const configured = normalizeInitRecommendedModels(input?.configuredModels);
+  if (configured.length > 0) {
+    return configured;
+  }
+  const envModels = normalizeInitRecommendedModels(input?.env?.TB_PROXYD_INIT_RECOMMENDED_MODELS);
+  if (envModels.length > 0) {
+    return envModels;
+  }
+  return [...DEFAULT_INIT_RECOMMENDED_MODELS];
+}
+
+function defaultInitSetupMarker(): InitSetupMarker {
+  return {
+    status: "not_started",
+    version: INIT_SETUP_VERSION,
+    completedSteps: [],
+  };
+}
+
+function normalizeInitSetupStatus(value: unknown): InitSetupStatus {
+  return value === "in_progress" || value === "completed" ? value : "not_started";
+}
+
+function normalizeInitSetupSteps(value: unknown): InitSetupStep[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const steps: InitSetupStep[] = [];
+  for (const entry of value) {
+    if (typeof entry === "string" && INIT_SETUP_STEP_SET.has(entry) && !steps.includes(entry as InitSetupStep)) {
+      steps.push(entry as InitSetupStep);
+    }
+  }
+  return steps;
+}