@armadra/agent 0.2.1 → 0.3.0

package/dist/cli/subcommands/models-cache-probe.js

@@ -103,7 +103,7 @@ async function run(ctx) {
         return ExitCode.NoModel;
     }
     const { model, provider } = found;
-    const key = await registry.resolveApiKey(provider.id);
+    const key = await registry.resolveApiKey(provider.id, model.channel);
     if (key.apiKey === undefined && provider.requiresApiKey) {
         io.stderr(`ama: ${provider.id} 没有 API key（ama auth set ${provider.id}）\n`);
         return ExitCode.NoModel;

package/dist/cli/subcommands/models-discover.d.ts

@@ -12,6 +12,9 @@
  * `--write`：新条目合并进用户级 config.json 的 `providers.<id>.models`——已有同 id 不覆盖；只写
  * `id` 与探到的 `api`（与供应商协议相同时省略）；带 `--probe` 时只写探测成功的模型。不猜
  * `contextWindow`（自动压缩随之关闭，输出 warning）。写前备份为 `config.json.bak`。
+ *
+ * models.dev：列表之后按需刷新缓存（24 小时内不重拉），每个模型标出上下文、输出、图片、工具调用与
+ * 匹配结果；`--write` 跳过 models.dev 标明不支持工具调用的模型。元数据不写进配置——运行时从缓存补。
  */
 import type { Api, Model, ProviderData, ProviderRegistryApi } from "../../ai/types.js";
 import type { ModelsAction } from "./models.js";
@@ -35,6 +38,9 @@ export interface ProbeOptions {
     /** 因鉴权失败或限流提前停止时回调。 */
     onStop?: (reason: string) => void;
 }
+export declare const FATAL_STATUS: RegExp;
 /** 返回已探测模型 → 第一个成功的协议（都失败为 undefined）；超出 `limit` 或提前停止的不在表里。 */
 export declare function probeModelApis(registry: ProviderRegistryApi, provider: ProviderData, ids: string[], limit: number, options?: ProbeOptions): Promise<Map<string, Api | undefined>>;
+/** 一次最小请求；成功返回 undefined，失败返回错误文本（`ama providers add --probe` 也用）。 */
+export declare function attempt(registry: ProviderRegistryApi, model: Model, apiKey: string | undefined, timeoutMs?: number): Promise<string | undefined>;
 export declare const DISCOVER_ACTION: ModelsAction;

package/dist/cli/subcommands/models-discover.js

@@ -12,15 +12,21 @@
  * `--write`：新条目合并进用户级 config.json 的 `providers.<id>.models`——已有同 id 不覆盖；只写
  * `id` 与探到的 `api`（与供应商协议相同时省略）；带 `--probe` 时只写探测成功的模型。不猜
  * `contextWindow`（自动压缩随之关闭，输出 warning）。写前备份为 `config.json.bak`。
+ *
+ * models.dev：列表之后按需刷新缓存（24 小时内不重拉），每个模型标出上下文、输出、图片、工具调用与
+ * 匹配结果；`--write` 跳过 models.dev 标明不支持工具调用的模型。元数据不写进配置——运行时从缓存补。
  */
 import { authHeaders, mergeHeaders } from "../../ai/http.js";
 import { discoverLocalModels, materializeModel } from "../../ai/providers/registry.js";
 import { withCustomDefaults } from "../../ai/providers/catalog.js";
+import { describeRefresh, refreshModelsDev } from "../../ai/providers/models-dev-cache.js";
+import { matchLabel, modelsDevFields } from "../../ai/providers/models-dev.js";
 import { existsSync } from "node:fs";
 import { loadConfigFile } from "../../config/load.js";
 import { writeConfigFile } from "../../config/write.js";
 import { UsageError } from "../args.js";
 import { ExitCode } from "../exit-codes.js";
+import { compactTokens } from "./model-meta.js";
 export const DISCOVER_TIMEOUT_MS = 15_000;
 export const PROBE_TIMEOUT_MS = 30_000;
 export const DEFAULT_PROBE_LIMIT = 30;
@@ -51,7 +57,7 @@ export function probeOrder(provider) {
         ? [provider.api, ...PROBE_APIS.filter((api) => api !== provider.api)]
         : [...PROBE_APIS];
 }
-const FATAL_STATUS = /^(?:HTTP )?(?:401|403|429)\b/;
+export const FATAL_STATUS = /^(?:HTTP )?(?:401|403|429)\b/;
 /** 返回已探测模型 → 第一个成功的协议（都失败为 undefined）；超出 `limit` 或提前停止的不在表里。 */
 export async function probeModelApis(registry, provider, ids, limit, options = {}) {
     const result = new Map();
@@ -80,8 +86,8 @@ export async function probeModelApis(registry, provider, ids, limit, options = {
     }
     return result;
 }
-/** 一次最小请求；成功返回 undefined，失败返回错误文本。 */
-async function attempt(registry, model, apiKey, timeoutMs = PROBE_TIMEOUT_MS) {
+/** 一次最小请求；成功返回 undefined，失败返回错误文本（`ama providers add --probe` 也用）。 */
+export async function attempt(registry, model, apiKey, timeoutMs = PROBE_TIMEOUT_MS) {
     const impl = registry.getApi(model.api);
     if (impl === undefined)
         return `协议 ${model.api} 尚未实现`;
@@ -111,7 +117,7 @@ function parseLimit(raw) {
     return n;
 }
 /** 把新条目合并进用户级 config.json；返回写入条数。 */
-function writeEntries(ctx, provider, entries) {
+function writeEntries(ctx, provider, entries, notes) {
     const { io } = ctx;
     const path = ctx.level.userConfigPath;
     const config = structuredClone(loadConfigFile("config", path)?.value ?? { version: 1 });
@@ -134,7 +140,12 @@ function writeEntries(ctx, provider, entries) {
     writeConfigFile(path, config, { backup: true });
     io.stdout(`\n已写入 ${path}：${provider.id} 新增 ${added.length} 个模型` +
         `${kept > 0 ? `，${kept} 个已存在未覆盖` : ""}${backup ? `（原文件备份为 ${path}.bak）` : ""}\n`);
-    io.stderr(`ama: 警告：新增模型未设 contextWindow，自动压缩关闭；需要时在 config.json 里补上\n`);
+    if (notes.noTools.size > 0)
+        io.stdout(`跳过不支持工具调用的模型（models.dev）：${[...notes.noTools].join(", ")}\n`);
+    const blind = added.filter((entry) => notes.unmatched.has(entry.id)).map((entry) => entry.id);
+    if (blind.length > 0)
+        io.stderr(`ama: 警告：${blind.join(", ")} 在 models.dev 未匹配，没有 contextWindow，自动压缩关闭；` +
+            `需要时在 config.json 里补上或写 modelsDev\n`);
     return added.length;
 }
 async function run(ctx) {
@@ -161,14 +172,31 @@ async function run(ctx) {
     }
     const configured = new Map(provider.models.map((m) => [m.id, m]));
     io.stdout(`${provider.id}：发现 ${found.length} 个模型（${modelsUrl(provider)}）\n`);
+    const md = await refreshModelsDev({ dataDir: ctx.level.dataDir, env: io.env });
+    io.stdout(`${describeRefresh(md)}\n`);
+    if (md.warning !== undefined)
+        io.stderr(`ama: 警告：${md.warning}\n`);
+    const noTools = new Set();
+    const unmatched = new Set();
     for (const model of found) {
         const known = configured.get(model.id);
-        io.stdout(`  ${model.id}${known !== undefined ? `  已配置（${known.api}）` : ""}\n`);
+        const match = md.index?.match(model.id);
+        const fields = match !== undefined ? modelsDevFields(match.model) : undefined;
+        if (fields?.toolCall === false)
+            noTools.add(model.id);
+        if (match === undefined)
+            unmatched.add(model.id);
+        const meta = fields === undefined
+            ? "  models.dev 未匹配"
+            : `  ctx ${compactTokens(fields.contextWindow)} · out ${compactTokens(fields.maxTokens)}` +
+                `${fields.input?.includes("image") ? " · 图片" : ""}${fields.reasoning ? " · 思考" : ""}` +
+                `${fields.toolCall === false ? " · 不支持工具调用" : ""} · ${matchLabel(match)}`;
+        io.stdout(`  ${model.id}${known !== undefined ? `  已配置（${known.api}）` : ""}${meta}\n`);
     }
     const write = ctx.flags.has("write");
     if (!ctx.flags.has("probe")) {
         if (write)
-            writeEntries(ctx, provider, found.map((m) => ({ id: m.id })));
+            writeEntries(ctx, provider, found.filter((m) => !noTools.has(m.id)).map((m) => ({ id: m.id })), { noTools, unmatched });
         return ExitCode.Ok;
     }
     const ids = found.map((m) => m.id);
@@ -184,10 +212,10 @@ async function run(ctx) {
     if (write) {
         const entries = [];
         for (const [modelId, api] of probed) {
-            if (api !== undefined)
+            if (api !== undefined && !noTools.has(modelId))
                 entries.push(api === provider.api ? { id: modelId } : { id: modelId, api });
         }
-        writeEntries(ctx, provider, entries);
+        writeEntries(ctx, provider, entries, { noTools, unmatched });
     }
     if (stopped !== undefined) {
         io.stderr(`ama: 探测提前停止（${stopped}）\n`);

package/dist/cli/subcommands/models.js

@@ -8,22 +8,16 @@
  * `cache-probe`、B12 的 `discover`）各写在自己的文件里，这里只加一行表项；用法文本、
  * 选项表与必填位置参数都从表里来。
  */
+import { formatModelRef, modelRefOf } from "../../ai/providers/channels.js";
+import { describeRefresh, modelsDevCachePath, refreshModelsDev, } from "../../ai/providers/models-dev-cache.js";
 import { parseSubArgs, UsageError } from "../args.js";
 import { ExitCode } from "../exit-codes.js";
 import { buildRegistry, loadUserLevel } from "./context.js";
 import { CACHE_PROBE_ACTION } from "./models-cache-probe.js";
 import { DISCOVER_ACTION } from "./models-discover.js";
+import { metadataOf, modelFlags, sourcesLine } from "./model-meta.js";
 const COMMON_VALUE_OPTIONS = ["profile", "auth-file"];
 export const CHECK_TIMEOUT_MS = 30_000;
-function compact(n) {
-    if (n === undefined)
-        return "?";
-    if (n >= 1_000_000)
-        return `${Math.round(n / 100_000) / 10}M`;
-    if (n >= 1000)
-        return `${Math.round(n / 1000)}k`;
-    return String(n);
-}
 async function list(io, registry, only) {
     const providers = registry.list().filter((p) => only === undefined || p.id === only);
     if (only !== undefined && providers.length === 0) {
@@ -38,14 +32,13 @@ async function list(io, registry, only) {
                 ? "无 key"
                 : "无需 key";
         io.stdout(`${provider.id}  ${provider.api}  ${keyText}\n`);
+        for (const channel of provider.channels ?? [])
+            io.stdout(`  @${channel.name}  ${channel.api}  ${channel.baseUrl}\n`);
         for (const model of provider.models) {
-            const flags = [
-                `ctx ${compact(model.contextWindow)}`,
-                `out ${compact(model.maxTokens)}`,
-                model.reasoning ? "思考" : undefined,
-                model.input.includes("image") ? "图片" : undefined,
-            ].filter((x) => x !== undefined);
-            io.stdout(`  ${provider.id}/${model.id}  ${flags.join(" · ")}\n`);
+            io.stdout(`  ${provider.id}/${model.id}  ${modelFlags(model)}\n`);
+            const sources = sourcesLine(metadataOf(registry, provider.id, model.id));
+            if (sources !== undefined)
+                io.stdout(`      ${sources}\n`);
         }
     }
     return ExitCode.Ok;
@@ -58,7 +51,7 @@ async function check(io, registry, ref) {
         return ExitCode.NoModel;
     }
     const { model, provider } = found;
-    const key = await registry.resolveApiKey(provider.id);
+    const key = await registry.resolveApiKey(provider.id, model.channel);
     if (key.apiKey === undefined && provider.requiresApiKey) {
         io.stderr(`ama: ${provider.id} 没有 API key（ama auth set ${provider.id}）\n`);
         return ExitCode.NoModel;
@@ -81,7 +74,8 @@ async function check(io, registry, ref) {
         io.stderr(`ama: ${provider.id}/${model.id} 失败（${ms} ms）：${message.errorMessage ?? message.stopReason}\n`);
         return ExitCode.RuntimeError;
     }
-    io.stdout(`${provider.id}/${model.id} 可用（${ms} ms，stopReason ${message.stopReason}）\n`);
+    const shown = formatModelRef(modelRefOf(model));
+    io.stdout(`${shown} 可用（${model.api}，${ms} ms，stopReason ${message.stopReason}）\n`);
     return ExitCode.Ok;
 }
 /** 动作表：键是子命令名，顺序即用法文本顺序。 */
@@ -98,6 +92,20 @@ export const MODELS_ACTIONS = Object.freeze({
     },
     discover: DISCOVER_ACTION,
     "cache-probe": CACHE_PROBE_ACTION,
+    "refresh-catalog": {
+        usage: "ama models refresh-catalog",
+        run: async (ctx) => {
+            const result = await refreshModelsDev({
+                dataDir: ctx.level.dataDir,
+                env: ctx.io.env,
+                force: true,
+            });
+            ctx.io.stdout(`${describeRefresh(result)}\n${modelsDevCachePath(ctx.level.dataDir)}\n`);
+            if (result.warning !== undefined)
+                ctx.io.stderr(`ama: 警告：${result.warning}\n`);
+            return result.status === "unavailable" ? ExitCode.RuntimeError : ExitCode.Ok;
+        },
+    },
 });
 export const MODELS_USAGE = `用法：${Object.values(MODELS_ACTIONS)
     .map((a) => a.usage)

package/dist/cli/subcommands/providers-list.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `ama providers list|channels|remove`（docs/providers.md「一键接入」）：供应商 → 渠道 → 模型数与 key 来源
+ * （从不显示 key）；remove 删配置条目（先备份）与 auth.json 里该供应商及其渠道的 key。
+ */
+import { type Ctx } from "./providers.js";
+export declare function listProviders(ctx: Ctx): Promise<number>;
+export declare function listChannels(ctx: Ctx, id: string): Promise<number>;
+export declare function removeProvider(ctx: Ctx, id: string): number;

package/dist/cli/subcommands/providers-list.js

@@ -0,0 +1,97 @@
+/**
+ * `ama providers list|channels|remove`（docs/providers.md「一键接入」）：供应商 → 渠道 → 模型数与 key 来源
+ * （从不显示 key）；remove 删配置条目（先备份）与 auth.json 里该供应商及其渠道的 key。
+ */
+import { apiShortName } from "../../ai/providers/channels.js";
+import { classifyKeyValue, readAuthFile, removeAuthKey } from "../../config/auth-file.js";
+import { writeConfigFile } from "../../config/write.js";
+import { ExitCode } from "../exit-codes.js";
+import { buildRegistry } from "./context.js";
+import { userConfig } from "./providers.js";
+async function keySource(registry, config, id, channel) {
+    const raw = channel !== undefined ? config?.channels?.[channel]?.apiKey : config?.apiKey;
+    if (raw !== undefined) {
+        const kind = classifyKeyValue(raw);
+        return kind === "env-ref"
+            ? raw
+            : kind === "command"
+                ? "!命令（config.json）"
+                : "字面量（config.json）";
+    }
+    const resolved = await registry.resolveApiKey(id, channel);
+    if (resolved.apiKey === undefined)
+        return channel !== undefined ? "同供应商" : "无";
+    if (channel !== undefined && resolved.source !== "auth-file")
+        return "同供应商";
+    return resolved.source === "env"
+        ? `环境变量 ${resolved.origin ?? ""}`
+        : resolved.source === "auth-file"
+            ? "auth.json"
+            : resolved.source;
+}
+export async function listProviders(ctx) {
+    const registry = await buildRegistry(ctx.level, ctx.io, ctx.deps);
+    const config = userConfig(ctx.level);
+    let shown = 0;
+    for (const provider of registry.list()) {
+        const own = config.providers?.[provider.id];
+        if (own === undefined &&
+            !(provider.builtin &&
+                provider.requiresApiKey &&
+                (await registry.resolveApiKey(provider.id)).apiKey !== undefined))
+            continue;
+        shown++;
+        const kind = provider.builtin ? "内置" : "自定义";
+        const channels = provider.channels ?? [];
+        ctx.io.stdout(`${provider.id}  ${kind} · ${channels.length > 0 ? `${channels.length} 渠道` : `${provider.api} ${provider.baseUrl}`} · ` +
+            `${provider.models.length} 模型 · key ${await keySource(registry, own, provider.id)}\n`);
+        for (const c of channels) {
+            const count = provider.models.filter((m) => m.channels?.includes(c.name)).length;
+            ctx.io.stdout(`  @${c.name}  ${c.api}  ${c.baseUrl}  ${count} 模型 · key ${await keySource(registry, own, provider.id, c.name)}\n`);
+        }
+    }
+    if (shown === 0)
+        ctx.io.stdout(`没有配置供应商（ama providers add <id> --base-url <url>）\n`);
+    return ExitCode.Ok;
+}
+export async function listChannels(ctx, id) {
+    const registry = await buildRegistry(ctx.level, ctx.io, ctx.deps);
+    const provider = registry.get(id);
+    if (provider === undefined) {
+        ctx.io.stderr(`ama: 供应商不存在：${id}\n`);
+        return ExitCode.NoModel;
+    }
+    const own = userConfig(ctx.level).providers?.[id];
+    if (provider.channels === undefined) {
+        ctx.io.stdout(`${id}：单渠道（${provider.api} ${provider.baseUrl}），${provider.models.length} 模型\n`);
+        return ExitCode.Ok;
+    }
+    for (const c of provider.channels) {
+        const models = provider.models.filter((m) => m.channels?.includes(c.name));
+        const mark = c.name === provider.defaultChannel ? "（缺省）" : "";
+        ctx.io.stdout(`@${c.name}${mark}  ${apiShortName(c.api)}  ${c.api}  ${c.baseUrl}  key ${await keySource(registry, own, id, c.name)}\n` +
+            `  ${models.length} 模型${models.length > 0 ? `：${models.map((m) => m.id).join(", ")}` : ""}\n`);
+    }
+    return ExitCode.Ok;
+}
+export function removeProvider(ctx, id) {
+    const config = userConfig(ctx.level);
+    const had = config.providers?.[id] !== undefined;
+    if (had) {
+        delete config.providers?.[id];
+        writeConfigFile(ctx.level.userConfigPath, config, { backup: true });
+        ctx.io.stdout(`已从 ${ctx.level.userConfigPath} 删除 ${id}（原文件备份为 config.json.bak）\n`);
+    }
+    const auth = readAuthFile(ctx.level.authFile).file;
+    let keys = 0;
+    for (const name of Object.keys(auth.providers))
+        if (name === id || name.startsWith(`${id}@`))
+            keys += removeAuthKey(ctx.level.authFile, name) ? 1 : 0;
+    if (keys > 0)
+        ctx.io.stdout(`已删除 ${ctx.level.authFile} 里 ${id} 的 ${keys} 个 key\n`);
+    if (!had && keys === 0) {
+        ctx.io.stderr(`ama: 没有供应商 ${id}\n`);
+        return ExitCode.RuntimeError;
+    }
+    return ExitCode.Ok;
+}

package/dist/cli/subcommands/providers-plan.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `ama providers add|refresh` 的纯计算部分（docs/providers.md「一键接入」）：候选渠道、模型列表的
+ * 协议提示、探测结果 → 模型渠道、渠道收敛、追加式合并进配置、表格。
+ *
+ * 不读写文件、不联网（`fetchModelList` 除外，它只是一次 GET）；命令流程在 providers.ts。
+ */
+import { type ModelsDevFields, type ModelsDevMatch } from "../../ai/providers/models-dev.js";
+import type { Api } from "../../ai/types.js";
+import type { ProviderConfig } from "../../config/types.js";
+export declare const PROBE_APIS: readonly Api[];
+export declare const DEFAULT_PREFER: readonly string[];
+export interface CandidateChannel {
+    name: string;
+    api: Api;
+    baseUrl: string;
+}
+/** `--channel name=api@baseUrl`。 */
+export declare function parseChannelSpec(spec: string): CandidateChannel;
+/** 从 `--base-url` 推出候选渠道；`api` 给定（非 auto）时只留对应的一个。 */
+export declare function defaultChannels(baseUrl: string, api?: string): CandidateChannel[];
+export interface ListedModel {
+    id: string;
+    /** new-api 一类中转的 `supported_endpoint_types`。 */
+    endpoints?: string[];
+}
+/**
+ * 模型列表的提示 → 候选渠道名。没有提示（或提示里没有认识的协议）返回 undefined；有提示但候选渠道
+ * 一个都不支持返回 []（该模型在这些渠道上不可用）。
+ */
+export declare function hintedChannels(listed: ListedModel, candidates: readonly CandidateChannel[]): string[] | undefined;
+/** 按 `prefer` 排序（不在 prefer 里的保持原顺序排在后面）。 */
+export declare function orderChannels(names: readonly string[], prefer: readonly string[]): string[];
+/** 解析 `GET /models` 的响应体。 */
+export declare function parseModelList(body: unknown): ListedModel[];
+/** 列模型用的渠道与 URL：第一个 OpenAI 系渠道 `{baseUrl}/models`；只有 Messages 时 `/v1/models`。 */
+export declare function listingTarget(candidates: readonly CandidateChannel[]): {
+    channel: CandidateChannel;
+    url: string;
+} | undefined;
+export type ModelStatus = "ok" | "unprobed" | "failed" | "no-tools" | "no-channel" | "existing";
+export interface ModelPlan {
+    id: string;
+    channels: string[];
+    status: ModelStatus;
+    fields: ModelsDevFields;
+    match: ModelsDevMatch | undefined;
+    /** 探测失败的原因（最后一次）。 */
+    error?: string;
+}
+/** 要探测的模型：`--probe-models` 给出的（保持顺序），否则按 id 字母序（不分大小写）取前 limit 个。 */
+export declare function probeSelection(ids: readonly string[], limit: number, only: readonly string[] | undefined): string[];
+/**
+ * 按请求上限截断：每个模型要试的渠道数相加超过 `max` 时丢掉后面的模型。返回保留的模型与请求数。
+ */
+export declare function capRequests(selected: readonly string[], channelsFor: (id: string) => readonly string[], max: number): {
+    ids: string[];
+    requests: number;
+    dropped: number;
+};
+/**
+ * 合并进已有的供应商配置（追加式）：已有渠道定义与模型条目一字不改，只加新渠道与新模型；
+ * 新模型只写 `id` 与 `channels`。返回新的配置与新增数。
+ */
+export declare function mergeProvider(existing: ProviderConfig | undefined, input: {
+    name?: string;
+    apiKey?: string;
+    channels: readonly CandidateChannel[];
+    models: readonly {
+        id: string;
+        channels: readonly string[];
+    }[];
+    prefer: readonly string[];
+}): {
+    config: ProviderConfig;
+    addedChannels: string[];
+    addedModels: string[];
+};
+/** 表格：id、渠道、上下文、输出、图像、推理、工具、价格（$/M 入/出）、状态、models.dev 匹配。 */
+export declare function renderTable(plans: readonly ModelPlan[]): string;

package/dist/cli/subcommands/providers-plan.js

@@ -0,0 +1,215 @@
+/**
+ * `ama providers add|refresh` 的纯计算部分（docs/providers.md「一键接入」）：候选渠道、模型列表的
+ * 协议提示、探测结果 → 模型渠道、渠道收敛、追加式合并进配置、表格。
+ *
+ * 不读写文件、不联网（`fetchModelList` 除外，它只是一次 GET）；命令流程在 providers.ts。
+ */
+import { apiShortName } from "../../ai/providers/channels.js";
+import { matchLabel, } from "../../ai/providers/models-dev.js";
+import { CHANNEL_NAME_PATTERN } from "../../config/types.js";
+import { padToWidth, visibleWidth } from "../../tui/ansi.js";
+import { UsageError } from "../args.js";
+import { compactTokens } from "./model-meta.js";
+export const PROBE_APIS = [
+    "openai-completions",
+    "openai-responses",
+    "anthropic-messages",
+];
+export const DEFAULT_PREFER = ["chat", "responses", "messages"];
+const API_CHOICES = [...PROBE_APIS, "google-generative-ai"];
+/** `--channel name=api@baseUrl`。 */
+export function parseChannelSpec(spec) {
+    const m = /^([^=]+)=([^@]+)@(.+)$/.exec(spec.trim());
+    if (!m)
+        throw new UsageError(`--channel 应为 <名字>=<协议>@<地址>：${spec}`);
+    const [, name = "", api = "", baseUrl = ""] = m;
+    if (!CHANNEL_NAME_PATTERN.test(name))
+        throw new UsageError(`渠道名不合法：${name}`);
+    if (!API_CHOICES.includes(api))
+        throw new UsageError(`--channel 的协议应为 ${API_CHOICES.join(" | ")}（收到 ${api}）`);
+    if (!/^https?:\/\//.test(baseUrl))
+        throw new UsageError(`--channel 的地址应为 http(s) URL：${baseUrl}`);
+    return { name, api: api, baseUrl: baseUrl.replace(/\/+$/, "") };
+}
+/** 从 `--base-url` 推出候选渠道；`api` 给定（非 auto）时只留对应的一个。 */
+export function defaultChannels(baseUrl, api) {
+    const base = baseUrl.replace(/\/+$/, "");
+    const root = base.replace(/\/v1$/, "");
+    const all = [
+        { name: "chat", api: "openai-completions", baseUrl: base },
+        { name: "responses", api: "openai-responses", baseUrl: base },
+        { name: "messages", api: "anthropic-messages", baseUrl: root },
+    ];
+    if (api === undefined || api === "auto")
+        return all;
+    if (!API_CHOICES.includes(api))
+        throw new UsageError(`--api 的取值应为 ${[...PROBE_APIS, "auto"].join(" | ")}（收到 ${api}）`);
+    const one = all.find((c) => c.api === api);
+    return [one ?? { name: apiShortName(api), api: api, baseUrl: base }];
+}
+const ENDPOINT_APIS = {
+    openai: "openai-completions",
+    "openai-response": "openai-responses",
+    "openai-responses": "openai-responses",
+    responses: "openai-responses",
+    anthropic: "anthropic-messages",
+    gemini: "google-generative-ai",
+};
+/**
+ * 模型列表的提示 → 候选渠道名。没有提示（或提示里没有认识的协议）返回 undefined；有提示但候选渠道
+ * 一个都不支持返回 []（该模型在这些渠道上不可用）。
+ */
+export function hintedChannels(listed, candidates) {
+    if (listed.endpoints === undefined || listed.endpoints.length === 0)
+        return undefined;
+    const apis = new Set(listed.endpoints.map((e) => ENDPOINT_APIS[e.toLowerCase()]).filter((a) => a !== undefined));
+    if (apis.size === 0)
+        return undefined;
+    return candidates.filter((c) => apis.has(c.api)).map((c) => c.name);
+}
+/** 按 `prefer` 排序（不在 prefer 里的保持原顺序排在后面）。 */
+export function orderChannels(names, prefer) {
+    const rank = (n) => {
+        const i = prefer.indexOf(n);
+        return i < 0 ? prefer.length : i;
+    };
+    return [...new Set(names)].sort((a, b) => rank(a) - rank(b));
+}
+/** 解析 `GET /models` 的响应体。 */
+export function parseModelList(body) {
+    const data = body?.data;
+    if (!Array.isArray(data))
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const item of data) {
+        const id = item?.id;
+        if (typeof id !== "string" || id === "" || seen.has(id))
+            continue;
+        seen.add(id);
+        const endpoints = item.supported_endpoint_types;
+        const listed = { id };
+        if (Array.isArray(endpoints))
+            listed.endpoints = endpoints.filter((e) => typeof e === "string");
+        out.push(listed);
+    }
+    return out;
+}
+/** 列模型用的渠道与 URL：第一个 OpenAI 系渠道 `{baseUrl}/models`；只有 Messages 时 `/v1/models`。 */
+export function listingTarget(candidates) {
+    const openai = candidates.find((c) => c.api === "openai-completions" || c.api === "openai-responses");
+    const channel = openai ?? candidates[0];
+    if (channel === undefined)
+        return undefined;
+    const base = channel.baseUrl.replace(/\/+$/, "");
+    const url = channel.api === "anthropic-messages" && !/\/v1$/.test(base)
+        ? `${base}/v1/models`
+        : `${base}/models`;
+    return { channel, url };
+}
+/** 要探测的模型：`--probe-models` 给出的（保持顺序），否则按 id 字母序（不分大小写）取前 limit 个。 */
+export function probeSelection(ids, limit, only) {
+    if (only !== undefined)
+        return only.filter((id) => ids.includes(id));
+    return [...ids].sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase())).slice(0, limit);
+}
+/**
+ * 按请求上限截断：每个模型要试的渠道数相加超过 `max` 时丢掉后面的模型。返回保留的模型与请求数。
+ */
+export function capRequests(selected, channelsFor, max) {
+    const ids = [];
+    let requests = 0;
+    for (const id of selected) {
+        const n = channelsFor(id).length;
+        if (requests + n > max)
+            break;
+        ids.push(id);
+        requests += n;
+    }
+    return { ids, requests, dropped: selected.length - ids.length };
+}
+/**
+ * 合并进已有的供应商配置（追加式）：已有渠道定义与模型条目一字不改，只加新渠道与新模型；
+ * 新模型只写 `id` 与 `channels`。返回新的配置与新增数。
+ */
+export function mergeProvider(existing, input) {
+    const config = structuredClone(existing ?? {});
+    if (input.name !== undefined && config.name === undefined)
+        config.name = input.name;
+    if (input.apiKey !== undefined && config.apiKey === undefined)
+        config.apiKey = input.apiKey;
+    const channels = config.channels ?? {};
+    const used = new Set(input.models.flatMap((m) => m.channels));
+    const addedChannels = [];
+    for (const c of input.channels) {
+        if (channels[c.name] !== undefined || !used.has(c.name))
+            continue;
+        channels[c.name] = { api: c.api, baseUrl: c.baseUrl };
+        addedChannels.push(c.name);
+    }
+    config.channels = channels;
+    if (config.defaultChannel === undefined || channels[config.defaultChannel] === undefined) {
+        const first = orderChannels(Object.keys(channels), input.prefer)[0];
+        if (first !== undefined)
+            config.defaultChannel = first;
+    }
+    const models = config.models ?? [];
+    const known = new Set(models.map((m) => m.id));
+    const addedModels = [];
+    for (const m of input.models) {
+        if (known.has(m.id) || m.channels.length === 0)
+            continue;
+        models.push({ id: m.id, channels: [...m.channels] });
+        known.add(m.id);
+        addedModels.push(m.id);
+    }
+    config.models = models;
+    return { config, addedChannels, addedModels };
+}
+const STATUS_TEXT = {
+    ok: "探测通过",
+    unprobed: "未探测",
+    failed: "探测失败，不写入",
+    "no-tools": "不支持工具调用，不写入",
+    "no-channel": "候选渠道都不支持，不写入",
+    existing: "已存在，未改动",
+};
+function cost(fields) {
+    return fields.cost !== undefined ? `$${fields.cost.input}/${fields.cost.output}` : "—";
+}
+function yesNo(value) {
+    return value === undefined ? "?" : value ? "是" : "否";
+}
+/** 表格：id、渠道、上下文、输出、图像、推理、工具、价格（$/M 入/出）、状态、models.dev 匹配。 */
+export function renderTable(plans) {
+    const head = [
+        "模型",
+        "渠道",
+        "上下文",
+        "输出",
+        "图像",
+        "推理",
+        "工具",
+        "价格$/M",
+        "状态",
+        "models.dev",
+    ];
+    const rows = plans.map((p) => [
+        p.id,
+        p.channels.length > 0 ? p.channels.join(",") : "—",
+        compactTokens(p.fields.contextWindow),
+        compactTokens(p.fields.maxTokens),
+        p.fields.input === undefined ? "?" : p.fields.input.includes("image") ? "是" : "否",
+        yesNo(p.fields.reasoning),
+        yesNo(p.fields.toolCall),
+        cost(p.fields),
+        STATUS_TEXT[p.status],
+        matchLabel(p.match),
+    ]);
+    const widths = head.map((h, i) => Math.max(visibleWidth(h), ...rows.map((r) => visibleWidth(r[i] ?? ""))));
+    const line = (cells) => cells
+        .map((cell, i) => (i === cells.length - 1 ? cell : padToWidth(cell, widths[i] ?? 0)))
+        .join("  ")
+        .trimEnd();
+    return [line(head), ...rows.map(line)].join("\n") + "\n";
+}

package/dist/cli/subcommands/providers.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `ama providers add|list|channels|remove|refresh`（docs/providers.md「一键接入」「渠道」）。
+ *
+ * - add：只给 baseUrl 与 key，列出中转的模型（`GET /models`）、用 models.dev 补元数据、可选逐渠道
+ *   探测，把渠道与模型追加进用户级 config.json（先备份）；key 从 stdin 读（不回显）存 auth.json，
+ *   或 `--key-env VAR` 写 `"apiKey": "$VAR"`。对已存在的供应商只追加，不改已有条目。
+ * - refresh：重拉 `/models` 与 models.dev，只追加新模型；已下架的只提示。
+ * - list / channels：供应商 → 渠道 → 模型数与 key 来源（从不显示 key）。remove：删配置与 auth.json 条目。
+ *
+ * 计费：`--probe` 每模型每渠道一次最小请求；执行前打印预估，TTY 问 y/N，非 TTY 必须 `--yes`。
+ */
+import type { AmaConfig } from "../../config/types.js";
+import type { CliIo, RuntimeDeps } from "../deps.js";
+import { type UserLevel } from "./context.js";
+export declare const DEFAULT_MAX_REQUESTS = 60;
+export declare const DEFAULT_LIMIT = 30;
+export declare const PROVIDERS_USAGE = "\u7528\u6CD5\uFF1Aama providers add <id> --base-url <url> [--channel <\u540D\u5B57>=<\u534F\u8BAE>@<\u5730\u5740> \u2026]\n                         [--api openai-completions|openai-responses|anthropic-messages|auto]\n                         [--key-env <VAR>] [--probe] [--limit N] [--probe-models a,b,\u2026]\n                         [--max-requests N] [--prefer chat,responses,messages]\n                         [--include-no-tools] [--yes]\n      ama providers list\n      ama providers channels <id>\n      ama providers remove <id>\n      ama providers refresh <id> [--probe] [--limit N] [--probe-models a,b,\u2026] [--max-requests N] [--yes]\n";
+export interface Ctx {
+    io: CliIo;
+    deps: Pick<RuntimeDeps, "providers">;
+    level: UserLevel;
+    values: ReadonlyMap<string, string>;
+    flags: ReadonlySet<string>;
+    channelSpecs: string[];
+}
+export declare function userConfig(level: UserLevel): AmaConfig;
+export declare function runProviders(argv: readonly string[], io: CliIo, deps: Pick<RuntimeDeps, "providers"> | undefined): Promise<number>;