@angelky7/dsh-browser-control 1.4.0 → 1.5.0

package/README.en.md

@@ -64,8 +64,8 @@ In one line: **for "use MY browser" tasks (logged-in Bilibili, Zhihu, admin pane
 
 | File | Purpose |
 |---|---|
-| [DSH-Browser-Control-v1.4.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.4.0/DSH-Browser-Control-v1.4.0.zip) | Chrome extension (unzip and load; navigation waiting is now event-driven — reinstall required) |
-| [dsh-browser-control-plugin-v1.4.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.4.0/dsh-browser-control-plugin-v1.4.0.zip) | dsh plugin (offline fallback; online installs use Option A/B) |
+| [DSH-Browser-Control-v1.5.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.5.0/DSH-Browser-Control-v1.5.0.zip) | Chrome extension (unzip and load; this release adds the archive command — reinstall required) |
+| [dsh-browser-control-plugin-v1.5.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.5.0/dsh-browser-control-plugin-v1.5.0.zip) | dsh plugin (offline fallback; online installs use Option A/B) |
 
 ## Install the Chrome extension (30 seconds)
 
@@ -104,7 +104,7 @@ npm install @angelky7/dsh-browser-control
 
 ```bash
 # Straight from GitHub
-dsh plugin --profile web add "github:angelky7/dsh-browser-control#v1.4.0"
+dsh plugin --profile web add "github:angelky7/dsh-browser-control#v1.5.0"
 
 # Local checkout for debugging (note: the explicit file: prefix is required)
 dsh plugin --profile web add "file:D:\path\to\dsh-browser-control"
@@ -263,11 +263,12 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `browser_network_log` | Captured HTTP requests, listed with method/status/URL (v1.0.7+) |
 | `browser_network_clear` | Clear the network log buffer on its own (v1.0.7+) |
 | `browser_pdf` | Export the current page as PDF (v1.0.7+) |
+| `browser_archive` | Save the whole page as a single-file MHTML (text/images/styles inline; a greppable offline evidence snapshot — embedded scripts do not run, v1.5.0+) |
 | `browser_emulate` | Switch to a device viewport (mobile / desktop / custom, v1.0.7+) |
 | `browser_cleanup` | Clean up temp files |
 | `browser_info` | Which browser and extension build is attached (run it first when debugging, v1.0.9+) |
 
-21 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`.
+23 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

@@ -64,8 +64,8 @@ Chrome 扩展（CDP 驱动）
 
 | 文件 | 说明 |
 |---|---|
-| [DSH-Browser-Control-v1.4.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.4.0/DSH-Browser-Control-v1.4.0.zip) | Chrome 扩展（解压后加载；这一版扩展的导航等待换成事件驱动，**必须重装**） |
-| [dsh-browser-control-plugin-v1.4.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.4.0/dsh-browser-control-plugin-v1.4.0.zip) | dsh 插件（离线兜底，在线装直接用方式 A/B） |
+| [DSH-Browser-Control-v1.5.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.5.0/DSH-Browser-Control-v1.5.0.zip) | Chrome 扩展（解压后加载；这一版扩展新增 archive 存档命令，**必须重装**） |
+| [dsh-browser-control-plugin-v1.5.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.5.0/dsh-browser-control-plugin-v1.5.0.zip) | dsh 插件（离线兜底，在线装直接用方式 A/B） |
 
 ## 安装 Chrome 扩展（30 秒）
 
@@ -104,7 +104,7 @@ npm install @angelky7/dsh-browser-control
 
 ```bash
 # 直接从 GitHub 安装
-dsh plugin --profile web add "github:angelky7/dsh-browser-control#v1.4.0"
+dsh plugin --profile web add "github:angelky7/dsh-browser-control#v1.5.0"
 
 # 本地目录调试（注意：必须显式 file: 前缀）
 dsh plugin --profile web add "file:D:\path\to\dsh-browser-control"
@@ -257,11 +257,12 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `browser_network_log` | 抓取 HTTP 请求/响应并逐条给出方法/状态/URL（v1.0.7+） |
 | `browser_network_clear` | 单独清空网络日志缓冲（v1.0.7+） |
 | `browser_pdf` | 当前页导出 PDF（v1.0.7+） |
+| `browser_archive` | 整页存成单文件 MHTML（正文/图片/样式全内联，可当文本 grep 的离线证据；是快照，内嵌脚本不会跑，v1.5.0+） |
 | `browser_emulate` | 切设备视口（移动 / 桌面 / 自定义，v1.0.7+） |
 | `browser_cleanup` | 清理临时文件 |
 | `browser_info` | 报告实际连上的浏览器与扩展版本（排障先跑它，v1.0.9+） |
 
-共 21 个工具。`browser_wait` / `browser_find` / `browser_dialog` / `browser_info` 在 v1.0.8 及以前是「扩展里已实现、但没注册成工具」，agent 调不到；`browser_network_clear` 则是代码里有、这张表漏了。这四条现在由 `verify/verify_surface.mjs` 做三方对账（扩展命令表 ↔ 插件调用 ↔ 文档表 ↔ 构建产物），漂移会直接让 `npm run verify` 失败。
+共 23 个工具。`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

@@ -1238,6 +1238,30 @@ async function savePdf(controller, payload, requestedPath) {
 		...payload.tabUrl === void 0 ? {} : { url: payload.tabUrl }
 	};
 }
