@armadra/agent 0.0.0-stage → 0.3.0

package/dist/cli/subcommands/doctor.js

@@ -0,0 +1,246 @@
+/**
+ * `ama doctor`（设计 §1.2、§6.1、R4、R8）。[B5]
+ *
+ * 输出：目录、配置层级（每层文件存在 / 有效 / 警告）、信任状态与需信任的资源、AGENTS.md、
+ * key 来源（只给来源不给值）、将执行的 Hook 命令（含因未信任被跳过的项目级）、终端能力。
+ * 只读：不询问信任、不写任何文件；配置错误照常列出并以退出码 3 结束。
+ * [W3-B12] baseUrl 来自 `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL` 时在 key 行后标出变量与地址。
+ */
+import { existsSync } from "node:fs";
+import { baseUrlEnvOf } from "../../ai/providers/registry.js";
+import { classifyKeyValue, isModeTooOpen, fileMode, readAuthFile } from "../../config/auth-file.js";
+import { findContextFiles } from "../../config/context-files.js";
+import { loadConfigFile, probeConfigFile } from "../../config/load.js";
+import { mergeProjectAndCli } from "../../config/merge.js";
+import { CONFIG_FILE, HOOKS_FILE, projectFile, userFile } from "../../config/paths.js";
+import { findTrustEntry, readTrustFile, trustGatedResources } from "../../config/trust.js";
+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 { buildRegistry, loadUserLevel } from "./context.js";
+export const DOCTOR_USAGE = `用法：ama doctor [--profile <文件>] [--auth-file <文件>] [--trust | --no-trust]
+`;
+class Report {
+    lines = [];
+    problems = 0;
+    section(title) {
+        if (this.lines.length > 0)
+            this.lines.push("");
+        this.lines.push(title);
+    }
+    item(text) {
+        this.lines.push(`  ${text}`);
+    }
+    problem(text) {
+        this.problems++;
+        this.lines.push(`  ✗ ${text}`);
+    }
+    text() {
+        return `${this.lines.join("\n")}\n`;
+    }
+}
+function probeLine(report, label, kind, path) {
+    const probe = probeConfigFile(kind, path);
+    if (!probe.exists) {
+        report.item(`${label}：${path}（不存在）`);
+        return;
+    }
+    if (!probe.ok) {
+        report.problem(`${label}：${probe.messages.join("; ")}`);
+        return;
+    }
+    report.item(`${label}：${path}`);
+    for (const message of probe.messages)
+        report.item(`  警告：${message}`);
+}
+function trustSection(report, io, level, flag) {
+    report.section("信任");
+    let trusted = false;
+    let from;
+    if (flag !== undefined) {
+        trusted = flag;
+        from = "命令行";
+    }
+    else if (level.profile?.trustProject === true) {
+        trusted = true;
+        from = "profile.trustProject";
+    }
+    else {
+        try {
+            const entry = findTrustEntry(readTrustFile(level.configDir).entries, io.cwd);
+            trusted = entry?.trusted ?? false;
+            from = entry === undefined ? "缺省：无记录，交互模式会询问" : `trust.json ${entry.path}`;
+        }
+        catch (error) {
+            report.problem(error.message);
+            from = "trust.json 无效";
+        }
+    }
+    report.item(`${io.cwd}：${trusted ? "已信任" : "未信任"}（${from}）`);
+    const gated = trustGatedResources(io.cwd);
+    if (gated.length > 0) {
+        report.item(`需要信任的资源${trusted ? "" : "（当前不加载）"}：`);
+        for (const path of gated)
+            report.item(`  ${path}`);
+    }
+    return trusted;
+}
+async function keySection(report, io, level, deps) {
+    report.section("Key 来源（只显示来源，不显示值）");
+    try {
+        const auth = readAuthFile(level.authFile);
+        const mode = fileMode(level.authFile);
+        if (!auth.exists)
+            report.item(`auth.json：${level.authFile}（不存在）`);
+        else if (isModeTooOpen(mode))
+            report.problem(`auth.json 权限 ${mode?.toString(8)}，应为 600：${level.authFile}`);
+        else
+            report.item(`auth.json：${level.authFile}`);
+    }
+    catch (error) {
+        report.problem(error.message);
+    }
+    if (deps !== undefined) {
+        try {
+            const registry = await buildRegistry(level, io, deps);
+            for (const provider of registry.list()) {
+                const key = await registry.resolveApiKey(provider.id);
+                const text = key.apiKey !== undefined
+                    ? `${key.source}${key.origin !== undefined ? `（${key.origin}）` : ""}`
+                    : provider.requiresApiKey
+                        ? "无"
+                        : "无需";
+                report.item(`${provider.id.padEnd(20)} ${text}`);
+                const env = baseUrlEnvOf(registry, provider.id);
+                if (env !== undefined)
+                    report.item(`${"".padEnd(20)} baseUrl 来自环境变量 ${env}：${provider.baseUrl}（compat 按保守缺省）`);
+            }
+            const model = await describeModel(level.merged.config, registry);
+            report.item(`将使用的模型：${model.ref ?? "（无）"}（${model.reason}）`);
+            return;
+        }
+        catch (error) {
+            report.problem(`供应商注册表：${error.message}`);
+        }
+    }
+    // 未装配注册表：按文件与环境变量名列出能看到的来源。
+    try {
+        for (const [id, entry] of Object.entries(readAuthFile(level.authFile).file.providers)) {
+            report.item(`${id.padEnd(20)} auth-file（${classifyKeyValue(entry.apiKey)}）`);
+        }
+    }
+    catch {
+        // 上面已报告
+    }
+    for (const [id, provider] of Object.entries(level.merged.config.providers ?? {})) {
+        if (provider.apiKey !== undefined) {
+            report.item(`${id.padEnd(20)} config（${classifyKeyValue(provider.apiKey)}）`);
+        }
+    }
+    const envNames = Object.keys(io.env)
+        .filter((n) => /_API_KEY$/.test(n) || n.startsWith("AMA_API_KEY_"))
+        .filter((n) => (io.env[n] ?? "") !== "")
+        .sort();
+    report.item(`环境变量：${envNames.length > 0 ? envNames.join(", ") : "（无）"}`);
+}
+function hookSection(report, io, level, trusted) {
+    report.section("Hook");
+    try {
+        const hooks = loadHookConfigs({
+            configDir: level.configDir,
+            cwd: io.cwd,
+            profileHooksFile: level.profile?.hooksFile,
+            trusted,
+            defaultTimeoutMs: level.merged.config.hooks?.timeoutMs,
+        });
+        if (hooks.hooks.length === 0)
+            report.item("（无）");
+        for (const hook of hooks.hooks) {
+            const matcher = hook.matcher !== undefined ? ` [${hook.matcher}]` : "";
+            report.item(`${hook.source.padEnd(7)} ${hook.event}${matcher} → ${hook.command}（${hook.timeoutMs} ms）`);
+        }
+        if (hooks.skippedProject !== undefined) {
+            report.item(`未信任，跳过：${hooks.skippedProject}`);
+        }
+    }
+    catch (error) {
+        report.problem(error.message);
+    }
+}
+function terminalSection(report, io) {
+    report.section("终端");
+    const env = io.env;
+    report.item(`stdin TTY：${io.stdinIsTTY ? "是" : "否"} · stdout TTY：${io.stdoutIsTTY ? "是" : "否"}`);
+    report.item(`TERM=${env["TERM"] ?? "（未设置）"} · COLORTERM=${env["COLORTERM"] ?? "（未设置）"}`);
+    if (env["NO_COLOR"] !== undefined)
+        report.item("NO_COLOR 已设置：不输出颜色");
+    if (env["TMUX"] !== undefined)
+        report.item("在 tmux 中运行");
+    const columns = process.stdout.columns;
+    if (io.stdoutIsTTY && columns !== undefined)
+        report.item(`尺寸：${columns}×${process.stdout.rows}`);
+    const tui = io.stdinIsTTY && io.stdoutIsTTY && env["TERM"] !== "dumb";
+    report.item(`缺省界面：${tui ? "终端界面" : "行式（--no-tui 等价）"}`);
+}
+export async function runDoctor(argv, io, deps) {
+    const { values, flags } = parseSubArgs(argv, ["profile", "auth-file"], ["trust", "no-trust"]);
+    if (flags.has("help")) {
+        io.stdout(DOCTOR_USAGE);
+        return ExitCode.Ok;
+    }
+    const report = new Report();
+    report.section(`ama ${AMA_VERSION} · Node ${process.version} · ${process.platform}-${process.arch}`);
+    let level;
+    try {
+        level = loadUserLevel(io, {
+            profile: values.get("profile"),
+            authFile: values.get("auth-file"),
+        });
+    }
+    catch (error) {
+        report.problem(error.message);
+        io.stdout(report.text());
+        return ExitCode.Config;
+    }
+    report.section("目录");
+    report.item(`配置目录：${level.configDir}`);
+    report.item(`数据目录：${level.dataDir}${existsSync(level.dataDir) ? "" : "（尚未创建）"}`);
+    report.section("配置层级（缺省 ← 用户级 ← profile ← 项目级（只能收紧）← 命令行）");
+    report.item("缺省：内置");
+    probeLine(report, "用户级", "config", level.userConfigPath);
+    if (level.profile !== undefined) {
+        report.item(`profile：${level.profile.path}`);
+        if (level.profile.configFile !== undefined)
+            probeLine(report, "profile.config", "config", level.profile.configFile);
+    }
+    const projectPath = projectFile(io.cwd, CONFIG_FILE);
+    probeLine(report, "项目级", "config", projectPath);
+    try {
+        const project = loadConfigFile("config", projectPath);
+        const merged = mergeProjectAndCli(level.merged, project?.value, undefined);
+        for (const warning of merged.warnings)
+            report.item(`  收紧：${warning}`);
+        report.item(`有效权限模式：${merged.config.permission?.mode ?? "default"}`);
+    }
+    catch {
+        // probeLine 已报告
+    }
+    for (const warning of level.warnings)
+        report.item(`警告：${warning}`);
+    const flag = flags.has("trust") ? true : flags.has("no-trust") ? false : undefined;
+    const trusted = trustSection(report, io, level, flag);
+    report.section("上下文文件（AGENTS.md，外层在前）");
+    const context = findContextFiles({ cwd: io.cwd, configDir: level.configDir });
+    if (context.files.length === 0)
+        report.item("（无）");
+    for (const file of context.files)
+        report.item(`${file.scope === "user" ? "用户级" : "项目"}  ${file.path}`);
+    await keySection(report, io, level, deps);
+    hookSection(report, io, level, trusted);
+    report.item(`用户级 hooks.json：${userFile(level, HOOKS_FILE)}`);
+    terminalSection(report, io);
+    io.stdout(report.text());
+    return report.problems > 0 ? ExitCode.Config : ExitCode.Ok;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * `ama init [--force]`（docs/providers.md「配置目录」）：建配置目录与缺省文件，逐个报告状态。
+ */
+import type { CliIo } from "../deps.js";
+export declare const INIT_USAGE = "\u7528\u6CD5\uFF1Aama init [--force]   \u5EFA\u914D\u7F6E\u76EE\u5F55\uFF080700\uFF09\u4E0E config.json\u3001config.schema.json\n                          \u5DF2\u6709\u7684 config.json \u4E0D\u8986\u76D6\uFF08--force \u5148\u5907\u4EFD\u4E3A .bak \u518D\u91CD\u5199\uFF09\uFF1B\u4E0D\u521B\u5EFA auth.json\n";
+export declare function runInit(argv: readonly string[], io: CliIo): number;

package/dist/cli/subcommands/init.js

@@ -0,0 +1,22 @@
+/**
+ * `ama init [--force]`（docs/providers.md「配置目录」）：建配置目录与缺省文件，逐个报告状态。
+ */
+import { describeInit, initConfigDir } from "../../config/init.js";
+import { resolveConfigDir } from "../../config/paths.js";
+import { parseSubArgs, UsageError } from "../args.js";
+import { ExitCode } from "../exit-codes.js";
+export const INIT_USAGE = `用法：ama init [--force]   建配置目录（0700）与 config.json、config.schema.json
+                          已有的 config.json 不覆盖（--force 先备份为 .bak 再重写）；不创建 auth.json
+`;
+export function runInit(argv, io) {
+    const { positionals, flags } = parseSubArgs(argv, [], ["force"]);
+    if (flags.has("help")) {
+        io.stdout(INIT_USAGE);
+        return ExitCode.Ok;
+    }
+    if (positionals.length > 0)
+        throw new UsageError(`多余的参数：${positionals.join(" ")}`);
+    const result = initConfigDir(resolveConfigDir({ env: io.env }), { force: flags.has("force") });
+    io.stdout(describeInit(result));
+    return ExitCode.Ok;
+}

package/dist/cli/subcommands/model-meta.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 模型元数据的一行描述（`ama models list`、`ama config show`、`ama providers`）：上下文、输出、思考、
+ * 图片、渠道，以及每个字段来自哪里（config / 目录 / models.dev / 缺省）与 models.dev 匹配。
+ */
+import { type ModelMetadata } from "../../ai/providers/enrich.js";
+import type { Model, ProviderRegistryApi } from "../../ai/types.js";
+export declare function compactTokens(n: number | undefined): string;
+/** 注册表若是 ProviderRegistry（或同形状），取模型元数据来源；否则 undefined。 */
+export declare function metadataOf(registry: ProviderRegistryApi, providerId: string, modelId: string): ModelMetadata | undefined;
+/** `ctx 262k · out 64k · 思考 · 图片 · 渠道 chat,messages`。 */
+export declare function modelFlags(model: Model): string;
+/**
+ * 来源说明：全部来自内置目录时返回 undefined（不刷屏）；否则
+ * `来源 ctx models.dev · out config · 图片 models.dev · …；models.dev 原厂 moonshotai/kimi-k2.5`。
+ */
+export declare function sourcesLine(metadata: ModelMetadata | undefined): string | undefined;

package/dist/cli/subcommands/model-meta.js

@@ -0,0 +1,54 @@
+/**
+ * 模型元数据的一行描述（`ama models list`、`ama config show`、`ama providers`）：上下文、输出、思考、
+ * 图片、渠道，以及每个字段来自哪里（config / 目录 / models.dev / 缺省）与 models.dev 匹配。
+ */
+import { sourceText } from "../../ai/providers/enrich.js";
+import { matchLabel } from "../../ai/providers/models-dev.js";
+export function compactTokens(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);
+}
+/** 注册表若是 ProviderRegistry（或同形状），取模型元数据来源；否则 undefined。 */
+export function metadataOf(registry, providerId, modelId) {
+    const r = registry;
+    return typeof r.modelMetadata === "function" ? r.modelMetadata(providerId, modelId) : undefined;
+}
+/** `ctx 262k · out 64k · 思考 · 图片 · 渠道 chat,messages`。 */
+export function modelFlags(model) {
+    return [
+        `ctx ${compactTokens(model.contextWindow)}`,
+        `out ${compactTokens(model.maxTokens)}`,
+        model.reasoning ? "思考" : undefined,
+        model.input.includes("image") ? "图片" : undefined,
+        model.channels !== undefined ? `渠道 ${model.channels.join(",")}` : undefined,
+    ]
+        .filter((x) => x !== undefined)
+        .join(" · ");
+}
+/**
+ * 来源说明：全部来自内置目录时返回 undefined（不刷屏）；否则
+ * `来源 ctx models.dev · out config · 图片 models.dev · …；models.dev 原厂 moonshotai/kimi-k2.5`。
+ */
+export function sourcesLine(metadata) {
+    if (metadata === undefined)
+        return undefined;
+    const values = Object.values(metadata.sources);
+    if (values.every((s) => s === "catalog" || s === "default") && !metadata.looked)
+        return undefined;
+    const label = {
+        contextWindow: "ctx",
+        maxTokens: "out",
+        input: "图片",
+        reasoning: "思考",
+        cost: "价格",
+    };
+    const parts = Object.keys(label).map((field) => `${label[field]} ${sourceText(metadata.sources[field])}`);
+    const match = metadata.looked ? `；models.dev ${matchLabel(metadata.match)}` : "";
+    const tools = metadata.toolCall === false ? "；不支持工具调用" : "";
+    return `来源 ${parts.join(" · ")}${match}${tools}`;
+}

