@armadra/agent 0.3.0 → 0.5.0

package/dist/ai/providers/models-dev-snapshot.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 入库的 models.dev 快照（docs/wave5-plan.md §2.1、docs/providers.md「模型元数据」）。
+ *
+ * `models-dev/*.json` 由 `scripts/update-models-dev.mjs` 生成并内联进 `models-dev-data.ts`（单 bundle，
+ * 运行时不读 JSON 文件、不联网）。本模块解析内联数据，并提供与脚本同一口径的 `buildSnapshot()`
+ * （`ama models refresh` 用它裁剪联网拉到的 api.json）与新旧对比 `diffSnapshots()`。
+ */
+import { ModelsDevIndex, type ModelsDevData, type ModelsDevModel, type ModelsDevProvider } from "./models-dev.js";
+export interface SnapshotMeta {
+    /** ISO 8601；只在内容 sha256 变化时更新。 */
+    fetchedAt: string;
+    license: string;
+    sha256: string;
+    source: string;
+    upstream: string;
+}
+/** 收录清单（`models-dev/_providers.json`）：供应商 id 与 OpenRouter 一类聚合商的前缀白名单。 */
+export interface SnapshotList {
+    providers: string[];
+    prefixes?: Record<string, string[]>;
+}
+export declare function snapshotMeta(): SnapshotMeta;
+export declare function snapshotList(): SnapshotList;
+/** 文件形状（模型不带 id）→ 运行时形状（补 id）。 */
+export declare function fromSnapshotFile(file: {
+    id: string;
+    name?: string;
+    api?: string;
+    models: Record<string, Omit<ModelsDevModel, "id">>;
+}): ModelsDevProvider;
+/** 运行时形状 → 文件形状（去掉模型 id 与 tool_call，与脚本写出的 JSON 一致）。 */
+export declare function toSnapshotFile(provider: ModelsDevProvider): unknown;
+/** 内置快照（同一进程只解析一次；调用方不得修改）。 */
+export declare function builtinSnapshot(): ModelsDevData;
+export declare function builtinSnapshotIndex(): ModelsDevIndex;
+/**
+ * 按清单裁剪 api.json（与脚本同一口径）。`only` 只取其中几家。校验失败抛错：顶层不是对象、
+ * 清单里的供应商缺失或过滤后没有模型（防止上游改版把数据清空）。
+ */
+export declare function buildSnapshot(raw: unknown, snapshot?: SnapshotList, only?: readonly string[]): ModelsDevData;
+export interface SnapshotDiff {
+    added: string[];
+    removed: string[];
+    /** `provider/model：context a → b；cost …`。 */
+    changed: string[];
+}
+/** 新旧对比（与脚本摘要同一口径）；只比较 `after` 里出现的供应商。 */
+export declare function diffSnapshots(before: ModelsDevData, after: ModelsDevData): SnapshotDiff;
+/** 快照 ⊕ 覆盖：同 provider/model 以覆盖为准，其余沿用快照。 */
+export declare function mergeSnapshot(base: ModelsDevData, override: ModelsDevData): ModelsDevData;

package/dist/ai/providers/models-dev-snapshot.js

