@bolloon/bolloon-agent 0.5.0 → 0.5.2

package/dist/llm/model-catalog.js

@@ -0,0 +1,717 @@
+/**
+ * model-catalog.ts — 模型目录与「模型元数据」的读写口 (2026-09-26)
+ *
+ * ## 这一层解决什么
+ *
+ * 选择器要显示模型的**能力**, 用户才知道为什么某个模型不能用来做工具调用。但在当前的
+ * 内置数据里, 每个供应商只有一张**模型 ID 清单** (`PROVIDER_INFO[provider].models`),
+ * 没有任何能力数据: 没有 tool_calls、没有 reasoning、没有上下文长度。真实的能力数据
+ * 只能来自两处, 而这两处**现在都还没接**:
+ *
+ *   ① 供应商注册表 (每个供应商的协议/鉴权/默认 URL/是否本地/是否允许当长期执行器)
+ *   ② 模型发现 (`GET /models` 实时目录 + 缓存 + 手工自定义)
+ *
+ * 所以本层的纪律是: **有真来源的字段给真值, 没有真来源的字段一律 `'unknown'` (或 `null`),
+ * 并把"为什么不知道"记在 `ModelEntry.unknowns` 里由界面直接显示** —— 绝不允许在下游渲染层
+ * 写一个"看起来像真的"的常量。渲染层只做三态到人话的翻译 (`capabilityZh` / `contextZh`),
+ * 一个能力值都不许在那里产生。
+ *
+ * ## 元数据填充点 (唯一)
+ *
+ * 外部数据一律通过 `ModelMetadataSource` 注入 (`registerModelMetadataSource`), 不通过
+ * 改本文件的常量、也不通过改渲染层。填充者只回答"这一项你知道什么":
+ * 返回 `undefined` 表示**这一项没有数据**, 该字段就保持 `unknown`。
+ * 这样 P3/P5 填真数据时不会出现"两处真相"。
+ *
+ * `requiresApiKey` / `credentialReady` / `isLocal` **不走填充点**, 它们是本层能**当场算出真值**的字段:
+ * 前者来自内置注册表 (`PROVIDER_INFO`), 中间那个来自"配置里的 key / 环境变量现在有没有",
+ * 后者来自 base URL 的主机名判定。
+ * 配置里那格 `ProviderConfig.requiresApiKey` 是**另一个事实** (= "别再问我了"), 单独放在
+ * `ProviderSummary.configRequiresKey`, 与注册表说法不一致时用 `requiresKeyConflict` 如实标出 ——
+ * 不许在渲染层挑一个装作不知道 (那就是两处真相里随机的一半)。
+ */
+import { llmConfigStore, DEFAULT_PROVIDER_CONFIGS, PROVIDER_INFO, } from './config-store.js';
+import { protocolOf, supportsReasoning, envKeyNamesOf, envApiKeyOf, effectiveModelConfig, normalizeBaseUrl, } from './model-selection.js';
+/** 允许为 `unknown` 的字段 (其余字段一律有真值) */
+export const UNKNOWN_TOLERANT_FIELDS = ['toolCalling', 'reasoning', 'contextLength'];
+// ============================================================
+// 填充点注册表
+// ============================================================
+const metadataSources = [];
+/**
+ * 注册一个元数据填充点。
+ *
+ * 优先级 = **注册顺序** (先注册的赢); 同一个 `id` 再注册 = **原地替换, 优先级不变**
+ * (不是挪到队尾 —— 否则"后注册的就悄悄抢走了优先级", 与本文档说法矛盾)。
+ */
+export function registerModelMetadataSource(src) {
+    const i = metadataSources.findIndex((s) => s.id === src.id);
+    if (i >= 0)
+        metadataSources.splice(i, 1, src);
+    else
+        metadataSources.push(src);
+}
+/** 已注册的填充点名 (顺序 = 生效优先级) */
+export function listModelMetadataSources() {
+    return metadataSources.map((s) => s.id);
+}
+/** 清空填充点 (测试用; 生产路径不调用) */
+export function resetModelMetadataSources() {
+    metadataSources.length = 0;
+}
+function factsOf(provider, model) {
+    const out = {};
+    for (const src of metadataSources) {
+        if (src.providers && !src.providers.includes(provider))
+            continue;
+        let facts;
+        try {
+            facts = src.metadataOf({ provider, model });
+        }
+        catch {
+            facts = undefined;
+        }
+        if (!facts)
+            continue;
+        for (const k of Object.keys(facts)) {
+            if (out[k] === undefined && facts[k] !== undefined)
+                out[k] = facts[k];
+        }
+    }
+    return out;
+}
+// ============================================================
+// 判定真值的小工具 (这些字段不需要填充点)
+// ============================================================
+/** 本地端点 = 主机名是环回地址 (真判定, 不是供应商白名单) */
+export function isLocalBaseUrl(raw) {
+    const url = normalizeBaseUrl(raw);
+    if (!url)
+        return false;
+    try {
+        const host = new URL(url).hostname.toLowerCase();
+        return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '0.0.0.0' || host.endsWith('.local');
+    }
+    catch {
+        return false;
+    }
+}
+/** 该供应商登记在册的模型 ID 清单 (内置目录; 没有清单 → 空数组) */
+export function curatedModelIds(provider) {
+    const info = PROVIDER_INFO[provider];
+    const list = Array.isArray(info?.models) ? info.models : [];
+    return list.filter((m) => typeof m === 'string' && m);
+}
+/** 内置目录给不给得出这一家的清单 —— 拿不到时界面必须说"无内置目录", 不是"0 个模型" */
+export function curatedOriginOf(provider) {
+    return curatedModelIds(provider).length ? 'curated' : 'unavailable';
+}
+/** 三态 → 中文 (渲染层只翻译, 不产生值) */
+export function capabilityZh(c) {
+    return c === 'yes' ? '支持' : c === 'no' ? '不支持' : '未知';
+}
+/** 上下文长度 → 人话 (`null` = 未知) */
+export function contextZh(n) {
+    if (n === null || n === undefined || !Number.isFinite(n) || n <= 0)
+        return '未知';
+    if (n >= 1_000_000)
+        return `${Math.round(n / 100_000) / 10}M`;
+    if (n >= 1000)
+        return `${Math.round(n / 1000)}K`;
+    return String(n);
+}
+// ============================================================
+// 条目构造
+// ============================================================
+/** 内置目录为什么给不出能力数据 —— 逐字段一句人话 (真出处: 目录里只有 ID) */
+export const CURATED_ONLY_REASON = '内置目录只有模型 ID, 没有能力字段 (供应商目录/注册表未接)';
+export function buildModelEntry(model, ctx) {
+    const facts = factsOf(ctx.provider, model);
+    const origin = facts.origin || ctx.originDefault || curatedOriginOf(ctx.provider);
+    const unknowns = [];
+    const toolCalling = facts.toolCalling ?? 'unknown';
+    const reasoning = facts.reasoning ?? 'unknown';
+    const contextLength = typeof facts.contextLength === 'number' ? facts.contextLength : null;
+    const why = ctx.unknownReason || CURATED_ONLY_REASON;
+    if (toolCalling === 'unknown')
+        unknowns.push({ field: 'toolCalling', reason: why });
+    if (reasoning === 'unknown')
+        unknowns.push({ field: 'reasoning', reason: why });
+    if (contextLength === null)
+        unknowns.push({ field: 'contextLength', reason: why });
+    // 注册表是"这家要不要 key"的主来源; 填充点只在**知道得更准**时覆盖它
+    const requiresApiKey = facts.requiresApiKey ?? ctx.requiresApiKey;
+    return {
+        id: model,
+        provider: ctx.provider,
+        displayName: facts.displayName || model,
+        toolCalling,
+        reasoning,
+        contextLength,
+        requiresApiKey,
+        credentialReady: !requiresApiKey || ctx.credentialReady,
+        isLocal: isLocalBaseUrl(ctx.baseUrl),
+        origin,
+        reachability: ctx.reachability || 'unknown',
+        ...(ctx.failureReason ? { failureReason: ctx.failureReason } : {}),
+        unknowns,
+        current: ctx.currentProvider === ctx.provider && ctx.currentModel === model,
+        ...(ctx.upstreamModels
+            ? { upstreamSeen: ctx.upstreamModels.has(model), upstreamOrigin: ctx.upstreamOrigin }
+            : {}),
+    };
+}
+// ============================================================
+// 目录读取
+// ============================================================
+async function providerConfigMap() {
+    await llmConfigStore.initialize();
+    const cfg = await llmConfigStore.getConfig();
+    return (cfg.providers || {});
+}
+function keyStateOf(cfg, provider) {
+    if (cfg?.apiKey)
+        return 'configured';
+    if (envApiKeyOf(provider))
+        return 'env';
+    if (cfg?.requiresApiKey === false)
+        return 'not_required';
+    return 'missing';
+}
+/**
+ * 该供应商**现在能用**的凭证 (真来源: 配置里的 key → 环境变量)。
+ *
+ * 用途: 选择器第 6 步的预检必须用**和真正落盘时同一份凭证**去探, 否则"已经配好 key 的供应商"
+ * 在预检里会被上游按未鉴权打回 (401), 用户看到一句假的"探测失败"。
+ * 返回值只用于当次请求头, 不进任何打印/快照 (渲染层只回显尾 4 位)。
+ */
+export async function resolvedApiKeyOf(provider) {
+    const providers = await providerConfigMap();
+    const own = providers[provider]?.apiKey;
+    if (own)
+        return own;
+    return envApiKeyOf(provider)?.value;
+}
+/** 供应商列表 (按内置推荐顺序给出; 顺序不参与任何判定) */
+export async function buildProviderSummaries(opts = {}) {
+    const providers = await providerConfigMap();
+    const eff = await effectiveModelConfig({ sessionKey: opts.sessionKey }).catch(() => null);
+    const out = [];
+    for (const id of Object.keys(DEFAULT_PROVIDER_CONFIGS)) {
+        const def = DEFAULT_PROVIDER_CONFIGS[id];
+        const cfg = providers[id];
+        const baseUrl = normalizeBaseUrl(cfg?.baseUrl || def.baseUrl);
+        // 注册表 (PROVIDER_INFO) 是"这家要不要 key"的主来源; config 里那格是"问过没有"
+        const registryRequires = (PROVIDER_INFO[id]?.requiresApiKey ?? def.requiresApiKey) !== false;
+        const configRequires = cfg?.requiresApiKey !== false;
+        const requiresApiKey = registryRequires;
+        const keyState = keyStateOf(cfg, id);
+        const credentialReady = keyState === 'configured' || keyState === 'env' || !registryRequires;
+        const ids = curatedModelIds(id);
+        const probe = opts.probes?.[id];
+        out.push({
+            id,
+            name: PROVIDER_INFO[id]?.name || id,
+            protocol: protocolOf(id),
+            configured: credentialReady,
+            requiresApiKey,
+            configRequiresKey: configRequires,
+            requiresKeyConflict: configRequires !== registryRequires,
+            isLocal: isLocalBaseUrl(baseUrl),
+            modelCount: ids.length,
+            modelCountOrigin: curatedOriginOf(id),
+            configuredModel: String(cfg?.model || ''),
+            baseUrl,
+            keyState,
+            current: !!eff && eff.provider === id,
+            active: !!eff && eff.provider === id,
+            providerReasoning: supportsReasoning(id) ? 'yes' : 'unknown',
+            reachability: probe ? (probe.ok ? 'ok' : 'failed') : 'unknown',
+            origin: 'builtin',
+            ...(probe && !probe.ok && probe.detail ? { failureReason: probe.detail } : {}),
+        });
+    }
+    // ★ 2026-09-26 (P3 接线收口): **自定义供应商也必须出现在这个列表里**。
+    //   只遍历 `DEFAULT_PROVIDER_CONFIGS` 的话, 用户在 `/model` 里根本看不到自己配的那一家
+    //   (它不在内置表里) —— 只能靠记住 id 手打, 而"这家到底配没配 key / 是不是本地端点"更没有地方可看。
+    //   数据来源是注册表读口 (`listProviderRegistry`) 与自定义供应商的**声明** (真出处), 不在这里
+    //   编任何一条: 拿不到声明就不出这一行。
+    for (const { entry, spec } of await customProviderRows()) {
+        if (Object.prototype.hasOwnProperty.call(DEFAULT_PROVIDER_CONFIGS, entry.id))
+            continue; // 内置的上面已经出过
+        const cfg = providers[entry.id];
+        const baseUrl = normalizeBaseUrl(cfg?.baseUrl || entry.defaultBaseUrl || '');
+        const declaredEnv = Array.isArray(entry.apiKeyEnvVars) && entry.apiKeyEnvVars.length ? String(entry.apiKeyEnvVars[0]) : '';
+        const envHas = declaredEnv ? !!String(process.env[declaredEnv] || '').trim() : false;
+        const ownKey = String(spec.apiKey || '').trim();
+        const requiresApiKey = entry.requiresApiKey !== false;
+        const keyState = ownKey ? 'configured' : envHas ? 'env' : (requiresApiKey ? 'missing' : 'not_required');
+        const credentialReady = keyState === 'configured' || keyState === 'env' || !requiresApiKey;
+        const declaredIds = Array.isArray(entry.declaredModelIds) ? entry.declaredModelIds : [];
+        // 配置那一格只有**真的存在**时才算一个事实 (自定义供应商本来就不在 providers 里)
+        const hasConfigRow = !!cfg && (cfg.requiresApiKey !== undefined || cfg.baseUrl !== undefined || cfg.model !== undefined);
+        const configRequiresKey = hasConfigRow ? cfg.requiresApiKey !== false : requiresApiKey;
+        const probe = opts.probes?.[entry.id];
+        out.push({
+            id: entry.id,
+            name: String(entry.displayName || entry.id),
+            protocol: entry.protocol,
+            configured: credentialReady,
+            requiresApiKey,
+            configRequiresKey,
+            requiresKeyConflict: configRequiresKey !== requiresApiKey,
+            isLocal: !!entry.isLocal || isLocalBaseUrl(baseUrl),
+            modelCount: declaredIds.length,
+            modelCountOrigin: declaredIds.length ? 'custom' : 'unavailable',
+            configuredModel: String(cfg?.model || spec.model || ''),
+            baseUrl,
+            keyState,
+            current: !!eff && eff.provider === entry.id,
+            active: !!eff && eff.provider === entry.id,
+            providerReasoning: entry.reasoning,
+            reachability: probe ? (probe.ok ? 'ok' : 'failed') : 'unknown',
+            origin: 'custom',
+            ...(probe && !probe.ok && probe.detail ? { failureReason: probe.detail } : {}),
+        });
+    }
+    // ★ 2026-09-27 (目录驱动): **目录里的家也进这个列表** —— 默认全部进来 (内置同名项跳过, 不重复)。
+    //   数据全部来自目录层 (`origin='catalog'`), 这里**不编**任何一条: 目录里没有这一家就不出这一行。
+    //   家数多 (=一屏放不下) 由界面层用"固定高度视窗 + 可折叠分组 + 搜索"消化 —— 见 `providerTierOf`。
+    const catalogMode = opts.catalog ?? 'all';
+    if (catalogMode !== 'none') {
+        const cat = await import('./provider-catalog.js');
+        await cat.initializeProviderCatalog();
+        const seen = new Set(out.map((s) => s.id));
+        for (const v of cat.catalogProviders()) {
+            if (seen.has(v.id))
+                continue; // 内置与自定义优先 (同名目录项直接跳过)
+            if (Object.prototype.hasOwnProperty.call(DEFAULT_PROVIDER_CONFIGS, v.id))
+                continue;
+            const cfg = providers[v.id];
+            const envHas = v.auth?.envVar ? !!String(process.env[String(v.auth.envVar)] || '').trim() : false;
+            const ownKey = String(cfg?.apiKey || '').trim();
+            const configured = envHas || !!ownKey;
+            if (catalogMode === 'configured' && !configured)
+                continue;
+            const baseUrl = normalizeBaseUrl(String(cfg?.baseUrl || v.api || ''));
+            const keyState = ownKey ? 'configured' : envHas ? 'env' : 'missing';
+            const probe = opts.probes?.[v.id];
+            const requiresApiKey = true;
+            out.push({
+                id: v.id,
+                name: String(v.name || v.id),
+                protocol: v.family === 'anthropic' ? 'anthropic' : v.family === 'gemini' ? 'gemini' : 'openai-compatible',
+                configured,
+                requiresApiKey,
+                configRequiresKey: cfg?.requiresApiKey !== false,
+                requiresKeyConflict: false,
+                isLocal: isLocalBaseUrl(baseUrl),
+                modelCount: v.modelIds.length,
+                modelCountOrigin: 'catalog',
+                configuredModel: String(cfg?.model || ''),
+                baseUrl,
+                keyState,
+                current: !!eff && eff.provider === v.id,
+                active: !!eff && eff.provider === v.id,
+                providerReasoning: catalogProviderReasoningOf(v),
+                reachability: probe ? (probe.ok ? 'ok' : 'failed') : 'unknown',
+                origin: 'catalog',
+                catalogFamily: String(v.family),
+                ...(v.auth?.supported ? {} : { catalogAuthUnsupported: true }),
+                ...(v.hasBaseUrl ? {} : { catalogBaseUrlMissing: true }),
+                ...(v.auth?.envVar ? { catalogEnvVar: String(v.auth.envVar) } : {}),
+                ...(!v.auth?.supported || !v.hasBaseUrl ? { catalogNote: String(v.unusableReason || '') } : {}),
+                ...(probe && !probe.ok && probe.detail ? { failureReason: probe.detail } : {}),
+            });
+            seen.add(v.id);
+        }
+    }
+    return out;
+}
+/** 目录家**供应商级** reasoning (目录里字面声明过才给结论; 没声明 → unknown) */
+function catalogProviderReasoningOf(v) {
+    const facts = Object.values(v?.models || {});
+    if (!facts.length)
+        return 'unknown';
+    if (facts.some((f) => f?.reasoning === true))
+        return 'yes';
+    if (facts.every((f) => f?.reasoning === false))
+        return 'no';
+    return 'unknown';
+}
+/**
+ * 列表分组/计数: 内置/自定义/目录各多少家, 各几家可用。只数, 不产生值。
+ * (2026-09-27: 默认已经**全部列出**, 所以这里不再说"目录家未列出"; 只有显式 `catalog:'none'` 时才是那样)
+ */
+export function providerGroupSummary(s) {
+    const g = (list) => `${list.length} 家 (可用 ${list.filter((x) => x.configured).length})`;
+    const builtin = s.filter((x) => (x.origin || 'builtin') === 'builtin');
+    const custom = s.filter((x) => x.origin === 'custom');
+    const catalog = s.filter((x) => x.origin === 'catalog');
+    return `分组: 内置 ${g(builtin)} · 自定义 ${g(custom)} · 目录 ${g(catalog)} · 合计 ${s.length} 家`
+        + (catalog.length ? '' : ' · 目录家未列出 (catalog:none; 看 /model catalog)');
+}
+// ============================================================
+// 第 1 步的"分组/排序"依据 (2026-09-27: 全量列出 + 分组折叠, 不再靠藏家数)
+// ============================================================
+/** 第 1 步的分组名 (顺序 = 优先级: 当前 → 可用 → 未配置凭据 → 需专用鉴权 → 无 api 基址) */
+export const PROVIDER_GROUPS = {
+    current: '当前生效',
+    usable: '可用 (有凭证 / 免 key)',
+    noCredential: '未配置凭据 (选了会先要 key)',
+    specialAuth: '需专用鉴权 (未支持)',
+    noBaseUrl: '无 api 基址 (需自定义 baseUrl)',
+};
+const TIER_RANK = { current: 0, usable: 1, noCredential: 2, specialAuth: 3, noBaseUrl: 4 };
+/**
+ * 这家落在第 1 步的哪一组。**分组只是排版, 不是候选集** ——
+ * 后两组 (需专用鉴权未支持 / 目录没给基址) 照样在列表里、照样搜得到、标题上照写家数,
+ * 它们只是**默认收起** (界面层按 `providerTierCollapsedByDefault` 决定)。
+ */
+export function providerTierOf(s) {
+    if (s.current)
+        return 'current';
+    if (s.catalogAuthUnsupported)
+        return 'specialAuth';
+    if (s.catalogBaseUrlMissing)
+        return 'noBaseUrl';
+    return s.configured ? 'usable' : 'noCredential';
+}
+/**
+ * 哪些分组**默认收起** (leo 2026-09-27: "默认只展开'当前生效 + 可用', 其余分组折叠但显示家数")。
+ * 后三组家数最多 (目录 200+ 家), 默认收起才不会把页面塞满; 按 `空格` 随时展开看全。
+ */
+export function providerTierCollapsedByDefault(t) {
+    return t === 'noCredential' || t === 'specialAuth' || t === 'noBaseUrl';
+}
+/** 按"当前 → 可用 → 未配置 → 需专用鉴权 → 无基址"排 (稳定排序: 同组内保持目录层给的顺序) */
+export function orderProvidersForMenu(list) {
+    return [...list].sort((a, b) => TIER_RANK[providerTierOf(a)] - TIER_RANK[providerTierOf(b)]);
+}
+/**
+ * 「在册的自定义供应商」的注册表记录 + 声明 (真出处: 注册表读口 / 自定义供应商存储)。
+ *
+ * 两个都是动态 import: `provider-registry` ↔ `model-catalog` 之间本来就是循环 import
+ * (见 provider-registry 文件头对模块体时机的说明), 静态 import 会把循环带进本模块的初始化路径。
+ * 读失败 → 返回空数组 (列表少一行自定义供应商, 而不是把整个列表炸掉)。
+ */
+async function customProviderRows() {
+    try {
+        const reg = await import('./provider-registry.js');
+        const store = await import('./custom-provider-store.js');
+        const specs = await store.readCustomProviders();
+        return Object.values(specs || {})
+            .map((spec) => ({ entry: reg.getProviderRegistryEntry(String(spec?.providerId || '')), spec }))
+            .filter((r) => r.entry && r.entry.kind === 'custom');
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 注册表里**非内置**的那一条记录 (自定义或目录; 内置 / 不在册 → `null`)。
+ * 动态 import 的理由与 `customProviderRows` 相同 (provider-registry ↔ model-catalog 循环)。
+ */
+async function customRegistryEntryOf(providerId) {
+    const id = String(providerId || '').trim();
+    if (!id)
+        return null;
+    try {
+        const reg = await import('./provider-registry.js');
+        const entry = reg.getProviderRegistryEntry(id);
+        if (!entry || entry.kind === 'builtin')
+            return null;
+        // 目录家走目录层: 先保证目录文件被读过 (全新进程里 status/list 也要看得到盘上的最新目录)
+        if (entry.kind === 'catalog') {
+            const cat = await import('./provider-catalog.js');
+            await cat.initializeProviderCatalog();
+            const fresh = reg.getProviderRegistryEntry(id);
+            if (fresh && fresh.kind === 'catalog')
+                return fresh;
+        }
+        return entry;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 一家供应商的模型条目。
+ * 当前生效的那一条**置顶** (不在内置清单里也要出现 —— 用户配了自定义 model 时必须看得到它)。
+ */
+export async function listModelsFor(providerId, opts = {}) {
+    const providers = await providerConfigMap();
+    const def = DEFAULT_PROVIDER_CONFIGS[providerId];
+    // 2026-09-26 (P6): 自定义供应商也要能列模型 —— 此前这里在内置表里查不到就直接返回空数组,
+    //   于是"从列表里点自定义供应商"看到的是一张空清单。事实全部来自注册表 (声明), 不在这里编。
+    const customEntry = def ? null : await customRegistryEntryOf(providerId);
+    if (!def && !customEntry)
+        return [];
+    const cfg = providers[providerId];
+    const eff = await effectiveModelConfig({ sessionKey: opts.sessionKey }).catch(() => null);
+    const needsKey = def
+        ? ((PROVIDER_INFO[providerId]?.requiresApiKey ?? def.requiresApiKey) !== false)
+        : (customEntry.requiresApiKey !== false);
+    const baseUrl = normalizeBaseUrl(cfg?.baseUrl || def?.baseUrl || customEntry?.defaultBaseUrl || '');
+    const keyState = keyStateOf(cfg, providerId);
+    const isCatalog = !!customEntry && customEntry.kind === 'catalog';
+    // ★ 2026-09-27 (实测改判): **优先用上游/发现到的真目录**。
+    //   实测事实: deepseek 的 `/models` 只列 `deepseek-flash`/`deepseek-v4-pro`, 而
+    //   `deepseek-v4-flash` 发 chat 请求**回 200 并给出 choices** ⇒ `/models` 是"上游愿意列出来的",
+    //   **不是**"可用模型的全集"。于是这里的规矩是:
+    //     · 上游目录里有的名字 → 排前面 (真目录优先, 顺序也按上游的);
+    //     · 内建 curated 表里有、上游没列的 → **保留**并标 `upstreamSeen: false` (界面写"上游未见"),
+    //       因为实测这种名字常常真能用 —— 隐藏它才是另一种撒谎;
+    //     · 一个字节都不**删**。
+    //   只读缓存, 不发请求 (列表路径不许偷偷打上游)。
+    let upstream;
+    try {
+        const md = await import('./model-discovery.js');
+        upstream = await md.cachedUpstreamModels(providerId, { baseUrl });
+    }
+    catch {
+        upstream = undefined;
+    }
+    const upstreamModels = upstream?.models?.length ? new Set(upstream.models) : undefined;
+    const ctx = {
+        provider: providerId,
+        requiresApiKey: needsKey,
+        credentialReady: keyState === 'configured' || keyState === 'env',
+        baseUrl,
+        currentProvider: eff?.provider,
+        currentModel: eff?.model,
+        reachability: opts.probe ? (opts.probe.ok ? 'ok' : 'failed') : 'unknown',
+        failureReason: opts.probe && !opts.probe.ok ? opts.probe.detail : undefined,
+        // 目录家的清单来自目录快照: 脚注要说"目录里没声明", 不许说成"内置目录只有模型 ID"
+        ...(isCatalog ? {
+            originDefault: 'catalog',
+            unknownReason: `供应商目录 (models.dev 快照) 里这一条没有字面声明该能力 → 未知 (不许编)`,
+        } : {}),
+        ...(upstreamModels ? { upstreamModels, upstreamOrigin: upstream.origin } : {}),
+    };
+    const declared = def ? curatedModelIds(providerId) : (customEntry.declaredModelIds || []);
+    const seen = new Set();
+    const order = [];
+    // ① 上游真目录优先 (顺序也用上游的)
+    for (const m of upstream?.models ?? []) {
+        if (m && !seen.has(m)) {
+            seen.add(m);
+            order.push(m);
+        }
+    }
+    // ② 配置里写着的 model 与当前生效的 model 都必须出现在清单里 (可能不在任何目录中)
+    for (const extra of [eff?.provider === providerId ? eff.model : '', cfg?.model || '', ...(opts.extra || [])]) {
+        const m = String(extra || '').trim();
+        if (m && !seen.has(m)) {
+            seen.add(m);
+            order.push(m);
+        }
+    }
+    // ③ 内建/声明的清单 (上游没列的会被标成"上游未见", 但一条都不删)
+    for (const m of declared) {
+        if (!seen.has(m)) {
+            seen.add(m);
+            order.push(m);
+        }
+    }
+    const entries = order.map((m) => buildModelEntry(m, ctx));
+    // 当前生效的置顶 (稳定: 其余保持原顺序)
+    const cur = entries.filter((e) => e.current);
+    const rest = entries.filter((e) => !e.current);
+    return [...cur, ...rest];
+}
+// ============================================================
+// 模糊搜索 (纯函数)
+// ============================================================
+/**
+ * 模糊匹配打分 (纯函数)。`null` = 不匹配。
+ *
+ * 规则刻意简单可解释: 全部字符按顺序出现在目标里就算匹配 (子序列),
+ * 连续命中给更高分; 完整子串命中直接给高权重。大小写不敏感, 空格与 `-`/`_`/`.` 视为同级分隔符。
+ */
+export function fuzzyScore(haystack, needle) {
+    const h = String(haystack || '').toLowerCase();
+    const raw = String(needle || '').trim().toLowerCase();
+    if (!raw)
+        return 0;
+    if (h.includes(raw))
+        return 1000 - h.indexOf(raw);
+    const n = raw.replace(/[\s]+/g, '');
+    const target = h.replace(/[\s]+/g, '');
+    let i = 0, score = 0, streak = 0;
+    for (const ch of target) {
+        if (ch === n[i]) {
+            i++;
+            streak++;
+            score += 1 + streak;
+        }
+        else
+            streak = 0;
+        if (i >= n.length)
+            break;
+    }
+    return i >= n.length ? score : null;
+}
+/** 按模糊分排序 (平分保持原顺序); `query` 为空 = 原样返回 */
+export function searchModelEntries(entries, query) {
+    const q = String(query || '').trim();
+    if (!q)
+        return entries;
+    const scored = [];
+    entries.forEach((e, i) => {
+        const a = fuzzyScore(e.id, q);
+        const b = fuzzyScore(e.displayName, q);
+        const s = a === null && b === null ? null : Math.max(a ?? -1, b ?? -1);
+        if (s !== null)
+            scored.push({ e, s, i });
+    });
+    scored.sort((x, y) => (y.s - x.s) || (x.i - y.i));
+    return scored.map((x) => x.e);
+}
+// ============================================================
+// 展示
+// ============================================================
+/** 供应商列表行: `● <供应商> · N models` / `○ <供应商> · N models · 未配置 key` / `● <供应商> · 本地` */
+export function formatProviderLine(s) {
+    const isCatalog = s.origin === 'catalog';
+    const mark = s.configured ? '●' : '○';
+    const bits = [];
+    if (isCatalog)
+        bits.push(`目录 · 族 ${s.catalogFamily || '未标'}`);
+    if (s.isLocal)
+        bits.push('本地');
+    bits.push(s.modelCountOrigin === 'unavailable'
+        ? '无内置目录'
+        : `${s.modelCount} models${s.modelCountOrigin === 'catalog' ? ' (目录)' : ''}`);
+    if (!s.configured && s.requiresApiKey) {
+        const envName = isCatalog
+            ? (s.catalogEnvVar || '环境变量名缺失')
+            : (envKeyNamesOf(s.id).join('/') || '环境变量');
+        bits.push(`未配置 key (${envName})`);
+    }
+    // 目录家不能用时**如实标**: 需专用鉴权 (未支持) / 目录里没给基址 —— 不许假装可用
+    if (isCatalog && s.catalogNote)
+        bits.push(`⚠ ${s.catalogNote}`);
+    if (s.current)
+        bits.push('← 当前');
+    // 两处说法不一致就如实标 (不挑一个装作不知道)
+    if (s.requiresKeyConflict)
+        bits.push(`⚠ key 要求不一致 (注册表说${s.requiresApiKey ? '要' : '不要'} / 配置里说${s.configRequiresKey ? '要' : '不要'})`);
+    return `${mark} ${s.id} · ${bits.join(' · ')}`;
+}
+/**
+ * 菜单行 (全屏选择器用): 比 `formatProviderLine` **更紧凑** —— 名字 · 模型数 · 凭证 · 族,
+ * 状态全用**符号/文字**表达 (颜色只是第二通道):
+ *
+ *   · `●` 可用 (有凭证或免 key) / `○` 未配置凭据;
+ *   · `← 当前` 这一家就是当前生效的;
+ *   · `special (需专用鉴权, 未支持)` —— 目录里这一家的鉴权形状本运行时不支持;
+ *   · `无基址 (需自定义 baseUrl)` —— 目录里没给 api 基址;
+ *   · `内置|自定义|目录` + `族 <family>` —— 这一行从哪来。
+ *
+ * 只做排版, 一个字段都不产生 (真事实全来自 `ProviderSummary`)。
+ */
+/**
+ * 供应商菜单行 (全屏选择器用): 一行的**截断存活优先级**就是它的字段顺序 ——
+ * 窄终端/长行会把尾巴切掉, 所以"为什么这家不能用"必须排在最前面, 计数排在后面。
+ *
+ *   ① 不可用/需额外条件的原因 (`special (需专用鉴权, 未支持)` / `无基址 (需自定义 baseUrl)` / key 要求不一致)
+ *   ② 凭证状态 (`免 key` / `key 已配` / `key 来自 env` / `缺 key (VAR)`)
+ *   ③ 计数与来源 (模型数 / 内置·自定义·目录 / 族 / 本地)
+ *   ④ `← 当前`
+ */
+export function formatProviderMenuRow(s) {
+    const mark = s.configured ? '●' : '○';
+    const bits = [];
+    // ① 原因类 (最不经得起截断)
+    if (s.catalogAuthUnsupported)
+        bits.push('special (需专用鉴权, 未支持)');
+    if (s.catalogBaseUrlMissing)
+        bits.push('无基址 (需自定义 baseUrl)');
+    if (s.requiresKeyConflict)
+        bits.push('⚠ key 要求不一致');
+    // ② 凭证状态
+    bits.push(!s.requiresApiKey
+        ? '免 key'
+        : s.keyState === 'configured' ? 'key 已配'
+            : s.keyState === 'env' ? 'key 来自 env'
+                : `缺 key${s.catalogEnvVar ? ` (${s.catalogEnvVar})` : ''}`);
+    // ③ 计数与来源
+    bits.push(s.modelCountOrigin === 'unavailable' ? '模型数未知' : `${s.modelCount} models`);
+    bits.push(s.origin === 'catalog' ? '目录' : s.origin === 'custom' ? '自定义' : '内置');
+    if (s.origin === 'catalog' && s.catalogFamily)
+        bits.push(`族 ${s.catalogFamily}`);
+    if (s.isLocal)
+        bits.push('本地');
+    // ④ 当前
+    if (s.current)
+        bits.push('← 当前');
+    return `${mark} ${s.id} · ${bits.join(' · ')}`;
+}
+/** 供应商行的**语义 tone** (只给颜色用; 语义本体在符号/文字里) */
+export function providerRowTone(s) {
+    // "不能用/需额外条件"两类都用 warn (leo 2026-09-27: special 与 无基址 显眼)
+    if (s.catalogAuthUnsupported || s.catalogBaseUrlMissing)
+        return 'warn';
+    if (s.current)
+        return 'accent';
+    return s.configured ? 'ok' : 'dim';
+}
+/**
+ * 模型菜单行 (全屏选择器用): **一行只放这一行独有的事实**。
+ *
+ * 版面纪律 (2026-09-27 简化后):
+ *   · 未知字段**一律不显示** —— 不逐行复读 `工具调用=未知 · reasoning=未知 · 上下文=未知`,
+ *     那是每行都一样的话, 由页脚统一说一次 (或什么都不说);
+ *   · 来源要标出来: `上游` / `上游(缓存)` / `上游未见` (测过: 上游未列 ≠ 不能用) / `手输`;
+ *   · 能力 (上下文/reasoning/tools) 只在本条**有真数据**时才出现。
+ */
+export function formatModelMenuRow(e) {
+    const bits = [];
+    if (e.upstreamSeen === true)
+        bits.push(e.upstreamOrigin === 'live' ? '上游' : '上游(缓存)');
+    else if (e.upstreamSeen === false)
+        bits.push('上游未见');
+    if (e.origin === 'custom')
+        bits.push('手输');
+    if (typeof e.contextLength === 'number' && e.contextLength > 0) {
+        bits.push(e.contextLength >= 1000 ? `${Math.round(e.contextLength / 1000)}k` : String(e.contextLength));
+    }
+    if (e.reasoning === 'yes')
+        bits.push('reasoning');
+    if (e.toolCalling === 'yes')
+        bits.push('tools');
+    if (e.isLocal)
+        bits.push('本地');
+    if (e.reachability === 'failed')
+        bits.push(`连不上 (${e.failureReason || '原因未知'})`);
+    if (e.current)
+        bits.push('← 当前');
+    return bits.length ? `${e.id} · ${bits.join(' · ')}` : e.id;
+}
+/** 模型条目行: 当前置顶标记 + 原始 ID + 能力三态 + 凭证状态 + 本地/远端 + 失败原因 */
+export function formatModelLine(e) {
+    // 凭证一栏由两个**真事实**合成: 注册表(这家要不要 key) + 手上现在有没有
+    const cred = !e.requiresApiKey ? '免 key' : (e.credentialReady ? 'key 已配' : '缺 key');
+    const bits = [
+        `工具调用=${capabilityZh(e.toolCalling)}`,
+        `reasoning=${capabilityZh(e.reasoning)}`,
+        `上下文=${contextZh(e.contextLength)}`,
+        cred,
+        e.isLocal ? '本地端点' : '远端端点',
+    ];
+    let line = `${e.current ? '▸' : ' '} ${e.id.padEnd(36)} ${bits.join(' · ')}`;
+    if (e.reachability === 'failed')
+        line += ` · ⚠ 连接失败: ${String(e.failureReason || '原因未明').slice(0, 80)}`;
+    return line;
+}
+/** 能力未知的说明 (列表脚注, 只打不重复的原因) */
+export function unknownFootnote(entries) {
+    const reasons = new Set();
+    for (const e of entries)
+        for (const u of e.unknowns)
+            reasons.add(u.reason);
+    if (!reasons.size)
+        return [];
+    return [...reasons].map((r) => `未知原因: ${r}`);
+}