@armadra/agent 0.0.0-stage → 0.2.1

package/dist/ai/providers/catalog.js

@@ -0,0 +1,166 @@
+/**
+ * 模型目录（设计 §3.4）：`catalog/*.json` 是数据源（人工校对、PR 更新），随包携带。
+ *
+ * 运行时零依赖、bundle 为单文件，不能在运行时读 JSON 文件；`catalog-data.ts` 是由 JSON 生成
+ * 的字符串表（`UPDATE_CATALOG=1 pnpm vitest run src/ai/providers/catalog.test.ts` 重新生成，
+ * 测试守住两者一致）。本模块解析并校验它，另提供覆盖合并。
+ *
+ * 必填字段：id、name、maxTokens、reasoning；contextWindow 与 cost「宁缺不猜」——数据源里
+ * 不确定的就不写（缺 contextWindow → 关自动压缩并警告；缺 cost → 显示 `$?`）。`promptCache`
+ * （TTL 秒数与最小可缓存长度）同样只写有公开依据的值（第三波 §1.4），留空 = 不承诺。
+ */
+import { AmaError } from "../../errors.js";
+import { CATALOG_SOURCES } from "./catalog-data.js";
+import { THINKING_LEVELS } from "../thinking.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonNegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+/** 校验一个模型条目，返回问题列表（空 = 合法）。 */
+export function checkCatalogModel(value, path) {
+    const problems = [];
+    if (!isRecord(value))
+        return [`${path}: must be an object`];
+    if (typeof value["id"] !== "string" || value["id"].length === 0)
+        problems.push(`${path}.id`);
+    if (typeof value["name"] !== "string")
+        problems.push(`${path}.name`);
+    if (typeof value["reasoning"] !== "boolean")
+        problems.push(`${path}.reasoning`);
+    if (!isNonNegative(value["maxTokens"]) || value["maxTokens"] === 0) {
+        problems.push(`${path}.maxTokens`);
+    }
+    if (value["contextWindow"] !== undefined && !isNonNegative(value["contextWindow"])) {
+        problems.push(`${path}.contextWindow`);
+    }
+    const input = value["input"];
+    if (input !== undefined &&
+        (!Array.isArray(input) || !input.every((i) => i === "text" || i === "image"))) {
+        problems.push(`${path}.input`);
+    }
+    const cost = value["cost"];
+    if (cost !== undefined) {
+        if (!isRecord(cost))
+            problems.push(`${path}.cost`);
+        else {
+            for (const key of ["input", "output", "cacheRead", "cacheWrite"]) {
+                if (!isNonNegative(cost[key]))
+                    problems.push(`${path}.cost.${key}`);
+            }
+            if (cost["tiers"] !== undefined && !Array.isArray(cost["tiers"])) {
+                problems.push(`${path}.cost.tiers`);
+            }
+        }
+    }
+    const promptCache = value["promptCache"];
+    if (promptCache !== undefined) {
+        if (!isRecord(promptCache))
+            problems.push(`${path}.promptCache`);
+        else {
+            for (const [key, seconds] of Object.entries(promptCache)) {
+                const known = key === "short" || key === "long" || key === "minTokens";
+                if (!known || !Number.isInteger(seconds) || seconds <= 0) {
+                    problems.push(`${path}.promptCache.${key}`);
+                }
+            }
+            const { short, long } = promptCache;
+            if (typeof short === "number" && typeof long === "number" && long < short) {
+                problems.push(`${path}.promptCache.long < short`);
+            }
+        }
+    }
+    const map = value["thinkingLevelMap"];
+    if (map !== undefined) {
+        if (!isRecord(map))
+            problems.push(`${path}.thinkingLevelMap`);
+        else {
+            for (const [level, mapped] of Object.entries(map)) {
+                const okLevel = THINKING_LEVELS.includes(level);
+                const okValue = mapped === null || typeof mapped === "string" || typeof mapped === "number";
+                if (!okLevel || !okValue)
+                    problems.push(`${path}.thinkingLevelMap.${level}`);
+            }
+        }
+    }
+    return problems;
+}
+export function parseCatalogFile(value, source) {
+    const problems = [];
+    if (!isRecord(value))
+        problems.push("$: must be an object");
+    else {
+        if (value["version"] !== 1)
+            problems.push("$.version must be 1");
+        if (typeof value["provider"] !== "string")
+            problems.push("$.provider");
+        if (!Array.isArray(value["models"]))
+            problems.push("$.models must be an array");
+        else {
+            const seen = new Set();
+            value["models"].forEach((model, i) => {
+                problems.push(...checkCatalogModel(model, `$.models[${i}]`));
+                const id = isRecord(model) ? model["id"] : undefined;
+                if (typeof id === "string") {
+                    if (seen.has(id))
+                        problems.push(`$.models[${i}].id duplicated: ${id}`);
+                    seen.add(id);
+                }
+            });
+        }
+    }
+    if (problems.length > 0) {
+        throw new AmaError("config_invalid", `model catalog ${source} is invalid: ${problems.join(", ")}`);
+    }
+    return value;
+}
+let cache;
+/** 内置目录：供应商 id → 模型条目（深拷贝，调用方可随意修改）。 */
+export function loadBuiltinCatalog() {
+    if (!cache) {
+        cache = new Map();
+        for (const [provider, raw] of Object.entries(CATALOG_SOURCES)) {
+            const file = parseCatalogFile(JSON.parse(raw), `catalog/${provider}.json`);
+            cache.set(file.provider, file.models);
+        }
+    }
+    const copy = new Map();
+    for (const [provider, models] of cache)
+        copy.set(provider, structuredClone(models));
+    return copy;
+}
+/** 目录条目 → Model（补 provider / api 与缺省 input）。 */
+export function toModel(entry, provider, api) {
+    return { ...structuredClone(entry), input: entry.input ?? ["text"], provider, api };
+}
+/** 自定义模型缺省：maxTokens 8192、reasoning false、input ["text"]、name = id；不猜 contextWindow。 */
+export function withCustomDefaults(entry, provider, api) {
+    return {
+        ...structuredClone(entry),
+        name: entry.name ?? entry.id,
+        input: entry.input ?? ["text"],
+        reasoning: entry.reasoning ?? false,
+        maxTokens: entry.maxTokens ?? 8192,
+        provider,
+        api,
+    };
+}
+/** 只改元数据：浅合并，`compat` / `cost` / `thinkingLevelMap` / `headers` 再合并一层。 */
+export function applyModelOverride(model, override) {
+    const { id: _id, ...rest } = override;
+    const next = { ...model, ...structuredClone(rest) };
+    if (override.compat && model.compat)
+        next.compat = { ...model.compat, ...override.compat };
+    if (override.cost && model.cost)
+        next.cost = { ...model.cost, ...override.cost };
+    if (override.headers && model.headers)
+        next.headers = { ...model.headers, ...override.headers };
+    if (override.thinkingLevelMap && model.thinkingLevelMap) {
+        next.thinkingLevelMap = {
+            ...model.thinkingLevelMap,
+            ...override.thinkingLevelMap,
+        };
+    }
+    return next;
+}

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