+/** Write one MHTML archive payload to `path` (absolute or under `controller.shotsDir`).
+*  Mirrors savePdf's contract; MHTML is text, so it is written verbatim as UTF-8. */
+async function saveMhtml(controller, payload, requestedPath) {
+	const dir = controller.shotsDir;
+	if (dir === void 0) throw new Error("browser-bridge is not configured yet");
+	let file;
+	if (requestedPath && path.isAbsolute(requestedPath)) {
+		file = requestedPath;
+		await mkdir(path.dirname(file), { recursive: true });
+	} else {
+		await mkdir(dir, { recursive: true });
+		const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+		const random = Math.random().toString(36).slice(2, 6);
+		const name = requestedPath ? path.basename(requestedPath) : `${stamp}-${random}.mhtml`;
+		file = path.join(dir, name);
+	}
+	const buffer = Buffer.from(payload.mhtml, "utf8");
+	await writeFile(file, buffer);
+	return {
+		file,
+		bytes: buffer.length,
+		tabId: payload.tabId
+	};
+}
 /** Register every `browser_*` tool; each is a thin adapter over one extension command. */
 function applyBrowserTools(ctx, controller) {
 	ctx.systemPrompt.section({
@@ -2590,6 +2614,54 @@ function applyBrowserTools(ctx, controller) {
 			return await savePdf(controller, await controller.execute("pdf", params, exec.signal), typeof args.path === "string" ? args.path : void 0);
 		}
 	}));
