@angelky7/dsh-browser-control 1.7.4 → 1.7.5

package/README.en.md

@@ -269,10 +269,11 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `browser_metrics` | Read performance counters (DOM nodes / JS heap / layout & script durations, Performance.getMetrics, read-only; puts numbers behind "this page is heavy", v1.7.1+) |
 | `browser_drag` | Drag from/to a selector or viewport point: `auto` synthesizes html5 dragstart→dragover→drop for `draggable="true"` sources (no drop unless accepted), otherwise sends real mouse input (press, interpolated moves, release — sliders/canvas/sortable widgets). **Plugin-side only** over the cdp channel embedded in extension v1.7.2, v1.7.3+ |
 | `browser_audit` | Read this plugin session's in-memory audit trail — every command sent or refused (redacted params, `code`/`effectState`, duration), capped at 200 entries and wiped on restart; typed text and cookie values are redacted, eval expressions truncated. Plugin-local read, works in read-only mode (v1.7.4+) |
+| `browser_journal` | Read the **persistent journal across dsh restarts** (`<stateDir>/journal.jsonl`, last 1000 entries, grouped by run) — ask it after a restart "what was I doing in which tab"; same redaction; plugin-local disk read that works with the extension offline (v1.7.5+) |
 | `browser_cleanup` | Clean up temp files |
 | `browser_info` | Which browser and extension build is attached (run it first when debugging, v1.0.9+) |
 
-27 tools in total. `browser_wait`, `browser_find`, `browser_dialog` and `browser_info` existed inside the extension up to v1.0.8 but were never registered as tools, so the agent could not reach them; `browser_network_clear` existed in code and was simply missing from this table. `verify/verify_surface.mjs` now reconciles the extension command table, the commands the plugin calls, this table and the built bundle, so any drift fails `npm run verify`.
+28 tools in total. `browser_wait`, `browser_find`, `browser_dialog` and `browser_info` existed inside the extension up to v1.0.8 but were never registered as tools, so the agent could not reach them; `browser_network_clear` existed in code and was simply missing from this table. `verify/verify_surface.mjs` now reconciles the extension command table, the commands the plugin calls, this table and the built bundle, so any drift fails `npm run verify`.
 
 ## Architecture
 

package/README.md

@@ -262,11 +262,12 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `browser_metrics` | 读性能计数器（DOM 节点数 / JS 堆 / 布局与脚本耗时，Performance.getMetrics，只读；让「这页面很重」有数字说话，v1.7.1+） |
 | `browser_drag` | 拖拽：from/to 用选择器或视口坐标；`auto` 对 `draggable="true"` 的源走 html5 事件合成（dragstart→dragover→drop，未接受就不 drop），其余走真实鼠标输入（按下→插值移动→抬起，滑杆/画布/排序组件用这个）。**纯插件实现**（经 v1.7.2 预埋的 cdp 通道），v1.7.3+ |
 | `browser_audit` | 读本次插件会话的内存审计账本：发过/被拒的每条命令（参数脱敏、`code`/`effectState`、耗时），最多 200 条、dsh 重启即清；输入的文字与 cookie 值打码、eval 表达式截断。纯本地读，只读档下照常可用（v1.7.4+） |
+| `browser_journal` | 读**跨 dsh 重启**的持久命令账本（`<stateDir>/journal.jsonl`，最多 1000 条，按运行分组）——重启后先问它「上个会话在哪个标签页干了什么」；同样的脱敏规则；纯本地磁盘读，**扩展离线也能用**（v1.7.5+） |
 | `browser_windows` | 窗口控制：清单/开窗/改状态与几何/关整窗/跨窗挪标签（唯一能碰窗口几何的工具，v1.6.0+） |
 | `browser_cleanup` | 清理临时文件 |
 | `browser_info` | 报告实际连上的浏览器与扩展版本（排障先跑它，v1.0.9+） |
 
-共 27 个工具。`browser_wait` / `browser_find` / `browser_dialog` / `browser_info` 在 v1.0.8 及以前是「扩展里已实现、但没注册成工具」，agent 调不到；`browser_network_clear` 则是代码里有、这张表漏了。这些现在由 `verify/verify_surface.mjs` 做三方对账（扩展命令表 ↔ 插件调用 ↔ 文档表 ↔ 构建产物），漂移会直接让 `npm run verify` 失败。
+共 28 个工具。`browser_wait` / `browser_find` / `browser_dialog` / `browser_info` 在 v1.0.8 及以前是「扩展里已实现、但没注册成工具」，agent 调不到；`browser_network_clear` 则是代码里有、这张表漏了。这些现在由 `verify/verify_surface.mjs` 做三方对账（扩展命令表 ↔ 插件调用 ↔ 文档表 ↔ 构建产物），漂移会直接让 `npm run verify` 失败。
 
 ## 架构
 

