@armadra/agent 0.3.0 → 0.5.0

package/dist/ai/providers/catalog.js

@@ -5,31 +5,81 @@
  * 的字符串表（`UPDATE_CATALOG=1 pnpm vitest run src/ai/providers/catalog.test.ts` 重新生成，
  * 测试守住两者一致）。本模块解析并校验它，另提供覆盖合并。
  *
- * 必填字段：id、name、maxTokens、reasoning；contextWindow 与 cost「宁缺不猜」——数据源里
- * 不确定的就不写（缺 contextWindow → 关自动压缩并警告；缺 cost → 显示 `$?`）。`promptCache`
+ * [W5-M1] 「快照 ⊕ 覆盖」格式（docs/wave5-plan.md §2.2、D6）：文件级 `modelsDev` 指向 models.dev
+ * 快照里的供应商 id（`false` = 没有对应），条目按 `<modelsDev>/<id>`（或条目自己的 `modelsDev:
+ * "provider/model"`）从快照继承数值事实——name、reasoning、contextWindow、maxTokens、input、cost、
+ * family / knowledge / releaseDate / inputLimit / status；目录只写覆盖项与 ama 特有字段（`api`、
+ * `thinkingLevelMap`、`promptCache`、`compat`、有意调小的 `maxTokens` 等）。`cost` 可只写要覆盖的键。
+ * `_reason` 是注释字段（运行时忽略；写了它的条目不做冗余检查，用来有意钉住与快照相同的值）。
+ *
+ * 合并后的必填字段：id、name、maxTokens、reasoning；contextWindow 与 cost「宁缺不猜」——快照与目录
+ * 都没有就不写（缺 contextWindow → 关自动压缩并警告；缺 cost → 显示 `$?`）。`promptCache`
  * （TTL 秒数与最小可缓存长度）同样只写有公开依据的值（第三波 §1.4），留空 = 不承诺。
  */
+import { isDeepStrictEqual } from "node:util";
 import { AmaError } from "../../errors.js";
 import { CATALOG_SOURCES } from "./catalog-data.js";
 import { THINKING_LEVELS } from "../thinking.js";
+import { modelsDevFields } from "./models-dev.js";
+import { builtinSnapshotIndex } from "./models-dev-snapshot.js";
+/** 从快照继承的字段（顺序即冗余检查与来源展示的顺序）。 */
+export const INHERITED_FIELDS = [
+    "name",
+    "reasoning",
+    "contextWindow",
+    "maxTokens",
+    "input",
+    "cost",
+    "family",
+    "knowledge",
+    "releaseDate",
+    "inputLimit",
+    "status",
+];
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isNonNegative(value) {
     return typeof value === "number" && Number.isFinite(value) && value >= 0;
 }
