@angelky7/dsh-browser-control 1.7.0 → 1.7.2

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.7.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.0/DSH-Browser-Control-v1.7.0.zip) | Chrome extension (unzip and load; this release adds the history navigation commands — reinstall required) |
-| [dsh-browser-control-plugin-v1.7.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.0/dsh-browser-control-plugin-v1.7.0.zip) | dsh plugin (offline fallback; online installs use Option A/B) |
+| [DSH-Browser-Control-v1.7.2.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.2/DSH-Browser-Control-v1.7.2.zip) | Chrome extension (unzip and load; this release adds the cdp channel and capabilities handshake — **reinstall required, and the last one a feature update will ever ask for**: CDP-level features now ship plugin-side) |
+| [dsh-browser-control-plugin-v1.7.2.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.2/dsh-browser-control-plugin-v1.7.2.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.7.0"
+dsh plugin --profile web add "github:angelky7/dsh-browser-control#v1.7.2"
 
 # Local checkout for debugging (note: the explicit file: prefix is required)
 dsh plugin --profile web add "file:D:\path\to\dsh-browser-control"
@@ -265,11 +265,12 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `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_windows` | Window control: list / open / update state & geometry / close a whole window / move tabs across windows (the only tool that may touch window geometry, v1.6.0+) |
-| `browser_emulate` | Switch to a device viewport (mobile / desktop / custom, v1.0.7+) |
+| `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_cleanup` | Clean up temp files |
 | `browser_info` | Which browser and extension build is attached (run it first when debugging, v1.0.9+) |
 
-24 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`.
+25 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
 
@@ -287,6 +288,7 @@ Chrome browser
 - Persistent debugger attachment — banner stays visible during control
 - Listens on 127.0.0.1 only; the command surface (WebSocket and HTTP) shares one token, and no cross-origin access is granted
 - The wire protocol has its own version, bumped only when the frame contract changes; a mismatch is named on the status page
+- **Plugin upgrades never regress old extensions** (iron rule: plugin x + extension x-n ≥ plugin x-n + extension x-n): from v1.7.2 the hello frame carries capabilities for an exact handshake, old extensions fall back to the version map, and a missing command is refused pre-flight with an actionable reinstall pointer instead of a raw unknown command — CDP-level features now ship plugin-side
 
 ## Verified
 
@@ -300,6 +302,7 @@ Chrome browser
 | `verify_extension_e2e` harness: real bridge + real extension code + real WebSocket end to end (frame contract, command reachability, error classification) | ✅ 2026-10-11 — only `chrome.*` is faked; visuals and real CDP behaviour still need a live browser |
 | `verify_cdp_retry` harness: session recovery after Chrome steals the attach, replay must not re-run side effects, bounded retries (6 scenarios) | ✅ 2026-10-11, real `background.js` against a stateful fake `chrome.debugger`; cross-checked on a merge-preview build |
 | `verify_render_contract` harness: every tool's real return value goes through the host's own output validator **and** its own `render`, asserting the model-facing text actually contains the data the call asked for | ✅ 2026-10-12, real bridge + fake extension + host `validateJsonSchemaValue`; this layer had **zero coverage** before, which is how two defect classes survived 12 / 5 released versions |
+| `verify_compat_matrix` harness: materializes **real historical extension code from git tags** (v1.2.0–v1.7.1) and runs 27 probes per surface against the current plugin, cell-by-cell asserting “≥ the matched pair from that era”; newer tools must fail with the actionable extension-outdated pointer, never a raw unknown command; append-only command surface (extension upgrades are pure gains for old plugins too) | ✅ 2026-11-04, 5 surfaces × 150 checks; exercises the version-map fallback path real old hellos take |
 | **Real host × real browser**: local dsh `0.2.0-rc.2` mounted this plugin from an isolated `DSH_HOME`, the user's actual Chrome attached to the bridge, and 9 read-only tools ran through the real code path | ✅ 2026-10-12, Chrome 153 + extension 1.0.10: `browser_read` returned 1,341 chars of real page text, `browser_snapshot` returned 14 ref-bearing lines, zero output-schema violations; **this is also the run that exposed an older extension silently ignoring `mode:"ax"`** (local extension was 1.0.10, predating the 1.0.11 AX snapshot) — the plugin now reports `axFallback` explicitly |
 | `tsc --noEmit` + `publint` | ✅ 2026-10-10 |
 

package/README.md

@@ -64,8 +64,8 @@ Chrome 扩展（CDP 驱动）
 
 | 文件 | 说明 |
 |---|---|
-| [DSH-Browser-Control-v1.7.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.0/DSH-Browser-Control-v1.7.0.zip) | Chrome 扩展（解压后加载；这一版扩展新增 tabs.back/forward 历史导航命令，**必须重装**） |
-| [dsh-browser-control-plugin-v1.7.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.0/dsh-browser-control-plugin-v1.7.0.zip) | dsh 插件（离线兜底，在线装直接用方式 A/B） |
+| [DSH-Browser-Control-v1.7.2.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.2/DSH-Browser-Control-v1.7.2.zip) | Chrome 扩展（解压后加载；这一版新增 cdp 通道与 capabilities 握手，**必须重装——也是最后一次因功能更新而重装**，此后 CDP 层新能力只更 dsh 插件） |
+| [dsh-browser-control-plugin-v1.7.2.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.2/dsh-browser-control-plugin-v1.7.2.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.7.0"
+dsh plugin --profile web add "github:angelky7/dsh-browser-control#v1.7.2"
 
 # 本地目录调试（注意：必须显式 file: 前缀）
 dsh plugin --profile web add "file:D:\path\to\dsh-browser-control"
@@ -258,12 +258,13 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `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_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_windows` | 窗口控制：清单/开窗/改状态与几何/关整窗/跨窗挪标签（唯一能碰窗口几何的工具，v1.6.0+） |
 | `browser_cleanup` | 清理临时文件 |
 | `browser_info` | 报告实际连上的浏览器与扩展版本（排障先跑它，v1.0.9+） |
 
-共 24 个工具。`browser_wait` / `browser_find` / `browser_dialog` / `browser_info` 在 v1.0.8 及以前是「扩展里已实现、但没注册成工具」，agent 调不到；`browser_network_clear` 则是代码里有、这张表漏了。这些现在由 `verify/verify_surface.mjs` 做三方对账（扩展命令表 ↔ 插件调用 ↔ 文档表 ↔ 构建产物），漂移会直接让 `npm run verify` 失败。
+共 25 个工具。`browser_wait` / `browser_find` / `browser_dialog` / `browser_info` 在 v1.0.8 及以前是「扩展里已实现、但没注册成工具」，agent 调不到；`browser_network_clear` 则是代码里有、这张表漏了。这些现在由 `verify/verify_surface.mjs` 做三方对账（扩展命令表 ↔ 插件调用 ↔ 文档表 ↔ 构建产物），漂移会直接让 `npm run verify` 失败。
 
 ## 架构
 
@@ -281,6 +282,7 @@ Chrome 浏览器
 - 持久 debugger 附着——控制期间横幅始终显示
 - 仅监听 127.0.0.1；命令面（WS 与 HTTP）共用同一个 Token，跨源一律不放行
 - 协议版本独立于版本号：帧契约变了才升，不匹配时状态页直接写出该升级哪一侧
+- **插件升级对旧扩展零倒退**（铁律：插件 x + 扩展 x-n ≥ 插件 x-n + 扩展 x-n）：v1.7.2 起 hello 带 capabilities 精确握手，老扩展走版本映射兜底；缺命令的动作在发送前拦下，给可执行的重装指引而不是裸 unknown command——CDP 层新能力此后只更插件
 
 ## 已验证
 
@@ -294,6 +296,7 @@ Chrome 浏览器
 | 实测台 `verify_extension_e2e`：真桥 + 真扩展代码 + 真 WebSocket 端到端（帧契约、命令可达、错误分类） | ✅ 2026-10-11，只有 `chrome.*` 是假的；视觉与真实 CDP 行为仍需实机确认 |
 | 实测台 `verify_cdp_retry`：CDP 会话被抢走后的恢复 / 重放不许把副作用做两遍 / 重试有界（6 场景） | ✅ 2026-10-11，真实 `background.js` + 有状态假 `chrome.debugger`；另用合并预览文件交叉验证过 |
 | 实测台 `verify_render_contract`：每条工具的真实返回值同时喂给宿主的输出校验器与它自己的 `render`，断言「模型可见文本里有这次调用真正要的数据」 | ✅ 2026-10-12，真桥 + 假扩展 + 宿主 `validateJsonSchemaValue`；这一层此前**零覆盖**，所以两类缺陷活了 12 / 5 个版本 |
+| 实测台 `verify_compat_matrix`：兼容矩阵——从 git 标签物化**真实历史扩展代码**（v1.2.0–v1.7.1），当前插件对每个面跑 27 个探针逐格验收「≥ 当年组合」；新工具报带重装指引的 extension-outdated、绝不许 unknown command 冒充；命令面 append-only（扩展升级对旧插件也纯增益） | ✅ 2026-11-04，5 面 × 150 项；老 hello 无 capabilities ⇒ 版本映射兜底路径的实测 |
 | **真实宿主 × 真实浏览器**：本机 dsh `0.2.0-rc.2` 用隔离 `DSH_HOME` 挂载本插件，用户的真实 Chrome 连上桥，9 条只读工具全部走真实代码路径 | ✅ 2026-10-12，Chrome 153 + 扩展 1.0.10：`browser_read` 交出 1341 字符真实正文、`browser_snapshot` 交出 14 条带 ref 的清单、输出 schema 零违规；**也正是这一跑发现了旧扩展会静默忽略 `mode:"ax"`**（本机扩展是 1.0.10，早于 AX 快照的 1.0.11）——已改成插件侧显式回报 `axFallback` |
 | `tsc --noEmit` + `publint` | ✅ 2026-10-10 |
 

package/lib/index.js

@@ -119,6 +119,7 @@ const WRITE_COMMANDS = /* @__PURE__ */ new Set([
 	"dialog",
 	"tabs.back",
 	"tabs.forward",
+	"cdp",
 	"cleanup",
 	"hold",
 	"windows.open"
@@ -663,6 +664,7 @@ Sec-WebSocket-Accept: ${accept}\r\n\r
 		}
 		if (msg.type === "hello") {
 			const declared = typeof msg.protocol === "number" ? msg.protocol : 0;
+			const capabilities = Array.isArray(msg.capabilities) ? msg.capabilities.filter((c) => typeof c === "string") : void 0;
 			this.hello = {
 				client: typeof msg.client === "string" ? msg.client : "unknown",
 				version: typeof msg.version === "string" ? msg.version : "unknown",
@@ -671,9 +673,10 @@ Sec-WebSocket-Accept: ${accept}\r\n\r
 					name: "unknown",
 					version: "unknown",
 					ua: ""
-				}
+				},
+				...capabilities !== void 0 ? { capabilities } : {}
 			};
-			this.log(`hello: client=${this.hello.client} v${this.hello.version} protocol=v${declared || "?"} browser=${this.hello.browser.name} ${this.hello.browser.version}`);
+			this.log(`hello: client=${this.hello.client} v${this.hello.version} protocol=v${declared || "?"} browser=${this.hello.browser.name} ${this.hello.browser.version}${capabilities ? ` capabilities=${capabilities.length}` : ""}`);
 			const note = this.protocolNote;
 			if (note !== null) this.log(`protocol mismatch: ${note}`);
 			return;
@@ -878,7 +881,8 @@ const READ_ONLY_ALLOWED = /* @__PURE__ */ new Set([
 	"console.log",
 	"network.log",
 	"windows.list",
-	"cookies.get"
+	"cookies.get",
+	"metrics"
 ]);
 /**
 * 会执行**任意页面脚本**的扩展命令。这条与只读档分开管，因为用户可能想「可以读、
@@ -983,6 +987,62 @@ const SNAPSHOT_REF_SELECTOR_PATTERN = /^e\d+$/;
 *  with `offset`, so no single call can put a whole site into the transcript. */
 const READ_WINDOW_MAX_CHARS = 2e4;
 /**
+* Extension command surface, as deltas over the pre-1.5 baseline. Used when a
+* connected extension predates the capability handshake (no `capabilities` in
+* its hello frame): the plugin maps its reported version to the commands it
+* must have. Anything not listed here exists since the baseline and is assumed
+* present; a version newer than every entry is assumed to have everything
+* (forward compatible — an extension never removes commands).
+*/
+const EXTENSION_COMMANDS_BY_VERSION = [
+	{
+		since: "1.5.0",
+		commands: ["archive"]
+	},
+	{
+		since: "1.6.0",
+		commands: [
+			"windows.list",
+			"windows.open",
+			"windows.update",
+			"windows.close",
+			"windows.moveTab"
+		]
+	},
+	{
+		since: "1.7.0",
+		commands: ["tabs.back", "tabs.forward"]
+	},
+	{
+		since: "1.7.1",
+		commands: ["metrics"]
+	},
+	{
+		since: "1.7.2",
+		commands: ["cdp"]
+	}
+];
+/** Compare two `x.y.z` version strings numerically; unparseable input sorts lowest. */
+function compareVersions(a, b) {
+	const parse = (v) => (/^(\d+)\.(\d+)\.(\d+)/.exec(v.trim()) ?? []).slice(1).map(Number);
+	const [pa, pb] = [parse(a), parse(b)];
+	if (pa.length === 0 || pb.length === 0) return pa.length === pb.length ? 0 : pa.length === 0 ? -1 : 1;
+	for (let i = 0; i < 3; i++) if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) - (pb[i] ?? 0);
+	return 0;
+}
+/**
+* The plugin updated, the extension did not: the invariant is that this combo is
+* never WORSE than the matched pair from the extension's era — existing tools
+* behave identically, and tools that need commands the old extension lacks fail
+* with an actionable upgrade pointer instead of a raw "unknown command".
+*/
+function extensionOutdatedError(have, command, since) {
+	const message = "extension-outdated: the connected browser extension" + (have === void 0 ? "" : ` (v${have})`) + ` does not have the "${command}" command this action needs (added in extension v${since}). One-time fix: download DSH-Browser-Control.zip from https://github.com/angelky7/dsh-browser-control/releases/latest, unzip, then chrome://extensions → Developer mode → replace the loaded folder (remove the old one first). That update makes the extension compatible with all future plugin updates — CDP-level features ship plugin-side from v1.7.2 on.`;
+	const error = new Error(message);
+	error.code = "extension_outdated";
+	return error;
+}
+/**
 * Owns zero or one live {@link BridgeServer} and restarts it whenever the
 * resolved settings change. Reconciles serialize through a promise chain so a
 * burst of settings commits cannot interleave stop/start pairs.
@@ -1001,6 +1061,34 @@ var BridgeController = class {
 	get shotsDir() {
 		return this.current === void 0 ? void 0 : path.resolve(this.current.shotsDir);
 	}
+	/** Version the connected extension reported in its hello frame, if any. */
+	extensionVersion() {
+		return this.server?.status.hello?.version;
+	}
+	/**
+	* Whether the connected extension implements `command`. Exact when the hello
+	* carries a capabilities list (v1.7.2+); otherwise derived from the reported
+	* version via the surface-delta map. No connection ⇒ true: the not-enabled
+	* error from execute is the right failure there, not a capability complaint.
+	*/
+	hasExtensionCommand(command) {
+		const hello = this.server?.status.hello;
+		if (hello?.capabilities !== void 0) return hello.capabilities.includes(command);
+		const version = hello?.version;
+		if (version === void 0 || version === "unknown") return true;
+		const entry = EXTENSION_COMMANDS_BY_VERSION.find((e) => e.commands.includes(command));
+		if (entry === void 0) return true;
+		return compareVersions(version, entry.since) >= 0;
+	}
+	/**
+	* Pre-flight capability gate: throw the actionable upgrade error before the
+	* command is sent, so an old extension answers with a what-to-do, never with
+	* a bare "unknown command" the model cannot act on.
+	*/
+	requireExtensionCommand(command, since) {
+		if (this.hasExtensionCommand(command)) return;
+		throw extensionOutdatedError(this.extensionVersion(), command, since);
+	}
 	/**
 	* Converge the live server onto `config`. With `throwOnError`, an initial
 	* start failure rejects (fail-loud activation); later changes record the
@@ -2146,7 +2234,11 @@ function applyBrowserTools(ctx, controller) {
 					let budgetMs = NAV_TIERS[waitUntil];
 					if (typeof args.timeoutMs === "number" && Number.isFinite(args.timeoutMs)) budgetMs = Math.min(NAV_MAX_MS, Math.max(100, Math.trunc(args.timeoutMs)));
 					params.timeoutMs = budgetMs;
-					if (args.action === "back") return await controller.execute("tabs.back", params, exec.signal, budgetMs + BRIDGE_MARGIN_MS);
+					if (args.action === "back") {
+						controller.requireExtensionCommand("tabs.back", "1.7.0");
+						return await controller.execute("tabs.back", params, exec.signal, budgetMs + BRIDGE_MARGIN_MS);
+					}
+					controller.requireExtensionCommand("tabs.forward", "1.7.0");
 					return await controller.execute("tabs.forward", params, exec.signal, budgetMs + BRIDGE_MARGIN_MS);
 				}
 				case "group": return await controller.execute("tabs.group", { tabId: requireTabId(args, "group") }, exec.signal);
@@ -2243,7 +2335,9 @@ function applyBrowserTools(ctx, controller) {
 		}),
 		async execute(args, exec) {
 			switch (args.action) {
-				case "list": return await controller.execute("windows.list", {}, exec.signal);
+				case "list":
+					controller.requireExtensionCommand("windows.list", "1.6.0");
+					return await controller.execute("windows.list", {}, exec.signal);
 				case "open": {
 					const params = {};
 					if (args.url !== void 0) params.url = args.url;
@@ -2256,6 +2350,7 @@ function applyBrowserTools(ctx, controller) {
 						"height"
 					]) if (typeof args[k] === "number") params[k] = args[k];
 					if (args.focused !== void 0) params.focused = args.focused;
+					controller.requireExtensionCommand("windows.open", "1.6.0");
 					return await controller.execute("windows.open", params, exec.signal);
 				}
 				case "update": {
@@ -2270,15 +2365,19 @@ function applyBrowserTools(ctx, controller) {
 					if (args.focused !== void 0) params.focused = args.focused;
 					if (args.alwaysOnTop !== void 0) params.alwaysOnTop = args.alwaysOnTop;
 					if (args.drawAttention === true) params.drawAttention = true;
+					controller.requireExtensionCommand("windows.update", "1.6.0");
 					return await controller.execute("windows.update", params, exec.signal);
 				}
-				case "close": return await controller.execute("windows.close", { windowId: requireWindowId(args, "close") }, exec.signal);
+				case "close":
+					controller.requireExtensionCommand("windows.close", "1.6.0");
+					return await controller.execute("windows.close", { windowId: requireWindowId(args, "close") }, exec.signal);
 				case "moveTab": {
 					if (args.tabId === void 0 && args.tabIds === void 0) throw new Error("moveTab requires tabId or tabIds");
 					const params = { windowId: requireWindowId(args, "moveTab") };
 					if (args.tabId !== void 0) params.tabId = args.tabId;
 					if (args.tabIds !== void 0) params.tabIds = args.tabIds;
 					if (args.index !== void 0) params.index = args.index;
+					controller.requireExtensionCommand("windows.moveTab", "1.6.0");
 					return await controller.execute("windows.moveTab", params, exec.signal);
 				}
 				default: throw new Error(`unknown windows action: ${String(args.action)} (use list|open|update|close|moveTab)`);
@@ -2848,12 +2947,13 @@ function applyBrowserTools(ctx, controller) {
 		async execute(args, exec) {
 			const params = {};
 			if (args.tabId !== void 0) params.tabId = args.tabId;
+			controller.requireExtensionCommand("archive", "1.5.0");
 			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.",
+		description: "Switch the tab into a device viewport (mobile / tablet / desktop) for responsive-UI testing, and throttle the network or CPU to test slow conditions. `device:\"reset\"` restores the user's actual viewport and clears all throttling. `network` presets (this tool's own numbers): slow3g = 400ms RTT + ~50KB/s both ways, fast3g = 150ms + ~200KB/s down / ~94KB/s up, offline, reset to clear. `cpuThrottlingRate` multiplies CPU cost (1 = off, up to 20). Throttling lives in the debugger session — it is gone when the extension detaches, and device:\"reset\" clears it too. Custom `width`/`height`/`deviceScaleFactor`/`isMobile`/`hasTouch` override any preset field.",
 		parameters: {
 			tabId: {
 				type: "number",
@@ -2863,6 +2963,14 @@ function applyBrowserTools(ctx, controller) {
 				type: "string",
 				description: "Preset: desktop | mobile-iphone-13 | mobile-pixel-7 | tablet-ipad | reset. Or pass custom width/height below."
 			},
+			network: {
+				type: "string",
+				description: "slow3g | fast3g | offline | reset. The receipt reports the applied latency/throughput in bytes per second."
+			},
+			cpuThrottlingRate: {
+				type: "number",
+				description: "CPU slowdown multiplier: 1 = none (default), 4 = mid-range phone, up to 20."
+			},
 			width: {
 				type: "number",
 				description: "Custom viewport width in CSS px."
@@ -2903,30 +3011,39 @@ function applyBrowserTools(ctx, controller) {
 					deviceScaleFactor: { type: "number" },
 					isMobile: { type: "boolean" },
 					hasTouch: { type: "boolean" },
-					userAgent: { type: "string" }
+					userAgent: { type: "string" },
+					network: { type: "string" },
+					latency: { type: "number" },
+					downloadThroughput: { type: "number" },
+					uploadThroughput: { type: "number" },
+					cpuThrottlingRate: { type: "number" }
 				}
 			},
 			render: (_args, value) => {
 				if (value.reset) return [{
 					type: "text",
-					text: `Tab ${value.tabId}: emulation reset to default`
+					text: `Tab ${value.tabId}: emulation reset to default (network unthrottled, CPU rate 1)`
 				}];
 				const ua = value.userAgent === void 0 ? "" : ` UA="${flattenOneLine(value.userAgent, 80)}"`;
+				const net = value.network === void 0 ? "" : ` network=${value.network}(${value.latency}ms↓${value.downloadThroughput}B/s↑${value.uploadThroughput}B/s)`;
+				const cpu = value.cpuThrottlingRate === void 0 ? "" : ` cpu×${value.cpuThrottlingRate}`;
 				return [{
 					type: "text",
-					text: `Tab ${value.tabId}: ${value.width || "?"}×${value.height || "?"} DPR=${value.deviceScaleFactor ?? "?"} mobile=${value.isMobile ?? false} touch=${value.hasTouch ?? false}${ua}`
+					text: `Tab ${value.tabId}: ${value.width || "?"}×${value.height || "?"} DPR=${value.deviceScaleFactor ?? "?"} mobile=${value.isMobile ?? false} touch=${value.hasTouch ?? false}${ua}${net}${cpu}`
 				}];
 			}
 		},
 		presentCall: (args) => ({
 			card: "generic",
-			title: `Emulate${args.device ? " " + args.device : " device"}`,
+			title: `Emulate${args.device ? " " + args.device : ""}${args.network ? " " + args.network : ""}${args.cpuThrottlingRate ? " cpu×" + args.cpuThrottlingRate : ""}`,
 			kind: "other"
 		}),
 		async execute(args, exec) {
 			const params = {};
 			if (args.tabId !== void 0) params.tabId = args.tabId;
 			if (typeof args.device === "string") params.device = args.device;
+			if (typeof args.network === "string") params.network = args.network;
+			if (typeof args.cpuThrottlingRate === "number") params.cpuThrottlingRate = args.cpuThrottlingRate;
 			if (typeof args.width === "number") params.width = args.width;
 			if (typeof args.height === "number") params.height = args.height;
 			if (typeof args.deviceScaleFactor === "number") params.deviceScaleFactor = args.deviceScaleFactor;
@@ -2942,10 +3059,82 @@ function applyBrowserTools(ctx, controller) {
 				...typeof raw.deviceScaleFactor === "number" ? { deviceScaleFactor: raw.deviceScaleFactor } : {},
 				...typeof raw.isMobile === "boolean" ? { isMobile: raw.isMobile } : {},
 				...typeof raw.hasTouch === "boolean" ? { hasTouch: raw.hasTouch } : {},
-				...typeof raw.userAgent === "string" && raw.userAgent.length > 0 ? { userAgent: raw.userAgent } : {}
+				...typeof raw.userAgent === "string" && raw.userAgent.length > 0 ? { userAgent: raw.userAgent } : {},
+				...typeof raw.network === "string" ? { network: raw.network } : {},
+				...typeof raw.latency === "number" ? { latency: raw.latency } : {},
+				...typeof raw.downloadThroughput === "number" ? { downloadThroughput: raw.downloadThroughput } : {},
+				...typeof raw.uploadThroughput === "number" ? { uploadThroughput: raw.uploadThroughput } : {},
+				...typeof raw.cpuThrottlingRate === "number" ? { cpuThrottlingRate: raw.cpuThrottlingRate } : {}
 			};
 		}
 	}));
+	ctx.tools.register(defineTool({
+		name: "browser_metrics",
+		description: "Read the tab's performance counters (Performance.getMetrics): DOM node count, JS heap usage, layout/style recalc counts, script/task durations. Use it to back \"this page is heavy\" with numbers, before and after an action. Read-only.",
+		parameters: { tabId: {
+			type: "number",
+			description: "Target tab; defaults to the active tab."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					tabId: {
+						type: "number",
+						required: true
+					},
+					metrics: {
+						type: "object",
+						required: true,
+						additionalProperties: false,
+						properties: {
+							Timestamp: { type: "number" },
+							Documents: { type: "number" },
+							Frames: { type: "number" },
+							JSEventListeners: { type: "number" },
+							Nodes: { type: "number" },
+							LayoutCount: { type: "number" },
+							RecalcStyleCount: { type: "number" },
+							LayoutDuration: { type: "number" },
+							RecalcStyleDuration: { type: "number" },
+							ScriptDuration: { type: "number" },
+							TaskDuration: { type: "number" },
+							JSHeapUsedSize: { type: "number" },
+							JSHeapTotalSize: { type: "number" }
+						}
+					}
+				}
+			},
+			render: (_args, value) => {
+				const m = value.metrics ?? {};
+				const parts = [];
+				if (m.Nodes !== void 0) parts.push(`nodes=${m.Nodes}`);
+				if (m.JSHeapUsedSize !== void 0) {
+					const total = m.JSHeapTotalSize !== void 0 ? `/${(m.JSHeapTotalSize / 1048576).toFixed(1)}MB` : "";
+					parts.push(`heap=${(m.JSHeapUsedSize / 1048576).toFixed(1)}${total}`);
+				}
+				if (m.LayoutCount !== void 0) parts.push(`layouts=${m.LayoutCount}`);
+				if (m.ScriptDuration !== void 0) parts.push(`script=${Number(m.ScriptDuration).toFixed(2)}s`);
+				if (m.TaskDuration !== void 0) parts.push(`tasks=${Number(m.TaskDuration).toFixed(2)}s`);
+				return [{
+					type: "text",
+					text: `Tab ${value.tabId}: ${parts.join(" ") || JSON.stringify(value.metrics)}`
+				}];
+			}
+		},
+		presentCall: () => ({
+			card: "generic",
+			title: "Browser metrics",
+			kind: "other"
+		}),
+		async execute(args, exec) {
+			const params = {};
+			if (args.tabId !== void 0) params.tabId = args.tabId;
+			controller.requireExtensionCommand("metrics", "1.7.1");
+			return await controller.execute("metrics", params, exec.signal);
+		}
+	}));
 }
 /** Cordis plugin entry: wire the settings-driven lifecycle plus the model-facing tools. */
 function apply(ctx, config) {

package/lib/types/errors.js

@@ -44,6 +44,9 @@ const WRITE_COMMANDS = new Set([
     // 历史导航与 nav 同族：超时/掉线后重试可能**多跳一条**历史（第一次 back 其实
     // 已经落了地），报 unknown 才诚实。
     'tabs.back', 'tabs.forward',
+    // CDP 透传（v1.7.2）：原始能力等价于「页面内任意 JS」，按写命令分类，
+    // 只读档拒、接管中止态拦。它是内部原语，不注册成模型工具。
+    'cdp',
     // 这条不是扩展命令，而是插件本地命令 `browser_cleanup`：它逐条 rm，中途失败
     // （Windows 上被占用的截图会 EPERM）时前面的文件已经没了，报 not_started
     // 就是告诉模型「什么都没发生，重试安全」，而那正好是假的。

package/lib/types/index.js

@@ -61,6 +61,49 @@ const SNAPSHOT_REF_SELECTOR_PATTERN = /^e\d+$/;
 /** One `browser_read` window, in characters of page text. Longer pages are paged
  *  with `offset`, so no single call can put a whole site into the transcript. */
 const READ_WINDOW_MAX_CHARS = 20_000;
+/**
+ * Extension command surface, as deltas over the pre-1.5 baseline. Used when a
+ * connected extension predates the capability handshake (no `capabilities` in
+ * its hello frame): the plugin maps its reported version to the commands it
+ * must have. Anything not listed here exists since the baseline and is assumed
+ * present; a version newer than every entry is assumed to have everything
+ * (forward compatible — an extension never removes commands).
+ */
+const EXTENSION_COMMANDS_BY_VERSION = [
+    { since: '1.5.0', commands: ['archive'] },
+    { since: '1.6.0', commands: ['windows.list', 'windows.open', 'windows.update', 'windows.close', 'windows.moveTab'] },
+    { since: '1.7.0', commands: ['tabs.back', 'tabs.forward'] },
+    { since: '1.7.1', commands: ['metrics'] },
+    { since: '1.7.2', commands: ['cdp'] },
+];
+/** Compare two `x.y.z` version strings numerically; unparseable input sorts lowest. */
+function compareVersions(a, b) {
+    const parse = (v) => (/^(\d+)\.(\d+)\.(\d+)/.exec(v.trim()) ?? []).slice(1).map(Number);
+    const [pa, pb] = [parse(a), parse(b)];
+    if (pa.length === 0 || pb.length === 0)
+        return pa.length === pb.length ? 0 : (pa.length === 0 ? -1 : 1);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] ?? 0) !== (pb[i] ?? 0))
+            return (pa[i] ?? 0) - (pb[i] ?? 0);
+    }
+    return 0;
+}
+/**
+ * The plugin updated, the extension did not: the invariant is that this combo is
+ * never WORSE than the matched pair from the extension's era — existing tools
+ * behave identically, and tools that need commands the old extension lacks fail
+ * with an actionable upgrade pointer instead of a raw "unknown command".
+ */
+function extensionOutdatedError(have, command, since) {
+    const message = 'extension-outdated: the connected browser extension'
+        + (have === undefined ? '' : ` (v${have})`)
+        + ` does not have the "${command}" command this action needs (added in extension v${since}).`
+        + ' One-time fix: download DSH-Browser-Control.zip from https://github.com/angelky7/dsh-browser-control/releases/latest, unzip, then chrome://extensions → Developer mode → replace the loaded folder (remove the old one first).'
+        + ' That update makes the extension compatible with all future plugin updates — CDP-level features ship plugin-side from v1.7.2 on.';
+    const error = new Error(message);
+    error.code = 'extension_outdated';
+    return error;
+}
 /**
  * Owns zero or one live {@link BridgeServer} and restarts it whenever the
  * resolved settings change. Reconciles serialize through a promise chain so a
@@ -80,6 +123,38 @@ class BridgeController {
     get shotsDir() {
         return this.current === undefined ? undefined : path.resolve(this.current.shotsDir);
     }
+    /** Version the connected extension reported in its hello frame, if any. */
+    extensionVersion() {
+        return this.server?.status.hello?.version;
+    }
+    /**
+     * Whether the connected extension implements `command`. Exact when the hello
+     * carries a capabilities list (v1.7.2+); otherwise derived from the reported
+     * version via the surface-delta map. No connection ⇒ true: the not-enabled
+     * error from execute is the right failure there, not a capability complaint.
+     */
+    hasExtensionCommand(command) {
+        const hello = this.server?.status.hello;
+        if (hello?.capabilities !== undefined)
+            return hello.capabilities.includes(command);
+        const version = hello?.version;
+        if (version === undefined || version === 'unknown')
+            return true;
+        const entry = EXTENSION_COMMANDS_BY_VERSION.find((e) => e.commands.includes(command));
+        if (entry === undefined)
+            return true;
+        return compareVersions(version, entry.since) >= 0;
+    }
+    /**
+     * Pre-flight capability gate: throw the actionable upgrade error before the
+     * command is sent, so an old extension answers with a what-to-do, never with
+     * a bare "unknown command" the model cannot act on.
+     */
+    requireExtensionCommand(command, since) {
+        if (this.hasExtensionCommand(command))
+            return;
+        throw extensionOutdatedError(this.extensionVersion(), command, since);
+    }
     /**
      * Converge the live server onto `config`. With `throwOnError`, an initial
      * start failure rejects (fail-loud activation); later changes record the
@@ -964,8 +1039,10 @@ function applyBrowserTools(ctx, controller) {
                     }
                     params.timeoutMs = budgetMs;
                     if (args.action === 'back') {
+                        controller.requireExtensionCommand('tabs.back', '1.7.0');
                         return await controller.execute('tabs.back', params, exec.signal, budgetMs + BRIDGE_MARGIN_MS);
                     }
+                    controller.requireExtensionCommand('tabs.forward', '1.7.0');
                     return await controller.execute('tabs.forward', params, exec.signal, budgetMs + BRIDGE_MARGIN_MS);
                 }
                 case 'group':
@@ -1012,6 +1089,7 @@ function applyBrowserTools(ctx, controller) {
         async execute(args, exec) {
             switch (args.action) {
                 case 'list':
+                    controller.requireExtensionCommand('windows.list', '1.6.0');
                     return await controller.execute('windows.list', {}, exec.signal);
                 case 'open': {
                     const params = {};
@@ -1027,6 +1105,7 @@ function applyBrowserTools(ctx, controller) {
                     }
                     if (args.focused !== undefined)
                         params.focused = args.focused;
+                    controller.requireExtensionCommand('windows.open', '1.6.0');
                     return await controller.execute('windows.open', params, exec.signal);
                 }
                 case 'update': {
@@ -1043,9 +1122,11 @@ function applyBrowserTools(ctx, controller) {
                         params.alwaysOnTop = args.alwaysOnTop;
                     if (args.drawAttention === true)
                         params.drawAttention = true;
+                    controller.requireExtensionCommand('windows.update', '1.6.0');
                     return await controller.execute('windows.update', params, exec.signal);
                 }
                 case 'close':
+                    controller.requireExtensionCommand('windows.close', '1.6.0');
                     return await controller.execute('windows.close', { windowId: requireWindowId(args, 'close') }, exec.signal);
                 case 'moveTab': {
                     if (args.tabId === undefined && args.tabIds === undefined)
@@ -1057,6 +1138,7 @@ function applyBrowserTools(ctx, controller) {
                         params.tabIds = args.tabIds;
                     if (args.index !== undefined)
                         params.index = args.index;
+                    controller.requireExtensionCommand('windows.moveTab', '1.6.0');
                     return await controller.execute('windows.moveTab', params, exec.signal);
                 }
                 default:
@@ -1440,16 +1522,19 @@ function applyBrowserTools(ctx, controller) {
             const params = {};
             if (args.tabId !== undefined)
                 params.tabId = args.tabId;
+            controller.requireExtensionCommand('archive', '1.5.0');
             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.',
+        description: 'Switch the tab into a device viewport (mobile / tablet / desktop) for responsive-UI testing, and throttle the network or CPU to test slow conditions. `device:"reset"` restores the user\'s actual viewport and clears all throttling. `network` presets (this tool\'s own numbers): slow3g = 400ms RTT + ~50KB/s both ways, fast3g = 150ms + ~200KB/s down / ~94KB/s up, offline, reset to clear. `cpuThrottlingRate` multiplies CPU cost (1 = off, up to 20). Throttling lives in the debugger session — it is gone when the extension detaches, and device:"reset" clears it too. Custom `width`/`height`/`deviceScaleFactor`/`isMobile`/`hasTouch` override any preset field.',
         parameters: {
             tabId: { type: 'number', description: 'Target tab; defaults to the active tab.' },
             device: { type: 'string', description: 'Preset: desktop | mobile-iphone-13 | mobile-pixel-7 | tablet-ipad | reset. Or pass custom width/height below.' },
+            network: { type: 'string', description: 'slow3g | fast3g | offline | reset. The receipt reports the applied latency/throughput in bytes per second.' },
+            cpuThrottlingRate: { type: 'number', description: 'CPU slowdown multiplier: 1 = none (default), 4 = mid-range phone, up to 20.' },
             width: { type: 'number', description: 'Custom viewport width in CSS px.' },
             height: { type: 'number', description: 'Custom viewport height in CSS px.' },
             deviceScaleFactor: { type: 'number', description: 'Custom DPR (1 = standard, 2 = retina, 3 = super-retina).' },
@@ -1470,26 +1555,37 @@ function applyBrowserTools(ctx, controller) {
                     isMobile: { type: 'boolean' },
                     hasTouch: { type: 'boolean' },
                     userAgent: { type: 'string' },
+                    network: { type: 'string' },
+                    latency: { type: 'number' },
+                    downloadThroughput: { type: 'number' },
+                    uploadThroughput: { type: 'number' },
+                    cpuThrottlingRate: { type: 'number' },
                 },
             },
             render: (_args, value) => {
                 if (value.reset)
-                    return [{ type: 'text', text: `Tab ${value.tabId}: emulation reset to default` }];
-                // 覆盖生效的是哪个 UA 必须写出来：模型只看这句，看不见 value 里的字段。
+                    return [{ type: 'text', text: `Tab ${value.tabId}: emulation reset to default (network unthrottled, CPU rate 1)` }];
+                // 覆盖生效的是哪个 UA / 哪档节流必须写出来：模型只看这句，看不见 value 里的字段。
                 const ua = value.userAgent === undefined ? '' : ` UA="${flattenOneLine(value.userAgent, 80)}"`;
+                const net = value.network === undefined ? '' : ` network=${value.network}(${value.latency}ms↓${value.downloadThroughput}B/s↑${value.uploadThroughput}B/s)`;
+                const cpu = value.cpuThrottlingRate === undefined ? '' : ` cpu×${value.cpuThrottlingRate}`;
                 return [{
                         type: 'text',
-                        text: `Tab ${value.tabId}: ${value.width || '?'}×${value.height || '?'} DPR=${value.deviceScaleFactor ?? '?'} mobile=${value.isMobile ?? false} touch=${value.hasTouch ?? false}${ua}`,
+                        text: `Tab ${value.tabId}: ${value.width || '?'}×${value.height || '?'} DPR=${value.deviceScaleFactor ?? '?'} mobile=${value.isMobile ?? false} touch=${value.hasTouch ?? false}${ua}${net}${cpu}`,
                     }];
             },
         },
-        presentCall: args => ({ card: 'generic', title: `Emulate${args.device ? ' ' + args.device : ' device'}`, kind: 'other' }),
+        presentCall: args => ({ card: 'generic', title: `Emulate${args.device ? ' ' + args.device : ''}${args.network ? ' ' + args.network : ''}${args.cpuThrottlingRate ? ' cpu×' + args.cpuThrottlingRate : ''}`, kind: 'other' }),
         async execute(args, exec) {
             const params = {};
             if (args.tabId !== undefined)
                 params.tabId = args.tabId;
             if (typeof args.device === 'string')
                 params.device = args.device;
+            if (typeof args.network === 'string')
+                params.network = args.network;
+            if (typeof args.cpuThrottlingRate === 'number')
+                params.cpuThrottlingRate = args.cpuThrottlingRate;
             if (typeof args.width === 'number')
                 params.width = args.width;
             if (typeof args.height === 'number')
@@ -1515,9 +1611,78 @@ function applyBrowserTools(ctx, controller) {
                 ...(typeof raw.isMobile === 'boolean' ? { isMobile: raw.isMobile } : {}),
                 ...(typeof raw.hasTouch === 'boolean' ? { hasTouch: raw.hasTouch } : {}),
                 ...(typeof raw.userAgent === 'string' && raw.userAgent.length > 0 ? { userAgent: raw.userAgent } : {}),
+                ...(typeof raw.network === 'string' ? { network: raw.network } : {}),
+                ...(typeof raw.latency === 'number' ? { latency: raw.latency } : {}),
+                ...(typeof raw.downloadThroughput === 'number' ? { downloadThroughput: raw.downloadThroughput } : {}),
+                ...(typeof raw.uploadThroughput === 'number' ? { uploadThroughput: raw.uploadThroughput } : {}),
+                ...(typeof raw.cpuThrottlingRate === 'number' ? { cpuThrottlingRate: raw.cpuThrottlingRate } : {}),
             };
         },
     }));
+    // Performance metrics: a pure read of CDP counters — whitelisted under
+    // readOnly, no effect on the page, and the numbers ARE the content.
+    ctx.tools.register(defineTool({
+        name: 'browser_metrics',
+        description: 'Read the tab\'s performance counters (Performance.getMetrics): DOM node count, JS heap usage, layout/style recalc counts, script/task durations. Use it to back "this page is heavy" with numbers, before and after an action. Read-only.',
+        parameters: {
+            tabId: { type: 'number', description: 'Target tab; defaults to the active tab.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    tabId: { type: 'number', required: true },
+                    metrics: {
+                        type: 'object',
+                        required: true,
+                        additionalProperties: false,
+                        properties: {
+                            Timestamp: { type: 'number' },
+                            Documents: { type: 'number' },
+                            Frames: { type: 'number' },
+                            JSEventListeners: { type: 'number' },
+                            Nodes: { type: 'number' },
+                            LayoutCount: { type: 'number' },
+                            RecalcStyleCount: { type: 'number' },
+                            LayoutDuration: { type: 'number' },
+                            RecalcStyleDuration: { type: 'number' },
+                            ScriptDuration: { type: 'number' },
+                            TaskDuration: { type: 'number' },
+                            JSHeapUsedSize: { type: 'number' },
+                            JSHeapTotalSize: { type: 'number' },
+                        },
+                    },
+                },
+            },
+            render: (_args, value) => {
+                const m = (value.metrics ?? {});
+                // 数字本身就是产出：关键几项原样进模型可见文本，heap 顺手换算成 MB。
+                const parts = [];
+                if (m.Nodes !== undefined)
+                    parts.push(`nodes=${m.Nodes}`);
+                if (m.JSHeapUsedSize !== undefined) {
+                    const total = m.JSHeapTotalSize !== undefined ? `/${(m.JSHeapTotalSize / 1_048_576).toFixed(1)}MB` : '';
+                    parts.push(`heap=${(m.JSHeapUsedSize / 1_048_576).toFixed(1)}${total}`);
+                }
+                if (m.LayoutCount !== undefined)
+                    parts.push(`layouts=${m.LayoutCount}`);
+                if (m.ScriptDuration !== undefined)
+                    parts.push(`script=${Number(m.ScriptDuration).toFixed(2)}s`);
+                if (m.TaskDuration !== undefined)
+                    parts.push(`tasks=${Number(m.TaskDuration).toFixed(2)}s`);
+                return [{ type: 'text', text: `Tab ${value.tabId}: ${parts.join(' ') || JSON.stringify(value.metrics)}` }];
+            },
+        },
+        presentCall: () => ({ card: 'generic', title: 'Browser metrics', kind: 'other' }),
+        async execute(args, exec) {
+            const params = {};
+            if (args.tabId !== undefined)
+                params.tabId = args.tabId;
+            controller.requireExtensionCommand('metrics', '1.7.1');
+            return await controller.execute('metrics', params, exec.signal);
+        },
+    }));
 }
 /** Cordis plugin entry: wire the settings-driven lifecycle plus the model-facing tools. */
 export function apply(ctx, config) {

package/lib/types/policy.js

@@ -28,6 +28,9 @@ export const READ_ONLY_ALLOWED = new Set([
     'windows.list',
     // 读浏览器自己的状态（cookie 是凭据，但 get 不改任何东西；set/remove 不在此列）
     'cookies.get',
+    // 读性能计数器（Performance.getMetrics）：纯粹读，重试无损害；节流（emulate
+    // 的 network/cpu 参数）改页面加载行为，emulate 整体仍是写命令，不在此列。
+    'metrics',
 ]);
 /**
  * 会执行**任意页面脚本**的扩展命令。这条与只读档分开管，因为用户可能想「可以读、

package/lib/types/server.d.ts

@@ -42,6 +42,11 @@ export interface BridgeHello {
         readonly version: string;
         readonly ua: string;
     };
+    /**
+     * Command names the extension implements (v1.7.2+). Absent when the extension
+     * predates the capability handshake — callers fall back to a version map.
+     */
+    readonly capabilities?: readonly string[];
 }
 /** Snapshot of the link and in-flight work, served verbatim on `/api/status`. */
 export interface BridgeServerStatus {

package/lib/types/server.js

@@ -488,13 +488,17 @@ export class BridgeServer {
         }
         if (msg.type === 'hello') {
             const declared = typeof msg.protocol === 'number' ? msg.protocol : 0;
+            const capabilities = Array.isArray(msg.capabilities)
+                ? msg.capabilities.filter((c) => typeof c === 'string')
+                : undefined;
             this.hello = {
                 client: typeof msg.client === 'string' ? msg.client : 'unknown',
                 version: typeof msg.version === 'string' ? msg.version : 'unknown',
                 protocol: declared,
                 browser: (msg.browser ?? { name: 'unknown', version: 'unknown', ua: '' }),
+                ...(capabilities !== undefined ? { capabilities } : {}),
             };
-            this.log(`hello: client=${this.hello.client} v${this.hello.version} protocol=v${declared || '?'} browser=${this.hello.browser.name} ${this.hello.browser.version}`);
+            this.log(`hello: client=${this.hello.client} v${this.hello.version} protocol=v${declared || '?'} browser=${this.hello.browser.name} ${this.hello.browser.version}${capabilities ? ` capabilities=${capabilities.length}` : ''}`);
             const note = this.protocolNote;
             if (note !== null)
                 this.log(`protocol mismatch: ${note}`);

package/llms.txt

@@ -33,9 +33,16 @@ Chrome 浏览器扩展 + DeepSeek Harness 插件，让 AI Agent 通过 CDP 驱
 - `browser_cookies` 的 get 会把 **cookie 值原样**放进模型可见文本（cookie 值 = 凭据，这是这条工具的定义而不是副作用）；只读档放行 get、拒 set/remove
 - `browser_hold`（接管浮层）是**软层**：它告诉用户模型在操作这一页并挡住误触，用户双击即可关掉；卡片上按「中止操作」后扩展拒绝 `click`/`input`/`press`/`nav`，但模型可以调 `hold action=off` 解除。它不是安全边界，也不是防逃逸手段——要冻住浏览器用扩展弹窗里的「锁定」
 
+## 版本与兼容
+
+- **插件升级对旧扩展零倒退**（铁律：插件 x + 扩展 x-n ≥ 插件 x-n + 扩展 x-n，兼容矩阵台机器验证，不是口号）
+- v1.7.2+ 扩展的 hello 帧带 `capabilities`（命令清单），插件精确握手；老扩展的 hello 不带 ⇒ 版本映射兜底
+- 插件比扩展新时，缺命令的动作在发送前拦下：`extension_outdated` + 可执行的重装指引，绝不裸 unknown command
+- 扩展预埋 `cdp` 透传（内部原语，不进模型工具面）：CDP 层新能力从此只发插件，扩展装一次长期用
+
 ## 关键文件
 
-- `src/index.ts` - 24 个 `browser_*` 工具注册 + settings 接线的版本兼容分支
+- `src/index.ts` - 25 个 `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.0",
+  "version": "1.7.2",
   "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"
+    "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_compat_matrix.mjs"
   },
   "publishConfig": {
     "access": "public",