@armadra/agent 0.4.0 → 0.5.0

package/dist/ai/providers/registry.js

@@ -19,8 +19,14 @@
  * 重新物化（协议、地址、headers、compat 取渠道的，模型级 api / baseUrl 仍覆盖）；渠道 key 经
  * `resolveApiKey(provider, channel)`。没有 `channels` 的供应商行为不变。
  *
+ * 内置渠道（[W5-M2]，builtin.ts）：用户 `channels` 同名字段级覆盖、新名追加，`defaultChannel` 用户优先
+ * （也可只写 `defaultChannel`，或只写 `api` 选同协议的内置渠道）；目录模型缺省挂全部渠道、缺省渠道在前。
+ * 用户（config / auth.json / `*_BASE_URL`）改了供应商级 baseUrl 而没写自己的 `channels` 时，内置渠道作废，
+ * 按单渠道回落（`api` 取用户写的或内置的回落协议）。
+ *
  * models.dev（enrich.ts）：config 里缺元数据的自定义模型与合成模型，用传入的索引（只读缓存）补
- * contextWindow / maxTokens / input / reasoning / cost，来源记在 `modelMetadata()`；内置目录不补。
+ * contextWindow / maxTokens / input / reasoning / cost，来源记在 `modelMetadata()`；内置目录按同一索引
+ * （快照 ⊕ `ama models refresh` 的覆盖）在 catalog.ts 合并，缺字段的条目退回内置快照。
  */
 import { ApiRegistry, createDefaultApiRegistry } from "../apis/api.js";
 import { fakeProviderData } from "../fake/fake-provider.js";
@@ -28,34 +34,10 @@ 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";
-import { channelKeyId, modelChannels, parseChannels, splitChannelRef } from "./channels.js";
+import { catalogChannels, channelKeyId, dropChannels, materializeModel, pickBuiltinChannel, modelChannels, parseChannels, splitChannelRef, } from "./channels.js";
 import { catalogMetadata, enrichEntry, lazyIndex, } from "./enrich.js";
 import { closest } from "./suggest.js";
