@armadra/agent 0.3.0 → 0.5.0

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

package/dist/cli/subcommands/providers-probe.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `ama providers add|refresh --probe` 的逐渠道探测：任务是「模型 × 渠道」，有界并发执行（见
+ * probe-runner.ts）；每个模型的所有渠道探完后按模型顺序打印一行，不按完成顺序。
+ */
+import type { ProviderRegistryApi } from "../../ai/types.js";
+import type { CliIo } from "../deps.js";
+import type { CandidateChannel } from "./providers-plan.js";
+export interface ChannelProbeResult {
+    /** 探测成功的渠道（按渠道尝试顺序）。 */
+    ok: string[];
+    /** 最后一个失败渠道的原因（首行，≤ 120 字符）。 */
+    error?: string;
+}
+export interface ChannelProbeInput {
+    io: Pick<CliIo, "stdout" | "stderr" | "stdoutIsTTY">;
+    providerId: string;
+    ids: readonly string[];
+    /** 每个模型要试的渠道名（顺序即输出顺序）。 */
+    channelsFor: (id: string) => readonly string[];
+    candidates: readonly CandidateChannel[];
+    registry: ProviderRegistryApi;
+    apiKey: string | undefined;
+    concurrency: number;
+    timeoutMs: number;
+    /** 测试用：429 重试前的退避。 */
+    retryDelayMs?: number;
+}
+/**
+ * 探测全部「模型 × 渠道」。返回有结论的模型（全部渠道探完，或因停止没探完但已有成功渠道）与停止原因。
+ */
+export declare function probeChannels(input: ChannelProbeInput): Promise<{
+    results: Map<string, ChannelProbeResult>;
+    stopped?: string;
+}>;

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

@@ -0,0 +1,87 @@
+/**
+ * `ama providers add|refresh --probe` 的逐渠道探测：任务是「模型 × 渠道」，有界并发执行（见
+ * probe-runner.ts）；每个模型的所有渠道探完后按模型顺序打印一行，不按完成顺序。
+ */
+import { withCustomDefaults } from "../../ai/providers/catalog.js";
+import { materializeModel } from "../../ai/providers/registry.js";
+import { ProbeProgress, ProbeScheduler } from "./probe-runner.js";
+/** 渠道的探测用供应商数据（key 由调用方传入）。 */
+function probeProvider(id, channel) {
+    return {
+        id,
+        name: id,
+        api: channel.api,
+        baseUrl: channel.baseUrl,
+        envKeys: [],
+        models: [],
+        requiresApiKey: true,
+        builtin: false,
+    };
+}
+const firstLine = (error) => error.split("\n")[0]?.slice(0, 120) ?? error;
+/**
+ * 探测全部「模型 × 渠道」。返回有结论的模型（全部渠道探完，或因停止没探完但已有成功渠道）与停止原因。
+ */
+export async function probeChannels(input) {
+    const { io } = input;
+    const tasks = input.ids.flatMap((id) => input.channelsFor(id).map((name) => ({ id, name })));
+    const pending = new Map(input.ids.map((id) => [id, input.channelsFor(id).length]));
+    const outcomes = new Map();
+    const results = new Map();
+    const progress = new ProbeProgress(io.stdout, io.stdoutIsTTY, tasks.length);
+    const scheduler = new ProbeScheduler(input.registry, input.apiKey, {
+        concurrency: input.concurrency,
+        timeoutMs: input.timeoutMs,
+        retryDelayMs: input.retryDelayMs,
+        onThrottle: (n) => progress.line(`  遇到 429 限流，并发降到 ${n}，稍后重试一次\n`),
+        onRecover: (n) => progress.line(`  一段时间没再限流，并发回升到 ${n}\n`),
+    });
+    let printed = 0;
+    /** 按模型顺序输出：前面的模型都探完才输出后面的。 */
+    const flush = (final) => {
+        while (printed < input.ids.length) {
+            const id = input.ids[printed];
+            if (!final && (pending.get(id) ?? 0) > 0)
+                return;
+            printed++;
+            const result = { ok: [] };
+            const failed = [];
+            let complete = true;
+            for (const name of input.channelsFor(id)) {
+                const outcome = outcomes.get(`${id}\n${name}`);
+                if (outcome === undefined || outcome.aborted)
+                    complete = false;
+                else if (outcome.error === undefined)
+                    result.ok.push(name);
+                else {
+                    result.error = firstLine(outcome.error);
+                    failed.push(`${name}：${result.error}`);
+                }
+            }
+            if (!complete && result.ok.length === 0)
+                continue;
+            results.set(id, result);
+            progress.line(`  ${id}  ${result.ok.length > 0 ? result.ok.join(", ") : "全部失败"}` +
+                `${failed.length > 0 ? `（失败 ${failed.join("；")}）` : ""}` +
+                `${complete ? "" : "（探测提前停止，部分渠道未探）"}\n`);
+        }
+    };
+    await scheduler.run(tasks.length, async (index) => {
+        const { id, name } = tasks[index];
+        const channel = input.candidates.find((c) => c.name === name);
+        const provider = probeProvider(input.providerId, channel);
+        const model = materializeModel(withCustomDefaults({ id }, input.providerId, channel.api), provider);
+        return scheduler.probe(model);
+    }, (index, outcome) => {
+        const { id, name } = tasks[index];
+        outcomes.set(`${id}\n${name}`, outcome);
+        pending.set(id, (pending.get(id) ?? 1) - 1);
+        if (!outcome.aborted)
+            progress.tick();
+        flush(false);
+    });
+    flush(true);
+    progress.finish();
+    const stopped = scheduler.stopped;
+    return { results, ...(stopped !== undefined ? { stopped } : {}) };
+}

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

