@armadra/agent 0.2.1 → 0.4.0

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

@@ -5,24 +5,31 @@
  * 带供应商的鉴权头，打印 id 列表并标出已配置的条目。
  *
  * `--probe`：同一中转下不同模型支持的协议不同，对每个 id 依次试供应商协议 → completions →
- * responses → messages（去重），各发一次最小请求（`ama models check` 同款，maxTokens 16），
- * 记第一个成功的协议；每模型最多 3 次请求，`--limit`（缺省 30）限制探测的模型数，执行前打印
- * 预估；401 / 403 / 429 立即停止（key 无效或被限流，继续只会浪费请求）。
+ * responses → messages（去重），各发一次最小请求（maxTokens 16，见到首个流事件即判可用并断开），
+ * 记第一个成功的协议；模型之间并发（`--concurrency`，缺省 6），单次超时 `--probe-timeout`（缺省
+ * 15 s）。每模型最多 3 次请求，`--limit`（缺省 30）限制探测的模型数，执行前打印预估；401 / 403 立即
+ * 停止，429 降并发并重试一次、仍 429 停止（见 probe-runner.ts）。
  *
  * `--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";
+import { describeProbePlan, parseProbeTuning, ProbeProgress, ProbeScheduler, } from "./probe-runner.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";
 /** 中转常见的三种协议，按此顺序探测（供应商协议排最前）。 */
@@ -51,57 +58,57 @@ export function probeOrder(provider) {
         ? [provider.api, ...PROBE_APIS.filter((api) => api !== provider.api)]
         : [...PROBE_APIS];
 }
-const FATAL_STATUS = /^(?:HTTP )?(?:401|403|429)\b/;
-/** 返回已探测模型 → 第一个成功的协议（都失败为 undefined）；超出 `limit` 或提前停止的不在表里。 */
+/**
+ * 返回已探测模型 → 第一个成功的协议（都失败为 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 selected = ids.slice(0, Math.max(0, limit));
+    const scheduler = new ProbeScheduler(registry, key.apiKey, {
+        concurrency: options.concurrency,
+        timeoutMs: options.timeoutMs,
+        retryDelayMs: options.retryDelayMs,
+    });
+    const done = [];
+    let printed = 0;
+    await scheduler.run(selected.length, async (index) => {
+        const id = selected[index];
         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;
+            const outcome = await scheduler.probe(model);
+            if (outcome.aborted)
+                return { complete: false, api: undefined };
+            options.onAttempt?.(id, api, outcome.error);
+            if (outcome.error === undefined)
+                return { complete: true, api };
+            if (scheduler.stopped !== undefined)
+                return { complete: false, api: undefined };
+        }
+        return { complete: true, api: undefined };
+    }, (index, found) => {
+        done[index] = found;
+        options.onSettled?.();
+        // 按模型顺序交出结果：前面的都完成了才输出
+        while (printed < selected.length && done[printed] !== undefined) {
+            const entry = done[printed];
+            const id = selected[printed];
+            if (entry.complete) {
+                result.set(id, entry.api);
+                options.onResult?.(id, entry.api);
             }
+            printed++;
         }
-        result.set(id, found);
-        options.onResult?.(id, found);
-    }
+    });
+    if (scheduler.stopped !== undefined)
+        options.onStop?.(scheduler.stopped);
     return result;
 }
-/** 一次最小请求；成功返回 undefined，失败返回错误文本。 */
-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;
@@ -111,7 +118,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 +141,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,33 +173,56 @@ 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);
     const count = Math.min(limit, ids.length);
     const order = probeOrder(provider);
+    const tuning = parseProbeTuning(ctx.values);
     io.stdout(`\n探测协议：${count} 个模型（${order.join(" → ")}），最多 ${count * order.length} 次请求` +
-        `${ids.length > count ? `；另有 ${ids.length - count} 个超出 --limit ${limit}，未探测` : ""}\n`);
+        `${ids.length > count ? `；另有 ${ids.length - count} 个超出 --limit ${limit}，未探测` : ""}\n` +
+        `${describeProbePlan(count * order.length, tuning.concurrency, tuning.timeoutMs)}\n`);
     let stopped;
+    const progress = new ProbeProgress(io.stdout, io.stdoutIsTTY, count);
     const probed = await probeModelApis(registry, provider, ids, limit, {
-        onResult: (modelId, api) => io.stdout(`  ${modelId}  ${api ?? "不可用（三种协议均失败）"}\n`),
+        ...tuning,
+        onSettled: () => progress.tick(),
+        onResult: (modelId, api) => progress.line(`  ${modelId}  ${api ?? "不可用（三种协议均失败）"}\n`),
         onStop: (reason) => (stopped = reason),
     });
+    progress.finish();
     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`);