+	ctx.tools.register(defineTool({
+		name: "browser_archive",
+		description: "Save the whole page as a single-file MHTML archive (text, images and styles inline; no network needed to reopen it). Returns the absolute path. The archive is a snapshot of when it was taken — scripts inside do not run and later page changes are not reflected; read it back with file tools or grep it like text.",
+		parameters: {
+			tabId: {
+				type: "number",
+				description: "Target tab; defaults to the active tab."
+			},
+			path: {
+				type: "string",
+				description: "Absolute path. Omit to save under the configured shotsDir with a timestamped .mhtml name."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					file: {
+						type: "string",
+						required: true
+					},
+					bytes: {
+						type: "number",
+						required: true
+					},
+					tabId: {
+						type: "number",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: `MHTML archive written to ${value.file} (${(value.bytes / 1024).toFixed(1)} KB)`
+			}]
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: `Save page archive${args.path ? " → " + args.path : ""}`,
+			kind: "other"
+		}),
+		async execute(args, exec) {
+			const params = {};
+			if (args.tabId !== void 0) params.tabId = args.tabId;
+			return await saveMhtml(controller, await controller.execute("archive", params, exec.signal), typeof args.path === "string" ? args.path : void 0);
+		}
+	}));
 	ctx.tools.register(defineTool({
 		name: "browser_emulate",
 		description: "Switch the tab into a device viewport (mobile / tablet / desktop) for responsive-UI testing. `device:\"reset\"` restores the user's actual viewport. Custom `width`/`height`/`deviceScaleFactor`/`isMobile`/`hasTouch` override any preset field.",

package/lib/types/index.js

@@ -351,6 +351,28 @@ async function savePdf(controller, payload, requestedPath) {
         ...(payload.tabUrl === undefined ? {} : { url: payload.tabUrl }),
     };
 }
+/** Write one MHTML archive payload to `path` (absolute or under `controller.shotsDir`).
+ *  Mirrors savePdf's contract; MHTML is text, so it is written verbatim as UTF-8. */
+async function saveMhtml(controller, payload, requestedPath) {
+    const dir = controller.shotsDir;
+    if (dir === undefined)
+        throw new Error('browser-bridge is not configured yet');
+    let file;
+    if (requestedPath && path.isAbsolute(requestedPath)) {
+        file = requestedPath;
+        await mkdir(path.dirname(file), { recursive: true });
+    }
+    else {
+        await mkdir(dir, { recursive: true });
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const random = Math.random().toString(36).slice(2, 6);
+        const name = requestedPath ? path.basename(requestedPath) : `${stamp}-${random}.mhtml`;
+        file = path.join(dir, name);
+    }
+    const buffer = Buffer.from(payload.mhtml, 'utf8');
+    await writeFile(file, buffer);
+    return { file, bytes: buffer.length, tabId: payload.tabId };
+}
 /** Register every `browser_*` tool; each is a thin adapter over one extension command. */
 function applyBrowserTools(ctx, controller) {
     ctx.systemPrompt.section({
@@ -1251,6 +1273,37 @@ function applyBrowserTools(ctx, controller) {
             return await savePdf(controller, payload, typeof args.path === 'string' ? args.path : undefined);
         },
     }));
+    ctx.tools.register(defineTool({
+        name: 'browser_archive',
+        description: 'Save the whole page as a single-file MHTML archive (text, images and styles inline; no network needed to reopen it). Returns the absolute path. The archive is a snapshot of when it was taken — scripts inside do not run and later page changes are not reflected; read it back with file tools or grep it like text.',
+        parameters: {
+            tabId: { type: 'number', description: 'Target tab; defaults to the active tab.' },
+            path: { type: 'string', description: 'Absolute path. Omit to save under the configured shotsDir with a timestamped .mhtml name.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    file: { type: 'string', required: true },
+                    bytes: { type: 'number', required: true },
+                    tabId: { type: 'number', required: true },
+                },
+            },
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: `MHTML archive written to ${value.file} (${(value.bytes / 1024).toFixed(1)} KB)`,
+                }],
+        },
+        presentCall: args => ({ card: 'generic', title: `Save page archive${args.path ? ' → ' + args.path : ''}`, kind: 'other' }),
+        async execute(args, exec) {
+            const params = {};
+            if (args.tabId !== undefined)
+                params.tabId = args.tabId;
+            const payload = await controller.execute('archive', params, exec.signal);
+            return await saveMhtml(controller, payload, typeof args.path === 'string' ? args.path : undefined);
+        },
+    }));
     ctx.tools.register(defineTool({
         name: 'browser_emulate',
         description: 'Switch the tab into a device viewport (mobile / tablet / desktop) for responsive-UI testing. `device:"reset"` restores the user\'s actual viewport. Custom `width`/`height`/`deviceScaleFactor`/`isMobile`/`hasTouch` override any preset field.',

package/llms.txt

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