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

package/dsh-plugin-litellm-bridge/cordis.patch.yml

@@ -0,0 +1,27 @@
+# litellm-bridge 的 profile-bundle 补丁：一行 insert，把本插件挂进 profile 的组合树。
+#
+# 说明（照 dsh-llm-fallbacks 的约定）：
+#   - 本行只声明中性默认值；用户级 profile cordis.patch.yml 里的覆盖优先级更高。
+#   - 补丁会「整块替换」目标行的 config 而不是合并，所以用户侧覆盖要写全字段。
+#   - 本插件与 dsh-llm-fallbacks「不应同时启用」：两套降级逻辑会互相冲突。
+#     安装前请先在插件管理器里禁用 dsh-llm-fallbacks。
+
+- insert:
+    - id: litellm-bridge
+      name: 'dsh-plugin-litellm-bridge'
+      config:
+        # LiteLLM 网关地址（UI「网关设置」Tab 可改）
+        gatewayUrl: 'http://127.0.0.1:4000'
+        # 请求超时（毫秒）
+        timeoutMs: 30000
+        # 日志面板默认保留条数（防止臃肿）
+        logLimit: 50
+        # 探测到可用热重载端点后写在这里；留空表示每次自动探测
+        reloadEndpoint: ''
+        # ---- 子代理路由覆盖 ----
+        # 会话选中这些供应商时，子代理强制改道网关（主 Agent 保持原样）
+        nativeProviders:
+          - trae
+          - workbuddy
+        # 子代理被改道到的 provider 名（需与 DSH 里指向本网关的 provider 路由一致）
+        gatewayProvider: 'litellm-gateway'

package/dsh-plugin-litellm-bridge/icon.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">
+  <!-- 桥接：左右两个节点经中间网关转发 -->
+  <circle cx="3.5" cy="12" r="2"/>
+  <circle cx="20.5" cy="6" r="1.7"/>
+  <circle cx="20.5" cy="12" r="1.7"/>
+  <circle cx="20.5" cy="18" r="1.7"/>
+  <path d="M5.5 12h4.2"/>
+  <path d="M15.8 12h2.7"/>
+  <path d="M9.7 12c1.6-.9 1.6-5.1 3.3-6h5.8"/>
+  <path d="M9.7 12c1.6.9 1.6 5.1 3.3 6h5.8"/>
+  <rect x="9.7" y="9.6" width="6.1" height="4.8" rx="1.1"/>
+</svg>

package/dsh-plugin-litellm-bridge/lib/assemble-chain.js