@@ -0,0 +1,83 @@
+/**
+ * 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。
+ */
+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 KeyResolverOptions } from "./auth.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;
+}
+export interface ModelEntry {
+    model: Model;
+    provider: ProviderData;
+    source: ModelSource;
+}
+/** 物化：模型补齐供应商级字段（不可变：返回新对象）。 */
+export declare function materializeModel(model: Model, provider: ProviderData): 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;
+    private readonly apis;
+    private readonly keys;
+    private readonly onWarning;
+    constructor(options?: ProviderRegistryOptions);
+    private warn;
+    private applyConfig;
+    /** baseUrl 来自哪个环境变量（未生效返回 undefined）。 */
+    baseUrlEnv(providerId: string): string | undefined;
+    /** 内置供应商的 baseUrl 指向非官方主机（中转站）。 */
+    isRelayed(providerId: string): boolean;
+    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;
+    findModel(ref: string): ModelLookup;
+    private similar;
+    hasConfiguredKey(providerId: string): boolean;
+    resolveApiKey(providerId: 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[]>;

package/dist/ai/providers/registry.js

@@ -0,0 +1,305 @@
+/**
+ * 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。
+ */
+import { ApiRegistry, createDefaultApiRegistry } from "../apis/api.js";
+import { fakeProviderData } from "../fake/fake-provider.js";
+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) {
+    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;
+    out.requiresApiKey = provider.requiresApiKey;
+    return out;
+}
+function configKeysOf(config) {
+    const keys = {};
+    for (const [id, provider] of Object.entries(config?.providers ?? {}))
+        keys[id] = provider.apiKey;
+    return keys;
+}
+export class ProviderRegistry {
+    warnings = [];
+    providers = new Map();
+    sources = new Map();
+    /** baseUrl 来自环境变量的供应商 → 变量名（被 config / auth.json 覆盖后删除）。 */
+    envBaseUrls = new Map();
+    /** baseUrl 指向非官方主机的内置供应商：接受目录外的 model id。 */
+    relayed = new Set();
+    apis;
+    keys;
+    onWarning;
+    constructor(options = {}) {
+        this.onWarning = options.onWarning;
+        this.apis = options.apis ?? createDefaultApiRegistry();
+        this.keys = new ApiKeyResolver({
+            ...options.keys,
+            configKeys: options.keys?.configKeys ?? configKeysOf(options.config),
+            onWarning: (message) => this.warn(message),
+        });
+        const catalog = loadBuiltinCatalog();
+        const env = options.keys?.useEnv === false ? {} : (options.keys?.env ?? process.env);
+        for (const { baseUrlEnv, ...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");
+                return toModel(entry, base.id, api);
+            });
+            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,
+            });
+        }
+        for (const [id, config] of Object.entries(options.config?.providers ?? {})) {
+            this.applyConfig(id, config);
+        }
+        for (const provider of this.providers.values()) {
+            const baseUrl = this.keys.authEntry(provider.id)?.entry.baseUrl;
+            if (baseUrl) {
+                provider.baseUrl = baseUrl;
+                this.envBaseUrls.delete(provider.id);
+            }
+            if (provider.builtin && isRelayedBaseUrl(provider.id, provider.baseUrl)) {
+                this.relayed.add(provider.id);
+                if (provider.compat?.sendPromptCacheKey === undefined)
+                    provider.compat = { ...provider.compat, sendPromptCacheKey: false };
+            }
+        }
+        if (options.includeFake !== false && !this.providers.has("fake")) {
+            const fake = fakeProviderData();
+            for (const model of fake.models)
+                this.sources.set(`fake/${model.id}`, "builtin");
+            this.providers.set(fake.id, fake);
+        }
+        for (const provider of this.providers.values()) {
+            provider.models = provider.models.map((model) => materializeModel(model, provider));
+        }
+    }
+    warn(message) {
+        this.warnings.push(message);
+        this.onWarning?.(message);
+    }
+    applyConfig(id, config) {
+        const existing = this.providers.get(id);
+        if (!existing && !config.baseUrl) {
+            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 ?? "",
+            envKeys: [fallbackEnvKey(id)],
+            models: [],
+            requiresApiKey: true,
+            builtin: false,
+        };
+        if (config.name !== undefined)
+            provider.name = config.name;
+        if (config.api !== undefined)
+            provider.api = config.api;
+        if (config.baseUrl !== undefined) {
+            provider.baseUrl = config.baseUrl;
+            this.envBaseUrls.delete(id);
+        }
+        if (config.envKeys !== undefined) {
+            provider.envKeys = [
+                ...config.envKeys,
+                ...provider.envKeys.filter((k) => !config.envKeys?.includes(k)),
+            ];
+        }
+        if (config.authHeader !== undefined)
+            provider.authHeader = config.authHeader;
+        if (config.headers)
+            provider.headers = mergeHeaders(provider.headers, config.headers);
+        if (config.compat)
+            provider.compat = { ...provider.compat, ...config.compat };
+        if (config.requiresApiKey !== undefined)
+            provider.requiresApiKey = config.requiresApiKey;
+        for (const entry of config.models ?? []) {
+            // 模型级 api（第三波 §2.3）：同一中转下不同模型走不同协议；缺省沿用供应商的。
+            const model = withCustomDefaults(entry, id, entry.api ?? provider.api);
+            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");
+        }
+        for (const override of config.modelOverrides ?? []) {
+            const index = provider.models.findIndex((m) => m.id === override.id);
+            const current = provider.models[index];
+            if (!current) {
+                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;
+        }
+        this.providers.set(id, provider);
+    }
+    /** baseUrl 来自哪个环境变量（未生效返回 undefined）。 */
+    baseUrlEnv(providerId) {
+        return this.envBaseUrls.get(providerId);
+    }
+    /** 内置供应商的 baseUrl 指向非官方主机（中转站）。 */
+    isRelayed(providerId) {
+        return this.relayed.has(providerId);
+    }
+    list() {
+        return [...this.providers.values()];
+    }
+    get(providerId) {
+        return this.providers.get(providerId);
+    }
+    listModels() {
+        const out = [];
+        for (const provider of this.providers.values()) {
+            for (const model of provider.models) {
+                out.push({ model, provider, source: this.modelSource(provider.id, model.id) });
+            }
+        }
+        return out;
+    }
+    modelSource(providerId, modelId) {
+        return this.sources.get(`${providerId}/${modelId}`) ?? "config";
+    }
+    /** 追加 / 替换模型（例如本地枚举得到的 ollama 模型）。 */
+    addModels(providerId, models, source = "discovered") {
+        const provider = this.providers.get(providerId);
+        if (!provider)
+            return;
+        for (const raw of models) {
+            const model = materializeModel({ ...raw, provider: providerId }, provider);
+            const index = provider.models.findIndex((m) => m.id === model.id);
+            if (index >= 0)
+                provider.models[index] = model;
+            else
+                provider.models.push(model);
+            this.sources.set(`${providerId}/${model.id}`, source);
+        }
+    }
+    synthesize(provider, modelId) {
+        return materializeModel(withCustomDefaults({ id: modelId }, provider.id, provider.api), provider);
+    }
+    findModel(ref) {
+        const trimmed = ref.trim();
+        const slash = trimmed.indexOf("/");
+        if (slash > 0) {
+            const provider = this.providers.get(trimmed.slice(0, slash));
+            if (provider) {
+                const id = trimmed.slice(slash + 1);
+                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 };
+                }
+                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 === 1 && matches[0]) {
+            return { ok: true, model: matches[0].model, provider: matches[0].provider };
+        }
+        if (matches.length === 0) {
+            return { ok: false, reason: "not_found", candidates: this.similar(trimmed) };
+        }
+        const configured = matches.filter((entry) => this.keys.hasConfiguredKey(entry.provider));
+        if (configured.length === 1 && configured[0]) {
+            return { ok: true, model: configured[0].model, provider: configured[0].provider };
+        }
+        return {
+            ok: false,
+            reason: "ambiguous",
+            candidates: (configured.length > 0 ? configured : matches).map((entry) => `${entry.provider.id}/${entry.model.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}`);
+    }
+    hasConfiguredKey(providerId) {
+        const provider = this.providers.get(providerId);
+        return provider ? this.keys.hasConfiguredKey(provider) : false;
+    }
+    async resolveApiKey(providerId) {
+        const provider = this.providers.get(providerId);
+        if (!provider)
+            return { apiKey: undefined, source: "none" };
+        return this.keys.resolve(provider);
+    }
+    getApi(api) {
+        return this.apis.get(api);
+    }
+}
+/** 注册表若是 ProviderRegistry（或同形状），报告 baseUrl 来自的环境变量；否则 undefined。 */
+export function baseUrlEnvOf(registry, providerId) {
+    const r = registry;
+    return typeof r.baseUrlEnv === "function" ? r.baseUrlEnv(providerId) : undefined;
+}
+/**
+ * 模型枚举：本地服务（`ama models list --provider ollama|lmstudio`）与 `ama models discover`
+ * （第三波 §2.3）共用。ollama 走 `/api/tags`，其它走 OpenAI 兼容的 `GET {baseUrl}/models`；
+ * `url` / `headers` 由调用方给出时原样使用（远端中转要带鉴权头）。失败抛错由调用方展示。
+ */
+export async function discoverLocalModels(provider, options = {}) {
+    const signal = AbortSignal.any([
+        options.signal ?? new AbortController().signal,
+        AbortSignal.timeout(options.timeoutMs ?? 5000),
+    ]);
+    const base = provider.baseUrl.replace(/\/+$/, "");
+    const isOllama = options.url === undefined && (provider.id === "ollama" || base.includes(":11434"));
+    const url = options.url ?? (isOllama ? `${base.replace(/\/v1$/, "")}/api/tags` : `${base}/models`);
+    const response = await fetch(url, {
+        signal,
+        ...(options.headers !== undefined ? { headers: options.headers } : {}),
+    });
+    if (!response.ok)
+        throw new Error(`${response.status} listing models from ${url}`);
+    const body = (await response.json());
+    const ids = isOllama
+        ? (body.models ?? []).map((m) => m.name)
+        : (body.data ?? []).map((m) => m.id);
+    return [
+        ...new Set(ids.filter((id) => typeof id === "string" && id.length > 0)),
+    ].map((id) => withCustomDefaults({ id }, provider.id, provider.api));
+}

