mslxdff 0.1.227 → 0.1.229

package/src/providers/cline/allowlist-sync.js

@@ -1,21 +1,20 @@
 /**
- * Cline 白名单自动同步（上游列表 = 真相）。
+ * Cline 白名单自动同步（上游目录 = 真相，双向收敛）。
  *
- * 背景：`providerConfigs.cline.allowedModels` 是一份**静态快照**（历史由 `-provider cline free sync --yes` 一次性写入）。
- * 上游 `recommended-models` 会漂移——新模型上架免费通道、同一模型从 `cline-pass/` 挪到 `cline-free/`——
- * 而静态快照不跟着变，于是 `isModelAllowed()` 精确匹配失败，把上游明明免费可用的模型当成"未授权"拦掉
- * （实测 2026-09-24：`cline-free/gemini-3.8-flash`、`stealth/space-bunny-alpha`、`cline-free/mimo-v2.6-flash` 被拦，
- *  而 allowlist 里只有 `cline-pass/mimo-v2.6-flash`，通道不同即视为不同 id）。
- *
- * 本模块把语义改成「每次成功读取上游列表后，立即把上游 id 并进白名单」：
- *   - **只增不减**：上游下架的 id 保留在表内（与 modelPicks 孤儿"仅标记不自动删"的既有口径一致，回收走 prune），
- *     避免同步动作变成删配置。
- *   - **仅在上游成功路径调用**：内置兜底常量不是上游真相，写盘只会污染（由调用方保证，见 models.js）。
- *   - **无新增不写盘**：上游 10 分钟缓存内反复命中同一列表时零写放大。
+ * 背景：`providerConfigs.cline.allowedModels` 曾是静态快照，上游漂移后两种偏差都会伤人：
+ *   ① 新上架/换通道的免费模型被静态快照拦成 blocked（2026-09-24 实测三例）；
+ *   ② 已下架的免费模型长期赖在白名单里，调用即 `404 model not found`（2026-10-21 实测 6 例）。
+ * 本模块把语义定为「**上游 free 目录即真相**」：
+ *   - **双向收敛**：free 目录新增的并入，free 目录消失的移除；
+ *   - **范围只有 free 通道**：`freeCatalogPrefixes`（缺省 `cline-free/…` 与其它 `-free`/`:free` 形态）
+ *     是唯一可被自动移除的命名空间。`cline-pass/*`、`meta/*`、`stealth/*`、用户手填 id 一律不动——
+ *     它们不在 free 目录里是正常的（目录接口本来只返回 free），移除会误删付费/手配模型。
+ *   - **只在上游成功路径调用**：内置兜底常量不是上游真相，写盘只会污染（由调用方保证，见 models.js）。
+ *   - **无变化不写盘**：10 分钟缓存内反复命中同一列表时零写放大。
  * 关掉：`MSLXDFF_CLINE_AUTOSYNC=0`（退回纯静态白名单行为）。
- * Note: 只增不减 + 仅上游成功路径同步的取舍见 .agents/notes/implemented/feature/2026-09-24-cline-auto-sync-free-catalog.md
+ * Note: 双向收敛的取舍见 .agents/notes/implemented/feature/2026-09-24-cline-auto-sync-free-catalog.md 与 docs/adr/0067-cline-free-catalog-bidirectional-sync.md。
  *
- * 纯逻辑（planMerge）无 IO，可单测；IO 全走注入。
+ * 纯逻辑（planSync）无 IO，可单测；IO 全走注入。
  */
 
 /** 与 state/provider-config.js 的 normalizeAllowedModel 对齐：只剥首段等于 providerId 的前缀。调用方可注入同名函数保证单一真相。 */
