@armadra/agent 0.3.0 → 0.5.0

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` 时只写探测成功的模型。不猜
@@ -19,7 +20,7 @@
 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 { describeModelsDev, loadModelsDevIndex } 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";
@@ -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;
@@ -172,15 +173,14 @@ 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`);
+    // models.dev 只读本地（快照 ⊕ `ama models refresh` 的覆盖），不联网。
+    const mdIndex = loadModelsDevIndex(ctx.level.dataDir);
+    io.stdout(`${describeModelsDev(ctx.level.dataDir)}\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 match = mdIndex.match(model.id);
         const fields = match !== undefined ? modelsDevFields(match.model) : undefined;
         if (fields?.toolCall === false)
             noTools.add(model.id);
@@ -202,13 +202,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 +230,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.d.ts

@@ -7,6 +7,8 @@
  * [W3-C0] 子命令分派改为动作表 `MODELS_ACTIONS`（第三波 §1.11 / §2.3）：新动作（C2 的
  * `cache-probe`、B12 的 `discover`）各写在自己的文件里，这里只加一行表项；用法文本、
  * 选项表与必填位置参数都从表里来。
+ *
+ * [W5-M1] `refresh`：models.dev 显式刷新（`refresh-catalog` 保留为别名）。
  */
 import type { ProviderRegistryApi } from "../../ai/types.js";
 import type { CliIo, RuntimeDeps } from "../deps.js";

package/dist/cli/subcommands/models.js

@@ -7,9 +7,12 @@
  * [W3-C0] 子命令分派改为动作表 `MODELS_ACTIONS`（第三波 §1.11 / §2.3）：新动作（C2 的
  * `cache-probe`、B12 的 `discover`）各写在自己的文件里，这里只加一行表项；用法文本、
  * 选项表与必填位置参数都从表里来。
+ *
+ * [W5-M1] `refresh`：models.dev 显式刷新（`refresh-catalog` 保留为别名）。
  */
 import { formatModelRef, modelRefOf } from "../../ai/providers/channels.js";
 import { describeRefresh, modelsDevCachePath, refreshModelsDev, } from "../../ai/providers/models-dev-cache.js";
+import { snapshotMeta } from "../../ai/providers/models-dev-snapshot.js";
 import { parseSubArgs, UsageError } from "../args.js";
 import { ExitCode } from "../exit-codes.js";
 import { buildRegistry, loadUserLevel } from "./context.js";
@@ -78,6 +81,34 @@ async function check(io, registry, ref) {
     io.stdout(`${shown} 可用（${model.api}，${ms} ms，stopReason ${message.stopReason}）\n`);
     return ExitCode.Ok;
 }
+/**
+ * `ama models refresh [--provider <id>[,<id>…]]`：显式联网拉 models.dev，按内置快照的清单裁剪，
+ * 写用户级覆盖 `<dataDir>/models-dev.json`（docs/providers.md「模型元数据」）。启动与其它命令不联网。
+ */
+const REFRESH_ACTION = {
+    usage: "ama models refresh [--provider <id>[,<id>…]]",
+    valueOptions: ["provider"],
+    run: async (ctx) => {
+        const only = ctx.values.get("provider");
+        const providers = only
+            ?.split(",")
+            .map((p) => p.trim())
+            .filter(Boolean);
+        ctx.io.stdout(`内置快照：${snapshotMeta().fetchedAt}；正在拉取 models.dev…\n`);
+        const result = await refreshModelsDev({
+            dataDir: ctx.level.dataDir,
+            env: ctx.io.env,
+            ...(providers !== undefined && providers.length > 0 ? { providers } : {}),
+        });
+        if (result.warning !== undefined)
+            ctx.io.stderr(`ama: ${result.warning}\n`);
+        ctx.io.stdout(`${describeRefresh(result)}\n`);
+        if (result.status === "failed")
+            return ExitCode.RuntimeError;
+        ctx.io.stdout(`已写入 ${modelsDevCachePath(ctx.level.dataDir)}\n`);
+        return ExitCode.Ok;
+    },
+};
 /** 动作表：键是子命令名，顺序即用法文本顺序。 */
 export const MODELS_ACTIONS = Object.freeze({
     list: {
@@ -92,20 +123,8 @@ 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;
-        },
-    },
+    refresh: REFRESH_ACTION,
+    "refresh-catalog": { ...REFRESH_ACTION, usage: "ama models refresh-catalog（refresh 的旧名）" },
 });
 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;
+}