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

package/dsh-plugin-litellm-bridge/lib/model-pool.js

@@ -0,0 +1,248 @@
+/**
+ * DSH 模型池读取
+ * ============================================================================
+ *
+ * 【架构修正需求 2】插件的模型下拉数据源 = DSH【设置 → 模型】页面里
+ * 已配置完成的供应商与模型（NIM / Agnes / 自定义 OpenAI 协议供应商等）。
+ *
+ * 三条铁律：
+ *   1. 插件**绝不**向 LiteLLM 网关拉取模型清单（models/sync 已删除）；
+ *   2. 供应商凭证（api-key、api 地址）只在 DSH 原生模型页面维护，
+ *      原生页面的【获取可用模型】负责向供应商拉目录 —— 插件不接管；
+ *   3. 只做「读取 + 归一化」，绝不写任何供应商配置。
+ *
+ * 【宿主契约（已 cordis_inspect 核对）】
+ *   ctx.llm.listProviders(): LlmProviderInfo[]        — 供应商目录
+ *   ctx.llm.listModels(provider): Promise<LlmModelInfo[]> — 某供应商的模型
+ *   ctx.sessionController.modelCatalog(): Promise<ModelCatalog> — 会话模型选择器用的目录
+ *
+ * 设计：三个来源按优先级短路，全部 fail-soft（取不到就返回空池 + 明确原因），
+ * 绝不让「模型服务缺一个方法」把插件 UI 拖崩 —— 这正是记忆里
+ * 「可选链 ?. 会让方法不存在静默变成空数据」那条坑的反面：
+ * 这里**显式**探测、**显式**报告原因，而不是静默。
+ */
+
+/**
+ * 归一化一条模型记录。
+ * 不同来源字段名不一（id / model / modelId / name），统一成 UI 需要的形状。
+ */
+function normalizeModel(raw, provider) {
+  if (typeof raw === 'string') {
+    return raw ? { id: raw, name: raw, provider, configured: true, meta: null } : null;
+  }
+  if (!raw || typeof raw !== 'object') return null;
+  const id = String(raw.id ?? raw.model ?? raw.modelId ?? raw.name ?? '').trim();
+  if (!id) return null;
+  return {
+    id,
+    name: String(raw.label ?? raw.displayName ?? raw.name ?? id),
+    provider,
+    // DSH 的「已配置完成」= 该供应商在【设置-模型】里有可用凭证。
+    // 模型目录里出现即代表供应商已配置，否则拉不到模型。
+    configured: raw.configured !== false,
+    meta: raw.contextWindow != null ? { contextWindow: raw.contextWindow } : null,
+  };
+}
+
+/** 归一化一条供应商记录。 */
+function normalizeProvider(raw) {
+  if (typeof raw === 'string') {
+    return raw ? { id: raw, name: raw, kind: null, configured: true, baseUrl: null, authEnv: [] } : null;
+  }
+  if (!raw || typeof raw !== 'object') return null;
+  const id = String(raw.id ?? raw.provider ?? raw.name ?? raw.key ?? '').trim();
+  if (!id) return null;
+  return {
+    id,
+    name: String(raw.displayName ?? raw.label ?? raw.name ?? id),
+    kind: raw.kind ?? raw.type ?? null,
+    configured: raw.configured !== false,
+    /**
+     * 【关键】LlmConfigurableProvider 带 defaultBaseURL / baseURLEnv / nativeAuth，
+     * LlmProviderInfo 只有 {id, name}。网关要能真的调到上游，必须知道 api_base，
+     * 所以这里把能拿到的都记下来；拿不到就让上层明确报错，绝不猜。
+     */
+    baseUrl: raw.defaultBaseURL ?? raw.baseURL ?? null,
+    baseUrlEnv: Array.isArray(raw.baseURLEnv) ? raw.baseURLEnv : [],
+    authEnv: Array.isArray(raw.nativeAuth?.env) ? raw.nativeAuth.env : [],
+    settingsNs: raw.settingsNs ?? null,
+  };
+}
+
+/**
+ * 从 sessionController.modelCatalog() 的返回里抽模型清单。
+ * ModelCatalog 的具体形状随版本变化，这里做多形状嗅探，取不到就返回 null。
+ */
+function modelsFromCatalog(catalog) {
+  if (!catalog || typeof catalog !== 'object') return null;
+  const out = [];
+  const visit = (node, providerHint) => {
+    if (!node) return;
+    if (Array.isArray(node)) {
+      for (const n of node) visit(n, providerHint);
+      return;
+    }
+    if (typeof node !== 'object') return;
+    // 形状 A：{ providers: [ { id, models: [...] } ] }
+    if (Array.isArray(node.providers)) {
+      for (const p of node.providers) visit(p, normalizeProvider(p)?.id || providerHint);
+      return;
+    }
+    // 形状 B：{ models: [...] } 或 { providers: { pid: { models: [...] } } }
+    if (Array.isArray(node.models)) {
+      for (const m of node.models) {
+        const n = normalizeModel(m, providerHint);
+        if (n) out.push(n);
+      }
+      return;
+    }
+    if (node.models && typeof node.models === 'object') {
+      const pid = providerHint || normalizeProvider(node)?.id || null;
+      for (const m of Object.values(node.models)) {
+        const n = normalizeModel(m, pid);
+        if (n) out.push(n);
+      }
+      return;
+    }
+    // 形状 C：Map/对象里直接挂模型：{ [id]: {...} }
+    const selfAsProvider = normalizeProvider(node);
+    const n = normalizeModel(node, providerHint || selfAsProvider?.id || null);
+    if (n) out.push(n);
+  };
+  visit(catalog, null);
+  return out;
+}
+
+/**
+ * 汇总模型池（多来源短路）。
+ *
+ * @param {object} ctx       宿主上下文
+ * @param {object} [opts]
+ * @param {AbortSignal} [opts.signal]
+ * @returns {Promise<{providers:Array, models:Array, source:string|null, reason:string|null}>}
+ */
+export async function collectModelPool(ctx, { signal } = {}) {
+  const providers = [];
+  const models = [];
+  let source = null;
+  let reason = null;
+
+  const llm = (() => {
+    try { return typeof ctx?.get === 'function' ? ctx.get('llm') : ctx?.llm; } catch { return undefined; }
+  })();
+  const sessionController = (() => {
+    try { return typeof ctx?.get === 'function' ? ctx.get('sessionController') : ctx?.sessionController; } catch { return undefined; }
+  })();
+
+  // ---- 来源 1：llm.listProviders() + llm.listModels(provider) -------------
+  if (llm && typeof llm.listProviders === 'function') {
+    try {
+      // 1a) 先读 configurable providers —— 这里有 baseURL / env，是供应链的关键
+      const configurable = [];
+      if (typeof llm.listConfigurableProviders === 'function') {
+        try {
+          for (const p of (await llm.listConfigurableProviders()) || []) {
+            const np = normalizeProvider(p);
+            if (np) configurable.push(np);
+          }
+        } catch {
+          /* 目录不可用不影响主流程：只是拿不到 baseURL */
+        }
+      }
+
+      const rawProviders = await llm.listProviders();
+      for (const p of rawProviders || []) {
+        const np = normalizeProvider(p);
+        if (!np) continue;
+        // 若能对上 configurable 目录，合并 baseURL / env 信息
+        const extra = configurable.find((c) => c.id === np.id || c.settingsNs === np.id);
+        providers.push(extra ? { ...extra, ...np, baseUrl: extra.baseUrl, baseUrlEnv: extra.baseUrlEnv, authEnv: extra.authEnv } : np);
+      }
+      // configurable 里有、但还没注册 adapter 的也算「DSH 里配置过的供应商」
+      for (const c of configurable) {
+        if (!providers.some((p) => p.id === c.id)) providers.push(c);
+      }
+
+      if (providers.length && typeof llm.listModels === 'function') {
+        for (const p of providers) {
+          if (signal?.aborted) break;
+          try {
+            const rows = await llm.listModels(p.id);
+            for (const r of rows || []) {
+              const nm = normalizeModel(r, p.id);
+              if (nm) models.push(nm);
+            }
+          } catch {
+            /* 单个供应商拉不到模型不影响其它供应商 */
+          }
+        }
+        if (models.length) source = 'dsh.llm';
+      } else if (providers.length && typeof llm.listModels !== 'function') {
+        reason = 'llm.listModels 不可用（inspect 已知该方法，但运行时未挂载）';
+      }
+    } catch (err) {
+      reason = `llm.listProviders 失败: ${String(err?.message || err).slice(0, 200)}`;
+    }
+  } else if (!llm) {
+    reason = 'llm 服务未挂载（inject 未包含 llm）';
+  } else {
+    reason = 'llm.listProviders 不可用';
+  }
+
+  // ---- 来源 2：sessionController.modelCatalog() --------------------------
+  if (!models.length && sessionController && typeof sessionController.modelCatalog === 'function') {
+    try {
+      const catalog = await sessionController.modelCatalog();
+      const rows = modelsFromCatalog(catalog) || [];
+      for (const r of rows) {
+        if (!models.some((m) => m.id === r.id && m.provider === r.provider)) models.push(r);
+      }
+      if (rows.length) {
+        source = source || 'dsh.sessionController.modelCatalog';
+        reason = null;
+        // 目录若带供应商信息，补齐 providers 列表
+        for (const r of rows) {
+          if (r.provider && !providers.some((p) => p.id === r.provider)) {
+            providers.push({ id: r.provider, name: r.provider, kind: null, configured: true });
+          }
+        }
+      } else if (!reason) {
+        reason = 'modelCatalog 返回了数据但无法解析出模型';
+      }
+    } catch (err) {
+      reason = reason || `modelCatalog 失败: ${String(err?.message || err).slice(0, 200)}`;
+    }
+  }
+
+  // 去重（同 id 同 provider 只留一条），按 provider → id 排序，UI 稳定
+  const seen = new Set();
+  const deduped = [];
+  for (const m of models) {
+    const key = `${m.provider || ''}::${m.id}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(m);
+  }
+  deduped.sort((a, b) => String(a.provider || '').localeCompare(String(b.provider || '')) || a.id.localeCompare(b.id));
+  providers.sort((a, b) => a.id.localeCompare(b.id));
+
+  return { providers, models: deduped, source, reason };
+}
+
+/**
+ * 从「选中的降级链」里取出去重后的模型 id 列表（primary + fallbacks）。
+ *
+ * profile.routes 结构：{ [pid]: { agents: { root: {primary, fallbacks, timeoutMs}, ... } } }
+ */
+export function chainModelIds(routes, profileId, agentType) {
+  const agents = routes?.[profileId]?.agents;
+  const cfg = agents?.[agentType];
+  if (!cfg) return [];
+  const ids = [];
+  if (cfg.primary) ids.push(String(cfg.primary).trim());
+  for (const f of cfg.fallbacks || []) {
+    const v = String(f || '').trim();
+    if (v) ids.push(v);
+  }
+  return [...new Set(ids.filter(Boolean))];
+}

package/dsh-plugin-litellm-bridge/lib/probe-log.js

@@ -0,0 +1,102 @@
+/**
+ * 本地探针日志环形缓冲
+ * ============================================================================
+ *
+ * 网关的 /spend/logs 需要 PostgreSQL，纯 config.yaml 模式下拿不到任何日志。
+ * 但「批量连通性测试」的失败原因必须能看到 —— 所以插件自己记一份。
+ *
+ * 设计：
+ *   - 纯内存环形缓冲，容量固定（默认 50，与日志面板策略一致），不会膨胀；
+ *   - 只记**探针失败**与批量测试的汇总，不记成功请求（避免刷屏）；
+ *   - 与网关日志合并展示时带 `source: 'local'` 标记，UI 可以区分来源；
+ *   - 结构对齐 gateway-client 的 normalizeLogs 输出，UI 复用同一套渲染。
+ *
+ * 注意：这里绝不记录任何密钥或请求体内容，只记模型名、错误摘要、耗时。
+ */
+
+export class ProbeLog {
+  constructor(limit = 50) {
+    this.limit = Math.max(1, Math.min(500, Number(limit) || 50));
+    this._rows = [];
+    this._seq = 0;
+  }
+
+  /** 记录一条探针结果。只保留失败项，成功项用于统计用不落这里。 */
+  add({ model, ok, latencyMs, error, agentType, profile, batchId }) {
+    if (ok) return null;
+    const row = {
+      id: `local-${++this._seq}`,
+      source: 'local',
+      time: new Date().toISOString(),
+      model: model || '-',
+      modelGroup: null,
+      agentType: agentType || '-',
+      profile: profile || '-',
+      status: 'failure',
+      // 明确标记：这是插件侧探针失败，不是网关调用日志
+      error: String(error || '未知错误').slice(0, 300),
+      latencyMs: Number.isFinite(latencyMs) ? latencyMs : null,
+      tokens: null,
+      spend: null,
+      // 探针失败天然意味着「该模型这条链路不可用」，归为 fallback 候选失效
+      fallback: 'unknown',
+      batchId: batchId || null,
+    };
+    this._rows.unshift(row);
+    if (this._rows.length > this.limit) this._rows.length = this.limit;
+    return row;
+  }
+
+  /**
+   * 【需求7】记录一条网关生命周期事件（启动 / 就绪 / 异常退出 / 已停止）。
+   *
+   * 这类事件与探针失败是不同性质的东西，但都要在日志面板里能看到 ——
+   * 否则用户只会觉得「降级没生效」，实际是网关根本没在跑。
+   * 用 source='gateway' 区分来源，status 按 level 映射颜色：
+   *   error → failure（红）；warn → failure 之外的 warn 语义；info → normal
+   */
+  addGatewayEvent({ level = 'info', message = '', at } = {}) {
+    const row = {
+      id: `gw-${++this._seq}`,
+      source: 'gateway',
+      time: at || new Date().toISOString(),
+      model: 'LiteLLM 网关',
+      modelGroup: null,
+      agentType: '-',
+      profile: '-',
+      // 只有 error 才染红；warn 用 fallback=yes 走橙色，info 是普通行
+      status: level === 'error' ? 'failure' : 'success',
+      error: level === 'error' || level === 'warn' ? String(message).slice(0, 300) : null,
+      latencyMs: null,
+      tokens: null,
+      spend: null,
+      fallback: level === 'warn' ? 'yes' : 'unknown',
+      batchId: null,
+      // UI 用它渲染「运行中 / 已停止 / 异常」这类标签
+      gatewayLevel: level,
+      message: String(message).slice(0, 300),
+    };
+    this._rows.unshift(row);
+    if (this._rows.length > this.limit) this._rows.length = this.limit;
+    return row;
+  }
+
+  /** 批量测试开始时清掉上一批的本地记录，避免堆积。 */
+  clearBatch(batchId) {
+    if (!batchId) return;
+    this._rows = this._rows.filter((r) => r.batchId !== batchId);
+  }
+
+  clearAll() {
+    this._rows = [];
+  }
+
+  list(limit) {
+    const n = Math.max(1, Math.min(this.limit, Number(limit) || this.limit));
+    return this._rows.slice(0, n);
+  }
+
+  get size() {
+    return this._rows.length;
+  }
+}

package/dsh-plugin-litellm-bridge/lib/subagent-routing.js

@@ -0,0 +1,280 @@
+/**
+ * 子代理路由覆盖
+ * ============================================================================
+ *
+ * 【需求】
+ *   会话选中的供应商为 Trae / WorkBuddy 时：
+ *     - root 主 Agent 保留原供应商（继续消耗 Trae/WorkBuddy 积分）；
+ *     - 所有 spawn 出来的子 Agent 强制覆盖为 LitellM-Gateway，
+ *       自动读会话 profile 并注入 header，走网关降级池。
+ *   会话选中的供应商为 LitellM-Gateway 时：
+ *     - 主 Agent、子 Agent 全部走网关链路（不做任何覆盖）。
+ *
+ * 【为什么用 internal/get 而不是事件】
+ *   DSH 里**没有** `agent/spawn` 事件（已核对宿主全部约 85 个事件）。
+ *   而且「子代理用什么模型」是在子会话创建**之前**定下来的，
+ *   任何事后事件都改不了。
+ *
+ *   真正的 hook 是 cordis 的「服务读取 waterfall」：
+ *       ctx.on('internal/get', (readCtx, name, error, next) => ...)
+ *   当有人读 `subagents` 服务时，我们返回一个**原型委托包装**，
+ *   它的 startActivation() 在委派给真服务之前改写 spec.request.agentOptions。
+ *   原服务对象**从不被修改**，其他读者透明拿到包装。
+ *
+ *   这个做法与 dsh-llm-fallbacks 的 subagent seam 完全同构
+ *   （见其 dist/index.js 的 installSubagentSeam / wrapService）。
+ *
+ * 【为什么不用 llm/stream】
+ *   llm/stream 拿到的 GenerateOptions 是**深冻结**的（改会抛异常），
+ *   而且它在语义上是「读」，不是「选路由」。用 internal/get 在源头改
+ *   才是干净的做法。
+ */
+
+/** 触发「子代理强制走网关」的供应商（大小写不敏感）。 */
+export const NATIVE_PROVIDERS = ['trae', 'workbuddy'];
+
+/** 子代理被覆盖到的供应商名。需与网关在 DSH 里的 provider 路由名一致。 */
+export const GATEWAY_PROVIDER = 'litellm-gateway';
+
+/** 网关里对应各 agent 类型的「对外模型名」，与 config.yaml.template 对齐。 */
+export const GATEWAY_MODEL_BY_AGENT = {
+  root: 'root-primary',
+  coder: 'coder-primary',
+  research: 'research-primary',
+};
+
+/** 供应商名归一化：去掉区域/账号后缀，统一小写比较。 */
+export function normalizeProvider(name) {
+  return String(name || '').trim().toLowerCase();
+}
+
+/**
+ * 该供应商是否属于「原生积分供应商」——即需要把子代理改道网关的那些。
+ * 用 includes 而非全等，以兼容 `trae`、`trae-cn`、`workbuddy`、`workbuddy-cn` 等写法。
+ */
+export function isNativeProvider(name) {
+  const n = normalizeProvider(name);
+  if (!n) return false;
+  return NATIVE_PROVIDERS.some((p) => n === p || n.startsWith(`${p}-`) || n.startsWith(`${p}_`));
+}
+
+/** 是否已经是网关供应商（这种情况一律不覆盖）。 */
+export function isGatewayProvider(name) {
+  const n = normalizeProvider(name);
+  return n === GATEWAY_PROVIDER || n === 'litellm' || n.startsWith('litellm-');
+}
+
+/**
+ * 从会话日志里推断「本会话选中的供应商」。
+ *
+ * 优先用已经解析好的选择（调用方传入），其次读会话事件里的模型选择记录。
+ * 读不到就返回 undefined —— 此时**不做任何覆盖**（fail-open 到原生行为），
+ * 因为「猜错了供应商」比「不覆盖」危险得多。
+ */
+export function detectSessionProvider(session, readEvent) {
+  try {
+    // 1) 会话头里可能直接带
+    const direct =
+      session?.header?.model?.provider ||
+      session?.modelSelection?.provider ||
+      session?.selection?.provider;
+    if (direct) return String(direct);
+
+    // 2) 扫会话事件里最后一次模型选择
+    if (typeof readEvent === 'function') {
+      const last = readEvent();
+      const p = last?.data?.provider || last?.data?.selection?.provider || last?.data?.model?.provider;
+      if (p) return String(p);
+    }
+  } catch {
+    /* 探测失败不致命：返回 undefined 表示不覆盖 */
+  }
+  return undefined;
+}
+
+/**
+ * 根据 spec 判断这是不是「子代理派发」，并解析出父会话 id。
+ * 主 Agent 自己发起的请求不会走 startActivation，所以走到这里的基本都是子代理；
+ * 但仍显式校验 parent 存在，避免误伤。
+ */
+export function parentSessionIdOf(spec) {
+  const id = spec?.request?.parent?.session?.id ?? spec?.request?.parent?.id;
+  return typeof id === 'string' && id !== '' ? id : undefined;
+}
+
+/**
+ * 决定这一次子代理派发要不要覆盖，覆盖成什么。
+ * 纯函数，方便单测；不碰任何服务。
+ *
+ * @returns {{override:false, reason:string} | {override:true, reason:string, provider:string, model:string, agentType:string}}
+ */
+export function decideOverride({ spec, sessionProvider, profile, agentType, natives, gateway }) {
+  const nativeList = Array.isArray(natives) && natives.length ? natives : NATIVE_PROVIDERS;
+  const gatewayName = gateway || GATEWAY_PROVIDER;
+
+  // 已经显式指定了路由的派发不动它（尊重调用方意图）
+  const explicitProvider = spec?.request?.agentOptions?.provider;
+
+  const n = normalizeProvider(sessionProvider);
+  const isNative = n
+    ? nativeList.some((p) => {
+        const np = normalizeProvider(p);
+        return n === np || n.startsWith(`${np}-`) || n.startsWith(`${np}_`);
+      })
+    : false;
+  const isGateway = n === normalizeProvider(gatewayName) || n === 'litellm' || n.startsWith('litellm-');
+
+  if (isGateway) {
+    return { override: false, reason: '会话已在网关供应商，主/子代理都走网关，无需覆盖' };
+  }
+
+  if (!isNative) {
+    return {
+      override: false,
+      reason: n
+        ? `会话供应商 "${sessionProvider}" 不在覆盖名单（${nativeList.join('/')}）`
+        : '无法确定会话供应商，保持原生行为',
+    };
+  }
+
+  // 到这里说明：会话是 Trae/WorkBuddy，子代理要改道网关
+  const type = agentType && GATEWAY_MODEL_BY_AGENT[agentType] ? agentType : 'root';
+  return {
+    override: true,
+    reason: `会话供应商 "${sessionProvider}" 属原生积分池，子代理改道网关`,
+    provider: gatewayName,
+    model: GATEWAY_MODEL_BY_AGENT[type],
+    agentType: type,
+    // 覆盖前显式带上原 provider，仅用于日志
+    fromProvider: explicitProvider || sessionProvider,
+  };
+}
+
+/**
+ * 安装服务读取 waterfall，包装 `subagents` 服务。
+ *
+ * @param {object} ctx          cordis 上下文
+ * @param {object} options
+ * @param {(parentSessionId:string)=>string|undefined} options.providerFor
+ *        给定父会话 id，返回该会话选中的供应商
+ * @param {(parentSessionId:string)=>string|undefined} options.profileFor
+ *        给定父会话 id，返回该会话绑定的 profile
+ * @param {(agentType:string)=>string|undefined} options.modelFor
+ *        给定 agent 类型，返回网关侧模型名（默认用 GATEWAY_MODEL_BY_AGENT）
+ * @param {(msg:string)=>void} [options.debug]
+ * @returns {{dispose:()=>void, stats:()=>object}}
+ */
+export function installSubagentRouting(ctx, options = {}) {
+  const debug = (m) => {
+    try {
+      options.debug?.(m);
+    } catch {
+      /* 日志失败绝不影响主流程 */
+    }
+  };
+
+  // 允许 profile config 覆盖名单与目标供应商
+  const natives = Array.isArray(options.nativeProviders) && options.nativeProviders.length
+    ? options.nativeProviders.map(normalizeProvider)
+    : NATIVE_PROVIDERS;
+  const gateway = options.gatewayProvider ? normalizeProvider(options.gatewayProvider) : GATEWAY_PROVIDER;
+
+  const stats = { evaluated: 0, overridden: 0, skipped: 0, degraded: 0 };
+  const wrappers = new WeakMap();
+  const disposers = [];
+
+  const wrapService = (value) => {
+    if (typeof value !== 'object' || value === null) return value;
+    if (typeof value.startActivation !== 'function') {
+      debug('[litellm-bridge] subagents 服务不是 activation-capable runtime，跳过包装');
+      return value;
+    }
+    const cached = wrappers.get(value);
+    if (cached !== undefined) return cached;
+
+    // 原型委托：原对象一个字节都不改，其他读者透明拿到包装
+    const wrapper = Object.create(value);
+    wrapper.startActivation = function startActivation(spec) {
+      try {
+        const parentSessionId = parentSessionIdOf(spec);
+        const sessionProvider = parentSessionId ? options.providerFor?.(parentSessionId) : undefined;
+        const profile = parentSessionId ? options.profileFor?.(parentSessionId) : undefined;
+        const agentType = options.agentTypeFor?.(spec) || 'root';
+
+        stats.evaluated += 1;
+        const verdict = decideOverride({
+          spec, sessionProvider, profile, agentType,
+          natives, gateway,
+        });
+
+        if (!verdict.override) {
+          stats.skipped += 1;
+          debug(`[litellm-bridge] 子代理不改道：${verdict.reason}`);
+          return value.startActivation(spec);
+        }
+
+        const model = options.modelFor?.(verdict.agentType, parentSessionId) || verdict.model;
+        const agentOptions = spec?.request?.agentOptions;
+
+        // 改写路由：只换 provider/model，其余字段原样保留
+        const nextSpec = {
+          ...spec,
+          request: {
+            ...spec.request,
+            agentOptions: {
+              ...agentOptions,
+              provider: verdict.provider,
+              model,
+            },
+          },
+        };
+
+        stats.overridden += 1;
+        debug(
+          `[litellm-bridge] 子代理改道网关：${verdict.fromProvider} -> ${verdict.provider}/${model}` +
+            `${profile ? `（profile=${profile}）` : ''}`,
+        );
+        return value.startActivation(nextSpec);
+      } catch (err) {
+        // 任何异常都退回原生行为：绝不因为我们的改写让子代理起不来
+        stats.degraded += 1;
+        debug(`[litellm-bridge] 子代理改道失败，退回原生路径：${err?.message || err}`);
+        return value.startActivation(spec);
+      }
+    };
+
+    wrappers.set(value, wrapper);
+    return wrapper;
+  };
+
+  const onRead = (_readCtx, name, _error, next) => {
+    const value = next();
+    if (name !== 'subagents') return value;
+    try {
+      return wrapService(value);
+    } catch (err) {
+      stats.degraded += 1;
+      debug(`[litellm-bridge] 包装 subagents 失败，返回原服务：${err?.message || err}`);
+      return value;
+    }
+  };
+
+  try {
+    disposers.push(ctx.on('internal/get', onRead));
+  } catch (err) {
+    debug(`[litellm-bridge] 无法注册 internal/get 监听：${err?.message || err}`);
+  }
+
+  const dispose = () => {
+    for (const withdraw of disposers.splice(0)) {
+      try {
+        withdraw();
+      } catch {
+        /* 清理失败忽略 */
+      }
+    }
+  };
+
+  debug('[litellm-bridge] 子代理路由覆盖已安装（服务读取 waterfall）');
+  return { dispose, stats: () => ({ ...stats }) };
+}

package/dsh-plugin-litellm-bridge/locale/en.json

@@ -0,0 +1,43 @@
+{
+  "meta": {
+    "title": "LiteLLM Gateway Bridge",
+    "description": "Configure the LiteLLM gateway URL, compose fallback routes per agent type, inspect gateway call logs, and bind a session profile. The plugin holds no routing/retry/fallback logic — the external gateway owns all of it."
+  },
+  "tabs": {
+    "gateway": "Gateway",
+    "routes": "Routes",
+    "logs": "Logs",
+    "session": "Session"
+  },
+  "gateway": {
+    "url": "Gateway URL",
+    "masterKey": "Gateway master admin key",
+    "fromEnv": "From .env environment variable",
+    "test": "Test connection",
+    "save": "Save"
+  },
+  "routes": {
+    "primary": "Primary model",
+    "timeout": "Timeout (ms)",
+    "fallbacks": "Fallback models (drag to reorder; order is priority)",
+    "saveAndReload": "Save and hot-reload",
+    "save": "Save only",
+    "preview": "Preview YAML"
+  },
+  "logs": {
+    "fallbackHint": "Amber = fallback triggered",
+    "failedHint": "Red = whole chain failed",
+    "refresh": "Refresh"
+  },
+  "session": {
+    "bindProfile": "Profile bound to this session",
+    "saveToSession": "Save to session variable",
+    "probe": "Run probe test",
+    "recentDrops": "Recent fallbacks in this session",
+    "subagentRouting": "Sub-agent routing override",
+    "currentProvider": "Current provider",
+    "rerouteToGateway": "Sub-agents will be rerouted to gateway",
+    "allViaGateway": "Everything via gateway",
+    "noOverride": "No override"
+  }
+}