@angelky7/dsh-browser-control 1.7.1 → 1.7.3

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; **the extension no longer changes with feature updates from v1.7.2 on**: v1.7.3 does not touch the extension — skip this if v1.7.2 is already loaded) |
+| [dsh-browser-control-plugin-v1.7.3.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.3/dsh-browser-control-plugin-v1.7.3.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.3"
 
 # Local checkout for debugging (note: the explicit file: prefix is required)
 dsh plugin --profile web add "file:D:\path\to\dsh-browser-control"
@@ -267,10 +267,11 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `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+); v1.7.1+ adds throttling: `network` slow3g/fast3g/offline/reset + `cpuThrottlingRate` (1–20), the receipt states the applied numbers, `device:"reset"` clears them too |
 | `browser_metrics` | Read performance counters (DOM nodes / JS heap / layout & script durations, Performance.getMetrics, read-only; puts numbers behind "this page is heavy", v1.7.1+) |
+| `browser_drag` | Drag from/to a selector or viewport point: `auto` synthesizes html5 dragstart→dragover→drop for `draggable="true"` sources (no drop unless accepted), otherwise sends real mouse input (press, interpolated moves, release — sliders/canvas/sortable widgets). **Plugin-side only** over the cdp channel embedded in extension v1.7.2, v1.7.3+ |
 | `browser_cleanup` | Clean up temp files |
 | `browser_info` | Which browser and extension build is attached (run it first when debugging, v1.0.9+) |
 
-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`.
+26 tools in total. `browser_wait`, `browser_find`, `browser_dialog` and `browser_info` existed inside the extension up to v1.0.8 but were never registered as tools, so the agent could not reach them; `browser_network_clear` existed in code and was simply missing from this table. `verify/verify_surface.mjs` now reconciles the extension command table, the commands the plugin calls, this table and the built bundle, so any drift fails `npm run verify`.
 
 ## Architecture
 
@@ -288,6 +289,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 +303,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 扩展（解压后加载；**扩展从 v1.7.2 起不再随功能更新**：v1.7.3 没有动扩展，装过 v1.7.2 的不用重装） |
+| [dsh-browser-control-plugin-v1.7.3.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.3/dsh-browser-control-plugin-v1.7.3.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.3"
 
 # 本地目录调试（注意：必须显式 file: 前缀）
 dsh plugin --profile web add "file:D:\path\to\dsh-browser-control"
@@ -260,11 +260,12 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `browser_archive` | 整页存成单文件 MHTML（正文/图片/样式全内联，可当文本 grep 的离线证据；是快照，内嵌脚本不会跑，v1.5.0+） |
 | `browser_emulate` | 切设备视口（移动 / 桌面 / 自定义，v1.0.7+）；v1.7.1 起还能限速：`network` slow3g/fast3g/offline/reset + `cpuThrottlingRate`（1–20），回执写明生效数值，`device:"reset"` 一并还原 |
 | `browser_metrics` | 读性能计数器（DOM 节点数 / JS 堆 / 布局与脚本耗时，Performance.getMetrics，只读；让「这页面很重」有数字说话，v1.7.1+） |
+| `browser_drag` | 拖拽：from/to 用选择器或视口坐标；`auto` 对 `draggable="true"` 的源走 html5 事件合成（dragstart→dragover→drop，未接受就不 drop），其余走真实鼠标输入（按下→插值移动→抬起，滑杆/画布/排序组件用这个）。**纯插件实现**（经 v1.7.2 预埋的 cdp 通道），v1.7.3+ |
 | `browser_windows` | 窗口控制：清单/开窗/改状态与几何/关整窗/跨窗挪标签（唯一能碰窗口几何的工具，v1.6.0+） |
 | `browser_cleanup` | 清理临时文件 |
 | `browser_info` | 报告实际连上的浏览器与扩展版本（排障先跑它，v1.0.9+） |
 
-共 25 个工具。`browser_wait` / `browser_find` / `browser_dialog` / `browser_info` 在 v1.0.8 及以前是「扩展里已实现、但没注册成工具」，agent 调不到；`browser_network_clear` 则是代码里有、这张表漏了。这些现在由 `verify/verify_surface.mjs` 做三方对账（扩展命令表 ↔ 插件调用 ↔ 文档表 ↔ 构建产物），漂移会直接让 `npm run verify` 失败。
+共 26 个工具。`browser_wait` / `browser_find` / `browser_dialog` / `browser_info` 在 v1.0.8 及以前是「扩展里已实现、但没注册成工具」，agent 调不到；`browser_network_clear` 则是代码里有、这张表漏了。这些现在由 `verify/verify_surface.mjs` 做三方对账（扩展命令表 ↔ 插件调用 ↔ 文档表 ↔ 构建产物），漂移会直接让 `npm run verify` 失败。
 
 ## 架构
 
@@ -282,6 +283,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 +297,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.2），当前插件对每个面跑 28 个探针逐格验收「≥ 当年组合」；新工具报带重装指引的 extension-outdated、绝不许 unknown command 冒充；命令面 append-only（扩展升级对旧插件也纯增益） | ✅ 2026-11-04，6 面 × 186 项；老 hello 无 capabilities ⇒ 版本映射兜底路径的实测，v1.7.2 面实测 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.
@@ -1003,6 +1062,45 @@ var BridgeController = class {
 		return this.current === void 0 ? void 0 : path.resolve(this.current.shotsDir);
 	}
 	/**
+	* Current policy flags. Tools that compose several commands (browser_drag
+	* runs `cdp`/`eval`) read this to refuse with a tool-level message; the
+	* per-command gate in execute() stays as the enforcement backstop.
+	*/
+	get policy() {
+		return {
+			readOnly: this.current?.readOnly === true,
+			allowScript: this.current?.allowScript !== false
+		};
+	}
+	/** 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
 	* failure instead, so a bad port cannot tear down an otherwise running session.
@@ -2147,7 +2245,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 +2346,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 +2361,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 +2376,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 +2958,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,9 +3142,338 @@ 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);
 		}
 	}));
+	registerDragTool(ctx, controller);
+}
+/** One CDP round-trip over the embedded `cdp` passthrough (extension v1.7.2+). */
+async function cdpCall(ctrl, tabId, method, params, signal) {
+	return await ctrl.execute("cdp", {
+		method,
+		params,
+		tabId
+	}, signal);
+}
+function dragTargetArgs(selector, x, y, side) {
+	const hasSel = typeof selector === "string" && selector.length > 0;
+	const hasX = typeof x === "number" && Number.isFinite(x);
+	const hasY = typeof y === "number" && Number.isFinite(y);
+	if (hasSel && (hasX || hasY)) throw new Error(`${side}: give either "${side}" (CSS selector) or "${side}X"/"${side}Y" coordinates, not both`);
+	if (!hasSel && !(hasX && hasY)) throw new Error(`${side}: needs a CSS selector ("${side}") or both "${side}X" and "${side}Y" coordinates`);
+	if (hasSel) return { selector };
+	return {
+		x,
+		y
+	};
+}
+/**
+* Resolve a drag endpoint. Selector endpoints become viewport coordinates via
+* the CDP DOM domain — no page JavaScript, so mouse mode also works with
+* `allowScript: false`. Top document only; cross-origin iframes are a later
+* iteration.
+*/
+async function resolveDragPoint(ctrl, tabId, target, signal) {
+	if (target.selector === void 0) return {
+		x: target.x,
+		y: target.y
+	};
+	const selector = target.selector;
+	const rootId = (await cdpCall(ctrl, tabId, "DOM.getDocument", { depth: 0 }, signal))?.root?.nodeId;
+	if (typeof rootId !== "number") throw new Error("DOM.getDocument returned no root node");
+	const nodeId = (await cdpCall(ctrl, tabId, "DOM.querySelector", {
+		nodeId: rootId,
+		selector
+	}, signal))?.nodeId ?? 0;
+	if (nodeId === 0) throw new Error(`no element matches selector ${JSON.stringify(selector)} (top document only)`);
+	await cdpCall(ctrl, tabId, "DOM.scrollIntoViewIfNeeded", { nodeId }, signal);
+	let box;
+	try {
+		box = await cdpCall(ctrl, tabId, "DOM.getBoxModel", { nodeId }, signal);
+	} catch (error) {
+		throw new Error(`cannot measure ${JSON.stringify(selector)} — hidden, zero-size or detached? (${error instanceof Error ? error.message : String(error)})`);
+	}
+	const q = box?.model?.content;
+	if (!Array.isArray(q) || q.length < 8) throw new Error(`DOM.getBoxModel returned no quad for ${JSON.stringify(selector)}`);
+	return {
+		selector,
+		x: (q[0] + q[2] + q[4] + q[6]) / 4,
+		y: (q[1] + q[3] + q[5] + q[7]) / 4,
+		width: typeof box?.model?.width === "number" ? box.model.width : Math.hypot(q[2] - q[0], q[3] - q[1]),
+		height: typeof box?.model?.height === "number" ? box.model.height : Math.hypot(q[4] - q[2], q[5] - q[3]),
+		nodeId
+	};
+}
+/** Whether the source declares the native HTML5 `draggable` attribute. */
+async function sourceIsDraggable(ctrl, tabId, nodeId, signal) {
+	const attrs = await cdpCall(ctrl, tabId, "DOM.getAttributes", { nodeId }, signal);
+	const list = Array.isArray(attrs?.attributes) ? attrs.attributes.map(String) : [];
+	const at = list.indexOf("draggable");
+	return at >= 0 && list[at + 1] === "true";
+}
+/**
+* Synthesize a native-order HTML5 drag in the page: dragstart on the source,
+* dragenter/dragover on the target, drop only when dragover was prevented
+* (the browser's own rule), dragend on the source, all sharing one DataTransfer.
+* Untrusted events — pages that gate on `event.isTrusted` will ignore them,
+* which the tool description states instead of pretending otherwise.
+*/
+function html5DragExpression(fromSelector, to) {
+	const toExpr = to.selector !== void 0 ? `document.querySelector(${JSON.stringify(to.selector)})` : `document.elementFromPoint(${to.x}, ${to.y})`;
+	return `(() => {
+  const src = document.querySelector(${JSON.stringify(fromSelector)});
+  if (!src) return { error: 'no element matches from selector ' + ${JSON.stringify(fromSelector)} };
+  const dst = ${toExpr};
+  if (!dst) return { error: 'target element not found' };
+  const dt = new DataTransfer();
+  const log = [];
+  const sr = src.getBoundingClientRect();
+  const dr = dst.getBoundingClientRect();
+  const sx = sr.left + sr.width / 2, sy = sr.top + sr.height / 2;
+  const tx = dr.left + dr.width / 2, ty = dr.top + dr.height / 2;
+  const fire = (type, target, cx, cy) => {
+    const ev = new DragEvent(type, { bubbles: true, cancelable: true, composed: true, dataTransfer: dt, clientX: cx, clientY: cy });
+    target.dispatchEvent(ev);
+    log.push({ type, defaultPrevented: ev.defaultPrevented });
+    return ev.defaultPrevented;
+  };
+  const startCancelled = fire('dragstart', src, sx, sy);
+  let dragenterDefaultPrevented = false, overPrevented = false, dropFired = false, dropPrevented = false;
+  if (!startCancelled) {
+    dragenterDefaultPrevented = fire('dragenter', dst, tx, ty);
+    overPrevented = fire('dragover', dst, tx, ty);
+    if (overPrevented) {
+      dropFired = true;
+      dropPrevented = fire('drop', dst, tx, ty);
+    }
+  }
+  fire('dragend', src, sx, sy);
+  return { startCancelled, dragenterDefaultPrevented, overPrevented, dropFired, dropPrevented, events: log.length, log };
+})()`;
+}
+function roundDragPoint(p) {
+	const out = {
+		x: Math.round(p.x * 100) / 100,
+		y: Math.round(p.y * 100) / 100
+	};
+	if (p.selector !== void 0) out.selector = p.selector;
+	if (p.width !== void 0) out.width = Math.round(p.width * 100) / 100;
+	if (p.height !== void 0) out.height = Math.round(p.height * 100) / 100;
+	return out;
+}
+function registerDragTool(ctx, controller) {
+	ctx.tools.register(defineTool({
+		name: "browser_drag",
+		description: "Drag a page element or point onto another with real input. mode \"mouse\" sends trusted press→moves→release input via CDP (canvas, sliders, sortable widgets); mode \"html5\" synthesizes dragstart/dragover/drop in the page for [draggable] elements and needs page scripting; \"auto\" (default) picks html5 only when the source declares draggable=\"true\". Endpoints are CSS selectors (top document) or fromX/fromY + toX/toY viewport coordinates. Needs browser extension v1.7.2+ (embedded cdp channel).",
+		parameters: {
+			from: {
+				type: "string",
+				description: "CSS selector of the drag source; use fromX/fromY instead for raw coordinates."
+			},
+			to: {
+				type: "string",
+				description: "CSS selector of the drop target; use toX/toY instead for raw coordinates."
+			},
+			fromX: {
+				type: "number",
+				description: "Viewport x of the drag start point (with fromY)."
+			},
+			fromY: {
+				type: "number",
+				description: "Viewport y of the drag start point (with fromX)."
+			},
+			toX: {
+				type: "number",
+				description: "Viewport x of the drop point (with toY)."
+			},
+			toY: {
+				type: "number",
+				description: "Viewport y of the drop point (with toX)."
+			},
+			tabId: {
+				type: "number",
+				description: "Target tab; defaults to the active tab."
+			},
+			mode: {
+				type: "string",
+				description: "\"auto\" (default), \"mouse\" or \"html5\" — see the tool description."
+			},
+			steps: {
+				type: "number",
+				description: "Intermediate mouse moves in mouse mode, 1–50 (default 12)."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					tabId: {
+						type: "number",
+						required: true
+					},
+					mode: {
+						type: "string",
+						required: true
+					},
+					from: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							selector: { type: "string" },
+							x: { type: "number" },
+							y: { type: "number" },
+							width: { type: "number" },
+							height: { type: "number" }
+						}
+					},
+					to: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							selector: { type: "string" },
+							x: { type: "number" },
+							y: { type: "number" },
+							width: { type: "number" },
+							height: { type: "number" }
+						}
+					},
+					steps: { type: "number" },
+					dispatched: { type: "number" },
+					startCancelled: { type: "boolean" },
+					dragenterDefaultPrevented: { type: "boolean" },
+					overPrevented: { type: "boolean" },
+					dropFired: { type: "boolean" },
+					dropPrevented: { type: "boolean" },
+					events: { type: "number" },
+					elapsedMs: {
+						type: "number",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => {
+				const v = value;
+				const d = (p) => p?.selector !== void 0 ? p.selector : `(${p?.x ?? "?"},${p?.y ?? "?"})`;
+				if (v.mode === "mouse") return [{
+					type: "text",
+					text: `Tab ${v.tabId}: dragged ${d(v.from)} → ${d(v.to)} with mouse input (${v.steps} steps, ${v.dispatched} dispatches, ${v.elapsedMs}ms)`
+				}];
+				const verdict = v.startCancelled === true ? "dragstart was cancelled by the page — nothing dropped" : v.overPrevented === true ? v.dropPrevented === true ? "drop fired and was handled" : "drop fired but no drop handler ran" : "target did not accept the drop (no dragover preventDefault)";
+				return [{
+					type: "text",
+					text: `Tab ${v.tabId}: dragged ${d(v.from)} → ${d(v.to)} with html5 events (${v.events} events, ${v.elapsedMs}ms) — ${verdict}`
+				}];
+			}
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: `Drag ${args.from ?? `(${args.fromX},${args.fromY})`} → ${args.to ?? `(${args.toX},${args.toY})`}`,
+			kind: "other"
+		}),
+		async execute(args, exec) {
+			const mode = args.mode === void 0 ? "auto" : args.mode;
+			if (mode !== "auto" && mode !== "mouse" && mode !== "html5") throw new Error(`mode must be "auto", "mouse" or "html5" — got ${JSON.stringify(mode)}`);
+			const from = dragTargetArgs(args.from, args.fromX, args.fromY, "from");
+			const to = dragTargetArgs(args.to, args.toX, args.toY, "to");
+			controller.requireExtensionCommand("cdp", "1.7.2");
+			if (controller.policy.readOnly) throw new Error("browser_drag changes page state and read-only mode is on — turn readOnly off in the browser-bridge config to drag");
+			let tabId = args.tabId;
+			if (tabId === void 0) {
+				const listing = await controller.execute("tabs.list", {}, exec.signal);
+				if (typeof listing?.activeTabId !== "number") throw new Error("could not resolve the active tab — pass tabId explicitly");
+				tabId = listing.activeTabId;
+			}
+			const started = Date.now();
+			let resolvedMode = mode === "auto" ? "mouse" : mode;
+			let source;
+			if (mode !== "html5") source = await resolveDragPoint(controller, tabId, from, exec.signal);
+			if (mode === "auto" && source?.nodeId !== void 0 && await sourceIsDraggable(controller, tabId, source.nodeId, exec.signal)) resolvedMode = "html5";
+			if (resolvedMode === "mouse") {
+				const target = await resolveDragPoint(controller, tabId, to, exec.signal);
+				const steps = Math.min(50, Math.max(1, Math.trunc(typeof args.steps === "number" ? args.steps : 12)));
+				const sx = source.x, sy = source.y, tx = target.x, ty = target.y;
+				const dispatch = async (params) => {
+					await cdpCall(controller, tabId, "Input.dispatchMouseEvent", params, exec.signal);
+				};
+				await dispatch({
+					type: "mouseMoved",
+					x: sx,
+					y: sy,
+					button: "none",
+					buttons: 0
+				});
+				await dispatch({
+					type: "mousePressed",
+					x: sx,
+					y: sy,
+					button: "left",
+					buttons: 1,
+					clickCount: 1
+				});
+				for (let i = 1; i <= steps; i++) {
+					const f = i / steps;
+					await dispatch({
+						type: "mouseMoved",
+						x: sx + (tx - sx) * f,
+						y: sy + (ty - sy) * f,
+						button: "left",
+						buttons: 1
+					});
+				}
+				await dispatch({
+					type: "mouseReleased",
+					x: tx,
+					y: ty,
+					button: "left",
+					buttons: 0,
+					clickCount: 1
+				});
+				await dispatch({
+					type: "mouseMoved",
+					x: tx,
+					y: ty,
+					button: "none",
+					buttons: 0
+				});
+				return {
+					tabId,
+					mode: "mouse",
+					from: roundDragPoint(source),
+					to: roundDragPoint(target),
+					steps,
+					dispatched: steps + 4,
+					elapsedMs: Date.now() - started
+				};
+			}
+			if (from.selector === void 0) throw new Error("html5 mode needs a CSS selector for \"from\" (a point has no draggable element)");
+			if (!controller.policy.allowScript) throw new Error("html5 drag synthesizes DOM events and needs page scripting — allowScript is off; use mode:\"mouse\" or re-enable the script switch");
+			const raw = await controller.execute("eval", {
+				expression: html5DragExpression(from.selector, to),
+				tabId
+			}, exec.signal);
+			const outcome = raw?.value;
+			if (outcome === void 0 || typeof outcome !== "object") throw new Error("html5 drag expression returned no outcome — page may have navigated mid-drag");
+			if (typeof outcome.error === "string") throw new Error(outcome.error);
+			return {
+				tabId: typeof raw?.tabId === "number" ? raw.tabId : tabId,
+				mode: "html5",
+				from: from.selector !== void 0 ? { selector: from.selector } : roundDragPoint(from),
+				to: to.selector !== void 0 ? { selector: to.selector } : {
+					x: to.x,
+					y: to.y
+				},
+				startCancelled: outcome.startCancelled === true,
+				dragenterDefaultPrevented: outcome.dragenterDefaultPrevented === true,
+				overPrevented: outcome.overPrevented === true,
+				dropFired: outcome.dropFired === true,
+				dropPrevented: outcome.dropPrevented === true,
+				events: typeof outcome.events === "number" ? outcome.events : 0,
+				elapsedMs: Date.now() - started
+			};
+		}
+	}));
 }
 /** 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,46 @@ class BridgeController {
     get shotsDir() {
         return this.current === undefined ? undefined : path.resolve(this.current.shotsDir);
     }
+    /**
+     * Current policy flags. Tools that compose several commands (browser_drag
+     * runs `cdp`/`eval`) read this to refuse with a tool-level message; the
+     * per-command gate in execute() stays as the enforcement backstop.
+     */
+    get policy() {
+        return { readOnly: this.current?.readOnly === true, allowScript: this.current?.allowScript !== false };
+    }
+    /** 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 +1047,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 +1097,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 +1113,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 +1130,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 +1146,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 +1530,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,9 +1687,276 @@ 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);
         },
     }));
+    registerDragTool(ctx, controller);
+}
+/* ------------------- browser_drag: composed plugin-side over the cdp channel ------------------- */
+/** One CDP round-trip over the embedded `cdp` passthrough (extension v1.7.2+). */
+async function cdpCall(ctrl, tabId, method, params, signal) {
+    return await ctrl.execute('cdp', { method, params, tabId }, signal);
+}
+function dragTargetArgs(selector, x, y, side) {
+    const hasSel = typeof selector === 'string' && selector.length > 0;
+    const hasX = typeof x === 'number' && Number.isFinite(x);
+    const hasY = typeof y === 'number' && Number.isFinite(y);
+    if (hasSel && (hasX || hasY))
+        throw new Error(`${side}: give either "${side}" (CSS selector) or "${side}X"/"${side}Y" coordinates, not both`);
+    if (!hasSel && !(hasX && hasY))
+        throw new Error(`${side}: needs a CSS selector ("${side}") or both "${side}X" and "${side}Y" coordinates`);
+    if (hasSel)
+        return { selector };
+    return { x, y };
+}
+/**
+ * Resolve a drag endpoint. Selector endpoints become viewport coordinates via
+ * the CDP DOM domain — no page JavaScript, so mouse mode also works with
+ * `allowScript: false`. Top document only; cross-origin iframes are a later
+ * iteration.
+ */
+async function resolveDragPoint(ctrl, tabId, target, signal) {
+    if (target.selector === undefined)
+        return { x: target.x, y: target.y };
+    const selector = target.selector;
+    const doc = await cdpCall(ctrl, tabId, 'DOM.getDocument', { depth: 0 }, signal);
+    const rootId = doc?.root?.nodeId;
+    if (typeof rootId !== 'number')
+        throw new Error('DOM.getDocument returned no root node');
+    const found = await cdpCall(ctrl, tabId, 'DOM.querySelector', { nodeId: rootId, selector }, signal);
+    const nodeId = found?.nodeId ?? 0;
+    if (nodeId === 0)
+        throw new Error(`no element matches selector ${JSON.stringify(selector)} (top document only)`);
+    await cdpCall(ctrl, tabId, 'DOM.scrollIntoViewIfNeeded', { nodeId }, signal);
+    let box;
+    try {
+        box = await cdpCall(ctrl, tabId, 'DOM.getBoxModel', { nodeId }, signal);
+    }
+    catch (error) {
+        throw new Error(`cannot measure ${JSON.stringify(selector)} — hidden, zero-size or detached? (${error instanceof Error ? error.message : String(error)})`);
+    }
+    const q = box?.model?.content;
+    if (!Array.isArray(q) || q.length < 8)
+        throw new Error(`DOM.getBoxModel returned no quad for ${JSON.stringify(selector)}`);
+    const x = (q[0] + q[2] + q[4] + q[6]) / 4;
+    const y = (q[1] + q[3] + q[5] + q[7]) / 4;
+    const width = typeof box?.model?.width === 'number' ? box.model.width : Math.hypot(q[2] - q[0], q[3] - q[1]);
+    const height = typeof box?.model?.height === 'number' ? box.model.height : Math.hypot(q[4] - q[2], q[5] - q[3]);
+    return { selector, x, y, width, height, nodeId };
+}
+/** Whether the source declares the native HTML5 `draggable` attribute. */
+async function sourceIsDraggable(ctrl, tabId, nodeId, signal) {
+    const attrs = await cdpCall(ctrl, tabId, 'DOM.getAttributes', { nodeId }, signal);
+    const list = Array.isArray(attrs?.attributes) ? attrs.attributes.map(String) : [];
+    const at = list.indexOf('draggable');
+    return at >= 0 && list[at + 1] === 'true';
+}
+/**
+ * Synthesize a native-order HTML5 drag in the page: dragstart on the source,
+ * dragenter/dragover on the target, drop only when dragover was prevented
+ * (the browser's own rule), dragend on the source, all sharing one DataTransfer.
+ * Untrusted events — pages that gate on `event.isTrusted` will ignore them,
+ * which the tool description states instead of pretending otherwise.
+ */
+function html5DragExpression(fromSelector, to) {
+    const toExpr = to.selector !== undefined
+        ? `document.querySelector(${JSON.stringify(to.selector)})`
+        : `document.elementFromPoint(${to.x}, ${to.y})`;
+    return `(() => {
+  const src = document.querySelector(${JSON.stringify(fromSelector)});
+  if (!src) return { error: 'no element matches from selector ' + ${JSON.stringify(fromSelector)} };
+  const dst = ${toExpr};
+  if (!dst) return { error: 'target element not found' };
+  const dt = new DataTransfer();
+  const log = [];
+  const sr = src.getBoundingClientRect();
+  const dr = dst.getBoundingClientRect();
+  const sx = sr.left + sr.width / 2, sy = sr.top + sr.height / 2;
+  const tx = dr.left + dr.width / 2, ty = dr.top + dr.height / 2;
+  const fire = (type, target, cx, cy) => {
+    const ev = new DragEvent(type, { bubbles: true, cancelable: true, composed: true, dataTransfer: dt, clientX: cx, clientY: cy });
+    target.dispatchEvent(ev);
+    log.push({ type, defaultPrevented: ev.defaultPrevented });
+    return ev.defaultPrevented;
+  };
+  const startCancelled = fire('dragstart', src, sx, sy);
+  let dragenterDefaultPrevented = false, overPrevented = false, dropFired = false, dropPrevented = false;
+  if (!startCancelled) {
+    dragenterDefaultPrevented = fire('dragenter', dst, tx, ty);
+    overPrevented = fire('dragover', dst, tx, ty);
+    if (overPrevented) {
+      dropFired = true;
+      dropPrevented = fire('drop', dst, tx, ty);
+    }
+  }
+  fire('dragend', src, sx, sy);
+  return { startCancelled, dragenterDefaultPrevented, overPrevented, dropFired, dropPrevented, events: log.length, log };
+})()`;
+}
+function roundDragPoint(p) {
+    const out = {
+        x: Math.round(p.x * 100) / 100,
+        y: Math.round(p.y * 100) / 100,
+    };
+    if (p.selector !== undefined)
+        out.selector = p.selector;
+    if (p.width !== undefined)
+        out.width = Math.round(p.width * 100) / 100;
+    if (p.height !== undefined)
+        out.height = Math.round(p.height * 100) / 100;
+    return out;
+}
+function registerDragTool(ctx, controller) {
+    ctx.tools.register(defineTool({
+        name: 'browser_drag',
+        description: 'Drag a page element or point onto another with real input. mode "mouse" sends trusted press→moves→release input via CDP (canvas, sliders, sortable widgets); mode "html5" synthesizes dragstart/dragover/drop in the page for [draggable] elements and needs page scripting; "auto" (default) picks html5 only when the source declares draggable="true". Endpoints are CSS selectors (top document) or fromX/fromY + toX/toY viewport coordinates. Needs browser extension v1.7.2+ (embedded cdp channel).',
+        parameters: {
+            from: { type: 'string', description: 'CSS selector of the drag source; use fromX/fromY instead for raw coordinates.' },
+            to: { type: 'string', description: 'CSS selector of the drop target; use toX/toY instead for raw coordinates.' },
+            fromX: { type: 'number', description: 'Viewport x of the drag start point (with fromY).' },
+            fromY: { type: 'number', description: 'Viewport y of the drag start point (with fromX).' },
+            toX: { type: 'number', description: 'Viewport x of the drop point (with toY).' },
+            toY: { type: 'number', description: 'Viewport y of the drop point (with toX).' },
+            tabId: { type: 'number', description: 'Target tab; defaults to the active tab.' },
+            mode: { type: 'string', description: '"auto" (default), "mouse" or "html5" — see the tool description.' },
+            steps: { type: 'number', description: 'Intermediate mouse moves in mouse mode, 1–50 (default 12).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    tabId: { type: 'number', required: true },
+                    mode: { type: 'string', required: true },
+                    from: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            selector: { type: 'string' },
+                            x: { type: 'number' },
+                            y: { type: 'number' },
+                            width: { type: 'number' },
+                            height: { type: 'number' },
+                        },
+                    },
+                    to: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            selector: { type: 'string' },
+                            x: { type: 'number' },
+                            y: { type: 'number' },
+                            width: { type: 'number' },
+                            height: { type: 'number' },
+                        },
+                    },
+                    steps: { type: 'number' },
+                    dispatched: { type: 'number' },
+                    startCancelled: { type: 'boolean' },
+                    dragenterDefaultPrevented: { type: 'boolean' },
+                    overPrevented: { type: 'boolean' },
+                    dropFired: { type: 'boolean' },
+                    dropPrevented: { type: 'boolean' },
+                    events: { type: 'number' },
+                    elapsedMs: { type: 'number', required: true },
+                },
+            },
+            render: (_args, value) => {
+                const v = value;
+                const d = (p) => p?.selector !== undefined ? p.selector : `(${p?.x ?? '?'},${p?.y ?? '?'})`;
+                if (v.mode === 'mouse') {
+                    return [{ type: 'text', text: `Tab ${v.tabId}: dragged ${d(v.from)} → ${d(v.to)} with mouse input (${v.steps} steps, ${v.dispatched} dispatches, ${v.elapsedMs}ms)` }];
+                }
+                const verdict = v.startCancelled === true
+                    ? 'dragstart was cancelled by the page — nothing dropped'
+                    : v.overPrevented === true
+                        ? (v.dropPrevented === true ? 'drop fired and was handled' : 'drop fired but no drop handler ran')
+                        : 'target did not accept the drop (no dragover preventDefault)';
+                return [{ type: 'text', text: `Tab ${v.tabId}: dragged ${d(v.from)} → ${d(v.to)} with html5 events (${v.events} events, ${v.elapsedMs}ms) — ${verdict}` }];
+            },
+        },
+        presentCall: args => ({
+            card: 'generic',
+            title: `Drag ${args.from ?? `(${args.fromX},${args.fromY})`} → ${args.to ?? `(${args.toX},${args.toY})`}`,
+            kind: 'other',
+        }),
+        async execute(args, exec) {
+            const mode = args.mode === undefined ? 'auto' : args.mode;
+            if (mode !== 'auto' && mode !== 'mouse' && mode !== 'html5')
+                throw new Error(`mode must be "auto", "mouse" or "html5" — got ${JSON.stringify(mode)}`);
+            const from = dragTargetArgs(args.from, args.fromX, args.fromY, 'from');
+            const to = dragTargetArgs(args.to, args.toX, args.toY, 'to');
+            controller.requireExtensionCommand('cdp', '1.7.2');
+            if (controller.policy.readOnly)
+                throw new Error('browser_drag changes page state and read-only mode is on — turn readOnly off in the browser-bridge config to drag');
+            let tabId = args.tabId;
+            if (tabId === undefined) {
+                const listing = await controller.execute('tabs.list', {}, exec.signal);
+                if (typeof listing?.activeTabId !== 'number')
+                    throw new Error('could not resolve the active tab — pass tabId explicitly');
+                tabId = listing.activeTabId;
+            }
+            const started = Date.now();
+            let resolvedMode = mode === 'auto' ? 'mouse' : mode;
+            let source;
+            if (mode !== 'html5')
+                source = await resolveDragPoint(controller, tabId, from, exec.signal);
+            if (mode === 'auto' && source?.nodeId !== undefined && await sourceIsDraggable(controller, tabId, source.nodeId, exec.signal)) {
+                resolvedMode = 'html5';
+            }
+            if (resolvedMode === 'mouse') {
+                const target = await resolveDragPoint(controller, tabId, to, exec.signal);
+                const steps = Math.min(50, Math.max(1, Math.trunc(typeof args.steps === 'number' ? args.steps : 12)));
+                const sx = source.x, sy = source.y, tx = target.x, ty = target.y;
+                const dispatch = async (params) => {
+                    await cdpCall(controller, tabId, 'Input.dispatchMouseEvent', params, exec.signal);
+                };
+                await dispatch({ type: 'mouseMoved', x: sx, y: sy, button: 'none', buttons: 0 });
+                await dispatch({ type: 'mousePressed', x: sx, y: sy, button: 'left', buttons: 1, clickCount: 1 });
+                for (let i = 1; i <= steps; i++) {
+                    const f = i / steps;
+                    await dispatch({ type: 'mouseMoved', x: sx + (tx - sx) * f, y: sy + (ty - sy) * f, button: 'left', buttons: 1 });
+                }
+                await dispatch({ type: 'mouseReleased', x: tx, y: ty, button: 'left', buttons: 0, clickCount: 1 });
+                await dispatch({ type: 'mouseMoved', x: tx, y: ty, button: 'none', buttons: 0 });
+                const receipt = {
+                    tabId,
+                    mode: 'mouse',
+                    from: roundDragPoint(source),
+                    to: roundDragPoint(target),
+                    steps,
+                    dispatched: steps + 4,
+                    elapsedMs: Date.now() - started,
+                };
+                return receipt;
+            }
+            if (from.selector === undefined)
+                throw new Error('html5 mode needs a CSS selector for "from" (a point has no draggable element)');
+            if (!controller.policy.allowScript)
+                throw new Error('html5 drag synthesizes DOM events and needs page scripting — allowScript is off; use mode:"mouse" or re-enable the script switch');
+            const raw = await controller.execute('eval', { expression: html5DragExpression(from.selector, to), tabId }, exec.signal);
+            const outcome = raw?.value;
+            if (outcome === undefined || typeof outcome !== 'object')
+                throw new Error('html5 drag expression returned no outcome — page may have navigated mid-drag');
+            if (typeof outcome.error === 'string')
+                throw new Error(outcome.error);
+            const receipt = {
+                tabId: typeof raw?.tabId === 'number' ? raw.tabId : tabId,
+                mode: 'html5',
+                from: from.selector !== undefined ? { selector: from.selector } : roundDragPoint(from),
+                to: to.selector !== undefined ? { selector: to.selector } : { x: to.x, y: to.y },
+                startCancelled: outcome.startCancelled === true,
+                dragenterDefaultPrevented: outcome.dragenterDefaultPrevented === true,
+                overPrevented: outcome.overPrevented === true,
+                dropFired: outcome.dropFired === true,
+                dropPrevented: outcome.dropPrevented === true,
+                events: typeof outcome.events === 'number' ? outcome.events : 0,
+                elapsedMs: Date.now() - started,
+            };
+            return receipt;
+        },
+    }));
 }
 /** Cordis plugin entry: wire the settings-driven lifecycle plus the model-facing tools. */
 export function apply(ctx, config) {

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` - 25 个 `browser_*` 工具注册 + settings 接线的版本兼容分支
+- `src/index.ts` - 26 个 `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.1",
+  "version": "1.7.3",
   "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_drag.mjs && node verify/verify_compat_matrix.mjs"
   },
   "publishConfig": {
     "access": "public",