@armadra/agent 0.5.1 → 0.6.1

package/dist/cli/subcommands/providers.js

@@ -28,19 +28,12 @@ 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";
+import { msg } from "../../i18n/index.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] [--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]
-                             [--concurrency N] [--probe-timeout ms] [--yes]
-`;
+export function providersUsage() {
+    return msg().subcommands.providers.usage;
+}
 const VALUE_OPTIONS = [
     "base-url",
     "api",
@@ -62,7 +55,7 @@ function intValue(ctx, name, fallback) {
         return fallback;
     const n = Number(raw);
     if (!Number.isInteger(n) || n < 1)
-        throw new UsageError(`--${name} 需要正整数：${raw}`);
+        throw new UsageError(msg().subcommands.providers.positiveInt(name, raw));
     return n;
 }
 function list(raw) {
@@ -83,7 +76,7 @@ async function approved(ctx, what) {
     if (ctx.flags.has("yes"))
         return true;
     if (!ctx.io.stdinIsTTY) {
-        ctx.io.stderr(`ama: ${what}，非交互环境需加 --yes\n`);
+        ctx.io.stderr(msg().subcommands.providers.needsYes(what));
         return "usage";
     }
     return confirm(ctx.io, `${what}\n`);
@@ -138,10 +131,8 @@ async function plan(ctx, input) {
         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` +
-            `${describeProbePlan(capped.requests, tuning.concurrency, tuning.timeoutMs)}\n`);
-        const ok = await approved(ctx, `将发 ${capped.requests} 次计费请求并写入 ${ctx.level.userConfigPath}`);
+        io.stdout(msg().subcommands.providers.probePlan(capped.ids.length, capped.requests, max, capped.dropped) + `${describeProbePlan(capped.requests, tuning.concurrency, tuning.timeoutMs)}\n`);
+        const ok = await approved(ctx, msg().subcommands.providers.confirmProbe(capped.requests, ctx.level.userConfigPath));
         if (ok === "usage")
             return { plans: [], cancelled: ExitCode.Usage };
         if (!ok)
