@armadra/agent 0.3.0 → 0.4.0

package/dist/cli/subcommands/context.js

@@ -7,6 +7,7 @@ import { loadConfigFile } from "../../config/load.js";
 import { mergeBaseLayers } from "../../config/merge.js";
 import { CONFIG_FILE, resolveConfigDir, resolveDataDir, userFile } from "../../config/paths.js";
 import { loadProfile } from "../../config/profile.js";
+import { hideFakeProvider } from "../fake-visibility.js";
 export function loadUserLevel(io, options = {}) {
     const configDir = resolveConfigDir({ env: io.env });
     const dataDir = resolveDataDir({ env: io.env });
@@ -32,11 +33,13 @@ export function loadUserLevel(io, options = {}) {
     return result;
 }
 export async function buildRegistry(level, io, deps) {
-    return deps.providers.create({
+    // 列表类子命令（doctor / models list / providers list / config show）缺省不列 fake
+    const registry = await deps.providers.create({
         config: level.merged.config,
         cwd: io.cwd,
         authFile: level.authFile,
         authEnv: level.profile?.authEnv ?? true,
         dataDir: level.dataDir,
     });
+    return hideFakeProvider(registry, io.env);
 }

package/dist/cli/subcommands/doctor.js

@@ -18,7 +18,8 @@ import { loadHookConfigs } from "../../hooks/config.js";
 import { AMA_VERSION } from "../../version.js";
 import { parseSubArgs } from "../args.js";
 import { ExitCode } from "../exit-codes.js";
-import { describeModel } from "./config.js";
+import { describeProxy, inspectProxy } from "../proxy.js";
+import { describeCodemode, describeModel } from "./config.js";
 import { buildRegistry, loadUserLevel } from "./context.js";
 export const DOCTOR_USAGE = `用法：ama doctor [--profile <文件>] [--auth-file <文件>] [--trust | --no-trust]
 `;
@@ -184,6 +185,11 @@ function terminalSection(report, io) {
     const tui = io.stdinIsTTY && io.stdoutIsTTY && env["TERM"] !== "dumb";
     report.item(`缺省界面：${tui ? "终端界面" : "行式（--no-tui 等价）"}`);
 }
+function proxySection(report, io) {
+    report.section("代理");
+    for (const line of describeProxy(inspectProxy(io.env)))
+        report.item(line);
+}
 export async function runDoctor(argv, io, deps) {
     const { values, flags } = parseSubArgs(argv, ["profile", "auth-file"], ["trust", "no-trust"]);
     if (flags.has("help")) {
@@ -223,6 +229,10 @@ export async function runDoctor(argv, io, deps) {
         for (const warning of merged.warnings)
             report.item(`  收紧：${warning}`);
         report.item(`有效权限模式：${merged.config.permission?.mode ?? "default"}`);
+        const codemode = describeCodemode(merged.config);
+        report.item(`codemode：${codemode.mode}（${codemode.reason}）`);
+        if (codemode.unavailable !== undefined)
+            report.item(`  ${codemode.unavailable}`);
     }
     catch {
         // probeLine 已报告
@@ -240,6 +250,7 @@ export async function runDoctor(argv, io, deps) {
     await keySection(report, io, level, deps);
     hookSection(report, io, level, trusted);
     report.item(`用户级 hooks.json：${userFile(level, HOOKS_FILE)}`);
+    proxySection(report, io);
     terminalSection(report, io);
     io.stdout(report.text());
     return report.problems > 0 ? ExitCode.Config : ExitCode.Ok;

package/dist/cli/subcommands/init.js

@@ -1,7 +1,7 @@
 /**
  * `ama init [--force]`（docs/providers.md「配置目录」）：建配置目录与缺省文件，逐个报告状态。
  */
-import { describeInit, initConfigDir } from "../../config/init.js";
+import { INIT_NEXT_STEPS, describeInit, initConfigDir } from "../../config/init.js";
 import { resolveConfigDir } from "../../config/paths.js";
 import { parseSubArgs, UsageError } from "../args.js";
 import { ExitCode } from "../exit-codes.js";
@@ -18,5 +18,6 @@ export function runInit(argv, io) {
         throw new UsageError(`多余的参数：${positionals.join(" ")}`);
     const result = initConfigDir(resolveConfigDir({ env: io.env }), { force: flags.has("force") });
     io.stdout(describeInit(result));
+    io.stdout(`\n${INIT_NEXT_STEPS.join("\n")}\n`);
     return ExitCode.Ok;
 }

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

@@ -5,9 +5,10 @@
  * 带供应商的鉴权头，打印 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` 时只写探测成功的模型。不猜
@@ -19,7 +20,6 @@
 import type { Api, Model, ProviderData, ProviderRegistryApi } from "../../ai/types.js";
 import type { ModelsAction } from "./models.js";
 export declare const DISCOVER_TIMEOUT_MS = 15000;
-export declare const PROBE_TIMEOUT_MS = 30000;
 export declare const DEFAULT_PROBE_LIMIT = 30;
 /** 中转常见的三种协议，按此顺序探测（供应商协议排最前）。 */
 export declare const PROBE_APIS: readonly Api[];
@@ -31,16 +31,22 @@ export declare function discoverModels(provider: ProviderData, apiKey: string |
 export declare function probeOrder(provider: ProviderData): Api[];
 export interface ProbeOptions {
     timeoutMs?: number;
+    /** 同时在途的模型数（每个模型内按协议顺序依次试）；缺省 6。 */
+    concurrency?: number;
+    /** 测试用：429 重试前的退避。 */
+    retryDelayMs?: number;
     /** 每次请求后回调。 */
     onAttempt?: (id: string, api: Api, error: string | undefined) => void;
-    /** 每个模型探完回调（进度输出）。 */
+    /** 每个模型探完立即回调（按完成顺序，进度用）。 */
+    onSettled?: () => void;
+    /** 每个模型探完回调，按模型顺序（不按完成顺序）。 */
     onResult?: (id: string, api: Api | undefined) => void;
     /** 因鉴权失败或限流提前停止时回调。 */
     onStop?: (reason: string) => void;
 }
-export declare const FATAL_STATUS: RegExp;
-/** 返回已探测模型 → 第一个成功的协议（都失败为 undefined）；超出 `limit` 或提前停止的不在表里。 */
+/**
+ * 返回已探测模型 → 第一个成功的协议（都失败为 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

@@ -5,9 +5,10 @@
  * 带供应商的鉴权头，打印 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` 时只写探测成功的模型。不猜
@@ -27,8 +28,8 @@ 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";
 /** 中转常见的三种协议，按此顺序探测（供应商协议排最前）。 */
@@ -57,57 +58,57 @@ export function probeOrder(provider) {
         ? [provider.api, ...PROBE_APIS.filter((api) => api !== provider.api)]
         : [...PROBE_APIS];
 }
-export 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，失败返回错误文本（`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;
@@ -202,13 +203,19 @@ async function run(ctx) {
     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) {
@@ -224,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/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;
+    }
+}