@bolloon/bolloon-agent 0.5.0 → 0.5.1

package/dist/llm/provider-registry.js

@@ -0,0 +1,917 @@
+/**
+ * provider-registry.ts — 供应商注册表 + 兼容协议 (P3, 2026-09-26)
+ *
+ * ## 这一层解决什么
+ *
+ * 此前「供应商」只是一串写死的名字 (`config-store.ModelProvider` 联合类型 + 几处各自的 switch),
+ * 于是每加一家就要改类型、改 switch、改白名单, 而且**谁也不知道某一家到底支不支持工具调用 /
+ * reasoning / 能不能当长期任务执行器** —— 这些判定此前散落在各处的 `if` 里, 甚至根本不存在。
+ *
+ * 本文件把它们收成两层:
+ *
+ *   ① **注册表 (registry)**: 每个供应商一条**逐项有出处**的记录 —— 默认 URL · API key 环境变量 ·
+ *      默认模型 · 模型发现方式 · 认证方式 · 是否要 key · 工具调用 · reasoning · 是否本地 ·
+ *      是否允许作为长期任务执行器。字段值**不在这里编**, 能从既有真表派生的就派生
+ *      (`config-store` 的默认表 / `model-selection` 的协议与鉴权表 / `model-catalog` 的本地判定),
+ *      派生不到的才允许是新事实, 且必须写明证据 (`toolCallingEvidence`)。
+ *   ② **兼容协议 (protocol)**: `openai-compatible|anthropic|gemini|ollama` 四条线上协议。
+ *      自定义供应商**只声明协议**, 不上改 TS 联合类型 —— 运行时把它接到说同一种协议的内置分支上
+ *      (`runtimeProviderIdOf`)。
+ *
+ * ## 与既有表的关系 (不许两处真相)
+ *
+ * | 字段 | 真出处 |
+ * | --- | --- |
+ * | `defaultBaseUrl` / `defaultModel` | `config-store.DEFAULT_PROVIDER_CONFIGS` (调用时读) |
+ * | `apiKeyEnvVars` | `model-selection.envKeyNamesOf` |
+ * | `protocol` | `model-selection.protocolOf` |
+ * | `reasoning` | `model-selection.supportsReasoning` (不在集合里 → `unknown`, **不写 `no`**) |
+ * | `requiresApiKey` | `config-store.PROVIDER_INFO` (P2 已冻结"注册表是这家的主来源") |
+ * | `isLocal` | `model-catalog.isLocalBaseUrl` (base URL 主机名真判定) |
+ * | `baseUrlEnvVars` | 客户端取 base URL 的那张表 (`pi-ai.ts`) |
+ * | `toolCalling` / `discovery` / `auth` | **本文件的新事实**, 证据写在 `toolCallingEvidence` / 表注释 |
+ *
+ * 逐项相等由门禁钉住 (`src/test/provider-registry.test.ts` 的源码级门 + `scripts/verify-provider-registry.ts`,
+ * 漂移即判红), 所以"派生"不是口头承诺。
+ *
+ * ## 元数据填充点
+ *
+ * 本文件向 P2 冻结的元数据接口注册一个填充点 (`id = 'provider-registry'`), **只回答自己有真值的项**:
+ *
+ *   - `requiresApiKey`: 注册表维度的事实 → 填;
+ *   - `origin`: 只有**自定义供应商**填 `'custom'` (它的模型清单来自用户声明)。内置供应商不填 ——
+ *     `model-catalog.curatedOriginOf` 已经在回答, 这里覆盖它等于在没有新证据的情况下改别人那层的结论;
+ *   - `toolCalling` / `reasoning` / `contextLength`: **只有**自定义供应商**显式声明**过的才填。
+ *     内置供应商一个都不填 —— 内置注册表只有**供应商级**能力, 模型级能力只有真目录 (P5) 能给,
+ *     拿供应商级数据装成模型级就是 P2 明令禁止的"编一个看起来像真的值"。
+ *
+ * 填充点必须**纯同步** (P2 冻结约定): 所以自定义供应商在进程内只以**已读到的快照**存在
+ * (`setCustomProviderSnapshot`)。快照由 `config-store.initialize()` (读配置后) 与
+ * `custom-provider-store` (每次读写后) 推入; 本文件**不**在这里读盘、不发请求。
+ */
+import { DEFAULT_PROVIDER_CONFIGS, PROVIDER_INFO } from './config-store.js';
+import { protocolOf, supportsReasoning, envKeyNamesOf, normalizeBaseUrl, } from './model-selection.js';
+import { registerModelMetadataSource, isLocalBaseUrl, } from './model-catalog.js';
+// 2026-09-27 (目录驱动): 目录里的家也进注册表。
+//   方向是 registry → provider-catalog (**单向**, 不成环: provider-catalog 不 import 本文件,
+//   它靠发现层注入的探针拿"真目录是否已覆盖这条模型")。
+//   内置 13 家仍然由上面的内置表逐个派生, **一个字都不改**; 目录只在"内置表里没有这个 id"时回答。
+import { catalogLoad, getCatalogProvider, catalogProviderIds, ensureProviderCatalogMetadataSource, } from './provider-catalog.js';
+/**
+ * 注册表**必须提供**的能力字段 (P3 验收逐项对上这里; 少一项就算没做完)。
+ * 顺序 = 计划里的顺序。名字与 `ProviderRegistryEntry` 的键一致。
+ */
+export const REQUIRED_REGISTRY_FIELDS = [
+    'defaultBaseUrl', // 默认 URL
+    'apiKeyEnvVars', // API key 环境变量
+    'defaultModel', // 默认模型
+    'discovery', // 模型发现方式
+    'auth', // 认证方式
+    'toolCalling', // 是否支持工具调用
+    'reasoning', // 是否支持 reasoning
+    'isLocal', // 是否本地
+    'allowsLongRunningExecutor', // 是否允许作为长期任务执行器
+];
+// ============================================================
+// 新事实 (1): 谁能发原生工具调用
+// ============================================================
+/**
+ * 本运行时会**真的把原生 tools 发出去**的供应商。
+ *
+ * 真出处: 客户端的路由表 —— `generateText()` 的 switch 里, 只有指向
+ * `callOpenAI(..., openaiTools)` 的那条分支收得到工具数组; 其余分支这条签名里根本没有 tools。
+ * 所以这个集合不是"猜哪些厂商支持工具", 而是**这条运行路径上工具调用真的能通吗**。
+ *
+ * 门禁 (`src/test/provider-registry.test.ts`) 会去 parse 那张路由表, 双向断言集合相等:
+ * 客户端加了新分支 / 撤了旧分支, 而没同步这里 → **判红**。
+ */
+export const NATIVE_TOOL_CALLING_IDS = [
+    'openai', 'minimax', 'deepseek', 'kimi', 'glm', 'qwen', 'mimo', 'grok',
+];
+const NATIVE_TOOL_EVIDENCE = '本运行时把原生 tools 交给 callOpenAI 分支 (客户端 generateText 路由表), 工具调用真能通';
+const NO_NATIVE_TOOL_EVIDENCE = '本运行时的这条协议分支不接收原生 tools (客户端 generateText 路由表) → 工具调用发不出去; '
+    + '这是**运行时口径**, 不等于供应商 API 本身不支持工具';
+// ============================================================
+// 新事实 (2): 协议 → 发现方式 / 认证方式
+// ============================================================
+/**
+ * 协议 → 默认发现方式。
+ *
+ * 出处: 探活/取目录用的是 `config-store.buildTestRequest` 那张表 —— openai 兼容与 openrouter 走
+ * `GET <base>/models`, gemini 走 `<base>/models?key=`, ollama/local 走 `GET <base>/api/tags`。
+ */
+export function discoveryOfProtocol(protocol) {
+    switch (protocol) {
+        case 'gemini': return 'gemini-models';
+        case 'ollama': return 'ollama-tags';
+        // anthropic 没有可用的 GET /v1/models (见下方覆盖表的理由) → 只能手工填 model ID
+        case 'anthropic': return 'manual';
+        case 'openai-compatible':
+        default: return 'openai-models';
+    }
+}
+/**
+ * 逐家覆盖 (只在"协议默认说法不成立"时才允许出现一条, 且必须写理由)。
+ *
+ * - `anthropic`: 仓库里已有的实测结论是 **没有可用的 `GET /v1/models`** (v0.2.15 的探活注释:
+ *   "Anthropic has no GET /v1/models endpoint -> always 404"), 所以这家只能走**手工 model ID**。
+ *   这不是"懒得接", 是已知端点的真结论。
+ */
+const DISCOVERY_OVERRIDES = {
+    anthropic: {
+        discovery: 'manual',
+        reason: '本仓实测: 没有可用的 GET /v1/models (探活表注释 v0.2.15) → 只能手工填 model ID',
+    },
+};
+/** 协议 → 默认认证方式 (出处: 取 base URL/鉴权头的那两张真表: config-store.buildHeaders + 客户端分支) */
+export function authOfProtocol(protocol) {
+    switch (protocol) {
+        case 'anthropic':
+            return { kind: 'x-api-key', header: 'x-api-key' };
+        case 'gemini':
+            // 客户端 chat 分支用 `?key=`; 探活分支用 `x-goog-api-key` 头 —— 两个都写出来, 由调用方选
+            return { kind: 'query-key', header: 'x-goog-api-key', query: 'key' };
+        case 'ollama':
+            return { kind: 'none' };
+        case 'openai-compatible':
+        default:
+            return { kind: 'bearer', header: 'Authorization', scheme: 'Bearer' };
+    }
+}
+// ============================================================
+// 内置优先保障清单
+// ============================================================
+/** 计划里点名要优先保障的那些 (只影响展示顺序, 不参与任何判定) */
+export const PRIORITY_BUILTIN_IDS = [
+    'openai', 'anthropic', 'gemini', 'deepseek', 'minimax', 'kimi', 'qwen', 'glm', 'openrouter', 'ollama', 'grok',
+];
+/** 除优先清单外还在册的内置供应商 (`local` = 本地端点的另一个 id, `mimo` = 小米 MiMo) */
+export const EXTRA_BUILTIN_IDS = ['mimo', 'local'];
+/**
+ * 覆盖 base URL 的环境变量名 (真出处: 客户端取 base URL 的表)。
+ * 只列真有环境变量覆盖的那几家; 其余家只能靠显式 `--base-url` 或配置里的 baseUrl。
+ */
+const BASE_URL_ENV_VARS = {
+    openai: ['OPENAI_BASE_URL'],
+    openrouter: ['OPENROUTER_BASE_URL'],
+    minimax: ['MINIMAX_BASE_URL'],
+    deepseek: ['DEEPSEEK_BASE_URL'],
+    kimi: ['KIMI_BASE_URL', 'MOONSHOT_BASE_URL'],
+    glm: ['GLM_BASE_URL', 'ZHIPU_BASE_URL'],
+    qwen: ['QWEN_BASE_URL', 'DASHSCOPE_BASE_URL'],
+    mimo: ['MIMO_BASE_URL'],
+    grok: ['XAI_BASE_URL'],
+    ollama: ['OLLAMA_BASE_URL'],
+};
+/** 在册的内置供应商 id (顺序 = 既有内置表顺序; 不参与判定) */
+export function listBuiltinProviderIds() {
+    return Object.keys(DEFAULT_PROVIDER_CONFIGS);
+}
+/** 这个 id 是不是内置供应商 */
+export function isBuiltinProvider(id) {
+    return Object.prototype.hasOwnProperty.call(DEFAULT_PROVIDER_CONFIGS, id);
+}
+// ============================================================
+// 条目构造 (内置: 除 toolCalling/discovery/auth 外全部派生)
+// ============================================================
+const PROVENANCE = {
+    defaultBaseUrl: 'config-store.DEFAULT_PROVIDER_CONFIGS.baseUrl (内置默认表)',
+    defaultModel: 'config-store.DEFAULT_PROVIDER_CONFIGS.model (内置默认表)',
+    apiKeyEnvVars: 'model-selection.envKeyNamesOf (环境变量凭据表)',
+    protocol: 'model-selection.protocolOf (协议表)',
+    requiresApiKey: 'config-store.PROVIDER_INFO.requiresApiKey (P2 冻结: 注册表是主来源)',
+    reasoning: 'model-selection.supportsReasoning (不在集合里 → unknown, 不写 no)',
+    isLocal: 'model-catalog.isLocalBaseUrl (base URL 主机名真判定)',
+    baseUrlEnvVars: '客户端取 base URL 的表 (pi-ai.ts getBaseUrl)',
+    discovery: 'config-store.buildTestRequest 的端点表 + 逐家覆盖表',
+    auth: 'config-store.buildHeaders / 客户端取 base URL 与鉴权分支',
+    toolCalling: '本文件 NATIVE_TOOL_CALLING_IDS (客户端 generateText 路由表)',
+    allowsLongRunningExecutor: '本文件判定: 需要 toolCalling=yes (工具调用发不出去的通道不能跑长期任务)',
+};
+function longRunningVerdict(toolCalling, evidence, extraReason) {
+    if (toolCalling === 'yes') {
+        return { ok: true, reason: '允许: 该分支会发出原生工具调用 (工具调用=支持)' };
+    }
+    const why = toolCalling === 'no'
+        ? '工具调用=不支持 (这条协议分支发不出原生 tools)'
+        : '工具调用=未知 (没有真来源 → 不拿未知当可用)';
+    return { ok: false, reason: `不允许: ${why}${extraReason ? `; ${extraReason}` : ''} (证据: ${evidence})` };
+}
+/** 内置供应商的一条注册表记录 (`id` 不在内置表里 → `undefined`, 不编一条出来) */
+export function builtinProviderEntry(id) {
+    const def = DEFAULT_PROVIDER_CONFIGS[id];
+    if (!def)
+        return undefined;
+    const info = PROVIDER_INFO[id];
+    const protocol = protocolOf(id);
+    const baseUrl = normalizeBaseUrl(def.baseUrl);
+    const discovery = DISCOVERY_OVERRIDES[id]?.discovery ?? discoveryOfProtocol(protocol);
+    const toolCalling = NATIVE_TOOL_CALLING_IDS.includes(id) ? 'yes' : 'no';
+    const evidence = toolCalling === 'yes' ? NATIVE_TOOL_EVIDENCE : NO_NATIVE_TOOL_EVIDENCE;
+    const verdict = longRunningVerdict(toolCalling, evidence);
+    const entry = {
+        id,
+        displayName: String(info?.name || id),
+        kind: 'builtin',
+        origin: 'builtin',
+        protocol,
+        defaultBaseUrl: baseUrl,
+        defaultModel: String(def.model || ''),
+        apiKeyEnvVars: envKeyNamesOf(id),
+        baseUrlEnvVars: BASE_URL_ENV_VARS[id] || [],
+        discovery,
+        modelsEndpoint: '',
+        auth: authOfProtocol(protocol),
+        requiresApiKey: info?.requiresApiKey !== false,
+        toolCalling,
+        reasoning: supportsReasoning(id) ? 'yes' : 'unknown',
+        declaredModelIds: declaredModelIdsOf(id),
+        isLocal: isLocalBaseUrl(baseUrl),
+        allowsLongRunningExecutor: verdict.ok,
+        longRunningReason: verdict.reason,
+        toolCallingEvidence: evidence,
+        authSupported: true,
+        authSupportNote: null,
+        catalogFamilySignal: null,
+        provenance: { ...PROVENANCE },
+    };
+    entry.modelsEndpoint = modelsEndpointOf(entry);
+    return entry;
+}
+// ============================================================
+// 自定义供应商 → 条目
+// ============================================================
+/** 自定义供应商的能力一栏永远来自声明; 没声明就是 `unknown` (不补默认值) */
+function customEntry(id, spec) {
+    const protocol = spec.protocol;
+    const baseUrl = normalizeBaseUrl(spec.baseUrl);
+    const declared = Array.isArray(spec.models) ? spec.models.filter((m) => typeof m === 'string' && m.trim()) : [];
+    const cap = spec.capabilities || {};
+    const toolCalling = cap.toolCalling ?? 'unknown';
+    const reasoning = cap.reasoning ?? 'unknown';
+    const localOnly = protocol === 'ollama' || isLocalBaseUrl(baseUrl);
+    const auth = spec.authHeader
+        ? {
+            kind: 'custom',
+            header: spec.authHeader.trim(),
+            // Authorization 是唯一有通用约定的头 (`Bearer <key>`); 其余自定义头按原值放
+            scheme: /^authorization$/i.test(spec.authHeader.trim()) ? 'Bearer' : undefined,
+        }
+        : authOfProtocol(protocol);
+    const evidence = toolCalling === 'yes'
+        ? '自定义供应商显式声明了 capabilities.toolCalling=yes'
+        : toolCalling === 'no'
+            ? '自定义供应商显式声明了 capabilities.toolCalling=no'
+            : '自定义供应商没有声明 capabilities.toolCalling → 未知 (不拿未知当可用)';
+    // 长期任务: 既要"声明支持工具调用", 也要协议本身是本运行时会发原生 tools 的那条
+    const openaiCompatible = protocol === 'openai-compatible';
+    let verdict;
+    if (toolCalling === 'yes' && openaiCompatible) {
+        verdict = { ok: true, reason: '允许: 声明 capabilities.toolCalling=yes 且协议是 openai-compatible (本运行时该分支发原生 tools)' };
+    }
+    else if (toolCalling === 'yes' && !openaiCompatible) {
+        verdict = { ok: false, reason: `不允许: 声明了工具调用能力, 但协议 ${protocol} 的分支不发原生 tools (证据: ${evidence})` };
+    }
+    else if (toolCalling === 'no') {
+        verdict = { ok: false, reason: `不允许: 工具调用=不支持 (自定义供应商显式声明); 证据: ${evidence}` };
+    }
+    else {
+        verdict = { ok: false, reason: `不允许: 工具调用=未知 (自定义供应商没有声明 capabilities.toolCalling, 不拿未知当可用)` };
+    }
+    const entry = {
+        id,
+        displayName: spec.displayName || id,
+        kind: 'custom',
+        origin: 'custom',
+        protocol,
+        defaultBaseUrl: baseUrl,
+        defaultModel: String(spec.model || ''),
+        apiKeyEnvVars: spec.apiKeyEnvVar ? [spec.apiKeyEnvVar.trim()] : [],
+        baseUrlEnvVars: [],
+        discovery: discoveryOfProtocol(protocol),
+        modelsEndpoint: '',
+        auth,
+        requiresApiKey: !localOnly,
+        toolCalling,
+        reasoning,
+        declaredModelIds: [...declared],
+        isLocal: isLocalBaseUrl(baseUrl),
+        allowsLongRunningExecutor: verdict.ok,
+        longRunningReason: verdict.reason,
+        toolCallingEvidence: evidence,
+        authSupported: true,
+        authSupportNote: null,
+        catalogFamilySignal: null,
+        provenance: {
+            defaultBaseUrl: '自定义供应商声明 (baseUrl)',
+            defaultModel: '自定义供应商声明 (model)',
+            apiKeyEnvVars: spec.apiKeyEnvVar ? '自定义供应商声明 (apiKeyEnvVar)' : '未声明 → 空 (只认配置/环境变量回退)',
+            protocol: '自定义供应商声明 (protocol)',
+            requiresApiKey: localOnly ? '本地端点或 ollama 协议 → 免 key (base URL 主机名真判定)' : '声明了远端地址 → 要 key',
+            reasoning: cap.reasoning ? '自定义供应商声明 (capabilities.reasoning)' : '未声明 → unknown',
+            isLocal: 'model-catalog.isLocalBaseUrl (base URL 主机名真判定)',
+            baseUrlEnvVars: '未声明 → 空 (自定义供应商不走内置环境变量覆盖)',
+            discovery: '按声明的协议取默认发现方式 (discoveryOfProtocol)',
+            auth: spec.authHeader ? '自定义供应商声明 (authHeader)' : '按声明的协议取默认认证方式 (authOfProtocol)',
+            toolCalling: '自定义供应商声明 (capabilities.toolCalling)',
+            allowsLongRunningExecutor: '本文件判定: 需要声明 toolCalling=yes 且协议是 openai-compatible',
+        },
+    };
+    entry.modelsEndpoint = modelsEndpointOf(entry, spec.modelsEndpoint);
+    return entry;
+}
+// ============================================================
+// 目录供应商 → 条目 (origin='catalog'; 内置同名项优先, 这条只在"内置表里没有这个 id"时用)
+// ============================================================
+/**
+ * 目录填充点的**范围**: 哪些家归目录层答 (`kind === 'catalog'`), 内置名单是谁。
+ * 方向 registry → catalog (单向)。理由见 `provider-catalog.CatalogFillScope` 的注释:
+ * 不知道范围就答, 会把内置 13 家与自定义家的 `unknown` 悄悄换成目录里的值 —— 那是改行为。
+ */
+function catalogFillScope() {
+    return {
+        builtinIds: [...Object.keys(DEFAULT_PROVIDER_CONFIGS)],
+        kindOf: (id) => {
+            if (isBuiltinProvider(id))
+                return 'builtin';
+            if (customSnapshot[id])
+                return 'custom';
+            if (getCatalogProvider(id))
+                return 'catalog';
+            return undefined;
+        },
+    };
+}
+/** 目录族 → 线上协议 (`special` 族本运行时不发请求, 这个值只是"最贴近的线上形状") */
+const CATALOG_PROTOCOL_BY_FAMILY = {
+    'openai-compatible': 'openai-compatible',
+    anthropic: 'anthropic',
+    gemini: 'gemini',
+    special: 'openai-compatible',
+};
+const CATALOG_TOOL_EVIDENCE_COMPATIBLE = '运行期接到 openai 分支 (runtimeProviderIdOf: 非内置 + openai-compatible → \'openai\'), 该分支发原生 tools'
+    + ' —— 这是**运行时口径**, 不等于这家所有模型都支持工具 (模型级看目录里字面声明的 tool_call)';
+const CATALOG_TOOL_EVIDENCE_OTHER = '本运行时的这条协议分支不接收原生 tools (客户端 generateText 路由表) → 工具调用发不出去; '
+    + '这是**运行时口径**, 不等于供应商 API 本身不支持工具';
+const CATALOG_TOOL_EVIDENCE_SPECIAL = '本运行时不支持这家的鉴权形状 (需专用鉴权) → 请求根本发不出去, 工具调用无从谈起';
+/** 目录家**供应商级** reasoning: 只有目录里字面声明过才给结论, 没声明就是 `unknown` */
+function catalogProviderReasoning(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';
+}
+/**
+ * 目录里的一家 → 注册表条目 (目录驱动: 新家只要在目录里就自动有记录, **不改代码**)。
+ *
+ * 三条诚实边界写在这里:
+ *   ① `defaultBaseUrl` 只用目录里的 `api`; 目录没给就是**空串** (调用方要如实报"需自定义 baseUrl");
+ *   ② 鉴权判成 `special` 的家 → `authSupported=false` + `authSupportNote` 里写清为什么, 不许当可用;
+ *   ③ `toolCalling` 是**运行时口径** (这条分支发不发得出原生 tools), **不是**模型能力数据。
+ *
+ * 不在这里编: 默认模型 (目录里没有"默认模型"这回事 → 空串), base URL 的环境变量覆盖名 (目录没说 → 空数组)。
+ */
+export function catalogProviderEntry(id) {
+    const v = getCatalogProvider(id);
+    if (!v)
+        return undefined;
+    ensureProviderCatalogMetadataSource(catalogFillScope());
+    const load = catalogLoad();
+    const family = v.family;
+    const protocol = CATALOG_PROTOCOL_BY_FAMILY[family];
+    const auth = family === 'special'
+        ? { kind: 'special' }
+        : v.auth.kind === 'x-api-key'
+            ? { kind: 'x-api-key', header: 'x-api-key' }
+            : v.auth.kind === 'x-goog-api-key'
+                ? { kind: 'query-key', header: 'x-goog-api-key', query: 'key' }
+                : v.auth.kind === 'none'
+                    ? { kind: 'none' }
+                    : { kind: 'bearer', header: 'Authorization', scheme: 'Bearer' };
+    const toolCalling = family === 'special'
+        ? 'no'
+        : (family === 'openai-compatible' ? 'yes' : 'no');
+    const evidence = family === 'special'
+        ? CATALOG_TOOL_EVIDENCE_SPECIAL
+        : (family === 'openai-compatible' ? CATALOG_TOOL_EVIDENCE_COMPATIBLE : CATALOG_TOOL_EVIDENCE_OTHER);
+    const verdict = longRunningVerdict(toolCalling, evidence, family === 'special' ? v.auth.note : undefined);
+    const requiresApiKey = true; // 目录家都有"要一个 key"这件事 (special 家要的是专用凭证)
+    const entry = {
+        id: v.id,
+        displayName: v.name || v.id,
+        kind: 'catalog',
+        origin: 'catalog',
+        protocol,
+        defaultBaseUrl: normalizeBaseUrl(v.api),
+        defaultModel: '',
+        apiKeyEnvVars: [...v.env],
+        baseUrlEnvVars: [],
+        discovery: family === 'special' ? 'manual' : discoveryOfProtocol(protocol),
+        modelsEndpoint: '',
+        auth,
+        requiresApiKey,
+        toolCalling,
+        reasoning: catalogProviderReasoning(v),
+        declaredModelIds: [...v.modelIds],
+        isLocal: isLocalBaseUrl(v.api),
+        allowsLongRunningExecutor: verdict.ok,
+        longRunningReason: verdict.reason,
+        toolCallingEvidence: evidence,
+        authSupported: v.auth.supported,
+        authSupportNote: v.auth.supported ? null : v.auth.note,
+        catalogFamilySignal: v.familySignal,
+        provenance: {
+            defaultBaseUrl: v.api
+                ? `目录 api 基址 (${load.provenance.sourceUrl || '公开源'} 快照, 生成于 ${load.generatedAt || '未知时间'})`
+                : '目录里没有 api 基址 → 空 (不许编一个; 需自定义 baseUrl)',
+            defaultModel: '目录里没有"默认模型"这回事 → 空 (用 /model <provider> <model> 指定)',
+            apiKeyEnvVars: `目录 env 名 (${load.provenance.sourceUrl || '公开源'}; 只存名字, 永不取值)`,
+            protocol: `按目录 npm/api 形状推得的协议族 (provider-catalog.familyOfProvider; 信号: ${v.familySignal})`,
+            requiresApiKey: '目录给了环境变量名 → 要一个 key (special 家要的是专用凭证)',
+            reasoning: '目录里逐模型字面声明的 reasoning (任一 true → yes; 全 false → no; 没声明 → unknown)',
+            isLocal: 'model-catalog.isLocalBaseUrl (base URL 主机名真判定)',
+            baseUrlEnvVars: '目录没说哪个环境变量能覆盖基址 → 空 (不编; 要用别的地址就 --base-url 或写配置)',
+            discovery: '按协议族取默认发现方式 (special 族 → manual: 本运行时不发它的请求)',
+            auth: `目录鉴权形状 (${v.auth.kind}): ${v.auth.note}`,
+            toolCalling: '本文件: 运行期路由 (runtimeProviderIdOf) + 鉴权是否受支持',
+            allowsLongRunningExecutor: '本文件判定: 需要 toolCalling=yes (工具调用发不出去的通道不能跑长期任务)',
+        },
+    };
+    entry.modelsEndpoint = modelsEndpointOf(entry);
+    return entry;
+}
+// ============================================================
+// 自定义供应商快照 (纯同步填充点的唯一数据源)
+// ============================================================
+let customSnapshot = {};
+/**
+ * 覆盖进程内的自定义供应商快照。
+ *
+ * 只允许两处推: `config-store.initialize()` (读配置之后) 与 `custom-provider-store` (每次读写之后)。
+ * 这样元数据填充点永远是纯同步的 (P2 冻结约定), 又不会出现"注册表里还是上一版"的陈旧结论。
+ */
+export function setCustomProviderSnapshot(map) {
+    customSnapshot = map && typeof map === 'object' ? map : {};
+}
+/** 当前快照 (排障/展示用; 不含任何网络或磁盘读) */
+export function customProviderSnapshot() {
+    return customSnapshot;
+}
+/** 单条自定义供应商的**声明** (拿不到 → undefined; 不编) */
+export function customProviderSpecOf(id) {
+    return customSnapshot[id];
+}
+// ============================================================
+// 注册表读口
+// ============================================================
+/** 自定义供应商的一条记录 (`spec` 不在快照里也要能构造 —— 由调用方给声明) */
+export function customProviderEntryOf(spec) {
+    return customEntry(spec.providerId, spec);
+}
+/** 全部在册供应商 (内置优先清单在前, 其余内置居中, 自定义在后; 顺序不参与判定) */
+export function listProviderRegistry() {
+    const order = [...PRIORITY_BUILTIN_IDS, ...EXTRA_BUILTIN_IDS];
+    const builtins = listBuiltinProviderIds();
+    const seen = new Set();
+    const ids = [];
+    for (const id of [...order, ...builtins]) {
+        if (!seen.has(id) && isBuiltinProvider(id)) {
+            seen.add(id);
+            ids.push(id);
+        }
+    }
+    const out = ids.map((id) => builtinProviderEntry(id)).filter(Boolean);
+    for (const spec of Object.values(customSnapshot))
+        out.push(customEntry(spec.providerId, spec));
+    return out;
+}
+/**
+ * 一个 id 的记录 (内置 → 自定义快照 → **目录**; 都没有 → `undefined`)。
+ *
+ * 2026-09-27 (目录驱动): 目录里的家 (223 家) 也在这里回答 —— 于是 `registryEntryOf` /
+ * `validateSelection` / `resolveDiscoveryTarget` 不用改就能认识"目录里新出现的一家"。
+ * **内置 13 家优先**: 同名目录项永远不会被走到 (内置那条在最前面就返回了)。
+ */
+export function getProviderRegistryEntry(id) {
+    const bid = builtinProviderEntry(id);
+    if (bid)
+        return bid;
+    const spec = customSnapshot[id];
+    if (spec)
+        return customEntry(id, spec);
+    return catalogProviderEntry(id);
+}
+/**
+ * 在册的家 + 目录里的家 (**列表/选择器/文档**读这个: 一条记录都不重复, 内置优先)。
+ *
+ * 为什么不在 `listProviderRegistry()` 里直接加目录家: 那张表是"**本机在册的**家"
+ * (内置 13 + 用户自定义), 有门 (单测 + 真跑门) 钉着它的长度与逐项来源 ——
+ * 目录是**另一个数据源** (223 家, 由公开目录决定), 混进同一张表会让"在册"这个说法失去判据。
+ * 于是分成两个读口: 在册的 (`listProviderRegistry`) 与 在册+目录 (`listProvidersWithCatalog`)。
+ */
+export function listProvidersWithCatalog() {
+    const out = listProviderRegistry();
+    const seen = new Set(out.map((e) => e.id));
+    for (const id of catalogProviderIds()) {
+        if (seen.has(id))
+            continue; // 内置/自定义优先 (内置同名项按 id 直接跳过)
+        const e = catalogProviderEntry(id);
+        if (!e)
+            continue;
+        seen.add(id);
+        out.push(e);
+    }
+    return out;
+}
+/** 这一家是不是**目录里来的** (内置/自定义都不是) */
+export function isCatalogProvider(id) {
+    return getCatalogProvider(id) !== undefined && !isBuiltinProvider(id) && !customSnapshot[id];
+}
+/** 这个 id 现在**在册**吗 (内置 / 自定义快照 / 目录里的一家) */
+export function isRegisteredProvider(id) {
+    return getProviderRegistryEntry(id) !== undefined;
+}
+/** 协议 (注册表口径; 内置走冻结协议表, 自定义走声明) */
+export function registryProtocolOf(id) {
+    return getProviderRegistryEntry(id)?.protocol ?? null;
+}
+/**
+ * 运行期 provider id —— **兼容协议的落点**。
+ *
+ * 自定义供应商不上改联合类型: 它在运行期接到"说同一种协议"的内置分支上 (openai-compatible → openai
+ * 那条分支), 于是 `initMinimax({provider: runtimeProviderIdOf(entry), baseUrl, model})` 就能真出网。
+ * 内置供应商返回自己 (客户端每条内置 id 都有自己的分支)。
+ */
+export function runtimeProviderIdOf(entry) {
+    if (entry.kind === 'builtin')
+        return entry.id;
+    switch (entry.protocol) {
+        case 'anthropic': return 'anthropic';
+        case 'gemini': return 'gemini';
+        case 'ollama': return 'ollama';
+        case 'openai-compatible':
+        default: return 'openai';
+    }
+}
+// ============================================================
+// 端点与鉴权 (调用方拼请求用; **不是**打印用)
+// ============================================================
+/**
+ * 模型目录端点 URL。
+ *
+ * `declaredEndpoint` (自定义供应商声明的 `modelsEndpoint`) 优先: 绝对 URL 原样用, 相对路径拼在
+ * `defaultBaseUrl` 后。没有端点可用的 (`discovery='manual'`) 返回空串 —— 不编一个端点出来。
+ */
+export function modelsEndpointOf(entry, declaredEndpoint) {
+    const base = normalizeBaseUrl(entry.defaultBaseUrl);
+    const declared = String(declaredEndpoint || '').trim();
+    if (declared) {
+        if (/^https?:\/\//i.test(declared))
+            return declared;
+        if (!base)
+            return declared;
+        return `${base}/${declared.replace(/^\/+/, '')}`;
+    }
+    if (!base)
+        return '';
+    switch (entry.discovery) {
+        case 'ollama-tags': return `${base}/api/tags`;
+        case 'manual': return '';
+        case 'gemini-models':
+        case 'openai-models':
+        default: return `${base}/models`;
+    }
+}
+/**
+ * 认证头 / query 参数。
+ *
+ * 返回值**含凭据**, 只许用于当次请求构造: 不进日志、不进快照、不进报告 (`[REDACTED]`)。
+ * `apiKey` 为空 → 返回空 (`kind='none'` 的本地端点本来也不需要)。
+ */
+export function authHeadersFor(entry, apiKey) {
+    const key = String(apiKey || '').trim();
+    const headers = {};
+    const query = {};
+    if (entry.protocol === 'anthropic')
+        headers['anthropic-version'] = '2023-06-01';
+    if (!key)
+        return { headers, query };
+    const auth = entry.auth;
+    switch (auth.kind) {
+        case 'bearer':
+            headers[auth.header || 'Authorization'] = `${auth.scheme || 'Bearer'} ${key}`;
+            break;
+        case 'x-api-key':
+            headers[auth.header || 'x-api-key'] = key;
+            break;
+        case 'x-goog-api-key':
+            headers[auth.header || 'x-goog-api-key'] = key;
+            break;
+        case 'query-key':
+            query[auth.query || 'key'] = key;
+            if (auth.header)
+                headers[auth.header] = key;
+            break;
+        case 'custom':
+            if (auth.header)
+                headers[auth.header] = auth.scheme ? `${auth.scheme} ${key}` : key;
+            break;
+        case 'none':
+        default:
+            break;
+    }
+    return { headers, query };
+}
+// ============================================================
+// 长期任务执行器门
+// ============================================================
+/** 这家现在能不能当长期任务执行器 (后台 Run/Goal 需要真工具调用) */
+export function canServeLongRunningTasks(id) {
+    return getProviderRegistryEntry(id)?.allowsLongRunningExecutor === true;
+}
+/** 不能当长期任务执行器的**理由** (可以的时候返回 `null`) */
+export function longRunningRefusalReason(id) {
+    const entry = getProviderRegistryEntry(id);
+    if (!entry)
+        return `不在册的供应商: ${id} (注册表里没有这条)`;
+    return entry.allowsLongRunningExecutor ? null : entry.longRunningReason;
+}
+// ============================================================
+// 自定义供应商: 规范化 / 迁移 (纯函数, 不读盘)
+// ============================================================
+const VALID_PROTOCOLS = ['openai-compatible', 'anthropic', 'gemini', 'ollama'];
+/**
+ * 从 base URL 的**主机名**推协议 (真判定, 不是白名单)。
+ *
+ * 用途只有一个: 迁移**旧配置**里那种"只有 baseUrl + model, 没说协议"的自定义端。
+ * 判不出来时退到 `openai-compatible` —— 这是绝大多数自建/兼容网关的协议, 且调用方能在
+ * `notes` 里看到"协议是推出来的", 不是用户声明的。
+ */
+export function inferProtocolFromBaseUrl(raw) {
+    const url = normalizeBaseUrl(raw);
+    if (!url)
+        return 'openai-compatible';
+    let host = '';
+    let path = '';
+    try {
+        const u = new URL(url);
+        host = u.hostname.toLowerCase();
+        path = u.pathname.toLowerCase();
+    }
+    catch {
+        return 'openai-compatible';
+    }
+    if (host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '0.0.0.0' || host.endsWith('.local')) {
+        // 本地端点: 11434 是 ollama 的招牌端口, 其余按兼容网关算
+        return /:11434$/.test(url) ? 'ollama' : 'openai-compatible';
+    }
+    if (host === 'api.anthropic.com' || host.endsWith('.anthropic.com'))
+        return 'anthropic';
+    if (host === 'generativelanguage.googleapis.com')
+        return 'gemini';
+    if (path.includes('/api/paas/'))
+        return 'openai-compatible'; // 智谱那种 path 后缀不改协议
+    return 'openai-compatible';
+}
+/** 是不是合法的自定义供应商 id (不许与内置撞名, 不许空/带斜杠) */
+export function isValidCustomProviderId(id) {
+    const v = String(id || '').trim();
+    if (!v)
+        return false;
+    if (isBuiltinProvider(v))
+        return false;
+    return /^[a-z0-9][a-z0-9._-]*$/i.test(v);
+}
+/**
+ * 规范化**一条**自定义供应商声明 (纯函数)。
+ *
+ * 老形状 (`providerId` / `name` / `url` / `api_key` 之类的别名) 一律在这里收成规范形, 缺必填项
+ * 就**明确拒绝**并把缺哪一项说出来 —— 不静默补默认值。
+ */
+export function normalizeCustomProvider(raw) {
+    if (!raw || typeof raw !== 'object')
+        return { ok: false, reason: '不是对象' };
+    const r = raw;
+    const id = String(r.providerId ?? r.id ?? '').trim();
+    if (!id)
+        return { ok: false, reason: '缺 providerId' };
+    if (!isValidCustomProviderId(id)) {
+        return { ok: false, reason: isBuiltinProvider(id) ? `providerId 与内置供应商撞名: ${id}` : `providerId 形状非法: ${id}` };
+    }
+    const rawUrl = String(r.baseUrl ?? r.base_url ?? r.url ?? '').trim();
+    if (!rawUrl)
+        return { ok: false, reason: '缺 baseUrl' };
+    const baseUrl = normalizeBaseUrl(rawUrl);
+    try {
+        const u = new URL(baseUrl);
+        if (u.protocol !== 'http:' && u.protocol !== 'https:')
+            return { ok: false, reason: `baseUrl 只支持 http/https, 收到 ${u.protocol}` };
+        if (!u.hostname)
+            return { ok: false, reason: 'baseUrl 缺主机名' };
+    }
+    catch {
+        return { ok: false, reason: `baseUrl 不是合法 URL: ${rawUrl}` };
+    }
+    const declaredProtocol = String(r.protocol ?? '').trim();
+    const protocol = VALID_PROTOCOLS.includes(declaredProtocol)
+        ? declaredProtocol
+        // 迁移路径: 老配置没说协议 → 按 base URL 主机名推 (调用方能看到这属于"推出来的")
+        : r.protocol ? 'openai-compatible' : inferProtocolFromBaseUrl(baseUrl);
+    if (r.protocol && !VALID_PROTOCOLS.includes(declaredProtocol)) {
+        return { ok: false, reason: `protocol 不合法: ${String(r.protocol)} (只能是 ${VALID_PROTOCOLS.join('/')})` };
+    }
+    const value = {
+        providerId: id,
+        displayName: String(r.displayName ?? r.name ?? id).trim() || id,
+        baseUrl,
+        protocol,
+    };
+    const apiKey = r.apiKey ?? r.api_key;
+    if (typeof apiKey === 'string' && apiKey.trim())
+        value.apiKey = apiKey.trim();
+    const model = String(r.model ?? '').trim();
+    if (model)
+        value.model = model;
+    const modelsEndpoint = String(r.modelsEndpoint ?? r.models_endpoint ?? '').trim();
+    if (modelsEndpoint)
+        value.modelsEndpoint = modelsEndpoint;
+    const authHeader = String(r.authHeader ?? r.auth_header ?? '').trim();
+    if (authHeader)
+        value.authHeader = authHeader;
+    const apiKeyEnvVar = String(r.apiKeyEnvVar ?? r.api_key_env ?? '').trim();
+    if (apiKeyEnvVar)
+        value.apiKeyEnvVar = apiKeyEnvVar;
+    const models = Array.isArray(r.models) ? r.models.filter((m) => typeof m === 'string' && m.trim()) : [];
+    if (models.length)
+        value.models = [...models];
+    const cap = r.capabilities;
+    if (cap && typeof cap === 'object') {
+        const out = {};
+        if (cap.toolCalling === 'yes' || cap.toolCalling === 'no' || cap.toolCalling === 'unknown')
+            out.toolCalling = cap.toolCalling;
+        if (cap.reasoning === 'yes' || cap.reasoning === 'no' || cap.reasoning === 'unknown')
+            out.reasoning = cap.reasoning;
+        if (typeof cap.contextLength === 'number' && Number.isFinite(cap.contextLength) && cap.contextLength > 0)
+            out.contextLength = cap.contextLength;
+        if (Object.keys(out).length)
+            value.capabilities = out;
+    }
+    if (typeof r.updatedAt === 'string' && r.updatedAt.trim())
+        value.updatedAt = r.updatedAt.trim();
+    return { ok: true, value };
+}
+/**
+ * 规范化 `config.customProviders` 这一格 (纯函数, **不写盘**)。
+ *
+ * 支持三种形态, 都是"用户现在真可能有的":
+ *   1. 缺省 / `null` → `{}` (旧配置一个字都没写 —— 这是绝大多数旧配置);
+ *   2. **map 形** `{ my-gw: {...} }` → 逐条规范化, 坏的**留名**不静默丢;
+ *   3. **数组形** `[ {...} ]` (早期形态) → 按 `providerId` 收成 map。
+ *
+ * 返回值带 `rejected`: 被拒绝的条目与原因 (调用方要如实报出来, 不许"读一读就少了两家")。
+ */
+export function normalizeCustomProviders(raw) {
+    const providers = {};
+    const rejected = [];
+    if (raw === undefined || raw === null)
+        return { providers, rejected };
+    if (typeof raw !== 'object') {
+        // 形状本身就不对 → 留名 + 理由 (不静默当空表: 用户会看到"我写的那一格没生效")
+        rejected.push({ key: 'customProviders', reason: `形状不是对象/数组 (收到 ${typeof raw}) → 这一格被忽略` });
+        return { providers, rejected };
+    }
+    const items = Array.isArray(raw)
+        ? raw.map((item, i) => [String(item?.providerId ?? item?.id ?? `#${i}`), item])
+        : Object.entries(raw);
+    for (const [key, item] of items) {
+        const r = normalizeCustomProvider(item);
+        if (r.ok)
+            providers[r.value.providerId] = r.value;
+        else
+            rejected.push({ key, reason: r.reason });
+    }
+    return { providers, rejected };
+}
+/**
+ * 旧版本把自定义端点直接写进 `providers.<id>` (那一格没有 `customProviders`) → **吸收**成自定义供应商。
+ *
+ * 规矩:
+ *   - 只吸收**不在内置表**、且 `baseUrl` 非空的键 (没有地址的键不是一个能用的端点, 不猜);
+ *   - 协议按 base URL 主机名推 (`inferProtocolFromBaseUrl`), 并**如实标** `inferredProtocol=true`;
+ *   - `known` 里已有的**不覆盖** (显式声明优先于推出来的)。
+ *
+ * 纯函数: `config-store.initialize()` 与 `custom-provider-store` 共用同一个实现 (不许两处各写一份)。
+ */
+export function absorbLegacyProviderEntries(providerMap, known) {
+    const providers = { ...known };
+    const absorbed = [];
+    for (const [id, rawCfg] of Object.entries(providerMap || {})) {
+        if (!rawCfg || typeof rawCfg !== 'object')
+            continue;
+        if (isBuiltinProvider(id) || providers[id])
+            continue;
+        if (!isValidCustomProviderId(id))
+            continue;
+        const cfg = rawCfg;
+        const baseUrl = String(cfg.baseUrl || '').trim();
+        if (!baseUrl)
+            continue;
+        const protocol = inferProtocolFromBaseUrl(baseUrl);
+        const value = {
+            providerId: id,
+            displayName: String(cfg.displayName || id),
+            baseUrl,
+            protocol,
+        };
+        const model = String(cfg.model || '').trim();
+        if (model)
+            value.model = model;
+        const apiKey = String(cfg.apiKey || '').trim();
+        if (apiKey)
+            value.apiKey = apiKey;
+        providers[id] = value;
+        absorbed.push({ providerId: id, protocol, inferredProtocol: true });
+    }
+    return { providers, absorbed };
+}
+// ============================================================
+// 元数据填充点 (P2 冻结接口的**唯一填充方式**)
+// ============================================================
+export const PROVIDER_REGISTRY_SOURCE_ID = 'provider-registry';
+/** 一家登记在册的模型 ID 清单 (自定义=声明, 内置=内置目录; 都没有 → 空数组) */
+function declaredModelIdsOf(provider) {
+    const spec = customSnapshot[provider];
+    if (spec)
+        return Array.isArray(spec.models) ? spec.models.filter((m) => typeof m === 'string' && m) : [];
+    const info = PROVIDER_INFO[provider];
+    return Array.isArray(info?.models) ? info.models.filter((m) => typeof m === 'string' && m) : [];
+}
+/**
+ * 注册表的元数据填充点。
+ *
+ * 只回答自己有真值的项; 其余项**不出现**在该键上 (= 保持 `unknown`)。逐条理由见文件头。
+ */
+export function providerRegistryMetadataSource() {
+    return {
+        id: PROVIDER_REGISTRY_SOURCE_ID,
+        metadataOf: ({ provider, model }) => {
+            const entry = getProviderRegistryEntry(provider);
+            if (!entry)
+                return undefined;
+            const facts = { requiresApiKey: entry.requiresApiKey };
+            if (entry.kind === 'custom') {
+                const spec = customSnapshot[provider];
+                const ids = declaredModelIdsOf(provider);
+                if (ids.length)
+                    facts.origin = 'custom';
+                const isDeclared = ids.includes(model);
+                const cap = spec?.capabilities || {};
+                // 只有**用户在声明里写过的**能力才填; 没写就是不出现 (保持 unknown)
+                if (isDeclared || !ids.length) {
+                    if (cap.toolCalling)
+                        facts.toolCalling = cap.toolCalling;
+                    if (cap.reasoning)
+                        facts.reasoning = cap.reasoning;
+                    if (typeof cap.contextLength === 'number')
+                        facts.contextLength = cap.contextLength;
+                }
+            }
+            return facts;
+        },
+    };
+}
+/**
+ * 把注册表的填充点接上 (幂等; 同 id 再注册 = 原地替换, 优先级不变)。
+ *
+ * 显式版: 无条件注册 (测试里 `resetModelMetadataSources()` 之后要靠它接回去)。
+ */
+export function registerProviderRegistryMetadataSource() {
+    registerModelMetadataSource(providerRegistryMetadataSource());
+    metadataSourceWired = true;
+}
+/**
+ * 自动接线 (幂等, 只做一次)。
+ *
+ * **为什么不放在模块体里**: 本模块与 `config-store` / `model-catalog` 之间是**循环 import**,
+ * 而模块体的执行时机取决于"谁是入口"—— 实测 `model-catalog` 先被别的入口拉起来时, 模块体里
+ * 调 `registerModelMetadataSource()` 会撞上对方模块还没初始化完 (`metadataSources` 的 TDZ) →
+ * 整个进程起不来。所以改在**调用时**接线: 任何一次注册表读、任何一次配置读 (`config-store.initialize()`)
+ * 都会顺手接上, 于是"真的接线了"依然是可核事实, 但不依赖 import 顺序。
+ *
+ * 只接一次也意味着: 测试里显式 `resetModelMetadataSources()` 之后它**不会**被偷偷加回来。
+ */
+export function ensureProviderRegistryMetadataSource() {
+    // 目录的填充点一起接上: 注册表一旦被读, "目录里字面声明过的能力"就该能被问出来。
+    // 两个填充点各答各的字段 (注册表答 requiresApiKey/origin-custom; 目录答 origin-catalog/能力),
+    // 合并规则是 P2 冻结的"逐字段: 没答案的让下一个答"。
+    // **scope 必须给**: 目录层只答 `kind === 'catalog'` 的家 (内置 13 家与自定义家一个字都不许变)。
+    ensureProviderCatalogMetadataSource(catalogFillScope());
+    if (metadataSourceWired)
+        return;
+    registerProviderRegistryMetadataSource();
+}
+let metadataSourceWired = false;