@armadra/agent 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,232 @@
+/**
+ * `ama models discover <provider>`（第三波 §2.3）：问中转站有哪些模型。[W3-B12]
+ *
+ * GET `{baseUrl}/models`（anthropic-messages 且 baseUrl 不以 `/v1` 结尾时为 `{baseUrl}/v1/models`），
+ * 带供应商的鉴权头，打印 id 列表并标出已配置的条目。
+ *
+ * `--probe`：同一中转下不同模型支持的协议不同，对每个 id 依次试供应商协议 → completions →
+ * responses → messages（去重），各发一次最小请求（`ama models check` 同款，maxTokens 16），
+ * 记第一个成功的协议；每模型最多 3 次请求，`--limit`（缺省 30）限制探测的模型数，执行前打印
+ * 预估；401 / 403 / 429 立即停止（key 无效或被限流，继续只会浪费请求）。
+ *
+ * `--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;
+const ANTHROPIC_VERSION = "2023-06-01";
+/** 中转常见的三种协议，按此顺序探测（供应商协议排最前）。 */
+export const PROBE_APIS = [
+    "openai-completions",
+    "openai-responses",
+    "anthropic-messages",
+];
+/** 模型列表的 URL：OpenAI 系是 `{baseUrl}/models`；Anthropic 官方形状的 baseUrl 不带 `/v1`。 */
+export function modelsUrl(provider) {
+    const base = provider.baseUrl.replace(/\/+$/, "");
+    if (provider.api === "anthropic-messages" && !/\/v1$/.test(base))
+        return `${base}/v1/models`;
+    return `${base}/models`;
+}
+export async function discoverModels(provider, apiKey, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DISCOVER_TIMEOUT_MS;
+    if (!provider.requiresApiKey && apiKey === undefined)
+        return discoverLocalModels(provider, { timeoutMs });
+    const anthropic = provider.api === "anthropic-messages";
+    const headers = mergeHeaders(provider.headers, anthropic ? { "anthropic-version": ANTHROPIC_VERSION } : {}, authHeaders(apiKey, provider.authHeader, anthropic ? "x-api-key" : "authorization-bearer"));
+    return discoverLocalModels(provider, { timeoutMs, url: modelsUrl(provider), headers });
+}
+export function probeOrder(provider) {
+    return PROBE_APIS.includes(provider.api)
+        ? [provider.api, ...PROBE_APIS.filter((api) => api !== provider.api)]
+        : [...PROBE_APIS];
+}
+export const FATAL_STATUS = /^(?:HTTP )?(?:401|403|429)\b/;
+/** 返回已探测模型 → 第一个成功的协议（都失败为 undefined）；超出 `limit` 或提前停止的不在表里。 */
+export async function probeModelApis(registry, provider, ids, limit, options = {}) {
+    const result = new Map();
+    const key = await registry.resolveApiKey(provider.id);
+    const order = probeOrder(provider).filter((api) => registry.getApi(api) !== undefined);
+    for (const id of ids.slice(0, Math.max(0, limit))) {
+        const known = provider.models.find((m) => m.id === id);
+        let found;
+        for (const api of order) {
+            const model = known !== undefined
+                ? { ...known, api }
+                : materializeModel(withCustomDefaults({ id }, provider.id, api), provider);
+            const error = await attempt(registry, model, key.apiKey, options.timeoutMs);
+            options.onAttempt?.(id, api, error);
+            if (error === undefined) {
+                found = api;
+                break;
+            }
+            if (FATAL_STATUS.test(error)) {
+                options.onStop?.(error);
+                return result;
+            }
+        }
+        result.set(id, found);
+        options.onResult?.(id, found);
+    }
+    return result;
+}
+/** 一次最小请求；成功返回 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} 尚未实现`;
+    try {
+        const message = await impl
+            .stream(model, { messages: [{ role: "user", content: "Reply with: ok", timestamp: Date.now() }] }, {
+            signal: AbortSignal.timeout(timeoutMs),
+            ...(apiKey !== undefined ? { apiKey } : {}),
+            maxTokens: 16,
+            cacheRetention: "none",
+        })
+            .result();
+        if (message.stopReason === "error" || message.stopReason === "aborted")
+            return message.errorMessage ?? message.stopReason;
+        return undefined;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+function parseLimit(raw) {
+    if (raw === undefined)
+        return DEFAULT_PROBE_LIMIT;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1)
+        throw new UsageError(`--limit 需要正整数：${raw}`);
+    return n;
+}
+/** 把新条目合并进用户级 config.json；返回写入条数。 */
+function writeEntries(ctx, provider, entries, notes) {
+    const { io } = ctx;
+    const path = ctx.level.userConfigPath;
+    const config = structuredClone(loadConfigFile("config", path)?.value ?? { version: 1 });
+    const providers = (config.providers ??= {});
+    if (providers[provider.id] === undefined && !provider.builtin) {
+        io.stderr(`ama: ${provider.id} 不在用户级配置（${path}）里，未写入\n`);
+        return 0;
+    }
+    const target = (providers[provider.id] ??= {});
+    const models = (target.models ??= []);
+    const existing = new Set([...models.map((m) => m.id), ...provider.models.map((m) => m.id)]);
+    const added = entries.filter((entry) => !existing.has(entry.id));
+    const kept = entries.length - added.length;
+    if (added.length === 0) {
+        io.stdout(`\n没有新模型要写入${kept > 0 ? `（${kept} 个已存在，未覆盖）` : ""}\n`);
+        return 0;
+    }
+    models.push(...added);
+    const backup = existsSync(path);
+    writeConfigFile(path, config, { backup: true });
+    io.stdout(`\n已写入 ${path}：${provider.id} 新增 ${added.length} 个模型` +
+        `${kept > 0 ? `，${kept} 个已存在未覆盖` : ""}${backup ? `（原文件备份为 ${path}.bak）` : ""}\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) {
+    const { io, registry } = ctx;
+    const id = ctx.args[0] ?? "";
+    const limit = parseLimit(ctx.values.get("limit"));
+    const provider = registry.get(id);
+    if (provider === undefined) {
+        io.stderr(`ama: 供应商不存在：${id}\n`);
+        return ExitCode.NoModel;
+    }
+    const key = await registry.resolveApiKey(provider.id);
+    if (key.apiKey === undefined && provider.requiresApiKey) {
+        io.stderr(`ama: ${provider.id} 没有 API key（ama auth set ${provider.id}）\n`);
+        return ExitCode.NoModel;
+    }
+    let found;
+    try {
+        found = await discoverModels(provider, key.apiKey);
+    }
+    catch (error) {
+        io.stderr(`ama: ${provider.id} 模型列表获取失败：${error.message}\n`);
+        return ExitCode.RuntimeError;
+    }
+    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);
+        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.filter((m) => !noTools.has(m.id)).map((m) => ({ id: m.id })), { noTools, unmatched });
+        return ExitCode.Ok;
+    }
+    const ids = found.map((m) => m.id);
+    const count = Math.min(limit, ids.length);
+    const order = probeOrder(provider);
+    io.stdout(`\n探测协议：${count} 个模型（${order.join(" → ")}），最多 ${count * order.length} 次请求` +
+        `${ids.length > count ? `；另有 ${ids.length - count} 个超出 --limit ${limit}，未探测` : ""}\n`);
+    let stopped;
+    const probed = await probeModelApis(registry, provider, ids, limit, {
+        onResult: (modelId, api) => io.stdout(`  ${modelId}  ${api ?? "不可用（三种协议均失败）"}\n`),
+        onStop: (reason) => (stopped = reason),
+    });
+    if (write) {
+        const entries = [];
+        for (const [modelId, api] of probed) {
+            if (api !== undefined && !noTools.has(modelId))
+                entries.push(api === provider.api ? { id: modelId } : { id: modelId, api });
+        }
+        writeEntries(ctx, provider, entries, { noTools, unmatched });
+    }
+    if (stopped !== undefined) {
+        io.stderr(`ama: 探测提前停止（${stopped}）\n`);
+        return ExitCode.RuntimeError;
+    }
+    return ExitCode.Ok;
+}
+export const DISCOVER_ACTION = {
+    usage: "ama models discover <provider> [--probe] [--write] [--limit <n>]",
+    required: "<provider>",
+    valueOptions: ["limit"],
+    flagOptions: ["probe", "write"],
+    run,
+};

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

@@ -0,0 +1,40 @@
+/**
+ * `ama models list [--provider <id>]`、`ama models check <provider/id>`（设计 §1.2、R6）。[B5]
+ *
+ * 注册表经 RuntimeDeps.providers 注入（B1）。check 发一次最小调用（一条 user 消息、
+ * maxTokens 16、超时 30 s），只报告成败与 stopReason，不输出 key。
+ *
+ * [W3-C0] 子命令分派改为动作表 `MODELS_ACTIONS`（第三波 §1.11 / §2.3）：新动作（C2 的
+ * `cache-probe`、B12 的 `discover`）各写在自己的文件里，这里只加一行表项；用法文本、
+ * 选项表与必填位置参数都从表里来。
+ */
+import type { ProviderRegistryApi } from "../../ai/types.js";
+import type { CliIo, RuntimeDeps } from "../deps.js";
+import { type UserLevel } from "./context.js";
+/** 动作执行时拿到的上下文（参数已按表解析、注册表已构造）。 */
+export interface ModelsActionContext {
+    io: CliIo;
+    registry: ProviderRegistryApi;
+    /** 用户级（+ profile）配置；写配置的动作（`discover --write`）要用 `userConfigPath`。 */
+    level: UserLevel;
+    /** 动作名之后的位置参数。 */
+    args: readonly string[];
+    values: ReadonlyMap<string, string>;
+    flags: ReadonlySet<string>;
+}
+export interface ModelsAction {
+    /** 用法行（不含「ama models 」前缀之前的「用法：」）。 */
+    usage: string;
+    /** 带值选项（不含共用的 --profile / --auth-file）。 */
+    valueOptions?: readonly string[];
+    /** 布尔选项。 */
+    flagOptions?: readonly string[];
+    /** 必填的第一个位置参数，缺失时报「ama models <动作> 需要 <required>」。 */
+    required?: string;
+    run(ctx: ModelsActionContext): Promise<number>;
+}
+export declare const CHECK_TIMEOUT_MS = 30000;
+/** 动作表：键是子命令名，顺序即用法文本顺序。 */
+export declare const MODELS_ACTIONS: Readonly<Record<string, ModelsAction>>;
+export declare const MODELS_USAGE: string;
+export declare function runModels(argv: readonly string[], io: CliIo, deps: Pick<RuntimeDeps, "providers"> | undefined): Promise<number>;

package/dist/cli/subcommands/models.js

@@ -0,0 +1,152 @@
+/**
+ * `ama models list [--provider <id>]`、`ama models check <provider/id>`（设计 §1.2、R6）。[B5]
+ *
+ * 注册表经 RuntimeDeps.providers 注入（B1）。check 发一次最小调用（一条 user 消息、
+ * maxTokens 16、超时 30 s），只报告成败与 stopReason，不输出 key。
+ *
+ * [W3-C0] 子命令分派改为动作表 `MODELS_ACTIONS`（第三波 §1.11 / §2.3）：新动作（C2 的
+ * `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;
+async function list(io, registry, only) {
+    const providers = registry.list().filter((p) => only === undefined || p.id === only);
+    if (only !== undefined && providers.length === 0) {
+        io.stderr(`ama: 供应商不存在：${only}\n`);
+        return ExitCode.NoModel;
+    }
+    for (const provider of providers) {
+        const key = await registry.resolveApiKey(provider.id);
+        const keyText = key.apiKey !== undefined
+            ? `key：${key.source}${key.origin !== undefined ? `（${key.origin}）` : ""}`
+            : provider.requiresApiKey
+                ? "无 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) {
+            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;
+}
+async function check(io, registry, ref) {
+    const found = registry.findModel(ref);
+    if (!found.ok) {
+        const hint = found.candidates.length > 0 ? `；候选：${found.candidates.slice(0, 10).join(", ")}` : "";
+        io.stderr(`ama: 模型不存在：${ref}${hint}\n`);
+        return ExitCode.NoModel;
+    }
+    const { model, provider } = found;
+    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;
+    }
+    const api = registry.getApi(model.api);
+    if (api === undefined) {
+        io.stderr(`ama: 协议 ${model.api} 尚未实现\n`);
+        return ExitCode.RuntimeError;
+    }
+    const started = Date.now();
+    const stream = api.stream(model, { messages: [{ role: "user", content: "Reply with: ok", timestamp: Date.now() }] }, {
+        signal: AbortSignal.timeout(CHECK_TIMEOUT_MS),
+        ...(key.apiKey !== undefined ? { apiKey: key.apiKey } : {}),
+        maxTokens: 16,
+        cacheRetention: "none",
+    });
+    const message = await stream.result();
+    const ms = Date.now() - started;
+    if (message.stopReason === "error" || message.stopReason === "aborted") {
+        io.stderr(`ama: ${provider.id}/${model.id} 失败（${ms} ms）：${message.errorMessage ?? message.stopReason}\n`);
+        return ExitCode.RuntimeError;
+    }
+    const shown = formatModelRef(modelRefOf(model));
+    io.stdout(`${shown} 可用（${model.api}，${ms} ms，stopReason ${message.stopReason}）\n`);
+    return ExitCode.Ok;
+}
+/** 动作表：键是子命令名，顺序即用法文本顺序。 */
+export const MODELS_ACTIONS = Object.freeze({
+    list: {
+        usage: "ama models list [--provider <id>]",
+        valueOptions: ["provider"],
+        run: (ctx) => list(ctx.io, ctx.registry, ctx.values.get("provider")),
+    },
+    check: {
+        usage: "ama models check <provider/id>",
+        required: "<provider/id>",
+        run: (ctx) => check(ctx.io, ctx.registry, ctx.args[0] ?? ""),
+    },
+    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)
+    .join("\n      ")}\n`;
+function unique(lists) {
+    return [...new Set(lists.flatMap((l) => l ?? []))];
+}
+export async function runModels(argv, io, deps) {
+    const actions = Object.values(MODELS_ACTIONS);
+    const { positionals, values, flags } = parseSubArgs(argv, unique([...actions.map((a) => a.valueOptions), COMMON_VALUE_OPTIONS]), unique(actions.map((a) => a.flagOptions)));
+    const name = positionals[0];
+    if (flags.has("help") || name === undefined) {
+        io.stdout(MODELS_USAGE);
+        return flags.has("help") ? ExitCode.Ok : ExitCode.Usage;
+    }
+    const action = Object.hasOwn(MODELS_ACTIONS, name) ? MODELS_ACTIONS[name] : undefined;
+    if (action === undefined)
+        throw new UsageError(`未知的 models 子命令：${name}`);
+    // 选项按全部动作的并集解析；这里再拒绝不属于本动作的（如 `list --json`）。
+    for (const option of [...values.keys(), ...flags]) {
+        const own = [
+            ...COMMON_VALUE_OPTIONS,
+            ...(action.valueOptions ?? []),
+            ...(action.flagOptions ?? []),
+        ];
+        if (!own.includes(option))
+            throw new UsageError(`未知选项：--${option}`);
+    }
+    const args = positionals.slice(1);
+    if (action.required !== undefined && args[0] === undefined)
+        throw new UsageError(`ama models ${name} 需要 ${action.required}`);
+    if (deps === undefined) {
+        io.stderr("ama: models 尚未装配（供应商注册表由集成批次注入）\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 registry = await buildRegistry(level, io, deps);
+    return action.run({ io, registry, level, args, values, flags });
+}

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;