@@ -28,25 +27,59 @@ export function defaultNormalize(model, providerId) {
 }
 
 /**
- * 求并集：保留 current 原顺序与全部既有条目，把 upstreamIds 中缺失的追加到尾部。
+ * free 通道命名空间判据（裸 id）：`cline-free/<x>`、任意前缀下的 `*-free`、任意 `:free` 变体。
+ * 只有落在这个集合里的既有条目才允许被自动移除；目录里出现的新 id 不设限（上游说免费即免费）。
+ */
+export function isFreeChannelId(id) {
+  const s = String(id || "").trim().toLowerCase();
+  if (!s) return false;
+  if (s.startsWith("cline-free/")) return true;
+  if (s.includes(":free")) return true;
+  if (s.endsWith("-free") || s.endsWith("_free")) return true;
+  return false;
+}
+
+/**
+ * 求新白名单：先剔掉「属于 free 通道但已不在上游目录」的条目，再把上游新 id 追加到尾部。
  * @param {string[]} current 当前白名单（裸 id）
- * @param {string[]} upstreamIds 上游模型 id（可带 provider 前缀，内部归一）
- * @param {(m:string, pid:string)=>string} [normalize]
- * @param {string} [providerId]
- * @returns {{next:string[], added:string[]}}
+ * @param {string[]} upstreamIds 上游 free 目录 id（可带 provider 前缀，内部归一）
+ * @param {{normalize?:Function, providerId?:string, isFreeChannel?:(bare:string)=>boolean}} [opts]
+ * @returns {{next:string[], added:string[], removed:string[]}}
  */
