@angelky7/dsh-browser-control 1.7.3 → 1.7.5

package/lib/types/audit.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 操作审计（v1.7.4）：插件这一侧到底发过哪些命令、被拒了几次、各自用了多久。
+ *
+ * 存在的理由不是「日志」，而是回答两个现实问题：出事后「刚才谁动了这个页面」，
+ * 以及做「会话恢复」之前先得有一份可靠的行为底账。所以：
+ *
+ *   - **记录在命令层**（controller.execute），不是工具层：模型看不到的内部重试、
+ *     browser_drag 一次拖拽打出的 N 次 cdp 往返，都在账上，不美化。
+ *   - **只存内存**（环形缓冲，200 条）：跨 dsh 重启的持久化是「会话恢复」那一版的事；
+ *     这一版先把账记对，别把磁盘格式写死。
+ *   - **参数摘要是脱敏后的**：输入框的值、cookie 的值、令牌类字段一律打码；
+ *     表达式截断。审计的用途是「做了什么」，不是「内容是什么」。
+ */
+export interface AuditEntry {
+    seq: number;
+    /** epoch 毫秒 */
+    t: number;
+    command: string;
+    tabId?: number;
+    /** 脱敏后的参数摘要（JSON 文本，已截断） */
+    params: string;
+    ok: boolean;
+    code?: string;
+    effectState?: string;
+    /** 失败描述，截断 */
+    error?: string;
+    durationMs: number;
+}
+export interface AuditFilter {
+    tabId?: number;
+    /** 命令名子串匹配（如 "nav" 命中 nav / browser.info? 不需要——命令名如 tabs.open） */
+    command?: string;
+    /** 只返回 seq 严格大于它的条目（分页） */
+    sinceSeq?: number;
+    /** 最多返回多少条（取最新的 N 条，按 seq 升序给出） */
+    limit?: number;
+}
+/** 环形缓冲上限。200 条足够覆盖一次排障现场，又不至于让内存跟着会话长度涨。 */
+export declare const AUDIT_MAX_ENTRIES = 200;
+/**
+ * 把一次调用的参数压成可审计的摘要：敏感键打码、特定命令的 value 打码、
+ * 长表达式截断、整体限长。返回 JSON 文本——审计工具原样把它交给模型。
+ */
+export declare function summarizeAuditParams(command: string, params: Record<string, unknown>): string;
+/** 记账器。一个桥（一个插件实例）一份；`record` 只追加，`list` 只读。 */
+export declare class AuditLog {
+    private readonly entries;
+    private nextSeq;
+    private readonly now;
+    constructor(now?: () => number);
+    /**
+     * 记一笔。
+     * @param input - 命令、摘要与结果；seq/t 由账本自己盖，durationMs 由调用方量。
+     */
+    record(input: {
+        command: string;
+        tabId?: number;
+        params: string;
+        ok: boolean;
+        code?: string;
+        effectState?: string;
+        error?: string;
+        durationMs: number;
+    }): AuditEntry;
+    /** 现有条目数（被挤掉的不算）。 */
+    size(): number;
+    /**
+     * 过滤并取最新的一批。
+     * @param filter - tabId / 命令子串 / sinceSeq / limit；返回按 seq 升序。
+     */
+    list(filter?: AuditFilter): AuditEntry[];
+}

package/lib/types/audit.js

