mslxdff 0.1.107 → 0.1.110

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mslxdff",
-  "version": "0.1.107",
+  "version": "0.1.110",
   "description": "测试项目，请勿使用。",
   "type": "module",
   "bin": {

package/src/chat-pipeline/index.js

@@ -4,6 +4,7 @@ import { planRoute } from "./planner.js";
 import { createEngine } from "./engine.js";
 import { runHook } from "../plugins.js";
 import { isFreeModel } from "../models.js";
+import { shouldUseGroupForModel } from "../state/schemas/use-group.js";
 import { clientIp, summarizePrompt } from "../routes/helpers.js";
 
 /**
@@ -85,7 +86,7 @@ export function createChatPipeline({ upstream, auto, logs, peers, groups, bus, t
 
     const plan = planRoute(policy, {
       candidates: order,
-      viaRoute: Boolean(!useAuto && requested.includes("/") && canForwardPeers) ? { via: true } : null,
+      viaRoute: Boolean(!useAuto && requested.includes("/") && canForwardPeers && shouldUseGroupForModel(requested)) ? { via: true } : null,
     });
     await engine.run(plan, {
       reqId, startedAt, req, res, body: req?.body, policy,

package/src/chat-pipeline/serial-trial.js

@@ -35,7 +35,7 @@ export async function runSerialTrial(ctx, deps = {}) {
   const workbuddyUid = ctx.workbuddyUid ?? ctx.policy?.workbuddyUid ?? null;
 
   let viaRouteLastErr = null;
-  if (!useAuto && requested && requested.includes("/") && canForwardPeers && !lockModel && peers) {
+  if (!useAuto && requested && requested.includes("/") && canForwardPeers && !lockModel && peers && shouldUseGroupForModel(requested)) {
     try {
       const vr = await viaRoute({ model: requested, body, peers, handlerCtx, evt, logCall, logError, mark, perf0, stages, startedAt, plugins, res, requested, useAuto, lockModel, auto });
       if (vr.handled) return { done: true };
@@ -131,7 +131,7 @@ export async function runSerialTrial(ctx, deps = {}) {
     }
     if (canForwardPeers) {
       if (!shouldUseGroupForModel(model)) {
-        evt("group-skip", { reqId, model, reason: "useGroup=off for opencode (peer)" });
+        evt("group-skip", { reqId, model, reason: "useGroup=off (peer)" });
       } else {
         const pr = await peerRelay({ model, body, lastErr, requested, useAuto, lockModel, auto, peers, handlerCtx, evt, logCall, mark, perf0, stages, startedAt, plugins, res });
         if (pr.handled) return { done: true };
@@ -139,7 +139,7 @@ export async function runSerialTrial(ctx, deps = {}) {
     }
     if (groups) {
       if (!shouldUseGroupForModel(model)) {
-        evt("group-skip", { reqId, model, reason: "useGroup=off for opencode (broadband)" });
+        evt("group-skip", { reqId, model, reason: "useGroup=off (broadband)" });
       } else {
         const br = await broadbandRelay({ model, body, hops, lastErr, requested, useAuto, lockModel, auto, groups, token, bus, logs, handlerCtx, evt, mark, perf0, stages, res, startedAt, plugins });
         if (br.handled) return { done: true };

package/src/cli/commands/sync.js

@@ -88,6 +88,8 @@ export async function handleSetto(args) {
           if (r.action === "inserted") inserted++; else updated++;
           prunedTotal += r.pruned || 0;
           console.log(`  ${r.action} "${r.id}" -> ${r.internal} @ ${file}`);
+          if (r.capsSummaryText) console.log(`      ${r.capsSummaryText}`);
+          if (r.upgraded) console.log(`      能力补齐 ${r.upgraded} 个旧条目`);
         }
         console.log(`synced to opencode: ${inserted} inserted, ${updated} updated, total ${list.length} @ ${file}`);
         if (prunedTotal) console.log(`  pruned ${prunedTotal} 个失效模型（未在 picks，不再于 opencode 显示）`);
@@ -158,6 +160,9 @@ export async function handleSetto(args) {
       const file = opencodeConfigPath();
       const r = await syncToOpencode({ id, token, port, file, keep: pruneKeep(), ensureAll: pruneKeep() });
       console.log(`synced to opencode: ${r.action} "${r.id}" @ ${file}`);
+      if (r.capsSummaryText) console.log(`  能力: ${r.capsSummaryText}`);
+      else console.log(`  能力: 未收录该模型的能力目录，条目仅含名称（不影响使用）`);
+      if (r.upgraded) console.log(`  能力补齐 ${r.upgraded} 个旧条目（此前仅含名称，已注入推理档位/读图/上下文）`);
       if (r.backfilled) console.log(`  backfilled ${r.backfilled} 个 picks 模型（此前 pick 了但未同步过，现已补齐）`);
       if (r.pruned) console.log(`  pruned ${r.pruned} 个失效模型（未在 picks，不再于 opencode 显示）`);
       console.log(`  url: http://127.0.0.1:${port}/v1`);

package/src/cli/commands/use-group.js

@@ -33,7 +33,7 @@ export async function handleUseGroup(args) {
     console.log(`  stored: ${stored ? "on" : "off"} (state.json useGroup)`);
     if (envVal !== null) console.log(`  env MSLXDFF_USE_GROUP=${envVal ? "on" : "off"} (overrides stored)`);
     console.log(`  default: on`);
-    console.log(`  usage: mslxdff -use-group on|off  (opencode 供应商本机失败时是否走组员网络，默认 on)`);
+    console.log(`  usage: mslxdff -use-group on|off  (本机失败时是否走组员网络，默认 on)`);
     console.log(`  env:   MSLXDFF_USE_GROUP=0|1  (优先级高于 state)`);
     process.exit(0);
   }
@@ -50,7 +50,7 @@ export async function handleUseGroup(args) {
 
   saveUseGroup(parsed);
   console.log(`use-group set to ${parsed ? "on" : "off"} (stored in state.json)`);
-  console.log(`  opencode 供应商：本机失败时 ${parsed ? "允许" : "不再"} 通过组员网络请求上游`);
-  if (!parsed) console.log(`  提示：opencode 请求将仅在本机重试，不再走 peer/broadband 组员中继`);
+  console.log(`  ${parsed ? "允许" : "不再允许"}走组员网络（via-route/hedge/peer/broadband，全部供应商）`);
+  if (!parsed) console.log(`  提示：所有请求将仅在本机重试，不再走组员中继`);
   process.exit(0);
 }

package/src/cli/help.js

@@ -43,7 +43,7 @@ Usage:
   mslxdff -autostart status        查看自启状态
   mslxdff -chat ["prompt"]       chat REPL（mimo-v2.5-free 优先/big-pickle 兜底，自然语言转命令，模糊匹配由模型完成，历史持久化，超长自动压缩，仅拦 -uninstall，daemon 重启不影响）
   mslxdff -resetban [ip]           clear join-failure bans (all, or one ip)
-  mslxdff -use-group [on|off]     opencode 供应商本机失败时是否走组员网络（默认 on；off 则仅本机，MSLXDFF_USE_GROUP 环境变量可覆盖）
+  mslxdff -use-group [on|off]     本机失败时是否走组员网络（默认 on；off 则所有供应商仅本机，MSLXDFF_USE_GROUP 环境变量可覆盖）
   mslxdff -help                    show this help
 
 Environment:
@@ -63,7 +63,7 @@ Environment:
   MSLXDFF_BAN_THRESHOLD   failed joins before an ip is banned (default 5)
   MSLXDFF_BAN_WINDOW_MS   ban duration after too many failures (default 48h)
   MSLXDFF_HEDGE_DELAY_MS  hedge peer race when local stream first chunk slow (default 1000, 0/off to disable)
-  MSLXDFF_USE_GROUP       opencode 组员中继开关（默认 on；0/off/false 关闭后 opencode 仅本机，不走 peer/broadband）
+  MSLXDFF_USE_GROUP       组员中继总开关（默认 on；0/off/false 关闭后所有供应商仅本机，不走 via-route/hedge/peer/broadband）
   MSLXDFF_AUTO_UPDATE   auto-update: hourly by default, 0/off/false to disable, 1/true or ms
   MSLXDFF_AUTO_UPDATE_MS  same as above, explicit ms (overrides AUTO_UPDATE)
 `);

package/src/model-capabilities/enrich.js

@@ -0,0 +1,72 @@
+// -setto opencode 条目能力注入（ADR-0016 联动）：把 models.dev 能力写进 opencode.json
+// 的 per-model 条目（opencode Model 形状，实测 debug config 原样保留并生效），
+// 并产出一行人话摘要供 CLI 展示。查不到能力（未收录 provider/模型）时原样返回不硬造。
+import { globalCapabilities } from "./index.js";
+
+// "bai/glm-5.3-flash" → { provider: "bai", raw: "glm-5.3-flash" }；裸 id 归 opencode
+function splitProvider(modelId) {
+  const s = String(modelId || "").trim();
+  const i = s.indexOf("/");
+  if (i > 0) return { provider: s.slice(0, i).toLowerCase(), raw: s.slice(i + 1) };
+  return { provider: "opencode", raw: s };
+}
+
+// caps → opencode Model 形状增量（只含能力字段，name 等原有键不动）
+function capsToEntryFields(caps) {
+  if (!caps) return null;
+  const fields = {
+    reasoning: Boolean(caps.reasoning),
+    tool_call: Boolean(caps.toolCall),
+    attachment: Boolean(caps.attachment),
+    temperature: Boolean(caps.temperature),
+    modalities: { input: caps.inputModalities || ["text"], output: caps.outputModalities || ["text"] },
+    limit: { context: Number(caps.context) || 0, output: Number(caps.maxOutput) || 0 },
+  };
+  if (caps.releaseDate) fields.release_date = caps.releaseDate;
+  if (caps.costIn != null || caps.costOut != null) {
+    fields.cost = { input: Number(caps.costIn) || 0, output: Number(caps.costOut) || 0 };
+  }
+  return fields;
+}
+
+// entry: 现有条目（含 name 等）；modelId: 内部 canonical id；capsSvc: 可注入（默认全局单例）
+// 返回 { entry: 增强后条目, caps: caps|null }；服务异常静默降级（同步命令不能因目录拉取失败而挂）
+export async function enrichOpencodeEntry(entry, modelId, capsSvc) {
+  const base = entry && typeof entry === "object" && !Array.isArray(entry) ? entry : {};
+  const svc = capsSvc === undefined ? globalCapabilities() : capsSvc;
+  if (!svc) return { entry: base, caps: null };
+  const { provider, raw } = splitProvider(modelId);
+  let caps = null;
+  try {
+    await svc.ready();
+    caps = svc.get(provider, raw) || null;
+    // 降级匹配：mslxdff 自建目录的 -free/-search-free/-expert-free 后缀在 models.dev 无后缀
+    if (!caps && /-free$/.test(raw)) caps = svc.get(provider, raw.replace(/-free$/, "")) || null;
+  } catch {
+    caps = null; // 目录不可用：降级为无能力条目（staleness 兜底在服务内已做）
+  }
+  const fields = capsToEntryFields(caps);
+  if (!fields) return { entry: base, caps: null };
+  return { entry: { ...base, ...fields }, caps };
+}
+
+// caps → 一行人话摘要（无有效信息返回 ""，调用方按空跳过不噪音）
+export function capsSummary(caps) {
+  if (!caps) return "";
+  const parts = [];
+  if (caps.effortType === "effort" && Array.isArray(caps.effortValues) && caps.effortValues.length) {
+    parts.push(`推理档 ${caps.effortValues.join("/")}`);
+  } else if (caps.effortType === "toggle") {
+    parts.push("推理 开关型");
+  } else if (caps.effortType === "budget_tokens") {
+    parts.push("推理 budget_tokens");
+  } else if (caps.reasoning) {
+    parts.push("推理模型");
+  }
+  if (caps.imageInput) parts.push("📷读图");
+  if (caps.context) parts.push(`上下文 ${caps.context >= 1000 ? `${Math.round(caps.context / 1000)}k` : caps.context}`);
+  if (caps.costIn != null || caps.costOut != null) {
+    parts.push(`$${caps.costIn ?? 0}/${caps.costOut ?? 0} 每M`);
+  }
+  return parts.join(" · ");
+}

package/src/model-capabilities/index.js

@@ -0,0 +1,130 @@
+// 模型能力目录服务（opencode 官方同源 models.dev）：fetch + 磁盘缓存 + TTL + staleness 降级
+// 源：https://models.opencode.ai/api.json（opencode core models-dev.ts:160 同款；备选 https://models.dev/api.json）
+// 形状：{ [providerId]: { models: { [modelId]: raw } } }；mslxdff 裸 id 归 opencode，`prov/id` 前缀路由到对应 provider
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { normalizeProviderModels } from "./parse.js";
+import { compatFetch } from "../compat.js";
+
+export const DEFAULT_SOURCE_URL = "https://models.opencode.ai/api.json";
+
+export function sourceUrl() {
+  const raw = process.env.MSLXDFF_MODELS_DEV_URL;
+  return raw && String(raw).trim() ? String(raw).trim() : DEFAULT_SOURCE_URL;
+}
+
+export function ttlMs() {
+  const n = Number(process.env.MSLXDFF_MODELS_DEV_TTL_MS);
+  return Number.isInteger(n) && n >= 0 ? n : 86_400_000; // 默认 24h
+}
+
+export function createCapabilitiesService({
+  fetchImpl = compatFetch,
+  cacheFile = "",
+  ttlMs: ttl = ttlMs(),
+  url = sourceUrl(),
+  now = Date.now,
+} = {}) {
+  let raw = null;          // 原始目录（全 provider）
+  let capsIndex = new Map(); // providerId -> { modelId -> caps }
+  let loadedAt = 0;
+  let inflight = null;
+
+  function buildIndex(data) {
+    const idx = new Map();
+    for (const [pid, p] of Object.entries(data || {})) {
+      if (!p || typeof p !== "object") continue;
+      idx.set(pid, normalizeProviderModels(p.models || {}));
+    }
+    return idx;
+  }
+
+  function readCache() {
+    if (!cacheFile) return null;
+    try { return JSON.parse(readFileSync(cacheFile, "utf8")); } catch { return null; }
+  }
+
+  function writeCache(data) {
+    if (!cacheFile || !data) return;
+    try {
+      mkdirSync(dirname(cacheFile), { recursive: true });
+      writeFileSync(cacheFile, JSON.stringify(data));
+    } catch { /* 缓存失败不致命 */ }
+  }
+
+  async function fetchFresh() {
+    const res = await fetchImpl(url, { headers: { Accept: "application/json" } });
+    if (!res?.ok) throw new Error(`models.dev fetch ${res?.status || "network"}`);
+    return res.json();
+  }
+
+  // ready：缓存新鲜直接用；否则拉新；失败回退旧缓存（含磁盘），完全无数据才抛
+  async function ready() {
+    const t = now();
+    if (raw && t - loadedAt < ttl) return;
+    if (inflight) return inflight;
+    inflight = (async () => {
+      try {
+        const data = await fetchFresh();
+        raw = data;
+        capsIndex = buildIndex(data);
+        loadedAt = t;
+        writeCache(data);
+      } catch (e) {
+        if (raw) return; // 内存还有旧的，继续用
+        const disk = readCache();
+        if (disk) {
+          raw = disk;
+          capsIndex = buildIndex(disk);
+          loadedAt = t; // 视作刚加载，避免每请求都重试打上游
+          return;
+        }
+        throw e;
+      } finally {
+        inflight = null;
+      }
+    })();
+    return inflight;
+  }
+
+  function capsFor(pid) {
+    return capsIndex.get(pid) || null;
+  }
+
+  function get(providerId, modelId) {
+    const pid = String(providerId || "opencode").toLowerCase();
+    const mid = String(modelId || "");
+    const map = capsFor(pid);
+    if (!map) return null;
+    return map[mid] || null;
+  }
+
+  function list(providerId) {
+    const pid = String(providerId || "opencode").toLowerCase();
+    const map = capsFor(pid);
+    if (!map) return [];
+    return Object.entries(map).map(([id, capabilities]) => ({ id, capabilities }));
+  }
+
+  function providers() {
+    return [...capsIndex.keys()].sort();
+  }
+
+  return { ready, get, list, providers };
+}
+
+// 模块级单例（与 globalDedup 同模式）：HTTP handler 懒加载，测试 _reset 后注入
+let _global = null;
+export function globalCapabilities() {
+  if (!_global) _global = createCapabilitiesService({ cacheFile: defaultCacheFile() });
+  return _global;
+}
+export function _resetGlobalCapabilities() { _global = null; }
+
+// 缓存落盘位置：MSLXDFF_MODELS_DEV_CACHE 覆盖 > ~/.config/mslxdff/models-dev.json（与 state 同目录）
+function defaultCacheFile() {
+  const override = process.env.MSLXDFF_MODELS_DEV_CACHE;
+  if (override && String(override).trim()) return String(override).trim();
+  return join(homedir(), ".config", "mslxdff", "models-dev.json");
+}

