@armadra/agent 0.2.1 → 0.4.0

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

@@ -0,0 +1,315 @@
+/**
+ * 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。
+ */
+/**
+ * 原厂供应商（models.dev 的供应商 id，顺序即优先级）。通义在 `alibaba`、Llama 在 `llama`、
+ * 智谱国际站在 `zai`；models.dev 没有 `qwen` / `meta` 这样的供应商 id。
+ */
+export const FIRST_PARTY_PROVIDERS = [
+    "anthropic",
+    "openai",
+    "google",
+    "deepseek",
+    "moonshotai",
+    "moonshotai-cn",
+    "zhipuai",
+    "zai",
+    "alibaba",
+    "alibaba-cn",
+    "xai",
+    "mistral",
+    "minimax",
+    "minimax-cn",
+    "llama",
+    "cohere",
+    "xiaomi",
+    "stepfun",
+    "perplexity",
+    "ai21",
+    "upstage",
+    "inception",
+];
+/** maxTokens 的上限：models.dev 给原厂上限（常与上下文相同），每次请求都会作为 max_tokens 发出。 */
+export const MODELS_DEV_MAX_OUTPUT = 65_536;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function positive(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+function nonNegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function strings(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : undefined;
+}
+function trimModel(id, raw) {
+    const out = { id };
+    if (typeof raw["name"] === "string")
+        out.name = raw["name"];
+    for (const key of ["reasoning", "tool_call"]) {
+        if (typeof raw[key] === "boolean")
+            out[key] = raw[key];
+    }
+    if (typeof raw["canonical_model_id"] === "string")
+        out.canonical_model_id = raw["canonical_model_id"];
+    const modalities = raw["modalities"];
+    if (isRecord(modalities)) {
+        const input = strings(modalities["input"]);
+        if (input)
+            out.modalities = { input };
+    }
+    const limit = raw["limit"];
+    if (isRecord(limit)) {
+        const context = positive(limit["context"]);
+        const output = positive(limit["output"]);
+        out.limit = {
+            ...(context !== undefined ? { context } : {}),
+            ...(output !== undefined ? { output } : {}),
+        };
+    }
+    const cost = raw["cost"];
+    if (isRecord(cost)) {
+        const c = {};
+        for (const key of ["input", "output", "cache_read", "cache_write"]) {
+            const v = nonNegative(cost[key]);
+            if (v !== undefined)
+                c[key] = v;
+        }
+        out.cost = c;
+    }
+    return out;
+}
+/** 校验并裁剪 api.json：只留用到的字段；形状不对的供应商 / 模型跳过。整体不是对象抛错。 */
+export function trimModelsDev(raw) {
+    if (!isRecord(raw))
+        throw new Error("models.dev 数据不是对象");
+    const out = {};
+    for (const [providerId, provider] of Object.entries(raw)) {
+        if (!isRecord(provider) || !isRecord(provider["models"]))
+            continue;
+        const models = {};
+        for (const [modelId, model] of Object.entries(provider["models"])) {
+            if (isRecord(model))
+                models[modelId] = trimModel(modelId, model);
+        }
+        out[providerId] = {
+            id: providerId,
+            ...(typeof provider["name"] === "string" ? { name: provider["name"] } : {}),
+            models,
+        };
+    }
+    return out;
+}
+/**
+ * 依次尝试的 id（小写、去重）：原样 → 去 `vendor/` 前缀 → 去 `:free` 一类后缀 → 去 `-latest` →
+ * 去日期后缀（`-0902`、`-20250514`、`-2025-05-14`）。
+ */
+export function idCandidates(id) {
+    const out = [];
+    const add = (value) => {
+        const v = value.trim();
+        if (v !== "" && !out.includes(v))
+            out.push(v);
+    };
+    let s = id.trim().toLowerCase();
+    add(s);
+    s = s.slice(s.lastIndexOf("/") + 1);
+    add(s);
+    s = s.replace(/:[a-z0-9._-]+$/, "");
+    add(s);
+    s = s.replace(/-latest$/, "");
+    add(s);
+    s = s.replace(/-(?:\d{4}-\d{2}-\d{2}|\d{8}|\d{6}|\d{4})$/, "");
+    add(s);
+    return out;
+}
+function refOf(entry) {
+    return `${entry.provider}/${entry.id}`;
+}
+function vendorRank(provider) {
+    const i = FIRST_PARTY_PROVIDERS.indexOf(provider);
+    return i < 0 ? Number.POSITIVE_INFINITY : i;
+}
+function hasImage(model) {
+    return model.modalities?.input?.includes("image") === true;
+}
+function signature(model) {
+    return `${model.limit?.context ?? "?"}/${model.limit?.output ?? "?"}/${hasImage(model) ? "img" : "text"}`;
+}
+export class ModelsDevIndex {
+    byId = new Map();
+    byRef = new Map();
+    data;
+    constructor(data) {
+        this.data = data;
+        for (const [providerId, provider] of Object.entries(data)) {
+            for (const [modelId, model] of Object.entries(provider.models)) {
+                const entry = { provider: providerId, id: modelId, model };
+                const key = modelId.toLowerCase();
+                const list = this.byId.get(key);
+                if (list)
+                    list.push(entry);
+                else
+                    this.byId.set(key, [entry]);
+                this.byRef.set(`${providerId}/${modelId}`.toLowerCase(), entry);
+            }
+        }
+    }
+    get providerCount() {
+        return Object.keys(this.data).length;
+    }
+    get modelCount() {
+        return this.byRef.size;
+    }
+    /** `provider/model`（不分大小写）。 */
+    get(ref) {
+        return this.byRef.get(ref.toLowerCase())?.model;
+    }
+    /**
+     * 匹配一个模型 id。`explicit` 是配置里的 `modelsDev: "provider/model"`：找得到就用，找不到返回
+     * undefined（调用方 warning），不再回落到按 id 猜。
+     */
+    match(id, explicit) {
+        if (explicit !== undefined) {
+            const entry = this.byRef.get(explicit.toLowerCase());
+            return entry
+                ? { ref: refOf(entry), model: entry.model, kind: "explicit", candidates: 1 }
+                : undefined;
+        }
+        if (id.includes("/")) {
+            const entry = this.byRef.get(id.toLowerCase());
+            if (entry)
+                return { ref: refOf(entry), model: entry.model, kind: "prefix", candidates: 1 };
+        }
+        const candidates = idCandidates(id);
+        for (const [i, key] of candidates.entries()) {
+            const entries = this.byId.get(key);
+            if (!entries || entries.length === 0)
+                continue;
+            const picked = this.choose(key, entries);
+            if (i > 0 && key !== id.toLowerCase())
+                picked.normalized = key;
+            return picked;
+        }
+        return undefined;
+    }
+    choose(key, entries) {
+        const candidates = entries.length;
+        let pool = entries;
+        let owner;
+        const votes = new Map();
+        for (const e of entries) {
+            const c = e.model.canonical_model_id?.toLowerCase();
+            if (c)
+                votes.set(c, (votes.get(c) ?? 0) + 1);
+        }
+        if (votes.size > 0) {
+            const tail = (ref) => ref.slice(ref.indexOf("/") + 1);
+            const ranked = [...votes].sort((a, b) => Number(tail(b[0]) === key) - Number(tail(a[0]) === key) || b[1] - a[1]);
+            const canonical = ranked[0]?.[0] ?? "";
+            const direct = this.byRef.get(canonical);
+            if (direct)
+                return { ref: refOf(direct), model: direct.model, kind: "canonical", candidates };
+            // 原厂条目不在 models.dev 里：只在指向同一 canonical 的条目里挑，原厂只认 canonical 的厂商
+            // （否则 alibaba 转售的 kimi 会被当成「原厂」）。
+            owner = canonical.slice(0, canonical.indexOf("/"));
+            const same = entries.filter((e) => e.model.canonical_model_id?.toLowerCase() === canonical);
+            if (same.length > 0)
+                pool = same;
+        }
+        const vendor = pool
+            .filter((e) => owner !== undefined
+            ? e.provider === owner || e.provider === `${owner}-cn`
+            : vendorRank(e.provider) < Number.POSITIVE_INFINITY)
+            .sort((a, b) => vendorRank(a.provider) - vendorRank(b.provider))[0];
+        if (vendor)
+            return { ref: refOf(vendor), model: vendor.model, kind: "vendor", candidates };
+        if (pool.length === 1 && pool[0]) {
+            return { ref: refOf(pool[0]), model: pool[0].model, kind: "single", candidates };
+        }
+        const groups = new Map();
+        for (const e of pool) {
+            const sig = signature(e.model);
+            const list = groups.get(sig);
+            if (list)
+                list.push(e);
+            else
+                groups.set(sig, [e]);
+        }
+        const best = [...groups.values()].sort((a, b) => b.length - a.length)[0] ?? pool;
+        const chosen = best[0];
+        const match = {
+            ref: refOf(chosen),
+            model: chosen.model,
+            kind: "consensus",
+            candidates,
+        };
+        if (groups.size > 1) {
+            match.warning =
+                `${key}：models.dev 有 ${pool.length} 个条目、${groups.size} 种取值，` +
+                    `取多数（${best.length} 条：${signature(chosen.model)}）`;
+        }
+        return match;
+    }
+}
+/** models.dev 条目 → ama Model 字段（规则见 docs/providers.md）。 */
+export function modelsDevFields(model) {
+    const out = {};
+    if (model.name !== undefined)
+        out.name = model.name;
+    const context = positive(model.limit?.context);
+    if (context !== undefined)
+        out.contextWindow = Math.floor(context);
+    const output = positive(model.limit?.output);
+    if (output !== undefined) {
+        out.maxTokens = Math.floor(Math.min(output, MODELS_DEV_MAX_OUTPUT, context ?? output));
+    }
+    const input = model.modalities?.input;
+    if (input !== undefined)
+        out.input = input.includes("image") ? ["text", "image"] : ["text"];
+    if (model.reasoning !== undefined)
+        out.reasoning = model.reasoning;
+    if (model.tool_call !== undefined)
+        out.toolCall = model.tool_call;
+    const cost = model.cost;
+    if (cost?.input !== undefined && cost.output !== undefined) {
+        out.cost = {
+            input: cost.input,
+            output: cost.output,
+            cacheRead: cost.cache_read ?? cost.input,
+            cacheWrite: cost.cache_write ?? cost.input,
+        };
+    }
+    return out;
+}
+/** 可由 models.dev 补的 Model 字段（展示来源用）。 */
+export const ENRICHABLE_FIELDS = [
+    "contextWindow",
+    "maxTokens",
+    "input",
+    "reasoning",
+    "cost",
+];
+/** 匹配方式的中文说明（表格与 `models list`）。 */
+export function matchLabel(match) {
+    if (match === undefined)
+        return "未匹配";
+    const kind = {
+        explicit: "显式",
+        prefix: "前缀",
+        canonical: "原厂",
+        vendor: "原厂",
+        consensus: "多数",
+        single: "唯一",
+    };
+    const via = match.normalized !== undefined ? `，按 ${match.normalized}` : "";
+    return `${kind[match.kind]} ${match.ref}${via}`;
+}

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

@@ -14,11 +14,19 @@
  * 的；仍不唯一 → ambiguous 并列出候选。模型表为空的供应商（ollama、lmstudio、未列模型的
  * 自定义供应商）与 baseUrl 被改到非官方主机的内置供应商（中转站）接受任意 model id，按自定义
  * 缺省合成；后者 compat 未显式配置 `sendPromptCacheKey` 时置 false。
+ *
+ * 渠道（channels.ts）：有 `channels` 的供应商，模型按首选渠道物化；`provider/model@channel` 换渠道
+ * 重新物化（协议、地址、headers、compat 取渠道的，模型级 api / baseUrl 仍覆盖）；渠道 key 经
+ * `resolveApiKey(provider, channel)`。没有 `channels` 的供应商行为不变。
+ *
+ * models.dev（enrich.ts）：config 里缺元数据的自定义模型与合成模型，用传入的索引（只读缓存）补
+ * contextWindow / maxTokens / input / reasoning / cost，来源记在 `modelMetadata()`；内置目录不补。
  */
 import type { AmaConfig } from "../../config/types.js";
 import { ApiRegistry } from "../apis/api.js";
-import type { Api, ApiImplementation, ApiKeyResolution, Model, ModelLookup, ProviderData, ProviderRegistryApi } from "../types.js";
+import type { Api, ApiImplementation, ApiKeyResolution, Model, ModelLookup, ProviderChannel, ProviderData, ProviderRegistryApi } from "../types.js";
 import { type KeyResolverOptions } from "./auth.js";
+import { type ModelMetadata, type ModelsDevSource } from "./enrich.js";
 export type ModelSource = "builtin" | "config" | "discovered";
 export interface ProviderRegistryOptions {
     config?: AmaConfig | undefined;
@@ -29,14 +37,25 @@ export interface ProviderRegistryOptions {
     /** 注册 `fake` 供应商（缺省 true）。 */
     includeFake?: boolean | undefined;
     onWarning?: ((message: string) => void) | undefined;
+    /**
+     * models.dev 索引（或惰性加载函数，只读缓存不联网）：给 config 里缺元数据的自定义模型补
+     * contextWindow / maxTokens / input / reasoning / cost。
+     */
+    modelsDev?: ModelsDevSource;
 }
 export interface ModelEntry {
     model: Model;
     provider: ProviderData;
     source: ModelSource;
 }
-/** 物化：模型补齐供应商级字段（不可变：返回新对象）。 */
-export declare function materializeModel(model: Model, provider: ProviderData): Model;
+/**
+ * 物化：模型补齐供应商级字段（不可变：返回新对象）。给了 `channel` 时协议与地址取渠道的（模型级
+ * `explicit` 覆盖优先），headers / compat 按 供应商 ← 渠道 ← 模型 合并，并记下渠道名。
+ */
+export declare function materializeModel(model: Model, provider: ProviderData, channel?: ProviderChannel, explicit?: {
+    api?: Api | undefined;
+    baseUrl?: string | undefined;
+}): Model;
 export declare class ProviderRegistry implements ProviderRegistryApi {
     readonly warnings: string[];
     private readonly providers;
@@ -45,16 +64,25 @@ export declare class ProviderRegistry implements ProviderRegistryApi {
     private readonly envBaseUrls;
     /** baseUrl 指向非官方主机的内置供应商：接受目录外的 model id。 */
     private readonly relayed;
+    /** `provider/model` → 物化前的模型（多渠道供应商切换渠道时重新物化）。 */
+    private readonly raw;
+    /** `provider/model` → 元数据来源与 models.dev 匹配。 */
+    private readonly metadata;
+    private readonly modelsDev;
     private readonly apis;
     private readonly keys;
     private readonly onWarning;
     constructor(options?: ProviderRegistryOptions);
     private warn;
+    /** 物化并记下原始模型；多渠道供应商用模型的首选渠道。 */
+    private materialize;
     private applyConfig;
     /** baseUrl 来自哪个环境变量（未生效返回 undefined）。 */
     baseUrlEnv(providerId: string): string | undefined;
     /** 内置供应商的 baseUrl 指向非官方主机（中转站）。 */
     isRelayed(providerId: string): boolean;
+    /** 模型元数据的来源与 models.dev 匹配（`ama models list` / `config show` / providers 表格）。 */
+    modelMetadata(providerId: string, modelId: string): ModelMetadata | undefined;
     list(): readonly ProviderData[];
     get(providerId: string): ProviderData | undefined;
     listModels(): ModelEntry[];
@@ -62,10 +90,20 @@ export declare class ProviderRegistry implements ProviderRegistryApi {
     /** 追加 / 替换模型（例如本地枚举得到的 ollama 模型）。 */
     addModels(providerId: string, models: readonly Model[], source?: ModelSource): void;
     private synthesize;
+    /** 按渠道取模型：渠道不在模型的 channels 里 → channel_not_found，列出可用渠道。 */
+    private withChannel;
+    /**
+     * `provider/model`、`provider/model@渠道` 或裸模型 id。`@` 先按渠道解析（id 里本来就带 `@` 且已登记的
+     * 模型除外），中转供应商的「未登记即合成」不会把 `@渠道` 吞进模型 id。失败的 reason：供应商不存在 →
+     * provider_not_found（候选是编辑距离最近的供应商）；渠道不存在 → channel_not_found；模型不存在 →
+     * not_found（候选是最接近的模型）。
+     */
     findModel(ref: string): ModelLookup;
+    private findPlain;
+    /** 最接近的模型（包含关系优先，其次编辑距离），`provider/id` 形式。 */
     private similar;
     hasConfiguredKey(providerId: string): boolean;
-    resolveApiKey(providerId: string): Promise<ApiKeyResolution>;
+    resolveApiKey(providerId: string, channel?: string): Promise<ApiKeyResolution>;
     getApi(api: Api): ApiImplementation | undefined;
 }
 /** 注册表若是 ProviderRegistry（或同形状），报告 baseUrl 来自的环境变量；否则 undefined。 */