@angelky7/dsh-browser-control 1.7.3 → 1.7.4

package/README.en.md

@@ -268,10 +268,11 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `browser_emulate` | Switch to a device viewport (mobile / desktop / custom, v1.0.7+); v1.7.1+ adds throttling: `network` slow3g/fast3g/offline/reset + `cpuThrottlingRate` (1–20), the receipt states the applied numbers, `device:"reset"` clears them too |
 | `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_cleanup` | Clean up temp files |
 | `browser_info` | Which browser and extension build is attached (run it first when debugging, v1.0.9+) |
 
-26 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`.
+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`.
 
 ## Architecture
 

package/README.md

@@ -261,11 +261,12 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `browser_emulate` | 切设备视口（移动 / 桌面 / 自定义，v1.0.7+）；v1.7.1 起还能限速：`network` slow3g/fast3g/offline/reset + `cpuThrottlingRate`（1–20），回执写明生效数值，`device:"reset"` 一并还原 |
 | `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_windows` | 窗口控制：清单/开窗/改状态与几何/关整窗/跨窗挪标签（唯一能碰窗口几何的工具，v1.6.0+） |
 | `browser_cleanup` | 清理临时文件 |
 | `browser_info` | 报告实际连上的浏览器与扩展版本（排障先跑它，v1.0.9+） |
 
-共 26 个工具。`browser_wait` / `browser_find` / `browser_dialog` / `browser_info` 在 v1.0.8 及以前是「扩展里已实现、但没注册成工具」，agent 调不到；`browser_network_clear` 则是代码里有、这张表漏了。这些现在由 `verify/verify_surface.mjs` 做三方对账（扩展命令表 ↔ 插件调用 ↔ 文档表 ↔ 构建产物），漂移会直接让 `npm run verify` 失败。
+共 27 个工具。`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

@@ -926,6 +926,92 @@ function policyRefusal(command, flags, params) {
 	if (flags.readOnly && PAGE_MUTATING_COMMANDS.has(command) && !isReadOnlyAction) return `只读模式已开启（readOnly: true）：命令 ${command} 会往页面里插入一层接管浮层（改页面 DOM），已被拒绝，没有向浏览器发出任何操作。浮层是给用户看的提示层，不是安全边界；只读档里连这种「只是提示」的改动也一并拒绝。要开浮层请由用户关掉 readOnly，${CONFIG_HINT}不要原地重试本命令。`;
 	if (flags.readOnly && !READ_ONLY_ALLOWED.has(command) && !isReadOnlyAction) return `只读模式已开启（readOnly: true）：命令 ${command} 会改变页面或浏览器状态，已被拒绝，没有向浏览器发出任何操作。只读模式下可用的工具是读页面与读日志那几类；要放开写操作，${CONFIG_HINT}不要原地重试本命令。`;
 }
+/** 单条参数摘要上限：审计要的是形状，不是全文。 */
+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 = /* @__PURE__ */ new Set(["input", "cookies.set"]);
+function redactValue(value) {
+	return `[redacted:${typeof value === "string" ? [...value].length : 0} chars]`;
+}
+/**
+* 把一次调用的参数压成可审计的摘要：敏感键打码、特定命令的 value 打码、
+* 长表达式截断、整体限长。返回 JSON 文本——审计工具原样把它交给模型。
+*/
+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` 只读。 */
+var AuditLog = class {
+	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 !== void 0) entry.tabId = input.tabId;
+		if (input.code !== void 0) entry.code = input.code;
+		if (input.effectState !== void 0) entry.effectState = input.effectState;
+		if (input.error !== void 0) entry.error = [...input.error].length > AUDIT_ERROR_MAX_CHARS ? `${[...input.error].slice(0, AUDIT_ERROR_MAX_CHARS).join("")}…` : input.error;
+		this.entries.push(entry);
+		if (this.entries.length > 200) this.entries.splice(0, this.entries.length - 200);
+		return entry;
+	}
+	/** 现有条目数（被挤掉的不算）。 */
+	size() {
+		return this.entries.length;
+	}
+	/**
+	* 过滤并取最新的一批。
+	* @param filter - tabId / 命令子串 / sinceSeq / limit；返回按 seq 升序。
+	*/
+	list(filter = {}) {
+		let matched = this.entries;
+		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));
+		}
+		if (filter.sinceSeq !== void 0) {
+			const floor = filter.sinceSeq;
+			matched = matched.filter((e) => e.seq > floor);
+		}
+		const limit = Math.min(200, Math.max(1, Math.trunc(filter.limit ?? 50)));
+		return matched.slice(Math.max(0, matched.length - limit));
+	}
+};
 //#endregion
 //#region lib/types/index.js
 /**
@@ -1054,6 +1140,8 @@ var BridgeController = class {
 	lastError;
 	chain = Promise.resolve();
 	current;
+	/** 操作审计账本（内存环形缓冲，200 条；命令层记录，见 audit.ts 顶部注释）。 */
+	audit = new AuditLog();
 	constructor(log) {
 		this.log = log;
 	}
