dsh-plugin-litellm-bridge 0.0.0-stage → 2.0.2

package/dsh-plugin-litellm-bridge/lib/gateway-client.js

@@ -0,0 +1,587 @@
+/**
+ * LiteLLM 网关 REST 客户端
+ * ============================================================================
+ *
+ * 【设计铁律】
+ *   本文件只做「通过 LiteLLM 官方 REST API 与网关通信」这一件事。
+ *   绝不实现路由、重试、降级、冷却、模型选择 —— 那些 100% 由网关负责。
+ *   这里没有 retry 循环，没有 fallback 链，没有模型优先级判断。
+ *
+ * 【密钥纪律】
+ *   master key 只存在于内存中的 config 对象里，来自网关侧 .env。
+ *   本模块绝不读取 .env，绝不把 key 写进日志或错误消息。
+ *   redact() 会把任何疑似密钥串替换成掩码后再对外暴露。
+ */
+
+const JSON_HEADERS = { 'Content-Type': 'application/json' };
+
+/** 把密钥从任意文本里抹掉，避免它出现在错误消息 / 日志里。 */
+export function redact(text, secret) {
+  let out = String(text ?? '');
+  if (secret && secret.length >= 8) {
+    out = out.split(secret).join('sk-***REDACTED***');
+  }
+  // 兜底：抹掉任何 sk- 开头的长串
+  return out.replace(/\b(sk-[A-Za-z0-9_\-]{8,})/g, 'sk-***REDACTED***');
+}
+
+/** 统一的「结果」形状，让 UI 永远拿到结构一致的对象而不是异常。 */
+function ok(data, extra = {}) {
+  return { ok: true, data, ...extra };
+}
+function fail(error, extra = {}) {
+  return { ok: false, error, ...extra };
+}
+
+export class GatewayClient {
+  /**
+   * 密钥用真正的私有字段（#），不是 `_apiKey` 约定：
+   *   - JSON.stringify(client) / console.log(client) / 展开运算符
+   *     都不会带出密钥；
+   *   - 只有类内部方法读得到。
+   * 这是「UI 绝不回显明文密钥」在代码层的硬保证，而不是靠自觉。
+   */
+  #apiKey = '';
+
+  /**
+   * @param {object} opts
+   * @param {string} opts.baseUrl  网关地址，如 http://127.0.0.1:4000
+   * @param {string} opts.apiKey   master admin key（来自 .env，仅存内存）
+   * @param {number} opts.timeoutMs
+   */
+  constructor({ baseUrl, apiKey, timeoutMs = 30000 } = {}) {
+    this.baseUrl = String(baseUrl || '').replace(/\/+$/, '');
+    this.#apiKey = apiKey || '';
+    this.timeoutMs = timeoutMs;
+    /** 探测到的可用热重载端点（缓存，避免每次保存都全量探测） */
+    this._reloadEndpoint = null;
+  }
+
+  update({ baseUrl, apiKey, timeoutMs } = {}) {
+    if (baseUrl !== undefined) this.baseUrl = String(baseUrl || '').replace(/\/+$/, '');
+    if (apiKey !== undefined) this.#apiKey = apiKey || '';
+    if (timeoutMs !== undefined) this.timeoutMs = timeoutMs;
+  }
+
+  /** 仅供类内部使用；外部拿不到明文。 */
+  get _secret() {
+    return this.#apiKey;
+  }
+
+  get configured() {
+    return Boolean(this.baseUrl);
+  }
+
+  /** master key 是否已从网关侧 .env 注入（只回答「有/没有」，绝不回显值）。 */
+  get hasKey() {
+    return Boolean(this.#apiKey);
+  }
+
+  _url(path) {
+    return `${this.baseUrl}${path}`;
+  }
+
+  async _fetch(path, { method = 'GET', body, headers = {}, auth = true, timeoutMs } = {}) {
+    if (!this.baseUrl) return fail('网关地址未配置');
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs ?? this.timeoutMs);
+    try {
+      const res = await fetch(this._url(path), {
+        method,
+        headers: {
+          ...JSON_HEADERS,
+          ...(auth && this.#apiKey ? { Authorization: `Bearer ${this.#apiKey}` } : {}),
+          ...headers,
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: ctrl.signal,
+      });
+      const text = await res.text();
+      let parsed;
+      try {
+        parsed = text ? JSON.parse(text) : null;
+      } catch {
+        parsed = text;
+      }
+      if (!res.ok) {
+        return fail(
+          redact(
+            `HTTP ${res.status} ${res.statusText}: ${
+              typeof parsed === 'string' ? parsed : JSON.stringify(parsed)
+            }`,
+            this.#apiKey,
+          ),
+          { status: res.status },
+        );
+      }
+      return ok(parsed, { status: res.status });
+    } catch (err) {
+      const msg = err?.name === 'AbortError' ? `请求超时（${timeoutMs ?? this.timeoutMs}ms）` : String(err?.message || err);
+      return fail(redact(msg, this.#apiKey));
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // 1. 连通性
+  // -------------------------------------------------------------------------
+
+  /**
+   * 测试连通性。分三层，逐层给出诊断，不把「服务活着」和「key 有效」混为一谈：
+   *   1) liveliness  进程活着吗（无需鉴权）
+   *   2) readiness   能接流量吗 + 数据库状态（无需鉴权）
+   *   3) /v1/models  master admin key 有效吗（需鉴权）
+   */
+  async testConnection() {
+    const steps = [];
+
+    const live = await this._fetch('/health/liveliness', { auth: false, timeoutMs: 10000 });
+    steps.push({
+      name: '网关存活',
+      path: '/health/liveliness',
+      ok: live.ok,
+      detail: live.ok ? String(live.data).slice(0, 80) : live.error,
+    });
+
+    const ready = await this._fetch('/health/readiness', { auth: false, timeoutMs: 10000 });
+    steps.push({
+      name: '网关就绪',
+      path: '/health/readiness',
+      ok: ready.ok,
+      detail: ready.ok
+        ? `db=${ready.data?.db ?? '未配置'}`
+        : ready.error,
+    });
+
+    let modelCount = null;
+    if (this.hasKey) {
+      const models = await this._fetch('/v1/models');
+      modelCount = models.ok ? (models.data?.data || []).length : null;
+      steps.push({
+        name: 'master admin key',
+        path: '/v1/models',
+        ok: models.ok,
+        detail: models.ok ? `可见 ${modelCount} 个模型` : models.error,
+      });
+    } else {
+      steps.push({
+        name: 'master admin key',
+        path: '/v1/models',
+        ok: false,
+        detail: '未检测到网关 master key（应在网关侧 .env 的 LITELLM_MASTER_KEY 中）',
+      });
+    }
+
+    const passed = steps.filter((s) => s.ok).length;
+    return {
+      ok: steps[0].ok && steps[1].ok && (this.hasKey ? steps[2].ok : false),
+      steps,
+      passed,
+      total: steps.length,
+      modelCount,
+      // 只报告「key 是否存在」，绝不回显
+      keySource: this.hasKey ? '来自 .env 环境变量' : '未配置',
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // 2. 模型清单（用于 UI 里挑首选/备选模型）
+  // -------------------------------------------------------------------------
+
+  /** GET /v1/models —— 公开的对外模型名列表。 */
+  async listModels() {
+    const res = await this._fetch('/v1/models');
+    if (!res.ok) return res;
+    const ids = (res.data?.data || []).map((m) => m?.id).filter(Boolean);
+    return ok(ids);
+  }
+
+  /** GET /v1/model/info —— 带元信息（上下文窗口等），部分版本才有。 */
+  async listModelInfo() {
+    const res = await this._fetch('/v1/model/info');
+    if (!res.ok) return res;
+    return ok(res.data?.data || []);
+  }
+
+  /**
+   * 【已废弃 · 架构修正】从网关拉取模型清单。
+   *
+   * 旧版用它给 UI 喂模型下拉（需求9）。架构修正后模型数据源改为
+   * **DSH【设置-模型】**（见 lib/model-pool.js），插件不再向网关索要模型，
+   * 该接口也随之从宿主半移除（models/sync 已删），否则 UI 一直报 404。
+   *
+   * 保留本方法仅为「排障时手工看看网关里到底注册了什么」——
+   * 它已不再是任何 UI 路径的数据源，也没有任何调用者，
+   * model-sync-batch.test.mjs 仍在验证它的解析逻辑（防止误改坏）。
+   */
+  async syncModels() {
+    const [infoRes, listRes] = await Promise.all([
+      this.listModelInfo(),
+      this.listModels(),
+    ]);
+
+    const byName = new Map();
+
+    // 1) 优先用 /v1/model/info 的丰富信息
+    if (infoRes.ok && Array.isArray(infoRes.data)) {
+      for (const d of infoRes.data) {
+        const name = d?.model_name || d?.model_info?.id;
+        if (!name) continue;
+        const p = d?.litellm_params || {};
+        const upstream = String(p.model || '');
+        byName.set(name, {
+          name,
+          upstream,
+          apiBase: p.api_base || null,
+          // 派生一个 "provider" 标签，UI 可分组显示
+          provider: guessProvider(upstream, p.api_base),
+          // 空模型名是明显的坏配置（${VAR} 未解析），标记出来让人看见
+          broken: !upstream || upstream === 'openai/' || /\/$/.test(upstream),
+          timeout: p.timeout ?? null,
+        });
+      }
+    }
+
+    // 2) 补齐 /v1/models 里有、info 里没有的
+    if (listRes.ok && Array.isArray(listRes.data)) {
+      for (const name of listRes.data) {
+        if (!byName.has(name)) {
+          byName.set(name, {
+            name, upstream: '', apiBase: null, provider: 'unknown', broken: false, timeout: null,
+          });
+        }
+      }
+    }
+
+    const models = [...byName.values()];
+    return ok({
+      models,
+      count: models.length,
+      // 供 UI 直接喂给 datalist
+      names: models.map((m) => m.name),
+      broken: models.filter((m) => m.broken).map((m) => m.name),
+      sources: {
+        modelInfo: infoRes.ok ? infoRes.data.length : null,
+        models: listRes.ok ? listRes.data.length : null,
+      },
+      error: infoRes.ok || listRes.ok ? null : infoRes.error || listRes.error,
+    });
+  }
+
+  /**
+   * 【需求10】批量连通性测试：对指定模型列表发起轻量探针。
+   *
+   * 默认并发 2、单模型超时 60s —— 这两个值来自实测，不是拍脑袋：
+   *   - 全串行 11 个模型要 398s（上游 agnes/zhipu 单次就要 20–90s）；
+   *   - 并发 3 + 30s 超时反而更糟：慢模型互相争抢，11 个里 7 个因超时误判失败，
+   *     还触发上游 429。
+   *   - 并发 2 + 60s 是「总时长可接受」与「不误判」的平衡点。
+   * 两者都可以由调用方（UI）覆盖，方便按自己的上游速度调。
+   *
+   * @param {object} opts
+   * @param {string[]} opts.models       要测的模型名列表
+   * @param {number} [opts.concurrency]  并发度（默认 2，上限 8）
+   * @param {number} [opts.timeoutMs]    单个模型超时（默认 60s）
+   * @param {(r:object)=>void} [opts.onResult] 每测完一个回调（UI 可增量渲染）
+   * @param {AbortSignal} [opts.signal]  供「停止」按钮中断
+   */
+  async probeBatch({
+    models = [],
+    agentType = 'root',
+    profile = 'profile-a',
+    concurrency = 2,
+    timeoutMs = 60000,
+    onResult,
+    signal,
+  } = {}) {
+    const results = [];
+    let aborted = false;
+    const width = Math.max(1, Math.min(8, Number(concurrency) || 2));
+    let cursor = 0;
+
+    const runOne = async (model) => {
+      const started = Date.now();
+      try {
+        const res = await this.probe({ model, agentType, profile, timeoutMs });
+        return res.ok
+          ? {
+              model, ok: true,
+              latencyMs: res.latencyMs ?? (Date.now() - started),
+              reply: String(res.data?.reply ?? '').slice(0, 80),
+              modelUsed: res.data?.modelUsed ?? model,
+              error: null,
+            }
+          : {
+              model, ok: false,
+              latencyMs: res.latencyMs ?? (Date.now() - started),
+              reply: null, modelUsed: null,
+              error: String(res.error || '未知错误'),
+            };
+      } catch (err) {
+        return {
+          model, ok: false, latencyMs: Date.now() - started,
+          reply: null, modelUsed: null, error: String(err?.message || err),
+        };
+      }
+    };
+
+    // 固定宽度的工作者池：每个 worker 不断取下一個模型，直到列表耗尽
+    const worker = async () => {
+      for (;;) {
+        if (signal?.aborted) { aborted = true; return; }
+        const idx = cursor++;
+        if (idx >= models.length) return;
+        const entry = await runOne(models[idx]);
+        results.push(entry);
+        try {
+          onResult?.(entry, results.length, models.length);
+        } catch {
+          /* UI 回调异常不影响后续测试 */
+        }
+      }
+    };
+
+    await Promise.all(Array.from({ length: Math.min(width, models.length) }, () => worker()));
+
+    // 结果按原始顺序排列，方便 UI 与清单对齐对照
+    const order = new Map(models.map((m, i) => [m, i]));
+    results.sort((a, b) => (order.get(a.model) ?? 0) - (order.get(b.model) ?? 0));
+
+    const passed = results.filter((r) => r.ok).length;
+    return ok({
+      results,
+      total: models.length,
+      passed,
+      failed: results.length - passed,
+      aborted,
+      concurrency: width,
+      finishedAt: new Date().toISOString(),
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // 3. 热重载
+  // -------------------------------------------------------------------------
+
+  /**
+   * 探测「本网关真正可用」的配置热重载端点。
+   *
+   * 实测事实（本机 litellm 1.108.3）：
+   *   - POST /config/reload   -> 404  该构建没有这条路由
+   *   - POST /reload/config   -> 404  同上
+   *   - POST /config/update   -> 400  "Authentication Error, No DB Connected"
+   *     路由存在，但**需要数据库**（store_model_in_db）。纯 config.yaml 模式下它不可用。
+   *
+   * 关键设计：不能只看「路由存在」就当可用。必须实际调一次、看是否真成功 ——
+   * 否则会把 400 当成「重载成功」，比直接报错更糟。
+   */
+  async detectReloadEndpoint() {
+    if (this._reloadEndpoint) return ok(this._reloadEndpoint);
+
+    const candidates = [
+      { method: 'POST', path: '/config/reload', label: '/config/reload' },
+      { method: 'POST', path: '/reload/config', label: '/reload/config' },
+      { method: 'POST', path: '/config/update', label: '/config/update (requires DB)' },
+    ];
+
+    const probed = [];
+    for (const c of candidates) {
+      const res = await this._fetch(c.path, { method: c.method, body: {}, timeoutMs: 15000 });
+      const notFound = res.status === 404 || res.status === 405 || res.status === undefined;
+      // 「路由存在」和「调用成功」是两件事：只有真的 2xx 才算可用。
+      const usable = Boolean(res.ok);
+      probed.push({
+        ...c,
+        status: res.status ?? 0,
+        exists: !notFound,
+        usable,
+        error: usable ? undefined : res.error,
+      });
+      if (usable) {
+        this._reloadEndpoint = c.path;
+        return ok({ endpoint: c.path, label: c.label, probed });
+      }
+    }
+    return ok({ endpoint: null, label: null, probed });
+  }
+
+  /**
+   * 调用热重载。返回真实结果；若网关没有可用端点则明确失败并给出手动方案，
+   * 绝不返回「成功」。
+   */
+  async reloadConfig() {
+    const detected = await this.detectReloadEndpoint();
+    const endpoint = detected.data?.endpoint;
+    if (!endpoint) {
+      const probed = detected.data?.probed || [];
+      // 区分两种失败：路由不存在 vs 路由存在但需要数据库
+      const needDb = probed.some((p) => p.exists && !p.usable && String(p.error || '').includes('DB'));
+      return fail(
+        needDb
+          ? '网关的 /config/update 存在，但需要数据库（store_model_in_db）才能写入配置；' +
+            '当前是纯 config.yaml 模式，无法热重载。请手动重启网关（./start-gateway.sh）以加载新配置。'
+          : '网关未提供可用的配置热重载端点。已探测 /config/reload、/reload/config、/config/update 均不可用。' +
+            '请手动重启网关（./start-gateway.sh）以加载新的 config.yaml。',
+        { probed, needsManualRestart: true },
+      );
+    }
+    const res = await this._fetch(endpoint, { method: 'POST', body: {}, timeoutMs: 30000 });
+    return { ...res, endpoint };
+  }
+
+  // -------------------------------------------------------------------------
+  // 4. 日志
+  // -------------------------------------------------------------------------
+
+  /**
+   * 拉取网关调用日志。优先 /spend/logs（多数版本可用），失败则退回 /global/spend/logs。
+   * 返回已归一化的记录数组，便于 UI 直接渲染。
+   */
+  async fetchLogs({ limit = 50 } = {}) {
+    const attempts = [
+      () => this._fetch(`/spend/logs?limit=${encodeURIComponent(limit)}`),
+      () => this._fetch(`/global/spend/logs?limit=${encodeURIComponent(limit)}`),
+    ];
+    let lastErr = null;
+    for (const attempt of attempts) {
+      const res = await attempt();
+      if (res.ok) {
+        const rows = Array.isArray(res.data) ? res.data : res.data?.data || [];
+        return ok(normalizeLogs(rows).slice(0, limit));
+      }
+      lastErr = res.error;
+    }
+    // 实测：纯 config.yaml 模式（无 DATABASE_URL）下 /spend/logs 返回 500
+    // "Prisma Client is not initialized"。这不是插件 bug，要把原因讲清楚。
+    const raw = String(lastErr || '');
+    if (/Prisma|database|DB|not initialized|No DB/i.test(raw)) {
+      return fail(
+        '日志接口需要数据库支持。/spend/logs 与 /global/spend/logs 都依赖 LiteLLM 的数据库，' +
+          '当前网关是纯 config.yaml 模式（未配置 DATABASE_URL 或 store_model_in_db），因此不记录调用日志。' +
+          '启用日志：在 .env 设置 DATABASE_URL，并在 config.yaml 打开 store_model_in_db: true。',
+        { needsDatabase: true },
+      );
+    }
+    return fail(lastErr || '无法获取网关日志');
+  }
+
+  // -------------------------------------------------------------------------
+  // 5. 探针
+  // -------------------------------------------------------------------------
+
+  /**
+   * 一键探针：发一条带 custom header 的最小补全请求，验证
+   * 「插件 → 网关 → 上游」整条链路 + header 透传。
+   * 这是「测试」行为，不是「路由」行为。
+   */
+  async probe({ model, agentType, profile, timeoutMs = 120000 }) {
+    if (!this.hasKey) {
+      return fail('缺少网关 master key，无法发探针请求（应在网关侧 .env 中配置）');
+    }
+    const body = {
+      model,
+      messages: [{ role: 'user', content: 'Reply with the single word: pong' }],
+      // 16 太小：实测降级到某些小模型时会返回空串，看起来像失败。
+      // 64 足够容纳一个单词，也留出降级/推理模型的余量。
+      max_tokens: 64,
+      temperature: 0,
+    };
+    const headers = {};
+    if (agentType) headers['x-agent-type'] = agentType;
+    if (profile) headers['x-session-profile'] = profile;
+
+    const started = Date.now();
+    const res = await this._fetch('/v1/chat/completions', {
+      method: 'POST',
+      body,
+      headers,
+      timeoutMs,
+    });
+    const latencyMs = Date.now() - started;
+
+    if (!res.ok) {
+      return fail(res.error, { latencyMs, headers });
+    }
+    const reply = res.data?.choices?.[0]?.message?.content ?? '';
+    const modelUsed = res.data?.model ?? model;
+    // 空回复要如实报告，不能伪装成成功：
+    // 说明上游连上了但没产出内容（常见于降级到小模型 / 达到 max_tokens / 拒答）。
+    if (!String(reply).trim()) {
+      return fail(
+        `上游可达但返回空内容（实际模型 ${modelUsed}）。链路本身是通的；` +
+          '可能是降级到的小模型未产出，或 max_tokens 太小。可换模型再试。',
+        { latencyMs, headers, modelUsed, emptyReply: true },
+      );
+    }
+    return ok(
+      {
+        reply: String(reply).slice(0, 200),
+        modelUsed,
+        agentType: agentType || null,
+        profile: profile || null,
+        headersSent: headers,
+      },
+      { latencyMs },
+    );
+  }
+}
+
+/** 从 upstream model 串 / api_base 猜一个供应商标签，纯展示用。 */
+function guessProvider(upstream = '', apiBase = '') {
+  const s = `${upstream} ${apiBase}`.toLowerCase();
+  if (s.includes('agnes-ai')) return 'agnes';
+  if (s.includes('bigmodel.cn') || s.includes('zhipu')) return 'zhipuai';
+  if (s.includes('nvidia')) return 'nvidia';
+  if (s.includes('siliconflow')) return 'siliconflow';
+  if (s.includes('amd')) return 'amd';
+  if (s.includes('deepseek')) return 'deepseek';
+  if (s.includes('openai')) return 'openai';
+  return 'other';
+}
+
+/**
+ * 把网关返回的各种日志形状归一化成 UI 需要的字段。
+ *
+ * 降级判定：LiteLLM 的响应/日志里可能带 attempted_fallbacks / fallback 痕迹，
+ * 各版本字段名不一，所以做多字段嗅探。判定不出来就标 'unknown'，
+ * 绝不猜——猜错会让橙色高亮变得没有意义。
+ */
+export function normalizeLogs(rows) {
+  return rows.map((r, i) => {
+    const meta = r?.metadata || {};
+    const attempted =
+      r?.attempted_fallbacks ??
+      meta?.attempted_fallbacks ??
+      r?.fallback_attempted ??
+      r?.model_group_attempted ??
+      null;
+
+    let fallback = 'unknown';
+    if (Array.isArray(attempted)) fallback = attempted.length > 0 ? 'yes' : 'no';
+    else if (attempted === true) fallback = 'yes';
+    else if (attempted === false) fallback = 'no';
+    // 备用判定：请求模型 ≠ 实际返回模型，通常意味着发生过降级
+    if (fallback === 'unknown' && r?.model && r?.model_group && r.model !== r.model_group) {
+      fallback = 'yes';
+    }
+
+    const status = r?.status ?? (r?.error ? 'failure' : 'success');
+    const failed = Boolean(r?.error) || String(status).toLowerCase().includes('fail');
+
+    return {
+      id: r?.request_id || r?.id || `log-${i}`,
+      time: r?.startTime || r?.start_time || r?.timestamp || r?.endTime || r?.end_time || null,
+      model: r?.model || r?.model_group || '-',
+      modelGroup: r?.model_group || null,
+      agentType: meta?.['x-agent-type'] || r?.['x-agent-type'] || r?.agent_type || '-',
+      profile: meta?.['x-session-profile'] || r?.['x-session-profile'] || r?.session_profile || '-',
+      status: failed ? 'failure' : 'success',
+      error: failed ? redact(r?.error || status, null).slice(0, 300) : null,
+      latencyMs: r?.response_time ?? r?.latency ?? null,
+      tokens: r?.total_tokens ?? null,
+      spend: r?.spend ?? null,
+      fallback,
+    };
+  });
+}