@armadra/agent 0.2.1 → 0.4.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,43 @@ 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";
+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 (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 +75,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 +98,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 +136,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 +186,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 +208,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 +240,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 +278,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 +306,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 +316,51 @@ 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 里 → channel_not_found，列出可用渠道。 */
+    withChannel(provider, model, channel) {
+        const available = model.channels ?? [];
+        if (!available.includes(channel) || !provider.channels?.some((c) => c.name === channel)) {
+            return {
+                ok: false,
+                reason: "channel_not_found",
+                candidates: available.filter(Boolean).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 };
     }
+    /**
+     * `provider/model`、`provider/model@渠道` 或裸模型 id。`@` 先按渠道解析（id 里本来就带 `@` 且已登记的
+     * 模型除外），中转供应商的「未登记即合成」不会把 `@渠道` 吞进模型 id。失败的 reason：供应商不存在 →
+     * provider_not_found（候选是编辑距离最近的供应商）；渠道不存在 → channel_not_found；模型不存在 →
+     * not_found（候选是最接近的模型）。
+     */
     findModel(ref) {
         const trimmed = ref.trim();
+        const split = splitChannelRef(trimmed);
+        if (split === undefined)
+            return this.findPlain(trimmed);
+        const exact = this.findPlain(trimmed, undefined, false);
+        if (exact.ok)
+            return exact;
+        const base = this.findPlain(split.base, split.channel);
+        if (!base.ok)
+            return base;
+        return this.withChannel(base.provider, base.model, split.channel);
+    }
+    findPlain(trimmed, channel, synthesize = true) {
         const slash = trimmed.indexOf("/");
         if (slash > 0) {
             const provider = this.providers.get(trimmed.slice(0, slash));
@@ -223,13 +369,25 @@ export class ProviderRegistry {
                 const model = provider.models.find((m) => m.id === id);
                 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 relayed = provider.models.length === 0 || this.relayed.has(provider.id);
+                if (synthesize && relayed && id.length > 0) {
+                    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) };
             }
         }
         const matches = this.listModels().filter((entry) => entry.model.id === trimmed);
+        if (matches.length === 0 && slash > 0) {
+            const ids = [...this.providers.keys()];
+            return {
+                ok: false,
+                reason: "provider_not_found",
+                candidates: closest(trimmed.slice(0, slash), ids),
+            };
+        }
         if (matches.length === 1 && matches[0]) {
             return { ok: true, model: matches[0].model, provider: matches[0].provider };
         }
@@ -246,25 +404,28 @@ export class ProviderRegistry {
             candidates: (configured.length > 0 ? configured : matches).map((entry) => `${entry.provider.id}/${entry.model.id}`),
         };
     }
+    /** 最接近的模型（包含关系优先，其次编辑距离），`provider/id` 形式。 */
     similar(id, providerId) {
-        const needle = id.toLowerCase();
-        return this.listModels()
-            .filter((entry) => providerId === undefined || entry.provider.id === providerId)
-            .filter((entry) => {
-            const candidate = entry.model.id.toLowerCase();
-            return needle.length > 0 && (candidate.includes(needle) || needle.includes(candidate));
-        })
-            .slice(0, 10)
-            .map((entry) => `${entry.provider.id}/${entry.model.id}`);
+        const entries = this.listModels().filter((entry) => providerId === undefined || entry.provider.id === providerId);
+        return closest(id, entries, 5, (entry) => entry.model.id).map((entry) => `${entry.provider.id}/${entry.model.id}`);
     }
     hasConfiguredKey(providerId) {
         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/providers/suggest.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 模型 / 供应商 / 渠道写错时的候选与报错文案（W4-C）。
+ *
+ * 候选排序：包含关系（`sonnet` ⊂ `claude-sonnet-5`）优先，其次按编辑距离；距离超过
+ * `max(2, ⌈长度 / 3⌉)` 的不算接近。只比较 id 本身（不含 `provider/` 前缀），大小写不敏感。
+ */
+import type { ModelLookup } from "../types.js";
+/** Levenshtein 距离（插入 / 删除 / 替换各计 1）。 */
+export declare function editDistance(a: string, b: string): number;
+/**
+ * 从 `candidates` 里挑与 `needle` 最接近的至多 `limit` 个。`key` 取参与比较的部分
+ * （缺省整串），返回原值。
+ */
+export declare function closest<T>(needle: string, candidates: readonly T[], limit?: number, key?: (item: T) => string): T[];
+/** 解析失败的一行说明（不含前缀标签）：`渠道不存在：x；该模型可用渠道：…` 等。 */
+export declare function describeLookupFailure(ref: string, failure: Extract<ModelLookup, {
+    ok: false;
+}>): string;

package/dist/ai/providers/suggest.js

@@ -0,0 +1,72 @@
+/**
+ * 模型 / 供应商 / 渠道写错时的候选与报错文案（W4-C）。
+ *
+ * 候选排序：包含关系（`sonnet` ⊂ `claude-sonnet-5`）优先，其次按编辑距离；距离超过
+ * `max(2, ⌈长度 / 3⌉)` 的不算接近。只比较 id 本身（不含 `provider/` 前缀），大小写不敏感。
+ */
+/** Levenshtein 距离（插入 / 删除 / 替换各计 1）。 */
+export function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const row = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            row[j] = Math.min((prev[j] ?? 0) + 1, (row[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+        }
+        prev = row;
+    }
+    return prev[b.length] ?? 0;
+}
+/**
+ * 从 `candidates` 里挑与 `needle` 最接近的至多 `limit` 个。`key` 取参与比较的部分
+ * （缺省整串），返回原值。
+ */
+export function closest(needle, candidates, limit = 5, key = String) {
+    const target = needle.toLowerCase();
+    if (target === "")
+        return [];
+    const budget = Math.max(2, Math.ceil(target.length / 3));
+    const scored = [];
+    candidates.forEach((item, index) => {
+        const value = key(item).toLowerCase();
+        if (value === "")
+            return;
+        if (value.includes(target) || target.includes(value)) {
+            scored.push({ item, score: Math.abs(value.length - target.length) / 1000, index });
+            return;
+        }
+        const distance = editDistance(target, value);
+        if (distance <= budget)
+            scored.push({ item, score: distance, index });
+    });
+    return scored
+        .sort((a, b) => a.score - b.score || a.index - b.index)
+        .slice(0, limit)
+        .map((entry) => entry.item);
+}
+/** 解析失败的一行说明（不含前缀标签）：`渠道不存在：x；该模型可用渠道：…` 等。 */
+export function describeLookupFailure(ref, failure) {
+    const list = failure.candidates.slice(0, 20).join(", ");
+    switch (failure.reason) {
+        case "channel_not_found":
+            return failure.candidates.length > 0
+                ? `渠道不存在：${ref}；该模型可用渠道：${list}`
+                : `渠道不存在：${ref}；该模型没有可选渠道（去掉 @ 后缀）`;
+        case "provider_not_found":
+            return failure.candidates.length > 0
+                ? `供应商不存在：${ref}；最接近的供应商：${list}`
+                : `供应商不存在：${ref}（ama providers list 查看已配置的供应商）`;
+        case "ambiguous":
+            return `模型名有歧义：${ref}；候选：${list}`;
+        default:
+            return failure.candidates.length > 0
+                ? `模型不存在：${ref}；最接近的模型：${list}`
+                : `模型不存在：${ref}（ama models list 查看可用模型）`;
+    }
+}

package/dist/ai/sse.d.ts

@@ -28,5 +28,9 @@ export declare class SseParser {
     private processLine;
     private dispatch;
 }
-/** 从字节流读 SSE 事件；`signal` 中止时停止读取（调用方据此产出 aborted）。 */
-export declare function readSseEvents(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<SseEvent>;
+/**
+ * 从字节流读 SSE 事件；`signal` 中止时停止读取（调用方据此产出 aborted）。
+ * `idleTimeoutMs`：等待下一块字节的上限，每收到一块即重新计时（消费者处理事件的时间不计）；
+ * 超时取消底层流并抛 `IdleTimeoutError`（phase `stream`）。
+ */
+export declare function readSseEvents(body: ReadableStream<Uint8Array>, signal?: AbortSignal, idleTimeoutMs?: number): AsyncGenerator<SseEvent>;

package/dist/ai/sse.js

@@ -6,6 +6,7 @@
  * 第一个空格去掉；多条 data 以 LF 连接。为兼容不规范服务端，流结束时未以空行收尾的最后一个
  * 事件也会分派。
  */
+import { IdleTimeoutError } from "./http.js";
 export class SseParser {
     buffer = "";
     event;
@@ -102,8 +103,12 @@ export class SseParser {
         return hadContent ? event : undefined;
     }
 }
-/** 从字节流读 SSE 事件；`signal` 中止时停止读取（调用方据此产出 aborted）。 */
-export async function* readSseEvents(body, signal) {
+/**
+ * 从字节流读 SSE 事件；`signal` 中止时停止读取（调用方据此产出 aborted）。
+ * `idleTimeoutMs`：等待下一块字节的上限，每收到一块即重新计时（消费者处理事件的时间不计）；
+ * 超时取消底层流并抛 `IdleTimeoutError`（phase `stream`）。
+ */
+export async function* readSseEvents(body, signal, idleTimeoutMs) {
     const reader = body.getReader();
     const decoder = new TextDecoder("utf-8");
     const parser = new SseParser();
@@ -112,11 +117,25 @@ export async function* readSseEvents(body, signal) {
     };
     signal?.addEventListener("abort", onAbort, { once: true });
     let drained = false;
+    let idle;
+    let stalled = false;
+    const arm = () => {
+        if (idleTimeoutMs === undefined || idleTimeoutMs <= 0)
+            return;
+        idle = setTimeout(() => {
+            stalled = true;
+            reader.cancel().catch(() => undefined);
+        }, idleTimeoutMs);
+    };
     try {
         while (true) {
             if (signal?.aborted)
                 return;
+            arm();
             const { value, done } = await reader.read();
+            clearTimeout(idle);
+            if (stalled && !signal?.aborted)
+                throw new IdleTimeoutError(idleTimeoutMs ?? 0, "stream");
             if (done)
                 break;
             if (signal?.aborted)
@@ -131,6 +150,7 @@ export async function* readSseEvents(body, signal) {
             yield event;
     }
     finally {
+        clearTimeout(idle);
         signal?.removeEventListener("abort", onAbort);
         // 消费者提前退出（读到终止事件即 break）或中止：取消底层流，释放连接
         if (!drained)

package/dist/ai/types.d.ts

@@ -27,11 +27,14 @@ export type CacheRetention = "none" | "short" | "long";
  * 真实回合，`summary` 是压缩 / 分支摘要，`warm` 是缓存保温重放，`probe` 是 `models check` /
  * `cache-probe` 一类的探测。缺省视为 `turn`。协议层只透传，不改变请求体。
  */
-export type RequestPurpose = "turn" | "summary" | "warm" | "probe";
+/** `classify`：auto 权限模式的分类请求（独立请求，不经会话层缓存观测、不触发保温）。 */
+export type RequestPurpose = "turn" | "summary" | "warm" | "probe" | "classify";
 /** `provider/model-id` 拆开后的引用。 */
 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 +298,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 +326,10 @@ export interface ProviderData {
     /** 本地服务 false：无 key 也能用。 */
     requiresApiKey: boolean;
     builtin: boolean;
+    /** 显式配置的渠道（没有 `channels` 的供应商不填，按单渠道处理）。 */
+    channels?: ProviderChannel[];
+    /** 首选渠道名（有 `channels` 时）。 */
+    defaultChannel?: string;
 }
 /** `catalog/*.json` 文件形状（§3.4）。 */
 export interface ModelCatalogFile {
@@ -323,6 +343,11 @@ export interface StreamOptions {
     /** 值为 null 表示删除该头。 */
     headers?: Record<string, string | null>;
     timeoutMs?: number;
+    /**
+     * 空闲超时：等响应头、以及流中两块数据之间的最长间隔（每收到字节即重新计时）。缺省 300 000，
+     * 0 关闭。超时报 `idle timeout` 错误，会话层按可重试处理。
+     */
+    idleTimeoutMs?: number;
     maxTokens?: number;
     temperature?: number;
     thinkingLevel?: ModelThinkingLevel;
@@ -415,7 +440,8 @@ export type ModelLookup = {
     provider: ProviderData;
 } | {
     ok: false;
-    reason: "not_found" | "ambiguous" | "provider_not_found";
+    /** `channel_not_found`：模型在，`@渠道` 不在（候选是该模型可用的 `provider/model@渠道`）。 */
+    reason: "not_found" | "ambiguous" | "provider_not_found" | "channel_not_found";
     candidates: string[];
 };
 export interface ProviderRegistryApi {
@@ -423,6 +449,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;
 }