@@ -197,10 +188,10 @@ async function obtainKey(ctx, id, registry) {
     const keyEnv = ctx.values.get("key-env");
     if (keyEnv !== undefined) {
         if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(keyEnv))
-            throw new UsageError(`--key-env 不是合法的变量名：${keyEnv}`);
+            throw new UsageError(msg().subcommands.providers.invalidKeyEnv(keyEnv));
         const value = ctx.io.env[keyEnv]?.trim();
         if (!value)
-            ctx.io.stderr(`ama: 警告：环境变量 ${keyEnv} 未设置，列模型与探测将不带 key\n`);
+            ctx.io.stderr(msg().subcommands.providers.keyEnvUnset(keyEnv));
         return { apiKey: value || undefined, configValue: `$${keyEnv}` };
     }
     if (registry.get(id) !== undefined) {
@@ -209,22 +200,23 @@ async function obtainKey(ctx, id, registry) {
             return { apiKey: existing.apiKey };
     }
     if (ctx.io.stdinIsTTY)
-        ctx.io.stderr(`输入 ${id} 的 API key（不回显），回车结束：`);
+        ctx.io.stderr(msg().subcommands.providers.keyPrompt(id));
     const key = extractKey(await ctx.io.readStdin());
     if (ctx.io.stdinIsTTY)
         ctx.io.stderr("\n");
     if (key === "")
-        throw new UsageError("没有从 stdin 读到 key（或用 --key-env <VAR>）");
+        throw new UsageError(msg().subcommands.providers.noKeyOnStdin);
     return { apiKey: key, store: key };
 }
 async function add(ctx, id, refresh) {
     const { io, level } = ctx;
+    const m = msg().subcommands.providers;
     if (!PROVIDER_ID_PATTERN.test(id) || id.includes("@"))
-        throw new UsageError(`供应商 id 不合法：${id}`);
+        throw new UsageError(m.invalidId(id));
     const config = userConfig(level);
     const existing = config.providers?.[id];
     if (refresh && existing === undefined) {
-        io.stderr(`ama: ${level.userConfigPath} 里没有供应商 ${id}（先 ama providers add）\n`);
+        io.stderr(m.missingInConfig(level.userConfigPath, id));
         return ExitCode.Usage;
     }
     const registry = await buildRegistry(level, io, ctx.deps);
@@ -236,28 +228,28 @@ async function add(ctx, id, refresh) {
     else {
         const baseUrl = ctx.values.get("base-url");
         if (baseUrl === undefined)
-            throw new UsageError("ama providers add 需要 --base-url <url> 或 --channel");
+            throw new UsageError(m.needsBaseUrl);
         if (!/^https?:\/\//.test(baseUrl))
-            throw new UsageError(`--base-url 应为 http(s) URL：${baseUrl}`);
+            throw new UsageError(m.baseUrlNotHttp(baseUrl));
         candidates = defaultChannels(baseUrl, ctx.values.get("api"));
     }
     const target = listingTarget(candidates);
     if (target === undefined)
-        throw new UsageError(`${id} 没有可用的渠道`);
+        throw new UsageError(m.noChannel(id));
     const key = await obtainKey(ctx, id, registry);
     let listed;
     try {
         listed = await fetchModelList(target, key.apiKey);
     }
     catch (error) {
-        io.stderr(`ama: ${id} 模型列表获取失败：${error.message}\n`);
+        io.stderr(m.listFailed(id, error.message));
         return ExitCode.RuntimeError;
     }
-    io.stdout(`${id}：发现 ${listed.length} 个模型（${target.url}）\n`);
+    io.stdout(m.discovered(id, listed.length, target.url));
     // 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`);
+    io.stdout(m.candidates(candidates));
     const existingIds = new Set((existing?.models ?? []).map((m) => m.id));
     const result = await plan(ctx, {
         id,
@@ -275,7 +267,7 @@ async function add(ctx, id, refresh) {
     if (refresh) {
         const gone = [...existingIds].filter((m) => !listed.some((l) => l.id === m));
         if (gone.length > 0)
-            io.stdout(`上游已不再列出（未删除）：${gone.join(", ")}\n`);
+            io.stdout(m.goneUpstream(gone));
     }
     const writable = result.plans.filter((p) => p.status === "ok" || p.status === "unprobed");
     const legacy = existing !== undefined && existing.channels === undefined;
@@ -290,7 +282,6 @@ async function add(ctx, id, refresh) {
             models: writable,
             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");
@@ -302,26 +293,30 @@ async function add(ctx, id, refresh) {
             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}${defaultNote}`;
-    io.stdout(`${summary}\n`);
+    io.stdout(m.writeSummary({
+        path: level.userConfigPath,
+        id,
+        channels: merged.addedChannels,
+        models: merged.addedModels.length,
+        authFile: key.store !== undefined ? level.authFile : undefined,
+        defaultModel: defaultPick !== undefined ? `${id}/${defaultPick.id}` : undefined,
+    }));
     if (defaultPick !== undefined)
-        io.stdout(`  选 ${defaultPick.id}：${defaultPick.reason}\n`);
+        io.stdout(m.defaultPick(defaultPick.id, defaultPick.reason));
     else if (level.merged.config.defaultModel === undefined && writable.length > 0)
-        io.stdout("  未设置 defaultModel：没有同时支持工具调用、上下文 ≥ 64k 且有价格的模型；用 ama config edit 设置\n");
+        io.stdout(m.noDefaultPick);
     if (merged.addedModels.length === 0 &&
         merged.addedChannels.length === 0 &&
         key.store === undefined) {
-        io.stdout("没有要写入的内容\n");
+        io.stdout(m.nothingToWrite);
         return result.stopped !== undefined ? ExitCode.RuntimeError : ExitCode.Ok;
     }
     if (!ctx.flags.has("probe")) {
-        const ok = await approved(ctx, "确认写入");
+        const ok = await approved(ctx, m.confirmWrite);
         if (ok === "usage")
             return ExitCode.Usage;
         if (!ok) {
-            io.stderr("ama: 已取消\n");
+            io.stderr(msg().subcommands.common.cancelled);
             return ExitCode.Ok;
         }
     }
@@ -333,14 +328,14 @@ async function add(ctx, id, refresh) {
     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`);
+    io.stdout(m.written(level.userConfigPath, backup));
     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`);
+        io.stdout(m.tryIt(`${id}/${sample}`));
     if (result.stopped !== undefined) {
-        io.stderr(`ama: 探测提前停止（${result.stopped}）\n`);
+        io.stderr(m.probeStopped(result.stopped));
         return ExitCode.RuntimeError;
     }
     return ExitCode.Ok;
@@ -375,7 +370,7 @@ function takeChannels(argv) {
         if (token === "--channel") {
             const value = argv[++i];
             if (value === undefined || value === "")
-                throw new UsageError("--channel 需要一个值");
+                throw new UsageError(msg().subcommands.providers.channelNeedsValue);
             specs.push(value);
         }
         else if (token.startsWith("--channel="))
@@ -390,11 +385,11 @@ export async function runProviders(argv, io, deps) {
     const { positionals, values, flags } = parseSubArgs(rest, VALUE_OPTIONS, FLAG_OPTIONS);
     const action = positionals[0];
     if (flags.has("help") || action === undefined) {
-        io.stdout(PROVIDERS_USAGE);
+        io.stdout(providersUsage());
         return flags.has("help") ? ExitCode.Ok : ExitCode.Usage;
     }
     if (deps === undefined) {
-        io.stderr("ama: providers 尚未装配（供应商注册表由集成批次注入）\n");
+        io.stderr(msg().subcommands.common.notAssembled("providers"));
         return ExitCode.RuntimeError;
     }
     const level = loadUserLevel(io, {
@@ -402,14 +397,14 @@ export async function runProviders(argv, io, deps) {
         authFile: values.get("auth-file"),
     });
     for (const warning of level.warnings)
-        io.stderr(`ama: 警告：${warning}\n`);
+        io.stderr(msg().subcommands.common.warning(warning));
     const ctx = { io, deps, level, values, flags, channelSpecs: specs };
     const target = positionals[1];
     const need = () => {
         if (target === undefined)
-            throw new UsageError(`ama providers ${action} 需要 <id>`);
+            throw new UsageError(msg().subcommands.common.needsArg(`ama providers ${action}`, "<id>"));
         if (positionals.length > 2)
-            throw new UsageError(`多余的参数：${positionals.slice(2).join(" ")}`);
+            throw new UsageError(msg().subcommands.common.extraArgs(positionals.slice(2).join(" ")));
         return target;
     };
     switch (action) {
@@ -424,6 +419,6 @@ export async function runProviders(argv, io, deps) {
         case "remove":
             return removeProvider(ctx, need());
         default:
-            throw new UsageError(`未知的 providers 子命令：${action}`);
+            throw new UsageError(msg().subcommands.common.unknownSubcommand("providers", action));
     }
 }

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

@@ -6,5 +6,5 @@
  * - 导出内容先脱敏（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 sessionsExportUsage(): string;
 export declare function runSessionsExport(argv: readonly string[], io: CliIo): Promise<number>;

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

@@ -12,9 +12,10 @@ 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 <目录>]
-`;
+import { msg } from "../../i18n/index.js";
+export function sessionsExportUsage() {
+    return msg().subcommands.sessionsExport.usage;
+}
 const FORMATS = ["md", "json", "jsonl"];
 const BRANCHES = ["leaf", "all"];
 export async function runSessionsExport(argv, io) {
@@ -25,21 +26,21 @@ export async function runSessionsExport(argv, io) {
         "session-dir",
     ]);
     if (flags.has("help")) {
-        io.stdout(SESSIONS_EXPORT_USAGE);
+        io.stdout(sessionsExportUsage());
         return ExitCode.Ok;
     }
     const [id, extra] = positionals;
     if (id === undefined)
-        throw new UsageError("ama sessions export 需要 <id>");
+        throw new UsageError(msg().subcommands.common.needsArg("ama sessions export", "<id>"));
     if (extra !== undefined)
-        throw new UsageError(`多余的参数：${extra}`);
+        throw new UsageError(msg().subcommands.common.extraArgs(extra));
     const format = (values.get("format") ?? "md");
     if (!FORMATS.includes(format)) {
-        throw new UsageError(`--format 的取值应为 ${FORMATS.join(" | ")}（收到 ${format}）`);
+        throw new UsageError(msg().subcommands.common.invalidChoice("--format", FORMATS, format));
     }
     const branch = (values.get("branch") ?? "leaf");
     if (!BRANCHES.includes(branch)) {
-        throw new UsageError(`--branch 的取值应为 ${BRANCHES.join(" | ")}（收到 ${branch}）`);
+        throw new UsageError(msg().subcommands.common.invalidChoice("--branch", BRANCHES, branch));
     }
     const dirFlag = values.get("session-dir");
     const root = dirFlag !== undefined
@@ -54,6 +55,6 @@ export async function runSessionsExport(argv, io) {
     }
     const target = resolve(io.cwd, expandHome(output, { env: io.env }));
     writeFileSync(target, text, { mode: 0o600 });
-    io.stderr(`已导出到 ${target}\n`);
+    io.stderr(msg().subcommands.sessionsExport.exported(target));
     return ExitCode.Ok;
 }

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

@@ -8,6 +8,6 @@
  */
 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 sessionsSearchUsage(): string;
 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

@@ -13,9 +13,10 @@ 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 <目录>]
-`;
+import { msg } from "../../i18n/index.js";
+export function sessionsSearchUsage() {
+    return msg().subcommands.sessionsSearch.usage;
+}
 const ROLES = ["user", "assistant", "tool"];
 function highlight(text, ranges, color) {
     if (!color || ranges.length === 0)
@@ -44,18 +45,18 @@ export function renderHit(hit, color) {
 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);
+        io.stdout(sessionsSearchUsage());
         return ExitCode.Ok;
     }
     const pattern = positionals.join(" ");
     if (pattern.trim() === "")
-        throw new UsageError("ama sessions search 需要关键词或 /正则/");
+        throw new UsageError(msg().subcommands.sessionsSearch.needsPattern);
     let query;
     try {
         query = compileQuery(pattern);
     }
     catch (error) {
-        throw new UsageError(`正则无效：${error.message}`);
+        throw new UsageError(msg().subcommands.sessionsSearch.invalidRegex(error.message));
     }
     let roles;
     const roleRaw = values.get("role");
@@ -63,14 +64,14 @@ export async function runSessionsSearch(argv, io) {
         roles = new Set();
         for (const role of roleRaw.split(",").map((r) => r.trim())) {
             if (!ROLES.includes(role)) {
-                throw new UsageError(`--role 的取值应为 ${ROLES.join(" | ")}（收到 ${role}）`);
+                throw new UsageError(msg().subcommands.common.invalidChoice("--role", ROLES, role));
             }
             roles.add(role);
         }
     }
     const limit = Number(values.get("limit") ?? "20");
     if (!Number.isInteger(limit) || limit < 1)
-        throw new UsageError("--limit 应为正整数");
+        throw new UsageError(msg().subcommands.sessionsSearch.limitPositive);
     const sinceRaw = values.get("since");
     const sinceIso = sinceRaw === undefined
         ? undefined
@@ -91,13 +92,13 @@ export async function runSessionsSearch(argv, io) {
         return ExitCode.Ok;
     }
     if (hits.length === 0) {
-        io.stdout(flags.has("all") ? "没有命中\n" : "没有命中（只搜了当前目录的会话，--all 搜全部）\n");
+        io.stdout(msg().subcommands.sessionsSearch.noHits(flags.has("all")));
         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`);
+        io.stdout(msg().subcommands.sessionsSearch.truncated(limit));
     return ExitCode.Ok;
 }

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

@@ -0,0 +1,30 @@
+/**
+ * `ama sessions trace <id|文件>`：会话轨迹导出（docs/wave6-plan.md §2.5、D7）。[W6-T2]
+ *
+ * - 缺省 / `--html [文件]` / `--format html`：自包含 HTML（`trace/html.ts`）；`--json` / `--format json`：与 RPC
+ *   `get_trace` 同形的 JSON（全部回合、已加载子会话、`previews` 只含本会话节点；`--no-content` 时没有）。
+ * - 输出：`--html <文件>` 或 `--output <文件>` 写文件（0600），否则 stdout；`--open` 写好后用系统浏览器打开
+ *   （没给文件时写到临时目录）。
+ * - `--branch leaf|all`、`--no-content`（只留结构与数字）、`--children`（HTML 内嵌子会话预览）、
+ *   `--now <ms>`（生成时间，确定性）。
+ * - 只读：不加锁、不改会话文件（推算出的时间不写回）；子会话缺失只标 childMissing。
+ */
+import { type TraceInput } from "../../trace/build.js";
+import type { CliIo } from "../deps.js";
+export declare function sessionsTraceUsage(): string;
+export interface SessionsTraceDeps {
+    /** 打开浏览器（测试替身；缺省 detached spawn）。 */
+    open?: (command: OpenCommand) => Promise<void>;
+    /** 生成时间（缺省 `Date.now()`；`--now` 优先）。 */
+    now?: () => number;
+    platform?: NodeJS.Platform;
+    /** 读子会话（测试替身）。 */
+    readChild?: (file: string) => TraceInput | undefined;
+}
+export interface OpenCommand {
+    command: string;
+    args: string[];
+}
+/** 各平台「用缺省程序打开文件」的命令。 */
+export declare function openCommand(platform: NodeJS.Platform, file: string): OpenCommand;
+export declare function runSessionsTrace(argv: readonly string[], io: CliIo, deps?: SessionsTraceDeps): Promise<number>;

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

@@ -0,0 +1,156 @@
+/**
+ * `ama sessions trace <id|文件>`：会话轨迹导出（docs/wave6-plan.md §2.5、D7）。[W6-T2]
+ *
+ * - 缺省 / `--html [文件]` / `--format html`：自包含 HTML（`trace/html.ts`）；`--json` / `--format json`：与 RPC
+ *   `get_trace` 同形的 JSON（全部回合、已加载子会话、`previews` 只含本会话节点；`--no-content` 时没有）。
+ * - 输出：`--html <文件>` 或 `--output <文件>` 写文件（0600），否则 stdout；`--open` 写好后用系统浏览器打开
+ *   （没给文件时写到临时目录）。
+ * - `--branch leaf|all`、`--no-content`（只留结构与数字）、`--children`（HTML 内嵌子会话预览）、
+ *   `--now <ms>`（生成时间，确定性）。
+ * - 只读：不加锁、不改会话文件（推算出的时间不写回）；子会话缺失只标 childMissing。
+ */
+import { spawn } from "node:child_process";
+import { existsSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { expandHome, resolveDataDir } from "../../config/paths.js";
+import { msg } from "../../i18n/index.js";
+import { findSessionFileReadOnly, readSessionReadOnly } from "../../session/scan.js";
+import { buildTrace } from "../../trace/build.js";
+import { entryLookup } from "../../trace/detail.js";
+import { renderTraceHtml } from "../../trace/html.js";
+import { queryTrace } from "../../trace/query.js";
+import { childLoader } from "../../trace/session.js";
+import { AMA_VERSION } from "../../version.js";
+import { parseSubArgs, UsageError } from "../args.js";
+import { ExitCode } from "../exit-codes.js";
+export function sessionsTraceUsage() {
+    return msg().trace.cli.usage;
+}
+/** 各平台「用缺省程序打开文件」的命令。 */
+export function openCommand(platform, file) {
+    if (platform === "darwin")
+        return { command: "open", args: [file] };
+    if (platform === "win32")
+        return { command: "explorer", args: [file] };
+    return { command: "xdg-open", args: [file] };
+}
+function spawnOpen({ command, args }) {
+    return new Promise((done, fail) => {
+        const child = spawn(command, args, { detached: true, stdio: "ignore" });
+        child.once("error", fail);
+        child.once("spawn", () => {
+            child.unref();
+            done();
+        });
+    });
+}
+/** `--html [文件]`：值可省略，只在下一个参数像 HTML 文件名时才当作文件。 */
+function splitHtmlFlag(argv) {
+    const rest = [];
+    let html = false;
+    let file;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i] ?? "";
+        if (token.startsWith("--html=")) {
+            html = true;
+            file = token.slice("--html=".length) || undefined;
+        }
+        else if (token === "--html") {
+            html = true;
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith("-") && /\.html?$/i.test(next)) {
+                file = next;
+                i++;
+            }
+        }
+        else
+            rest.push(token);
+    }
+    return { rest, html, ...(file !== undefined ? { file } : {}) };
+}
+function locate(io, target, dirFlag) {
+    const asPath = resolve(io.cwd, expandHome(target, { env: io.env }));
+    if (/[\\/]|\.jsonl$/.test(target) && existsSync(asPath))
+        return asPath;
+    const root = dirFlag !== undefined
+        ? resolve(io.cwd, expandHome(dirFlag, { env: io.env }))
+        : join(resolveDataDir({ env: io.env }), "sessions");
+    return findSessionFileReadOnly(root, target, io.cwd);
+}
+export async function runSessionsTrace(argv, io, deps = {}) {
+    const common = msg().subcommands.common;
+    const m = msg().trace.cli;
+    const split = splitHtmlFlag(argv);
+    const { positionals, values, flags } = parseSubArgs(split.rest, ["format", "output", "branch", "session-dir", "now"], ["json", "open", "no-content", "children"]);
+    if (flags.has("help")) {
+        io.stdout(sessionsTraceUsage());
+        return ExitCode.Ok;
+    }
+    const [target, extra] = positionals;
+    if (target === undefined)
+        throw new UsageError(common.needsArg("ama sessions trace", "<id|file>"));
+    if (extra !== undefined)
+        throw new UsageError(common.extraArgs(extra));
+    const formatFlag = values.get("format");
+    if (formatFlag !== undefined && formatFlag !== "html" && formatFlag !== "json")
+        throw new UsageError(common.invalidChoice("--format", ["html", "json"], formatFlag));
+    const wantsJson = flags.has("json") || formatFlag === "json";
+    if (wantsJson && (split.html || formatFlag === "html"))
+        throw new UsageError(m.formatConflict);
+    const branch = values.get("branch") ?? "leaf";
+    if (branch !== "leaf" && branch !== "all")
+        throw new UsageError(common.invalidChoice("--branch", ["leaf", "all"], branch));
+    const rawNow = values.get("now");
+    const nowFlag = rawNow === undefined ? undefined : Number(rawNow);
+    if (nowFlag !== undefined && (!Number.isInteger(nowFlag) || nowFlag < 0))
+        throw new UsageError(m.badNow(rawNow ?? ""));
+    const content = !flags.has("no-content");
+    const file = locate(io, target, values.get("session-dir"));
+    const read = readSessionReadOnly(file);
+    const input = {
+        header: read.header,
+        entries: read.entries,
+        leaf: read.leaf,
+        sessionFile: file,
+    };
+    const loadChild = childLoader(deps.readChild);
+    const base = nowFlag !== undefined ? { now: nowFlag } : {};
+    let text;
+    if (wantsJson) {
+        const result = queryTrace(input, { branch, content: content ? "preview" : "none" }, { loadChild, loadChildren: true, unlimited: true, ...base });
+        text = `${JSON.stringify(result, null, 2)}\n`;
+    }
+    else {
+        const trace = buildTrace(input, { branch, loadChild, ...base });
+        const children = loadChild.inputs().flatMap((i) => i.entries);
+        text = renderTraceHtml(trace, {
+            content,
+            children: flags.has("children"),
+            generatedAt: nowFlag ?? (deps.now ?? Date.now)(),
+            version: AMA_VERSION,
+            lookup: entryLookup([...input.entries, ...children], read.header.cwd),
+        });
+    }
+    const outFlag = split.file ?? values.get("output");
+    const open = flags.has("open");
+    let outPath = outFlag === undefined ? undefined : resolve(io.cwd, expandHome(outFlag, { env: io.env }));
+    if (outPath === undefined && open)
+        outPath = join(tmpdir(), `ama-trace-${read.header.id}.${wantsJson ? "json" : "html"}`);
+    if (outPath === undefined) {
+        io.stdout(text);
+        return ExitCode.Ok;
+    }
+    writeFileSync(outPath, text, { mode: 0o600 });
+    io.stderr(m.wrote(outPath));
+    if (open) {
+        try {
+            await (deps.open ?? spawnOpen)(openCommand(deps.platform ?? process.platform, outPath));
+        }
+        catch (error) {
+            io.stderr(m.openFailed(error instanceof Error ? error.message : String(error)));
+            return ExitCode.RuntimeError;
+        }
+    }
+    return ExitCode.Ok;
+}

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

