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

package/dsh-plugin-litellm-bridge/lib/index.js

@@ -0,0 +1,760 @@
+/**
+ * dsh-plugin-litellm-bridge —— 宿主半
+ * ============================================================================
+ *
+ * 【定位】LiteLLM 网关桥接面板。插件**不含任何路由 / 重试 / 降级执行逻辑**；
+ *   降级动作 100% 由 LiteLLM 网关按 config.yaml 执行。插件只做四件事：
+ *   读配置、写配置、下发降级链、发探针。
+ *
+ * 【架构修正要点（本轮）】
+ *   1. 模型清单**不再**从网关同步（models/sync 已删除）。数据源 = DSH
+ *      【设置-模型】的模型池（lib/model-pool.js 读取 llm / sessionController）。
+ *   2. 路由配置负责「新建 profile + root/coder/research 三条链 + 拖拽排序 +
+ *      超时」，保存后组装成 config.yaml 下发给网关，网关执行 fallback 调度。
+ *   3. 一键探针测的是**当前 profile 里选中的那组模型**，不是网关里的模型。
+ *   4. 网关生命周期跟随 DSH；进程异常退出写进日志面板（需求7）。
+ *
+ * 【契约】宿主半导出形状（照 dsh-llm-fallbacks）：
+ *     export function apply(ctx, config)
+ *     export const name / provide / Config
+ *
+ * 【RPC 通道 · 实测踩过的坑】
+ *   最初把路由注册成 `kind:'prefix', path:'/api/litellm-bridge'`，客户端用
+ *   connection.rpc.call('/api', ...)，实测报 `transport for ... HTTP 404`。
+ *   根因：`/api/**` 是 dsh-api-gateway 的 typert RPC 分发领地，我们注册
+ *   在它下面的路由永远匹配不到。对照真实插件：
+ *     dsh-connect-trae  → /plugins/dsh-connect-trae/usage
+ *     dsh-qq-plugin     → /.dsh-qq-plugin
+ *   都**刻意避开** /api 前缀。所以这里改用插件命名空间：
+ *     /plugins/dsh-plugin-litellm-bridge
+ *   客户端直接 fetch 这个路径（带浏览器会话 cookie 鉴权）。
+ *
+ * 【密钥】master key 只在网关侧 .env，由启动脚本注入环境变量。
+ *   插件从不上传、不落盘、不回显；界面只显示「来自 .env 环境变量」。
+ */
+
+import Schema from '@deepseek-ai/schemastery';
+import { writeFile, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { GatewaySupervisor, isGatewayAlive, findGatewayDir } from './gateway-supervisor.js';
+import {
+  ConfigStore,
+  AGENT_TYPES,
+  DEFAULT_PROFILE_ID,
+  isValidProfileId,
+} from './config-store.js';
+import { assembleChainConfig } from './assemble-chain.js';
+import { collectModelPool, chainModelIds } from './model-pool.js';
+import { GatewayClient } from './gateway-client.js';
+import { ProbeLog } from './probe-log.js';
+import {
+  installSubagentRouting,
+  GATEWAY_PROVIDER,
+  NATIVE_PROVIDERS,
+} from './subagent-routing.js';
+
+export const name = 'litellm-bridge';
+
+/**
+ * 【不再导出 provide】
+ *
+ * 历史：这里曾写 `export const provide = ['litellm-bridge', 'litellmBridge']`，
+ * 配合 apply 里的 `ctx.set('litellmBridge', {...})` 把服务暴露给 header-inject。
+ * 实测在 DSH 里整插件激活失败：
+ *     cannot set property 'litellmBridge' without provide
+ * 即 cordis 判定 provide 里没有这个 key（数组形式不被认可为多个服务）。
+ *
+ * 现在两个插件改为**纯事件解耦**（litellm-bridge/session-profile-changed 等），
+ * 不再有跨插件服务依赖，所以既不导出 provide，也不调用 ctx.set。
+ * 这也和 dsh-connect-trae / dsh-qq-plugin / dsh-infinite-canvas 的做法一致。
+ *
+ * 保留 name 导出（Loader 用它做显示名与去重）。
+ */
+
+/**
+ * 注入宿主能力 —— **一个都不声明为必需**。
+ *
+ * 【为什么是空数组 · 这是「设置页空白」的真凶】
+ *   cordis 的语义：**声明了却拿不到的服务会让整个插件 pending/failed**。
+ *
+ *   之前写成 `['webServer', 'connection', 'llm', 'sessionController']`，
+ *   只要其中任何一个在这个 profile 的组合里缺失，Host 半就完全不挂载：
+ *     · UI 设置页只剩一个齿轮图标，点进去空白
+ *     · 所有 RPC 不通（没有 apply 就没有路由注册）
+ *
+ *   对照能正常工作的 dsh-qq-plugin，它对这点写得很清楚：
+ *     「声明了拿不到的服务会让插件 pending/failed，那是最难查的一类问题。」
+ *
+ *   本插件全部能力都可以降级使用：
+ *     - webServer        缺 → UI 读不到数据，但插件本身仍加载（日志里明说）
+ *     - llm              缺 → 模型池为空，UI 提示去【设置-模型】配置
+ *     - sessionController缺 → 模型池少一条兜底路径
+ *     - connection       缺 → 根本没用到（RPC 走自建 HTTP 路由）
+ *   所以一个都不声明，全部用 ctx.get 探测 —— **宁可降级，绝不整体失败**。
+ */
+export const inject = [];
+
+/**
+ * 需要探测的可选服务清单（给排障日志用，不参与 cordis 的依赖判定）。
+ */
+export const OPTIONAL_SERVICES = ['webServer', 'llm', 'sessionController', 'connection'];
+
+/** Loader 条目 Config —— 必须是 Schemastery。 */
+export const Config = Schema.object({
+  gatewayUrl: Schema.string().default('http://127.0.0.1:4000'),
+  timeoutMs: Schema.natural().min(1000).max(900000).default(30000),
+  logLimit: Schema.natural().min(1).max(500).default(50),
+  reloadEndpoint: Schema.string().default(''),
+  nativeProviders: Schema.array(Schema.string()).default(['trae', 'workbuddy']),
+  gatewayProvider: Schema.string().default('litellm-gateway'),
+  autoStartGateway: Schema.boolean().default(true),
+  gatewayStartTimeoutMs: Schema.natural().min(3000).max(300000).default(45000),
+  gatewayDir: Schema.string().default(''),
+});
+
+/** 会话 profile 变量的键名。header 注入插件读的就是它。 */
+export const SESSION_PROFILE_KEY = 'litellm-bridge/session-profile';
+
+/** 插件 HTTP 路由前缀（**刻意避开 /api**，见文件头注释）。 */
+export const ROUTE_BASE = '/plugins/dsh-plugin-litellm-bridge';
+
+export function apply(ctx, config = {}) {
+  const store = new ConfigStore();
+  const probeLog = new ProbeLog(config.logLimit || 50);
+
+  // -------------------------------------------------------------------------
+  // 启动诊断：把「哪些可选服务真的可用」打进日志。
+  // 出问题时这一行能立刻区分「插件没挂载」与「挂载了但缺服务」。
+  // -------------------------------------------------------------------------
+  try {
+    const probe = OPTIONAL_SERVICES.map((n) => {
+      let ok = false;
+      try { ok = typeof ctx.get === 'function' ? ctx.get(n) !== undefined : ctx[n] !== undefined; } catch { ok = false; }
+      return `${n}:${ok ? 'OK' : 'missing'}`;
+    }).join(' ');
+    ctx.logger?.info?.(`[litellm-bridge] apply 进入。服务探测 → ${probe}`);
+  } catch { /* 诊断失败不影响加载 */ }
+
+  /** UI 配置的超时（每次 RPC 前刷新，供探针使用）。 */
+  let uiTimeoutMs = Number(config.timeoutMs) || 30000;
+
+  // -------------------------------------------------------------------------
+  // 网关生命周期托管（需求7）
+  //
+  // 网关跟着 DSH 生灭：
+  //   - DSH 启动 → 没起就拉起来；已在跑（用户手动 / 别的实例）→ 只识别不接管
+  //   - DSH 退出 → 只关自己拉起的那个
+  //   - 进程异常退出 → 写进日志面板（下面 onLog 回调）
+  // -------------------------------------------------------------------------
+  const supervisor = new GatewaySupervisor({
+    gatewayUrl: config.gatewayUrl,
+    envFile: process.env.LITELLM_BRIDGE_ENV || '',
+    gatewayDir: config.gatewayDir || '',
+    logger: ctx.logger,
+    startTimeoutMs: Number(config.gatewayStartTimeoutMs) || 45000,
+    // 【需求7】网关生命周期事件 → 日志面板
+    onLog: ({ level, message, at }) => {
+      probeLog.addGatewayEvent({ level, message, at });
+    },
+  });
+
+  /** master key 只从环境读，绝不落盘。 */
+  const gateway = new GatewayClient({
+    baseUrl: config.gatewayUrl || 'http://127.0.0.1:4000',
+    apiKey: process.env.LITELLM_MASTER_KEY || '',
+    timeoutMs: uiTimeoutMs,
+  });
+
+  let ready = null;
+  function ensureReady() {
+    if (!ready) {
+      ready = (async () => {
+        await store.load();
+        const s = store.get();
+        uiTimeoutMs = s.gateway.timeoutMs || uiTimeoutMs;
+        gateway.update({
+          baseUrl: config.gatewayUrl || s.gateway.url,
+          apiKey: process.env.LITELLM_MASTER_KEY || '',
+          timeoutMs: uiTimeoutMs,
+        });
+        return s;
+      })();
+    }
+    return ready;
+  }
+
+  // -------------------------------------------------------------------------
+  // 会话 profile 变量
+  // -------------------------------------------------------------------------
+  const memoryProfiles = new Map();
+  const sessionProviders = new Map();
+
+  function getSessionProfile(_ctx, sessionId) {
+    if (sessionId && memoryProfiles.has(sessionId)) return memoryProfiles.get(sessionId);
+    return '';
+  }
+  function setSessionProfile(_ctx, sessionId, value) {
+    if (!sessionId) return false;
+    if (value) memoryProfiles.set(sessionId, value);
+    else memoryProfiles.delete(sessionId);
+    return true;
+  }
+  function getSessionProvider(sessionId) {
+    return sessionId ? sessionProviders.get(sessionId) : undefined;
+  }
+
+  // 观察真实出站请求，记录每个会话在用的供应商（只读不改）
+  ctx.on?.('llm/stream', function observeProvider(options, proceed) {
+    try {
+      if (options?.sessionId && options?.provider) {
+        const sid = String(options.sessionId);
+        const provider = String(options.provider);
+        const prev = sessionProviders.get(sid);
+        sessionProviders.set(sid, provider);
+        // 【解耦广播】header-inject 靠这个事件做本地镜像，
+        // 从而不需要跨插件服务就能判断「本会话是否走网关」。
+        if (prev !== provider) {
+          ctx.emit?.('litellm-bridge/session-provider-changed', {
+            sessionId: sid,
+            provider,
+          });
+        }
+      }
+    } catch {
+      /* 记录失败绝不影响请求 */
+    }
+    return proceed();
+  });
+
+  // -------------------------------------------------------------------------
+  // 子代理路由覆盖（Trae/WorkBuddy 会话的子代理强制改道网关）
+  // -------------------------------------------------------------------------
+  const routing = installSubagentRouting(ctx, {
+    nativeProviders: config.nativeProviders,
+    gatewayProvider: config.gatewayProvider,
+    providerFor: (parentSessionId) => getSessionProvider(parentSessionId),
+    profileFor: (parentSessionId) => getSessionProfile(ctx, parentSessionId),
+    agentTypeFor: (spec) => {
+      const label = String(spec?.request?.agentOptions?.role || spec?.label || '').toLowerCase();
+      if (label.includes('research') || label.includes('scout')) return 'research';
+      return 'coder';
+    },
+    /**
+     * 【需求8】子 Agent 走哪条链 = 该会话 profile 下 coder / research 链的头。
+     * 链的顺序与超时可在 UI 单独配置，与 root 链完全独立。
+     *
+     * 返回链头名（<at>-<pid>-primary），由网关按 fallbacks 执行后续降级。
+     */
+    modelFor: (agentType, parentSessionId) => {
+      try {
+        const profileId = parentSessionId ? getSessionProfile(ctx, parentSessionId) : '';
+        const routes = store.get().routes;
+        const pid = routes[profileId] ? profileId : Object.keys(routes)[0];
+        const cfg = routes?.[pid]?.agents?.[agentType];
+        if (cfg?.primary) return `${agentType}-${pid}-primary`;
+      } catch {
+        /* 读配置失败退回默认链头 */
+      }
+      return `${agentType}-${DEFAULT_PROFILE_ID}-primary`;
+    },
+    debug: (m) => ctx.logger?.debug?.(m),
+  });
+  ctx.effect?.(() => () => routing.dispose());
+
+  // -------------------------------------------------------------------------
+  // 组装 + 下发降级链（需求3）
+  // -------------------------------------------------------------------------
+
+  /** 生成 config.yaml 文本（需带模型池：要拿到供应商 baseURL / 凭证 env）。 */
+  async function buildYaml() {
+    const pool = await collectModelPool(ctx);
+    return assembleChainConfig(store.get(), pool);
+  }
+
+  /**
+   * 把 config.yaml 落盘到网关目录，然后重启网关使其生效。
+   *
+   * 为什么不用热重载：本机 LiteLLM 1.108.3 的 /config/reload 实测 404，
+   * /config/update 需要 PostgreSQL（SQLite 硬失败）。而 start-gateway.sh
+   * 已有「config.yaml 存在则跳过生成」逻辑 → 写文件 + 重启即可生效。
+   */
+  async function applyChains({ restart = true } = {}) {
+    const { yaml, warnings, upstreams, chains } = await buildYaml();
+
+    // 有警告就先不落盘：生成一条「看起来正常、实际调不通」的配置，
+    // 比直接报错更难排查（网关会启动成功，但每次请求都失败）。
+    if (!upstreams.length) {
+      return {
+        ok: false,
+        yaml,
+        warnings,
+        written: false,
+        restarted: false,
+        error: warnings[0] || '没有任何可用模型：请先在【设置-模型】里配置供应商，并在「路由配置」里选好模型。',
+      };
+    }
+
+    const dir = findGatewayDir(config.gatewayDir || '');
+    if (!dir) {
+      return {
+        ok: false, yaml, warnings, upstreams, written: false, restarted: false,
+        error: '找不到 litellm-gateway 目录，无法下发配置（可在插件 Config 里设置 gatewayDir）',
+      };
+    }
+    const target = join(dir, 'config.yaml');
+    try {
+      // 纯 ASCII + 无 BOM：LiteLLM 用平台默认编码读 YAML（中文 Windows 是 GBK）
+      await writeFile(target, yaml, { encoding: 'utf8' });
+    } catch (err) {
+      return {
+        ok: false, yaml, warnings, written: false, restarted: false,
+        error: `写入 config.yaml 失败: ${err?.message || err}`,
+      };
+    }
+
+    if (!restart) {
+      return {
+        ok: true, yaml, warnings, upstreams, chains,
+        written: true, restarted: false, configPath: target,
+        message: '配置已写入，未重启网关',
+      };
+    }
+    const r = await supervisor.restart();
+    return {
+      ok: Boolean(r.running),
+      yaml, warnings, upstreams, chains,
+      written: true,
+      restarted: Boolean(r.running),
+      configPath: target,
+      message: r.running
+        ? `降级链已下发（${chains.length} 条链 / ${upstreams.length} 个模型），网关已按新配置重启`
+        : `配置已写入，但网关未能启动: ${r.error || '未知原因'}`,
+      gateway: supervisor.status(),
+    };
+  }
+
+  /** 统一 RPC 处理：永远返回结构化结果，绝不让异常穿透到 UI。 */
+  async function handle(action, args = {}) {
+    await ensureReady();
+
+    switch (action) {
+      // ---- 网关设置 ----
+      case 'gateway/get':
+        return { ok: true, data: store.get() };
+
+      case 'gateway/save': {
+        const next = await store.updateGateway(args);
+        uiTimeoutMs = next.gateway.timeoutMs;
+        gateway.update({
+          baseUrl: next.gateway.url,
+          timeoutMs: next.gateway.timeoutMs,
+          apiKey: process.env.LITELLM_MASTER_KEY || '',
+        });
+        return { ok: true, data: next };
+      }
+
+      case 'gateway/test':
+        if (typeof args?.url === 'string' && args.url.trim()) {
+          gateway.update({ baseUrl: args.url.trim() });
+        }
+        {
+          const result = await gateway.testConnection();
+          await store.markProbe(result.ok);
+          return { ok: true, data: result };
+        }
+
+      case 'gateway/keyStatus':
+        return {
+          ok: true,
+          data: {
+            hasKey: gateway.hasKey,
+            source: '来自 .env 环境变量',
+            envVar: 'LITELLM_MASTER_KEY',
+          },
+        };
+
+      // ---- 网关生命周期（需求7）----
+      case 'gateway/lifecycle': {
+        const alive = await isGatewayAlive(store.get().gateway.url);
+        const st = supervisor.status();
+        // 状态口径：以「进程托管状态 + 端口探活」共同决定，避免只看其一
+        const state = st.state === 'error' ? 'error' : alive ? 'running' : st.starting ? 'starting' : 'stopped';
+        return {
+          ok: true,
+          data: {
+            ...st,
+            alive,
+            state,
+            stateLabel: state === 'running' ? '运行中' : state === 'starting' ? '启动中' : state === 'error' ? '异常' : '已停止',
+            autoStart: config.autoStartGateway !== false,
+            ownership: st.owned
+              ? '由本插件启动，退出 DSH 时自动关闭'
+              : alive
+                ? '外部已在运行，本插件不接管（退出时不会关它）'
+                : '未运行',
+          },
+        };
+      }
+
+      case 'gateway/start': {
+        const r = await supervisor.ensureRunning();
+        return { ok: Boolean(r.running), data: { ...supervisor.status(), ...r } };
+      }
+
+      case 'gateway/stop': {
+        const r = await supervisor.stop();
+        return { ok: true, data: { ...supervisor.status(), ...r } };
+      }
+
+      // ---- 【需求2】DSH 模型池 ----
+      case 'models/pool': {
+        const pool = await collectModelPool(ctx);
+        return {
+          ok: true,
+          data: {
+            ...pool,
+            // 明确告诉 UI 数据来源，便于排障时一眼看出用的是哪个入口
+            hint: pool.models.length
+              ? `来自 DSH 设置-模型（${pool.models.length} 个模型 / ${pool.providers.length} 个供应商）`
+              : '未读取到 DSH 模型池，请先在【设置-模型】里配置供应商并获取可用模型',
+          },
+        };
+      }
+
+      // ---- 【需求3】路由配置 ----
+      case 'routes/get':
+        return { ok: true, data: store.get().routes, profileIds: store.get().profileIds };
+
+      case 'routes/createProfile': {
+        const s = await store.createProfile(args.id, args.label);
+        return { ok: true, data: s.routes, profileIds: s.profileIds };
+      }
+
+      case 'routes/renameProfile': {
+        const s = await store.renameProfile(args.id, args.label);
+        return { ok: true, data: s.routes, profileIds: s.profileIds };
+      }
+
+      case 'routes/deleteProfile': {
+        const s = await store.deleteProfile(args.id);
+        return { ok: true, data: s.routes, profileIds: s.profileIds };
+      }
+
+      case 'routes/saveRoute': {
+        const s = await store.updateRoute(args.profileId, args.agentType, args.patch || {});
+        return { ok: true, data: s.routes, profileIds: s.profileIds };
+      }
+
+      case 'routes/replaceProfile': {
+        const s = await store.replaceProfile(args.profileId, args.agents || {});
+        return { ok: true, data: s.routes, profileIds: s.profileIds };
+      }
+
+      case 'routes/reset': {
+        const s = await store.resetRoutes();
+        return { ok: true, data: s.routes, profileIds: s.profileIds };
+      }
+
+      case 'routes/preview': {
+        const r = await buildYaml();
+        return {
+          ok: true,
+          data: {
+            yaml: r.yaml,
+            warnings: r.warnings,
+            chains: r.chains,
+            upstreams: r.upstreams.map(({ name, providerId, baseUrl, prefix }) => ({
+              name, providerId, baseUrl, prefix,
+            })),
+          },
+        };
+      }
+
+      // ---- 【需求3】保存并下发降级链给网关 ----
+      case 'routes/apply': {
+        // 允许「边保存边下发」：UI 可先传 agents 再 apply
+        if (args?.profileId && args?.agents) {
+          await store.replaceProfile(args.profileId, args.agents);
+        }
+        const r = await applyChains({ restart: args?.restart !== false });
+        return { ok: r.ok, data: r, error: r.ok ? undefined : r.error };
+      }
+
+      // ---- 【需求4】一键探针：测当前 profile 选中的那组模型 ----
+      case 'probe/profile': {
+        const routes = store.get().routes;
+        const pid = routes[args.profileId] ? args.profileId : Object.keys(routes)[0];
+        const agentType = AGENT_TYPES.includes(args.agentType) ? args.agentType : 'root';
+        const models = chainModelIds(routes, pid, agentType);
+        if (!models.length) {
+          return {
+            ok: false,
+            error: `profile ${pid} 的 ${agentType} 链还没有选模型。请先在「路由配置」里从 DSH 模型池选好模型。`,
+          };
+        }
+        const batchId = `probe-${Date.now()}`;
+        const res = await gateway.probeBatch({
+          models,
+          agentType,
+          profile: pid,
+          concurrency: 2,
+          timeoutMs: Math.min(120000, Math.max(15000, Number(args.timeoutMs) || 60000)),
+          onResult: (entry) => {
+            if (!entry.ok) {
+              probeLog.add({
+                model: entry.model,
+                ok: false,
+                latencyMs: entry.latencyMs,
+                error: entry.error,
+                agentType,
+                profile: pid,
+                batchId,
+              });
+            }
+          },
+        });
+        if (!res.ok) return { ok: false, error: res.error };
+        return {
+          ok: true,
+          data: {
+            ...res.data,
+            batchId,
+            profile: pid,
+            agentType,
+            chain: models,
+            // 按链路顺序展示，让用户看到「第 1 顺位 / 第 2 顺位」
+            ordered: res.data.results.map((r) => ({ ...r, position: models.indexOf(r.model) + 1 })),
+          },
+        };
+      }
+
+      // 单模型探针（保留：会话 Tab 的「一键探针」用链头）
+      case 'probe/run': {
+        const routes = store.get().routes;
+        const pid = routes[args.profileId] ? args.profileId : Object.keys(routes)[0];
+        const agentType = AGENT_TYPES.includes(args.agentType) ? args.agentType : 'root';
+        const chain = chainModelIds(routes, pid, agentType);
+        const model = args.model || chain[0];
+        if (!model) {
+          return { ok: false, error: '当前 profile 该链未选模型，无法探针' };
+        }
+        const res = await gateway.probe({ model, agentType, profile: pid });
+        return res.ok
+          ? { ok: true, data: res.data, latencyMs: res.latencyMs }
+          : { ok: false, error: res.error, latencyMs: res.latencyMs, emptyReply: res.emptyReply };
+      }
+
+      // ---- 日志面板（需求5 + 需求7 网关状态）----
+      case 'logs/fetch': {
+        const limit = args.limit || store.get().gateway.logLimit || 50;
+        const res = await gateway.fetchLogs({ limit });
+        const local = probeLog.list(limit);
+        const gw = supervisor.status();
+        const alive = await isGatewayAlive(store.get().gateway.url);
+        if (!res.ok) {
+          return {
+            ok: true,
+            data: local,
+            gatewayError: res.error,
+            needsDatabase: Boolean(res.needsDatabase),
+            localOnly: true,
+            gateway: {
+              state: gw.state === 'error' ? 'error' : alive ? 'running' : 'stopped',
+              alive,
+              owned: gw.owned,
+              lastError: gw.lastError,
+              lastExit: gw.lastExit,
+            },
+          };
+        }
+        const merged = [...(res.data || []), ...local]
+          .sort((a, b) => (Date.parse(b.time || 0) || 0) - (Date.parse(a.time || 0) || 0))
+          .slice(0, limit);
+        return {
+          ok: true,
+          data: merged,
+          gateway: {
+            state: gw.state === 'error' ? 'error' : alive ? 'running' : 'stopped',
+            alive,
+            owned: gw.owned,
+            lastError: gw.lastError,
+            lastExit: gw.lastExit,
+          },
+        };
+      }
+
+      case 'logs/clearLocal':
+        probeLog.clearAll();
+        return { ok: true, data: { cleared: true } };
+
+      // ---- 会话 profile ----
+      case 'session/getProfile':
+        return { ok: true, data: getSessionProfile(ctx, args.sessionId) };
+
+      case 'session/setProfile': {
+        const value = String(args.profile || '').trim();
+        // 绑定的 profile 必须真实存在，否则会话会指向一条不存在的链
+        if (value && !store.get().routes[value]) {
+          return { ok: false, error: `profile 不存在：${value}` };
+        }
+        const written = setSessionProfile(ctx, args.sessionId, value);
+        ctx.emit?.('litellm-bridge/session-profile-changed', {
+          sessionId: args.sessionId,
+          profile: value,
+        });
+        return { ok: true, data: { profile: value, persisted: written } };
+      }
+
+      // ---- 子代理路由覆盖状态 ----
+      case 'routing/status':
+        return {
+          ok: true,
+          data: {
+            nativeProviders: routing.nativeProviders || NATIVE_PROVIDERS,
+            gatewayProvider: routing.gatewayProvider || GATEWAY_PROVIDER,
+            stats: routing.stats(),
+            sessionProvider: args.sessionId ? getSessionProvider(String(args.sessionId)) || null : null,
+          },
+        };
+
+      default:
+        return { ok: false, error: `未知操作: ${action}` };
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // HTTP 路由（客户端 RPC 入口）
+  //
+  // 前缀刻意不是 /api（那是 dsh-api-gateway 的领地，实测 404）。
+  // -------------------------------------------------------------------------
+  const webServer = (() => {
+    try {
+      return typeof ctx.get === 'function' ? ctx.get('webServer') : ctx.webServer;
+    } catch {
+      return undefined;
+    }
+  })();
+
+  if (webServer && typeof webServer.register === 'function') {
+    ctx.effect?.(() =>
+      webServer.register({
+        kind: 'prefix',
+        path: ROUTE_BASE,
+        handler: async (req, res) => {
+          const send = (status, payload) => {
+            try {
+              const body = JSON.stringify(payload);
+              res.writeHead(status, {
+                'Content-Type': 'application/json; charset=utf-8',
+                'Cache-Control': 'no-store',
+              });
+              res.end(body);
+            } catch (err) {
+              try { res.destroy?.(err); } catch { /* ignore */ }
+            }
+          };
+
+          try {
+            if (req.method !== 'POST') {
+              res.writeHead(405, { Allow: 'POST', 'Content-Type': 'application/json' });
+              res.end(JSON.stringify({ ok: false, error: '只接受 POST' }));
+              return;
+            }
+
+            const urlPath = String(req.url || '').split('?')[0];
+            const tail = urlPath.startsWith(ROUTE_BASE)
+              ? urlPath.slice(ROUTE_BASE.length).replace(/^\/+/, '')
+              : '';
+
+            const chunks = [];
+            let size = 0;
+            for await (const chunk of req) {
+              size += chunk.length;
+              if (size > 1024 * 1024) {
+                send(413, { ok: false, error: '请求体过大' });
+                return;
+              }
+              chunks.push(chunk);
+            }
+            const raw = Buffer.concat(chunks).toString('utf8');
+            let payload = {};
+            try { payload = raw ? JSON.parse(raw) : {}; } catch { payload = {}; }
+
+            let action = tail;
+            if (!action && payload?.action) action = String(payload.action);
+            const args = payload?.args ?? payload ?? {};
+            send(200, await handle(action, args));
+          } catch (err) {
+            send(200, { ok: false, error: String(err?.message || err) });
+          }
+        },
+      }),
+    );
+    ctx.logger?.info?.(`[litellm-bridge] 已注册 RPC 路由 ${ROUTE_BASE}`);
+  } else {
+    ctx.logger?.warn?.('[litellm-bridge] webServer 不可用，UI 将无法访问宿主能力');
+  }
+
+  // -------------------------------------------------------------------------
+  // 与 header-inject 解耦：**只用事件，不用跨插件服务**
+  //
+  // 【为什么改掉了 ctx.set('litellmBridge')】
+  //   cordis 对 ctx.set 有强校验：目标 key 必须在插件导出的 `provide` 里，
+  //   否则整个插件在激活阶段直接失败，报
+  //     cannot set property 'litellmBridge' without provide
+  //   实测（本机 DSH）：`provide = ['litellm-bridge', 'litellmBridge']` 仍被拒，
+  //   而对照 dsh-connect-trae / dsh-qq-plugin / dsh-infinite-canvas 等能正常
+  //   工作的插件，**没有一个用 provide + ctx.set 对外暴露服务**。
+  //
+  //   而 header-inject 侧本来就写好了事件镜像兜底（它 on 这个事件做本地缓存），
+  //   所以去掉服务暴露不会降低功能，反而少了一个跨插件耦合点。
+  //
+  //   事件名保持 `litellm-bridge/session-profile-changed` 不变 ——
+  //   header-inject 已经在监听它，改了会静默失效。
+  // -------------------------------------------------------------------------
+  /** 当前状态快照（header-inject 需要时通过事件拿到，也可自行缓存）。 */
+  function statusSnapshot() {
+    return {
+      gatewayProvider: config.gatewayProvider || GATEWAY_PROVIDER,
+      nativeProviders: config.nativeProviders || NATIVE_PROVIDERS,
+      gateway: supervisor.status(),
+    };
+  }
+
+  // 启动时广播一次完整状态，让 header-inject 无需轮询即可缓存
+  void ensureReady().then(() => {
+    try {
+      ctx.emit?.('litellm-bridge/ready', statusSnapshot());
+    } catch { /* 广播失败不影响插件本身 */ }
+  });
+
+  // -------------------------------------------------------------------------
+  // 生命周期：不阻塞激活，后台拉起网关
+  // -------------------------------------------------------------------------
+  void ensureReady().then(() => {
+    if (config.autoStartGateway === false) {
+      ctx.logger?.info?.('[litellm-bridge] autoStartGateway=false，只连接不托管网关');
+      return;
+    }
+    void supervisor.ensureRunning().then((r) => {
+      if (r.running) {
+        ctx.logger?.info?.(
+          `[litellm-bridge] 网关就绪 ${supervisor.gatewayUrl}（${r.started ? '由本插件启动，退出时自动关闭' : '外部已在运行，不接管'}）`,
+        );
+      } else {
+        ctx.logger?.warn?.(`[litellm-bridge] 网关未就绪: ${r.error || '未知原因'}`);
+      }
+    });
+  });
+
+  // 插件卸载（DSH 退出 / 禁用）时停掉自己启动的网关
+  ctx.effect?.(() => async () => {
+    try { await supervisor.stop(); } catch { /* 清理失败不影响 DSH 退出 */ }
+  });
+
+  void ensureReady().then(() => {
+    ctx.logger?.info?.(
+      `[litellm-bridge] 就绪。网关=${gateway.baseUrl} key=${gateway.hasKey ? '来自 .env 环境变量' : '未配置'}`,
+    );
+  });
+}