@armadra/agent 0.3.0 → 0.4.0

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 { 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) => {
@@ -314,9 +298,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 +334,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;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * `ama sessions search <关键词|/正则/>`：跨会话全文检索（只读）。[W4-D]
+ *
+ * - 范围：缺省当前目录的会话，`--all` 全部；`--role user|assistant|tool`（可逗号分隔多个）；
+ *   `--since 7d|today|YYYY-MM-DD`；`--limit N`（缺省 20）；`--json` 每条命中一行 JSON。
+ * - 输出一行一条：会话 id 前 8 位、条目时间、项目、角色与编号（user 是 `#n`，可直接给 `--from <id>#n`；
+ *   其它角色是条目序号 `@k`）、命中片段。stdout 是 TTY 且没设 NO_COLOR 时用 ANSI 高亮，否则纯文本。
+ */
+import { type SearchHit } from "../../session/search.js";
+import type { CliIo } from "../deps.js";
+export declare const SESSIONS_SEARCH_USAGE = "\u7528\u6CD5\uFF1Aama sessions search <\u5173\u952E\u8BCD|/\u6B63\u5219/\u6807\u5FD7> [--all] [--role user|assistant|tool]\n                            [--since 7d|today|YYYY-MM-DD] [--limit N] [--json] [--session-dir <\u76EE\u5F55>]\n";
+export declare function renderHit(hit: SearchHit, color: boolean): string;
+export declare function runSessionsSearch(argv: readonly string[], io: CliIo): Promise<number>;

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

@@ -0,0 +1,103 @@
+/**
+ * `ama sessions search <关键词|/正则/>`：跨会话全文检索（只读）。[W4-D]
+ *
+ * - 范围：缺省当前目录的会话，`--all` 全部；`--role user|assistant|tool`（可逗号分隔多个）；
+ *   `--since 7d|today|YYYY-MM-DD`；`--limit N`（缺省 20）；`--json` 每条命中一行 JSON。
+ * - 输出一行一条：会话 id 前 8 位、条目时间、项目、角色与编号（user 是 `#n`，可直接给 `--from <id>#n`；
+ *   其它角色是条目序号 `@k`）、命中片段。stdout 是 TTY 且没设 NO_COLOR 时用 ANSI 高亮，否则纯文本。
+ */
+import { join, resolve } from "node:path";
+import { expandHome, resolveDataDir } from "../../config/paths.js";
+import { sessionFilesInScope } from "../../session/scan.js";
+import { compileQuery, searchSessions, } from "../../session/search.js";
+import { parseSubArgs, UsageError } from "../args.js";
+import { ExitCode } from "../exit-codes.js";
+import { parseDaySpec } from "./stats.js";
+export const SESSIONS_SEARCH_USAGE = `用法：ama sessions search <关键词|/正则/标志> [--all] [--role user|assistant|tool]
+                            [--since 7d|today|YYYY-MM-DD] [--limit N] [--json] [--session-dir <目录>]
+`;
+const ROLES = ["user", "assistant", "tool"];
+function highlight(text, ranges, color) {
+    if (!color || ranges.length === 0)
+        return text;
+    let out = "";
+    let at = 0;
+    for (const [a, b] of ranges) {
+        if (a < at)
+            continue;
+        out += text.slice(at, a) + `\x1b[1;33m${text.slice(a, b)}\x1b[0m`;
+        at = b;
+    }
+    return out + text.slice(at);
+}
+function shortTime(iso) {
+    return iso
+        .replace("T", " ")
+        .replace(/\.\d+Z$|Z$/, "")
+        .slice(0, 16);
+}
+export function renderHit(hit, color) {
+    const ref = hit.userN !== undefined ? `#${hit.userN}` : `@${hit.entryIndex}`;
+    const dim = (s) => (color ? `\x1b[2m${s}\x1b[0m` : s);
+    return `${hit.sessionId.slice(0, 8)}${ref.padEnd(4)}  ${dim(shortTime(hit.timestamp))}  ${dim(hit.cwd)}  ${hit.role.padEnd(9)}  ${highlight(hit.snippet, hit.ranges, color)}\n`;
+}
+export async function runSessionsSearch(argv, io) {
+    const { positionals, values, flags } = parseSubArgs(argv, ["role", "since", "limit", "session-dir"], ["all", "json"]);
+    if (flags.has("help")) {
+        io.stdout(SESSIONS_SEARCH_USAGE);
+        return ExitCode.Ok;
+    }
+    const pattern = positionals.join(" ");
+    if (pattern.trim() === "")
+        throw new UsageError("ama sessions search 需要关键词或 /正则/");
+    let query;
+    try {
+        query = compileQuery(pattern);
+    }
+    catch (error) {
+        throw new UsageError(`正则无效：${error.message}`);
+    }
+    let roles;
+    const roleRaw = values.get("role");
+    if (roleRaw !== undefined) {
+        roles = new Set();
+        for (const role of roleRaw.split(",").map((r) => r.trim())) {
+            if (!ROLES.includes(role)) {
+                throw new UsageError(`--role 的取值应为 ${ROLES.join(" | ")}（收到 ${role}）`);
+            }
+            roles.add(role);
+        }
+    }
+    const limit = Number(values.get("limit") ?? "20");
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new UsageError("--limit 应为正整数");
+    const sinceRaw = values.get("since");
+    const sinceIso = sinceRaw === undefined
+        ? undefined
+        : new Date(`${parseDaySpec("since", sinceRaw)}T00:00:00`).toISOString();
+    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 files = sessionFilesInScope(root, flags.has("all") ? undefined : io.cwd);
+    const { hits, truncated } = searchSessions(files, query, {
+        limit,
+        ...(roles !== undefined ? { roles } : {}),
+        ...(sinceIso !== undefined ? { sinceIso } : {}),
+    });
+    if (flags.has("json")) {
+        for (const hit of hits)
+            io.stdout(`${JSON.stringify(hit)}\n`);
+        return ExitCode.Ok;
+    }
+    if (hits.length === 0) {
+        io.stdout(flags.has("all") ? "没有命中\n" : "没有命中（只搜了当前目录的会话，--all 搜全部）\n");
+        return ExitCode.Ok;
+    }
+    const color = io.stdoutIsTTY && (io.env["NO_COLOR"] ?? "") === "";
+    for (const hit of hits)
+        io.stdout(renderHit(hit, color));
+    if (truncated)
+        io.stdout(`（已到 --limit ${limit}，可能还有更多）\n`);
+    return ExitCode.Ok;
+}

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

@@ -3,9 +3,10 @@
  *
  * 会话存储是 B2 的实现，经 RuntimeDeps.sessions 注入；这里只做参数、目录解析与输出格式。
  * - list [--all]：缺省只列当前目录的会话；`--all` 列全部。
- * - show <id>：头信息 + 条目类型统计 + 首条提示。
+ * - show <id>：头信息 + 条目类型统计 + 首条提示 + 用户消息编号（`--from <id>#<编号>` 复用）。
+ * - search / export：见 sessions-search.ts、sessions-export.ts（只读扫描，不经会话存储）。
  * - 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 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      ama sessions search <\u5173\u952E\u8BCD|/\u6B63\u5219/> [--all] [--role user|assistant|tool] [--since 7d] [--limit N]\n      ama sessions export <id> [--format md|json|jsonl] [--output <\u6587\u4EF6>] [--branch leaf|all]\n";
 export declare function runSessions(argv: readonly string[], io: CliIo, deps: Pick<RuntimeDeps, "sessions"> | undefined): Promise<number>;

package/dist/cli/subcommands/sessions.js

@@ -3,16 +3,22 @@
  *
  * 会话存储是 B2 的实现，经 RuntimeDeps.sessions 注入；这里只做参数、目录解析与输出格式。
  * - list [--all]：缺省只列当前目录的会话；`--all` 列全部。
- * - show <id>：头信息 + 条目类型统计 + 首条提示。
+ * - show <id>：头信息 + 条目类型统计 + 首条提示 + 用户消息编号（`--from <id>#<编号>` 复用）。
+ * - search / export：见 sessions-search.ts、sessions-export.ts（只读扫描，不经会话存储）。
  * - prune [--older-than <天>] [--dry-run]：缺省 30 天，移到 trash（不删除）。
  */
 import { resolve } from "node:path";
 import { expandHome, resolveDataDir } from "../../config/paths.js";
 import { parseSubArgs, UsageError } from "../args.js";
 import { ExitCode } from "../exit-codes.js";
+import { numberUserMessages } from "../../session/reuse.js";
+import { runSessionsExport } from "./sessions-export.js";
+import { runSessionsSearch } from "./sessions-search.js";
 export const SESSIONS_USAGE = `用法：ama sessions list [--all] [--session-dir <目录>]
       ama sessions show <id> [--session-dir <目录>]
       ama sessions prune [--older-than <天>] [--dry-run] [--all] [--session-dir <目录>]
+      ama sessions search <关键词|/正则/> [--all] [--role user|assistant|tool] [--since 7d] [--limit N]
+      ama sessions export <id> [--format md|json|jsonl] [--output <文件>] [--branch leaf|all]
 `;
 function shortTime(iso) {
     return iso.replace("T", " ").replace(/\.\d+Z$|Z$/, "");
@@ -24,6 +30,10 @@ function oneLine(text, max = 60) {
     return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
 }
 export async function runSessions(argv, io, deps) {
+    if (argv[0] === "search")
+        return runSessionsSearch(argv.slice(1), io);
+    if (argv[0] === "export")
+        return runSessionsExport(argv.slice(1), io);
     const { positionals, values, flags } = parseSubArgs(argv, ["session-dir", "older-than"], ["all", "dry-run"]);
     const action = positionals[0];
     if (flags.has("help") || action === undefined) {
@@ -73,6 +83,17 @@ export async function runSessions(argv, io, deps) {
                     ? [`首条提示：${oneLine(item.firstPrompt, 200)}`]
                     : []),
             ].join("\n") + "\n");
+            const users = numberUserMessages(entries);
+            if (users.length > 0) {
+                io.stdout(`用户消息（ama --from ${item.id.slice(0, 8)}#<编号> 复用）：\n`);
+                for (const user of users) {
+                    const tags = [
+                        ...(user.origin !== undefined ? [`[${user.origin}]`] : []),
+                        ...(user.images.length > 0 ? [`[图片 ${user.images.length}]`] : []),
+                    ];
+                    io.stdout(`  #${String(user.n).padEnd(3)} ${shortTime(user.timestamp)}  ${[...tags, oneLine(user.text, 100)].join(" ")}\n`);
+                }
+            }
             return ExitCode.Ok;
         }
         case "prune": {

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

@@ -0,0 +1,17 @@
+/**
+ * `ama stats`：跨会话的用量统计（只读扫描会话 JSONL）。[W4-D]
+ *
+ * - 范围：缺省当前目录的会话；`--project <目录>` 指定项目；`--all` 全部（`--by project` 未指定范围时也看全部）。
+ * - 时间：`--since` / `--until` 接受 `7d`（含今天的最近 7 天）、`today`、`YYYY-MM-DD`（本地日期，含当天）。
+ * - 分组：`--by day|week|month|provider|channel|model|project`。
+ * - 缓存：`<数据目录>/stats-index.json`，按文件 mtime / size 失效；`--no-cache` 不读也不写。
+ * - 口径见 session/stats-aggregate.ts 与 docs/sessions.md「统计」。
+ */
+import { type StatsReport } from "../../session/stats-aggregate.js";
+import type { CliIo } from "../deps.js";
+export declare const STATS_USAGE = "\u7528\u6CD5\uFF1Aama stats [--since 7d|30d|today|YYYY-MM-DD] [--until \u2026]\n                 [--by day|week|month|provider|channel|model|project]\n                 [--project <\u76EE\u5F55> | --all] [--top N] [--json] [--no-cache] [--session-dir <\u76EE\u5F55>]\n";
+/** `7d` / `today` / `YYYY-MM-DD` → 本地日期。 */
+export declare function parseDaySpec(option: string, raw: string, now?: Date): string;
+export declare function formatTokens(count: number): string;
+export declare function renderStats(report: StatsReport, scope: string): string;
+export declare function runStats(argv: readonly string[], io: CliIo): Promise<number>;