package/src/model-capabilities/parse.js

@@ -0,0 +1,39 @@
+// models.dev 能力目录 → mslxdff 能力形状的纯函数解析层（无 IO，测试接缝 S1）
+// 源数据形态（实测 models.opencode.ai/api.json 2026-09-11）：
+//   reasoning_options: [{type:"effort",values:["low","medium","high","max"]} | {type:"toggle"} | {type:"budget_tokens",min}]
+//   modalities.input 含 "image" 即可读图；limit.context/output；cost.input/output 为 $/M tokens
+export function normalizeModelCaps(_id, m) {
+  const opts = Array.isArray(m?.reasoning_options) ? m.reasoning_options : [];
+  const effort = opts.find((o) => o?.type === "effort");
+  const toggle = opts.some((o) => o?.type === "toggle");
+  const budget = opts.find((o) => o?.type === "budget_tokens");
+  const input = Array.isArray(m?.modalities?.input) ? m.modalities.input : [];
+  return {
+    reasoning: Boolean(m?.reasoning),
+    effortType: effort ? "effort" : toggle ? "toggle" : budget ? "budget_tokens" : null,
+    effortValues: effort && Array.isArray(effort.values) ? effort.values.map(String) : null,
+    imageInput: input.includes("image"),
+    toolCall: Boolean(m?.tool_call),
+    context: Number(m?.limit?.context) || null,
+    maxOutput: Number(m?.limit?.output) || null,
+    costIn: Number(m?.cost?.input) || null,
+    costOut: Number(m?.cost?.output) || null,
+    // opencode Model 形状补充字段（-setto opencode 条目注入用）
+    attachment: Boolean(m?.attachment),
+    temperature: Boolean(m?.temperature),
+    releaseDate: typeof m?.release_date === "string" && m.release_date ? m.release_date : null,
+    inputModalities: input.length ? input : ["text"],
+    outputModalities: Array.isArray(m?.modalities?.output) && m.modalities.output.length ? m.modalities.output : ["text"],
+  };
+}
+
+// provider.models 对象（{ [modelId]: rawModel }）→ { [modelId]: caps }
+export function normalizeProviderModels(modelsObj) {
+  const out = {};
+  if (!modelsObj || typeof modelsObj !== "object") return out;
+  for (const [id, m] of Object.entries(modelsObj)) {
+    if (!m || typeof m !== "object") continue;
+    out[id] = normalizeModelCaps(id, m);
+  }
+  return out;
+}