@@ -7,14 +7,15 @@
  * - refresh：重拉 `/models` 与 models.dev，只追加新模型；已下架的只提示。
  * - list / channels：供应商 → 渠道 → 模型数与 key 来源（从不显示 key）。remove：删配置与 auth.json 条目。
  *
- * 计费：`--probe` 每模型每渠道一次最小请求；执行前打印预估，TTY 问 y/N，非 TTY 必须 `--yes`。
+ * 计费：`--probe` 每模型每渠道一次最小请求（并发执行，见到首个流事件即判可用并断开，见
+ * probe-runner.ts）；执行前打印预估，TTY 问 y/N，非 TTY 必须 `--yes`。
  */
 import type { AmaConfig } from "../../config/types.js";
 import type { CliIo, RuntimeDeps } from "../deps.js";
 import { type UserLevel } from "./context.js";
 export declare const DEFAULT_MAX_REQUESTS = 60;
 export declare const DEFAULT_LIMIT = 30;
-export declare const PROVIDERS_USAGE = "\u7528\u6CD5\uFF1Aama providers add <id> --base-url <url> [--channel <\u540D\u5B57>=<\u534F\u8BAE>@<\u5730\u5740> \u2026]\n                         [--api openai-completions|openai-responses|anthropic-messages|auto]\n                         [--key-env <VAR>] [--probe] [--limit N] [--probe-models a,b,\u2026]\n                         [--max-requests N] [--prefer chat,responses,messages]\n                         [--include-no-tools] [--yes]\n      ama providers list\n      ama providers channels <id>\n      ama providers remove <id>\n      ama providers refresh <id> [--probe] [--limit N] [--probe-models a,b,\u2026] [--max-requests N] [--yes]\n";
+export declare const PROVIDERS_USAGE = "\u7528\u6CD5\uFF1Aama providers add <id> --base-url <url> [--channel <\u540D\u5B57>=<\u534F\u8BAE>@<\u5730\u5740> \u2026]\n                         [--api openai-completions|openai-responses|anthropic-messages|auto]\n                         [--key-env <VAR>] [--probe] [--limit N] [--probe-models a,b,\u2026]\n                         [--max-requests N] [--concurrency N] [--probe-timeout ms]\n                         [--prefer chat,responses,messages] [--include-no-tools] [--yes]\n      ama providers list\n      ama providers channels <id>\n      ama providers remove <id>\n      ama providers refresh <id> [--probe] [--limit N] [--probe-models a,b,\u2026] [--max-requests N]\n                             [--concurrency N] [--probe-timeout ms] [--yes]\n";
 export interface Ctx {
     io: CliIo;
     deps: Pick<RuntimeDeps, "providers">;

package/dist/cli/subcommands/providers.js

@@ -7,36 +7,39 @@
  * - refresh：重拉 `/models` 与 models.dev，只追加新模型；已下架的只提示。
  * - list / channels：供应商 → 渠道 → 模型数与 key 来源（从不显示 key）。remove：删配置与 auth.json 条目。
  *
- * 计费：`--probe` 每模型每渠道一次最小请求；执行前打印预估，TTY 问 y/N，非 TTY 必须 `--yes`。
+ * 计费：`--probe` 每模型每渠道一次最小请求（并发执行，见到首个流事件即判可用并断开，见
+ * probe-runner.ts）；执行前打印预估，TTY 问 y/N，非 TTY 必须 `--yes`。
  */
 import { existsSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
-import { withCustomDefaults } from "../../ai/providers/catalog.js";
-import { describeRefresh, refreshModelsDev } from "../../ai/providers/models-dev-cache.js";
+import { describeModelsDev, loadModelsDevIndex } from "../../ai/providers/models-dev-cache.js";
 import { modelsDevFields } from "../../ai/providers/models-dev.js";
-import { materializeModel } from "../../ai/providers/registry.js";
 import { PROVIDER_ID_PATTERN, setAuthKey } from "../../config/auth-file.js";
 import { loadConfigFile } from "../../config/load.js";
 import { CONFIG_FILE_VERSION } from "../../config/types.js";
 import { writeConfigFile } from "../../config/write.js";
 import { parseSubArgs, UsageError } from "../args.js";
+import { pickByPrice } from "../default-model.js";
 import { ExitCode } from "../exit-codes.js";
 import { extractKey } from "./auth.js";
 import { listChannels, listProviders, removeProvider } from "./providers-list.js";
 import { buildRegistry, loadUserLevel } from "./context.js";
-import { attempt, DISCOVER_TIMEOUT_MS, FATAL_STATUS } from "./models-discover.js";
+import { DISCOVER_TIMEOUT_MS } from "./models-discover.js";
+import { describeProbePlan, parseProbeTuning } from "./probe-runner.js";
+import { probeChannels } from "./providers-probe.js";
 import { DEFAULT_PREFER, capRequests, defaultChannels, hintedChannels, listingTarget, mergeProvider, orderChannels, parseChannelSpec, parseModelList, probeSelection, renderTable, } from "./providers-plan.js";
 export const DEFAULT_MAX_REQUESTS = 60;
 export const DEFAULT_LIMIT = 30;
 export const PROVIDERS_USAGE = `用法：ama providers add <id> --base-url <url> [--channel <名字>=<协议>@<地址> …]
                          [--api openai-completions|openai-responses|anthropic-messages|auto]
                          [--key-env <VAR>] [--probe] [--limit N] [--probe-models a,b,…]
-                         [--max-requests N] [--prefer chat,responses,messages]
-                         [--include-no-tools] [--yes]
+                         [--max-requests N] [--concurrency N] [--probe-timeout ms]
+                         [--prefer chat,responses,messages] [--include-no-tools] [--yes]
       ama providers list
       ama providers channels <id>
       ama providers remove <id>
-      ama providers refresh <id> [--probe] [--limit N] [--probe-models a,b,…] [--max-requests N] [--yes]
+      ama providers refresh <id> [--probe] [--limit N] [--probe-models a,b,…] [--max-requests N]
+                             [--concurrency N] [--probe-timeout ms] [--yes]
 `;
 const VALUE_OPTIONS = [
     "base-url",
@@ -45,6 +48,8 @@ const VALUE_OPTIONS = [
     "limit",
     "probe-models",
     "max-requests",
+    "concurrency",
+    "probe-timeout",
     "prefer",
     "name",
     "profile",
@@ -119,19 +124,6 @@ function channelsOfConfig(config) {
     const api = config.api ?? "openai-completions";
     return [{ name: "default", api, baseUrl: config.baseUrl }];
 }
-/** 渠道的探测用供应商数据（key 由调用方传入）。 */
-function probeProvider(id, channel) {
-    return {
-        id,
-        name: id,
-        api: channel.api,
-        baseUrl: channel.baseUrl,
-        envKeys: [],
-        models: [],
-        requiresApiKey: true,
-        builtin: false,
-    };
-}
 /** 逐模型定渠道（含探测）；返回各模型的计划与是否因鉴权 / 限流提前停止。 */
 async function plan(ctx, input) {
     const { io } = ctx;
@@ -151,36 +143,28 @@ async function plan(ctx, input) {
         const selected = probeSelection(fresh.map((m) => m.id).filter(probeable), intValue(ctx, "limit", DEFAULT_LIMIT), only);
         const max = intValue(ctx, "max-requests", DEFAULT_MAX_REQUESTS);
         const capped = capRequests(selected, tryChannels, max);
+        const tuning = parseProbeTuning(ctx.values);
         io.stdout(`\n探测：${capped.ids.length} 个模型、${capped.requests} 次最小请求（每模型每渠道 1 次，上限 ${max}）` +
-            `${capped.dropped > 0 ? `；另有 ${capped.dropped} 个超出上限未探测` : ""}\n`);
+            `${capped.dropped > 0 ? `；另有 ${capped.dropped} 个超出上限未探测` : ""}\n` +
+            `${describeProbePlan(capped.requests, tuning.concurrency, tuning.timeoutMs)}\n`);
         const ok = await approved(ctx, `将发 ${capped.requests} 次计费请求并写入 ${ctx.level.userConfigPath}`);
         if (ok === "usage")
             return { plans: [], cancelled: ExitCode.Usage };
         if (!ok)
             return { plans: [], cancelled: ExitCode.Ok };
-        outer: for (const id of capped.ids) {
-            const result = { ok: [] };
-            const failed = [];
+        const probed = await probeChannels({
+            io,
+            providerId: input.id,
+            ids: capped.ids,
+            channelsFor: tryChannels,
+            candidates: input.candidates,
+            registry: input.registry,
+            apiKey: input.apiKey,
+            ...tuning,
+        });
+        for (const [id, result] of probed.results)
             results.set(id, result);
-            for (const name of tryChannels(id)) {
-                const channel = input.candidates.find((c) => c.name === name);
-                const provider = probeProvider(input.id, channel);
-                const model = materializeModel(withCustomDefaults({ id }, input.id, channel.api), provider);
-                const error = await attempt(input.registry, model, input.apiKey);
-                if (error === undefined)
-                    result.ok.push(name);
-                else {
-                    result.error = error.split("\n")[0]?.slice(0, 120) ?? error;
-                    failed.push(`${name}：${result.error}`);
-                    if (FATAL_STATUS.test(error)) {
-                        stopped = error;
-                        break outer;
-                    }
-                }
-            }
-            io.stdout(`  ${id}  ${result.ok.length > 0 ? result.ok.join(", ") : "全部失败"}` +
-                `${failed.length > 0 ? `（失败 ${failed.join("；")}）` : ""}\n`);
-        }
+        stopped = probed.stopped;
     }
     const includeNoTools = ctx.flags.has("include-no-tools");
     const plans = input.listed.map((listed) => {
@@ -276,17 +260,16 @@ async function add(ctx, id, refresh) {
         return ExitCode.RuntimeError;
     }
     io.stdout(`${id}：发现 ${listed.length} 个模型（${target.url}）\n`);
-    const md = await refreshModelsDev({ dataDir: level.dataDir, env: io.env, force: refresh });
-    io.stdout(`${describeRefresh(md)}\n`);
-    if (md.warning !== undefined)
-        io.stderr(`ama: 警告：${md.warning}\n`);
+    // models.dev 只读本地（快照 ⊕ `ama models refresh` 的覆盖），不联网。
+    const mdIndex = loadModelsDevIndex(level.dataDir);
+    io.stdout(`${describeModelsDev(level.dataDir)}\n`);
     io.stdout(`候选渠道：${candidates.map((c) => `${c.name}（${c.api} ${c.baseUrl}）`).join(" · ")}\n`);
     const existingIds = new Set((existing?.models ?? []).map((m) => m.id));
     const result = await plan(ctx, {
         id,
         candidates,
         listed,
-        index: md.index,
+        index: mdIndex,
         existingIds,
         apiKey: key.apiKey,
         registry,
@@ -314,9 +297,25 @@ async function add(ctx, id, refresh) {
             prefer: list(ctx.values.get("prefer")) ?? [...DEFAULT_PREFER],
         });
     const keyNote = key.store !== undefined ? `；key → ${level.authFile}（0600）` : "";
+    // 还没有缺省模型时按价格规则挑一个写进 defaultModel（default-model.ts 的 pickByPrice）；
+    // 探测过时只在探测通过的模型里挑
+    const verified = writable.filter((p) => p.status === "ok");
+    const defaultPick = level.merged.config.defaultModel === undefined && config.defaultModel === undefined
+        ? pickByPrice((verified.length > 0 ? verified : writable).map((p) => ({
+            id: p.id,
+            contextWindow: p.fields.contextWindow,
+            inputCost: p.fields.cost?.input,
+            toolCall: p.fields.toolCall,
+        })))
+        : undefined;
+    const defaultNote = defaultPick !== undefined ? `；defaultModel → ${id}/${defaultPick.id}` : "";
     const summary = `\n将写入 ${level.userConfigPath}：${id} 新增渠道 ${merged.addedChannels.join(", ") || "无"}，` +
-        `新增模型 ${merged.addedModels.length} 个${keyNote}`;
+        `新增模型 ${merged.addedModels.length} 个${keyNote}${defaultNote}`;
     io.stdout(`${summary}\n`);
+    if (defaultPick !== undefined)
+        io.stdout(`  选 ${defaultPick.id}：${defaultPick.reason}\n`);
+    else if (level.merged.config.defaultModel === undefined && writable.length > 0)
+        io.stdout("  未设置 defaultModel：没有同时支持工具调用、上下文 ≥ 64k 且有价格的模型；用 ama config edit 设置\n");
     if (merged.addedModels.length === 0 &&
         merged.addedChannels.length === 0 &&
         key.store === undefined) {
@@ -334,12 +333,15 @@ async function add(ctx, id, refresh) {
     }
     const providers = (config.providers ??= {});
     providers[id] = merged.config;
+    if (defaultPick !== undefined)
+        config.defaultModel = `${id}/${defaultPick.id}`;
     const backup = existsSync(level.userConfigPath);
     writeConfigFile(level.userConfigPath, config, { backup: true });
     if (key.store !== undefined)
         setAuthKey(level.authFile, id, key.store);
     io.stdout(`已写入 ${level.userConfigPath}${backup ? "（原文件备份为 config.json.bak）" : ""}\n`);
-    const sample = result.plans.find((p) => p.status === "ok" && merged.addedModels.includes(p.id))?.id ??
+    const sample = defaultPick?.id ??
+        result.plans.find((p) => p.status === "ok" && merged.addedModels.includes(p.id))?.id ??
         merged.addedModels[0];
     if (sample !== undefined)
         io.stdout(`试试：ama -p "hi" --model ${id}/${sample}\n`);

package/dist/cli/subcommands/sessions-export.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `ama sessions export <id>`：导出会话（只读，不加锁；正在运行的会话也能导）。[W4-D]
+ *
+ * - `--format md|json|jsonl`（缺省 md）；`--branch leaf|all`（缺省 leaf = 当前分支）；
+ * - `--output <文件>`：写文件（0600，已存在则覆盖），否则写 stdout；
+ * - 导出内容先脱敏（session/redact.ts），格式说明见 docs/sessions.md「导出」。
+ */
+import type { CliIo } from "../deps.js";
+export declare const SESSIONS_EXPORT_USAGE = "\u7528\u6CD5\uFF1Aama sessions export <id> [--format md|json|jsonl] [--output <\u6587\u4EF6>] [--branch leaf|all]\n                            [--session-dir <\u76EE\u5F55>]\n";
+export declare function runSessionsExport(argv: readonly string[], io: CliIo): Promise<number>;

package/dist/cli/subcommands/sessions-export.js

@@ -0,0 +1,59 @@
+/**
+ * `ama sessions export <id>`：导出会话（只读，不加锁；正在运行的会话也能导）。[W4-D]
+ *
+ * - `--format md|json|jsonl`（缺省 md）；`--branch leaf|all`（缺省 leaf = 当前分支）；
+ * - `--output <文件>`：写文件（0600，已存在则覆盖），否则写 stdout；
+ * - 导出内容先脱敏（session/redact.ts），格式说明见 docs/sessions.md「导出」。
+ */
+import { writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { expandHome, resolveDataDir } from "../../config/paths.js";
+import { renderExport } from "../../session/export.js";
+import { findSessionFileReadOnly, readSessionReadOnly } from "../../session/scan.js";
+import { parseSubArgs, UsageError } from "../args.js";
+import { ExitCode } from "../exit-codes.js";
+export const SESSIONS_EXPORT_USAGE = `用法：ama sessions export <id> [--format md|json|jsonl] [--output <文件>] [--branch leaf|all]
+                            [--session-dir <目录>]
+`;
+const FORMATS = ["md", "json", "jsonl"];
+const BRANCHES = ["leaf", "all"];
+export async function runSessionsExport(argv, io) {
+    const { positionals, values, flags } = parseSubArgs(argv, [
+        "format",
+        "output",
+        "branch",
+        "session-dir",
+    ]);
+    if (flags.has("help")) {
+        io.stdout(SESSIONS_EXPORT_USAGE);
+        return ExitCode.Ok;
+    }
+    const [id, extra] = positionals;
+    if (id === undefined)
+        throw new UsageError("ama sessions export 需要 <id>");
+    if (extra !== undefined)
+        throw new UsageError(`多余的参数：${extra}`);
+    const format = (values.get("format") ?? "md");
+    if (!FORMATS.includes(format)) {
+        throw new UsageError(`--format 的取值应为 ${FORMATS.join(" | ")}（收到 ${format}）`);
+    }
+    const branch = (values.get("branch") ?? "leaf");
+    if (!BRANCHES.includes(branch)) {
+        throw new UsageError(`--branch 的取值应为 ${BRANCHES.join(" | ")}（收到 ${branch}）`);
+    }
+    const dirFlag = values.get("session-dir");
+    const root = dirFlag !== undefined
+        ? resolve(io.cwd, expandHome(dirFlag, { env: io.env }))
+        : join(resolveDataDir({ env: io.env }), "sessions");
+    const session = readSessionReadOnly(findSessionFileReadOnly(root, id, io.cwd));
+    const text = renderExport(session, format, branch);
+    const output = values.get("output");
+    if (output === undefined) {
+        io.stdout(text);
+        return ExitCode.Ok;
+    }
+    const target = resolve(io.cwd, expandHome(output, { env: io.env }));
+    writeFileSync(target, text, { mode: 0o600 });
+    io.stderr(`已导出到 ${target}\n`);
+    return ExitCode.Ok;
+}