-/** 校验一个模型条目，返回问题列表（空 = 合法）。 */
+/** 校验合并后的模型（必填齐全、cost 四个价都在），返回问题列表（空 = 合法）。 */
 export function checkCatalogModel(value, path) {
+    if (!isRecord(value))
+        return [`${path}: must be an object`];
+    const problems = [];
+    if (typeof value["name"] !== "string")
+        problems.push(`${path}.name`);
+    if (typeof value["reasoning"] !== "boolean")
+        problems.push(`${path}.reasoning`);
+    if (value["maxTokens"] === undefined)
+        problems.push(`${path}.maxTokens`);
+    const cost = value["cost"];
+    if (isRecord(cost)) {
+        for (const key of ["input", "output", "cacheRead", "cacheWrite"]) {
+            if (cost[key] === undefined)
+                problems.push(`${path}.cost.${key}`);
+        }
+    }
+    return [...new Set([...problems, ...checkCatalogEntry(value, path)])];
+}
+/** 校验目录里的一条（覆盖格式：只查写了的字段），返回问题列表（空 = 合法）。 */
+export function checkCatalogEntry(value, path) {
     const problems = [];
     if (!isRecord(value))
         return [`${path}: must be an object`];
     if (typeof value["id"] !== "string" || value["id"].length === 0)
         problems.push(`${path}.id`);
-    if (typeof value["name"] !== "string")
+    if (value["name"] !== undefined && typeof value["name"] !== "string")
         problems.push(`${path}.name`);
-    if (typeof value["reasoning"] !== "boolean")
+    if (value["reasoning"] !== undefined && typeof value["reasoning"] !== "boolean")
         problems.push(`${path}.reasoning`);
-    if (!isNonNegative(value["maxTokens"]) || value["maxTokens"] === 0) {
+    const modelsDev = value["modelsDev"];
+    if (modelsDev !== undefined && modelsDev !== false && typeof modelsDev !== "string")
+        problems.push(`${path}.modelsDev`);
+    if (value["_reason"] !== undefined && typeof value["_reason"] !== "string")
+        problems.push(`${path}._reason`);
+    if (value["maxTokens"] !== undefined &&
+        (!isNonNegative(value["maxTokens"]) || value["maxTokens"] === 0)) {
         problems.push(`${path}.maxTokens`);
     }
     if (value["contextWindow"] !== undefined && !isNonNegative(value["contextWindow"])) {
@@ -46,7 +96,7 @@ export function checkCatalogModel(value, path) {
             problems.push(`${path}.cost`);
         else {
             for (const key of ["input", "output", "cacheRead", "cacheWrite"]) {
-                if (!isNonNegative(cost[key]))
+                if (cost[key] !== undefined && !isNonNegative(cost[key]))
                     problems.push(`${path}.cost.${key}`);
             }
             if (cost["tiers"] !== undefined && !Array.isArray(cost["tiers"])) {
@@ -86,50 +136,159 @@ export function checkCatalogModel(value, path) {
     }
     return problems;
 }
-export function parseCatalogFile(value, source) {
+/** 一条目录条目对应的快照条目 `provider/model`（没有返回 undefined）。 */
+export function snapshotRefOf(file, entry) {
+    if (entry.modelsDev === false)
+        return undefined;
+    if (typeof entry.modelsDev === "string")
+        return entry.modelsDev;
+    return typeof file.modelsDev === "string" ? `${file.modelsDev}/${entry.id}` : undefined;
+}
+/** 快照能给这条目录条目的字段（catalog 口径：不封顶、缺缓存价记 0）。 */
+export function inheritedFields(file, entry, index = builtinSnapshotIndex()) {
+    const ref = snapshotRefOf(file, entry);
+    const model = ref !== undefined ? index.get(ref) : undefined;
+    if (model === undefined)
+        return {};
+    const fields = modelsDevFields(model, "catalog");
+    const out = {};
+    for (const key of INHERITED_FIELDS) {
+        if (fields[key] !== undefined)
+            out[key] = fields[key];
+    }
+    return out;
+}
+/** 合并：快照 ⊕ 目录条目（`cost` 按键合并）；返回模型与从快照继承的字段名。 */
+export function resolveCatalogEntry(entry, inherited) {
+    const { modelsDev: _modelsDev, _reason: _r, ...own } = structuredClone(entry);
+    const model = { ...structuredClone(inherited), ...own };
+    if (own.cost !== undefined && inherited.cost !== undefined)
+        model.cost = { ...structuredClone(inherited.cost), ...own.cost };
+    // 目录有意把窗口调小（如 272k 计价档）时，继承来的更大的输入上限没有意义
+    if (own.inputLimit === undefined &&
+        model.inputLimit !== undefined &&
+        model.contextWindow !== undefined &&
+        model.inputLimit >= model.contextWindow)
+        delete model.inputLimit;
+    const from = INHERITED_FIELDS.filter((k) => own[k] === undefined && model[k] !== undefined);
+    return { model, inherited: from };
+}
+/**
+ * 与快照取值相同的覆盖项（冗余，测试报错；`UPDATE_CATALOG=1` 时自动删）：`name`、`cost.input` 一类路径。
+ * 写了 `_reason` 的条目不查。
+ */
+export function redundantFields(entry, inherited) {
+    if (entry._reason !== undefined)
+        return [];
+    const out = [];
+    for (const key of INHERITED_FIELDS) {
+        const own = entry[key];
+        const base = inherited[key];
+        if (own === undefined || base === undefined)
+            continue;
+        if (key === "cost" && isRecord(own) && isRecord(base)) {
+            for (const [k, v] of Object.entries(own))
+                if (isDeepStrictEqual(v, base[k]))
+                    out.push(`cost.${k}`);
+        }
+        else if (isDeepStrictEqual(own, base))
+            out.push(key);
+    }
+    return out;
+}
+function fileProblems(value) {
     const problems = [];
     if (!isRecord(value))
-        problems.push("$: must be an object");
+        return ["$: must be an object"];
+    if (value["version"] !== 1)
+        problems.push("$.version must be 1");
+    if (typeof value["provider"] !== "string")
+        problems.push("$.provider");
+    const modelsDev = value["modelsDev"];
+    if (modelsDev !== undefined && modelsDev !== false && typeof modelsDev !== "string")
+        problems.push("$.modelsDev");
+    if (!Array.isArray(value["models"]))
+        problems.push("$.models must be an array");
     else {
-        if (value["version"] !== 1)
-            problems.push("$.version must be 1");
-        if (typeof value["provider"] !== "string")
-            problems.push("$.provider");
-        if (!Array.isArray(value["models"]))
-            problems.push("$.models must be an array");
-        else {
-            const seen = new Set();
-            value["models"].forEach((model, i) => {
-                problems.push(...checkCatalogModel(model, `$.models[${i}]`));
-                const id = isRecord(model) ? model["id"] : undefined;
-                if (typeof id === "string") {
-                    if (seen.has(id))
-                        problems.push(`$.models[${i}].id duplicated: ${id}`);
-                    seen.add(id);
-                }
-            });
-        }
-    }
-    if (problems.length > 0) {
-        throw new AmaError("config_invalid", `model catalog ${source} is invalid: ${problems.join(", ")}`);
+        const seen = new Set();
+        value["models"].forEach((model, i) => {
+            problems.push(...checkCatalogEntry(model, `$.models[${i}]`));
+            const id = isRecord(model) ? model["id"] : undefined;
+            if (typeof id === "string") {
+                if (seen.has(id))
+                    problems.push(`$.models[${i}].id duplicated: ${id}`);
+                seen.add(id);
+            }
+        });
     }
+    return problems;
+}
+function invalid(source, problems) {
+    return new AmaError("config_invalid", `model catalog ${source} is invalid: ${problems.join(", ")}`);
+}
+/** 校验文件形状（覆盖格式），不合并。 */
+export function parseCatalogSource(value, source) {
+    const problems = fileProblems(value);
+    if (problems.length > 0)
+        throw invalid(source, problems);
     return value;
 }
-let cache;
-/** 内置目录：供应商 id → 模型条目（深拷贝，调用方可随意修改）。 */
-export function loadBuiltinCatalog() {
-    if (!cache) {
+function resolveFile(file, source, index) {
+    const problems = [];
+    const inherited = new Map();
+    const builtin = builtinSnapshotIndex();
+    const models = file.models.map((entry, i) => {
+        const path = `$.models[${i}]`;
+        let resolved = resolveCatalogEntry(entry, inheritedFields(file, entry, index ?? builtin));
+        let found = checkCatalogModel(resolved.model, path);
+        if (found.length > 0 && index !== undefined && index !== builtin) {
+            // 用户刷新的数据缺字段（上游改版）：这一条退回内置快照，不让启动失败。
+            resolved = resolveCatalogEntry(entry, inheritedFields(file, entry, builtin));
+            found = checkCatalogModel(resolved.model, path);
+        }
+        problems.push(...found);
+        inherited.set(entry.id, resolved.inherited);
+        return resolved.model;
+    });
+    if (problems.length > 0)
+        throw invalid(source, problems);
+    return { file: { version: 1, provider: file.provider, models }, inherited };
+}
+/** 校验并合并（快照 ⊕ 目录）一个目录文件；`index` 缺省用内置快照。 */
+export function parseCatalogFile(value, source, index) {
+    return resolveFile(parseCatalogSource(value, source), source, index).file;
+}
+const caches = new WeakMap();
+let lastInherited = new Map();
+/**
+ * 内置目录：供应商 id → 模型条目（深拷贝，调用方可随意修改）。`index` 缺省用内置快照；传入
+ * 「快照 ⊕ 用户刷新」的索引时目录也吃刷新后的数值（缺字段的条目退回内置快照）。
+ */
+export function loadBuiltinCatalog(index) {
+    const key = index ?? builtinSnapshotIndex();
+    let cache = caches.get(key);
+    if (cache === undefined) {
         cache = new Map();
         for (const [provider, raw] of Object.entries(CATALOG_SOURCES)) {
-            const file = parseCatalogFile(JSON.parse(raw), `catalog/${provider}.json`);
-            cache.set(file.provider, file.models);
+            const source = `catalog/${provider}.json`;
+            const resolved = resolveFile(parseCatalogSource(JSON.parse(raw), source), source, index);
+            cache.set(resolved.file.provider, resolved);
         }
+        caches.set(key, cache);
     }
     const copy = new Map();
-    for (const [provider, models] of cache)
-        copy.set(provider, structuredClone(models));
+    lastInherited = new Map();
+    for (const [provider, resolved] of cache) {
+        copy.set(provider, structuredClone(resolved.file.models));
+        for (const [id, fields] of resolved.inherited)
+            lastInherited.set(`${provider}/${id}`, fields);
+    }
     return copy;
 }
+/** 最近一次 `loadBuiltinCatalog()` 里，该目录模型从快照继承的字段（来源展示用）。 */
+export function catalogInherited(provider, modelId) {
+    return lastInherited.get(`${provider}/${modelId}`) ?? [];
+}
 /** 目录条目 → Model（补 provider / api 与缺省 input）。 */
 export function toModel(entry, provider, api) {
     return { ...structuredClone(entry), input: entry.input ?? ["text"], provider, api };

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

@@ -10,17 +10,32 @@
  *   auth.json 的同名条目），没有时用供应商的 key。
  */
 import type { ProviderConfig } from "../../config/types.js";
-import type { Api, ProviderChannel } from "../types.js";
+import type { Api, Model, ProviderChannel, ProviderData } from "../types.js";
 /** 隐式渠道名（单渠道供应商）。 */
 export declare const DEFAULT_CHANNEL = "default";
 /** 渠道 key 在 key 解析里的键。 */
 export declare function channelKeyId(providerId: string, channel: string): string;
-/** config 的 `channels` → 物化渠道表（跳过名字非法或缺 api / baseUrl 的，返回警告）。 */
-export declare function parseChannels(providerId: string, config: ProviderConfig): {
+/**
+ * 内置渠道 ⊕ 用户渠道（[W5-M2]）：同名按字段覆盖（`headers` / `compat` 再合并一层）、新名追加在后。
+ */
+export declare function mergeChannels(base: readonly ProviderChannel[], user: readonly ProviderChannel[]): ProviderChannel[];
+/**
+ * config 的 `channels` → 物化渠道表（跳过名字非法或缺 api / baseUrl 的，返回警告）。给了 `builtin`
+ * （内置供应商的内置渠道）时与之合并：同名渠道可只写要改的字段；`defaultChannel` 用户优先，其次内置。
+ */
+export declare function parseChannels(providerId: string, config: ProviderConfig, builtin?: {
+    channels: readonly ProviderChannel[];
+    defaultChannel: string | undefined;
+}): {
     channels: ProviderChannel[];
     defaultChannel: string | undefined;
     warnings: string[];
 };
+/**
+ * 内置供应商目录模型的渠道表：目录条目写了 `channels` 就用它（去掉不存在的），否则挂全部渠道；
+ * 缺省渠道在表里时排到首位（首个 = 首选）。
+ */
+export declare function catalogChannels(wanted: readonly string[] | undefined, known: readonly ProviderChannel[], defaultChannel: string): string[];
 /** 模型的渠道表：去掉不存在的；空 → [defaultChannel]。 */
 export declare function modelChannels(wanted: readonly string[] | undefined, known: readonly ProviderChannel[], defaultChannel: string, onUnknown: (name: string) => void): string[];
 /**
@@ -49,3 +64,18 @@ export declare function modelRefOf(model: {
 };
 /** 协议的短名（表格用）。 */
 export declare function apiShortName(api: Api): string;
+/**
+ * 物化：模型补齐供应商级字段（不可变：返回新对象）。给了 `channel` 时协议与地址取渠道的（模型级
+ * `explicit` 覆盖优先），headers / compat 按 供应商 ← 渠道 ← 模型 合并，并记下渠道名。
+ */
+export declare function materializeModel(model: Model, provider: ProviderData, channel?: ProviderChannel, explicit?: {
+    api?: Api | undefined;
+    baseUrl?: string | undefined;
+}): Model;
+/** 内置渠道作废：按供应商级 api / baseUrl 单渠道处理。 */
+export declare function dropChannels(provider: ProviderData): void;
+/**
+ * 内置渠道 + 用户只改供应商级字段：改了 baseUrl → 内置渠道作废（单渠道回落）；只写 `api` → 选同协议的
+ * 内置渠道作缺省（没有就作废）；`defaultChannel` 必须是内置渠道名。
+ */
+export declare function pickBuiltinChannel(provider: ProviderData, config: ProviderConfig, warn: (message: string) => void): void;

package/dist/ai/providers/channels.js

@@ -10,37 +10,84 @@
  *   auth.json 的同名条目），没有时用供应商的 key。
  */
 import { CHANNEL_NAME_PATTERN } from "../../config/types.js";
+import { mergeHeaders } from "../http.js";
 /** 隐式渠道名（单渠道供应商）。 */
 export const DEFAULT_CHANNEL = "default";
 /** 渠道 key 在 key 解析里的键。 */
 export function channelKeyId(providerId, channel) {
     return `${providerId}@${channel}`;
 }
-/** config 的 `channels` → 物化渠道表（跳过名字非法或缺 api / baseUrl 的，返回警告）。 */
-export function parseChannels(providerId, config) {
+/**
+ * 内置渠道 ⊕ 用户渠道（[W5-M2]）：同名按字段覆盖（`headers` / `compat` 再合并一层）、新名追加在后。
+ */
+export function mergeChannels(base, user) {
+    const out = base.map((c) => structuredClone(c));
+    for (const channel of user) {
+        const index = out.findIndex((c) => c.name === channel.name);
+        const current = out[index];
+        if (current === undefined) {
+            out.push(channel);
+            continue;
+        }
+        const next = { ...current, ...channel };
+        if (current.headers && channel.headers)
+            next.headers = { ...current.headers, ...channel.headers };
+        if (current.compat && channel.compat)
+            next.compat = { ...current.compat, ...channel.compat };
+        out[index] = next;
+    }
+    return out;
+}
+/**
+ * config 的 `channels` → 物化渠道表（跳过名字非法或缺 api / baseUrl 的，返回警告）。给了 `builtin`
+ * （内置供应商的内置渠道）时与之合并：同名渠道可只写要改的字段；`defaultChannel` 用户优先，其次内置。
+ */
+export function parseChannels(providerId, config, builtin) {
     const warnings = [];
-    const channels = [];
+    const own = [];
+    const known = new Set((builtin?.channels ?? []).map((c) => c.name));
     for (const [name, raw] of Object.entries(config.channels ?? {})) {
         const c = raw;
-        if (!CHANNEL_NAME_PATTERN.test(name) || !c || !c.api || !c.baseUrl) {
+        const partial = known.has(name);
+        if (!CHANNEL_NAME_PATTERN.test(name) || !c || (!partial && (!c.api || !c.baseUrl))) {
             warnings.push(`provider "${providerId}" channel "${name}" is invalid; ignored`);
             continue;
         }
-        const channel = { name, api: c.api, baseUrl: c.baseUrl };
+        const channel = { name };
+        if (c.api)
+            channel.api = c.api;
+        if (c.baseUrl)
+            channel.baseUrl = c.baseUrl;
         if (c.authHeader !== undefined)
             channel.authHeader = c.authHeader;
         if (c.headers !== undefined)
             channel.headers = { ...c.headers };
         if (c.compat !== undefined)
             channel.compat = { ...c.compat };
-        channels.push(channel);
+        own.push(channel);
     }
+    const channels = mergeChannels(builtin?.channels ?? [], own);
     let defaultChannel = config.defaultChannel;
     if (defaultChannel !== undefined && !channels.some((c) => c.name === defaultChannel)) {
         warnings.push(`provider "${providerId}" defaultChannel "${defaultChannel}" not found`);
         defaultChannel = undefined;
     }
-    return { channels, defaultChannel: defaultChannel ?? channels[0]?.name, warnings };
+    const fallback = channels.some((c) => c.name === builtin?.defaultChannel)
+        ? builtin?.defaultChannel
+        : channels[0]?.name;
+    return { channels, defaultChannel: defaultChannel ?? fallback, warnings };
+}
+/**
+ * 内置供应商目录模型的渠道表：目录条目写了 `channels` 就用它（去掉不存在的），否则挂全部渠道；
+ * 缺省渠道在表里时排到首位（首个 = 首选）。
+ */
+export function catalogChannels(wanted, known, defaultChannel) {
+    const names = known.map((c) => c.name);
+    const list = wanted === undefined ? names : wanted.filter((name) => names.includes(name));
+    const out = list.includes(defaultChannel)
+        ? [defaultChannel, ...list.filter((name) => name !== defaultChannel)]
+        : [...list];
+    return out.length > 0 ? out : [defaultChannel];
 }
 /** 模型的渠道表：去掉不存在的；空 → [defaultChannel]。 */
 export function modelChannels(wanted, known, defaultChannel, onUnknown) {
@@ -94,3 +141,57 @@ export function apiShortName(api) {
             return api;
     }
 }
+/**
+ * 物化：模型补齐供应商级字段（不可变：返回新对象）。给了 `channel` 时协议与地址取渠道的（模型级
+ * `explicit` 覆盖优先），headers / compat 按 供应商 ← 渠道 ← 模型 合并，并记下渠道名。
+ */
+export function materializeModel(model, provider, channel, explicit) {
+    const out = {
+        ...model,
+        provider: provider.id,
+        baseUrl: model.baseUrl ?? provider.baseUrl,
+    };
+    if (channel !== undefined) {
+        out.api = explicit?.api ?? channel.api;
+        out.baseUrl = explicit?.baseUrl ?? channel.baseUrl;
+        out.channel = channel.name;
+    }
+    if (provider.headers || channel?.headers || model.headers)
+        out.headers = mergeHeaders(provider.headers, channel?.headers, model.headers);
+    if (provider.compat || channel?.compat || model.compat)
+        out.compat = { ...provider.compat, ...channel?.compat, ...model.compat };
+    const authHeader = channel?.authHeader ?? provider.authHeader;
+    if (authHeader !== undefined)
+        out.authHeader = model.authHeader ?? authHeader;
+    out.requiresApiKey = provider.requiresApiKey;
+    return out;
+}
+/** 内置渠道作废：按供应商级 api / baseUrl 单渠道处理。 */
+export function dropChannels(provider) {
+    delete provider.channels;
+    delete provider.defaultChannel;
+}
+/**
+ * 内置渠道 + 用户只改供应商级字段：改了 baseUrl → 内置渠道作废（单渠道回落）；只写 `api` → 选同协议的
+ * 内置渠道作缺省（没有就作废）；`defaultChannel` 必须是内置渠道名。
+ */
+export function pickBuiltinChannel(provider, config, warn) {
+    if (config.baseUrl !== undefined) {
+        dropChannels(provider);
+        return;
+    }
+    const channels = provider.channels ?? [];
+    if (config.defaultChannel !== undefined) {
+        if (channels.some((c) => c.name === config.defaultChannel))
+            provider.defaultChannel = config.defaultChannel;
+        else
+            warn(`provider "${provider.id}" defaultChannel "${config.defaultChannel}" not found`);
+    }
+    else if (config.api !== undefined) {
+        const same = channels.find((c) => c.api === config.api);
+        if (same !== undefined)
+            provider.defaultChannel = same.name;
+        else
+            dropChannels(provider);
+    }
+}

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

@@ -2,8 +2,8 @@
  * 用 models.dev 缓存给自定义模型补元数据（docs/providers.md「模型元数据：models.dev」）。
  *
  * 优先级：用户配置写了的字段 > models.dev > 自定义缺省（maxTokens 8192、input ["text"]、
- * reasoning false、不猜 contextWindow）。内置目录的模型不经过这里（目录本身就是人工校对的值）。
- * 只读传入的索引，不联网。
+ * reasoning false、不猜 contextWindow）。内置目录的模型不经过这里：目录在 catalog.ts 里已经
+ * 「快照 ⊕ 覆盖」合并好（[W5-M1]），这里只给它们标来源。只读传入的索引，不联网。
  */
 import type { ModelConfig } from "../../config/types.js";
 import type { Model } from "../types.js";
@@ -29,6 +29,9 @@ export declare function enrichEntry(entry: ModelConfig, index: () => ModelsDevIn
     entry: Omit<ModelConfig, "modelsDev" | "channels">;
     metadata: ModelMetadata;
 };
-/** 内置目录模型的来源（全部 catalog；目录没写 contextWindow / cost 的为缺省）。 */
+/**
+ * 内置目录模型的来源：目录自己写的为 catalog，从入库快照继承的为 models.dev（catalog.ts），
+ * 都没有的为缺省。
+ */
 export declare function catalogMetadata(model: Model): ModelMetadata;
 export declare function sourceText(source: FieldSource): string;

package/dist/ai/providers/enrich.js

@@ -2,9 +2,10 @@
  * 用 models.dev 缓存给自定义模型补元数据（docs/providers.md「模型元数据：models.dev」）。
  *
  * 优先级：用户配置写了的字段 > models.dev > 自定义缺省（maxTokens 8192、input ["text"]、
- * reasoning false、不猜 contextWindow）。内置目录的模型不经过这里（目录本身就是人工校对的值）。
- * 只读传入的索引，不联网。
+ * reasoning false、不猜 contextWindow）。内置目录的模型不经过这里：目录在 catalog.ts 里已经
+ * 「快照 ⊕ 覆盖」合并好（[W5-M1]），这里只给它们标来源。只读传入的索引，不联网。
  */
+import { catalogInherited } from "./catalog.js";
 import { ENRICHABLE_FIELDS, modelsDevFields, } from "./models-dev.js";
 /** 惰性取索引：只有真的要补字段时才读缓存（启动时没有自定义模型就不读约 2 MB 的缓存）。 */
 export function lazyIndex(source) {
@@ -25,6 +26,8 @@ export function lazyIndex(source) {
         return index;
     };
 }
+/** 只作说明的元数据（不进来源表）：缺了就从 models.dev 补。 */
+const METADATA_FIELDS = ["family", "knowledge", "releaseDate", "inputLimit", "status"];
 function needsLookup(entry) {
     return ENRICHABLE_FIELDS.some((field) => entry[field] === undefined);
 }
@@ -65,13 +68,25 @@ export function enrichEntry(entry, index) {
     }
     if (out.name === undefined && fields.name !== undefined)
         out.name = fields.name;
+    for (const field of METADATA_FIELDS) {
+        if (out[field] === undefined && fields[field] !== undefined)
+            out[field] = fields[field];
+    }
     return { entry: out, metadata };
 }
-/** 内置目录模型的来源（全部 catalog；目录没写 contextWindow / cost 的为缺省）。 */
+/**
+ * 内置目录模型的来源：目录自己写的为 catalog，从入库快照继承的为 models.dev（catalog.ts），
+ * 都没有的为缺省。
+ */
 export function catalogMetadata(model) {
+    const inherited = catalogInherited(model.provider, model.id);
     const sources = {};
     for (const field of ENRICHABLE_FIELDS) {
-        sources[field] = model[field] !== undefined ? "catalog" : "default";
+        sources[field] = inherited.includes(field)
+            ? "models.dev"
+            : model[field] !== undefined
+                ? "catalog"
+                : "default";
     }
     return { sources, looked: false };
 }

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

@@ -1,53 +1,57 @@
 /**
- * models.dev 缓存（docs/providers.md「模型元数据：models.dev」）。
+ * models.dev 索引 = 内置快照 ⊕ 用户级覆盖（docs/wave5-plan.md §2.2、docs/providers.md「模型元数据」）。
  *
- * - 缓存文件 `<dataDir>/models-dev.json`：`{ version, url, fetchedAt, etag?, providers }`，providers 是
- *   `trimModelsDev()` 裁剪后的数据（约 2.3 MB，原始约 5 MB）。写入走同目录临时文件 + rename。
- * - **启动不联网**：`loadModelsDevIndex()` 只读缓存（按路径 + mtime 记忆，同一进程只解析一次）。
- * - 联网只在 `ama providers add|refresh`、`ama models discover`、`ama models refresh-catalog` 调
- *   `refreshModelsDev()` 时发生：缓存 24 小时内不重拉（`force` 例外），带 `If-None-Match`；304 只刷新时间；
- *   失败时返回旧缓存与 warning。`AMA_MODELS_DEV_URL` 换数据源。
+ * - 内置快照随 bundle 携带（models-dev-snapshot.ts），**启动与运行都不联网**。
+ * - 覆盖文件 `<dataDir>/models-dev.json`：`{ version: 2, url, fetchedAt, providers }`，只有
+ *   `ama models refresh` 会写（`refreshModelsDev()`，显式联网，按快照同一清单裁剪）。存在且
+ *   fetchedAt 晚于快照才叠加；同 provider/model 以覆盖为准。旧版（version 1，全量 2 MB 缓存）忽略。
+ * - `loadModelsDevIndex()` 按覆盖文件路径 + mtime + 大小记忆，同一进程只解析一次。
+ * - `AMA_MODELS_DEV_URL` 换刷新的数据源。
  */
-import { ModelsDevIndex, type ModelsDevData } from "./models-dev.js";
+import type { ModelsDevData, ModelsDevIndex } from "./models-dev.js";
+import { type SnapshotDiff } from "./models-dev-snapshot.js";
 export declare const MODELS_DEV_URL = "https://models.dev/api.json";
 export declare const MODELS_DEV_URL_ENV = "AMA_MODELS_DEV_URL";
 export declare const MODELS_DEV_FILE = "models-dev.json";
-export declare const MODELS_DEV_TTL_MS: number;
-export declare const MODELS_DEV_TIMEOUT_MS = 30000;
+export declare const MODELS_DEV_TIMEOUT_MS = 60000;
 export interface ModelsDevCacheFile {
-    version: 1;
+    version: 2;
     url: string;
     /** ISO 8601。 */
     fetchedAt: string;
-    etag?: string;
     providers: ModelsDevData;
 }
 export declare function modelsDevCachePath(dataDir: string): string;
 export declare function modelsDevUrl(env?: Readonly<Record<string, string | undefined>>): string;
-/** 读缓存；不存在或损坏返回 undefined（损坏不报错：下次拉取会覆盖）。 */
+/** 读覆盖文件；不存在、旧版或损坏返回 undefined（损坏不报错：下次 refresh 会覆盖）。 */
 export declare function readModelsDevCache(dataDir: string): ModelsDevCacheFile | undefined;
 export declare function writeModelsDevCache(dataDir: string, file: ModelsDevCacheFile): void;
-/** 只读缓存构造索引（不联网）；没有缓存返回 undefined。 */
-export declare function loadModelsDevIndex(dataDir: string): ModelsDevIndex | undefined;
-export type RefreshStatus = "fresh" | "updated" | "not-modified" | "stale" | "unavailable";
+/** 覆盖文件是否生效：fetchedAt 晚于内置快照。 */
+export declare function overrideApplies(file: ModelsDevCacheFile): boolean;
+/** 快照 ⊕ 覆盖（零网络；没有覆盖文件时只做一次 stat）。 */
+export declare function loadModelsDevIndex(dataDir: string): ModelsDevIndex;
+/** 当前索引的来源说明（`providers add` / `models discover` 输出用）。 */
+export declare function describeModelsDev(dataDir: string): string;
+export type RefreshStatus = "updated" | "unchanged" | "failed";
 export interface RefreshResult {
     status: RefreshStatus;
-    index?: ModelsDevIndex;
-    fetchedAt?: string;
     url: string;
+    fetchedAt?: string;
+    /** 与刷新前的索引（快照 ⊕ 旧覆盖）相比。 */
+    diff?: SnapshotDiff;
+    index: ModelsDevIndex;
     warning?: string;
 }
 export interface RefreshOptions {
     dataDir: string;
     env?: Readonly<Record<string, string | undefined>>;
-    /** 忽略 TTL（`ama models refresh-catalog`）。 */
-    force?: boolean;
-    ttlMs?: number;
+    /** 只刷新这几家（须在快照清单里）。 */
+    providers?: readonly string[];
     timeoutMs?: number;
     now?: () => number;
     fetch?: typeof fetch;
 }
-/** 按需拉取 models.dev 并更新缓存；失败时回落旧缓存（status `stale`）或无数据（`unavailable`）。 */
+/** 显式联网刷新（只被 `ama models refresh` 调用）：拉 api.json、按清单裁剪、写用户级覆盖。 */
 export declare function refreshModelsDev(options: RefreshOptions): Promise<RefreshResult>;
-/** 一行状态说明（命令输出用）。 */
-export declare function describeRefresh(result: RefreshResult): string;
+/** 刷新结果的说明（命令输出用）：一行状态 + 新增 / 删除 / 变化清单。 */
+export declare function describeRefresh(result: RefreshResult, limit?: number): string;