package/dist/cli/subcommands/models-cache-probe.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `ama models cache-probe <provider/model>`（第三波 §1.11）：这个端点报不报缓存。[W3-C2]
+ *
+ * 固定前缀（system 一段确定性的编号句子，按字符 / 4 估到 `--tokens`，缺省 2048）+ user
+ * `Reply with: ok`，`maxTokens` 16、`cacheRetention: "short"`、`purpose: "probe"`，相隔 `--gap-ms`
+ * 发两次。判定：第二次 cacheRead ≥ 第一次前缀的 50% → `reported`；两次读写都是 0 → `silent`
+ * （字段缺失或恒 0）；其余（读到一点、只有写入）→ `inconclusive`（粒度或 TTL 问题）。
+ *
+ * 计费动作：执行前打印预估（两次 × `--tokens` × 目录输入价，无价 `$?`）；非 TTY 必须 `--yes`
+ * （否则退出 2），TTY 下问一次 y/N。`--json` 时预估写 stderr，stdout 只有一个结果对象。
+ * 协议层不保留原始响应，「usage 字段」列的是该协议解析时读取的字段名。
+ */
+import type { Api, Model, Usage } from "../../ai/types.js";
+import type { ModelsAction } from "./models.js";
+export declare const PROBE_DEFAULT_TOKENS = 2048;
+export declare const PROBE_DEFAULT_GAP_MS = 3000;
+export declare const PROBE_REQUEST_TIMEOUT_MS = 60000;
+export type ProbeVerdict = "reported" | "silent" | "inconclusive";
+export interface ProbeSample {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** 原始响应里出现过缓存字段（含 0）；协议没给出时 undefined。 */
+    cacheReported: boolean | undefined;
+    promptTokens: number;
+}
+/** 各协议解析缓存用量时读取的字段（`parseOpenAIUsage` 等）。 */
+export declare const USAGE_FIELDS: Readonly<Partial<Record<Api, readonly string[]>>>;
+/** 确定性前缀：编号句子，字符数 ≈ tokens × 4。 */
+export declare function probePrefix(tokens: number): string;
+export declare function sampleOf(usage: Usage): ProbeSample;
+export declare function judgeProbe(first: ProbeSample, second: ProbeSample): ProbeVerdict;
+export declare function probeAdvice(verdict: ProbeVerdict, model: Model, samples?: readonly ProbeSample[]): string | undefined;
+export declare const CACHE_PROBE_ACTION: ModelsAction;