@@ -0,0 +1,107 @@
+/** 环形缓冲上限。200 条足够覆盖一次排障现场，又不至于让内存跟着会话长度涨。 */
+export const AUDIT_MAX_ENTRIES = 200;
+/** 单条参数摘要上限：审计要的是形状，不是全文。 */
+const AUDIT_PARAMS_MAX_CHARS = 300;
+/** 失败描述上限。 */
+const AUDIT_ERROR_MAX_CHARS = 200;
+/** eval 表达式只留前 120 字符：里面可能有凭据。 */
+const AUDIT_EXPRESSION_MAX_CHARS = 120;
+/** 参数里这些键的值一律打码（大小写不敏感）。 */
+const SECRET_KEY = /^(token|authorization|password|passwd|secret|apikey|api_key|cookie)$/i;
+/**
+ * 哪个命令的 `value` 字段是敏感内容：`input` 是往页面里打的字（可能是密码），
+ * `cookies.set` 直接写凭据。其余命令的 value 字段（如果有）不动。
+ */
+const VALUE_REDACTED_COMMANDS = new Set(['input', 'cookies.set']);
+function redactValue(value) {
+    const length = typeof value === 'string' ? [...value].length : 0;
+    return `[redacted:${length} chars]`;
+}
+/**
+ * 把一次调用的参数压成可审计的摘要：敏感键打码、特定命令的 value 打码、
+ * 长表达式截断、整体限长。返回 JSON 文本——审计工具原样把它交给模型。
+ */
+export function summarizeAuditParams(command, params) {
+    let text;
+    try {
+        text = JSON.stringify(params, (key, value) => {
+            if (SECRET_KEY.test(key))
+                return '[redacted]';
+            if (key === 'value' && VALUE_REDACTED_COMMANDS.has(command))
+                return redactValue(value);
+            if (key === 'expression' && typeof value === 'string' && [...value].length > AUDIT_EXPRESSION_MAX_CHARS) {
+                return `${[...value].slice(0, AUDIT_EXPRESSION_MAX_CHARS).join('')}…[+${[...value].length - AUDIT_EXPRESSION_MAX_CHARS} chars]`;
+            }
+            return value;
+        }) ?? '{}';
+    }
+    catch {
+        text = '[unserializable params]';
+    }
+    return [...text].length > AUDIT_PARAMS_MAX_CHARS
+        ? `${[...text].slice(0, AUDIT_PARAMS_MAX_CHARS).join('')}…[+${[...text].length - AUDIT_PARAMS_MAX_CHARS} chars]`
+        : text;
+}
+/** 记账器。一个桥（一个插件实例）一份；`record` 只追加，`list` 只读。 */
+export class AuditLog {
+    entries = [];
+    nextSeq = 1;
+    now;
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /**
+     * 记一笔。
+     * @param input - 命令、摘要与结果；seq/t 由账本自己盖，durationMs 由调用方量。
+     */
+    record(input) {
+        const entry = {
+            seq: this.nextSeq++,
+            t: this.now(),
+            command: input.command,
+            params: input.params,
+            ok: input.ok,
+            durationMs: Math.max(0, Math.round(input.durationMs)),
+        };
+        if (input.tabId !== undefined)
+            entry.tabId = input.tabId;
+        if (input.code !== undefined)
+            entry.code = input.code;
+        if (input.effectState !== undefined)
+            entry.effectState = input.effectState;
+        if (input.error !== undefined) {
+            entry.error = [...input.error].length > AUDIT_ERROR_MAX_CHARS
+                ? `${[...input.error].slice(0, AUDIT_ERROR_MAX_CHARS).join('')}…`
+                : input.error;
+        }
+        this.entries.push(entry);
+        // 环形缓冲：超出上限从最旧的一端丢。seq 不回收——调用方拿 seq 分页时
+        // 「中间缺了号」本身就是「被挤掉了」的机器可读信号。
+        if (this.entries.length > AUDIT_MAX_ENTRIES)
+            this.entries.splice(0, this.entries.length - AUDIT_MAX_ENTRIES);
+        return entry;
+    }
+    /** 现有条目数（被挤掉的不算）。 */
+    size() {
+        return this.entries.length;
+    }
+    /**
+     * 过滤并取最新的一批。
+     * @param filter - tabId / 命令子串 / sinceSeq / limit；返回按 seq 升序。
+     */
+    list(filter = {}) {
+        let matched = this.entries;
+        if (filter.tabId !== undefined)
+            matched = matched.filter((e) => e.tabId === filter.tabId);
+        if (filter.command !== undefined && filter.command.length > 0) {
+            const needle = filter.command.toLowerCase();
+            matched = matched.filter((e) => e.command.toLowerCase().includes(needle));
+        }
+        if (filter.sinceSeq !== undefined) {
+            const floor = filter.sinceSeq;
+            matched = matched.filter((e) => e.seq > floor);
+        }
+        const limit = Math.min(AUDIT_MAX_ENTRIES, Math.max(1, Math.trunc(filter.limit ?? 50)));
+        return matched.slice(Math.max(0, matched.length - limit));
+    }
+}

package/lib/types/index.d.ts

