@angelky7/dsh-browser-control 1.7.2 → 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.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) |
+| [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.2"
+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
 

package/README.md

@@ -64,8 +64,8 @@ Chrome 扩展（CDP 驱动）
 
 | 文件 | 说明 |
 |---|---|
-| [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） |
+| [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.2"
+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` 失败。
 
 ## 架构
 
@@ -296,7 +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.1），当前插件对每个面跑 27 个探针逐格验收「≥ 当年组合」；新工具报带重装指引的 extension-outdated、绝不许 unknown command 冒充；命令面 append-only（扩展升级对旧插件也纯增益） | ✅ 2026-11-04，5 面 × 150 项；老 hello 无 capabilities ⇒ 版本映射兜底路径的实测 |
+| 实测台 `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

@@ -1061,6 +1061,17 @@ var BridgeController = class {
 	get shotsDir() {
 		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;
@@ -3135,6 +3146,334 @@ function applyBrowserTools(ctx, controller) {
 			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/index.js

@@ -123,6 +123,14 @@ 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;
@@ -1683,6 +1691,272 @@ function applyBrowserTools(ctx, controller) {
             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/llms.txt

@@ -42,7 +42,7 @@ Chrome 浏览器扩展 + DeepSeek Harness 插件，让 AI Agent 通过 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.2",
+  "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 && node verify/verify_compat_matrix.mjs"
+    "verify": "node verify/verify_config_patch.mjs && node verify/verify_peers.mjs && node verify/verify_surface.mjs && node verify/verify_tab_groups.mjs && node verify/verify_tabs_close_many.mjs && node verify/verify_cdp_retry.mjs && node verify/verify_snapshot_ax.mjs && node verify/verify_hard_lock.mjs && node verify/verify_policy.mjs && node verify/verify_cookies.mjs && node verify/verify_extension_e2e.mjs && node verify/verify_plugin.mjs legacy && node verify/verify_plugin.mjs conflict && node verify/verify_plugin.mjs new && node verify/verify_http.mjs && node verify/verify_errors.mjs && node verify/verify_hold.mjs && node verify/verify_protocol.mjs && node verify/verify_bundle_http.mjs && node verify/verify_nav_report.mjs && node verify/verify_nav_landing.mjs && node verify/verify_render_contract.mjs && node verify/verify_press_events.mjs && node verify/verify_nav_timeout.mjs && node verify/verify_nav_waituntil.mjs && node verify/verify_archive.mjs && node verify/verify_windows.mjs && node verify/verify_history_nav.mjs && node verify/verify_metrics_throttle.mjs && node verify/verify_drag.mjs && node verify/verify_compat_matrix.mjs"
   },
   "publishConfig": {
     "access": "public",