@armadra/agent 0.0.0-stage → 0.3.0

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>;

package/dist/cli/subcommands/providers.js

@@ -0,0 +1,433 @@
+/**
+ * `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 { existsSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { withCustomDefaults } from "../../ai/providers/catalog.js";
+import { describeRefresh, refreshModelsDev } from "../../ai/providers/models-dev-cache.js";
+import { modelsDevFields } from "../../ai/providers/models-dev.js";
+import { materializeModel } from "../../ai/providers/registry.js";
+import { PROVIDER_ID_PATTERN, setAuthKey } from "../../config/auth-file.js";
+import { loadConfigFile } from "../../config/load.js";
+import { CONFIG_FILE_VERSION } from "../../config/types.js";
+import { writeConfigFile } from "../../config/write.js";
+import { parseSubArgs, UsageError } from "../args.js";
+import { ExitCode } from "../exit-codes.js";
+import { extractKey } from "./auth.js";
+import { listChannels, listProviders, removeProvider } from "./providers-list.js";
+import { buildRegistry, loadUserLevel } from "./context.js";
+import { attempt, DISCOVER_TIMEOUT_MS, FATAL_STATUS } from "./models-discover.js";
+import { DEFAULT_PREFER, capRequests, defaultChannels, hintedChannels, listingTarget, mergeProvider, orderChannels, parseChannelSpec, parseModelList, probeSelection, renderTable, } from "./providers-plan.js";
+export const DEFAULT_MAX_REQUESTS = 60;
+export const DEFAULT_LIMIT = 30;
+export const PROVIDERS_USAGE = `用法：ama providers add <id> --base-url <url> [--channel <名字>=<协议>@<地址> …]
+                         [--api openai-completions|openai-responses|anthropic-messages|auto]
+                         [--key-env <VAR>] [--probe] [--limit N] [--probe-models a,b,…]
+                         [--max-requests N] [--prefer chat,responses,messages]
+                         [--include-no-tools] [--yes]
+      ama providers list
+      ama providers channels <id>
+      ama providers remove <id>
+      ama providers refresh <id> [--probe] [--limit N] [--probe-models a,b,…] [--max-requests N] [--yes]
+`;
+const VALUE_OPTIONS = [
+    "base-url",
+    "api",
+    "key-env",
+    "limit",
+    "probe-models",
+    "max-requests",
+    "prefer",
+    "name",
+    "profile",
+    "auth-file",
+];
+const FLAG_OPTIONS = ["probe", "include-no-tools", "yes"];
+function intValue(ctx, name, fallback) {
+    const raw = ctx.values.get(name);
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1)
+        throw new UsageError(`--${name} 需要正整数：${raw}`);
+    return n;
+}
+function list(raw) {
+    return raw
+        ?.split(",")
+        .map((s) => s.trim())
+        .filter((s) => s !== "");
+}
+export function userConfig(level) {
+    return structuredClone(loadConfigFile("config", level.userConfigPath)?.value ?? { version: CONFIG_FILE_VERSION });
+}
+async function confirm(io, question) {
+    io.stderr(question);
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return /^y(es)?$/i.test((await rl.question("继续？[y/N] ")).trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+/** --yes / TTY 确认；非 TTY 且没有 --yes 返回 false 并提示（调用方退出 2）。 */
+async function approved(ctx, what) {
+    if (ctx.flags.has("yes"))
+        return true;
+    if (!ctx.io.stdinIsTTY) {
+        ctx.io.stderr(`ama: ${what}，非交互环境需加 --yes\n`);
+        return "usage";
+    }
+    return confirm(ctx.io, `${what}\n`);
+}
+/**
+ * `GET /models`。OpenAI 系带 `Authorization: Bearer`；Anthropic 形状的渠道先试 Bearer（中转多半只认它），
+ * 401 / 403 再试 `x-api-key` + `anthropic-version`（官方形状）。
+ */
+async function fetchModelList(target, apiKey) {
+    const get = (headers) => fetch(target.url, {
+        headers: { accept: "application/json", ...headers },
+        signal: AbortSignal.timeout(DISCOVER_TIMEOUT_MS),
+    });
+    let response = await get(apiKey !== undefined ? { authorization: `Bearer ${apiKey}` } : {});
+    if ((response.status === 401 || response.status === 403) &&
+        apiKey !== undefined &&
+        target.channel.api === "anthropic-messages")
+        response = await get({ "x-api-key": apiKey, "anthropic-version": "2023-06-01" });
+    if (!response.ok)
+        throw new Error(`HTTP ${response.status} ${target.url}`);
+    return parseModelList(await response.json());
+}
+function channelsOfConfig(config) {
+    if (config.channels !== undefined)
+        return Object.entries(config.channels).map(([name, c]) => ({
+            name,
+            api: c.api,
+            baseUrl: c.baseUrl,
+        }));
+    if (config.baseUrl === undefined)
+        return [];
+    const api = config.api ?? "openai-completions";
+    return [{ name: "default", api, baseUrl: config.baseUrl }];
+}
+/** 渠道的探测用供应商数据（key 由调用方传入）。 */
+function probeProvider(id, channel) {
+    return {
+        id,
+        name: id,
+        api: channel.api,
+        baseUrl: channel.baseUrl,
+        envKeys: [],
+        models: [],
+        requiresApiKey: true,
+        builtin: false,
+    };
+}
+/** 逐模型定渠道（含探测）；返回各模型的计划与是否因鉴权 / 限流提前停止。 */
+async function plan(ctx, input) {
+    const { io } = ctx;
+    const prefer = list(ctx.values.get("prefer")) ?? [...DEFAULT_PREFER];
+    const byId = new Map(input.listed.map((m) => [m.id, m]));
+    const fresh = input.listed.filter((m) => !input.existingIds.has(m.id));
+    const hint = (id) => {
+        const listed = byId.get(id);
+        return listed !== undefined ? hintedChannels(listed, input.candidates) : undefined;
+    };
+    const tryChannels = (id) => orderChannels(hint(id) ?? input.candidates.map((c) => c.name), prefer);
+    const probeable = (id) => tryChannels(id).length > 0;
+    const results = new Map();
+    let stopped;
+    if (input.probe) {
+        const only = list(ctx.values.get("probe-models"));
+        const selected = probeSelection(fresh.map((m) => m.id).filter(probeable), intValue(ctx, "limit", DEFAULT_LIMIT), only);
+        const max = intValue(ctx, "max-requests", DEFAULT_MAX_REQUESTS);
+        const capped = capRequests(selected, tryChannels, max);
+        io.stdout(`\n探测：${capped.ids.length} 个模型、${capped.requests} 次最小请求（每模型每渠道 1 次，上限 ${max}）` +
+            `${capped.dropped > 0 ? `；另有 ${capped.dropped} 个超出上限未探测` : ""}\n`);
+        const ok = await approved(ctx, `将发 ${capped.requests} 次计费请求并写入 ${ctx.level.userConfigPath}`);
+        if (ok === "usage")
+            return { plans: [], cancelled: ExitCode.Usage };
+        if (!ok)
+            return { plans: [], cancelled: ExitCode.Ok };
+        outer: for (const id of capped.ids) {
+            const result = { ok: [] };
+            const failed = [];
+            results.set(id, result);
+            for (const name of tryChannels(id)) {
+                const channel = input.candidates.find((c) => c.name === name);
+                const provider = probeProvider(input.id, channel);
+                const model = materializeModel(withCustomDefaults({ id }, input.id, channel.api), provider);
+                const error = await attempt(input.registry, model, input.apiKey);
+                if (error === undefined)
+                    result.ok.push(name);
+                else {
+                    result.error = error.split("\n")[0]?.slice(0, 120) ?? error;
+                    failed.push(`${name}：${result.error}`);
+                    if (FATAL_STATUS.test(error)) {
+                        stopped = error;
+                        break outer;
+                    }
+                }
+            }
+            io.stdout(`  ${id}  ${result.ok.length > 0 ? result.ok.join(", ") : "全部失败"}` +
+                `${failed.length > 0 ? `（失败 ${failed.join("；")}）` : ""}\n`);
+        }
+    }
+    const includeNoTools = ctx.flags.has("include-no-tools");
+    const plans = input.listed.map((listed) => {
+        const match = input.index?.match(listed.id);
+        const fields = match !== undefined ? modelsDevFields(match.model) : {};
+        const base = { id: listed.id, fields, match };
+        if (input.existingIds.has(listed.id))
+            return { ...base, channels: [], status: "existing" };
+        const probed = results.get(listed.id);
+        if (probed !== undefined) {
+            if (probed.ok.length === 0)
+                return {
+                    ...base,
+                    channels: [],
+                    status: "failed",
+                    ...(probed.error ? { error: probed.error } : {}),
+                };
+            return { ...base, channels: orderChannels(probed.ok, prefer), status: "ok" };
+        }
+        const hinted = hint(listed.id);
+        if (hinted !== undefined && hinted.length === 0)
+            return { ...base, channels: [], status: "no-channel" };
+        const channels = hinted !== undefined
+            ? orderChannels(hinted, prefer)
+            : orderChannels(input.candidates.map((c) => c.name), prefer).slice(0, 1);
+        if (fields.toolCall === false && !includeNoTools)
+            return { ...base, channels, status: "no-tools" };
+        return { ...base, channels, status: "unprobed" };
+    });
+    for (const p of plans)
+        if (p.status === "ok" && p.fields.toolCall === false && !includeNoTools)
+            p.status = "no-tools";
+    return { plans, ...(stopped !== undefined ? { stopped } : {}) };
+}
+async function obtainKey(ctx, id, registry) {
+    const keyEnv = ctx.values.get("key-env");
+    if (keyEnv !== undefined) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(keyEnv))
+            throw new UsageError(`--key-env 不是合法的变量名：${keyEnv}`);
+        const value = ctx.io.env[keyEnv]?.trim();
+        if (!value)
+            ctx.io.stderr(`ama: 警告：环境变量 ${keyEnv} 未设置，列模型与探测将不带 key\n`);
+        return { apiKey: value || undefined, configValue: `$${keyEnv}` };
+    }
+    if (registry.get(id) !== undefined) {
+        const existing = await registry.resolveApiKey(id);
+        if (existing.apiKey !== undefined)
+            return { apiKey: existing.apiKey };
+    }
+    if (ctx.io.stdinIsTTY)
+        ctx.io.stderr(`输入 ${id} 的 API key（不回显），回车结束：`);
+    const key = extractKey(await ctx.io.readStdin());
+    if (ctx.io.stdinIsTTY)
+        ctx.io.stderr("\n");
+    if (key === "")
+        throw new UsageError("没有从 stdin 读到 key（或用 --key-env <VAR>）");
+    return { apiKey: key, store: key };
+}
+async function add(ctx, id, refresh) {
+    const { io, level } = ctx;
+    if (!PROVIDER_ID_PATTERN.test(id) || id.includes("@"))
+        throw new UsageError(`供应商 id 不合法：${id}`);
+    const config = userConfig(level);
+    const existing = config.providers?.[id];
+    if (refresh && existing === undefined) {
+        io.stderr(`ama: ${level.userConfigPath} 里没有供应商 ${id}（先 ama providers add）\n`);
+        return ExitCode.Usage;
+    }
+    const registry = await buildRegistry(level, io, ctx.deps);
+    let candidates;
+    if (refresh)
+        candidates = channelsOfConfig(existing);
+    else if (ctx.channelSpecs.length > 0)
+        candidates = ctx.channelSpecs.map(parseChannelSpec);
+    else {
+        const baseUrl = ctx.values.get("base-url");
+        if (baseUrl === undefined)
+            throw new UsageError("ama providers add 需要 --base-url <url> 或 --channel");
+        if (!/^https?:\/\//.test(baseUrl))
+            throw new UsageError(`--base-url 应为 http(s) URL：${baseUrl}`);
+        candidates = defaultChannels(baseUrl, ctx.values.get("api"));
+    }
+    const target = listingTarget(candidates);
+    if (target === undefined)
+        throw new UsageError(`${id} 没有可用的渠道`);
+    const key = await obtainKey(ctx, id, registry);
+    let listed;
+    try {
+        listed = await fetchModelList(target, key.apiKey);
+    }
+    catch (error) {
+        io.stderr(`ama: ${id} 模型列表获取失败：${error.message}\n`);
+        return ExitCode.RuntimeError;
+    }
+    io.stdout(`${id}：发现 ${listed.length} 个模型（${target.url}）\n`);
+    const md = await refreshModelsDev({ dataDir: level.dataDir, env: io.env, force: refresh });
+    io.stdout(`${describeRefresh(md)}\n`);
+    if (md.warning !== undefined)
+        io.stderr(`ama: 警告：${md.warning}\n`);
+    io.stdout(`候选渠道：${candidates.map((c) => `${c.name}（${c.api} ${c.baseUrl}）`).join(" · ")}\n`);
+    const existingIds = new Set((existing?.models ?? []).map((m) => m.id));
+    const result = await plan(ctx, {
+        id,
+        candidates,
+        listed,
+        index: md.index,
+        existingIds,
+        apiKey: key.apiKey,
+        registry,
+        probe: ctx.flags.has("probe"),
+    });
+    if (result.cancelled !== undefined)
+        return result.cancelled;
+    io.stdout(`\n${renderTable(result.plans)}`);
+    if (refresh) {
+        const gone = [...existingIds].filter((m) => !listed.some((l) => l.id === m));
+        if (gone.length > 0)
+            io.stdout(`上游已不再列出（未删除）：${gone.join(", ")}\n`);
+    }
+    const writable = result.plans.filter((p) => p.status === "ok" || p.status === "unprobed");
+    const legacy = existing !== undefined && existing.channels === undefined;
+    const merged = legacy && refresh
+        ? legacyMerge(existing, writable.map((p) => p.id))
+        : mergeProvider(legacy ? asChannels(existing) : existing, {
+            ...(ctx.values.get("name") !== undefined
+                ? { name: ctx.values.get("name") }
+                : {}),
+            ...(key.configValue !== undefined ? { apiKey: key.configValue } : {}),
+            channels: candidates,
+            models: writable,
+            prefer: list(ctx.values.get("prefer")) ?? [...DEFAULT_PREFER],
+        });
+    const keyNote = key.store !== undefined ? `；key → ${level.authFile}（0600）` : "";
+    const summary = `\n将写入 ${level.userConfigPath}：${id} 新增渠道 ${merged.addedChannels.join(", ") || "无"}，` +
+        `新增模型 ${merged.addedModels.length} 个${keyNote}`;
+    io.stdout(`${summary}\n`);
+    if (merged.addedModels.length === 0 &&
+        merged.addedChannels.length === 0 &&
+        key.store === undefined) {
+        io.stdout("没有要写入的内容\n");
+        return result.stopped !== undefined ? ExitCode.RuntimeError : ExitCode.Ok;
+    }
+    if (!ctx.flags.has("probe")) {
+        const ok = await approved(ctx, "确认写入");
+        if (ok === "usage")
+            return ExitCode.Usage;
+        if (!ok) {
+            io.stderr("ama: 已取消\n");
+            return ExitCode.Ok;
+        }
+    }
+    const providers = (config.providers ??= {});
+    providers[id] = merged.config;
+    const backup = existsSync(level.userConfigPath);
+    writeConfigFile(level.userConfigPath, config, { backup: true });
+    if (key.store !== undefined)
+        setAuthKey(level.authFile, id, key.store);
+    io.stdout(`已写入 ${level.userConfigPath}${backup ? "（原文件备份为 config.json.bak）" : ""}\n`);
+    const sample = result.plans.find((p) => p.status === "ok" && merged.addedModels.includes(p.id))?.id ??
+        merged.addedModels[0];
+    if (sample !== undefined)
+        io.stdout(`试试：ama -p "hi" --model ${id}/${sample}\n`);
+    if (result.stopped !== undefined) {
+        io.stderr(`ama: 探测提前停止（${result.stopped}）\n`);
+        return ExitCode.RuntimeError;
+    }
+    return ExitCode.Ok;
+}
+/** 旧写法（无 channels）的供应商：先把供应商级 api + baseUrl 变成 `default` 渠道。 */
+function asChannels(config) {
+    const { api, baseUrl, ...rest } = structuredClone(config);
+    if (baseUrl === undefined)
+        return rest;
+    return {
+        ...rest,
+        channels: { default: { api: api ?? "openai-completions", baseUrl } },
+        defaultChannel: "default",
+    };
+}
+/** 旧写法供应商的 refresh：只追加 `{ id }`。 */
+function legacyMerge(config, ids) {
+    const next = structuredClone(config);
+    const models = (next.models ??= []);
+    const known = new Set(models.map((m) => m.id));
+    const addedModels = ids.filter((id) => !known.has(id));
+    for (const id of addedModels)
+        models.push({ id });
+    return { config: next, addedChannels: [], addedModels };
+}
+/** `--channel` 可重复：先从 argv 里取出来，其余交给 parseSubArgs。 */
+function takeChannels(argv) {
+    const rest = [];
+    const specs = [];
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i] ?? "";
+        if (token === "--channel") {
+            const value = argv[++i];
+            if (value === undefined || value === "")
+                throw new UsageError("--channel 需要一个值");
+            specs.push(value);
+        }
+        else if (token.startsWith("--channel="))
+            specs.push(token.slice("--channel=".length));
+        else
+            rest.push(token);
+    }
+    return { rest, specs };
+}
+export async function runProviders(argv, io, deps) {
+    const { rest, specs } = takeChannels(argv);
+    const { positionals, values, flags } = parseSubArgs(rest, VALUE_OPTIONS, FLAG_OPTIONS);
+    const action = positionals[0];
+    if (flags.has("help") || action === undefined) {
+        io.stdout(PROVIDERS_USAGE);
+        return flags.has("help") ? ExitCode.Ok : ExitCode.Usage;
+    }
+    if (deps === undefined) {
+        io.stderr("ama: providers 尚未装配（供应商注册表由集成批次注入）\n");
+        return ExitCode.RuntimeError;
+    }
+    const level = loadUserLevel(io, {
+        profile: values.get("profile"),
+        authFile: values.get("auth-file"),
+    });
+    for (const warning of level.warnings)
+        io.stderr(`ama: 警告：${warning}\n`);
+    const ctx = { io, deps, level, values, flags, channelSpecs: specs };
+    const target = positionals[1];
+    const need = () => {
+        if (target === undefined)
+            throw new UsageError(`ama providers ${action} 需要 <id>`);
+        if (positionals.length > 2)
+            throw new UsageError(`多余的参数：${positionals.slice(2).join(" ")}`);
+        return target;
+    };
+    switch (action) {
+        case "add":
+            return add(ctx, need(), false);
+        case "refresh":
+            return add(ctx, need(), true);
+        case "list":
+            return listProviders(ctx);
+        case "channels":
+            return listChannels(ctx, need());
+        case "remove":
+            return removeProvider(ctx, need());
+        default:
+            throw new UsageError(`未知的 providers 子命令：${action}`);
+    }
+}