@@ -40,7 +40,14 @@ export interface Config {
     /**
      * Directory screenshots are written to and `cleanup` clears. Relative paths
      * resolve against the process working directory at resolve time.
-     */ shotsDir?: string;
+     */
+    shotsDir?: string;
+    /**
+     * Directory the command journal is written to (v1.7.5 session recovery).
+     * Defaults to `~/.dsh-browser-control` — stable across restarts regardless
+     * of the process working directory.
+     */
+    stateDir?: string;
     /**
      * Read-only mode: refuse every command that would change the page or the
      * browser (click / input / press / nav / scroll / tabs.* / emulate / dialog /

package/lib/types/index.js

@@ -18,12 +18,15 @@
  * @module @deepseek-ai/dsh-browser-bridge
  */
 import { mkdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import path from 'node:path';
 import z from '@deepseek-ai/schemastery';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { BridgeServer, cleanupArtifacts } from "./server.js";
 import { BridgeError, classify } from "./errors.js";
 import { policyRefusal } from "./policy.js";
+import { AUDIT_MAX_ENTRIES, AuditLog, summarizeAuditParams } from "./audit.js";
+import { Journal, readJournal } from "./journal.js";
 /** Navigation wait ceiling (same as browser_wait); the bridge gets this plus BRIDGE_MARGIN_MS. */
 const NAV_MAX_MS = 120_000;
 /**
@@ -54,6 +57,8 @@ export const Config = z.object({
     port: z.number().step(1).min(1024).max(65_535).default(9777),
     token: z.string().default('dsh-local'),
     shotsDir: z.string().default('dsh-browser-shots'),
+    // 审计账本落盘目录（v1.7.5 会话恢复）。默认放用户主目录，跟 dsh 的启动目录无关。
+    stateDir: z.string().default(path.join(homedir(), '.dsh-browser-control')),
     readOnly: z.boolean().default(false),
     allowScript: z.boolean().default(true),
 });
@@ -116,6 +121,10 @@ class BridgeController {
     lastError;
     chain = Promise.resolve();
     current;
+    journal;
+    journalKey = '';
+    /** 操作审计账本（内存环形缓冲，200 条；命令层记录，见 audit.ts 顶部注释）。 */
+    audit = new AuditLog();
     constructor(log) {
         this.log = log;
     }
@@ -123,6 +132,17 @@ class BridgeController {
     get shotsDir() {
         return this.current === undefined ? undefined : path.resolve(this.current.shotsDir);
     }
+    /** 审计账本落盘目录；配置到达之前是 undefined。 */
+    get stateDir() {
+        return this.current === undefined ? undefined : path.resolve(this.current.stateDir);
+    }
+    /**
+     * Record one audit entry in memory and, when the journal is open, on disk.
+     * Journal appends are queued and never block the command path.
+     */
+    recordAudit(input) {
+        this.journal?.append(this.audit.record(input));
+    }
     /**
      * Current policy flags. Tools that compose several commands (browser_drag
      * runs `cdp`/`eval`) read this to refuse with a tool-level message; the
@@ -161,6 +181,16 @@ class BridgeController {
     requireExtensionCommand(command, since) {
         if (this.hasExtensionCommand(command))
             return;
+        // 预检拒绝也要上账：这是「升级插件后模型发现功能不可用」的最常见现场。
+        this.recordAudit({
+            command,
+            params: '',
+            ok: false,
+            code: 'extension_outdated',
+            effectState: 'not_started',
+            error: `connected extension v${this.extensionVersion() ?? '?'} lacks ${command} (added in ${since})`,
+            durationMs: 0,
+        });
         throw extensionOutdatedError(this.extensionVersion(), command, since);
     }
     /**
@@ -184,6 +214,20 @@ class BridgeController {
     }
     async reconcileNow(config) {
         const shotsDir = path.resolve(config.shotsDir);
+        const stateDir = path.resolve(config.stateDir);
+        if (stateDir !== this.journalKey) {
+            const previousJournal = this.journal;
+            this.journal = undefined;
+            this.journalKey = stateDir;
+            await previousJournal?.close();
+            try {
+                this.journal = await Journal.open(stateDir, this.log);
+            }
+            catch (error) {
+                // 账本打不开不是让桥起不来的理由：降级为纯内存审计。
+                this.log(`journal: disabled — ${errorMessage(error)}`);
+            }
+        }
         const key = config.enabled ? `${config.port}|${config.token}|${shotsDir}` : '';
         if (key === this.serverKey)
             return;
@@ -221,12 +265,34 @@ class BridgeController {
      * @returns the extension's result payload verbatim.
      */
     async execute(command, params, signal, timeoutMs) {
-        this.policyGate(command, params);
-        const server = this.server;
-        if (server === undefined) {
-            throw classify(command, new Error(this.lastError ?? '浏览器控制未启用 —— 在 profile 的 cordis.patch.yml 里给 browser-bridge 配 enabled: true（dsh 0.1.7+ 的宿主也会在设置 → 插件 自动列出本插件开关；0.1.2 及更早的宿主没有这张卡片，只能改配置文件）'));
+        const started = Date.now();
+        const summary = summarizeAuditParams(command, params);
+        const tabId = typeof params.tabId === 'number' ? params.tabId : undefined;
+        try {
+            this.policyGate(command, params);
+            const server = this.server;
+            if (server === undefined) {
+                throw classify(command, new Error(this.lastError ?? '浏览器控制未启用 —— 在 profile 的 cordis.patch.yml 里给 browser-bridge 配 enabled: true（dsh 0.1.7+ 的宿主也会在设置 → 插件 自动列出本插件开关；0.1.2 及更早的宿主没有这张卡片，只能改配置文件）'));
+            }
+            const result = await server.execute(command, params, timeoutMs === undefined ? { signal } : { signal, timeoutMs });
+            this.recordAudit({ command, tabId, params: summary, ok: true, durationMs: Date.now() - started });
+            return result;
+        }
+        catch (error) {
+            const code = error.code;
+            const effectState = error.effectState;
+            this.recordAudit({
+                command,
+                tabId,
+                params: summary,
+                ok: false,
+                code: typeof code === 'string' ? code : undefined,
+                effectState: typeof effectState === 'string' ? effectState : undefined,
+                error: errorMessage(error),
+                durationMs: Date.now() - started,
+            });
+            throw error;
         }
-        return server.execute(command, params, timeoutMs === undefined ? { signal } : { signal, timeoutMs });
     }
     /**
      * Refuse a command the local policy forbids, before anything is sent or deleted.
@@ -252,27 +318,50 @@ class BridgeController {
      * @returns counts and names of what was removed.
      */
     async cleanup() {
-        // cleanup() 不经过 execute()，所以它必须自己站一次闸门：否则只读档下
-        // 模型仍能用 browser_cleanup 删掉用户的整个截图目录。
-        this.policyGate('cleanup');
-        const dir = this.shotsDir;
-        if (dir === undefined)
-            throw classify('cleanup', new Error('browser-bridge is not configured yet —— 浏览器控制尚未加载配置，无法确定清理目录'));
+        const started = Date.now();
         try {
-            return await cleanupArtifacts({ shotsDir: dir });
+            // cleanup() 不经过 execute()，所以它必须自己站一次闸门：否则只读档下
+            // 模型仍能用 browser_cleanup 删掉用户的整个截图目录。
+            this.policyGate('cleanup');
+            const dir = this.shotsDir;
+            if (dir === undefined)
+                throw classify('cleanup', new Error('browser-bridge is not configured yet —— 浏览器控制尚未加载配置，无法确定清理目录'));
+            try {
+                const result = await cleanupArtifacts({ shotsDir: dir });
+                this.recordAudit({ command: 'cleanup', params: '{}', ok: true, durationMs: Date.now() - started });
+                return result;
+            }
+            catch (error) {
+                // 删除是逐条进行的，中途失败时前面的文件已经没了；不包一层分类，
+                // 模型拿到的就是一句没有 code / effectState 的裸 fs 错误。
+                throw classify('cleanup', error);
+            }
         }
         catch (error) {
-            // 删除是逐条进行的，中途失败时前面的文件已经没了；不包一层分类，
-            // 模型拿到的就是一句没有 code / effectState 的裸 fs 错误。
-            throw classify('cleanup', error);
+            const code = error.code;
+            const effectState = error.effectState;
+            this.recordAudit({
+                command: 'cleanup',
+                params: '{}',
+                ok: false,
+                code: typeof code === 'string' ? code : undefined,
+                effectState: typeof effectState === 'string' ? effectState : undefined,
+                error: errorMessage(error),
+                durationMs: Date.now() - started,
+            });
+            throw error;
         }
     }
     /** Stop the listener; safe to call repeatedly and during teardown. */
-    stop() {
+    async stop() {
         const previous = this.server;
         this.server = undefined;
         this.serverKey = '';
-        return previous?.stop() ?? Promise.resolve();
+        await (previous?.stop() ?? Promise.resolve());
+        const journal = this.journal;
+        this.journal = undefined;
+        this.journalKey = '';
+        await journal?.close();
     }
 }
 function errorMessage(error) {
@@ -1692,6 +1781,8 @@ function applyBrowserTools(ctx, controller) {
         },
     }));
     registerDragTool(ctx, controller);
+    registerAuditTool(ctx, controller);
+    registerJournalTool(ctx, controller);
 }
 /* ------------------- browser_drag: composed plugin-side over the cdp channel ------------------- */
 /** One CDP round-trip over the embedded `cdp` passthrough (extension v1.7.2+). */
@@ -1958,6 +2049,140 @@ function registerDragTool(ctx, controller) {
         },
     }));
 }
