@armadra/agent 0.0.0-stage → 0.3.0

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;

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

@@ -0,0 +1,114 @@
+/**
+ * ProviderRegistry（设计 §3.2–§3.5）：内置供应商 + 目录 + config.json 合并、模型查找、
+ * `provider/model` 解析、key 解析、协议实现查找。实现 B0 契约 `ProviderRegistryApi`。
+ *
+ * 合并顺序：内置（builtin.ts + catalog）← config.json `providers.<id>`（字段覆盖；`headers` /
+ * `compat` 合并；`models[]` 同 id 整条替换、新 id 追加；`modelOverrides[]` 只改元数据；两者都可带
+ * 模型级 `api`，缺省沿用供应商的协议）←
+ * auth.json 条目的 `baseUrl`。内置 openai / anthropic 的 baseUrl 还可来自 `OPENAI_BASE_URL` /
+ * `ANTHROPIC_BASE_URL`（第三波 §2.3，优先级最低，`baseUrlEnv(id)` 报告是否生效）。之后「物化」每个模型：补 baseUrl / headers / compat /
+ * authHeader / requiresApiKey，让协议实现只看 Model 就能发请求。
+ *
+ * 模型引用：`provider/model-id`（model id 自身可含斜杠，如 `openrouter/anthropic/claude-…`）；
+ * 前缀不是供应商 id 时整串当 model id。无供应商前缀时全局唯一匹配；多家同名时只留已配置 key
+ * 的；仍不唯一 → 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, 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;
+    /** 缺省 createDefaultApiRegistry()。 */
+    apis?: ApiRegistry | undefined;
+    /** key 发现选项；`configKeys` 缺省取自 config.providers.*.apiKey。 */
+    keys?: KeyResolverOptions | undefined;
+    /** 注册 `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;
+}
+/**
+ * 物化：模型补齐供应商级字段（不可变：返回新对象）。给了 `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;
+    private readonly sources;
+    /** baseUrl 来自环境变量的供应商 → 变量名（被 config / auth.json 覆盖后删除）。 */
+    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[];
+    modelSource(providerId: string, modelId: string): ModelSource;
+    /** 追加 / 替换模型（例如本地枚举得到的 ollama 模型）。 */
+    addModels(providerId: string, models: readonly Model[], source?: ModelSource): void;
+    private synthesize;
+    /** 按渠道取模型：渠道不在模型的 channels 里 → 列出可用渠道。 */
+    private withChannel;
+    findModel(ref: string): ModelLookup;
+    private findPlain;
+    private similar;
+    hasConfiguredKey(providerId: string): boolean;
+    resolveApiKey(providerId: string, channel?: string): Promise<ApiKeyResolution>;
+    getApi(api: Api): ApiImplementation | undefined;
+}
+/** 注册表若是 ProviderRegistry（或同形状），报告 baseUrl 来自的环境变量；否则 undefined。 */
+export declare function baseUrlEnvOf(registry: ProviderRegistryApi, providerId: string): string | undefined;
+/**
+ * 模型枚举：本地服务（`ama models list --provider ollama|lmstudio`）与 `ama models discover`
+ * （第三波 §2.3）共用。ollama 走 `/api/tags`，其它走 OpenAI 兼容的 `GET {baseUrl}/models`；
+ * `url` / `headers` 由调用方给出时原样使用（远端中转要带鉴权头）。失败抛错由调用方展示。
+ */
+export declare function discoverLocalModels(provider: ProviderData, options?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    url?: string;
+    headers?: Record<string, string>;
+}): Promise<Model[]>;