@@ -0,0 +1,137 @@
+/**
+ * 入库的 models.dev 快照（docs/wave5-plan.md §2.1、docs/providers.md「模型元数据」）。
+ *
+ * `models-dev/*.json` 由 `scripts/update-models-dev.mjs` 生成并内联进 `models-dev-data.ts`（单 bundle，
+ * 运行时不读 JSON 文件、不联网）。本模块解析内联数据，并提供与脚本同一口径的 `buildSnapshot()`
+ * （`ama models refresh` 用它裁剪联网拉到的 api.json）与新旧对比 `diffSnapshots()`。
+ */
+import { MODELS_DEV_SOURCES } from "./models-dev-data.js";
+import { ModelsDevIndex, keepForSnapshot, trimProvider, } from "./models-dev.js";
+function parse(id) {
+    const text = MODELS_DEV_SOURCES[id];
+    if (text === undefined)
+        throw new Error(`models.dev 快照缺少 ${id}`);
+    return JSON.parse(text);
+}
+let meta;
+let list;
+let data;
+let index;
+export function snapshotMeta() {
+    meta ??= parse("_meta");
+    return meta;
+}
+export function snapshotList() {
+    list ??= parse("_providers");
+    return list;
+}
+/** 文件形状（模型不带 id）→ 运行时形状（补 id）。 */
+export function fromSnapshotFile(file) {
+    const models = {};
+    for (const [id, model] of Object.entries(file.models))
+        models[id] = { id, ...model };
+    return {
+        id: file.id,
+        ...(file.name !== undefined ? { name: file.name } : {}),
+        ...(file.api !== undefined ? { api: file.api } : {}),
+        models,
+    };
+}
+/** 运行时形状 → 文件形状（去掉模型 id 与 tool_call，与脚本写出的 JSON 一致）。 */
+export function toSnapshotFile(provider) {
+    const models = {};
+    for (const [id, model] of Object.entries(provider.models)) {
+        const { id: _id, tool_call: _toolCall, ...rest } = model;
+        models[id] = rest;
+    }
+    return { ...provider, models };
+}
+/** 内置快照（同一进程只解析一次；调用方不得修改）。 */
+export function builtinSnapshot() {
+    if (data === undefined) {
+        const out = {};
+        for (const id of snapshotList().providers)
+            out[id] = fromSnapshotFile(parse(id));
+        data = out;
+    }
+    return data;
+}
+export function builtinSnapshotIndex() {
+    index ??= new ModelsDevIndex(builtinSnapshot());
+    return index;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * 按清单裁剪 api.json（与脚本同一口径）。`only` 只取其中几家。校验失败抛错：顶层不是对象、
+ * 清单里的供应商缺失或过滤后没有模型（防止上游改版把数据清空）。
+ */
+export function buildSnapshot(raw, snapshot = snapshotList(), only) {
+    if (!isRecord(raw))
+        throw new Error("api.json 顶层不是对象");
+    const out = {};
+    for (const id of only ?? snapshot.providers) {
+        const provider = raw[id];
+        if (!isRecord(provider))
+            throw new Error(`api.json 缺少供应商 ${id}`);
+        const prefixes = snapshot.prefixes?.[id];
+        const trimmed = trimProvider(id, provider, (modelId, model) => keepForSnapshot(model) &&
+            (prefixes === undefined || prefixes.some((p) => modelId.startsWith(`${p}/`))));
+        if (Object.keys(trimmed.models).length === 0)
+            throw new Error(`${id} 过滤后没有模型`);
+        for (const model of Object.values(trimmed.models))
+            delete model.tool_call;
+        out[id] = trimmed;
+    }
+    return out;
+}
+function priceText(model) {
+    const c = model.cost;
+    return c === undefined
+        ? "无"
+        : `${c.input}/${c.output}/${c.cache_read ?? "-"}/${c.cache_write ?? "-"}`;
+}
+/** 新旧对比（与脚本摘要同一口径）；只比较 `after` 里出现的供应商。 */
+export function diffSnapshots(before, after) {
+    const out = { added: [], removed: [], changed: [] };
+    for (const [providerId, provider] of Object.entries(after)) {
+        const old = before[providerId]?.models ?? {};
+        for (const id of Object.keys(old))
+            if (provider.models[id] === undefined)
+                out.removed.push(`${providerId}/${id}`);
+        for (const [id, next] of Object.entries(provider.models)) {
+            const prev = old[id];
+            if (prev === undefined) {
+                out.added.push(`${providerId}/${id}`);
+                continue;
+            }
+            const parts = [];
+            for (const key of ["context", "output"]) {
+                if (prev.limit?.[key] !== next.limit?.[key])
+                    parts.push(`${key} ${prev.limit?.[key] ?? "无"} → ${next.limit?.[key] ?? "无"}`);
+            }
+            if (priceText(prev) !== priceText(next))
+                parts.push(`cost ${priceText(prev)} → ${priceText(next)}`);
+            if (parts.length > 0)
+                out.changed.push(`${providerId}/${id}：${parts.join("；")}`);
+        }
+    }
+    out.added.sort();
+    out.removed.sort();
+    out.changed.sort();
+    return out;
+}
+/** 快照 ⊕ 覆盖：同 provider/model 以覆盖为准，其余沿用快照。 */
+export function mergeSnapshot(base, override) {
+    const out = { ...base };
+    for (const [id, provider] of Object.entries(override)) {
+        const prev = base[id];
+        out[id] = {
+            ...prev,
+            ...provider,
+            models: { ...prev?.models, ...provider.models },
+        };
+    }
+    return out;
+}

package/dist/ai/providers/models-dev.d.ts

@@ -9,10 +9,24 @@
  * 本模块只做纯计算（不读文件、不联网）；缓存与拉取在 models-dev-cache.ts。
  */
 import type { ModelCost } from "../types.js";
-/** 用到的模型字段（name、推理、工具调用、输入模态、上下限、价格、canonical）；其余写缓存时丢掉。 */
+/** 价格（$/1M token）；input 与 output 都有才保留。 */
+export interface ModelsDevPrices {
+    input: number;
+    output: number;
+    cache_read?: number;
+    cache_write?: number;
+}
+/**
+ * 用到的模型字段（models.dev 原名）；其余裁剪时丢掉。快照只多存 family / knowledge /
+ * release_date / limit.input / 价格档位 / interleaved / status（docs/wave5-plan.md §2.1）。
+ */
 export interface ModelsDevModel {
     id: string;
     name?: string;
+    family?: string;
+    /** 知识截止（`YYYY-MM` / `YYYY-MM-DD`）。 */
+    knowledge?: string;
+    release_date?: string;
     reasoning?: boolean;
     tool_call?: boolean;
     modalities?: {
@@ -20,25 +34,37 @@ export interface ModelsDevModel {
     };
     limit?: {
         context?: number;
-        output?: number;
-    };
-    cost?: {
         input?: number;
         output?: number;
-        cache_read?: number;
-        cache_write?: number;
     };
+    cost?: ModelsDevPrices & {
+        context_over_200k?: ModelsDevPrices;
+        tiers?: (ModelsDevPrices & {
+            tier: {
+                size: number;
+                type: "context";
+            };
+        })[];
+    };
+    interleaved?: true | {
+        field: string;
+    };
+    /** 只留 beta（deprecated 在快照里已过滤）。 */
+    status?: "beta";
     canonical_model_id?: string;
 }
 export interface ModelsDevProvider {
     id: string;
     name?: string;
+    /** 供应商级 OpenAI / Anthropic 兼容 baseUrl（协议线索，展示用）。 */
+    api?: string;
     models: Record<string, ModelsDevModel>;
 }
 export type ModelsDevData = Record<string, ModelsDevProvider>;
 /**
- * 原厂供应商（models.dev 的供应商 id，顺序即优先级）。通义在 `alibaba`、Llama 在 `llama`、
- * 智谱国际站在 `zai`；models.dev 没有 `qwen` / `meta` 这样的供应商 id。
+ * 原厂供应商（models.dev 的供应商 id，顺序即优先级）。通义在 `alibaba`、Meta 在 `meta`（Llama API
+ * 在 `llama`）、智谱国际站在 `zai`、豆包在 `volcengine`、混元在 `tencent-tokenhub`；models.dev 没有
+ * `qwen` 这样的供应商 id。
  */
 export declare const FIRST_PARTY_PROVIDERS: readonly string[];
 /** maxTokens 的上限：models.dev 给原厂上限（常与上下文相同），每次请求都会作为 max_tokens 发出。 */
@@ -66,7 +92,22 @@ export interface ModelsDevFields {
     cost?: ModelCost;
     /** models.dev 的 tool_call；Model 上没有对应字段，只用于展示与写入过滤。 */
     toolCall?: boolean;
+    family?: string;
+    knowledge?: string;
+    releaseDate?: string;
+    inputLimit?: number;
+    status?: "beta";
 }
+/**
+ * 映射口径：`custom`（自定义模型补全，缺省）maxTokens 封顶 64k、缺的缓存价按输入价；
+ * `catalog`（内置目录继承）maxTokens 不封顶（目录模型的输出上限就是原厂值，有意调小的写在目录里）、
+ * 缺的缓存价记 0（与目录一贯写法一致：没有单独计价）。
+ */
+export type ModelsDevMapping = "custom" | "catalog";
+/** 快照过滤：丢 deprecated、输出不含文本、上下文为 0 / 缺失、tool_call:false（docs/wave5-plan.md §2.1）。 */
+export declare function keepForSnapshot(raw: unknown): boolean;
+/** 裁剪一家供应商；`keep` 给出时只留它放行的模型（模型 id 按字典序）。 */
+export declare function trimProvider(providerId: string, provider: Record<string, unknown>, keep?: (modelId: string, raw: unknown) => boolean): ModelsDevProvider;
 /** 校验并裁剪 api.json：只留用到的字段；形状不对的供应商 / 模型跳过。整体不是对象抛错。 */
 export declare function trimModelsDev(raw: unknown): ModelsDevData;
 /**
@@ -90,8 +131,8 @@ export declare class ModelsDevIndex {
     match(id: string, explicit?: string): ModelsDevMatch | undefined;
     private choose;
 }
-/** models.dev 条目 → ama Model 字段（规则见 docs/providers.md）。 */
-export declare function modelsDevFields(model: ModelsDevModel): ModelsDevFields;
+/** models.dev 条目 → ama Model 字段（规则见 docs/providers.md「模型元数据」）。 */
+export declare function modelsDevFields(model: ModelsDevModel, mapping?: ModelsDevMapping): ModelsDevFields;
 /** 可由 models.dev 补的 Model 字段（展示来源用）。 */
 export declare const ENRICHABLE_FIELDS: readonly ["contextWindow", "maxTokens", "input", "reasoning", "cost"];
 export type EnrichableField = (typeof ENRICHABLE_FIELDS)[number];

package/dist/ai/providers/models-dev.js

@@ -9,8 +9,9 @@
  * 本模块只做纯计算（不读文件、不联网）；缓存与拉取在 models-dev-cache.ts。
  */
 /**
- * 原厂供应商（models.dev 的供应商 id，顺序即优先级）。通义在 `alibaba`、Llama 在 `llama`、
- * 智谱国际站在 `zai`；models.dev 没有 `qwen` / `meta` 这样的供应商 id。
+ * 原厂供应商（models.dev 的供应商 id，顺序即优先级）。通义在 `alibaba`、Meta 在 `meta`（Llama API
+ * 在 `llama`）、智谱国际站在 `zai`、豆包在 `volcengine`、混元在 `tencent-tokenhub`；models.dev 没有
+ * `qwen` 这样的供应商 id。
  */
 export const FIRST_PARTY_PROVIDERS = [
     "anthropic",
@@ -27,10 +28,14 @@ export const FIRST_PARTY_PROVIDERS = [
     "mistral",
     "minimax",
     "minimax-cn",
+    "meta",
     "llama",
     "cohere",
     "xiaomi",
     "stepfun",
+    "stepfun-ai",
+    "volcengine",
+    "tencent-tokenhub",
     "perplexity",
     "ai21",
     "upstage",
@@ -50,16 +55,59 @@ function nonNegative(value) {
 function strings(value) {
     return Array.isArray(value) ? value.filter((v) => typeof v === "string") : undefined;
 }
+function prices(value) {
+    if (!isRecord(value))
+        return undefined;
+    const input = nonNegative(value["input"]);
+    const output = nonNegative(value["output"]);
+    if (input === undefined || output === undefined)
+        return undefined;
+    const out = { input, output };
+    const read = nonNegative(value["cache_read"]);
+    if (read !== undefined)
+        out.cache_read = read;
+    const write = nonNegative(value["cache_write"]);
+    if (write !== undefined)
+        out.cache_write = write;
+    return out;
+}
+function trimCost(value) {
+    const base = prices(value);
+    if (base === undefined || !isRecord(value))
+        return undefined;
+    const out = base;
+    const over = prices(value["context_over_200k"]);
+    if (over !== undefined)
+        out.context_over_200k = over;
+    const tiers = [];
+    for (const tier of Array.isArray(value["tiers"]) ? value["tiers"] : []) {
+        const p = prices(tier);
+        const spec = isRecord(tier) ? tier["tier"] : undefined;
+        const size = isRecord(spec) ? positive(spec["size"]) : undefined;
+        if (p !== undefined && size !== undefined && isRecord(spec) && spec["type"] === "context")
+            tiers.push({ ...p, tier: { size, type: "context" } });
+    }
+    if (tiers.length > 0)
+        out.tiers = tiers;
+    return out;
+}
+/** 字段裁剪（不过滤）；与 scripts/update-models-dev.mjs 的 trimModel 同一口径，另多留 tool_call。 */
 function trimModel(id, raw) {
     const out = { id };
-    if (typeof raw["name"] === "string")
-        out.name = raw["name"];
+    for (const key of ["name", "family", "knowledge", "release_date"]) {
+        const v = raw[key];
+        if (typeof v === "string" && v !== "")
+            out[key] = v;
+    }
     for (const key of ["reasoning", "tool_call"]) {
-        if (typeof raw[key] === "boolean")
-            out[key] = raw[key];
+        const v = raw[key];
+        if (typeof v === "boolean")
+            out[key] = v;
     }
     if (typeof raw["canonical_model_id"] === "string")
         out.canonical_model_id = raw["canonical_model_id"];
+    if (raw["status"] === "beta")
+        out.status = "beta";
     const modalities = raw["modalities"];
     if (isRecord(modalities)) {
         const input = strings(modalities["input"]);
@@ -68,25 +116,55 @@ function trimModel(id, raw) {
     }
     const limit = raw["limit"];
     if (isRecord(limit)) {
-        const context = positive(limit["context"]);
-        const output = positive(limit["output"]);
-        out.limit = {
-            ...(context !== undefined ? { context } : {}),
-            ...(output !== undefined ? { output } : {}),
-        };
-    }
-    const cost = raw["cost"];
-    if (isRecord(cost)) {
-        const c = {};
-        for (const key of ["input", "output", "cache_read", "cache_write"]) {
-            const v = nonNegative(cost[key]);
+        const l = {};
+        for (const key of ["context", "input", "output"]) {
+            const v = positive(limit[key]);
             if (v !== undefined)
-                c[key] = v;
+                l[key] = v;
         }
-        out.cost = c;
+        if (Object.keys(l).length > 0)
+            out.limit = l;
     }
+    const cost = trimCost(raw["cost"]);
+    if (cost !== undefined)
+        out.cost = cost;
+    const interleaved = raw["interleaved"];
+    if (interleaved === true)
+        out.interleaved = true;
+    else if (isRecord(interleaved) && typeof interleaved["field"] === "string")
+        out.interleaved = { field: interleaved["field"] };
     return out;
 }
+/** 快照过滤：丢 deprecated、输出不含文本、上下文为 0 / 缺失、tool_call:false（docs/wave5-plan.md §2.1）。 */
+export function keepForSnapshot(raw) {
+    if (!isRecord(raw))
+        return false;
+    if (raw["status"] === "deprecated" || raw["tool_call"] === false)
+        return false;
+    const modalities = raw["modalities"];
+    const output = isRecord(modalities) ? strings(modalities["output"]) : undefined;
+    if (output !== undefined && !output.includes("text"))
+        return false;
+    const limit = raw["limit"];
+    return isRecord(limit) && positive(limit["context"]) !== undefined;
+}
+/** 裁剪一家供应商；`keep` 给出时只留它放行的模型（模型 id 按字典序）。 */
+export function trimProvider(providerId, provider, keep) {
+    const models = {};
+    const rawModels = isRecord(provider["models"]) ? provider["models"] : {};
+    for (const modelId of Object.keys(rawModels).sort()) {
+        const model = rawModels[modelId];
+        if (!isRecord(model) || (keep !== undefined && !keep(modelId, model)))
+            continue;
+        models[modelId] = trimModel(modelId, model);
+    }
+    return {
+        id: providerId,
+        ...(typeof provider["name"] === "string" ? { name: provider["name"] } : {}),
+        ...(typeof provider["api"] === "string" ? { api: provider["api"] } : {}),
+        models,
+    };
+}
 /** 校验并裁剪 api.json：只留用到的字段；形状不对的供应商 / 模型跳过。整体不是对象抛错。 */
 export function trimModelsDev(raw) {
     if (!isRecord(raw))
@@ -95,16 +173,7 @@ export function trimModelsDev(raw) {
     for (const [providerId, provider] of Object.entries(raw)) {
         if (!isRecord(provider) || !isRecord(provider["models"]))
             continue;
-        const models = {};
-        for (const [modelId, model] of Object.entries(provider["models"])) {
-            if (isRecord(model))
-                models[modelId] = trimModel(modelId, model);
-        }
-        out[providerId] = {
-            id: providerId,
-            ...(typeof provider["name"] === "string" ? { name: provider["name"] } : {}),
-            models,
-        };
+        out[providerId] = trimProvider(providerId, provider);
     }
     return out;
 }
@@ -260,8 +329,17 @@ export class ModelsDevIndex {
         return match;
     }
 }
-/** models.dev 条目 → ama Model 字段（规则见 docs/providers.md）。 */
-export function modelsDevFields(model) {
+function toCost(p, mapping) {
+    const missing = mapping === "catalog" ? 0 : p.input;
+    return {
+        input: p.input,
+        output: p.output,
+        cacheRead: p.cache_read ?? missing,
+        cacheWrite: p.cache_write ?? missing,
+    };
+}
+/** models.dev 条目 → ama Model 字段（规则见 docs/providers.md「模型元数据」）。 */
+export function modelsDevFields(model, mapping = "custom") {
     const out = {};
     if (model.name !== undefined)
         out.name = model.name;
@@ -270,8 +348,12 @@ export function modelsDevFields(model) {
         out.contextWindow = Math.floor(context);
     const output = positive(model.limit?.output);
     if (output !== undefined) {
-        out.maxTokens = Math.floor(Math.min(output, MODELS_DEV_MAX_OUTPUT, context ?? output));
+        const cap = mapping === "catalog" ? output : MODELS_DEV_MAX_OUTPUT;
+        out.maxTokens = Math.floor(Math.min(output, cap, context ?? output));
     }
+    const inputLimit = positive(model.limit?.input);
+    if (inputLimit !== undefined && inputLimit !== context)
+        out.inputLimit = Math.floor(inputLimit);
     const input = model.modalities?.input;
     if (input !== undefined)
         out.input = input.includes("image") ? ["text", "image"] : ["text"];
@@ -281,13 +363,24 @@ export function modelsDevFields(model) {
         out.toolCall = model.tool_call;
     const cost = model.cost;
     if (cost?.input !== undefined && cost.output !== undefined) {
-        out.cost = {
-            input: cost.input,
-            output: cost.output,
-            cacheRead: cost.cache_read ?? cost.input,
-            cacheWrite: cost.cache_write ?? cost.input,
-        };
+        out.cost = toCost(cost, mapping);
+        // 档位：优先通用 tiers；只有 context_over_200k 时折成 200k 一档。
+        const tiers = cost.tiers !== undefined && cost.tiers.length > 0
+            ? cost.tiers.map((t) => ({ inputTokensAbove: t.tier.size, ...toCost(t, mapping) }))
+            : cost.context_over_200k !== undefined
+                ? [{ inputTokensAbove: 200_000, ...toCost(cost.context_over_200k, mapping) }]
+                : [];
+        if (tiers.length > 0)
+            out.cost.tiers = tiers.sort((a, b) => a.inputTokensAbove - b.inputTokensAbove);
     }
+    if (model.family !== undefined)
+        out.family = model.family;
+    if (model.knowledge !== undefined)
+        out.knowledge = model.knowledge;
+    if (model.release_date !== undefined)
+        out.releaseDate = model.release_date;
+    if (model.status === "beta")
+        out.status = "beta";
     return out;
 }
 /** 可由 models.dev 补的 Model 字段（展示来源用）。 */

package/dist/ai/providers/registry.d.ts

@@ -19,14 +19,21 @@
  * 重新物化（协议、地址、headers、compat 取渠道的，模型级 api / baseUrl 仍覆盖）；渠道 key 经
  * `resolveApiKey(provider, channel)`。没有 `channels` 的供应商行为不变。
  *
+ * 内置渠道（[W5-M2]，builtin.ts）：用户 `channels` 同名字段级覆盖、新名追加，`defaultChannel` 用户优先
+ * （也可只写 `defaultChannel`，或只写 `api` 选同协议的内置渠道）；目录模型缺省挂全部渠道、缺省渠道在前。
+ * 用户（config / auth.json / `*_BASE_URL`）改了供应商级 baseUrl 而没写自己的 `channels` 时，内置渠道作废，
+ * 按单渠道回落（`api` 取用户写的或内置的回落协议）。
+ *
  * models.dev（enrich.ts）：config 里缺元数据的自定义模型与合成模型，用传入的索引（只读缓存）补
- * contextWindow / maxTokens / input / reasoning / cost，来源记在 `modelMetadata()`；内置目录不补。
+ * contextWindow / maxTokens / input / reasoning / cost，来源记在 `modelMetadata()`；内置目录按同一索引
+ * （快照 ⊕ `ama models refresh` 的覆盖）在 catalog.ts 合并，缺字段的条目退回内置快照。
  */
 import type { AmaConfig } from "../../config/types.js";
 import { ApiRegistry } from "../apis/api.js";
-import type { Api, ApiImplementation, ApiKeyResolution, Model, ModelLookup, ProviderChannel, ProviderData, ProviderRegistryApi } from "../types.js";
+import type { Api, ApiImplementation, ApiKeyResolution, Model, ModelLookup, ProviderData, ProviderRegistryApi } from "../types.js";
 import { type KeyResolverOptions } from "./auth.js";
 import { type ModelMetadata, type ModelsDevSource } from "./enrich.js";
+export { materializeModel } from "./channels.js";
 export type ModelSource = "builtin" | "config" | "discovered";
 export interface ProviderRegistryOptions {
     config?: AmaConfig | undefined;
@@ -48,14 +55,6 @@ export interface ModelEntry {
     provider: ProviderData;
     source: ModelSource;
 }
-/**
- * 物化：模型补齐供应商级字段（不可变：返回新对象）。给了 `channel` 时协议与地址取渠道的（模型级
- * `explicit` 覆盖优先），headers / compat 按 供应商 ← 渠道 ← 模型 合并，并记下渠道名。
- */
-export declare function materializeModel(model: Model, provider: ProviderData, channel?: ProviderChannel, explicit?: {
-    api?: Api | undefined;
-    baseUrl?: string | undefined;
-}): Model;
 export declare class ProviderRegistry implements ProviderRegistryApi {
     readonly warnings: string[];
     private readonly providers;
@@ -64,6 +63,10 @@ export declare class ProviderRegistry implements ProviderRegistryApi {
     private readonly envBaseUrls;
     /** baseUrl 指向非官方主机的内置供应商：接受目录外的 model id。 */
     private readonly relayed;
+    /** config 里写了自己 `channels` 的供应商（内置渠道不因改 baseUrl 作废）。 */
+    private readonly userChannels;
+    /** config 里写了供应商级 `api` 的供应商（单渠道回落时目录模型跟它走）。 */
+    private readonly userApi;
     /** `provider/model` → 物化前的模型（多渠道供应商切换渠道时重新物化）。 */
     private readonly raw;
     /** `provider/model` → 元数据来源与 models.dev 匹配。 */
@@ -73,6 +76,13 @@ export declare class ProviderRegistry implements ProviderRegistryApi {
     private readonly keys;
     private readonly onWarning;
     constructor(options?: ProviderRegistryOptions);
+    /** 内置目录（快照 ⊕ 用户刷新）；刷新数据出任何问题都退回内置快照，不让启动失败。 */
+    private loadCatalog;
+    /**
+     * 内置供应商定渠道：供应商级 api / baseUrl 取缺省渠道的（discover 等单地址的用法看它）；用户没指定渠道的
+     * 模型挂全部渠道（缺省在前）。渠道已作废的去掉模型上残留的 `channels`。
+     */
+    private settleBuiltinChannels;
     private warn;
     /** 物化并记下原始模型；多渠道供应商用模型的首选渠道。 */
     private materialize;
@@ -90,10 +100,17 @@ export declare class ProviderRegistry implements ProviderRegistryApi {
     /** 追加 / 替换模型（例如本地枚举得到的 ollama 模型）。 */
     addModels(providerId: string, models: readonly Model[], source?: ModelSource): void;
     private synthesize;
-    /** 按渠道取模型：渠道不在模型的 channels 里 → 列出可用渠道。 */
+    /** 按渠道取模型：渠道不在模型的 channels 里 → channel_not_found，列出可用渠道。 */
     private withChannel;
+    /**
+     * `provider/model`、`provider/model@渠道` 或裸模型 id。`@` 先按渠道解析（id 里本来就带 `@` 且已登记的
+     * 模型除外），中转供应商的「未登记即合成」不会把 `@渠道` 吞进模型 id。失败的 reason：供应商不存在 →
+     * provider_not_found（候选是编辑距离最近的供应商）；渠道不存在 → channel_not_found；模型不存在 →
+     * not_found（候选是最接近的模型）。
+     */
     findModel(ref: string): ModelLookup;
     private findPlain;
+    /** 最接近的模型（包含关系优先，其次编辑距离），`provider/id` 形式。 */
     private similar;
     hasConfiguredKey(providerId: string): boolean;
     resolveApiKey(providerId: string, channel?: string): Promise<ApiKeyResolution>;