@@ -196,9 +231,9 @@ async function run(ctx) {
     return ExitCode.Ok;
 }
 export const DISCOVER_ACTION = {
-    usage: "ama models discover <provider> [--probe] [--write] [--limit <n>]",
+    usage: "ama models discover <provider> [--probe] [--write] [--limit <n>] [--concurrency <n>] [--probe-timeout <ms>]",
     required: "<provider>",
-    valueOptions: ["limit"],
+    valueOptions: ["limit", "concurrency", "probe-timeout"],
     flagOptions: ["probe", "write"],
     run,
 };

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/probe-runner.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 探测的执行层（`ama providers add|refresh --probe`、`ama models discover --probe` 共用）。
+ *
+ * - **首事件即判定**：HTTP 成功、流里出现第一个内容事件（text / thinking / toolcall）或 done 即判可用，
+ *   立刻中止请求；只见到 `start`（推理模型可能要想很久才出第一个 delta）时再等 `settleMs`，期间没有
+ *   error 事件也判可用——防止中转先回 200、紧接着在流里报错被误判。HTTP 错误、流 error 事件、超时判不可用。
+ * - **有界并发**：同时在途 ≤ `concurrency`；结果按任务下标交回，调用方自己按顺序输出。
+ * - **限流**：429 时并发减半（至少 1），等 `retryDelayMs` 后重试该请求一次；重试仍 429 → 停止；
+ *   401 / 403 → 立即停止。停止后不再发新请求，并中止在途的请求（它们的结果标记为 aborted）。
+ * - **恢复（加法增、乘法减）**：降并发之后，每连续 `recoverAfter`（缺省 4）次没被限流的请求，并发 +1，
+ *   直到回到初始并发；中途再遇 429 重新减半、计数清零。
+ *
+ * `ama models check` 不走这里：它只发一次，要看到完整回复与耗时。
+ */
+import type { Model, ProviderRegistryApi } from "../../ai/types.js";
+export declare const PROBE_TIMEOUT_MS = 15000;
+export declare const DEFAULT_PROBE_CONCURRENCY = 6;
+export declare const MAX_PROBE_CONCURRENCY = 16;
+export declare const PROBE_SETTLE_MS = 1000;
+export declare const RATE_LIMIT_RETRY_MS = 2000;
+/** 降并发后，连续多少次没被限流才 +1。 */
+export declare const RECOVER_AFTER = 4;
+/** 鉴权失败或限流：继续只会浪费请求。 */
+export declare const FATAL_STATUS: RegExp;
+export interface ProbeTuning {
+    timeoutMs?: number | undefined;
+    settleMs?: number | undefined;
+}
+/** 一次探测请求的结果：error 为 undefined 即可用；aborted 表示被调度方中止，结果作废。 */
+export interface ProbeOutcome {
+    error?: string;
+    aborted?: boolean;
+}
+/** 发一次最小请求，见到首个有效事件即判定并中止。 */
+export declare function probeOnce(registry: ProviderRegistryApi, model: Model, apiKey: string | undefined, tuning?: ProbeTuning, signal?: AbortSignal): Promise<ProbeOutcome>;
+export interface SchedulerOptions extends ProbeTuning {
+    concurrency?: number | undefined;
+    retryDelayMs?: number | undefined;
+    /** 429 降并发时回调（新的并发数）。 */
+    onThrottle?: (concurrency: number) => void;
+    /** 连续多少次没被限流后并发 +1（缺省 RECOVER_AFTER）。 */
+    recoverAfter?: number | undefined;
+    /** 并发回升时回调（新的并发数）。 */
+    onRecover?: (concurrency: number) => void;
+}
+/**
+ * 有界并发的探测调度器：`run` 按下标调度任务，任务里用 `probe` 发请求（带 429 重试与停止判定）。
+ */
+export declare class ProbeScheduler {
+    private readonly registry;
+    private readonly apiKey;
+    private readonly options;
+    private limit;
+    private readonly initial;
+    /** 上次降并发以来连续没被限流的请求数。 */
+    private streak;
+    private readonly controller;
+    private stopReason;
+    private active;
+    /** 观测用：同时在途请求数的峰值。 */
+    peak: number;
+    constructor(registry: ProviderRegistryApi, apiKey: string | undefined, options?: SchedulerOptions);
+    get stopped(): string | undefined;
+    get concurrency(): number;
+    stop(reason: string): void;
+    /** 一次探测；429 降并发、退避后重试一次，仍 429 或 401 / 403 → 停止。 */
+    probe(model: Model): Promise<ProbeOutcome>;
+    /** 一次没被限流的请求：攒够 recoverAfter 次就并发 +1（不超过初始值）。 */
+    private recover;
+    /** 并发执行 `count` 个任务；`onDone` 按完成顺序回调。停止后未开始的任务不执行（结果为 undefined）。 */
+    run<T>(count: number, task: (index: number) => Promise<T>, onDone?: (index: number, result: T) => void): Promise<(T | undefined)[]>;
+    private get signal();
+}
+/** `--concurrency`（1–16）与 `--probe-timeout`（毫秒，1000–300000）。 */
+export declare function parseProbeTuning(values: ReadonlyMap<string, string>): {
+    concurrency: number;
+    timeoutMs: number;
+};
+/** 预估文案：`并发 6，单次最长 15 s，预计不超过 150 s`。 */
+export declare function describeProbePlan(requests: number, concurrency: number, timeoutMs: number): string;
+/** 进度：TTY 下单行刷新「探测 18/60」；非 TTY 只在结束时打印一行汇总。 */
+export declare class ProbeProgress {
+    private readonly write;
+    private readonly tty;
+    private readonly total;
+    private done;
+    private shown;
+    private readonly started;
+    constructor(write: (text: string) => void, tty: boolean, total: number);
+    /** 输出一行结果（TTY 下先擦掉进度行，再重画）。 */
+    line(text: string): void;
+    tick(): void;
+    finish(): void;
+    private draw;
+    private clear;
+}

