@armadra/agent 0.2.1 → 0.3.0

package/dist/ai/providers/registry.js

@@ -14,6 +14,13 @@
  * 的；仍不唯一 → 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 { ApiRegistry, createDefaultApiRegistry } from "../apis/api.js";
 import { fakeProviderData } from "../fake/fake-provider.js";
@@ -21,26 +28,42 @@ import { mergeHeaders } from "../http.js";
 import { ApiKeyResolver } from "./auth.js";
 import { BUILTIN_PROVIDERS, fallbackEnvKey, isRelayedBaseUrl } from "./builtin.js";
 import { applyModelOverride, loadBuiltinCatalog, toModel, withCustomDefaults } from "./catalog.js";
-/** 物化：模型补齐供应商级字段（不可变：返回新对象）。 */
-export function materializeModel(model, provider) {
+import { channelKeyId, modelChannels, parseChannels, splitChannelRef } from "./channels.js";
+import { catalogMetadata, enrichEntry, lazyIndex, } from "./enrich.js";
+/**
+ * 物化：模型补齐供应商级字段（不可变：返回新对象）。给了 `channel` 时协议与地址取渠道的（模型级
+ * `explicit` 覆盖优先），headers / compat 按 供应商 ← 渠道 ← 模型 合并，并记下渠道名。
+ */
+export function materializeModel(model, provider, channel, explicit) {
     const out = {
         ...model,
         provider: provider.id,
         baseUrl: model.baseUrl ?? provider.baseUrl,
     };
-    if (provider.headers || model.headers)
-        out.headers = mergeHeaders(provider.headers, model.headers);
-    if (provider.compat || model.compat)
-        out.compat = { ...provider.compat, ...model.compat };
-    if (provider.authHeader !== undefined)
-        out.authHeader = model.authHeader ?? provider.authHeader;
+    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;
 }
 function configKeysOf(config) {
     const keys = {};
-    for (const [id, provider] of Object.entries(config?.providers ?? {}))
+    for (const [id, provider] of Object.entries(config?.providers ?? {})) {
         keys[id] = provider.apiKey;
+        for (const [name, channel] of Object.entries(provider.channels ?? {})) {
+            if (channel?.apiKey !== undefined)
+                keys[channelKeyId(id, name)] = channel.apiKey;
+        }
+    }
     return keys;
 }
 export class ProviderRegistry {
@@ -51,11 +74,17 @@ export class ProviderRegistry {
     envBaseUrls = new Map();
     /** baseUrl 指向非官方主机的内置供应商：接受目录外的 model id。 */
     relayed = new Set();
+    /** `provider/model` → 物化前的模型（多渠道供应商切换渠道时重新物化）。 */
+    raw = new Map();
+    /** `provider/model` → 元数据来源与 models.dev 匹配。 */
+    metadata = new Map();
+    modelsDev;
     apis;
     keys;
     onWarning;
     constructor(options = {}) {
         this.onWarning = options.onWarning;
+        this.modelsDev = lazyIndex(options.modelsDev);
         this.apis = options.apis ?? createDefaultApiRegistry();
         this.keys = new ApiKeyResolver({
             ...options.keys,
@@ -68,7 +97,11 @@ export class ProviderRegistry {
             const models = (catalog.get(base.id) ?? []).map((entry) => {
                 const api = entry.api ?? base.api;
                 this.sources.set(`${base.id}/${entry.id}`, "builtin");
-                return toModel(entry, base.id, api);
+                const model = toModel(entry, base.id, api);
+                this.metadata.set(`${base.id}/${entry.id}`, catalogMetadata(model));
+                if (entry.api !== undefined)
+                    this.raw.set(`${base.id}/${entry.id}`, { model, explicit: { api } });
+                return model;
             });
             const fromEnv = baseUrlEnv !== undefined ? env[baseUrlEnv]?.trim() : undefined;
             if (baseUrlEnv !== undefined && fromEnv)
@@ -102,24 +135,43 @@ export class ProviderRegistry {
             this.providers.set(fake.id, fake);
         }
         for (const provider of this.providers.values()) {
-            provider.models = provider.models.map((model) => materializeModel(model, provider));
+            provider.models = provider.models.map((model) => this.materialize(provider, model));
         }
     }
     warn(message) {
         this.warnings.push(message);
         this.onWarning?.(message);
     }
+    /** 物化并记下原始模型；多渠道供应商用模型的首选渠道。 */
+    materialize(provider, model, channelName) {
+        const key = `${provider.id}/${model.id}`;
+        const raw = this.raw.get(key) ?? { model, explicit: {} };
+        if (!this.raw.has(key)) {
+            if (model.baseUrl !== undefined)
+                raw.explicit.baseUrl = model.baseUrl;
+            this.raw.set(key, raw);
+        }
+        if (provider.channels === undefined || provider.channels.length === 0)
+            return materializeModel(raw.model, provider);
+        const name = channelName ?? raw.model.channels?.[0] ?? provider.defaultChannel;
+        const channel = provider.channels.find((c) => c.name === name) ?? provider.channels[0];
+        return materializeModel(raw.model, provider, channel, raw.explicit);
+    }
     applyConfig(id, config) {
         const existing = this.providers.get(id);
-        if (!existing && !config.baseUrl) {
+        const parsed = config.channels !== undefined ? parseChannels(id, config) : undefined;
+        for (const warning of parsed?.warnings ?? [])
+            this.warn(warning);
+        const first = parsed?.channels.find((c) => c.name === parsed.defaultChannel);
+        if (!existing && !config.baseUrl && first === undefined) {
             this.warn(`provider "${id}" in config.json has no baseUrl; ignored`);
             return;
         }
         const provider = existing ?? {
             id,
             name: config.name ?? id,
-            api: config.api ?? "openai-completions",
-            baseUrl: config.baseUrl ?? "",
+            api: config.api ?? first?.api ?? "openai-completions",
+            baseUrl: config.baseUrl ?? first?.baseUrl ?? "",
             envKeys: [fallbackEnvKey(id)],
             models: [],
             requiresApiKey: true,
@@ -133,6 +185,14 @@ export class ProviderRegistry {
             provider.baseUrl = config.baseUrl;
             this.envBaseUrls.delete(id);
         }
+        if (parsed !== undefined && first !== undefined) {
+            // 有渠道时供应商级 api / baseUrl 取首选渠道的（discover 等单地址的用法看它）。
+            provider.channels = parsed.channels;
+            provider.defaultChannel = first.name;
+            provider.api = first.api;
+            provider.baseUrl = first.baseUrl;
+            this.envBaseUrls.delete(id);
+        }
         if (config.envKeys !== undefined) {
             provider.envKeys = [
                 ...config.envKeys,
@@ -147,15 +207,30 @@ export class ProviderRegistry {
             provider.compat = { ...provider.compat, ...config.compat };
         if (config.requiresApiKey !== undefined)
             provider.requiresApiKey = config.requiresApiKey;
+        const channelsOf = (wanted, modelId) => modelChannels(wanted, provider.channels ?? [], provider.defaultChannel ?? "", (name) => this.warn(`model "${id}/${modelId}" channel "${name}" not found; ignored`));
         for (const entry of config.models ?? []) {
-            // 模型级 api（第三波 §2.3）：同一中转下不同模型走不同协议；缺省沿用供应商的。
-            const model = withCustomDefaults(entry, id, entry.api ?? provider.api);
+            // 模型级 api（第三波 §2.3）：同一中转下不同模型走不同协议；缺省沿用供应商（或渠道）的。
+            const { entry: filled, metadata } = enrichEntry(entry, this.modelsDev);
+            if (typeof entry.modelsDev === "string" && metadata.looked && metadata.match === undefined)
+                this.warn(`modelsDev "${entry.modelsDev}" for "${id}/${entry.id}" not found`);
+            const model = withCustomDefaults(filled, id, entry.api ?? provider.api);
+            if (provider.channels !== undefined)
+                model.channels = channelsOf(entry.channels, entry.id);
             const index = provider.models.findIndex((m) => m.id === entry.id);
             if (index >= 0)
                 provider.models[index] = model;
             else
                 provider.models.push(model);
-            this.sources.set(`${id}/${entry.id}`, "config");
+            const key = `${id}/${entry.id}`;
+            this.raw.set(key, {
+                model,
+                explicit: {
+                    ...(entry.api !== undefined ? { api: entry.api } : {}),
+                    ...(entry.baseUrl !== undefined ? { baseUrl: entry.baseUrl } : {}),
+                },
+            });
+            this.sources.set(key, "config");
+            this.metadata.set(key, metadata);
         }
         for (const override of config.modelOverrides ?? []) {
             const index = provider.models.findIndex((m) => m.id === override.id);
@@ -164,8 +239,33 @@ export class ProviderRegistry {
                 this.warn(`modelOverrides: "${id}/${override.id}" not found; ignored`);
                 continue;
             }
-            const next = applyModelOverride(current, override);
-            provider.models[index] = override.api !== undefined ? { ...next, api: override.api } : next;
+            const { channels, modelsDev: _md, ...fields } = override;
+            let next = applyModelOverride(current, fields);
+            if (override.api !== undefined)
+                next = { ...next, api: override.api };
+            if (channels !== undefined && provider.channels !== undefined)
+                next.channels = channelsOf(channels, override.id);
+            provider.models[index] = next;
+            const key = `${id}/${override.id}`;
+            const raw = this.raw.get(key);
+            this.raw.set(key, {
+                model: next,
+                explicit: {
+                    ...raw?.explicit,
+                    ...(override.api !== undefined ? { api: override.api } : {}),
+                    ...(override.baseUrl !== undefined ? { baseUrl: override.baseUrl } : {}),
+                },
+            });
+            const meta = this.metadata.get(key);
+            if (meta !== undefined)
+                for (const field of Object.keys(meta.sources))
+                    if (fields[field] !== undefined)
+                        meta.sources[field] = "config";
+        }
+        if (provider.channels !== undefined) {
+            // 目录模型（给内置供应商加了渠道时）挂到首选渠道。
+            for (const model of provider.models)
+                model.channels ??= [provider.defaultChannel ?? ""];
         }
         this.providers.set(id, provider);
     }
@@ -177,6 +277,10 @@ export class ProviderRegistry {
     isRelayed(providerId) {
         return this.relayed.has(providerId);
     }
+    /** 模型元数据的来源与 models.dev 匹配（`ama models list` / `config show` / providers 表格）。 */
+    modelMetadata(providerId, modelId) {
+        return this.metadata.get(`${providerId}/${modelId}`);
+    }
     list() {
         return [...this.providers.values()];
     }
@@ -201,7 +305,8 @@ export class ProviderRegistry {
         if (!provider)
             return;
         for (const raw of models) {
-            const model = materializeModel({ ...raw, provider: providerId }, provider);
+            this.raw.delete(`${providerId}/${raw.id}`);
+            const model = this.materialize(provider, { ...raw, provider: providerId });
             const index = provider.models.findIndex((m) => m.id === model.id);
             if (index >= 0)
                 provider.models[index] = model;
@@ -210,11 +315,47 @@ export class ProviderRegistry {
             this.sources.set(`${providerId}/${model.id}`, source);
         }
     }
-    synthesize(provider, modelId) {
-        return materializeModel(withCustomDefaults({ id: modelId }, provider.id, provider.api), provider);
+    synthesize(provider, modelId, channel) {
+        const key = `${provider.id}/${modelId}`;
+        const { entry, metadata } = enrichEntry({ id: modelId }, this.modelsDev);
+        if (!this.metadata.has(key))
+            this.metadata.set(key, metadata);
+        const model = withCustomDefaults(entry, provider.id, provider.api);
+        if (provider.channels !== undefined)
+            model.channels = [provider.defaultChannel ?? ""];
+        const channelData = provider.channels?.find((c) => c.name === (channel ?? model.channels?.[0]));
+        return materializeModel(model, provider, channelData);
+    }
+    /** 按渠道取模型：渠道不在模型的 channels 里 → 列出可用渠道。 */
+    withChannel(provider, model, channel) {
+        const available = model.channels ?? [];
+        if (!available.includes(channel)) {
+            return {
+                ok: false,
+                reason: "not_found",
+                candidates: available.map((c) => `${provider.id}/${model.id}@${c}`),
+            };
+        }
+        if (channel === model.channel)
+            return { ok: true, model, provider };
+        return { ok: true, model: this.materialize(provider, model, channel), provider };
     }
     findModel(ref) {
         const trimmed = ref.trim();
+        const direct = this.findPlain(trimmed);
+        if (direct.ok)
+            return direct;
+        const split = splitChannelRef(trimmed);
+        if (split === undefined)
+            return direct;
+        const base = this.findPlain(split.base, split.channel);
+        if (!base.ok)
+            return base.reason === "ambiguous" ? base : direct;
+        if (!base.provider.channels?.some((c) => c.name === split.channel))
+            return direct;
+        return this.withChannel(base.provider, base.model, split.channel);
+    }
+    findPlain(trimmed, channel) {
         const slash = trimmed.indexOf("/");
         if (slash > 0) {
             const provider = this.providers.get(trimmed.slice(0, slash));
@@ -224,7 +365,10 @@ export class ProviderRegistry {
                 if (model)
                     return { ok: true, model, provider };
                 if ((provider.models.length === 0 || this.relayed.has(provider.id)) && id.length > 0) {
-                    return { ok: true, model: this.synthesize(provider, id), provider };
+                    const synthesized = this.synthesize(provider, id);
+                    if (channel !== undefined && provider.channels?.some((c) => c.name === channel))
+                        synthesized.channels = [...new Set([...(synthesized.channels ?? []), channel])];
+                    return { ok: true, model: synthesized, provider };
                 }
                 return { ok: false, reason: "not_found", candidates: this.similar(id, provider.id) };
             }
@@ -261,10 +405,19 @@ export class ProviderRegistry {
         const provider = this.providers.get(providerId);
         return provider ? this.keys.hasConfiguredKey(provider) : false;
     }
-    async resolveApiKey(providerId) {
+    async resolveApiKey(providerId, channel) {
         const provider = this.providers.get(providerId);
         if (!provider)
             return { apiKey: undefined, source: "none" };
+        if (channel !== undefined && provider.channels?.some((c) => c.name === channel)) {
+            const own = await this.keys.resolve({
+                id: channelKeyId(provider.id, channel),
+                envKeys: [],
+                requiresApiKey: provider.requiresApiKey,
+            });
+            if (own.apiKey !== undefined)
+                return own;
+        }
         return this.keys.resolve(provider);
     }
     getApi(api) {

package/dist/ai/types.d.ts

@@ -32,6 +32,8 @@ export type RequestPurpose = "turn" | "summary" | "warm" | "probe";
 export interface ModelRef {
     provider: string;
     id: string;
+    /** 所选渠道（多渠道供应商；单渠道 / 隐式渠道不填）。 */
+    channel?: string;
 }
 export type JsonSchemaType = "object" | "string" | "number" | "integer" | "boolean" | "array";
 export type JsonPrimitive = string | number | boolean | null;
@@ -295,6 +297,19 @@ export interface Model {
      * 填入。缺省视为 true：流函数缺 key 时同步抛 `AmaError{code:"no_api_key"}`。
      */
     requiresApiKey?: boolean;
+    /** 所选渠道名（registry 物化时填入；隐式 `default` 渠道不填）。 */
+    channel?: string;
+    /** 该模型挂载的全部渠道，首个为首选（多渠道供应商才有）。 */
+    channels?: string[];
+}
+/** 物化后的渠道（docs/providers.md「渠道」）；key 不在这里，经 `resolveApiKey(provider, channel)` 取。 */
+export interface ProviderChannel {
+    name: string;
+    api: Api;
+    baseUrl: string;
+    authHeader?: AuthHeader;
+    headers?: Record<string, string>;
+    compat?: ProviderCompat;
 }
 export interface ProviderData {
     id: string;
@@ -310,6 +325,10 @@ export interface ProviderData {
     /** 本地服务 false：无 key 也能用。 */
     requiresApiKey: boolean;
     builtin: boolean;
+    /** 显式配置的渠道（没有 `channels` 的供应商不填，按单渠道处理）。 */
+    channels?: ProviderChannel[];
+    /** 首选渠道名（有 `channels` 时）。 */
+    defaultChannel?: string;
 }
 /** `catalog/*.json` 文件形状（§3.4）。 */
 export interface ModelCatalogFile {
@@ -423,6 +442,7 @@ export interface ProviderRegistryApi {
     get(providerId: string): ProviderData | undefined;
     /** 解析 `provider/model-id` 或无斜杠的模型 id（§3.4）。 */
     findModel(ref: string): ModelLookup;
-    resolveApiKey(providerId: string): Promise<ApiKeyResolution>;
+    /** `channel`：渠道自己配了 key 时用渠道的，否则用供应商的。 */
+    resolveApiKey(providerId: string, channel?: string): Promise<ApiKeyResolution>;
     getApi(api: Api): ApiImplementation | undefined;
 }