+function registerAuditTool(ctx, controller) {
+    ctx.tools.register(defineTool({
+        name: 'browser_audit',
+        description: 'Read this plugin session\'s in-memory audit trail: every command sent to the browser extension (and every policy/gate refusal), with redacted params, outcome code and duration. Newest last; capped at 200 entries and wiped when dsh restarts. Values typed into pages and cookie values are redacted; eval expressions are truncated. Plugin-local read — works in read-only mode.',
+        parameters: {
+            command: { type: 'string', description: 'Only entries whose command contains this substring (e.g. "nav", "cookies", "tabs").' },
+            tabId: { type: 'number', description: 'Only entries that carried this tabId.' },
+            sinceSeq: { type: 'number', description: 'Only entries with seq greater than this (paging).' },
+            limit: { type: 'number', description: `Max entries to return (newest last), 1–${AUDIT_MAX_ENTRIES}; default 50.` },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    total: { type: 'number', required: true },
+                    shown: { type: 'number', required: true },
+                    entries: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                seq: { type: 'number', required: true },
+                                t: { type: 'number', required: true },
+                                command: { type: 'string', required: true },
+                                tabId: { type: 'number' },
+                                params: { type: 'string', required: true },
+                                ok: { type: 'boolean', required: true },
+                                code: { type: 'string' },
+                                effectState: { type: 'string' },
+                                error: { type: 'string' },
+                                durationMs: { type: 'number', required: true },
+                            },
+                        },
+                    },
+                },
+            },
+            render: (_args, value) => {
+                const v = value;
+                if (v.entries.length === 0) {
+                    return [{ type: 'text', text: `Audit: ${v.total} entries, none match — the trail starts when a command is executed.` }];
+                }
+                const lines = v.entries.map((e) => {
+                    const tab = e.tabId === undefined ? '' : ` tab ${e.tabId}`;
+                    const outcome = e.ok ? 'ok' : `FAIL ${e.code ?? 'error'}${e.effectState ? `/${e.effectState}` : ''}`;
+                    const err = e.ok || e.error === undefined ? '' : ` — ${e.error}`;
+                    return `#${e.seq} ${formatClock(e.t)} ${e.command}${tab} ${outcome} ${e.durationMs}ms ${e.params}${err}`;
+                });
+                return [{ type: 'text', text: clampRendered(`Audit: ${v.total} entries (showing ${v.shown})\n${lines.join('\n')}`) }];
+            },
+        },
+        presentCall: () => ({ card: 'generic', title: 'Browser audit', kind: 'other' }),
+        async execute(args) {
+            const entries = controller.audit.list({
+                tabId: args.tabId,
+                command: args.command,
+                sinceSeq: args.sinceSeq,
+                limit: args.limit,
+            });
+            return { total: controller.audit.size(), shown: entries.length, entries };
+        },
+    }));
+}
+function registerJournalTool(ctx, controller) {
+    ctx.tools.register(defineTool({
+        name: 'browser_journal',
+        description: 'Read the persistent command journal across dsh restarts: every command from previous runs of this plugin (written to <stateDir>/journal.jsonl, last 1000 entries), grouped by run. Same redaction as browser_audit. Plugin-local disk read — works with the extension offline and in read-only mode, so it is the way to recover "what was I doing" after a restart.',
+        parameters: {
+            command: { type: 'string', description: 'Only entries whose command contains this substring.' },
+            tabId: { type: 'number', description: 'Only entries that carried this tabId.' },
+            limit: { type: 'number', description: 'Max entries to return (newest last), 1–500; default 50.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    total: { type: 'number', required: true },
+                    shown: { type: 'number', required: true },
+                    runs: { type: 'number', required: true },
+                    entries: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                run: { type: 'string', required: true },
+                                seq: { type: 'number', required: true },
+                                t: { type: 'number', required: true },
+                                command: { type: 'string', required: true },
+                                tabId: { type: 'number' },
+                                params: { type: 'string', required: true },
+                                ok: { type: 'boolean', required: true },
+                                code: { type: 'string' },
+                                effectState: { type: 'string' },
+                                error: { type: 'string' },
+                                durationMs: { type: 'number', required: true },
+                            },
+                        },
+                    },
+                },
+            },
+            render: (_args, value) => {
+                const v = value;
+                if (v.entries.length === 0) {
+                    return [{ type: 'text', text: `Journal: ${v.total} entries on disk, none match — nothing recorded across runs yet.` }];
+                }
+                const lines = [];
+                let run = '';
+                for (const e of v.entries) {
+                    if (e.run !== run) {
+                        run = e.run;
+                        lines.push(`── run ${run}`);
+                    }
+                    const tab = e.tabId === undefined ? '' : ` tab ${e.tabId}`;
+                    const outcome = e.ok ? 'ok' : `FAIL ${e.code ?? 'error'}`;
+                    lines.push(`#${e.seq} ${formatClock(e.t)} ${e.command}${tab} ${outcome} ${e.durationMs}ms ${e.params}`);
+                }
+                return [{ type: 'text', text: clampRendered(`Journal: ${v.total} entries in ${v.runs} run(s) (showing ${v.shown})\n${lines.join('\n')}`) }];
+            },
+        },
+        presentCall: () => ({ card: 'generic', title: 'Browser journal', kind: 'other' }),
+        async execute(args) {
+            const dir = controller.stateDir;
+            if (dir === undefined)
+                throw new Error('browser-bridge is not configured yet — the journal has no stateDir to read');
+            const { total, entries } = await readJournal(dir, { command: args.command, tabId: args.tabId, limit: args.limit });
+            return { total, shown: entries.length, runs: new Set(entries.map((e) => e.run)).size, entries };
+        },
+    }));
+}
 /** Cordis plugin entry: wire the settings-driven lifecycle plus the model-facing tools. */
 export function apply(ctx, config) {
     const resolved = config;

package/lib/types/journal.d.ts

@@ -0,0 +1,45 @@
+import type { AuditEntry } from './audit.ts';
+/** 磁盘上最多保留的条数（启动时裁剪）。 */
+export declare const JOURNAL_MAX_LINES = 1000;
+/** 一行 = 一次运行的编号 + 审计条目。 */
+export interface JournalEntry extends AuditEntry {
+    /** 这次插件运行的身份（启动时刻，ISO 秒）。跨运行恢复靠它分组。 */
+    run: string;
+}
+export interface JournalFilter {
+    tabId?: number;
+    command?: string;
+    limit?: number;
+}
+/**
+ * 打开（并按需裁剪）一个 journal 目录。
+ * @param stateDir - 目录（不存在会创建）；journal 文件是 `<stateDir>/journal.jsonl`。
+ * @param log - 一行式日志；打开/裁剪的结论写进去。
+ * @returns 带 run 编号的追加器；`close()` 等所有在途写入落盘。
+ */
+export declare class Journal {
+    /** 这次运行的编号：启动时刻（毫秒精度；秒级精度下两次启动同秒会撞号）。 */
+    readonly runId: string;
+    private readonly file;
+    private readonly log;
+    private chain;
+    private warned;
+    private constructor();
+    static open(stateDir: string, log: (line: string) => void): Promise<Journal>;
+    /**
+     * 追加一条（异步、排队写；失败只告警一次，绝不阻塞命令路径）。
+     * @param entry - AuditLog 刚记下的条目（参数已脱敏）。
+     */
+    append(entry: AuditEntry): void;
+    /** 等在途写入落盘（teardown / 测试用）。 */
+    close(): Promise<void>;
+}
+/**
+ * 读 journal 的尾部（不要求 Journal 实例——读在线程外也能工作，扩展离线也行）。
+ * @param stateDir - journal 所在目录。
+ * @param filter - tabId / 命令子串 / 条数（默认 50，最大 500；取最新）。
+ */
+export declare function readJournal(stateDir: string, filter?: JournalFilter): Promise<{
+    total: number;
+    entries: JournalEntry[];
+}>;