@angelky7/dsh-browser-control 1.7.1 → 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.1.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.1/DSH-Browser-Control-v1.7.1.zip) | Chrome extension (unzip and load; this release adds the metrics command and emulate throttling — reinstall required) |
-| [dsh-browser-control-plugin-v1.7.1.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.1/dsh-browser-control-plugin-v1.7.1.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.1"
+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"
@@ -288,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
 
@@ -301,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.1.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.1/DSH-Browser-Control-v1.7.1.zip) | Chrome 扩展（解压后加载；这一版扩展新增 metrics 命令与 emulate 节流参数，**必须重装**） |
-| [dsh-browser-control-plugin-v1.7.1.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.1/dsh-browser-control-plugin-v1.7.1.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.1"
+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"
@@ -282,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 层新能力此后只更插件
 
 ## 已验证
 
@@ -295,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;
@@ -984,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.
@@ -1002,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
@@ -2147,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);
@@ -2244,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;
@@ -2257,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": {
@@ -2271,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)`);
@@ -2849,6 +2947,7 @@ 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);
 		}
 	}));
@@ -3032,6 +3131,7 @@ function applyBrowserTools(ctx, controller) {
 		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);
 		}
 	}));

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,6 +1522,7 @@ 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);
         },
@@ -1596,6 +1679,7 @@ function applyBrowserTools(ctx, controller) {
             const params = {};
             if (args.tabId !== undefined)
                 params.tabId = args.tabId;
+            controller.requireExtensionCommand('metrics', '1.7.1');
             return await controller.execute('metrics', params, exec.signal);
         },
     }));

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,6 +33,13 @@ 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` - 25 个 `browser_*` 工具注册 + settings 接线的版本兼容分支

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.1",
+  "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 && node verify/verify_metrics_throttle.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",