@@ -0,0 +1,193 @@
+/**
+ * profile 降级链 → LiteLLM config 片段
+ * ============================================================================
+ *
+ * 【架构修正需求 3】路由配置 Tab 保存的 profile × (root / coder / research)
+ * 三条降级序列，必须**下发给 LiteLLM 网关**；网关只按顺序执行重试 / 降级，
+ * 插件本身不含路由逻辑。
+ *
+ * 【这一版最关键的修正 · 上一版是错的】
+ *   上一版把上游写成 `os.environ/LITELLM_UPSTREAM_<模型名大写>` —— 这些
+ *   环境变量**没有任何人设置**，网关启动后每条链都是坏的（表面成功、实际不通）。
+ *   正确做法：模型来自 DSH【设置-模型】，那里的供应商已配好 api_base + api_key。
+ *   所以按**供应商**解析到真实的 api_base 与凭证环境变量名；拿不到就明确报警，
+ *   绝不生成一条看起来正常、实际调不通的配置。
+ *
+ * 【必须纯 ASCII】LiteLLM 用平台默认编码读 config.yaml；中文 Windows 是 GBK，
+ * 非 ASCII 注释会在启动 / 重载时抛 UnicodeDecodeError（实测踩过）。
+ */
+
+/** 默认按 OpenAI 兼容协议发请求。 */
+const OPENAI_COMPAT = 'openai';
+
+/**
+ * 供应商协议 → LiteLLM model 前缀。
+ * LiteLLM 认这些前缀，用对协议发请求，否则会 404 / 400。
+ */
+export function protocolPrefix(provider) {
+  const k = String(provider?.kind || provider?.id || provider?.name || '').toLowerCase();
+  if (k.includes('anthropic') || k.includes('claude')) return 'anthropic';
+  if (k.includes('gemini') || k.includes('google')) return 'gemini';
+  return OPENAI_COMPAT;
+}
+
+/**
+ * 供应商的凭证环境变量名。
+ *
+ * DSH 自己管凭证；网关是独立进程，只能通过环境变量拿到同一个 key。
+ * 优先用供应商声明的 nativeAuth.env / baseURLEnv，没有就退回约定名。
+ * 名字本身不含密钥，写进 YAML 是安全的（os.environ/XXX 只引用不展开）。
+ */
+export function keyEnvName(provider) {
+  const env = provider?.authEnv?.[0] || provider?.baseUrlEnv?.[0];
+  if (env) return env;
+  return `${String(provider?.id || 'provider').toUpperCase().replace(/[^A-Z0-9]/g, '_')}_API_KEY`;
+}
+
+/**
+ * 组装 config.yaml。
+ *
+ * @param {object} state  ConfigStore 状态（含 routes）
+ * @param {object} [pool] collectModelPool() 结果（供应商 baseURL / 凭证 env）
+ * @returns {{yaml:string, warnings:string[], chains:Array, upstreams:Array}}
+ */
+export function assembleChainConfig(state, pool = null) {
+  const routes = state?.routes || {};
+  const providerMap = new Map((pool?.providers || []).map((p) => [p.id, p]));
+  /** model id → 归属供应商（池里第一个出现的） */
+  const providerOfModel = new Map();
+  for (const m of pool?.models || []) {
+    if (!providerOfModel.has(m.id)) providerOfModel.set(m.id, m.provider);
+  }
+
+  const warnings = [];
+  /** 真实上游：model id → { name, provider, baseUrl, keyEnv, timeoutSec } */
+  const upstreams = new Map();
+  /** 链：{ pid, at, head, chain, timeoutMs } */
+  const chains = [];
+
+  // ---- 1. 收集所有链与上游 ------------------------------------------------
+  for (const pid of Object.keys(routes)) {
+    const agents = routes[pid]?.agents || {};
+    for (const at of Object.keys(agents)) {
+      const cfg = agents[at];
+      if (!cfg?.primary) continue;
+      const chain = [cfg.primary, ...(cfg.fallbacks || [])].filter(Boolean);
+      if (!chain.length) continue;
+
+      chains.push({
+        pid,
+        at,
+        head: `${at}-${pid}-primary`,
+        chain,
+        timeoutMs: cfg.timeoutMs || 600000,
+      });
+
+      for (const modelId of chain) {
+        if (upstreams.has(modelId)) continue;
+        const providerId = providerOfModel.get(modelId) || '';
+        const prov = providerMap.get(providerId);
+        if (!providerId) {
+          warnings.push(
+            `模型 ${modelId} 不在 DSH 模型池里（可能已被删除或改了名）。` +
+            '请到【设置-模型】确认，或在「路由配置」里重新选择。',
+          );
+          continue;
+        }
+        if (!prov?.baseUrl) {
+          warnings.push(
+            `供应商 ${providerId} 缺少 API 地址（baseURL），模型 ${modelId} 无法下发。` +
+            '请到【设置-模型】补全该供应商的 API 地址。',
+          );
+          continue;
+        }
+        upstreams.set(modelId, {
+          name: modelId,
+          providerId,
+          prefix: protocolPrefix(prov),
+          baseUrl: prov.baseUrl,
+          keyEnv: keyEnvName(prov),
+          timeoutSec: Math.max(1, Math.round((cfg.timeoutMs || 600000) / 1000)),
+        });
+      }
+    }
+  }
+
+  // ---- 2. 生成 YAML -------------------------------------------------------
+  const lines = [];
+  const push = (s = '') => lines.push(s);
+
+  push('# ============================================================================');
+  push('#  Generated by dsh-plugin-litellm-bridge - profile fallback chains');
+  push(`#  Generated at: ${new Date().toISOString()}`);
+  push('# ============================================================================');
+  push('#  Model catalog and provider credentials live in DSH Settings > Models.');
+  push('#  This file only mirrors those upstreams so the gateway can execute the');
+  push('#  fallback order. The plugin itself performs no routing / retry / fallback.');
+  push('#  api_key entries are os.environ references - never plaintext.');
+  push('#');
+
+  push('model_list:');
+  for (const u of upstreams.values()) {
+    push(`  # ${u.providerId}`);
+    push(`  - model_name: ${u.name}`);
+    push('    litellm_params:');
+    push(`      model: ${u.prefix}/${u.name}`);
+    push(`      api_base: ${u.baseUrl}`);
+    push(`      api_key: os.environ/${u.keyEnv}`);
+    push(`      timeout: ${u.timeoutSec}`);
+  }
+  // 链头：逻辑名 → 链首模型的真实上游
+  for (const c of chains) {
+    const first = upstreams.get(c.chain[0]);
+    if (!first) continue;
+    if (upstreams.has(c.head)) continue;
+    push(`  # chain head: ${c.pid} / ${c.at}`);
+    push(`  - model_name: ${c.head}`);
+    push('    litellm_params:');
+    push(`      model: ${first.prefix}/${first.name}`);
+    push(`      api_base: ${first.baseUrl}`);
+    push(`      api_key: os.environ/${first.keyEnv}`);
+    push(`      timeout: ${Math.max(1, Math.round(c.timeoutMs / 1000))}`);
+  }
+  push('');
+
+  // ---- 3. 降级顺序（网关执行）--------------------------------------------
+  push('litellm_settings:');
+  push('  # Fallback order is assembled by the plugin, executed by the gateway.');
+  const multi = chains.filter((c) => c.chain.length >= 2 && upstreams.has(c.chain[0]));
+  push('  fallbacks:');
+  if (!multi.length) {
+    push('    []');
+  } else {
+    for (const c of multi) push(`    - ${c.head}: [${c.chain.slice(1).map((m) => `"${m}"`).join(', ')}]`);
+  }
+  push('  context_window_fallbacks:');
+  if (!multi.length) {
+    push('    []');
+  } else {
+    for (const c of multi) push(`    - ${c.head}: ["${c.chain[c.chain.length - 1]}"]`);
+  }
+  push('  num_retries: 2');
+  push('  request_timeout: 900');
+  push('  drop_params: true');
+  push('  forward_client_headers_to_llm_api: true   # pass x-agent-type / x-session-profile through');
+  push('');
+
+  return {
+    yaml: lines.join('\n'),
+    warnings: [...new Set(warnings)],
+    chains: chains.map(({ head, pid, at, chain }) => ({ head, pid, at, chain })),
+    upstreams: [...upstreams.values()],
+  };
+}
+
+/** 兼容旧签名：只要 YAML 文本。 */
+export function assembleChainYaml(state, pool = null) {
+  return assembleChainConfig(state, pool).yaml;
+}
+
+/** 排障提示用：模型名 → 约定环境变量名（不再写入配置）。 */
+export function upstreamEnvVar(modelId) {
+  return `LITELLM_UPSTREAM_${String(modelId).toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
+}

package/dsh-plugin-litellm-bridge/lib/config-store.js

@@ -0,0 +1,290 @@
+/**
+ * 插件配置与路由 Profile 的持久化
+ * ============================================================================
+ *
+ * 【架构修正后的职责】
+ *   - 存网关连接设置（地址、超时、日志条数）
+ *   - 存 profile 列表：每个 profile 下 root / coder / research 三条降级链
+ *     （root = 主 Agent 链；coder / research = 子 Agent 链，两者可完全不同）
+ *
+ * 【模型来源变了】模型名不再来自 LiteLLM 网关（那个 models/sync 已删除），
+ *   而是用户在 UI 里从 **DSH【设置-模型】的模型池** 里选出来的。
+ *   本模块只存"选了哪些模型、什么顺序"，不碰任何供应商凭证。
+ *
+ * 【绝不存密钥】真正的 master key 在网关侧 .env 里；插件只在内存里按需读取。
+ *
+ * 落盘位置：$DSH_HOME/litellm-bridge/state.json
+ */
+
+import { mkdir, readFile, writeFile, rename } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/** 三类 Agent 槽位。root 是主链，coder/research 是子 Agent 链。 */
+export const AGENT_TYPES = ['root', 'coder', 'research'];
+
+/** 默认 profile id（用户可在 UI 里新建更多）。 */
+export const DEFAULT_PROFILE_ID = 'profile-a';
+
+/** 兼容旧代码引用：默认 profile 列表。 */
+export const PROFILE_IDS = ['profile-a', 'profile-b'];
+
+/**
+ * 校验 profile id：只允许字母数字、连字符、下划线，长度 1–40。
+ * 因为它会被写进 YAML 的 model_name，必须保证 YAML/ASCII 安全。
+ */
+export function isValidProfileId(id) {
+  return typeof id === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$/.test(id);
+}
+
+/** 一个空的 agent 链骨架。 */
+export function emptyAgentChain(label = '') {
+  return { label, primary: '', timeoutMs: 600000, fallbacks: [] };
+}
+
+/** 一个空 profile 骨架。 */
+export function emptyProfile(id) {
+  return {
+    label: id,
+    agents: {
+      root: emptyAgentChain('主代理'),
+      coder: emptyAgentChain('子代理 · Coder'),
+      research: emptyAgentChain('子代理 · Research'),
+    },
+  };
+}
+
+/**
+ * 出厂默认：两个 profile 骨架。
+ *
+ * 【注意】primary/fallbacks 故意留空：模型必须由用户从 DSH 模型池里选，
+ * 插件不能凭空编造模型名（旧版写死了 root-primary 之类网关侧别名，
+ * 现在网关不再维护模型清单，那些名字已经没有意义）。
+ */
+export function defaultRoutes() {
+  return {
+    'profile-a': emptyProfile('profile-a（稳定优先）'),
+    'profile-b': emptyProfile('profile-b（成本优先）'),
+  };
+}
+
+export function defaultState() {
+  return {
+    version: 2,
+    gateway: {
+      url: 'http://127.0.0.1:4000',
+      timeoutMs: 30000,
+      logLimit: 50,
+      reloadEndpoint: '',
+      lastProbeAt: null,
+      lastProbeOk: null,
+    },
+    routes: defaultRoutes(),
+    updatedAt: null,
+  };
+}
+
+export function stateDir() {
+  const home = process.env.DSH_HOME || join(homedir(), '.dsh');
+  return join(home, 'litellm-bridge');
+}
+
+export function statePath() {
+  return join(stateDir(), 'state.json');
+}
+
+/** 归一化一条 agent 链（容忍旧版本 / 残缺字段）。 */
+function mergeAgentChain(src, base) {
+  const out = { ...base };
+  if (!src || typeof src !== 'object') return out;
+  if (typeof src.label === 'string' && src.label) out.label = src.label;
+  if (typeof src.primary === 'string') out.primary = src.primary.trim();
+  const t = Number(src.timeoutMs);
+  if (Number.isFinite(t) && t > 0) out.timeoutMs = t;
+  if (Array.isArray(src.fallbacks)) {
+    out.fallbacks = src.fallbacks
+      .map((x) => (typeof x === 'string' ? x.trim() : ''))
+      .filter(Boolean);
+  }
+  return out;
+}
+
+/** 深合并：磁盘内容覆盖默认值，但结构始终完整。 */
+function mergeState(base, loaded) {
+  if (!loaded || typeof loaded !== 'object') return base;
+  const merged = {
+    ...base,
+    gateway: { ...base.gateway, ...(loaded.gateway || {}) },
+    routes: {},
+  };
+  const srcRoutes = loaded.routes && typeof loaded.routes === 'object' ? loaded.routes : null;
+  if (srcRoutes) {
+    for (const [pid, prof] of Object.entries(srcRoutes)) {
+      if (!isValidProfileId(pid)) continue;
+      const skeleton = emptyProfile(pid);
+      const out = {
+        label: typeof prof?.label === 'string' && prof.label ? prof.label : skeleton.label,
+        agents: {},
+      };
+      for (const at of AGENT_TYPES) {
+        out.agents[at] = mergeAgentChain(prof?.agents?.[at], skeleton.agents[at]);
+      }
+      merged.routes[pid] = out;
+    }
+  }
+  // 一个 profile 都没有时（旧文件为空 / 全非法）退回默认，避免 UI 空壳
+  if (Object.keys(merged.routes).length === 0) merged.routes = defaultRoutes();
+  return merged;
+}
+
+export class ConfigStore {
+  constructor() {
+    this._state = defaultState();
+    this._loaded = false;
+    this._writeChain = Promise.resolve();
+  }
+
+  async load() {
+    if (this._loaded) return this._state;
+    try {
+      const raw = await readFile(statePath(), 'utf8');
+      this._state = mergeState(defaultState(), JSON.parse(raw));
+    } catch (err) {
+      if (err?.code !== 'ENOENT') {
+        this._loadError = String(err?.message || err);
+      }
+      this._state = defaultState();
+    }
+    this._loaded = true;
+    return this._state;
+  }
+
+  /** 只读快照（UI 用）。保证绝不包含任何密钥字段。 */
+  get() {
+    const s = this._state;
+    return {
+      version: s.version,
+      gateway: {
+        url: s.gateway.url,
+        timeoutMs: s.gateway.timeoutMs,
+        logLimit: s.gateway.logLimit,
+        reloadEndpoint: s.gateway.reloadEndpoint,
+        lastProbeAt: s.gateway.lastProbeAt,
+        lastProbeOk: s.gateway.lastProbeOk,
+        keySource: '来自 .env 环境变量',
+      },
+      routes: s.routes,
+      profileIds: Object.keys(s.routes),
+      updatedAt: s.updatedAt,
+      statePath: statePath(),
+      loadError: this._loadError || null,
+    };
+  }
+
+  /** 串行化写入 + 原子替换，避免并发保存把文件写坏。 */
+  async _persist() {
+    this._state.updatedAt = new Date().toISOString();
+    const snapshot = JSON.stringify(this._state, null, 2);
+    const target = statePath();
+    this._writeChain = this._writeChain.then(async () => {
+      await mkdir(dirname(target), { recursive: true });
+      const tmp = `${target}.${process.pid}.tmp`;
+      await writeFile(tmp, snapshot, 'utf8');
+      await rename(tmp, target);
+    });
+    return this._writeChain;
+  }
+
+  async updateGateway(patch = {}) {
+    const g = this._state.gateway;
+    if (typeof patch.url === 'string') g.url = patch.url.trim().replace(/\/+$/, '');
+    if (Number(patch.timeoutMs) > 0) g.timeoutMs = Number(patch.timeoutMs);
+    if (Number(patch.logLimit) > 0) g.logLimit = Math.min(500, Number(patch.logLimit));
+    if (typeof patch.reloadEndpoint === 'string') g.reloadEndpoint = patch.reloadEndpoint;
+    await this._persist();
+    return this.get();
+  }
+
+  async markProbe(okFlag) {
+    this._state.gateway.lastProbeAt = new Date().toISOString();
+    this._state.gateway.lastProbeOk = Boolean(okFlag);
+    await this._persist();
+    return this.get();
+  }
+
+  /** 新建 profile。已存在则报错（不静默覆盖用户配置）。 */
+  async createProfile(id, label = '') {
+    if (!isValidProfileId(id)) {
+      throw new Error(`profile 名称非法：只能用字母数字、连字符、下划线（1–40 字符）`);
+    }
+    if (this._state.routes[id]) throw new Error(`profile 已存在：${id}`);
+    this._state.routes[id] = emptyProfile(label || id);
+    await this._persist();
+    return this.get();
+  }
+
+  /** 重命名 profile 的显示标签（id 不改，避免破坏会话绑定）。 */
+  async renameProfile(id, label) {
+    const prof = this._state.routes[id];
+    if (!prof) throw new Error(`未知 profile: ${id}`);
+    if (typeof label === 'string') prof.label = label.trim() || id;
+    await this._persist();
+    return this.get();
+  }
+
+  /** 删除 profile（至少保留一个，否则会话绑定的值会指向不存在的链）。 */
+  async deleteProfile(id) {
+    if (!this._state.routes[id]) throw new Error(`未知 profile: ${id}`);
+    if (Object.keys(this._state.routes).length <= 1) {
+      throw new Error('至少保留一个 profile');
+    }
+    delete this._state.routes[id];
+    await this._persist();
+    return this.get();
+  }
+
+  /**
+   * 覆盖某个 profile 下某类 agent 的配置。
+   * fallbacks 用「有序数组」表达拖拽排序结果——顺序即优先级。
+   */
+  async updateRoute(profileId, agentType, patch = {}) {
+    const prof = this._state.routes[profileId];
+    if (!prof) throw new Error(`未知 profile: ${profileId}`);
+    if (!AGENT_TYPES.includes(agentType)) throw new Error(`未知 agent 类型: ${agentType}`);
+    const target = prof.agents[agentType];
+    if (typeof patch.primary === 'string') target.primary = patch.primary.trim();
+    if (Number(patch.timeoutMs) > 0) target.timeoutMs = Number(patch.timeoutMs);
+    if (Array.isArray(patch.fallbacks)) {
+      target.fallbacks = patch.fallbacks
+        .map((x) => (typeof x === 'string' ? x.trim() : ''))
+        .filter(Boolean);
+    }
+    if (typeof patch.label === 'string' && patch.label) target.label = patch.label;
+    await this._persist();
+    return this.get();
+  }
+
+  /** 整体替换某 profile 的 agent 配置（UI 保存整块时用）。 */
+  async replaceProfile(profileId, agents = {}) {
+    if (!this._state.routes[profileId]) throw new Error(`未知 profile: ${profileId}`);
+    for (const at of AGENT_TYPES) {
+      if (agents[at]) await this.updateRoute(profileId, at, agents[at]);
+    }
+    return this.get();
+  }
+
+  /** 重置所有路由为出厂骨架（不动网关设置）。 */
+  async resetRoutes() {
+    this._state.routes = defaultRoutes();
+    await this._persist();
+    return this.get();
+  }
+}
+
+/**
+ * 【已废弃】旧的 assembleYaml —— 组装逻辑已迁移到 assemble-chain.js。
+ *
+ * 注意：新版的 assembleChainYaml 需要「模型池」作为第二参数才能解析出
+ * 供应商的 api_base 与凭证环境变量名。只传 state 时上游会缺 api_base，
+ * 所以这里不再提供无池转发（避免调用方以为配置可用、实际调不通）。
+ */