@armadra/agent 0.0.0-stage → 0.2.1

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);
+    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,40 @@
+/**
+ * `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`。
+ */
+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;
+}
+/** 返回已探测模型 → 第一个成功的协议（都失败为 undefined）；超出 `limit` 或提前停止的不在表里。 */
+export declare function probeModelApis(registry: ProviderRegistryApi, provider: ProviderData, ids: string[], limit: number, options?: ProbeOptions): Promise<Map<string, Api | undefined>>;
+export declare const DISCOVER_ACTION: ModelsAction;

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

@@ -0,0 +1,204 @@
+/**
+ * `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`。
+ */
+import { authHeaders, mergeHeaders } from "../../ai/http.js";
+import { discoverLocalModels, materializeModel } from "../../ai/providers/registry.js";
+import { withCustomDefaults } from "../../ai/providers/catalog.js";
+import { existsSync } from "node:fs";
+import { loadConfigFile } from "../../config/load.js";
+import { writeConfigFile } from "../../config/write.js";
+import { UsageError } from "../args.js";
+import { ExitCode } from "../exit-codes.js";
+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";
+/** 中转常见的三种协议，按此顺序探测（供应商协议排最前）。 */
+export const PROBE_APIS = [
+    "openai-completions",
+    "openai-responses",
+    "anthropic-messages",
+];
+/** 模型列表的 URL：OpenAI 系是 `{baseUrl}/models`；Anthropic 官方形状的 baseUrl 不带 `/v1`。 */
+export function modelsUrl(provider) {
+    const base = provider.baseUrl.replace(/\/+$/, "");
+    if (provider.api === "anthropic-messages" && !/\/v1$/.test(base))
+        return `${base}/v1/models`;
+    return `${base}/models`;
+}
+export async function discoverModels(provider, apiKey, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DISCOVER_TIMEOUT_MS;
+    if (!provider.requiresApiKey && apiKey === undefined)
+        return discoverLocalModels(provider, { timeoutMs });
+    const anthropic = provider.api === "anthropic-messages";
+    const headers = mergeHeaders(provider.headers, anthropic ? { "anthropic-version": ANTHROPIC_VERSION } : {}, authHeaders(apiKey, provider.authHeader, anthropic ? "x-api-key" : "authorization-bearer"));
+    return discoverLocalModels(provider, { timeoutMs, url: modelsUrl(provider), headers });
+}
+export function probeOrder(provider) {
+    return PROBE_APIS.includes(provider.api)
+        ? [provider.api, ...PROBE_APIS.filter((api) => api !== provider.api)]
+        : [...PROBE_APIS];
+}
+const FATAL_STATUS = /^(?:HTTP )?(?:401|403|429)\b/;
+/** 返回已探测模型 → 第一个成功的协议（都失败为 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 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;
+            }
+        }
+        result.set(id, found);
+        options.onResult?.(id, found);
+    }
+    return result;
+}
+/** 一次最小请求；成功返回 undefined，失败返回错误文本。 */
+async function attempt(registry, model, apiKey, timeoutMs = PROBE_TIMEOUT_MS) {
+    const impl = registry.getApi(model.api);
+    if (impl === undefined)
+        return `协议 ${model.api} 尚未实现`;
+    try {
+        const message = await impl
+            .stream(model, { messages: [{ role: "user", content: "Reply with: ok", timestamp: Date.now() }] }, {
+            signal: AbortSignal.timeout(timeoutMs),
+            ...(apiKey !== undefined ? { apiKey } : {}),
+            maxTokens: 16,
+            cacheRetention: "none",
+        })
+            .result();
+        if (message.stopReason === "error" || message.stopReason === "aborted")
+            return message.errorMessage ?? message.stopReason;
+        return undefined;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+function parseLimit(raw) {
+    if (raw === undefined)
+        return DEFAULT_PROBE_LIMIT;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1)
+        throw new UsageError(`--limit 需要正整数：${raw}`);
+    return n;
+}
+/** 把新条目合并进用户级 config.json；返回写入条数。 */
+function writeEntries(ctx, provider, entries) {
+    const { io } = ctx;
+    const path = ctx.level.userConfigPath;
+    const config = structuredClone(loadConfigFile("config", path)?.value ?? { version: 1 });
+    const providers = (config.providers ??= {});
+    if (providers[provider.id] === undefined && !provider.builtin) {
+        io.stderr(`ama: ${provider.id} 不在用户级配置（${path}）里，未写入\n`);
+        return 0;
+    }
+    const target = (providers[provider.id] ??= {});
+    const models = (target.models ??= []);
+    const existing = new Set([...models.map((m) => m.id), ...provider.models.map((m) => m.id)]);
+    const added = entries.filter((entry) => !existing.has(entry.id));
+    const kept = entries.length - added.length;
+    if (added.length === 0) {
+        io.stdout(`\n没有新模型要写入${kept > 0 ? `（${kept} 个已存在，未覆盖）` : ""}\n`);
+        return 0;
+    }
+    models.push(...added);
+    const backup = existsSync(path);
+    writeConfigFile(path, config, { backup: true });
+    io.stdout(`\n已写入 ${path}：${provider.id} 新增 ${added.length} 个模型` +
+        `${kept > 0 ? `，${kept} 个已存在未覆盖` : ""}${backup ? `（原文件备份为 ${path}.bak）` : ""}\n`);
+    io.stderr(`ama: 警告：新增模型未设 contextWindow，自动压缩关闭；需要时在 config.json 里补上\n`);
+    return added.length;
+}
+async function run(ctx) {
+    const { io, registry } = ctx;
+    const id = ctx.args[0] ?? "";
+    const limit = parseLimit(ctx.values.get("limit"));
+    const provider = registry.get(id);
+    if (provider === undefined) {
+        io.stderr(`ama: 供应商不存在：${id}\n`);
+        return ExitCode.NoModel;
+    }
+    const key = await registry.resolveApiKey(provider.id);
+    if (key.apiKey === undefined && provider.requiresApiKey) {
+        io.stderr(`ama: ${provider.id} 没有 API key（ama auth set ${provider.id}）\n`);
+        return ExitCode.NoModel;
+    }
+    let found;
+    try {
+        found = await discoverModels(provider, key.apiKey);
+    }
+    catch (error) {
+        io.stderr(`ama: ${provider.id} 模型列表获取失败：${error.message}\n`);
+        return ExitCode.RuntimeError;
+    }
+    const configured = new Map(provider.models.map((m) => [m.id, m]));
+    io.stdout(`${provider.id}：发现 ${found.length} 个模型（${modelsUrl(provider)}）\n`);
+    for (const model of found) {
+        const known = configured.get(model.id);
+        io.stdout(`  ${model.id}${known !== undefined ? `  已配置（${known.api}）` : ""}\n`);
+    }
+    const write = ctx.flags.has("write");
+    if (!ctx.flags.has("probe")) {
+        if (write)
+            writeEntries(ctx, provider, found.map((m) => ({ id: m.id })));
+        return ExitCode.Ok;
+    }
+    const ids = found.map((m) => m.id);
+    const count = Math.min(limit, ids.length);
+    const order = probeOrder(provider);
+    io.stdout(`\n探测协议：${count} 个模型（${order.join(" → ")}），最多 ${count * order.length} 次请求` +
+        `${ids.length > count ? `；另有 ${ids.length - count} 个超出 --limit ${limit}，未探测` : ""}\n`);
+    let stopped;
+    const probed = await probeModelApis(registry, provider, ids, limit, {
+        onResult: (modelId, api) => io.stdout(`  ${modelId}  ${api ?? "不可用（三种协议均失败）"}\n`),
+        onStop: (reason) => (stopped = reason),
+    });
+    if (write) {
+        const entries = [];
+        for (const [modelId, api] of probed) {
+            if (api !== undefined)
+                entries.push(api === provider.api ? { id: modelId } : { id: modelId, api });
+        }
+        writeEntries(ctx, provider, entries);
+    }
+    if (stopped !== undefined) {
+        io.stderr(`ama: 探测提前停止（${stopped}）\n`);
+        return ExitCode.RuntimeError;
+    }
+    return ExitCode.Ok;
+}
+export const DISCOVER_ACTION = {
+    usage: "ama models discover <provider> [--probe] [--write] [--limit <n>]",
+    required: "<provider>",
+    valueOptions: ["limit"],
+    flagOptions: ["probe", "write"],
+    run,
+};

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

@@ -0,0 +1,40 @@
+/**
+ * `ama models list [--provider <id>]`、`ama models check <provider/id>`（设计 §1.2、R6）。[B5]
+ *
+ * 注册表经 RuntimeDeps.providers 注入（B1）。check 发一次最小调用（一条 user 消息、
+ * maxTokens 16、超时 30 s），只报告成败与 stopReason，不输出 key。
+ *
+ * [W3-C0] 子命令分派改为动作表 `MODELS_ACTIONS`（第三波 §1.11 / §2.3）：新动作（C2 的
+ * `cache-probe`、B12 的 `discover`）各写在自己的文件里，这里只加一行表项；用法文本、
+ * 选项表与必填位置参数都从表里来。
+ */
+import type { ProviderRegistryApi } from "../../ai/types.js";
+import type { CliIo, RuntimeDeps } from "../deps.js";
+import { type UserLevel } from "./context.js";
+/** 动作执行时拿到的上下文（参数已按表解析、注册表已构造）。 */
+export interface ModelsActionContext {
+    io: CliIo;
+    registry: ProviderRegistryApi;
+    /** 用户级（+ profile）配置；写配置的动作（`discover --write`）要用 `userConfigPath`。 */
+    level: UserLevel;
+    /** 动作名之后的位置参数。 */
+    args: readonly string[];
+    values: ReadonlyMap<string, string>;
+    flags: ReadonlySet<string>;
+}
+export interface ModelsAction {
+    /** 用法行（不含「ama models 」前缀之前的「用法：」）。 */
+    usage: string;
+    /** 带值选项（不含共用的 --profile / --auth-file）。 */
+    valueOptions?: readonly string[];
+    /** 布尔选项。 */
+    flagOptions?: readonly string[];
+    /** 必填的第一个位置参数，缺失时报「ama models <动作> 需要 <required>」。 */
+    required?: string;
+    run(ctx: ModelsActionContext): Promise<number>;
+}
+export declare const CHECK_TIMEOUT_MS = 30000;
+/** 动作表：键是子命令名，顺序即用法文本顺序。 */
+export declare const MODELS_ACTIONS: Readonly<Record<string, ModelsAction>>;
+export declare const MODELS_USAGE: string;
+export declare function runModels(argv: readonly string[], io: CliIo, deps: Pick<RuntimeDeps, "providers"> | undefined): Promise<number>;

package/dist/cli/subcommands/models.js

@@ -0,0 +1,144 @@
+/**
+ * `ama models list [--provider <id>]`、`ama models check <provider/id>`（设计 §1.2、R6）。[B5]
+ *
+ * 注册表经 RuntimeDeps.providers 注入（B1）。check 发一次最小调用（一条 user 消息、
+ * maxTokens 16、超时 30 s），只报告成败与 stopReason，不输出 key。
+ *
+ * [W3-C0] 子命令分派改为动作表 `MODELS_ACTIONS`（第三波 §1.11 / §2.3）：新动作（C2 的
+ * `cache-probe`、B12 的 `discover`）各写在自己的文件里，这里只加一行表项；用法文本、
+ * 选项表与必填位置参数都从表里来。
+ */
+import { parseSubArgs, UsageError } from "../args.js";
+import { ExitCode } from "../exit-codes.js";
+import { buildRegistry, loadUserLevel } from "./context.js";
+import { CACHE_PROBE_ACTION } from "./models-cache-probe.js";
+import { DISCOVER_ACTION } from "./models-discover.js";
+const COMMON_VALUE_OPTIONS = ["profile", "auth-file"];
+export const CHECK_TIMEOUT_MS = 30_000;
+function compact(n) {
+    if (n === undefined)
+        return "?";
+    if (n >= 1_000_000)
+        return `${Math.round(n / 100_000) / 10}M`;
+    if (n >= 1000)
+        return `${Math.round(n / 1000)}k`;
+    return String(n);
+}
+async function list(io, registry, only) {
+    const providers = registry.list().filter((p) => only === undefined || p.id === only);
+    if (only !== undefined && providers.length === 0) {
+        io.stderr(`ama: 供应商不存在：${only}\n`);
+        return ExitCode.NoModel;
+    }
+    for (const provider of providers) {
+        const key = await registry.resolveApiKey(provider.id);
+        const keyText = key.apiKey !== undefined
+            ? `key：${key.source}${key.origin !== undefined ? `（${key.origin}）` : ""}`
+            : provider.requiresApiKey
+                ? "无 key"
+                : "无需 key";
+        io.stdout(`${provider.id}  ${provider.api}  ${keyText}\n`);
+        for (const model of provider.models) {
+            const flags = [
+                `ctx ${compact(model.contextWindow)}`,
+                `out ${compact(model.maxTokens)}`,
+                model.reasoning ? "思考" : undefined,
+                model.input.includes("image") ? "图片" : undefined,
+            ].filter((x) => x !== undefined);
+            io.stdout(`  ${provider.id}/${model.id}  ${flags.join(" · ")}\n`);
+        }
+    }
+    return ExitCode.Ok;
+}
+async function check(io, registry, ref) {
+    const found = registry.findModel(ref);
+    if (!found.ok) {
+        const hint = found.candidates.length > 0 ? `；候选：${found.candidates.slice(0, 10).join(", ")}` : "";
+        io.stderr(`ama: 模型不存在：${ref}${hint}\n`);
+        return ExitCode.NoModel;
+    }
+    const { model, provider } = found;
+    const key = await registry.resolveApiKey(provider.id);
+    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 started = Date.now();
+    const stream = api.stream(model, { messages: [{ role: "user", content: "Reply with: ok", timestamp: Date.now() }] }, {
+        signal: AbortSignal.timeout(CHECK_TIMEOUT_MS),
+        ...(key.apiKey !== undefined ? { apiKey: key.apiKey } : {}),
+        maxTokens: 16,
+        cacheRetention: "none",
+    });
+    const message = await stream.result();
+    const ms = Date.now() - started;
+    if (message.stopReason === "error" || message.stopReason === "aborted") {
+        io.stderr(`ama: ${provider.id}/${model.id} 失败（${ms} ms）：${message.errorMessage ?? message.stopReason}\n`);
+        return ExitCode.RuntimeError;
+    }
+    io.stdout(`${provider.id}/${model.id} 可用（${ms} ms，stopReason ${message.stopReason}）\n`);
+    return ExitCode.Ok;
+}
+/** 动作表：键是子命令名，顺序即用法文本顺序。 */
+export const MODELS_ACTIONS = Object.freeze({
+    list: {
+        usage: "ama models list [--provider <id>]",
+        valueOptions: ["provider"],
+        run: (ctx) => list(ctx.io, ctx.registry, ctx.values.get("provider")),
+    },
+    check: {
+        usage: "ama models check <provider/id>",
+        required: "<provider/id>",
+        run: (ctx) => check(ctx.io, ctx.registry, ctx.args[0] ?? ""),
+    },
+    discover: DISCOVER_ACTION,
+    "cache-probe": CACHE_PROBE_ACTION,
+});
+export const MODELS_USAGE = `用法：${Object.values(MODELS_ACTIONS)
+    .map((a) => a.usage)
+    .join("\n      ")}\n`;
+function unique(lists) {
+    return [...new Set(lists.flatMap((l) => l ?? []))];
+}
+export async function runModels(argv, io, deps) {
+    const actions = Object.values(MODELS_ACTIONS);
+    const { positionals, values, flags } = parseSubArgs(argv, unique([...actions.map((a) => a.valueOptions), COMMON_VALUE_OPTIONS]), unique(actions.map((a) => a.flagOptions)));
+    const name = positionals[0];
+    if (flags.has("help") || name === undefined) {
+        io.stdout(MODELS_USAGE);
+        return flags.has("help") ? ExitCode.Ok : ExitCode.Usage;
+    }
+    const action = Object.hasOwn(MODELS_ACTIONS, name) ? MODELS_ACTIONS[name] : undefined;
+    if (action === undefined)
+        throw new UsageError(`未知的 models 子命令：${name}`);
+    // 选项按全部动作的并集解析；这里再拒绝不属于本动作的（如 `list --json`）。
+    for (const option of [...values.keys(), ...flags]) {
+        const own = [
+            ...COMMON_VALUE_OPTIONS,
+            ...(action.valueOptions ?? []),
+            ...(action.flagOptions ?? []),
+        ];
+        if (!own.includes(option))
+            throw new UsageError(`未知选项：--${option}`);
+    }
+    const args = positionals.slice(1);
+    if (action.required !== undefined && args[0] === undefined)
+        throw new UsageError(`ama models ${name} 需要 ${action.required}`);
+    if (deps === undefined) {
+        io.stderr("ama: models 尚未装配（供应商注册表由集成批次注入）\n");
+        return ExitCode.RuntimeError;
+    }
+    const level = loadUserLevel(io, {
+        profile: values.get("profile"),
+        authFile: values.get("auth-file"),
+    });
+    for (const warning of level.warnings)
+        io.stderr(`ama: 警告：${warning}\n`);
+    const registry = await buildRegistry(level, io, deps);
+    return action.run({ io, registry, level, args, values, flags });
+}

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

@@ -0,0 +1,11 @@
+/**
+ * `ama sessions list|show|prune`（设计 §1.2、§8）。[B5]
+ *
+ * 会话存储是 B2 的实现，经 RuntimeDeps.sessions 注入；这里只做参数、目录解析与输出格式。
+ * - list [--all]：缺省只列当前目录的会话；`--all` 列全部。
+ * - show <id>：头信息 + 条目类型统计 + 首条提示。
+ * - prune [--older-than <天>] [--dry-run]：缺省 30 天，移到 trash（不删除）。
+ */
+import type { CliIo, RuntimeDeps } from "../deps.js";
+export declare const SESSIONS_USAGE = "\u7528\u6CD5\uFF1Aama sessions list [--all] [--session-dir <\u76EE\u5F55>]\n      ama sessions show <id> [--session-dir <\u76EE\u5F55>]\n      ama sessions prune [--older-than <\u5929>] [--dry-run] [--all] [--session-dir <\u76EE\u5F55>]\n";
+export declare function runSessions(argv: readonly string[], io: CliIo, deps: Pick<RuntimeDeps, "sessions"> | undefined): Promise<number>;