@@ -1098,6 +1186,15 @@ var BridgeController = class {
 	*/
 	requireExtensionCommand(command, since) {
 		if (this.hasExtensionCommand(command)) return;
+		this.audit.record({
+			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);
 	}
 	/**
@@ -1159,13 +1256,40 @@ var BridgeController = class {
 	* @returns the extension's result payload verbatim.
 	*/
 	async execute(command, params, signal, timeoutMs) {
-		this.policyGate(command, params);
-		const server = this.server;
-		if (server === void 0) throw classify(command, new Error(this.lastError ?? "浏览器控制未启用 —— 在 profile 的 cordis.patch.yml 里给 browser-bridge 配 enabled: true（dsh 0.1.7+ 的宿主也会在设置 → 插件 自动列出本插件开关；0.1.2 及更早的宿主没有这张卡片，只能改配置文件）"));
-		return server.execute(command, params, timeoutMs === void 0 ? { signal } : {
-			signal,
-			timeoutMs
-		});
+		const started = Date.now();
+		const summary = summarizeAuditParams(command, params);
+		const tabId = typeof params.tabId === "number" ? params.tabId : void 0;
+		try {
+			this.policyGate(command, params);
+			const server = this.server;
+			if (server === void 0) 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 === void 0 ? { signal } : {
+				signal,
+				timeoutMs
+			});
+			this.audit.record({
+				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({
+				command,
+				tabId,
+				params: summary,
+				ok: false,
+				code: typeof code === "string" ? code : void 0,
+				effectState: typeof effectState === "string" ? effectState : void 0,
+				error: errorMessage(error),
+				durationMs: Date.now() - started
+			});
+			throw error;
+		}
 	}
 	/**
 	* Refuse a command the local policy forbids, before anything is sent or deleted.
@@ -1190,13 +1314,36 @@ var BridgeController = class {
 	* @returns counts and names of what was removed.
 	*/
 	async cleanup() {
-		this.policyGate("cleanup");
-		const dir = this.shotsDir;
-		if (dir === void 0) throw classify("cleanup", /* @__PURE__ */ new Error("browser-bridge is not configured yet —— 浏览器控制尚未加载配置，无法确定清理目录"));
+		const started = Date.now();
 		try {
-			return await cleanupArtifacts({ shotsDir: dir });
+			this.policyGate("cleanup");
+			const dir = this.shotsDir;
+			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({
+					command: "cleanup",
+					params: "{}",
+					ok: true,
+					durationMs: Date.now() - started
+				});
+				return result;
+			} catch (error) {
+				throw classify("cleanup", error);
+			}
 		} catch (error) {
-			throw classify("cleanup", error);
+			const code = error.code;
+			const effectState = error.effectState;
+			this.audit.record({
+				command: "cleanup",
+				params: "{}",
+				ok: false,
+				code: typeof code === "string" ? code : void 0,
+				effectState: typeof effectState === "string" ? effectState : void 0,
+				error: errorMessage(error),
+				durationMs: Date.now() - started
+			});
+			throw error;
 		}
 	}
 	/** Stop the listener; safe to call repeatedly and during teardown. */
@@ -3147,6 +3294,7 @@ function applyBrowserTools(ctx, controller) {
 		}
 	}));
 	registerDragTool(ctx, controller);
+	registerAuditTool(ctx, controller);
 }
 /** One CDP round-trip over the embedded `cdp` passthrough (extension v1.7.2+). */
 async function cdpCall(ctrl, tabId, method, params, signal) {
@@ -3475,6 +3623,119 @@ 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–200; 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 === void 0 ? "" : ` tab ${e.tabId}`;
+					const outcome = e.ok ? "ok" : `FAIL ${e.code ?? "error"}${e.effectState ? `/${e.effectState}` : ""}`;
+					const err = e.ok || e.error === void 0 ? "" : ` — ${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
+			};
+		}
+	}));
+}
 /** Cordis plugin entry: wire the settings-driven lifecycle plus the model-facing tools. */
 function apply(ctx, config) {
 	const resolved = config;

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.js

@@ -24,6 +24,7 @@ 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";
 /** Navigation wait ceiling (same as browser_wait); the bridge gets this plus BRIDGE_MARGIN_MS. */
 const NAV_MAX_MS = 120_000;
 /**
@@ -116,6 +117,8 @@ class BridgeController {
     lastError;
     chain = Promise.resolve();
     current;
+    /** 操作审计账本（内存环形缓冲，200 条；命令层记录，见 audit.ts 顶部注释）。 */
+    audit = new AuditLog();
     constructor(log) {
         this.log = log;
     }
@@ -161,6 +164,16 @@ class BridgeController {
     requireExtensionCommand(command, since) {
         if (this.hasExtensionCommand(command))
             return;
+        // 预检拒绝也要上账：这是「升级插件后模型发现功能不可用」的最常见现场。
+        this.audit.record({
+            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);
     }
     /**
@@ -221,12 +234,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.audit.record({ 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({
+                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,19 +287,38 @@ 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.audit.record({ 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.audit.record({
+                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. */
@@ -1692,6 +1746,7 @@ function applyBrowserTools(ctx, controller) {
         },
     }));
     registerDragTool(ctx, controller);
+    registerAuditTool(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 +2013,71 @@ 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 };
+        },
+    }));
+}
 /** Cordis plugin entry: wire the settings-driven lifecycle plus the model-facing tools. */
 export function apply(ctx, config) {
     const resolved = config;

package/llms.txt

@@ -42,7 +42,7 @@ Chrome 浏览器扩展 + DeepSeek Harness 插件，让 AI Agent 通过 CDP 驱
 
 ## 关键文件
 
-- `src/index.ts` - 26 个 `browser_*` 工具注册 + settings 接线的版本兼容分支
+- `src/index.ts` - 27 个 `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.3",
+  "version": "1.7.4",
   "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_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_compat_matrix.mjs"
   },
   "publishConfig": {
     "access": "public",