package/dist/cli/subcommands/models-cache-probe.js

@@ -0,0 +1,190 @@
+/**
+ * `ama models cache-probe <provider/model>`（第三波 §1.11）：这个端点报不报缓存。[W3-C2]
+ *
+ * 固定前缀（system 一段确定性的编号句子，按字符 / 4 估到 `--tokens`，缺省 2048）+ user
+ * `Reply with: ok`，`maxTokens` 16、`cacheRetention: "short"`、`purpose: "probe"`，相隔 `--gap-ms`
+ * 发两次。判定：第二次 cacheRead ≥ 第一次前缀的 50% → `reported`；两次读写都是 0 → `silent`
+ * （字段缺失或恒 0）；其余（读到一点、只有写入）→ `inconclusive`（粒度或 TTL 问题）。
+ *
+ * 计费动作：执行前打印预估（两次 × `--tokens` × 目录输入价，无价 `$?`）；非 TTY 必须 `--yes`
+ * （否则退出 2），TTY 下问一次 y/N。`--json` 时预估写 stderr，stdout 只有一个结果对象。
+ * 协议层不保留原始响应，「usage 字段」列的是该协议解析时读取的字段名。
+ */
+import { createInterface } from "node:readline/promises";
+import { priceTokens } from "../../ai/cost.js";
+import { UsageError } from "../args.js";
+import { ExitCode } from "../exit-codes.js";
+export const PROBE_DEFAULT_TOKENS = 2048;
+export const PROBE_DEFAULT_GAP_MS = 3000;
+export const PROBE_REQUEST_TIMEOUT_MS = 60_000;
+/** 各协议解析缓存用量时读取的字段（`parseOpenAIUsage` 等）。 */
+export const USAGE_FIELDS = {
+    "openai-completions": [
+        "prompt_tokens_details.cached_tokens",
+        "prompt_cache_hit_tokens",
+        "cached_tokens",
+        "prompt_tokens_details.cache_write_tokens",
+    ],
+    "openai-responses": ["input_tokens_details.cached_tokens"],
+    "anthropic-messages": ["cache_read_input_tokens", "cache_creation_input_tokens"],
+    "google-generative-ai": ["usageMetadata.cachedContentTokenCount"],
+};
+/** 确定性前缀：编号句子，字符数 ≈ tokens × 4。 */
+export function probePrefix(tokens) {
+    const lines = [];
+    let chars = 0;
+    for (let i = 1; chars < tokens * 4; i++) {
+        const line = `Reference line ${i}: cache probe filler text that stays byte-identical between requests.`;
+        lines.push(line);
+        chars += line.length + 1;
+    }
+    return lines.join("\n");
+}
+export function sampleOf(usage) {
+    return {
+        input: usage.input,
+        cacheRead: usage.cacheRead,
+        cacheWrite: usage.cacheWrite,
+        cacheReported: usage.cacheReported,
+        promptTokens: usage.input + usage.cacheRead + usage.cacheWrite,
+    };
+}
+export function judgeProbe(first, second) {
+    if (first.promptTokens > 0 && second.cacheRead >= first.promptTokens * 0.5)
+        return "reported";
+    const any = first.cacheRead + first.cacheWrite + second.cacheRead + second.cacheWrite;
+    return any === 0 ? "silent" : "inconclusive";
+}
+export function probeAdvice(verdict, model, samples = []) {
+    if (verdict === "silent") {
+        // 实测：同一中转的 Kimi 间隔 3 s 两次都是 0、间隔更久才命中——字段存在时提示写入延迟的可能
+        const present = samples.some((s) => s.cacheReported === true)
+            ? "（响应里有缓存字段但恒为 0；也可能是缓存写入有延迟，可加大 --gap-ms 再测一次）"
+            : "";
+        return `可在 config 里设 providers.${model.provider}.compat.cacheReporting: "silent"，状态栏将显示未报告${present}`;
+    }
+    if (verdict === "inconclusive")
+        return "第二次只读到少量缓存或只有写入：可能是缓存粒度或 TTL 问题，可加大 --tokens 或缩短 --gap-ms 重试";
+    if (model.promptCache === undefined)
+        return `可自填 promptCache.short 以启用保温（providers.${model.provider}.modelOverrides: [{ "id": "${model.id}", "promptCache": { "short": 300 } }]）`;
+    return undefined;
+}
+function intOption(ctx, name, fallback, min) {
+    const raw = ctx.values.get(name);
+    if (raw === undefined)
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < min)
+        throw new UsageError(`--${name} 应为不小于 ${min} 的整数`);
+    return value;
+}
+async function confirm() {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return /^y(es)?$/i.test((await rl.question("继续？[y/N] ")).trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+function sampleLine(index, s) {
+    const field = s.cacheReported === undefined ? "?" : s.cacheReported ? "有" : "无";
+    return `#${index}  input ${s.input} · cacheRead ${s.cacheRead} · cacheWrite ${s.cacheWrite} · 缓存字段 ${field}`;
+}
+async function run(ctx) {
+    const { io, registry } = ctx;
+    const ref = ctx.args[0] ?? "";
+    const tokens = intOption(ctx, "tokens", PROBE_DEFAULT_TOKENS, 1);
+    const gapMs = intOption(ctx, "gap-ms", PROBE_DEFAULT_GAP_MS, 0);
+    const json = ctx.flags.has("json");
+    const found = registry.findModel(ref);
+    if (!found.ok) {
+        io.stderr(`ama: 模型不存在：${ref}\n`);
+        return ExitCode.NoModel;
+    }
+    const { model, provider } = found;
+    const key = await registry.resolveApiKey(provider.id, model.channel);
+    if (key.apiKey === undefined && provider.requiresApiKey) {
+        io.stderr(`ama: ${provider.id} 没有 API key（ama auth set ${provider.id}）\n`);
+        return ExitCode.NoModel;
+    }
+    const api = registry.getApi(model.api);
+    if (api === undefined) {
+        io.stderr(`ama: 协议 ${model.api} 尚未实现\n`);
+        return ExitCode.RuntimeError;
+    }
+    const estimate = priceTokens(model, { input: tokens * 2, output: 32 });
+    const name = `${provider.id}/${model.id}`;
+    const head = `cache-probe ${name}（${model.api}）· 前缀约 ${tokens} token · 间隔 ${gapMs} ms\n预估花费：${estimate === undefined ? "$?" : `$${estimate.toFixed(4)}`}（两次 × ${tokens} token × 目录价）\n`;
+    (json ? io.stderr : io.stdout)(head);
+    if (!ctx.flags.has("yes")) {
+        if (!io.stdinIsTTY) {
+            io.stderr("ama: cache-probe 会发两次计费请求，非交互环境需加 --yes\n");
+            return ExitCode.Usage;
+        }
+        if (!(await confirm())) {
+            io.stderr("ama: 已取消\n");
+            return ExitCode.Ok;
+        }
+    }
+    const messages = [
+        { role: "system", sections: { probe: probePrefix(tokens) }, timestamp: 0 },
+        { role: "user", content: "Reply with: ok", timestamp: 0 },
+    ];
+    const samples = [];
+    for (let i = 0; i < 2; i++) {
+        if (i > 0 && gapMs > 0)
+            await new Promise((r) => setTimeout(r, gapMs));
+        const message = await api
+            .stream(model, { messages }, {
+            signal: AbortSignal.timeout(PROBE_REQUEST_TIMEOUT_MS),
+            ...(key.apiKey !== undefined ? { apiKey: key.apiKey } : {}),
+            maxTokens: 16,
+            cacheRetention: "short",
+            purpose: "probe",
+        })
+            .result();
+        if (message.stopReason === "error" || message.stopReason === "aborted") {
+            io.stderr(`ama: 第 ${i + 1} 次请求失败：${message.errorMessage ?? message.stopReason}\n`);
+            return ExitCode.RuntimeError;
+        }
+        samples.push(sampleOf(message.usage));
+    }
+    const [first, second] = samples;
+    const verdict = judgeProbe(first, second);
+    const advice = probeAdvice(verdict, model, samples);
+    const fields = USAGE_FIELDS[model.api] ?? [];
+    if (json) {
+        const result = {
+            model: name,
+            api: model.api,
+            tokens,
+            gapMs,
+            estimatedCostUsd: estimate ?? null,
+            requests: samples,
+            usageFields: fields,
+            verdict,
+            ...(advice !== undefined ? { advice } : {}),
+        };
+        io.stdout(`${JSON.stringify(result)}\n`);
+        return ExitCode.Ok;
+    }
+    const share = first.promptTokens > 0
+        ? `（第二次读到前缀的 ${Math.round((second.cacheRead / first.promptTokens) * 100)}%）`
+        : "";
+    io.stdout([
+        sampleLine(1, first),
+        sampleLine(2, second),
+        ...(fields.length > 0 ? [`usage 字段（${model.api} 读取）：${fields.join(" / ")}`] : []),
+        `判定：${verdict}${share}`,
+        ...(advice !== undefined ? [`建议：${advice}`] : []),
+    ].join("\n") + "\n");
+    return ExitCode.Ok;
+}
+export const CACHE_PROBE_ACTION = {
+    usage: "ama models cache-probe <provider/id> [--tokens 2048] [--gap-ms 3000] [--json] [--yes]",
+    required: "<provider/id>",
+    valueOptions: ["tokens", "gap-ms"],
+    flagOptions: ["json", "yes"],
+    run,
+};

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

@@ -0,0 +1,46 @@
+/**
+ * `ama models discover <provider>`（第三波 §2.3）：问中转站有哪些模型。[W3-B12]
+ *
+ * GET `{baseUrl}/models`（anthropic-messages 且 baseUrl 不以 `/v1` 结尾时为 `{baseUrl}/v1/models`），
+ * 带供应商的鉴权头，打印 id 列表并标出已配置的条目。
+ *
+ * `--probe`：同一中转下不同模型支持的协议不同，对每个 id 依次试供应商协议 → completions →
+ * responses → messages（去重），各发一次最小请求（`ama models check` 同款，maxTokens 16），
+ * 记第一个成功的协议；每模型最多 3 次请求，`--limit`（缺省 30）限制探测的模型数，执行前打印
+ * 预估；401 / 403 / 429 立即停止（key 无效或被限流，继续只会浪费请求）。
+ *
+ * `--write`：新条目合并进用户级 config.json 的 `providers.<id>.models`——已有同 id 不覆盖；只写
+ * `id` 与探到的 `api`（与供应商协议相同时省略）；带 `--probe` 时只写探测成功的模型。不猜
+ * `contextWindow`（自动压缩随之关闭，输出 warning）。写前备份为 `config.json.bak`。
+ *
+ * models.dev：列表之后按需刷新缓存（24 小时内不重拉），每个模型标出上下文、输出、图片、工具调用与
+ * 匹配结果；`--write` 跳过 models.dev 标明不支持工具调用的模型。元数据不写进配置——运行时从缓存补。
+ */
+import 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[];
+/** 模型列表的 URL：OpenAI 系是 `{baseUrl}/models`；Anthropic 官方形状的 baseUrl 不带 `/v1`。 */
+export declare function modelsUrl(provider: ProviderData): string;
+export declare function discoverModels(provider: ProviderData, apiKey: string | undefined, options?: {
+    timeoutMs?: number;
+}): Promise<Model[]>;
+export declare function probeOrder(provider: ProviderData): Api[];
+export interface ProbeOptions {
+    timeoutMs?: number;
+    /** 每次请求后回调。 */
+    onAttempt?: (id: string, api: Api, error: string | undefined) => void;
+    /** 每个模型探完回调（进度输出）。 */
+    onResult?: (id: string, api: Api | undefined) => void;
+    /** 因鉴权失败或限流提前停止时回调。 */
+    onStop?: (reason: string) => void;
+}
+export declare const FATAL_STATUS: RegExp;
+/** 返回已探测模型 → 第一个成功的协议（都失败为 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;