-export function planMerge(current, upstreamIds, normalize = defaultNormalize, providerId = "") {
+export function planSync(current, upstreamIds, opts = {}) {
+  const { normalize = defaultNormalize, providerId = "", isFreeChannel = isFreeChannelId } = opts;
   const cur = Array.isArray(current) ? current : [];
-  const next = [...new Set(cur.map((m) => normalize(m, providerId)).filter(Boolean))];
-  const seen = new Set(next);
+  const ups = (Array.isArray(upstreamIds) ? upstreamIds : [])
+    .map((raw) => normalize(raw, providerId))
+    .filter(Boolean);
+  const upstream = new Set(ups);
+  const next = [];
+  const seen = new Set();
+  const removed = [];
+  for (const raw of cur) {
+    const bare = normalize(raw, providerId);
+    if (!bare) continue;
+    if (seen.has(bare)) continue;
+    if (isFreeChannel(bare) && !upstream.has(bare)) {
+      removed.push(bare);
+      continue;
+    }
+    seen.add(bare);
+    next.push(bare);
+  }
   const added = [];
-  for (const raw of Array.isArray(upstreamIds) ? upstreamIds : []) {
-    const norm = normalize(raw, providerId);
-    if (!norm || seen.has(norm)) continue;
-    seen.add(norm);
-    next.push(norm);
-    added.push(norm);
+  for (const bare of ups) {
+    if (seen.has(bare)) continue;
+    seen.add(bare);
+    next.push(bare);
+    added.push(bare);
   }
+  return { next, added, removed };
+}
+
+/** 兼容旧名：只并集不改动既有条目（含 free 下架项）。保留导出供历史调用方/测试使用。 */
+export function planMerge(current, upstreamIds, normalize = defaultNormalize, providerId = "") {
+  const { next, added } = planSync(current, upstreamIds, { normalize, providerId, isFreeChannel: () => false });
   return { next, added };
 }
 
@@ -57,9 +90,10 @@ export function planMerge(current, upstreamIds, normalize = defaultNormalize, pr
  * @param {(id:string, list:string[]) => unknown} opts.persist 写回白名单
  * @param {(msg:string) => void} [opts.onLog]
  * @param {(m:string, pid:string)=>string} [opts.normalize]
+ * @param {(bare:string)=>boolean} [opts.isFreeChannel]
  * @param {boolean} [opts.enabled] 显式覆盖 env 开关
  */
-export function createAllowlistSync({ providerId, loadCurrent, persist, onLog, normalize = defaultNormalize, enabled } = {}) {
+export function createAllowlistSync({ providerId, loadCurrent, persist, onLog, normalize = defaultNormalize, isFreeChannel = isFreeChannelId, enabled } = {}) {
   const isEnabled = () => {
     if (typeof enabled === "boolean") return enabled;
     return String(process.env.MSLXDFF_CLINE_AUTOSYNC ?? "") !== "0";
@@ -67,25 +101,29 @@ export function createAllowlistSync({ providerId, loadCurrent, persist, onLog, n
   const log = (msg) => { try { onLog?.(msg); } catch {} };
 
   /**
-   * 把一批上游模型并进白名单。
+   * 把一批上游 free 模型同步进白名单（新增并入、free 通道下架移除）。
    * @param {{id?:string}[]|string[]} models 上游模型对象数组或 id 数组
-   * @returns {{skipped:string, added:string[], total:number}}
+   * @returns {{skipped:string, added:string[], removed:string[], total:number}}
    */
   function syncIds(models) {
-    if (!isEnabled()) return { skipped: "disabled", added: [], total: 0 };
-    if (!Array.isArray(models) || !models.length) return { skipped: "empty", added: [], total: 0 };
+    if (!isEnabled()) return { skipped: "disabled", added: [], removed: [], total: 0 };
+    if (!Array.isArray(models) || !models.length) return { skipped: "empty", added: [], removed: [], total: 0 };
     try {
       const ids = models.map((m) => (typeof m === "string" ? m : m?.id)).filter(Boolean);
       const cur = loadCurrent() || [];
-      const { next, added } = planMerge(cur, ids, normalize, providerId);
-      if (!added.length) return { skipped: "", added: [], total: next.length };
+      const { next, added, removed } = planSync(cur, ids, { normalize, providerId, isFreeChannel });
+      if (!added.length && !removed.length) return { skipped: "", added: [], removed: [], total: next.length };
       persist(providerId, next);
-      log(`[${providerId}] allowlist auto-sync: +${added.length} → ${next.length} total (${added.join(", ")})`);
-      return { skipped: "", added, total: next.length };
+      const parts = [];
+      if (added.length) parts.push(`+${added.length}`);
+      if (removed.length) parts.push(`-${removed.length}`);
+      log(`[${providerId}] allowlist auto-sync: ${parts.join("/")} → ${next.length} total${
+        added.length ? ` (added: ${added.join(", ")})` : ""}${removed.length ? ` (removed: ${removed.join(", ")})` : ""}`);
+      return { skipped: "", added, removed, total: next.length };
     } catch (err) {
       // 同步是增益动作，失败绝不打断模型列表读取与请求链路
       log(`[${providerId}] allowlist auto-sync failed: ${String(err?.message || err)}`);
-      return { skipped: "error", added: [], total: 0 };
+      return { skipped: "error", added: [], removed: [], total: 0 };
     }
   }
 

package/src/providers/cline/free-catalog.js

@@ -9,13 +9,16 @@ import { joinUrl } from "../base.js";
 export const FREE_CATALOG_PATH = "/api/v1/ai/cline/recommended-models";
 export const DEFAULT_CLINE_BASE = "https://api.cline.bot";
 
-// 上游不可达时的内置兜底（2026-09-20 实测 5 个；只有 id 与短名，无凭据）
+// 上游不可达时的内置兜底（2026-10-21 实测 6 个；只有 id 与短名，无凭据）。
+// 旧兜底 5 个里 deepseek-v4.1-flash/solar-pro4/muse-spark-1.3-contributor/glm-5.3-flash 已下架或转付费，
+// 现网实测 404 model not found / 402 insufficient_credits，不得再兜。
 export const FALLBACK_FREE = Object.freeze([
-  { id: "cline-free/deepseek-v4.1-flash", name: "deepseek-v4.1-flash" },
-  { id: "cline-free/muse-spark-1.3-contributor", name: "muse-spark-1.3-contributor" },
-  { id: "z-ai/glm-5.3-flash", name: "glm-5.3-flash" },
-  { id: "cline-free/solar-pro4", name: "solar-pro4" },
-  { id: "poolside/laguna-s-2.1:free", name: "laguna-s-2.1:free" },
+  { id: "cline-free/minimax-m3.1-flash", name: "minimax-m3.1-flash" },
+  { id: "cline-free/solar-mini4", name: "solar-mini4" },
+  { id: "cline-free/nemotron-3.5-super-vl", name: "nemotron-3.5-super-vl" },
+  { id: "reflection/beam-free", name: "beam-free" },
+  { id: "nvidia/nemotron-3.5-lightning-free", name: "nemotron-3.5-lightning-free" },
+  { id: "poolside/laguna-s-2.1-free", name: "laguna-s-2.1-free" },
 ]);
 export const FALLBACK_FREE_IDS = FALLBACK_FREE.map((m) => m.id);
 

package/src/providers/dispatcher.js

@@ -1,147 +1,147 @@
- import { appendEvent } from "../logs.js";
- import { splitModelId, DEFAULT_PROVIDER, joinModelId } from "./model-id.js";
- import { isModelAllowed as stateIsAllowed, loadProviderAllowedModels as stateLoadAllowed, loadProviderAllowAnyModels as stateLoadAllowAny } from "../state.js";
-// 定制预热名单：registry customProviders 9 家 + 默认 opencode；openrouter/自配 generic 不预热（按需自拉）
-const CUSTOM_PREHEAT_IDS = new Set(["opencode", "workbuddy", "traework", "cline", "codearts", "qoder", "globalqwenwork", "qwenwork", "zcode", "raccoon"]);
- function isPreheatDisabled() {
-   const raw = process.env.MSLXDFF_PREHEAT;
-   if (raw === undefined || raw === null || raw === "") return false;
-   const s = String(raw).trim().toLowerCase();
-   return s === "0" || s === "off" || s === "false" || s === "no" || s === "disable" || s === "disabled";
- }
-
-// 多供应商 dispatcher：把多个 Provider 聚合成一个 `upstream` 形状（chat/preheat/close），
-// 按 body.model 的前缀路由到对应供应商，转发上游前剥掉前缀只发原始 id。
-// 纯化：第二参可注入纯函数 isAllowed/getAllowed/getAllowAny，便于单测不读盘
-export function createProviderDispatcher(providers = [], opts = {}) {
-  const byId = new Map(providers.map((p) => [p.id, p]));
-  // 纯化注入：第二参可为 {isAllowed, getAllowedModels, getAllowAny} 或直接函数 isAllowed
-  let isAllowedFn, getAllowedFn, getAllowAnyFn;
-  if (typeof opts === "function") {
-    isAllowedFn = opts;
-    getAllowedFn = stateLoadAllowed;
-    getAllowAnyFn = stateLoadAllowAny;
-  } else {
-    isAllowedFn = opts.isAllowed || stateIsAllowed;
-    getAllowedFn = opts.getAllowedModels || stateLoadAllowed;
-    getAllowAnyFn = opts.getAllowAny || stateLoadAllowAny;
-  }
-
-  function resolve(model) {
-    const split = splitModelId(model, providers.map((p) => p.id));
-    return {
-      provider: byId.get(split.provider) ?? byId.get(DEFAULT_PROVIDER) ?? providers[0],
-      raw: split.raw,
-      prefixed: split.prefixed,
-    };
-  }
-
-  async function chat(body, opts = {}) {
-    let { provider, raw } = resolve(body?.model);
-    if (!provider) throw new Error(`no provider for model ${body?.model ?? "(empty)"}`);
-    let workbuddyUid = opts?.workbuddyUid ? String(opts.workbuddyUid).trim() : "";
-    // model 前缀钉死：workbuddy/<uid>:<rawId>  -> 剥 uid，rawId 为真实模型
-    if (provider.id === "workbuddy" && typeof raw === "string" && raw.includes(":")) {
-      const idx = raw.indexOf(":");
-      const uidPart = raw.slice(0, idx).trim();
-      const modelPart = raw.slice(idx + 1).trim();
-      if (uidPart && modelPart) {
-        if (!workbuddyUid) workbuddyUid = uidPart;
-        raw = modelPart;
-      }
-    }
-    if (!isAllowedFn(provider.id, raw)) {
-      const allowed = getAllowedFn(provider.id) || [];
-      const msg = `model not allowed for provider "${provider.id}": "${raw}" — allowed: ${allowed.join(", ") || "(none)"} (use: mslxdff -provider ${provider.id} allowlist add <model>)`;
-      appendEvent({ type: "provider-model-state", provider: provider.id, model: body?.model, rawModel: raw, state: "blocked", reason: "allowlist", status: 403 });
-      return new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json", "x-mslxdff-allowlist": "1" } });
-    }
-    const forwarded = raw === body?.model ? body : { ...body, model: raw };
-    // ADR-0008：本请求携带瞬时共享 key（shareKeys 由组员侧按 header 解析后传入）。
-    const sharedKeys = opts?.shareKeys?.[provider.id];
-    const startedAt = Date.now();
-    let res;
-    try {
-      if (sharedKeys && sharedKeys.length && typeof provider.chatWithKeys === "function") {
-        res = await provider.chatWithKeys(forwarded, sharedKeys, opts);
-      } else if (provider.id === "workbuddy" && workbuddyUid) {
-        res = await provider.chat(forwarded, { ...opts, workbuddyUid });
-      } else {
-        res = await provider.chat(forwarded, opts);
-      }
-    } catch (err) {
-      appendEvent({ type: "provider-model-state", provider: provider.id, model: body?.model, rawModel: raw, state: "upstream-error", error: String(err?.message || err), durationMs: Date.now() - startedAt });
-      throw err;
-    }
-    appendEvent({
-      type: "provider-model-state",
-      provider: provider.id,
-      model: body?.model,
-      rawModel: raw,
-      status: res?.status,
-      state: res?.status === 429 ? "limited" : res?.ok ? "ok" : "upstream-error",
-      durationMs: Date.now() - startedAt,
-    });
-    return res;
-  }
-
-  // 聚合所有供应商的模型列表；默认供应商（opencode）裸 id，其它带前缀
-  // 若某供应商设置了 allowlist（非空），则仅暴露白名单内的模型（按 raw id 匹配）
-  async function listModels() {
-    const out = [];
-    const seen = new Set();
-    for (const p of providers) {
-      let list;
-      try {
-        list = (await p.listModels?.()) ?? [];
-      } catch {
-        list = [];
-      }
-      const allowed = getAllowedFn(p.id) || [];
-      const allowAny = getAllowAnyFn(p.id);
-      const allowedSet = allowed.length ? new Set(allowed) : null;
-      // 空名单且不允许任意模型 => 该供应商不暴露任何模型（安全默认）
-      if (!allowedSet && !allowAny) continue;
-      for (const m of list) {
-        if (!m || !m.id) continue;
-        if (seen.has(m.id)) continue;
-        if (allowedSet) {
-          // m.id 已是带前缀的对外 id，需剥回 raw 再比对
-          const { raw } = splitModelId(m.id, providers.map((x) => x.id));
-          const rawNorm = String(raw || "").trim();
-          if (!allowedSet.has(rawNorm)) continue;
-          // 对于 opencode 裸 id，rawNorm 即 m.id 本身
-        }
-        seen.add(m.id);
-        out.push(m);
-      }
-    }
-    return out;
-  }
-
-  // 预热定制供应商 + 默认供应商（opencode）：registry 名单 8 家 + opencode 共 9 家并发各打一次；
-  // openrouter/用户自配 generic 不在此列（按需首次请求自拉）。单家失败静默，不拖累启动。
-  async function preheat() {
-    if (isPreheatDisabled()) return { ok: true, skipped: true };
-    const targets = providers.filter((p) => p && typeof p.preheat === "function" && CUSTOM_PREHEAT_IDS.has(p.id));
-    if (!targets.length) return { ok: false, skipped: true };
-    const settled = await Promise.all(targets.map(async (p) => {
-      try {
-        const r = await p.preheat();
-        return { id: p.id, ...(r && typeof r === "object" ? r : { ok: false }) };
-      } catch {
-        return { id: p.id, ok: false, error: "preheat failed" };
-      }
-    }));
-    const okCount = settled.filter((r) => r && r.ok).length;
-    return { ok: okCount > 0, results: settled, okCount, total: settled.length };
-  }
-
-  async function close() {
-    for (const p of providers) {
-      try { await p.close?.(); } catch {}
-    }
-  }
-
-  return { providers, byId, resolve, listModels, chat, preheat, close, joinModelId };
+ import { appendEvent } from "../logs.js";
+ import { splitModelId, DEFAULT_PROVIDER, joinModelId } from "./model-id.js";
+ import { isModelAllowed as stateIsAllowed, loadProviderAllowedModels as stateLoadAllowed, loadProviderAllowAnyModels as stateLoadAllowAny } from "../state.js";
+// 定制预热名单：registry customProviders 9 家 + 默认 opencode；openrouter/自配 generic 不预热（按需自拉）
+const CUSTOM_PREHEAT_IDS = new Set(["opencode", "workbuddy", "traework", "cline", "codearts", "qoder", "globalqwenwork", "qwenwork", "zcode", "raccoon", "agentrouter"]);
+ function isPreheatDisabled() {
+   const raw = process.env.MSLXDFF_PREHEAT;
+   if (raw === undefined || raw === null || raw === "") return false;
+   const s = String(raw).trim().toLowerCase();
+   return s === "0" || s === "off" || s === "false" || s === "no" || s === "disable" || s === "disabled";
+ }
+
+// 多供应商 dispatcher：把多个 Provider 聚合成一个 `upstream` 形状（chat/preheat/close），
+// 按 body.model 的前缀路由到对应供应商，转发上游前剥掉前缀只发原始 id。
+// 纯化：第二参可注入纯函数 isAllowed/getAllowed/getAllowAny，便于单测不读盘
+export function createProviderDispatcher(providers = [], opts = {}) {
+  const byId = new Map(providers.map((p) => [p.id, p]));
+  // 纯化注入：第二参可为 {isAllowed, getAllowedModels, getAllowAny} 或直接函数 isAllowed
+  let isAllowedFn, getAllowedFn, getAllowAnyFn;
+  if (typeof opts === "function") {
+    isAllowedFn = opts;
+    getAllowedFn = stateLoadAllowed;
+    getAllowAnyFn = stateLoadAllowAny;
+  } else {
+    isAllowedFn = opts.isAllowed || stateIsAllowed;
+    getAllowedFn = opts.getAllowedModels || stateLoadAllowed;
+    getAllowAnyFn = opts.getAllowAny || stateLoadAllowAny;
+  }
+
+  function resolve(model) {
+    const split = splitModelId(model, providers.map((p) => p.id));
+    return {
+      provider: byId.get(split.provider) ?? byId.get(DEFAULT_PROVIDER) ?? providers[0],
+      raw: split.raw,
+      prefixed: split.prefixed,
+    };
+  }
+
+  async function chat(body, opts = {}) {
+    let { provider, raw } = resolve(body?.model);
+    if (!provider) throw new Error(`no provider for model ${body?.model ?? "(empty)"}`);
+    let workbuddyUid = opts?.workbuddyUid ? String(opts.workbuddyUid).trim() : "";
+    // model 前缀钉死：workbuddy/<uid>:<rawId>  -> 剥 uid，rawId 为真实模型
+    if (provider.id === "workbuddy" && typeof raw === "string" && raw.includes(":")) {
+      const idx = raw.indexOf(":");
+      const uidPart = raw.slice(0, idx).trim();
+      const modelPart = raw.slice(idx + 1).trim();
+      if (uidPart && modelPart) {
+        if (!workbuddyUid) workbuddyUid = uidPart;
+        raw = modelPart;
+      }
+    }
+    if (!isAllowedFn(provider.id, raw)) {
+      const allowed = getAllowedFn(provider.id) || [];
+      const msg = `model not allowed for provider "${provider.id}": "${raw}" — allowed: ${allowed.join(", ") || "(none)"} (use: mslxdff -provider ${provider.id} allowlist add <model>)`;
+      appendEvent({ type: "provider-model-state", provider: provider.id, model: body?.model, rawModel: raw, state: "blocked", reason: "allowlist", status: 403 });
+      return new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json", "x-mslxdff-allowlist": "1" } });
+    }
+    const forwarded = raw === body?.model ? body : { ...body, model: raw };
+    // ADR-0008：本请求携带瞬时共享 key（shareKeys 由组员侧按 header 解析后传入）。
+    const sharedKeys = opts?.shareKeys?.[provider.id];
+    const startedAt = Date.now();
+    let res;
+    try {
+      if (sharedKeys && sharedKeys.length && typeof provider.chatWithKeys === "function") {
+        res = await provider.chatWithKeys(forwarded, sharedKeys, opts);
+      } else if (provider.id === "workbuddy" && workbuddyUid) {
+        res = await provider.chat(forwarded, { ...opts, workbuddyUid });
+      } else {
+        res = await provider.chat(forwarded, opts);
+      }
+    } catch (err) {
+      appendEvent({ type: "provider-model-state", provider: provider.id, model: body?.model, rawModel: raw, state: "upstream-error", error: String(err?.message || err), durationMs: Date.now() - startedAt });
+      throw err;
+    }
+    appendEvent({
+      type: "provider-model-state",
+      provider: provider.id,
+      model: body?.model,
+      rawModel: raw,
+      status: res?.status,
+      state: res?.status === 429 ? "limited" : res?.ok ? "ok" : "upstream-error",
+      durationMs: Date.now() - startedAt,
+    });
+    return res;
+  }
+
+  // 聚合所有供应商的模型列表；默认供应商（opencode）裸 id，其它带前缀
+  // 若某供应商设置了 allowlist（非空），则仅暴露白名单内的模型（按 raw id 匹配）
+  async function listModels() {
+    const out = [];
+    const seen = new Set();
+    for (const p of providers) {
+      let list;
+      try {
+        list = (await p.listModels?.()) ?? [];
+      } catch {
+        list = [];
+      }
+      const allowed = getAllowedFn(p.id) || [];
+      const allowAny = getAllowAnyFn(p.id);
+      const allowedSet = allowed.length ? new Set(allowed) : null;
+      // 空名单且不允许任意模型 => 该供应商不暴露任何模型（安全默认）
+      if (!allowedSet && !allowAny) continue;
+      for (const m of list) {
+        if (!m || !m.id) continue;
+        if (seen.has(m.id)) continue;
+        if (allowedSet) {
+          // m.id 已是带前缀的对外 id，需剥回 raw 再比对
+          const { raw } = splitModelId(m.id, providers.map((x) => x.id));
+          const rawNorm = String(raw || "").trim();
+          if (!allowedSet.has(rawNorm)) continue;
+          // 对于 opencode 裸 id，rawNorm 即 m.id 本身
+        }
+        seen.add(m.id);
+        out.push(m);
+      }
+    }
+    return out;
+  }
+
+  // 预热定制供应商 + 默认供应商（opencode）：registry 名单 8 家 + opencode 共 9 家并发各打一次；
+  // openrouter/用户自配 generic 不在此列（按需首次请求自拉）。单家失败静默，不拖累启动。
+  async function preheat() {
+    if (isPreheatDisabled()) return { ok: true, skipped: true };
+    const targets = providers.filter((p) => p && typeof p.preheat === "function" && CUSTOM_PREHEAT_IDS.has(p.id));
+    if (!targets.length) return { ok: false, skipped: true };
+    const settled = await Promise.all(targets.map(async (p) => {
+      try {
+        const r = await p.preheat();
+        return { id: p.id, ...(r && typeof r === "object" ? r : { ok: false }) };
+      } catch {
+        return { id: p.id, ok: false, error: "preheat failed" };
+      }
+    }));
+    const okCount = settled.filter((r) => r && r.ok).length;
+    return { ok: okCount > 0, results: settled, okCount, total: settled.length };
+  }
+
+  async function close() {
+    for (const p of providers) {
+      try { await p.close?.(); } catch {}
+    }
+  }
+
+  return { providers, byId, resolve, listModels, chat, preheat, close, joinModelId };
 }