@armadra/agent 0.3.0 → 0.5.0

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,12 @@
  *
  * 会话存储是 B2 的实现，经 RuntimeDeps.sessions 注入；这里只做参数、目录解析与输出格式。
  * - list [--all]：缺省只列当前目录的会话；`--all` 列全部。
- * - show <id>：头信息 + 条目类型统计 + 首条提示。
- * - prune [--older-than <天>] [--dry-run]：缺省 30 天，移到 trash（不删除）。
+ * - show <id>：头信息 + 条目类型统计 + 首条提示 + 用户消息编号（`--from <id>#<编号>` 复用）。
+ * - search / export：见 sessions-search.ts、sessions-export.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";
+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,26 @@
  *
  * 会话存储是 B2 的实现，经 RuntimeDeps.sessions 注入；这里只做参数、目录解析与输出格式。
  * - list [--all]：缺省只列当前目录的会话；`--all` 列全部。
- * - show <id>：头信息 + 条目类型统计 + 首条提示。
- * - prune [--older-than <天>] [--dry-run]：缺省 30 天，移到 trash（不删除）。
+ * - show <id>：头信息 + 条目类型统计 + 首条提示 + 用户消息编号（`--from <id>#<编号>` 复用）。
+ * - search / export：见 sessions-search.ts、sessions-export.ts（只读扫描，不经会话存储）。
+ * - prune [--older-than <天>] [--dry-run]：缺省 30 天，移到 trash（不删除）；之后清理检查点备份
+ *   （未被任何会话引用且超过 1 天的 blob，docs/rewind-plan.md §1.4）与超过 7 天的剪贴板图片
+ *   （`<数据目录>/clipboard/`，W5-I），`--dry-run` 时只报告。
  */
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
+import { formatBytes, gcBlobs } from "../../checkpoints/gc.js";
 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 { gcClipboardImages } from "../../tools/clipboard-image.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 +34,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 +87,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": {
@@ -88,12 +113,42 @@ export async function runSessions(argv, io, deps) {
             for (const file of moved)
                 io.stdout(`${dryRun ? "将移到 trash" : "已移到 trash"}：${file}\n`);
             io.stdout(`${moved.length} 个会话${dryRun ? "（演练，未改动）" : ""}\n`);
+            await pruneFileHistory(io, sessionDir, dryRun);
+            await pruneClipboard(io, dryRun);
             return ExitCode.Ok;
         }
         default:
             throw new UsageError(`未知的 sessions 子命令：${action}`);
     }
 }
