@armadra/agent 0.4.0 → 0.5.0

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;

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

@@ -1,21 +1,21 @@
 /**
- * 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 { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { ModelsDevIndex, trimModelsDev } from "./models-dev.js";
+import { ModelsDevIndex as Index } from "./models-dev.js";
+import { buildSnapshot, builtinSnapshot, builtinSnapshotIndex, diffSnapshots, mergeSnapshot, snapshotList, snapshotMeta, } from "./models-dev-snapshot.js";
 export const MODELS_DEV_URL = "https://models.dev/api.json";
 export const MODELS_DEV_URL_ENV = "AMA_MODELS_DEV_URL";
 export const MODELS_DEV_FILE = "models-dev.json";
-export const MODELS_DEV_TTL_MS = 24 * 60 * 60 * 1000;
-export const MODELS_DEV_TIMEOUT_MS = 30_000;
+export const MODELS_DEV_TIMEOUT_MS = 60_000;
 export function modelsDevCachePath(dataDir) {
     return join(dataDir, MODELS_DEV_FILE);
 }
@@ -23,14 +23,16 @@ export function modelsDevUrl(env = process.env) {
     const custom = env[MODELS_DEV_URL_ENV]?.trim();
     return custom ? custom : MODELS_DEV_URL;
 }
-/** 读缓存；不存在或损坏返回 undefined（损坏不报错：下次拉取会覆盖）。 */
+/** 读覆盖文件；不存在、旧版或损坏返回 undefined（损坏不报错：下次 refresh 会覆盖）。 */
 export function readModelsDevCache(dataDir) {
     try {
         const value = JSON.parse(readFileSync(modelsDevCachePath(dataDir), "utf8"));
         if (typeof value !== "object" || value === null)
             return undefined;
         const file = value;
-        if (file.version !== 1 || typeof file.fetchedAt !== "string")
+        if (file.version !== 2 || typeof file.fetchedAt !== "string")
+            return undefined;
+        if (Number.isNaN(Date.parse(file.fetchedAt)))
             return undefined;
         if (typeof file.providers !== "object" || file.providers === null)
             return undefined;
@@ -48,8 +50,12 @@ export function writeModelsDevCache(dataDir, file) {
     renameSync(tmp, path);
     memo = undefined;
 }
+/** 覆盖文件是否生效：fetchedAt 晚于内置快照。 */
+export function overrideApplies(file) {
+    return Date.parse(file.fetchedAt) > Date.parse(snapshotMeta().fetchedAt);
+}
 let memo;
-/** 只读缓存构造索引（不联网）；没有缓存返回 undefined。 */
+/** 快照 ⊕ 覆盖（零网络；没有覆盖文件时只做一次 stat）。 */
 export function loadModelsDevIndex(dataDir) {
     const path = modelsDevCachePath(dataDir);
     let key;
@@ -58,90 +64,98 @@ export function loadModelsDevIndex(dataDir) {
         key = `${path}\0${stat.mtimeMs}\0${stat.size}`;
     }
     catch {
-        return undefined;
+        return builtinSnapshotIndex();
     }
     if (memo?.key === key)
         return memo.index;
     const file = readModelsDevCache(dataDir);
-    const index = file !== undefined ? new ModelsDevIndex(file.providers) : undefined;
+    const index = file !== undefined && overrideApplies(file)
+        ? new Index(mergeSnapshot(builtinSnapshot(), file.providers))
+        : builtinSnapshotIndex();
     memo = { key, index };
     return index;
 }
-/** 按需拉取 models.dev 并更新缓存；失败时回落旧缓存（status `stale`）或无数据（`unavailable`）。 */
+/** 当前索引的来源说明（`providers add` / `models discover` 输出用）。 */
+export function describeModelsDev(dataDir) {
+    const index = loadModelsDevIndex(dataDir);
+    const file = readModelsDevCache(dataDir);
+    const size = `${index.providerCount} 家供应商、${index.modelCount} 个模型`;
+    const via = file !== undefined && overrideApplies(file)
+        ? `快照 ${snapshotMeta().fetchedAt} ⊕ 刷新 ${file.fetchedAt}`
+        : `快照 ${snapshotMeta().fetchedAt}`;
+    return `models.dev：${via}（${size}）`;
+}
+/** 显式联网刷新（只被 `ama models refresh` 调用）：拉 api.json、按清单裁剪、写用户级覆盖。 */
 export async function refreshModelsDev(options) {
     const url = modelsDevUrl(options.env);
     const now = options.now ?? Date.now;
-    const cached = readModelsDevCache(options.dataDir);
-    const cachedIndex = () => cached !== undefined ? new ModelsDevIndex(cached.providers) : undefined;
-    const age = cached !== undefined ? now() - Date.parse(cached.fetchedAt) : Infinity;
-    if (cached !== undefined &&
-        cached.url === url &&
-        !options.force &&
-        age >= 0 &&
-        age < (options.ttlMs ?? MODELS_DEV_TTL_MS)) {
-        return {
-            status: "fresh",
-            index: cachedIndex(),
-            fetchedAt: cached.fetchedAt,
-            url,
-        };
-    }
-    const doFetch = options.fetch ?? fetch;
+    const before = loadModelsDevIndex(options.dataDir);
+    const fail = (reason) => ({
+        status: "failed",
+        url,
+        index: before,
+        warning: `models.dev 刷新失败（${reason}），沿用现有数据`,
+    });
+    const list = snapshotList();
+    const unknown = (options.providers ?? []).filter((p) => !list.providers.includes(p));
+    if (unknown.length > 0)
+        return fail(`不在收录清单里：${unknown.join(", ")}；可选 ${list.providers.join(", ")}`);
+    let fresh;
     try {
-        const headers = { accept: "application/json" };
-        if (cached?.etag !== undefined && cached.url === url)
-            headers["if-none-match"] = cached.etag;
-        const response = await doFetch(url, {
-            headers,
+        const response = await (options.fetch ?? fetch)(url, {
+            headers: { accept: "application/json" },
             signal: AbortSignal.timeout(options.timeoutMs ?? MODELS_DEV_TIMEOUT_MS),
         });
-        const fetchedAt = new Date(now()).toISOString();
-        if (response.status === 304 && cached !== undefined) {
-            writeModelsDevCache(options.dataDir, { ...cached, fetchedAt });
-            return { status: "not-modified", index: cachedIndex(), fetchedAt, url };
-        }
         if (!response.ok)
             throw new Error(`HTTP ${response.status}`);
-        const providers = trimModelsDev(await response.json());
-        const etag = response.headers.get("etag") ?? undefined;
-        writeModelsDevCache(options.dataDir, {
-            version: 1,
-            url,
-            fetchedAt,
-            ...(etag !== undefined ? { etag } : {}),
-            providers,
-        });
-        return { status: "updated", index: new ModelsDevIndex(providers), fetchedAt, url };
+        fresh = buildSnapshot(await response.json(), list, options.providers);
     }
     catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
-        if (cached !== undefined) {
-            return {
-                status: "stale",
-                index: cachedIndex(),
-                fetchedAt: cached.fetchedAt,
-                url,
-                warning: `models.dev 拉取失败（${reason}），沿用 ${cached.fetchedAt} 的缓存`,
-            };
-        }
-        return {
-            status: "unavailable",
-            url,
-            warning: `models.dev 拉取失败（${reason}），没有缓存可用`,
-        };
+        return fail(error instanceof Error ? error.message : String(error));
     }
+    const fetchedAt = new Date(now()).toISOString();
+    const previous = readModelsDevCache(options.dataDir);
+    const kept = previous !== undefined && overrideApplies(previous) ? previous.providers : {};
+    writeModelsDevCache(options.dataDir, {
+        version: 2,
+        url,
+        fetchedAt,
+        providers: { ...kept, ...fresh },
+    });
+    const diff = diffSnapshots(before.data, fresh);
+    const changed = diff.added.length + diff.removed.length + diff.changed.length > 0;
+    return {
+        status: changed ? "updated" : "unchanged",
+        url,
+        fetchedAt,
+        diff,
+        index: loadModelsDevIndex(options.dataDir),
+    };
 }
-/** 一行状态说明（命令输出用）。 */
-export function describeRefresh(result) {
-    const size = result.index
-        ? `${result.index.providerCount} 家供应商、${result.index.modelCount} 个模型`
-        : "无数据";
+/** 刷新结果的说明（命令输出用）：一行状态 + 新增 / 删除 / 变化清单。 */
+export function describeRefresh(result, limit = 20) {
+    const size = `${result.index.providerCount} 家供应商、${result.index.modelCount} 个模型`;
     const text = {
-        fresh: "缓存未过期",
-        updated: "已更新",
-        "not-modified": "未变化（304）",
-        stale: "拉取失败，用旧缓存",
-        unavailable: "不可用",
+        updated: "已刷新",
+        unchanged: "已刷新，无变化",
+        failed: "刷新失败",
     };
-    return `models.dev：${text[result.status]}（${size}${result.fetchedAt ? `，${result.fetchedAt}` : ""}）`;
+    const lines = [
+        `models.dev：${text[result.status]}（${size}${result.fetchedAt ? `，${result.fetchedAt}` : ""}）`,
+    ];
+    const section = (title, items) => {
+        if (items.length === 0)
+            return;
+        lines.push(`${title}（${items.length}）：`);
+        for (const item of items.slice(0, limit))
+            lines.push(`  ${item}`);
+        if (items.length > limit)
+            lines.push(`  …另 ${items.length - limit} 条`);
+    };
+    if (result.diff !== undefined) {
+        section("新增", result.diff.added);
+        section("上游删除（快照里的条目保留）", result.diff.removed);
+        section("变化", result.diff.changed);
+    }
+    return lines.join("\n");
 }

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

@@ -0,0 +1,7 @@
+/**
+ * 由 scripts/update-models-dev.mjs 生成，勿手改（docs/providers.md「模型元数据」）。
+ *
+ * 数据来自 models.dev（https://models.dev/api.json，github.com/anomalyco/models.dev），MIT 许可：
+ * Copyright (c) 2025 models.dev。完整声明见 THIRD_PARTY_NOTICES.md。
+ */
+export declare const MODELS_DEV_SOURCES: Readonly<Record<string, string>>;