-/**
- * 物化：模型补齐供应商级字段（不可变：返回新对象）。给了 `channel` 时协议与地址取渠道的（模型级
- * `explicit` 覆盖优先），headers / compat 按 供应商 ← 渠道 ← 模型 合并，并记下渠道名。
- */
-export function materializeModel(model, provider, channel, explicit) {
-    const out = {
-        ...model,
-        provider: provider.id,
-        baseUrl: model.baseUrl ?? provider.baseUrl,
-    };
-    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;
-}
+export { materializeModel } from "./channels.js";
 function configKeysOf(config) {
     const keys = {};
     for (const [id, provider] of Object.entries(config?.providers ?? {})) {
@@ -75,6 +57,10 @@ export class ProviderRegistry {
     envBaseUrls = new Map();
     /** baseUrl 指向非官方主机的内置供应商：接受目录外的 model id。 */
     relayed = new Set();
+    /** config 里写了自己 `channels` 的供应商（内置渠道不因改 baseUrl 作废）。 */
+    userChannels = new Set();
+    /** config 里写了供应商级 `api` 的供应商（单渠道回落时目录模型跟它走）。 */
+    userApi = new Set();
     /** `provider/model` → 物化前的模型（多渠道供应商切换渠道时重新物化）。 */
     raw = new Map();
     /** `provider/model` → 元数据来源与 models.dev 匹配。 */
@@ -92,9 +78,9 @@ export class ProviderRegistry {
             configKeys: options.keys?.configKeys ?? configKeysOf(options.config),
             onWarning: (message) => this.warn(message),
         });
-        const catalog = loadBuiltinCatalog();
+        const catalog = this.loadCatalog();
         const env = options.keys?.useEnv === false ? {} : (options.keys?.env ?? process.env);
-        for (const { baseUrlEnv, ...base } of BUILTIN_PROVIDERS) {
+        for (const { baseUrlEnv, catalogApi: _catalogApi, ...base } of BUILTIN_PROVIDERS) {
             const models = (catalog.get(base.id) ?? []).map((entry) => {
                 const api = entry.api ?? base.api;
                 this.sources.set(`${base.id}/${entry.id}`, "builtin");
@@ -107,12 +93,12 @@ export class ProviderRegistry {
             const fromEnv = baseUrlEnv !== undefined ? env[baseUrlEnv]?.trim() : undefined;
             if (baseUrlEnv !== undefined && fromEnv)
                 this.envBaseUrls.set(base.id, baseUrlEnv);
-            this.providers.set(base.id, {
-                ...base,
-                ...(fromEnv ? { baseUrl: fromEnv } : {}),
-                models,
-                builtin: true,
-            });
+            const provider = { ...structuredClone(base), models, builtin: true };
+            if (fromEnv) {
+                provider.baseUrl = fromEnv;
+                dropChannels(provider);
+            }
+            this.providers.set(base.id, provider);
         }
         for (const [id, config] of Object.entries(options.config?.providers ?? {})) {
             this.applyConfig(id, config);
@@ -122,6 +108,8 @@ export class ProviderRegistry {
             if (baseUrl) {
                 provider.baseUrl = baseUrl;
                 this.envBaseUrls.delete(provider.id);
+                if (provider.builtin && !this.userChannels.has(provider.id))
+                    dropChannels(provider);
             }
             if (provider.builtin && isRelayedBaseUrl(provider.id, provider.baseUrl)) {
                 this.relayed.add(provider.id);
@@ -136,9 +124,52 @@ export class ProviderRegistry {
             this.providers.set(fake.id, fake);
         }
         for (const provider of this.providers.values()) {
+            if (provider.builtin)
+                this.settleBuiltinChannels(provider);
             provider.models = provider.models.map((model) => this.materialize(provider, model));
         }
     }
+    /** 内置目录（快照 ⊕ 用户刷新）；刷新数据出任何问题都退回内置快照，不让启动失败。 */
+    loadCatalog() {
+        try {
+            return loadBuiltinCatalog(this.modelsDev());
+        }
+        catch (error) {
+            this.warn(`models.dev refresh data ignored: ${error.message}`);
+            return loadBuiltinCatalog();
+        }
+    }
+    /**
+     * 内置供应商定渠道：供应商级 api / baseUrl 取缺省渠道的（discover 等单地址的用法看它）；用户没指定渠道的
+     * 模型挂全部渠道（缺省在前）。渠道已作废的去掉模型上残留的 `channels`。
+     */
+    settleBuiltinChannels(provider) {
+        const channels = provider.channels;
+        if (channels === undefined || channels.length === 0) {
+            // 单渠道回落：没有模型级协议的目录模型走 catalogApi（用户改了 api 时走用户的）
+            const builtin = BUILTIN_PROVIDERS.find((p) => p.id === provider.id);
+            const api = builtin === undefined || this.userApi.has(provider.id)
+                ? provider.api
+                : (builtin.catalogApi ?? builtin.api);
+            for (const model of provider.models) {
+                delete model.channels;
+                const key = `${provider.id}/${model.id}`;
+                if (this.sources.get(key) === "builtin" && this.raw.get(key)?.explicit.api === undefined)
+                    model.api = api;
+            }
+            return;
+        }
+        const first = channels.find((c) => c.name === provider.defaultChannel) ?? channels[0];
+        if (first === undefined)
+            return;
+        provider.defaultChannel = first.name;
+        provider.api = first.api;
+        provider.baseUrl = first.baseUrl;
+        for (const model of provider.models) {
+            if (this.sources.get(`${provider.id}/${model.id}`) === "builtin" || !model.channels)
+                model.channels = catalogChannels(model.channels, channels, first.name);
+        }
+    }
     warn(message) {
         this.warnings.push(message);
         this.onWarning?.(message);
@@ -160,7 +191,15 @@ export class ProviderRegistry {
     }
     applyConfig(id, config) {
         const existing = this.providers.get(id);
-        const parsed = config.channels !== undefined ? parseChannels(id, config) : undefined;
+        const builtinChannels = existing?.builtin ? existing.channels : undefined;
+        const parsed = config.channels !== undefined
+            ? parseChannels(id, config, builtinChannels && {
+                channels: builtinChannels,
+                defaultChannel: existing?.defaultChannel,
+            })
+            : undefined;
+        if (config.channels !== undefined)
+            this.userChannels.add(id);
         for (const warning of parsed?.warnings ?? [])
             this.warn(warning);
         const first = parsed?.channels.find((c) => c.name === parsed.defaultChannel);
@@ -180,12 +219,16 @@ export class ProviderRegistry {
         };
         if (config.name !== undefined)
             provider.name = config.name;
-        if (config.api !== undefined)
+        if (config.api !== undefined) {
             provider.api = config.api;
+            this.userApi.add(id);
+        }
         if (config.baseUrl !== undefined) {
             provider.baseUrl = config.baseUrl;
             this.envBaseUrls.delete(id);
         }
+        if (builtinChannels !== undefined && parsed === undefined)
+            pickBuiltinChannel(provider, config, (m) => this.warn(m));
         if (parsed !== undefined && first !== undefined) {
             // 有渠道时供应商级 api / baseUrl 取首选渠道的（discover 等单地址的用法看它）。
             provider.channels = parsed.channels;
@@ -215,7 +258,8 @@ export class ProviderRegistry {
             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)
+            // 内置供应商上没写 channels 的模型：定渠道时挂全部渠道（settleBuiltinChannels）
+            if (provider.channels !== undefined && (entry.channels !== undefined || !provider.builtin))
                 model.channels = channelsOf(entry.channels, entry.id);
             const index = provider.models.findIndex((m) => m.id === entry.id);
             if (index >= 0)
@@ -263,11 +307,6 @@ export class ProviderRegistry {
                     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);
     }
     /** baseUrl 来自哪个环境变量（未生效返回 undefined）。 */

package/dist/ai/types.d.ts

@@ -15,6 +15,11 @@
  * - [W3-C0] 第三波 §1.3 的五个缓存兼容开关单列为 `PromptCacheCompat`（各协议共用），只并入
  *   `ProviderCompat`（全部可选），不改各协议 compat 接口——`detectCompat` 的返回形状不变，
  *   缺省值由 C1a 在协议层按端点推断。
+ * - [W5-C0] 第五波（docs/wave5-plan.md §2.1、§3.1）：`Model` 加 models.dev 元数据字段
+ *   （`family / knowledge / releaseDate / inputLimit / status`）；`AnthropicMessagesCompat` 加
+ *   `sendInterleavedThinkingBeta / sendCacheControl`、`OpenAIResponsesCompat` 加
+ *   `explicitCacheField`，全部可选（缺省由 W5-M2 的主机推断表给出）；`ProviderData.channels /
+ *   defaultChannel` 已有，内置供应商（`BuiltinProvider`）同样可带。
  */
 export type KnownApi = "anthropic-messages" | "openai-completions" | "openai-responses" | "google-generative-ai";
 export type Api = KnownApi | (string & {});
@@ -207,6 +212,12 @@ export interface AnthropicMessagesCompat {
     /** true：新模型用 `effort` 参数；false：老模型用 `budget_tokens`。 */
     adaptiveThinking: boolean;
     maxCacheBreakpoints: number;
+    /**
+     * [W5-C0] 发 `interleaved-thinking` beta 头；缺省（W5-M2 主机表）：官方端点 true、其它主机 false。
+     */
+    sendInterleavedThinkingBeta?: boolean;
+    /** [W5-C0] 打 `cache_control`；缺省 true，忽略它的端点（DeepSeek 等）可关以减小请求体。 */
+    sendCacheControl?: boolean;
 }
 /** B8 补全。 */
 export interface GoogleCompat {
@@ -217,6 +228,8 @@ export interface GoogleCompat {
 export interface OpenAIResponsesCompat {
     supportsReasoningSummary: boolean;
     supportsStore: boolean;
+    /** [W5-C0] 端点私有的显式缓存字段：`volcengine` = 火山方舟 `caching: { type: "enabled" }`。 */
+    explicitCacheField?: "volcengine";
 }
 /**
  * [W3-C0] 供应商不报缓存时的处理（第三波 §1.6）：`auto` 按响应自动判定三态；`silent` /
@@ -302,6 +315,16 @@ export interface Model {
     channel?: string;
     /** 该模型挂载的全部渠道，首个为首选（多渠道供应商才有）。 */
     channels?: string[];
+    /** 模型家族（如 `claude-sonnet`）。 */
+    family?: string;
+    /** 知识截止（`YYYY-MM` 或 `YYYY-MM-DD`）。 */
+    knowledge?: string;
+    /** 发布日期（`YYYY-MM-DD`）。 */
+    releaseDate?: string;
+    /** 输入上限（token），与 `contextWindow` 不同的模型才有。 */
+    inputLimit?: number;
+    /** 发布状态；正式版不填（deprecated 的模型在快照里已过滤）。 */
+    status?: "beta";
 }
 /** 物化后的渠道（docs/providers.md「渠道」）；key 不在这里，经 `resolveApiKey(provider, channel)` 取。 */
 export interface ProviderChannel {
@@ -326,9 +349,12 @@ export interface ProviderData {
     /** 本地服务 false：无 key 也能用。 */
     requiresApiKey: boolean;
     builtin: boolean;
-    /** 显式配置的渠道（没有 `channels` 的供应商不填，按单渠道处理）。 */
+    /**
+     * 渠道（没有 `channels` 的供应商不填，按单渠道处理）。[W5-C0] 内置供应商也可带内置渠道，
+     * 用户配置同名字段级覆盖、新名追加（物化归 W5-M2）。
+     */
     channels?: ProviderChannel[];
-    /** 首选渠道名（有 `channels` 时）。 */
+    /** 首选渠道名（有 `channels` 时；用户配置优先）。 */
     defaultChannel?: string;
 }
 /** `catalog/*.json` 文件形状（§3.4）。 */

package/dist/ai/types.js

@@ -15,5 +15,10 @@
  * - [W3-C0] 第三波 §1.3 的五个缓存兼容开关单列为 `PromptCacheCompat`（各协议共用），只并入
  *   `ProviderCompat`（全部可选），不改各协议 compat 接口——`detectCompat` 的返回形状不变，
  *   缺省值由 C1a 在协议层按端点推断。
+ * - [W5-C0] 第五波（docs/wave5-plan.md §2.1、§3.1）：`Model` 加 models.dev 元数据字段
+ *   （`family / knowledge / releaseDate / inputLimit / status`）；`AnthropicMessagesCompat` 加
+ *   `sendInterleavedThinkingBeta / sendCacheControl`、`OpenAIResponsesCompat` 加
+ *   `explicitCacheField`，全部可选（缺省由 W5-M2 的主机推断表给出）；`ProviderData.channels /
+ *   defaultChannel` 已有，内置供应商（`BuiltinProvider`）同样可带。
  */
 export {};