@armadra/agent 0.2.1 → 0.4.0

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}` : ""}）`;
+}

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

@@ -0,0 +1,99 @@
+/**
+ * models.dev 模型元数据（docs/providers.md「模型元数据：models.dev」）：裁剪、索引、匹配、映射。
+ *
+ * 数据源 `https://models.dev/api.json` 是「供应商 → 模型」两层表，同一个模型 id 会在几十家转售商下
+ * 重复出现且取值不一。`ModelsDevIndex.match()` 按文档里的顺序挑一条：显式 `provider/model` →
+ * `vendor/model` 形状的 id → 同名条目的 `canonical_model_id` 指向的原厂条目 → 原厂供应商 →
+ * 多数一致 → 归一化 id（去前缀 / `:后缀` / `-latest` / 日期）后重试 → 未匹配。
+ *
+ * 本模块只做纯计算（不读文件、不联网）；缓存与拉取在 models-dev-cache.ts。
+ */
+import type { ModelCost } from "../types.js";
+/** 用到的模型字段（name、推理、工具调用、输入模态、上下限、价格、canonical）；其余写缓存时丢掉。 */
+export interface ModelsDevModel {
+    id: string;
+    name?: string;
+    reasoning?: boolean;
+    tool_call?: boolean;
+    modalities?: {
+        input?: string[];
+    };
+    limit?: {
+        context?: number;
+        output?: number;
+    };
+    cost?: {
+        input?: number;
+        output?: number;
+        cache_read?: number;
+        cache_write?: number;
+    };
+    canonical_model_id?: string;
+}
+export interface ModelsDevProvider {
+    id: string;
+    name?: string;
+    models: Record<string, ModelsDevModel>;
+}
+export type ModelsDevData = Record<string, ModelsDevProvider>;
+/**
+ * 原厂供应商（models.dev 的供应商 id，顺序即优先级）。通义在 `alibaba`、Llama 在 `llama`、
+ * 智谱国际站在 `zai`；models.dev 没有 `qwen` / `meta` 这样的供应商 id。
+ */
+export declare const FIRST_PARTY_PROVIDERS: readonly string[];
+/** maxTokens 的上限：models.dev 给原厂上限（常与上下文相同），每次请求都会作为 max_tokens 发出。 */
+export declare const MODELS_DEV_MAX_OUTPUT = 65536;
+export type MatchKind = "explicit" | "prefix" | "canonical" | "vendor" | "consensus" | "single";
+export interface ModelsDevMatch {
+    /** 选中条目 `provider/model`。 */
+    ref: string;
+    model: ModelsDevModel;
+    kind: MatchKind;
+    /** 经归一化才匹配到时的 id（如去掉日期后缀）。 */
+    normalized?: string;
+    /** 同名条目数。 */
+    candidates: number;
+    /** 多条取值不一致时的说明。 */
+    warning?: string;
+}
+/** 映射到 ama Model 的字段（缺的不给）。 */
+export interface ModelsDevFields {
+    name?: string;
+    contextWindow?: number;
+    maxTokens?: number;
+    input?: ("text" | "image")[];
+    reasoning?: boolean;
+    cost?: ModelCost;
+    /** models.dev 的 tool_call；Model 上没有对应字段，只用于展示与写入过滤。 */
+    toolCall?: boolean;
+}
+/** 校验并裁剪 api.json：只留用到的字段；形状不对的供应商 / 模型跳过。整体不是对象抛错。 */
+export declare function trimModelsDev(raw: unknown): ModelsDevData;
+/**
+ * 依次尝试的 id（小写、去重）：原样 → 去 `vendor/` 前缀 → 去 `:free` 一类后缀 → 去 `-latest` →
+ * 去日期后缀（`-0902`、`-20250514`、`-2025-05-14`）。
+ */
+export declare function idCandidates(id: string): string[];
+export declare class ModelsDevIndex {
+    private readonly byId;
+    private readonly byRef;
+    readonly data: ModelsDevData;
+    constructor(data: ModelsDevData);
+    get providerCount(): number;
+    get modelCount(): number;
+    /** `provider/model`（不分大小写）。 */
+    get(ref: string): ModelsDevModel | undefined;
+    /**
+     * 匹配一个模型 id。`explicit` 是配置里的 `modelsDev: "provider/model"`：找得到就用，找不到返回
+     * undefined（调用方 warning），不再回落到按 id 猜。
+     */
+    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 补的 Model 字段（展示来源用）。 */
+export declare const ENRICHABLE_FIELDS: readonly ["contextWindow", "maxTokens", "input", "reasoning", "cost"];
+export type EnrichableField = (typeof ENRICHABLE_FIELDS)[number];
+/** 匹配方式的中文说明（表格与 `models list`）。 */
+export declare function matchLabel(match: ModelsDevMatch | undefined): string;