+/** 检查点备份 GC：扫描本次的会话目录、缺省会话目录与登记过的目录。失败只提示，不影响 prune。 */
+async function pruneFileHistory(io, sessionDir, dryRun) {
+    const dataDir = resolveDataDir({ env: io.env });
+    try {
+        const result = await gcBlobs({
+            dataDir,
+            sessionRoots: [sessionDir, join(dataDir, "sessions")],
+            dryRun,
+        });
+        if (result.removed.length === 0)
+            return;
+        io.stdout(`file-history：${dryRun ? "将清除" : "已清除"} ${result.removed.length} 个未引用的备份（${formatBytes(result.removedBytes)}）\n`);
+    }
+    catch (error) {
+        io.stderr(`ama: file-history 清理跳过（${error instanceof Error ? error.message : String(error)}）\n`);
+    }
+}
+/** [W5-I] `<数据目录>/clipboard/` 超过 7 天的剪贴板图片。失败只提示。 */
+async function pruneClipboard(io, dryRun) {
+    try {
+        const removed = await gcClipboardImages(resolveDataDir({ env: io.env }), { dryRun });
+        if (removed.length > 0)
+            io.stdout(`clipboard：${dryRun ? "将清除" : "已清除"} ${removed.length} 个超过 7 天的剪贴板图片\n`);
+    }
+    catch (error) {
+        io.stderr(`ama: clipboard 清理跳过（${error instanceof Error ? error.message : String(error)}）\n`);
+    }
+}
 function notWired(io, what) {
     io.stderr(`ama: ${what} 尚未装配（会话存储由集成批次注入）\n`);
     return ExitCode.RuntimeError;

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

package/dist/cli/subcommands/stats.js

@@ -0,0 +1,198 @@
+/**
+ * `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 { join, resolve } from "node:path";
+import { expandHome, resolveDataDir } from "../../config/paths.js";
+import { sessionFilesInScope } from "../../session/scan.js";
+import { STATS_GROUPS, aggregateStats, } from "../../session/stats-aggregate.js";
+import { STATS_INDEX_FILE, collectSummaries } from "../../session/stats-index.js";
+import { localDay } from "../../session/stats-scan.js";
+import { parseSubArgs, UsageError } from "../args.js";
+import { ExitCode } from "../exit-codes.js";
+export const STATS_USAGE = `用法：ama stats [--since 7d|30d|today|YYYY-MM-DD] [--until …]
+                 [--by day|week|month|provider|channel|model|project]
+                 [--project <目录> | --all] [--top N] [--json] [--no-cache] [--session-dir <目录>]
+`;
+/** `7d` / `today` / `YYYY-MM-DD` → 本地日期。 */
+export function parseDaySpec(option, raw, now = new Date()) {
+    if (raw === "today")
+        return localDay(now.toISOString()) ?? "";
+    const rel = /^(\d+)d$/.exec(raw);
+    if (rel !== null) {
+        const days = Number(rel[1]);
+        if (days < 1)
+            throw new UsageError(`--${option} 的天数至少为 1（收到 ${raw}）`);
+        const d = new Date(now);
+        d.setDate(d.getDate() - (days - 1));
+        return localDay(d.toISOString()) ?? "";
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(raw) && Number.isFinite(Date.parse(`${raw}T00:00:00`)))
+        return raw;
+    throw new UsageError(`--${option} 应为 7d、today 或 YYYY-MM-DD（收到 ${raw}）`);
+}
+export function formatTokens(count) {
+    const trim = (text) => text.replace(/\.?0+$/, "");
+    if (count < 1000)
+        return String(Math.round(count));
+    if (count < 100_000)
+        return `${trim((count / 1000).toFixed(1))}k`;
+    if (count < 1_000_000)
+        return `${Math.round(count / 1000)}k`;
+    return `${trim((count / 1_000_000).toFixed(2))}M`;
+}
+const percent = (rate) => rate === undefined ? "—" : `${(rate * 100).toFixed(1)}%`;
+const usd = (t) => {
+    if (t.cost === undefined)
+        return "—";
+    return t.cost >= 1 || t.cost === 0 ? `$${t.cost.toFixed(2)}` : `$${t.cost.toFixed(4)}`;
+};
+function seconds(ms) {
+    if (ms === undefined)
+        return "—";
+    return ms < 60_000 ? `${(ms / 1000).toFixed(1)}s` : `${(ms / 60_000).toFixed(1)}m`;
+}
+function width(text) {
+    let w = 0;
+    for (const ch of text)
+        w += (ch.codePointAt(0) ?? 0) > 0x2e7f ? 2 : 1;
+    return w;
+}
+function table(rows, rightAlign) {
+    const widths = [];
+    for (const row of rows)
+        row.forEach((cell, i) => (widths[i] = Math.max(widths[i] ?? 0, width(cell))));
+    return rows
+        .map((row) => row
+        .map((cell, i) => {
+        const padding = " ".repeat((widths[i] ?? 0) - width(cell));
+        return rightAlign(i) ? padding + cell : cell + padding;
+    })
+        .join("  ")
+        .trimEnd())
+        .join("\n");
+}
+export function renderStats(report, scope) {
+    const t = report.totals;
+    const range = report.since === undefined && report.until === undefined
+        ? "全部时间"
+        : `${report.since ?? "最早"} – ${report.until ?? "今天"}`;
+    const lines = [`${range} · ${scope} · ${report.sessions} 个会话`];
+    if (t.requests === 0) {
+        lines.push("没有模型请求");
+        return lines.join("\n") + "\n";
+    }
+    const kinds = Object.entries(report.byKind)
+        .sort((a, b) => b[1] - a[1])
+        .map(([kind, n]) => `${kind === "turn" ? "对话" : kind} ${n}`)
+        .join(" · ");
+    const costLine = t.cost === undefined
+        ? "— （所有请求的模型都无价格，见 token）"
+        : t.unpriced > 0
+            ? `${usd(t)}（另有 ${t.unpriced} 次请求无价，未计入）`
+            : usd(t);
+    const rows = [
+        ["请求", `${t.requests}（${kinds}）`],
+        ["回合", `${t.turns} · 平均耗时 ${seconds(t.avgTurnMs)}`],
+        [
+            "Token",
+            `输入 ${formatTokens(t.input)} · 输出 ${formatTokens(t.output)} · 缓存读 ${formatTokens(t.cacheRead)} · 缓存写 ${formatTokens(t.cacheWrite)}`,
+        ],
+        [
+            "缓存命中率",
+            `${percent(t.hitRate)}（报告缓存的端点 ${report.endpoints.reported}/${report.endpoints.total}，其余不进分母）`,
+        ],
+        ["费用", costLine],
+        ["错误 / 重试", `${t.errors} / ${t.retries}`],
+    ];
+    lines.push(table(rows, () => false));
+    if (report.groups !== undefined && report.groups.length > 0) {
+        const head = ["", "会话", "请求", "回合", "输入", "输出", "缓存读", "缓存写", "命中率", "费用"];
+        const body = report.groups.map((g) => [
+            g.key,
+            String(g.sessions),
+            String(g.requests),
+            String(g.turns),
+            formatTokens(g.input),
+            formatTokens(g.output),
+            formatTokens(g.cacheRead),
+            formatTokens(g.cacheWrite),
+            percent(g.hitRate),
+            usd(g) + (g.cost !== undefined && g.unpriced > 0 ? "+" : ""),
+        ]);
+        lines.push("", table([head, ...body], (i) => i > 0));
+    }
+    if (report.tools.length > 0) {
+        lines.push("", `工具调用 Top ${report.tools.length}`);
+        lines.push(table(report.tools.map((tool) => [`  ${tool.name}`, String(tool.count)]), (i) => i > 0));
+    }
+    return lines.join("\n") + "\n";
+}
+export async function runStats(argv, io) {
+    const { positionals, values, flags } = parseSubArgs(argv, ["since", "until", "by", "project", "session-dir", "top"], ["all", "json", "no-cache"]);
+    if (flags.has("help")) {
+        io.stdout(STATS_USAGE);
+        return ExitCode.Ok;
+    }
+    if (positionals.length > 0)
+        throw new UsageError(`ama stats 不接受位置参数：${positionals[0]}`);
+    const now = new Date();
+    const since = values.has("since") ? parseDaySpec("since", values.get("since"), now) : undefined;
+    const until = values.has("until") ? parseDaySpec("until", values.get("until"), now) : undefined;
+    const byRaw = values.get("by");
+    if (byRaw !== undefined && !STATS_GROUPS.includes(byRaw)) {
+        throw new UsageError(`--by 的取值应为 ${STATS_GROUPS.join(" | ")}（收到 ${byRaw}）`);
+    }
+    const by = byRaw;
+    const top = Number(values.get("top") ?? "10");
+    if (!Number.isInteger(top) || top < 0)
+        throw new UsageError("--top 应为非负整数");
+    if (flags.has("all") && values.has("project")) {
+        throw new UsageError("--project 与 --all 不能同时使用");
+    }
+    const dataDir = resolveDataDir({ env: io.env });
+    const dirFlag = values.get("session-dir");
+    const root = dirFlag !== undefined
+        ? resolve(io.cwd, expandHome(dirFlag, { env: io.env }))
+        : join(dataDir, "sessions");
+    const projectFlag = values.get("project");
+    const project = projectFlag !== undefined
+        ? resolve(io.cwd, expandHome(projectFlag, { env: io.env }))
+        : flags.has("all") || by === "project"
+            ? undefined
+            : io.cwd;
+    const files = sessionFilesInScope(root, project);
+    const useCache = !flags.has("no-cache");
+    const collected = collectSummaries(files, {
+        ...(useCache ? { indexFile: join(dataDir, STATS_INDEX_FILE) } : {}),
+        prune: project === undefined,
+    });
+    const report = aggregateStats(collected.summaries, {
+        ...(since !== undefined ? { since } : {}),
+        ...(until !== undefined ? { until } : {}),
+        ...(by !== undefined ? { by } : {}),
+        topTools: top,
+    });
+    if (flags.has("json")) {
+        io.stdout(JSON.stringify({
+            scope: project === undefined ? { all: true } : { project },
+            ...report,
+            files: {
+                total: files.length,
+                scanned: collected.scanned,
+                cached: collected.cached,
+                invalid: collected.invalid,
+            },
+        }, null, 2) + "\n");
+        return ExitCode.Ok;
+    }
+    io.stdout(renderStats(report, project === undefined ? "全部项目" : `项目 ${project}`));
+    if (collected.invalid > 0)
+        io.stderr(`ama: 跳过 ${collected.invalid} 个无法读取的会话文件\n`);
+    return ExitCode.Ok;
+}

package/dist/cli/system-prompt-arg.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `--system-prompt <文本|@文件>` 与 `--system-prompt-mode append|replace`（W4-C）。
+ *
+ * - `append`（缺省）：作为最后一条规则追加进系统提示的 rules 节——preamble 与工具表在它前面，
+ *   缓存前缀里最长的那段不受影响；同一段文本每次都逐字节相同。
+ * - `replace`：替换开头的 preamble（「You are ama…」那一段）；工具表、规则、AGENTS.md、Skill 索引、
+ *   cwd 等节照常保留，工具仍然可用。
+ * - `@文件`：相对当前目录读取（UTF-8）；文件不存在或为空 → 配置错误（退出码 3，同 `--instructions`）。
+ */
+import type { SystemPromptOverride } from "./deps.js";
+export declare function resolveSystemPromptArg(value: string | undefined, mode: "append" | "replace" | undefined, cwd: string): SystemPromptOverride | undefined;

package/dist/cli/system-prompt-arg.js

@@ -0,0 +1,34 @@
+/**
+ * `--system-prompt <文本|@文件>` 与 `--system-prompt-mode append|replace`（W4-C）。
+ *
+ * - `append`（缺省）：作为最后一条规则追加进系统提示的 rules 节——preamble 与工具表在它前面，
+ *   缓存前缀里最长的那段不受影响；同一段文本每次都逐字节相同。
+ * - `replace`：替换开头的 preamble（「You are ama…」那一段）；工具表、规则、AGENTS.md、Skill 索引、
+ *   cwd 等节照常保留，工具仍然可用。
+ * - `@文件`：相对当前目录读取（UTF-8）；文件不存在或为空 → 配置错误（退出码 3，同 `--instructions`）。
+ */
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { StartupError } from "../errors.js";
+import { ExitCode } from "./exit-codes.js";
+export function resolveSystemPromptArg(value, mode, cwd) {
+    if (value === undefined)
+        return undefined;
+    let text = value;
+    if (value.startsWith("@")) {
+        const raw = value.slice(1);
+        const path = isAbsolute(raw) ? raw : resolve(cwd, raw);
+        try {
+            if (!statSync(path).isFile())
+                throw new Error("not a file");
+            text = readFileSync(path, "utf8");
+        }
+        catch {
+            throw new StartupError("config_invalid", `--system-prompt 文件不存在：${path}`, ExitCode.Config);
+        }
+    }
+    text = text.trim();
+    if (text === "")
+        throw new StartupError("config_invalid", "--system-prompt 的内容为空", ExitCode.Config);
+    return { text, mode: mode ?? "append" };
+}

package/dist/codemode/capability.d.ts

@@ -1,14 +1,19 @@
 /**
- * 沙箱能力探测（设计 §5.5 沙箱第 4 条）。[B10]
+ * 沙箱能力探测（设计 §5.5 沙箱第 4 条；docs/sandbox.md「探测与降级」）。[B10][S2]
  *
  * Node 的权限模型（`--permission`）在 Node ≥ 25 同时拒绝网络；Node 22 / 24 只管文件、子进程、
- * worker 与 addon，不管网络——脚本若逃出 `vm` 就能联网。所以：
- * - Node ≥ 25 → `strict`；
- * - Node 22 / 24 → 仍可用，但工具描述与状态栏标注「网络未隔离」；`codemode.requireStrict: true`
- *   时直接禁用 codemode 工具并 warning（`codemodeAvailability`）。
+ * worker 与 addon，不管网络——脚本若逃出 `vm` 就能联网。子进程另外经操作系统沙箱（macOS
+ * sandbox-exec、Linux bwrap / unshare，src/sandbox）启动时，网络由内核拒绝。所以：
+ * - Node ≥ 25 → `strict`（OS 沙箱可用时叠加，纵深防御）；
+ * - Node 22 / 24 + 可用的 OS 沙箱 → `strict`（子进程必须经 OS 沙箱启动）；
+ * - Node 22 / 24 且没有 OS 沙箱 → 仍可用，但工具描述与状态栏标注「网络未隔离」；
+ *   `codemode.requireStrict: true` 时直接禁用 codemode 工具并 warning（`codemodeAvailability`）。
  *
- * 状态栏由 B7 直接调用 `detectSandboxCapability()` 判断（不经宿主 status）。
+ * 能力在进程内只探测一次（OS 沙箱探针有缓存），同一环境下描述与权限类字节稳定。状态栏直接调用
+ * `detectSandboxCapability()`（不经宿主 status）；组装根先用 `configureOsSandbox` 记下 `sandbox.enabled`。
  */
+import type { SandboxConfig } from "../config/types.js";
+import { type OsSandboxStatus } from "../sandbox/detect.js";
 export interface SandboxCapability {
     /** 权限模型同时隔离文件、子进程与网络。 */
     strict: boolean;
@@ -18,12 +23,24 @@ export interface SandboxCapability {
     reason: string;
     /** 运行时支持的权限开关：Node ≥ 22.13 / 23.5 为 `--permission`，更早为 `--experimental-permission`。 */
     permissionFlag: "--permission" | "--experimental-permission";
+    /** 操作系统沙箱（`kind: none` 表示没有）；codemode 子进程经它启动。 */
+    os: OsSandboxStatus;
 }
 export declare const NETWORK_NOT_ISOLATED = "network not isolated";
 export declare function parseNodeMajor(version: string): number;
 /** `--permission` 在 Node 22.13 / 23.5 之后才是稳定名字；之前只有 `--experimental-permission`。 */
 export declare function permissionFlagFor(allowedFlags?: ReadonlySet<string>): SandboxCapability["permissionFlag"];
-export declare function detectSandboxCapability(nodeVersion?: string, allowedFlags?: ReadonlySet<string>): SandboxCapability;
+/**
+ * 运行时的沙箱能力。`os` 缺省：不传 `nodeVersion` 时用进程内缓存的探测结果（`osSandboxStatus()`）；
+ * 传了假设的 Node 版本（测试、展示）时不探测，按没有 OS 沙箱算，需要时显式传入。
+ */
+export declare function detectSandboxCapability(nodeVersion?: string, allowedFlags?: ReadonlySet<string>, os?: OsSandboxStatus): SandboxCapability;
+/** 按配置的 `sandbox.enabled`（缺省 auto）得到运行时能力。 */
+export declare function sandboxCapabilityFor(config: {
+    sandbox?: SandboxConfig;
+}): SandboxCapability;
+/** strict 是否依赖 OS 沙箱（Node 22 / 24）：此时子进程必须经 OS 沙箱启动，包装不了就报错。 */
+export declare function strictNeedsOsSandbox(capability: Pick<SandboxCapability, "strict" | "nodeMajor">): boolean;
 export type CodemodeAvailability = {
     available: true;
     capability: SandboxCapability;

package/dist/codemode/capability.js

@@ -1,14 +1,18 @@
 /**
- * 沙箱能力探测（设计 §5.5 沙箱第 4 条）。[B10]
+ * 沙箱能力探测（设计 §5.5 沙箱第 4 条；docs/sandbox.md「探测与降级」）。[B10][S2]
  *
  * Node 的权限模型（`--permission`）在 Node ≥ 25 同时拒绝网络；Node 22 / 24 只管文件、子进程、
- * worker 与 addon，不管网络——脚本若逃出 `vm` 就能联网。所以：
- * - Node ≥ 25 → `strict`；
- * - Node 22 / 24 → 仍可用，但工具描述与状态栏标注「网络未隔离」；`codemode.requireStrict: true`
- *   时直接禁用 codemode 工具并 warning（`codemodeAvailability`）。
+ * worker 与 addon，不管网络——脚本若逃出 `vm` 就能联网。子进程另外经操作系统沙箱（macOS
+ * sandbox-exec、Linux bwrap / unshare，src/sandbox）启动时，网络由内核拒绝。所以：
+ * - Node ≥ 25 → `strict`（OS 沙箱可用时叠加，纵深防御）；
+ * - Node 22 / 24 + 可用的 OS 沙箱 → `strict`（子进程必须经 OS 沙箱启动）；
+ * - Node 22 / 24 且没有 OS 沙箱 → 仍可用，但工具描述与状态栏标注「网络未隔离」；
+ *   `codemode.requireStrict: true` 时直接禁用 codemode 工具并 warning（`codemodeAvailability`）。
  *
- * 状态栏由 B7 直接调用 `detectSandboxCapability()` 判断（不经宿主 status）。
+ * 能力在进程内只探测一次（OS 沙箱探针有缓存），同一环境下描述与权限类字节稳定。状态栏直接调用
+ * `detectSandboxCapability()`（不经宿主 status）；组装根先用 `configureOsSandbox` 记下 `sandbox.enabled`。
  */
+import { NO_OS_SANDBOX, osSandboxStatus } from "../sandbox/detect.js";
 export const NETWORK_NOT_ISOLATED = "network not isolated";
 export function parseNodeMajor(version) {
     const major = Number.parseInt(version.replace(/^v/, "").split(".")[0] ?? "", 10);
@@ -18,8 +22,13 @@ export function parseNodeMajor(version) {
 export function permissionFlagFor(allowedFlags = process.allowedNodeEnvironmentFlags) {
     return allowedFlags.has("--permission") ? "--permission" : "--experimental-permission";
 }
-export function detectSandboxCapability(nodeVersion = process.versions.node, allowedFlags) {
-    const nodeMajor = parseNodeMajor(nodeVersion);
+/**
+ * 运行时的沙箱能力。`os` 缺省：不传 `nodeVersion` 时用进程内缓存的探测结果（`osSandboxStatus()`）；
+ * 传了假设的 Node 版本（测试、展示）时不探测，按没有 OS 沙箱算，需要时显式传入。
+ */
+export function detectSandboxCapability(nodeVersion, allowedFlags, os) {
+    const osStatus = os ?? (nodeVersion === undefined ? osSandboxStatus() : NO_OS_SANDBOX);
+    const nodeMajor = parseNodeMajor(nodeVersion ?? process.versions.node);
     const permissionFlag = permissionFlagFor(allowedFlags);
     if (nodeMajor >= 25) {
         return {
@@ -27,6 +36,16 @@ export function detectSandboxCapability(nodeVersion = process.versions.node, all
             nodeMajor,
             reason: `Node ${nodeMajor}: the permission model blocks file access, child processes and network`,
             permissionFlag,
+            os: osStatus,
+        };
+    }
+    if (osStatus.isolatesNetwork) {
+        return {
+            strict: true,
+            nodeMajor,
+            reason: `Node ${nodeMajor}: the OS sandbox (${osStatus.kind}) blocks network; the permission model blocks file access and child processes`,
+            permissionFlag,
+            os: osStatus,
         };
     }
     return {
@@ -34,8 +53,17 @@ export function detectSandboxCapability(nodeVersion = process.versions.node, all
         nodeMajor,
         reason: `Node ${nodeMajor}: ${NETWORK_NOT_ISOLATED} (the permission model blocks file access and child processes only)`,
         permissionFlag,
+        os: osStatus,
     };
 }
+/** 按配置的 `sandbox.enabled`（缺省 auto）得到运行时能力。 */
+export function sandboxCapabilityFor(config) {
+    return detectSandboxCapability(undefined, undefined, osSandboxStatus(config.sandbox?.enabled ?? "auto"));
+}
+/** strict 是否依赖 OS 沙箱（Node 22 / 24）：此时子进程必须经 OS 沙箱启动，包装不了就报错。 */
+export function strictNeedsOsSandbox(capability) {
+    return capability.strict && capability.nodeMajor < 25;
+}
 /** `requireStrict` 且运行时不是 strict → 禁用并给出 warning；非 strict 但允许 → 可用并提示。 */
 export function codemodeAvailability(requireStrict, capability = detectSandboxCapability()) {
     if (capability.strict)
@@ -44,12 +72,12 @@ export function codemodeAvailability(requireStrict, capability = detectSandboxCa
         return {
             available: false,
             capability,
-            warning: `codemode 已禁用：Node ${capability.nodeMajor} 的权限模型不隔离网络（codemode.requireStrict 为 true；Node ≥ 25 才隔离）`,
+            warning: `codemode 已禁用：Node ${capability.nodeMajor} 的权限模型不隔离网络，也没有可用的操作系统沙箱（${capability.os.detail}；codemode.requireStrict 为 true；Node ≥ 25 或 macOS sandbox-exec / Linux bwrap 可隔离）`,
         };
     }
     return {
         available: true,
         capability,
-        warning: `codemode：Node ${capability.nodeMajor} 下网络未隔离（Node ≥ 25 才隔离；要求隔离可设 codemode.requireStrict）`,
+        warning: `codemode：Node ${capability.nodeMajor} 下网络未隔离（没有可用的操作系统沙箱：${capability.os.detail}；要求隔离可设 codemode.requireStrict）`,
     };
 }