@armadra/agent 0.0.0-stage → 0.3.0

package/dist/ai/providers/catalog.js

@@ -0,0 +1,166 @@
+/**
+ * 模型目录（设计 §3.4）：`catalog/*.json` 是数据源（人工校对、PR 更新），随包携带。
+ *
+ * 运行时零依赖、bundle 为单文件，不能在运行时读 JSON 文件；`catalog-data.ts` 是由 JSON 生成
+ * 的字符串表（`UPDATE_CATALOG=1 pnpm vitest run src/ai/providers/catalog.test.ts` 重新生成，
+ * 测试守住两者一致）。本模块解析并校验它，另提供覆盖合并。
+ *
+ * 必填字段：id、name、maxTokens、reasoning；contextWindow 与 cost「宁缺不猜」——数据源里
+ * 不确定的就不写（缺 contextWindow → 关自动压缩并警告；缺 cost → 显示 `$?`）。`promptCache`
+ * （TTL 秒数与最小可缓存长度）同样只写有公开依据的值（第三波 §1.4），留空 = 不承诺。
+ */
+import { AmaError } from "../../errors.js";
+import { CATALOG_SOURCES } from "./catalog-data.js";
+import { THINKING_LEVELS } from "../thinking.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonNegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+/** 校验一个模型条目，返回问题列表（空 = 合法）。 */
+export function checkCatalogModel(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")
+        problems.push(`${path}.name`);
+    if (typeof value["reasoning"] !== "boolean")
+        problems.push(`${path}.reasoning`);
+    if (!isNonNegative(value["maxTokens"]) || value["maxTokens"] === 0) {
+        problems.push(`${path}.maxTokens`);
+    }
+    if (value["contextWindow"] !== undefined && !isNonNegative(value["contextWindow"])) {
+        problems.push(`${path}.contextWindow`);
+    }
+    const input = value["input"];
+    if (input !== undefined &&
+        (!Array.isArray(input) || !input.every((i) => i === "text" || i === "image"))) {
+        problems.push(`${path}.input`);
+    }
+    const cost = value["cost"];
+    if (cost !== undefined) {
+        if (!isRecord(cost))
+            problems.push(`${path}.cost`);
+        else {
+            for (const key of ["input", "output", "cacheRead", "cacheWrite"]) {
+                if (!isNonNegative(cost[key]))
+                    problems.push(`${path}.cost.${key}`);
+            }
+            if (cost["tiers"] !== undefined && !Array.isArray(cost["tiers"])) {
+                problems.push(`${path}.cost.tiers`);
+            }
+        }
+    }
+    const promptCache = value["promptCache"];
+    if (promptCache !== undefined) {
+        if (!isRecord(promptCache))
+            problems.push(`${path}.promptCache`);
+        else {
+            for (const [key, seconds] of Object.entries(promptCache)) {
+                const known = key === "short" || key === "long" || key === "minTokens";
+                if (!known || !Number.isInteger(seconds) || seconds <= 0) {
+                    problems.push(`${path}.promptCache.${key}`);
+                }
+            }
+            const { short, long } = promptCache;
+            if (typeof short === "number" && typeof long === "number" && long < short) {
+                problems.push(`${path}.promptCache.long < short`);
+            }
+        }
+    }
+    const map = value["thinkingLevelMap"];
+    if (map !== undefined) {
+        if (!isRecord(map))
+            problems.push(`${path}.thinkingLevelMap`);
+        else {
+            for (const [level, mapped] of Object.entries(map)) {
+                const okLevel = THINKING_LEVELS.includes(level);
+                const okValue = mapped === null || typeof mapped === "string" || typeof mapped === "number";
+                if (!okLevel || !okValue)
+                    problems.push(`${path}.thinkingLevelMap.${level}`);
+            }
+        }
+    }
+    return problems;
+}
+export function parseCatalogFile(value, source) {
+    const problems = [];
+    if (!isRecord(value))
+        problems.push("$: must be an object");
+    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(", ")}`);
+    }
+    return value;
+}
+let cache;
+/** 内置目录：供应商 id → 模型条目（深拷贝，调用方可随意修改）。 */
+export function loadBuiltinCatalog() {
+    if (!cache) {
+        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 copy = new Map();
+    for (const [provider, models] of cache)
+        copy.set(provider, structuredClone(models));
+    return copy;
+}
+/** 目录条目 → Model（补 provider / api 与缺省 input）。 */
+export function toModel(entry, provider, api) {
+    return { ...structuredClone(entry), input: entry.input ?? ["text"], provider, api };
+}
+/** 自定义模型缺省：maxTokens 8192、reasoning false、input ["text"]、name = id；不猜 contextWindow。 */
+export function withCustomDefaults(entry, provider, api) {
+    return {
+        ...structuredClone(entry),
+        name: entry.name ?? entry.id,
+        input: entry.input ?? ["text"],
+        reasoning: entry.reasoning ?? false,
+        maxTokens: entry.maxTokens ?? 8192,
+        provider,
+        api,
+    };
+}
+/** 只改元数据：浅合并，`compat` / `cost` / `thinkingLevelMap` / `headers` 再合并一层。 */
+export function applyModelOverride(model, override) {
+    const { id: _id, ...rest } = override;
+    const next = { ...model, ...structuredClone(rest) };
+    if (override.compat && model.compat)
+        next.compat = { ...model.compat, ...override.compat };
+    if (override.cost && model.cost)
+        next.cost = { ...model.cost, ...override.cost };
+    if (override.headers && model.headers)
+        next.headers = { ...model.headers, ...override.headers };
+    if (override.thinkingLevelMap && model.thinkingLevelMap) {
+        next.thinkingLevelMap = {
+            ...model.thinkingLevelMap,
+            ...override.thinkingLevelMap,
+        };
+    }
+    return next;
+}

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

@@ -0,0 +1,51 @@
+/**
+ * 渠道（docs/providers.md「渠道」）：一个供应商下的多种接口（协议 + 地址 + 可选 key / headers / compat）。
+ *
+ * - 没有 `channels` 的供应商按单渠道处理：供应商级 `api` + `baseUrl` 就是隐式的 `default` 渠道，
+ *   模型上不出现 `channel` / `channels` 字段，行为与引入渠道之前完全相同。
+ * - 有 `channels` 时：模型 `channels[0]` 是首选，缺省 `defaultChannel`；模型级 `api` / `baseUrl`
+ *   覆盖在所选渠道之上（等价于匿名渠道）。
+ * - 模型引用 `provider/model@channel`：`@` 之后是该供应商的渠道名才当渠道，否则整串仍是 model id。
+ * - 渠道自己的 key 以 `<provider>@<channel>` 为键进 key 解析（config 的 `channels.<c>.apiKey` 或
+ *   auth.json 的同名条目），没有时用供应商的 key。
+ */
+import type { ProviderConfig } from "../../config/types.js";
+import type { Api, ProviderChannel } 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): {
+    channels: ProviderChannel[];
+    defaultChannel: string | undefined;
+    warnings: string[];
+};
+/** 模型的渠道表：去掉不存在的；空 → [defaultChannel]。 */
+export declare function modelChannels(wanted: readonly string[] | undefined, known: readonly ProviderChannel[], defaultChannel: string, onUnknown: (name: string) => void): string[];
+/**
+ * 拆 `provider/model@channel` 末尾的渠道：只看最后一个 `/` 之后的部分；渠道名不合法时返回 undefined。
+ * 是否真的是渠道由调用方结合供应商的渠道表判断。
+ */
+export declare function splitChannelRef(ref: string): {
+    base: string;
+    channel: string;
+} | undefined;
+/** `provider/model` 或 `provider/model@channel`（channel 为空时不带后缀）。 */
+export declare function formatModelRef(ref: {
+    provider: string;
+    id: string;
+    channel?: string;
+}): string;
+/** Model / ModelRef → ModelRef（带上渠道，没有渠道时不出现该键）。 */
+export declare function modelRefOf(model: {
+    provider: string;
+    id: string;
+    channel?: string | undefined;
+}): {
+    provider: string;
+    id: string;
+    channel?: string;
+};
+/** 协议的短名（表格用）。 */
+export declare function apiShortName(api: Api): string;

package/dist/ai/providers/channels.js

@@ -0,0 +1,96 @@
+/**
+ * 渠道（docs/providers.md「渠道」）：一个供应商下的多种接口（协议 + 地址 + 可选 key / headers / compat）。
+ *
+ * - 没有 `channels` 的供应商按单渠道处理：供应商级 `api` + `baseUrl` 就是隐式的 `default` 渠道，
+ *   模型上不出现 `channel` / `channels` 字段，行为与引入渠道之前完全相同。
+ * - 有 `channels` 时：模型 `channels[0]` 是首选，缺省 `defaultChannel`；模型级 `api` / `baseUrl`
+ *   覆盖在所选渠道之上（等价于匿名渠道）。
+ * - 模型引用 `provider/model@channel`：`@` 之后是该供应商的渠道名才当渠道，否则整串仍是 model id。
+ * - 渠道自己的 key 以 `<provider>@<channel>` 为键进 key 解析（config 的 `channels.<c>.apiKey` 或
+ *   auth.json 的同名条目），没有时用供应商的 key。
+ */
+import { CHANNEL_NAME_PATTERN } from "../../config/types.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) {
+    const warnings = [];
+    const channels = [];
+    for (const [name, raw] of Object.entries(config.channels ?? {})) {
+        const c = raw;
+        if (!CHANNEL_NAME_PATTERN.test(name) || !c || !c.api || !c.baseUrl) {
+            warnings.push(`provider "${providerId}" channel "${name}" is invalid; ignored`);
+            continue;
+        }
+        const channel = { name, api: c.api, 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);
+    }
+    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 };
+}
+/** 模型的渠道表：去掉不存在的；空 → [defaultChannel]。 */
+export function modelChannels(wanted, known, defaultChannel, onUnknown) {
+    const names = new Set(known.map((c) => c.name));
+    const out = [];
+    for (const name of wanted ?? []) {
+        if (!names.has(name))
+            onUnknown(name);
+        else if (!out.includes(name))
+            out.push(name);
+    }
+    return out.length > 0 ? out : [defaultChannel];
+}
+/**
+ * 拆 `provider/model@channel` 末尾的渠道：只看最后一个 `/` 之后的部分；渠道名不合法时返回 undefined。
+ * 是否真的是渠道由调用方结合供应商的渠道表判断。
+ */
+export function splitChannelRef(ref) {
+    const at = ref.lastIndexOf("@");
+    if (at <= 0 || at < ref.lastIndexOf("/"))
+        return undefined;
+    const channel = ref.slice(at + 1);
+    if (!CHANNEL_NAME_PATTERN.test(channel))
+        return undefined;
+    return { base: ref.slice(0, at), channel };
+}
+/** `provider/model` 或 `provider/model@channel`（channel 为空时不带后缀）。 */
+export function formatModelRef(ref) {
+    return `${ref.provider}/${ref.id}${ref.channel !== undefined ? `@${ref.channel}` : ""}`;
+}
+/** Model / ModelRef → ModelRef（带上渠道，没有渠道时不出现该键）。 */
+export function modelRefOf(model) {
+    return {
+        provider: model.provider,
+        id: model.id,
+        ...(model.channel !== undefined ? { channel: model.channel } : {}),
+    };
+}
+/** 协议的短名（表格用）。 */
+export function apiShortName(api) {
+    switch (api) {
+        case "openai-completions":
+            return "chat";
+        case "openai-responses":
+            return "responses";
+        case "anthropic-messages":
+            return "messages";
+        case "google-generative-ai":
+            return "gemini";
+        default:
+            return api;
+    }
+}

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

@@ -0,0 +1,34 @@
+/**
+ * 用 models.dev 缓存给自定义模型补元数据（docs/providers.md「模型元数据：models.dev」）。
+ *
+ * 优先级：用户配置写了的字段 > models.dev > 自定义缺省（maxTokens 8192、input ["text"]、
+ * reasoning false、不猜 contextWindow）。内置目录的模型不经过这里（目录本身就是人工校对的值）。
+ * 只读传入的索引，不联网。
+ */
+import type { ModelConfig } from "../../config/types.js";
+import type { Model } from "../types.js";
+import { type EnrichableField, type ModelsDevIndex, type ModelsDevMatch } from "./models-dev.js";
+export type FieldSource = "config" | "catalog" | "models.dev" | "default";
+export interface ModelMetadata {
+    sources: Record<EnrichableField, FieldSource>;
+    /** models.dev 匹配结果；未查（没有缓存或 `modelsDev: false`）为 undefined。 */
+    match?: ModelsDevMatch | undefined;
+    /** 是否查过 models.dev（有缓存且没关闭）。 */
+    looked: boolean;
+    /** models.dev 的 tool_call。 */
+    toolCall?: boolean;
+}
+export type ModelsDevSource = ModelsDevIndex | (() => ModelsDevIndex | undefined) | undefined;
+/** 惰性取索引：只有真的要补字段时才读缓存（启动时没有自定义模型就不读约 2 MB 的缓存）。 */
+export declare function lazyIndex(source: ModelsDevSource): () => ModelsDevIndex | undefined;
+/**
+ * 补全一个自定义模型条目（config 的 `models[]` 或合成的模型）。返回补过字段的条目（不含
+ * `modelsDev` / `channels` 这些配置专用键）与每个字段的来源。
+ */
+export declare function enrichEntry(entry: ModelConfig, index: () => ModelsDevIndex | undefined): {
+    entry: Omit<ModelConfig, "modelsDev" | "channels">;
+    metadata: ModelMetadata;
+};
+/** 内置目录模型的来源（全部 catalog；目录没写 contextWindow / cost 的为缺省）。 */
+export declare function catalogMetadata(model: Model): ModelMetadata;
+export declare function sourceText(source: FieldSource): string;

package/dist/ai/providers/enrich.js

@@ -0,0 +1,86 @@
+/**
+ * 用 models.dev 缓存给自定义模型补元数据（docs/providers.md「模型元数据：models.dev」）。
+ *
+ * 优先级：用户配置写了的字段 > models.dev > 自定义缺省（maxTokens 8192、input ["text"]、
+ * reasoning false、不猜 contextWindow）。内置目录的模型不经过这里（目录本身就是人工校对的值）。
+ * 只读传入的索引，不联网。
+ */
+import { ENRICHABLE_FIELDS, modelsDevFields, } from "./models-dev.js";
+/** 惰性取索引：只有真的要补字段时才读缓存（启动时没有自定义模型就不读约 2 MB 的缓存）。 */
+export function lazyIndex(source) {
+    if (typeof source !== "function")
+        return () => source;
+    let loaded = false;
+    let index;
+    return () => {
+        if (!loaded) {
+            loaded = true;
+            try {
+                index = source();
+            }
+            catch {
+                index = undefined;
+            }
+        }
+        return index;
+    };
+}
+function needsLookup(entry) {
+    return ENRICHABLE_FIELDS.some((field) => entry[field] === undefined);
+}
+/**
+ * 补全一个自定义模型条目（config 的 `models[]` 或合成的模型）。返回补过字段的条目（不含
+ * `modelsDev` / `channels` 这些配置专用键）与每个字段的来源。
+ */
+export function enrichEntry(entry, index) {
+    const { modelsDev, channels: _channels, ...rest } = entry;
+    const sources = {};
+    for (const field of ENRICHABLE_FIELDS) {
+        sources[field] = rest[field] !== undefined ? "config" : "default";
+    }
+    const metadata = { sources, looked: false };
+    if (modelsDev === false || (!needsLookup(rest) && modelsDev === undefined)) {
+        return { entry: rest, metadata };
+    }
+    const idx = index();
+    if (idx === undefined)
+        return { entry: rest, metadata };
+    metadata.looked = true;
+    const match = idx.match(entry.id, typeof modelsDev === "string" ? modelsDev : undefined);
+    metadata.match = match;
+    if (match === undefined)
+        return { entry: rest, metadata };
+    const fields = modelsDevFields(match.model);
+    if (fields.toolCall !== undefined)
+        metadata.toolCall = fields.toolCall;
+    const out = { ...rest };
+    for (const field of ENRICHABLE_FIELDS) {
+        if (out[field] !== undefined)
+            continue;
+        const value = fields[field];
+        if (value === undefined)
+            continue;
+        out[field] = structuredClone(value);
+        sources[field] = "models.dev";
+    }
+    if (out.name === undefined && fields.name !== undefined)
+        out.name = fields.name;
+    return { entry: out, metadata };
+}
+/** 内置目录模型的来源（全部 catalog；目录没写 contextWindow / cost 的为缺省）。 */
+export function catalogMetadata(model) {
+    const sources = {};
+    for (const field of ENRICHABLE_FIELDS) {
+        sources[field] = model[field] !== undefined ? "catalog" : "default";
+    }
+    return { sources, looked: false };
+}
+const SOURCE_TEXT = {
+    config: "config",
+    catalog: "目录",
+    "models.dev": "models.dev",
+    default: "缺省",
+};
+export function sourceText(source) {
+    return SOURCE_TEXT[source];
+}

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

@@ -0,0 +1,53 @@
+/**
+ * models.dev 缓存（docs/providers.md「模型元数据：models.dev」）。
+ *
+ * - 缓存文件 `<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` 换数据源。
+ */
+import { ModelsDevIndex, type ModelsDevData } from "./models-dev.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 interface ModelsDevCacheFile {
+    version: 1;
+    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（损坏不报错：下次拉取会覆盖）。 */
+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";
+export interface RefreshResult {
+    status: RefreshStatus;
+    index?: ModelsDevIndex;
+    fetchedAt?: string;
+    url: string;
+    warning?: string;
+}
+export interface RefreshOptions {
+    dataDir: string;
+    env?: Readonly<Record<string, string | undefined>>;
+    /** 忽略 TTL（`ama models refresh-catalog`）。 */
+    force?: boolean;
+    ttlMs?: number;
+    timeoutMs?: number;
+    now?: () => number;
+    fetch?: typeof fetch;
+}
+/** 按需拉取 models.dev 并更新缓存；失败时回落旧缓存（status `stale`）或无数据（`unavailable`）。 */
+export declare function refreshModelsDev(options: RefreshOptions): Promise<RefreshResult>;
+/** 一行状态说明（命令输出用）。 */
+export declare function describeRefresh(result: RefreshResult): string;

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

@@ -0,0 +1,147 @@
+/**
+ * models.dev 缓存（docs/providers.md「模型元数据：models.dev」）。
+ *
+ * - 缓存文件 `<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` 换数据源。
+ */
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ModelsDevIndex, trimModelsDev } from "./models-dev.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 function modelsDevCachePath(dataDir) {
+    return join(dataDir, MODELS_DEV_FILE);
+}
+export function modelsDevUrl(env = process.env) {
+    const custom = env[MODELS_DEV_URL_ENV]?.trim();
+    return custom ? custom : MODELS_DEV_URL;
+}
+/** 读缓存；不存在或损坏返回 undefined（损坏不报错：下次拉取会覆盖）。 */
+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")
+            return undefined;
+        if (typeof file.providers !== "object" || file.providers === null)
+            return undefined;
+        return file;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeModelsDevCache(dataDir, file) {
+    const path = modelsDevCachePath(dataDir);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(file));
+    renameSync(tmp, path);
+    memo = undefined;
+}
+let memo;
+/** 只读缓存构造索引（不联网）；没有缓存返回 undefined。 */
+export function loadModelsDevIndex(dataDir) {
+    const path = modelsDevCachePath(dataDir);
+    let key;
+    try {
+        const stat = statSync(path);
+        key = `${path}\0${stat.mtimeMs}\0${stat.size}`;
+    }
+    catch {
+        return undefined;
+    }
+    if (memo?.key === key)
+        return memo.index;
+    const file = readModelsDevCache(dataDir);
+    const index = file !== undefined ? new ModelsDevIndex(file.providers) : undefined;
+    memo = { key, index };
+    return index;
+}
+/** 按需拉取 models.dev 并更新缓存；失败时回落旧缓存（status `stale`）或无数据（`unavailable`）。 */
+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;
+    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,
+            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 };
+    }
+    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}），没有缓存可用`,
+        };
+    }
+}
+/** 一行状态说明（命令输出用）。 */
+export function describeRefresh(result) {
+    const size = result.index
+        ? `${result.index.providerCount} 家供应商、${result.index.modelCount} 个模型`
+        : "无数据";
+    const text = {
+        fresh: "缓存未过期",
+        updated: "已更新",
+        "not-modified": "未变化（304）",
+        stale: "拉取失败，用旧缓存",
+        unavailable: "不可用",
+    };
+    return `models.dev：${text[result.status]}（${size}${result.fetchedAt ? `，${result.fetchedAt}` : ""}）`;
+}