package/dist/cli/subcommands/probe-runner.js

@@ -0,0 +1,264 @@
+/**
+ * 探测的执行层（`ama providers add|refresh --probe`、`ama models discover --probe` 共用）。
+ *
+ * - **首事件即判定**：HTTP 成功、流里出现第一个内容事件（text / thinking / toolcall）或 done 即判可用，
+ *   立刻中止请求；只见到 `start`（推理模型可能要想很久才出第一个 delta）时再等 `settleMs`，期间没有
+ *   error 事件也判可用——防止中转先回 200、紧接着在流里报错被误判。HTTP 错误、流 error 事件、超时判不可用。
+ * - **有界并发**：同时在途 ≤ `concurrency`；结果按任务下标交回，调用方自己按顺序输出。
+ * - **限流**：429 时并发减半（至少 1），等 `retryDelayMs` 后重试该请求一次；重试仍 429 → 停止；
+ *   401 / 403 → 立即停止。停止后不再发新请求，并中止在途的请求（它们的结果标记为 aborted）。
+ * - **恢复（加法增、乘法减）**：降并发之后，每连续 `recoverAfter`（缺省 4）次没被限流的请求，并发 +1，
+ *   直到回到初始并发；中途再遇 429 重新减半、计数清零。
+ *
+ * `ama models check` 不走这里：它只发一次，要看到完整回复与耗时。
+ */
+import { UsageError } from "../args.js";
+export const PROBE_TIMEOUT_MS = 15_000;
+export const DEFAULT_PROBE_CONCURRENCY = 6;
+export const MAX_PROBE_CONCURRENCY = 16;
+export const PROBE_SETTLE_MS = 1_000;
+export const RATE_LIMIT_RETRY_MS = 2_000;
+/** 降并发后，连续多少次没被限流才 +1。 */
+export const RECOVER_AFTER = 4;
+/** 鉴权失败或限流：继续只会浪费请求。 */
+export const FATAL_STATUS = /^(?:HTTP )?(?:401|403|429)\b/;
+const RATE_LIMITED = /^(?:HTTP )?429\b/;
+const sleep = (ms, signal) => new Promise((resolve) => {
+    const timer = setTimeout(done, ms);
+    function done() {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", done);
+        resolve();
+    }
+    signal?.addEventListener("abort", done, { once: true });
+});
+/** 发一次最小请求，见到首个有效事件即判定并中止。 */
+export async function probeOnce(registry, model, apiKey, tuning = {}, signal) {
+    const impl = registry.getApi(model.api);
+    if (impl === undefined)
+        return { error: `协议 ${model.api} 尚未实现` };
+    if (signal?.aborted)
+        return { aborted: true };
+    const timeoutMs = tuning.timeoutMs ?? PROBE_TIMEOUT_MS;
+    const settleMs = tuning.settleMs ?? PROBE_SETTLE_MS;
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    const onAbort = () => controller.abort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const verdict = (outcome) => {
+        if (signal?.aborted)
+            return { aborted: true };
+        if (timedOut)
+            return { error: `超时（${Math.round(timeoutMs / 1000)} s 内没有响应）` };
+        return outcome;
+    };
+    try {
+        const stream = impl.stream(model, { messages: [{ role: "user", content: "Reply with: ok", timestamp: Date.now() }] }, {
+            signal: controller.signal,
+            ...(apiKey !== undefined ? { apiKey } : {}),
+            maxTokens: 16,
+            cacheRetention: "none",
+            purpose: "probe",
+        });
+        const events = stream[Symbol.asyncIterator]();
+        let settled;
+        while (true) {
+            const next = events.next();
+            const step = settled !== undefined ? await Promise.race([next, settled]) : await next;
+            if (step === "settled")
+                return verdict({});
+            if (step.done)
+                break;
+            const event = step.value;
+            if (event.type === "error")
+                return verdict({ error: event.message.errorMessage ?? event.reason });
+            if (event.type === "start") {
+                settled ??= sleep(settleMs, controller.signal).then(() => "settled");
+                continue;
+            }
+            return verdict({});
+        }
+        // 流没有逐个产出事件（实现只给 result）：按最终消息判定
+        const message = await stream.result();
+        if (message.stopReason === "error" || message.stopReason === "aborted")
+            return verdict({ error: message.errorMessage ?? message.stopReason });
+        return verdict({});
+    }
+    catch (error) {
+        return verdict({ error: error instanceof Error ? error.message : String(error) });
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        // 判定后立刻断开：不等推理模型把 16 个 token 想完
+        controller.abort();
+    }
+}
+/**
+ * 有界并发的探测调度器：`run` 按下标调度任务，任务里用 `probe` 发请求（带 429 重试与停止判定）。
+ */
+export class ProbeScheduler {
+    registry;
+    apiKey;
+    options;
+    limit;
+    initial;
+    /** 上次降并发以来连续没被限流的请求数。 */
+    streak = 0;
+    controller = new AbortController();
+    stopReason;
+    active = 0;
+    /** 观测用：同时在途请求数的峰值。 */
+    peak = 0;
+    constructor(registry, apiKey, options = {}) {
+        this.registry = registry;
+        this.apiKey = apiKey;
+        this.options = options;
+        this.limit = options.concurrency ?? DEFAULT_PROBE_CONCURRENCY;
+        this.initial = this.limit;
+    }
+    get stopped() {
+        return this.stopReason;
+    }
+    get concurrency() {
+        return this.limit;
+    }
+    stop(reason) {
+        if (this.stopReason !== undefined)
+            return;
+        this.stopReason = reason;
+        this.controller.abort();
+    }
+    /** 一次探测；429 降并发、退避后重试一次，仍 429 或 401 / 403 → 停止。 */
+    async probe(model) {
+        if (this.stopReason !== undefined)
+            return { aborted: true };
+        let outcome = await probeOnce(this.registry, model, this.apiKey, this.options, this.signal);
+        if (outcome.error !== undefined && RATE_LIMITED.test(outcome.error)) {
+            this.limit = Math.max(1, Math.floor(this.limit / 2));
+            this.streak = 0;
+            this.options.onThrottle?.(this.limit);
+            await sleep(this.options.retryDelayMs ?? RATE_LIMIT_RETRY_MS, this.signal);
+            if (this.stopReason !== undefined)
+                return { aborted: true };
+            outcome = await probeOnce(this.registry, model, this.apiKey, this.options, this.signal);
+            if (outcome.error !== undefined && RATE_LIMITED.test(outcome.error)) {
+                this.stop(`连续 429 限流：${outcome.error}`);
+                return outcome;
+            }
+        }
+        if (outcome.error !== undefined && FATAL_STATUS.test(outcome.error))
+            this.stop(outcome.error);
+        else if (outcome.aborted !== true)
+            this.recover();
+        return outcome;
+    }
+    /** 一次没被限流的请求：攒够 recoverAfter 次就并发 +1（不超过初始值）。 */
+    recover() {
+        if (this.limit >= this.initial)
+            return;
+        this.streak++;
+        if (this.streak < (this.options.recoverAfter ?? RECOVER_AFTER))
+            return;
+        this.streak = 0;
+        this.limit++;
+        this.options.onRecover?.(this.limit);
+    }
+    /** 并发执行 `count` 个任务；`onDone` 按完成顺序回调。停止后未开始的任务不执行（结果为 undefined）。 */
+    async run(count, task, onDone) {
+        const results = new Array(count).fill(undefined);
+        let next = 0;
+        await new Promise((resolve, reject) => {
+            const pump = () => {
+                while (this.stopReason === undefined && next < count && this.active < this.limit) {
+                    const index = next++;
+                    this.active++;
+                    this.peak = Math.max(this.peak, this.active);
+                    task(index).then((result) => {
+                        this.active--;
+                        results[index] = result;
+                        onDone?.(index, result);
+                        pump();
+                    }, (error) => {
+                        this.active--;
+                        this.stop(error instanceof Error ? error.message : String(error));
+                        reject(error);
+                    });
+                }
+                if (this.active === 0 && (next >= count || this.stopReason !== undefined))
+                    resolve();
+            };
+            pump();
+        });
+        return results;
+    }
+    get signal() {
+        return this.controller.signal;
+    }
+}
+/** `--concurrency`（1–16）与 `--probe-timeout`（毫秒，1000–300000）。 */
+export function parseProbeTuning(values) {
+    const int = (name, fallback, min, max) => {
+        const raw = values.get(name);
+        if (raw === undefined)
+            return fallback;
+        const n = Number(raw);
+        if (!Number.isInteger(n) || n < min || n > max)
+            throw new UsageError(`--${name} 需要 ${min}–${max} 的整数：${raw}`);
+        return n;
+    };
+    return {
+        concurrency: int("concurrency", DEFAULT_PROBE_CONCURRENCY, 1, MAX_PROBE_CONCURRENCY),
+        timeoutMs: int("probe-timeout", PROBE_TIMEOUT_MS, 1_000, 300_000),
+    };
+}
+/** 预估文案：`并发 6，单次最长 15 s，预计不超过 150 s`。 */
+export function describeProbePlan(requests, concurrency, timeoutMs) {
+    const worst = Math.ceil(requests / concurrency) * Math.ceil(timeoutMs / 1000);
+    return `并发 ${concurrency}，单次最长 ${Math.round(timeoutMs / 1000)} s，预计不超过 ${worst} s`;
+}
+/** 进度：TTY 下单行刷新「探测 18/60」；非 TTY 只在结束时打印一行汇总。 */
+export class ProbeProgress {
+    write;
+    tty;
+    total;
+    done = 0;
+    shown = false;
+    started = Date.now();
+    constructor(write, tty, total) {
+        this.write = write;
+        this.tty = tty;
+        this.total = total;
+    }
+    /** 输出一行结果（TTY 下先擦掉进度行，再重画）。 */
+    line(text) {
+        this.clear();
+        this.write(text);
+        this.draw();
+    }
+    tick() {
+        this.done++;
+        this.draw();
+    }
+    finish() {
+        this.clear();
+        const seconds = ((Date.now() - this.started) / 1000).toFixed(1);
+        this.write(`探测完成 ${this.done}/${this.total}，用时 ${seconds} s\n`);
+    }
+    draw() {
+        if (!this.tty)
+            return;
+        this.write(`\r\x1b[2K探测 ${this.done}/${this.total}`);
+        this.shown = true;
+    }
+    clear() {
+        if (!this.tty || !this.shown)
+            return;
+        this.write("\r\x1b[2K");
+        this.shown = false;
+    }
+}