package/lib/index.js

@@ -1,4 +1,5 @@
-import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, readFile, readdir, rename, rm, 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";
@@ -1013,6 +1014,127 @@ var AuditLog = class {
 	}
 };
 //#endregion
+//#region lib/types/journal.js
+/**
+* 会话恢复（v1.7.5）：把审计账本持久化到磁盘，dsh 重启以后还查得到上一个会话做过什么。
+*
+* 为什么是文件而不是数据库：一条命令一行 JSONL，出问题时能直接打开看、能 grep、
+* 写坏了最多丢一行（读到坏行跳过，不炸整本账）。上限 1000 行，超了在**启动时**
+* 裁掉最旧的——运行中不裁剪，append 永远是纯追加。
+*
+* 隐私与审计同一套：写盘的就是 AuditLog 里那份脱敏后的摘要（输入值/cookie 值已
+* 打码），journal 层不再碰原始参数。文件在 <stateDir>/journal.jsonl，stateDir
+* 默认 ~/.dsh-browser-control，可在 profile 的 browser-bridge 配置里改。
+*/
+/** 磁盘上最多保留的条数（启动时裁剪）。 */
+const JOURNAL_MAX_LINES = 1e3;
+/** 防御性上限：正常文件远小于它；超过就只读尾巴，别为了一本账吃掉内存。 */
+const JOURNAL_MAX_BYTES = 8388608;
+function isEntry(value) {
+	if (value === null || typeof value !== "object") return false;
+	const v = value;
+	return typeof v.run === "string" && typeof v.command === "string" && typeof v.seq === "number" && typeof v.t === "number" && typeof v.params === "string" && typeof v.ok === "boolean" && typeof v.durationMs === "number";
+}
+/** 拆行并解析；坏行（截断、手改坏）跳过——一本账不能因为一行烂掉就全废。 */
+function parseLines(text) {
+	const out = [];
+	for (const line of text.split("\n")) {
+		if (line.trim().length === 0) continue;
+		try {
+			const parsed = JSON.parse(line);
+			if (isEntry(parsed)) out.push(parsed);
+		} catch {}
+	}
+	return out;
+}
+/**
+* 打开（并按需裁剪）一个 journal 目录。
+* @param stateDir - 目录（不存在会创建）；journal 文件是 `<stateDir>/journal.jsonl`。
+* @param log - 一行式日志；打开/裁剪的结论写进去。
+* @returns 带 run 编号的追加器；`close()` 等所有在途写入落盘。
+*/
+var Journal = class Journal {
+	/** 这次运行的编号：启动时刻（毫秒精度；秒级精度下两次启动同秒会撞号）。 */
+	runId;
+	file;
+	log;
+	chain = Promise.resolve();
+	warned = false;
+	constructor(file, runId, log) {
+		this.file = file;
+		this.runId = runId;
+		this.log = log;
+	}
+	static async open(stateDir, log) {
+		await mkdir(stateDir, { recursive: true });
+		const file = path.join(stateDir, "journal.jsonl");
+		let existing = [];
+		try {
+			const text = await readFile(file, "utf8");
+			existing = parseLines(text.length > JOURNAL_MAX_BYTES ? text.slice(-8388608) : text);
+		} catch {}
+		if (existing.length > 1e3) {
+			const kept = existing.slice(existing.length - JOURNAL_MAX_LINES);
+			const tmp = `${file}.tmp`;
+			await writeFile(tmp, kept.map((e) => `${JSON.stringify(e)}\n`).join(""), "utf8");
+			await rename(tmp, file);
+			log(`journal: pruned ${existing.length - kept.length} old entries (${JOURNAL_MAX_LINES} kept)`);
+		} else if (existing.length > 0) {
+			const last = existing[existing.length - 1];
+			log(`journal: restored context — ${existing.length} entries on disk, last from run ${last.run} (#${last.seq} ${last.command})`);
+		}
+		return new Journal(file, (/* @__PURE__ */ new Date()).toISOString().slice(0, 23).replace("T", " "), log);
+	}
+	/**
+	* 追加一条（异步、排队写；失败只告警一次，绝不阻塞命令路径）。
+	* @param entry - AuditLog 刚记下的条目（参数已脱敏）。
+	*/
+	append(entry) {
+		const line = `${JSON.stringify({
+			run: this.runId,
+			...entry
+		})}\n`;
+		this.chain = this.chain.then(() => appendFile(this.file, line, "utf8")).catch((error) => {
+			if (!this.warned) {
+				this.warned = true;
+				this.log(`journal: write failed — ${error instanceof Error ? error.message : String(error)}`);
+			}
+		});
+	}
+	/** 等在途写入落盘（teardown / 测试用）。 */
+	async close() {
+		await this.chain.catch(() => {});
+	}
+};
+/**
+* 读 journal 的尾部（不要求 Journal 实例——读在线程外也能工作，扩展离线也行）。
+* @param stateDir - journal 所在目录。
+* @param filter - tabId / 命令子串 / 条数（默认 50，最大 500；取最新）。
+*/
+async function readJournal(stateDir, filter = {}) {
+	let text;
+	try {
+		text = await readFile(path.join(stateDir, "journal.jsonl"), "utf8");
+	} catch {
+		return {
+			total: 0,
+			entries: []
+		};
+	}
+	if (text.length > JOURNAL_MAX_BYTES) text = text.slice(-8388608);
+	let matched = parseLines(text);
+	if (filter.tabId !== void 0) matched = matched.filter((e) => e.tabId === filter.tabId);
+	if (filter.command !== void 0 && filter.command.length > 0) {
+		const needle = filter.command.toLowerCase();
+		matched = matched.filter((e) => e.command.toLowerCase().includes(needle));
+	}
+	const limit = Math.min(500, Math.max(1, Math.trunc(filter.limit ?? 50)));
+	return {
+		total: matched.length,
+		entries: matched.slice(Math.max(0, matched.length - limit))
+	};
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Browser-bridge plugin: one local WebSocket endpoint the DSH Browser Control
@@ -1065,6 +1187,7 @@ const Config = z.object({
 	port: z.number().step(1).min(1024).max(65535).default(9777),
 	token: z.string().default("dsh-local"),
 	shotsDir: z.string().default("dsh-browser-shots"),
+	stateDir: z.string().default(path.join(homedir(), ".dsh-browser-control")),
 	readOnly: z.boolean().default(false),
 	allowScript: z.boolean().default(true)
 });
@@ -1140,6 +1263,8 @@ var BridgeController = class {
 	lastError;
 	chain = Promise.resolve();
 	current;
+	journal;
+	journalKey = "";
 	/** 操作审计账本（内存环形缓冲，200 条；命令层记录，见 audit.ts 顶部注释）。 */
 	audit = new AuditLog();
 	constructor(log) {
@@ -1149,6 +1274,17 @@ var BridgeController = class {
 	get shotsDir() {
 		return this.current === void 0 ? void 0 : path.resolve(this.current.shotsDir);
 	}
+	/** 审计账本落盘目录；配置到达之前是 undefined。 */
+	get stateDir() {
+		return this.current === void 0 ? void 0 : 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
@@ -1186,7 +1322,7 @@ var BridgeController = class {
 	*/
 	requireExtensionCommand(command, since) {
 		if (this.hasExtensionCommand(command)) return;
-		this.audit.record({
+		this.recordAudit({
 			command,
 			params: "",
 			ok: false,
@@ -1216,6 +1352,18 @@ var BridgeController = class {
 	}
 	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 = void 0;
+			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;
 		const previous = this.server;
@@ -1267,7 +1415,7 @@ var BridgeController = class {
 				signal,
 				timeoutMs
 			});
-			this.audit.record({
+			this.recordAudit({
 				command,
 				tabId,
 				params: summary,
@@ -1278,7 +1426,7 @@ var BridgeController = class {
 		} catch (error) {
 			const code = error.code;
 			const effectState = error.effectState;
-			this.audit.record({
+			this.recordAudit({
 				command,
 				tabId,
 				params: summary,
@@ -1321,7 +1469,7 @@ var BridgeController = class {
 			if (dir === void 0) throw classify("cleanup", /* @__PURE__ */ new Error("browser-bridge is not configured yet —— 浏览器控制尚未加载配置，无法确定清理目录"));
 			try {
 				const result = await cleanupArtifacts({ shotsDir: dir });
-				this.audit.record({
+				this.recordAudit({
 					command: "cleanup",
 					params: "{}",
 					ok: true,
@@ -1334,7 +1482,7 @@ var BridgeController = class {
 		} catch (error) {
 			const code = error.code;
 			const effectState = error.effectState;
-			this.audit.record({
+			this.recordAudit({
 				command: "cleanup",
 				params: "{}",
 				ok: false,
@@ -1347,11 +1495,15 @@ var BridgeController = class {
 		}
 	}
 	/** Stop the listener; safe to call repeatedly and during teardown. */
-	stop() {
+	async stop() {
 		const previous = this.server;
 		this.server = void 0;
 		this.serverKey = "";
-		return previous?.stop() ?? Promise.resolve();
+		await (previous?.stop() ?? Promise.resolve());
+		const journal = this.journal;
+		this.journal = void 0;
+		this.journalKey = "";
+		await journal?.close();
 	}
 };
 function errorMessage(error) {
@@ -3295,6 +3447,7 @@ function applyBrowserTools(ctx, controller) {
 	}));
 	registerDragTool(ctx, controller);
 	registerAuditTool(ctx, controller);
+	registerJournalTool(ctx, controller);
 }
 /** One CDP round-trip over the embedded `cdp` passthrough (extension v1.7.2+). */
 async function cdpCall(ctrl, tabId, method, params, signal) {
@@ -3736,6 +3889,130 @@ function registerAuditTool(ctx, controller) {
 		}
 	}));
 }
+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 === void 0 ? "" : ` 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 === void 0) 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. */
 function apply(ctx, config) {
 	const resolved = config;

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,6 +18,7 @@
  * @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';
@@ -25,6 +26,7 @@ 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;
 /**
@@ -55,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),
 });
@@ -117,6 +121,8 @@ class BridgeController {
     lastError;
     chain = Promise.resolve();
     current;
+    journal;
+    journalKey = '';
     /** 操作审计账本（内存环形缓冲，200 条；命令层记录，见 audit.ts 顶部注释）。 */
     audit = new AuditLog();
     constructor(log) {
@@ -126,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
@@ -165,7 +182,7 @@ class BridgeController {
         if (this.hasExtensionCommand(command))
             return;
         // 预检拒绝也要上账：这是「升级插件后模型发现功能不可用」的最常见现场。
-        this.audit.record({
+        this.recordAudit({
             command,
             params: '',
             ok: false,
@@ -197,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;
@@ -244,13 +275,13 @@ class BridgeController {
                 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.audit.record({ command, tabId, params: summary, ok: true, durationMs: Date.now() - started });
+            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.audit.record({
+            this.recordAudit({
                 command,
                 tabId,
                 params: summary,
@@ -297,7 +328,7 @@ class BridgeController {
                 throw classify('cleanup', new Error('browser-bridge is not configured yet —— 浏览器控制尚未加载配置，无法确定清理目录'));
             try {
                 const result = await cleanupArtifacts({ shotsDir: dir });
-                this.audit.record({ command: 'cleanup', params: '{}', ok: true, durationMs: Date.now() - started });
+                this.recordAudit({ command: 'cleanup', params: '{}', ok: true, durationMs: Date.now() - started });
                 return result;
             }
             catch (error) {
@@ -309,7 +340,7 @@ class BridgeController {
         catch (error) {
             const code = error.code;
             const effectState = error.effectState;
-            this.audit.record({
+            this.recordAudit({
                 command: 'cleanup',
                 params: '{}',
                 ok: false,
@@ -322,11 +353,15 @@ class BridgeController {
         }
     }
     /** 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) {
@@ -1747,6 +1782,7 @@ 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+). */
@@ -2078,6 +2114,75 @@ function registerAuditTool(ctx, controller) {
         },
     }));
 }
+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[];
+}>;

package/lib/types/journal.js

@@ -0,0 +1,128 @@
+/**
+ * 会话恢复（v1.7.5）：把审计账本持久化到磁盘，dsh 重启以后还查得到上一个会话做过什么。
+ *
+ * 为什么是文件而不是数据库：一条命令一行 JSONL，出问题时能直接打开看、能 grep、
+ * 写坏了最多丢一行（读到坏行跳过，不炸整本账）。上限 1000 行，超了在**启动时**
+ * 裁掉最旧的——运行中不裁剪，append 永远是纯追加。
+ *
+ * 隐私与审计同一套：写盘的就是 AuditLog 里那份脱敏后的摘要（输入值/cookie 值已
+ * 打码），journal 层不再碰原始参数。文件在 <stateDir>/journal.jsonl，stateDir
+ * 默认 ~/.dsh-browser-control，可在 profile 的 browser-bridge 配置里改。
+ */
+import { appendFile, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+/** 磁盘上最多保留的条数（启动时裁剪）。 */
+export const JOURNAL_MAX_LINES = 1000;
+/** 防御性上限：正常文件远小于它；超过就只读尾巴，别为了一本账吃掉内存。 */
+const JOURNAL_MAX_BYTES = 8 * 1024 * 1024;
+function isEntry(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const v = value;
+    return typeof v.run === 'string'
+        && typeof v.command === 'string'
+        && typeof v.seq === 'number'
+        && typeof v.t === 'number'
+        && typeof v.params === 'string'
+        && typeof v.ok === 'boolean'
+        && typeof v.durationMs === 'number';
+}
+/** 拆行并解析；坏行（截断、手改坏）跳过——一本账不能因为一行烂掉就全废。 */
+function parseLines(text) {
+    const out = [];
+    for (const line of text.split('\n')) {
+        if (line.trim().length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (isEntry(parsed))
+                out.push(parsed);
+        }
+        catch { /* 坏行跳过 */ }
+    }
+    return out;
+}
+/**
+ * 打开（并按需裁剪）一个 journal 目录。
+ * @param stateDir - 目录（不存在会创建）；journal 文件是 `<stateDir>/journal.jsonl`。
+ * @param log - 一行式日志；打开/裁剪的结论写进去。
+ * @returns 带 run 编号的追加器；`close()` 等所有在途写入落盘。
+ */
+export class Journal {
+    /** 这次运行的编号：启动时刻（毫秒精度；秒级精度下两次启动同秒会撞号）。 */
+    runId;
+    file;
+    log;
+    chain = Promise.resolve();
+    warned = false;
+    constructor(file, runId, log) {
+        this.file = file;
+        this.runId = runId;
+        this.log = log;
+    }
+    static async open(stateDir, log) {
+        await mkdir(stateDir, { recursive: true });
+        const file = path.join(stateDir, 'journal.jsonl');
+        let existing = [];
+        try {
+            const text = await readFile(file, 'utf8');
+            existing = parseLines(text.length > JOURNAL_MAX_BYTES ? text.slice(-JOURNAL_MAX_BYTES) : text);
+        }
+        catch { /* 首次运行没有文件 */ }
+        if (existing.length > JOURNAL_MAX_LINES) {
+            const kept = existing.slice(existing.length - JOURNAL_MAX_LINES);
+            const tmp = `${file}.tmp`;
+            await writeFile(tmp, kept.map((e) => `${JSON.stringify(e)}\n`).join(''), 'utf8');
+            await rename(tmp, file);
+            log(`journal: pruned ${existing.length - kept.length} old entries (${JOURNAL_MAX_LINES} kept)`);
+        }
+        else if (existing.length > 0) {
+            const last = existing[existing.length - 1];
+            log(`journal: restored context — ${existing.length} entries on disk, last from run ${last.run} (#${last.seq} ${last.command})`);
+        }
+        return new Journal(file, new Date().toISOString().slice(0, 23).replace('T', ' '), log);
+    }
+    /**
+     * 追加一条（异步、排队写；失败只告警一次，绝不阻塞命令路径）。
+     * @param entry - AuditLog 刚记下的条目（参数已脱敏）。
+     */
+    append(entry) {
+        const line = `${JSON.stringify({ run: this.runId, ...entry })}\n`;
+        this.chain = this.chain.then(() => appendFile(this.file, line, 'utf8')).catch((error) => {
+            // 账本写不进去不是命令失败的理由：告警一次，继续跑。
+            if (!this.warned) {
+                this.warned = true;
+                this.log(`journal: write failed — ${error instanceof Error ? error.message : String(error)}`);
+            }
+        });
+    }
+    /** 等在途写入落盘（teardown / 测试用）。 */
+    async close() {
+        await this.chain.catch(() => { });
+    }
+}
+/**
+ * 读 journal 的尾部（不要求 Journal 实例——读在线程外也能工作，扩展离线也行）。
+ * @param stateDir - journal 所在目录。
+ * @param filter - tabId / 命令子串 / 条数（默认 50，最大 500；取最新）。
+ */
+export async function readJournal(stateDir, filter = {}) {
+    let text;
+    try {
+        text = await readFile(path.join(stateDir, 'journal.jsonl'), 'utf8');
+    }
+    catch {
+        return { total: 0, entries: [] };
+    }
+    if (text.length > JOURNAL_MAX_BYTES)
+        text = text.slice(-JOURNAL_MAX_BYTES);
+    let matched = parseLines(text);
+    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));
+    }
+    const limit = Math.min(500, Math.max(1, Math.trunc(filter.limit ?? 50)));
+    return { total: matched.length, entries: matched.slice(Math.max(0, matched.length - limit)) };
+}

package/llms.txt

@@ -42,7 +42,7 @@ Chrome 浏览器扩展 + DeepSeek Harness 插件，让 AI Agent 通过 CDP 驱
 
 ## 关键文件
 
-- `src/index.ts` - 27 个 `browser_*` 工具注册 + settings 接线的版本兼容分支
+- `src/index.ts` - 28 个 `browser_*` 工具注册 + settings 接线的版本兼容分支
 - `src/policy.ts` - 三张互不相同的表：只读白名单、脚本命令、插件本地破坏性命令（`browser_cleanup` 不经过 `execute()`，必须自己站闸门）
 - `src/server.ts` - WebSocket 服务 + HTTP 面（鉴权、来源校验、状态页）
 - `src/ws.ts` - RFC 6455 帧编解码

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@angelky7/dsh-browser-control",
   "description": "Local WebSocket bridge between dsh and the DSH Browser Control browser extension, with model-facing browser_* tools and a Settings-managed on/off switch",
-  "version": "1.7.4",
+  "version": "1.7.5",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -37,7 +37,7 @@
     "build": "tsc -p tsconfig.json && tsdown",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "check": "npm run typecheck && npm run build && publint",
-    "verify": "node verify/verify_config_patch.mjs && node verify/verify_peers.mjs && node verify/verify_surface.mjs && node verify/verify_tab_groups.mjs && node verify/verify_tabs_close_many.mjs && node verify/verify_cdp_retry.mjs && node verify/verify_snapshot_ax.mjs && node verify/verify_hard_lock.mjs && node verify/verify_policy.mjs && node verify/verify_cookies.mjs && node verify/verify_extension_e2e.mjs && node verify/verify_plugin.mjs legacy && node verify/verify_plugin.mjs conflict && node verify/verify_plugin.mjs new && node verify/verify_http.mjs && node verify/verify_errors.mjs && node verify/verify_hold.mjs && node verify/verify_protocol.mjs && node verify/verify_bundle_http.mjs && node verify/verify_nav_report.mjs && node verify/verify_nav_landing.mjs && node verify/verify_render_contract.mjs && node verify/verify_press_events.mjs && node verify/verify_nav_timeout.mjs && node verify/verify_nav_waituntil.mjs && node verify/verify_archive.mjs && node verify/verify_windows.mjs && node verify/verify_history_nav.mjs && node verify/verify_metrics_throttle.mjs && node verify/verify_drag.mjs && node verify/verify_audit.mjs && node verify/verify_compat_matrix.mjs"
+    "verify": "node verify/verify_config_patch.mjs && node verify/verify_peers.mjs && node verify/verify_surface.mjs && node verify/verify_tab_groups.mjs && node verify/verify_tabs_close_many.mjs && node verify/verify_cdp_retry.mjs && node verify/verify_snapshot_ax.mjs && node verify/verify_hard_lock.mjs && node verify/verify_policy.mjs && node verify/verify_cookies.mjs && node verify/verify_extension_e2e.mjs && node verify/verify_plugin.mjs legacy && node verify/verify_plugin.mjs conflict && node verify/verify_plugin.mjs new && node verify/verify_http.mjs && node verify/verify_errors.mjs && node verify/verify_hold.mjs && node verify/verify_protocol.mjs && node verify/verify_bundle_http.mjs && node verify/verify_nav_report.mjs && node verify/verify_nav_landing.mjs && node verify/verify_render_contract.mjs && node verify/verify_press_events.mjs && node verify/verify_nav_timeout.mjs && node verify/verify_nav_waituntil.mjs && node verify/verify_archive.mjs && node verify/verify_windows.mjs && node verify/verify_history_nav.mjs && node verify/verify_metrics_throttle.mjs && node verify/verify_drag.mjs && node verify/verify_audit.mjs && node verify/verify_journal.mjs && node verify/verify_compat_matrix.mjs"
   },
   "publishConfig": {
     "access": "public",