package/src/providers/cline/auth.js

@@ -19,6 +19,22 @@ export function parseCooldown(body, status) {
   return 60 * 1000;
 }
 
+/**
+ * 真死 vs 假死：对标官方 getValidClineCredentials 契约——只有 invalid_grant
+ *（refresh token 被拒）才判死，需重新授权；网络抖动/5xx/超时是瞬时失败，
+ * 手里 token 仍有效时继续用，且绝不清掉已存凭证。
+ */
+export function isInvalidGrant(bodyText, status) {
+  const t = String(bodyText || "").toLowerCase();
+  if (/invalid_grant|invalid_token/.test(t)) return true;
+  // 路由拼错/版本提示类 401（"...latest version...re-authenticate your Cline account"）
+  // 只是打错了地址，不是 token 死，绝不能判死，否则好号会被永久冷冻。
+  if (/latest version|re-authenticate/.test(t)) return false;
+  if ((status === 400 || status === 403) && /invalid|expired|revoked/.test(t)) return true;
+  if (status === 401 && /invalid_grant|invalid token|token[^.]{0,30}(expired|revoked|invalid)/.test(t)) return true;
+  return false;
+}
+
 /**
  * 一次性 refresh：bench/诊断用，不落盘、不建池。
  * 返回 accessToken 或 null。
@@ -90,6 +106,7 @@ export function createAuthPool({
     for (let k = 0; k < list.length; k++) {
       const acc = list[accountIndex % list.length];
       accountIndex = (accountIndex + 1) % list.length;
+      if (acc.dead) continue;
       if (!acc.cooldownUntil || acc.cooldownUntil <= clock()) {
         currentAccount = acc;
         return acc;
@@ -100,9 +117,13 @@ export function createAuthPool({
 
   async function refreshOne(account) {
     const now = clock();
+    if (account.dead) throw new Error("invalid_grant");
     if (account.cooldownUntil > now) throw new Error("account_cooldown");
     if (account.accessToken && now < account.expiry) return account.accessToken;
-    const url = joinUrl(resolvedBase, "/api/v1/auth/refresh");
+    // base 可能已含 /api/v1（state 里 clinebot baseUrl 就是 …/api/v1），直接拼会 double 成
+    // …/api/v1/api/v1/auth/refresh → 上游回 401 Unauthorized（版本/重认证提示），绝不能当 token 死。
+    const baseNoV1 = resolvedBase.replace(/\/api\/v1\/?$/, "");
+    const url = joinUrl(baseNoV1, "/api/v1/auth/refresh");
     const opts = {
       method: "POST",
       headers: { "Content-Type": "application/json" },
@@ -111,7 +132,12 @@ export function createAuthPool({
     if (dispatcher) opts.dispatcher = dispatcher;
     let res;
     try { res = await fetchImpl(url, opts); } catch { account.cooldownUntil = now + 60 * 1000; throw new Error("refresh_failed"); }
-    if (!res.ok) { account.cooldownUntil = now + 60 * 1000; throw new Error("refresh_failed"); }
+    if (!res.ok) {
+      let t = "";
+      try { t = await res.text(); } catch {}
+      if (isInvalidGrant(t, res.status)) { account.dead = true; throw new Error("invalid_grant"); }
+      account.cooldownUntil = now + 60 * 1000; throw new Error("refresh_failed");
+    }
     let data;
     try { data = await res.json(); } catch { account.cooldownUntil = now + 60 * 1000; throw new Error("refresh_no_token"); }
     const accessToken = data?.data?.accessToken || data?.accessToken || data?.access_token;
@@ -138,11 +164,12 @@ export function createAuthPool({
     if (pool.length === 0) throw new Error("缺少 CLINE_REFRESH_TOKEN（请用 cline_oauth.py 获取）");
     for (let attempt = 0; attempt < pool.length; attempt++) {
       const acc = pool[attempt % pool.length];
+      if (acc.dead) continue;
       if (acc.cooldownUntil && acc.cooldownUntil > clock()) continue;
       currentAccount = acc;
       try { return await refreshOne(acc); } catch (e) { if (e.message === "account_cooldown") continue; continue; }
     }
-    const acc = pool[0];
+    const acc = pool.find((a) => !a.dead) || null;
     if (!acc) throw new Error("无可用 Cline 账号");
     currentAccount = acc;
     acc.cooldownUntil = 0;

package/src/providers/cline/chat.js

@@ -155,9 +155,14 @@ export function createChatService({
     const sessionId = genSessionId();
     const isStream = body?.stream === true;
     const upstreamModel = stripProviderPrefix(model);
+    // token 口径双写：对标官方 withMaxCompletionTokensForReasoningModels——
+    // cline 上游默认 reasoning_effort high，推理模型认 max_completion_tokens，
+    // 只发 max_tokens 会被部分通道拒；双写兼容最稳。
+    const tokLimit = body?.max_tokens || body?.max_completion_tokens || 4096;
     const upstreamBody = {
       model: upstreamModel,
-      max_tokens: body?.max_tokens || body?.max_completion_tokens || 4096,
+      max_tokens: tokLimit,
+      max_completion_tokens: tokLimit,
       session_id: sessionId,
       reasoning_effort: body?.reasoning_effort || body?.reasoningEffort || "high",
       messages: body?.messages || [],

package/src/providers/cline/models.js

@@ -16,10 +16,34 @@ export function createModelsService({ id, baseUrl, modelsPath, fetchImpl, dispat
   let cache = null;
   let fetchedAt = 0;
 
+  // 离线兜底：对标官方 FALLBACK（free 数组实证含 z-ai/glm-5.3-flash）。
+  // 上游挂了/401 时也不返回空数组，保证 -provider clinebot models 与 picks 仍有免费可用。
+  const FALLBACK_FREE = [
+    { id: "deepseek/deepseek-v4-flash", name: "deepseek-v4-flash" },
+    { id: "z-ai/glm-5.3-flash", name: "glm-5.3-flash" },
+    { id: "poolside/laguna-s-2.1:free", name: "laguna-s-2.1:free" },
+  ];
+
+  function fallbackList() {
+    const out = FALLBACK_FREE.map((m) => ({ ...m, id: joinModelId(id, m.id) }));
+    cache = out; fetchedAt = Date.now();
+    return out;
+  }
+
+  // 端点归一化：官方取 {bareHost}/api/v1/ai/cline/recommended-models。
+  // baseUrl 可能是裸 host（https://api.cline.bot）也可能是带 /api/v1 的，
+  // 统一收敛到 …/api/v1/ai/cline/recommended-models；用户自定义 path 原样尊重。
+  function resolveModelsUrl() {
+    const custom = modelsPath && modelsPath !== "/models" && modelsPath !== "/ai/cline/recommended-models";
+    if (custom) return joinUrl(resolvedBase, resolvedPath);
+    const bare = resolvedBase.replace(/\/api\/v1\/?$/, "");
+    return joinUrl(bare, "/api/v1/ai/cline/recommended-models");
+  }
+
   async function listModels() {
     const now = Date.now();
     if (cache && now - fetchedAt < CACHE_TTL) return cache;
-    const url = joinUrl(resolvedBase, resolvedPath);
+    const url = resolveModelsUrl();
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(new Error(`${id} models timed out`)), 15_000);
     try {
@@ -29,20 +53,22 @@ export function createModelsService({ id, baseUrl, modelsPath, fetchImpl, dispat
       const opts = { headers, signal: controller.signal };
       if (dispatcher) opts.dispatcher = dispatcher;
       const res = await fetchImpl(url, opts);
-      if (!res.ok) return [];
+      if (!res.ok) return fallbackList();
       const json = await res.json().catch(() => ({}));
       if (isClineBotHost(resolvedBase) && Array.isArray(json.free)) {
         const out = json.free.filter((m) => m && typeof m.id === "string").map((m) => ({ ...m, id: joinModelId(id, m.id) }));
+        if (!out.length) return fallbackList();
         cache = out; fetchedAt = now; return out;
       }
       const raw = Array.isArray(json.data) ? json.data : Array.isArray(json.models) ? json.models : Array.isArray(json) ? json : [];
       const out = raw.filter((m) => m && typeof m.id === "string").map((m) => ({ ...m, id: joinModelId(id, m.id) }));
+      if (!out.length) return fallbackList();
       cache = out; fetchedAt = now; return out;
-    } catch { return []; } finally { clearTimeout(timer); }
+    } catch { return fallbackList(); } finally { clearTimeout(timer); }
   }
 
   async function preheat() {
-    const url = joinUrl(resolvedBase, resolvedPath);
+    const url = resolveModelsUrl();
     const t0 = performance.now();
     try {
       const headers = { Accept: "application/json" };

package/src/routes/index.js

@@ -4,7 +4,7 @@ import { json, notFound, authorized } from "./helpers.js";
 import { chatHandler } from "./chat.js";
 import { joinHandler, leaveHandler } from "./groups.js";
 import { heartbeatHandler, pollHandler, resultHandler, forwardHandler, streamHandler } from "./groups-relay.js";
-import { modelsHandler, modelsStatusHandler, providerModelsHandler } from "./models-route.js";
+import { modelsHandler, modelsStatusHandler, providerModelsHandler, capabilitiesHandler } from "./models-route.js";
 import { relayHandler } from "./relay.js";
 import { responsesHandler } from "./responses-route.js";
 
@@ -110,6 +110,12 @@ const ROUTES = [
     requiresAuth: true,
     handler: modelsStatusHandler,
   },
+  {
+    method: "GET",
+    path: "/v1/models/capabilities",
+    requiresAuth: true,
+    handler: capabilitiesHandler,
+  },
 ];
 
 // re-export for facade & tests

package/src/routes/models-route.js

@@ -1,6 +1,7 @@
 import { json, errMsg } from "./helpers.js";
 import { runHook } from "../plugins.js";
 import { isModelAllowed } from "../state.js";
+import { globalCapabilities } from "../model-capabilities/index.js";
 
 // Codex 自定义 provider 拉目录要顶层 `models` 数组（codex-rs endpoint/models.rs 解 ModelsResponse{models}），
 // 给它 OpenAI 标准 {object,data} 会报 missing field `models`。学 OmniRoute：仅 codex 调用者追加空数组
@@ -83,3 +84,28 @@ export async function providerModelsHandler({ req, res, models }) {
     json(res, 502, { error: errMsg(err) });
   }
 }
+
+// GET /v1/models/capabilities[?provider=opencode][&id=big-pickle]
+// 模型能力元数据（reasoning 档位/图片输入/tool_call/上下文/价格），源 = opencode 官方 models.dev 目录
+// jsonFn 注入仅为测试接缝（S3）；生产路径用 helpers.json
+export async function capabilitiesHandler({ req, res, capabilities, jsonFn = json }) {
+  // 仅未注入（生产）时用全局单例；显式 null 视作服务不可用（测试可复现 502 空状态）
+  const svc = capabilities === undefined ? globalCapabilities() : capabilities;
+  if (!svc) return jsonFn(res, 502, { error: "capabilities service unavailable" });
+  const q = String(req?.url || "").split("?")[1] || "";
+  const params = new URLSearchParams(q);
+  const provider = (params.get("provider") || "opencode").toLowerCase();
+  const id = params.get("id") || "";
+  try {
+    await svc.ready();
+  } catch (err) {
+    return jsonFn(res, 502, { error: `capabilities source unavailable: ${errMsg(err)}` });
+  }
+  if (id) {
+    const caps = svc.get(provider, id);
+    if (!caps) return jsonFn(res, 404, { error: `model '${id}' not found in capabilities catalog (provider=${provider})` });
+    return jsonFn(res, 200, { object: "model.capabilities", id, provider, capabilities: caps });
+  }
+  const data = svc.list(provider);
+  return jsonFn(res, 200, { object: "list", provider, data });
+}

package/src/state/schemas/use-group.js

@@ -35,19 +35,8 @@ export function getEffectiveUseGroup({ file = defaultStateFile() } = {}) {
   return loadUseGroup({ file });
 }
 
-// 仅对 opencode 供应商生效：opencode 的模型为裸 id 或 opencode/ 前缀
+// 全局开关：off 则所有供应商都不走组员网络（via-route/hedge/peer/broadband 全禁），仅本机直连
 export function shouldUseGroupForModel(model, { file = defaultStateFile() } = {}) {
-  const m = String(model || "").trim();
-  if (!m) return getEffectiveUseGroup({ file });
-  // 带前缀：判断是否为 opencode
-  if (m.includes("/")) {
-    const head = m.split("/")[0].trim().toLowerCase();
-    if (head === "opencode" || head === "oc") {
-      return getEffectiveUseGroup({ file });
-    }
-    return true; // 其他供应商不受此开关限制
-  }
-  // 裸 id 视为 opencode
   return getEffectiveUseGroup({ file });
 }
 

package/src/sync-opencode.js

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from "node:fs";
 import { dirname, join } from "node:path";
 import os from "node:os";
+import { enrichOpencodeEntry, capsSummary as capsSummaryText } from "./model-capabilities/enrich.js";
 
 export function opencodeConfigPath() {
   const env = process.env.OPENCODE_CONFIG || process.env.OPENCODE_CONFIG_PATH;
@@ -79,21 +80,35 @@ export function pruneOpencodeModels(models, keep, currentKey) {
 }
 
 // 补齐：把 ensureAll（picks 口径）里缺失的键写入 models（slash → dash + alias 注册）。
-// 返回 { nextModels, backfilled }；ensureAll 非数组或为空时原样返回（backfilled=0）。
+// 已存在但为旧格式（缺 limit 能力字段）的条目也自动补注能力（upgraded 计数）。
+// 返回 { nextModels, backfilled, upgraded }；ensureAll 非数组或为空时原样返回。
 // 注意：需在剪枝之前调用——先补 picks 缺失，再剪 picks 外旧键，结果集恰为 picks ∪ currentKey。
-export async function ensureAllOpencodeModels(models, ensureAll) {
+// capsSvc 透传给能力注入（undefined=全局单例；补齐的条目同样带能力）。
+export async function ensureAllOpencodeModels(models, ensureAll, capsSvc) {
   if (!Array.isArray(ensureAll) || !ensureAll.length || !models || typeof models !== "object") {
-    return { nextModels: models, backfilled: 0 };
+    return { nextModels: models, backfilled: 0, upgraded: 0 };
   }
   const existing = new Set(Object.keys(models).map(normalizeOpencodeKey));
   let backfilled = 0;
+  let upgraded = 0;
   let aliasDirty = false;
   for (const raw of ensureAll) {
     const internal = toInternalId(String(raw || "").trim());
     if (!internal || internal === "auto") continue;
     const storageKey = internal.includes("/") ? internal.replace(/\//g, "-") : internal;
-    if (!storageKey || existing.has(storageKey)) continue;
-    models[storageKey] = { name: storageKey };
+    if (!storageKey) continue;
+    if (existing.has(storageKey)) {
+      // 已存在：旧格式条目（仅 name、无能力字段）自动升级注入；已带 limit 的新格式不动
+      const cur = models[storageKey];
+      if (cur && typeof cur === "object" && !Array.isArray(cur) && cur.limit === undefined) {
+        const en = await enrichOpencodeEntry(cur, internal, capsSvc);
+        models[storageKey] = en.entry;
+        if (en.caps) upgraded++;
+      }
+      continue;
+    }
+    const enriched = await enrichOpencodeEntry({ name: storageKey }, internal, capsSvc);
+    models[storageKey] = enriched.entry;
     existing.add(storageKey);
     backfilled++;
     if (internal.includes("/") && storageKey !== internal) {
@@ -111,10 +126,10 @@ export async function ensureAllOpencodeModels(models, ensureAll) {
       persistModelAliases();
     } catch {}
   }
-  return { nextModels: models, backfilled };
+  return { nextModels: models, backfilled, upgraded };
 }
 
-export async function syncToOpencode({ id, token, port, file, keep, ensureAll } = {}) {
+export async function syncToOpencode({ id, token, port, file, keep, ensureAll, capabilities } = {}) {
   const targetFile = file || opencodeConfigPath();
   const normalizedRaw = String(id || "").trim();
   if (!normalizedRaw) throw new Error("model id required");
@@ -156,6 +171,8 @@ export async function syncToOpencode({ id, token, port, file, keep, ensureAll }
   let effectiveId = storageKey;
   let pruned = 0;
   let backfilled = 0;
+  let upgraded = 0;
+  let currentCaps = null;
   if (oldProvider) {
     const oldModels = oldProvider.models && typeof oldProvider.models === "object" && !Array.isArray(oldProvider.models)
       ? oldProvider.models
@@ -187,16 +204,21 @@ export async function syncToOpencode({ id, token, port, file, keep, ensureAll }
         if (nextModels[legacyAlias]) delete nextModels[legacyAlias];
         if (legacyInternal !== legacyAlias && nextModels[legacyInternal]) delete nextModels[legacyInternal];
       }
-      nextModels[storageKey] = { ...merged, name: storageKey };
+      const enriched = await enrichOpencodeEntry({ ...merged, name: storageKey }, internal, capabilities);
+      nextModels[storageKey] = enriched.entry;
+      currentCaps = enriched.caps;
       effectiveId = storageKey;
       action = "updated";
     } else {
-      nextModels[storageKey] = { name: storageKey };
+      const enriched = await enrichOpencodeEntry({ name: storageKey }, internal, capabilities);
+      nextModels[storageKey] = enriched.entry;
+      currentCaps = enriched.caps;
       effectiveId = storageKey;
       action = "inserted";
     }
-    const ensured = await ensureAllOpencodeModels(nextModels, ensureAll);
+    const ensured = await ensureAllOpencodeModels(nextModels, ensureAll, capabilities);
     backfilled = ensured.backfilled;
+    upgraded = ensured.upgraded || 0;
     pruned = pruneOpencodeModels(nextModels, keep, storageKey);
     const nextProvider = {
       ...oldProvider,
@@ -216,8 +238,12 @@ export async function syncToOpencode({ id, token, port, file, keep, ensureAll }
     if (!data.provider.mslxdff.models[storageKey]) {
       data.provider.mslxdff.models = { [storageKey]: { name: storageKey } };
     }
-    const ensured = await ensureAllOpencodeModels(data.provider.mslxdff.models, ensureAll);
+    const enrichedNew = await enrichOpencodeEntry(data.provider.mslxdff.models[storageKey], internal, capabilities);
+    data.provider.mslxdff.models[storageKey] = enrichedNew.entry;
+    currentCaps = enrichedNew.caps;
+    const ensured = await ensureAllOpencodeModels(data.provider.mslxdff.models, ensureAll, capabilities);
     backfilled = ensured.backfilled;
+    upgraded = ensured.upgraded || 0;
     action = "inserted";
   }
 
@@ -249,5 +275,5 @@ export async function syncToOpencode({ id, token, port, file, keep, ensureAll }
     }
   } catch {}
 
-  return { action, file: targetFile, id: effectiveId, alias: storageKey, internal, corrupted, storageKey, pruned, backfilled };
+  return { action, file: targetFile, id: effectiveId, alias: storageKey, internal, corrupted, storageKey, pruned, backfilled, upgraded, caps: currentCaps, capsSummaryText: capsSummaryText(currentCaps) };
 }