package/dist/ai/sse.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Server-Sent Events 解析（设计 §1.2 ai/sse.ts）：event / data / id / 多行 data / 注释行 /
+ * CRLF、CR、LF 三种行尾 / UTF-8 跨块 / 首字节 BOM。
+ *
+ * 规则取自 WHATWG「Interpreting an event stream」：空行分派事件；`:` 开头是注释；字段名后的
+ * 第一个空格去掉；多条 data 以 LF 连接。为兼容不规范服务端，流结束时未以空行收尾的最后一个
+ * 事件也会分派。
+ */
+export interface SseEvent {
+    /** `event:` 字段；缺省时为 undefined（规范上视为 "message"）。 */
+    event: string | undefined;
+    data: string;
+    id: string | undefined;
+}
+export declare class SseParser {
+    private buffer;
+    private event;
+    private data;
+    private id;
+    private hasData;
+    private bomChecked;
+    /** 上一块以 CR 结尾：下一块开头的 LF 属于同一个行尾。 */
+    private pendingCr;
+    /** 喂入一段文本，返回其中完整分派的事件。 */
+    feed(chunk: string): SseEvent[];
+    /** 流结束：处理残留行，并分派未以空行收尾的事件。 */
+    flush(): SseEvent[];
+    private processLine;
+    private dispatch;
+}
+/** 从字节流读 SSE 事件；`signal` 中止时停止读取（调用方据此产出 aborted）。 */
+export declare function readSseEvents(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<SseEvent>;