@@ -2,13 +2,14 @@
  * `ama sessions list|show|prune`（设计 §1.2、§8）。[B5]
  *
  * 会话存储是 B2 的实现，经 RuntimeDeps.sessions 注入；这里只做参数、目录解析与输出格式。
- * - list [--all]：缺省只列当前目录的会话；`--all` 列全部。
+ * - list [--all]：缺省只列当前目录的会话、不列子 Agent 会话；`--all` 列全部目录并带上子 Agent 会话（标 `↳`）。
  * - show <id>：头信息 + 条目类型统计 + 首条提示 + 用户消息编号（`--from <id>#<编号>` 复用）。
- * - search / export：见 sessions-search.ts、sessions-export.ts（只读扫描，不经会话存储）。
+ * - search / export / trace：见 sessions-search.ts、sessions-export.ts、sessions-trace.ts（只读扫描，不经会话存储）。
  * - prune [--older-than <天>] [--dry-run]：缺省 30 天，移到 trash（不删除）；之后清理检查点备份
  *   （未被任何会话引用且超过 1 天的 blob，docs/rewind-plan.md §1.4）与超过 7 天的剪贴板图片
  *   （`<数据目录>/clipboard/`，W5-I），`--dry-run` 时只报告。
  */
 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      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 sessionsUsage(): string;
 export declare function runSessions(argv: readonly string[], io: CliIo, deps: Pick<RuntimeDeps, "sessions"> | undefined): Promise<number>;