pi-browser-use-lite 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# CHANGELOG
+
+本文件记录已发布版本的用户可见变更。更细的过程见 git log。破坏性变更标 **BREAKING**。
+
+## 0.1.0 — 2026-11-08
+
+首版。
+
+- 五个工具：`chrome_act`（navigate、click、type、fill、press、hover、drag、scroll、upload、eval、wait、batch）、`chrome_see`（refs、text、changes、full，另可取 console 与 network 日志）、`chrome_tab`（list、new、switch、close）、`chrome_vision`（截图落盘）、`chrome_cdp`（裸 CDP 调用）。
+- `/chrome` 命令：`authorize on|off`、`background on|off`、`status`。扩展装好之前，命令与工具都报 `extension_missing` 并给出装扩展三步。
+- 本地桥：只绑 `127.0.0.1`，多 Pi 会话共用一个服务端，其余退成客户端。扩展每 100 毫秒轮询一次。
+- 每个会话一个独立的浏览器窗口：动作在本次会话的 target 里执行，别的窗口不动，退出时按配置关掉标签。
+- 截图默认落在 `<agent dir>/pi-browser-use-lite/screenshots`，跟着 `PI_CODING_AGENT_DIR` 走，不写进家目录的 `~/.pi/screenshots`。
+- 发布：`CHANGELOG.md` 与 `browser-extension/` 一起进 `files`。用户从 npm 装到扩展源码后 load unpacked。
+- 扩展版本落后于包时自己重载一次，不必再去扩展页手动刷新。
+- 轮询断了由扩展的 1 秒定时器重起；`chrome.alarms` 只作服务工作进程被回收后的兜底。
+- `chrome_act eval` 省掉超长 `data` 时，说明接在正文末尾；此前这条说明到不了模型。
+- 包内带 `README.md`：安装、配置、开发各一节，扩展目录由 `/chrome status` 打印。

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024-2026 pi-chrome contributors
+Copyright (c) 2026 setwhite
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,151 @@
-# Temporary Holding Version
+# pi-browser-use-lite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Five `chrome_*` tools that drive your own browser: the tabs you are already logged into, with your cookies and your sessions.
+
+The package has two halves. The pi extension registers the tools and runs a local bridge on `127.0.0.1`. The companion Chrome extension polls that bridge and runs each command through `chrome.debugger`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `chrome_act` | navigate, click, type, fill, press, hover, drag, scroll, upload, eval, wait, batch |
+| `chrome_see` | snapshot the page as refs, text, changes or full; read console and network logs |
+| `chrome_tab` | list, new, switch, close |
+| `chrome_vision` | screenshot the viewport or the full page |
+| `chrome_cdp` | one raw CDP call for anything the other four do not cover |
+
+Behaviour worth knowing:
+
+- Each session gets its own browser window. The tools do not touch your own tabs. The tabs the session opened are closed when the session ends.
+- Input goes through trusted CDP events, so pages that reject synthetic events still react.
+- Console and network capture starts at navigation, not at the first read.
+- Every failure carries a class and a `hint` that says what to do next.
+
+## Install
+
+```bash
+pi install npm:pi-browser-use-lite
+```
+
+The extension ships inside the package. Load it once per browser:
+
+1. Run `/chrome status` in pi. When the extension is missing, the reply prints the directory to load.
+2. Open `chrome://extensions`, turn on Developer mode, click Load unpacked and pick that directory.
+3. Run `/chrome status` again. `connected: yes` means the bridge sees the extension.
+
+Then authorize the tools for this session:
+
+```
+/chrome authorize on
+```
+
+Authorization ends with the session. Set `policy.authorizeOnStart` to skip this step.
+
+## Configuration
+
+One JSON file: `<agent dir>/pi-browser-use-lite/config.json`. The agent dir is `PI_CODING_AGENT_DIR`, or `~/.pi/agent` when the variable is unset.
+
+Without the file every value is the default. A wrong type or an unknown key fails startup and names every bad field at once. An unknown enum value falls back to the default. An out-of-range number is clamped to the nearest bound. The comments below only explain. A real file must be strict JSON.
+
+**Minimal configuration**: nothing. All five tools work on the defaults.
+
+```json
+{}
+```
+
+**Full example**: every key follows with its default and when to change it.
+
+```jsonc
+{
+  // The local bridge. The extension has the same port compiled in
+  // (browser-extension/background/transport.js): change both, then reload the extension
+  "bridge": { "port": 17318 },
+
+  // Session rules
+  "policy": {
+    "authorizeOnStart": false,  // true = the tools work without /chrome authorize on
+    "background": true,         // true = block every focusing call, chrome_tab switch included.
+                                //        Turn it off when the model must bring a page to the front
+    "closeOwnTabsOnExit": true  // close the tabs this session opened when the session ends
+  },
+
+  // Input and timing
+  "input": {
+    "dragSteps": 10,            // mouse moves between press and release
+    "scrollSteps": 5            // wheel events per scroll call
+  },
+  "timing": { "navigateTimeoutMs": 15000 },  // wait for the load event; the navigate call gets this plus 2s
+
+  // Model-visible output
+  "output": {
+    "maxElements": 80,          // snapshot element cap
+    "textChars": 18000          // body text cap in see mode=text; the rest is dropped with a note
+  },
+
+  // Screenshots
+  "screenshot": {
+    "dir": "/home/me/.pi/agent/pi-browser-use-lite/screenshots",  // created on first use
+    "format": "png",            // png | jpeg
+    "keepNewest": 20            // older screenshots in that directory are deleted
+  },
+
+  // Global rules for the system prompt. These replace the three defaults; they do not extend them
+  "prompt": {
+    "guidelines": ["chrome_act: this is the user's real browser; confirm before destructive actions."]
+  },
+
+  // Tool switches and names. Keep at least one enabled; names must be unique and must not shadow a host tool
+  "tools": {
+    "chrome_act": { "enabled": true, "name": "chrome_act" },
+    "chrome_see": { "enabled": true, "name": "chrome_see" },
+    "chrome_tab": { "enabled": true, "name": "chrome_tab" },
+    "chrome_vision": { "enabled": true, "name": "chrome_vision" },
+    "chrome_cdp": { "enabled": true, "name": "chrome_cdp" }
+  },
+
+  // Override the built-in prompts per tool. "" clears description or promptSnippet; [] adds no rules
+  "guidance": {
+    "chrome_act": {
+      "description": "Drive the user's real browser.",
+      "promptSnippet": "Drive the browser",
+      "promptGuidelines": ["chrome_act: pass see: refs on navigate."]
+    }
+  }
+}
+```
+
+Every key is optional. `src/config/schema.ts` holds the ranges and the defaults.
+
+## Docs
+
+| Document | Content |
+|---|---|
+| [ARCHITECTURE](docs/ARCHITECTURE.md) | Module boundaries and seams; read it before changing the structure |
+| [GLOSSARY](docs/GLOSSARY.md) | One name per concept |
+| [Modules](docs/modules/) | Trade-offs and traps per module |
+| [Decisions](docs/decisions/) | Why the shape is what it is |
+
+## Development
+
+From the repository root:
+
+```bash
+pnpm -C packages/pi-browser-use-lite lint
+pnpm -C packages/pi-browser-use-lite check:imports
+pnpm -C packages/pi-browser-use-lite typecheck
+pnpm -C packages/pi-browser-use-lite test
+```
+
+The end-to-end test drives a real browser. Load the extension from `packages/pi-browser-use-lite/browser-extension`, keep one Chromium browser open with that extension enabled, then run:
+
+```bash
+pnpm -C packages/pi-browser-use-lite test:e2e
+```
+
+Close every other browser that has this extension. Two copies poll the same bridge, and the commands go to whichever copy asks first.
+
+The extension reloads itself when the bridge reports a different version. After editing extension code without a version bump, reload it by hand on the extensions page.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/browser-extension/background/capture.js

@@ -0,0 +1,267 @@
+/**
+ * 日志捕获：用 CDP 事件流记 console 与 network，按标签存一份。
+ * 缓冲区在后台而不是页面里，所以同一标签再导航一次也不会丢。
+ */
+
+import { attach, sendCommand } from "./input/debugger.js";
+import { trackedTabIds } from "./target.js";
+
+const KEY_PREFIX = "capture.logs.";
+const CONSOLE_LIMIT = 500;
+const NETWORK_LIMIT = 1_000;
+const BODY_LIMIT = 200_000;
+
+/** tabId → { console, network, starts, capturing, offReason } */
+const buffers = new Map();
+/** 正在从存储里读的缓冲区。两个调用同时到时共用同一次读，不各建一份。 */
+const pending = new Map();
+let subscribed = false;
+
+subscribe();
+
+/** 事件监听在模块加载时注册，service worker 才会被它们唤醒。 */
+function subscribe() {
+	const debuggerApi = globalThis.chrome?.debugger;
+	if (subscribed || debuggerApi === undefined) return;
+	subscribed = true;
+	debuggerApi.onEvent.addListener(onEvent);
+	debuggerApi.onDetach.addListener(onDetach);
+}
+
+/**
+ * 在这个标签上开抓。已经开着就只补一次 attach，不重复开域。
+ * 挂不上调试器时只记一句说明，不挡动作。
+ * @param {number} tabId 标签 id
+ * @returns {Promise<void>}
+ */
+export async function startCapture(tabId) {
+	subscribe();
+	const buffer = await bufferOf(tabId);
+	buffer.offReason = undefined;
+	try {
+		await attach(tabId);
+		if (buffer.capturing !== true) {
+			await sendCommand(tabId, "Runtime.enable");
+			await sendCommand(tabId, "Network.enable");
+			buffer.capturing = true;
+		}
+	} catch (error) {
+		buffer.capturing = false;
+		buffer.offReason = `capture is off for this tab: ${messageOf(error)}`;
+	}
+	await save(tabId, buffer);
+}
+
+/**
+ * `chrome.webNavigation.onCommitted` 的处理。只抓本会话台账里的标签。
+ * @param {{ tabId?: number, frameId?: number }} details 导航详情
+ * @returns {Promise<void>}
+ */
+export async function onCommitted({ tabId, frameId } = {}) {
+	if (frameId !== 0 || !Number.isInteger(tabId)) return;
+	if (!(await trackedTabIds()).has(tabId)) return;
+	await startCapture(tabId);
+}
+
+/**
+ * 读 console 条目，最旧的在前。
+ * @param {number} tabId 标签 id
+ * @param {{ clear?: boolean }} [options] `clear` 读完清空
+ * @returns {Promise<{ records: object[], note?: string }>} 条目与说明
+ */
+export async function listConsole(tabId, { clear = false } = {}) {
+	const buffer = await bufferOf(tabId);
+	const records = buffer.console.slice();
+	if (clear) {
+		buffer.console.length = 0;
+		await save(tabId, buffer);
+	}
+	return withNote(records, buffer.offReason);
+}
+
+/**
+ * 读网络请求，最早的在前。
+ * @param {number} tabId 标签 id
+ * @param {{ clear?: boolean }} [options] `clear` 读完清空
+ * @returns {Promise<{ records: object[], note?: string }>} 请求与说明
+ */
+export async function listNetwork(tabId, { clear = false } = {}) {
+	const buffer = await bufferOf(tabId);
+	const records = buffer.network.map((record) => ({ ...record }));
+	if (clear) {
+		buffer.network.length = 0;
+		await save(tabId, buffer);
+	}
+	return withNote(records, buffer.offReason);
+}
+
+/**
+ * 单条请求的详情，顺带取回响应体。
+ * @param {number} tabId 标签 id
+ * @param {string} requestId 请求 id
+ * @returns {Promise<object>} 请求记录
+ */
+export async function networkRequest(tabId, requestId) {
+	const buffer = await bufferOf(tabId);
+	const record = buffer.network.find((entry) => entry.id === requestId);
+	if (record === undefined)
+		throw new Error(`bad_args: no request with id ${requestId}`);
+
+	const detail = { ...record };
+	try {
+		const body = await sendCommand(tabId, "Network.getResponseBody", {
+			requestId,
+		});
+		if (body?.base64Encoded === true)
+			detail.responseBodyNote = "the response body is binary";
+		else if (typeof body?.body === "string")
+			detail.responseBody = clipBody(body.body);
+	} catch (error) {
+		detail.responseBodyNote = `could not read the response body: ${messageOf(error)}`;
+	}
+	return detail;
+}
+
+function onEvent(source, method, params = {}) {
+	void handleEvent(source, method, params);
+}
+
+/// 调试器事件可能在 startCapture 之前到（service worker 刚醒来），所以先按标签建缓冲区。
+async function handleEvent(source, method, params) {
+	const tabId = source?.tabId;
+	if (!Number.isInteger(tabId)) return;
+	const buffer = await bufferOf(tabId);
+	if (buffer.offReason !== undefined) return;
+	if (method === "Runtime.consoleAPICalled") pushConsole(buffer, params);
+	else if (method === "Network.requestWillBeSent") pushRequest(buffer, params);
+	else if (method === "Network.responseReceived") markStatus(buffer, params);
+	else if (method === "Network.loadingFinished") markDuration(buffer, params);
+	else return;
+	await save(tabId, buffer);
+}
+
+function onDetach(source, reason) {
+	const buffer = buffers.get(source?.tabId);
+	if (buffer === undefined) return;
+	buffer.capturing = false;
+	buffer.offReason = `capture is off for this tab: ${reason}`;
+}
+
+function pushConsole(buffer, { type, args = [], timestamp }) {
+	buffer.console.push({
+		level: levelOf(type),
+		text: args.map(textOf).join(" "),
+		time: Math.round(timestamp ?? Date.now()),
+	});
+	if (buffer.console.length > CONSOLE_LIMIT)
+		buffer.console.splice(0, buffer.console.length - CONSOLE_LIMIT);
+}
+
+function pushRequest(buffer, { requestId, request = {}, timestamp }) {
+	const record = {
+		id: requestId,
+		method: request.method ?? "GET",
+		url: request.url ?? "",
+		status: undefined,
+		durationMs: undefined,
+	};
+	if (typeof request.postData === "string") {
+		record.requestBody = clipBody(request.postData);
+		if (record.requestBody !== request.postData)
+			record.requestBodyTruncated = true;
+	}
+	buffer.starts.set(requestId, timestamp);
+	buffer.network.push(record);
+	if (buffer.network.length > NETWORK_LIMIT)
+		buffer.network.splice(0, buffer.network.length - NETWORK_LIMIT);
+}
+
+function markStatus(buffer, { requestId, response = {} }) {
+	const record = buffer.network.find((entry) => entry.id === requestId);
+	if (record !== undefined) record.status = response.status;
+}
+
+function markDuration(buffer, { requestId, timestamp }) {
+	const record = buffer.network.find((entry) => entry.id === requestId);
+	const startedAt = buffer.starts.get(requestId);
+	if (record === undefined || startedAt === undefined) return;
+	record.durationMs = Math.round((timestamp - startedAt) * 1000);
+}
+
+async function bufferOf(tabId) {
+	const existing = buffers.get(tabId);
+	if (existing !== undefined) return existing;
+	let loading = pending.get(tabId);
+	if (loading === undefined) {
+		const key = KEY_PREFIX + tabId;
+		loading = chrome.storage.session.get(key).then((stored) => {
+			const saved = stored?.[key] ?? {};
+			return {
+				console: saved.console ?? [],
+				network: saved.network ?? [],
+				starts: new Map(Object.entries(saved.starts ?? {})),
+				capturing: saved.capturing === true,
+				offReason: saved.offReason,
+			};
+		});
+		pending.set(tabId, loading);
+	}
+	const buffer = await loading;
+	buffers.set(tabId, buffer);
+	pending.delete(tabId);
+	return buffer;
+}
+
+async function save(tabId, buffer) {
+	await chrome.storage.session.set({
+		[KEY_PREFIX + tabId]: {
+			console: buffer.console,
+			network: buffer.network,
+			starts: Object.fromEntries(buffer.starts),
+			capturing: buffer.capturing,
+			offReason: buffer.offReason,
+		},
+	});
+}
+
+function withNote(records, offReason) {
+	return offReason === undefined ? { records } : { records, note: offReason };
+}
+
+function levelOf(type) {
+	if (type === "warning") return "warn";
+	if (type === "error" || type === "assert") return "error";
+	if (type === "debug" || type === "trace") return "debug";
+	if (type === "info") return "info";
+	return "log";
+}
+
+function textOf(arg) {
+	if (arg?.value !== undefined) return String(arg.value);
+	if (typeof arg?.description === "string") return arg.description;
+	return String(arg?.type ?? "");
+}
+
+/** 按上限切请求体。说明占的字符也算在上限内，丢掉的数量与实际切掉的一致。 */
+function clipBody(text) {
+	if (text.length <= BODY_LIMIT) return text;
+	let kept = BODY_LIMIT;
+	let dropped = text.length - kept;
+	// 说明里的数字位数会改变说明本身的长度，迭代到不再变为止。
+	for (;;) {
+		const next = BODY_LIMIT - bodyNote(dropped).length;
+		const nextDropped = text.length - next;
+		if (next === kept) break;
+		kept = next;
+		dropped = nextDropped;
+	}
+	return text.slice(0, kept) + bodyNote(dropped);
+}
+
+function bodyNote(dropped) {
+	return `\n[truncated ${dropped} chars]`;
+}
+
+function messageOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}

package/browser-extension/background/dispatch.js

@@ -0,0 +1,231 @@
+/**
+ * 动作路由表：动作名 → 处理函数。键与 src/protocol 的 `ACTION_NAMES` 一致。
+ *
+ * 用 Map 而不是对象：动作名来自命令，对象查表会命中原型链上的名字（`toString` 等）。
+ * target 解析在 dispatch 里统一做一步，不散进每个处理函数。
+ */
+
+import {
+	listConsole,
+	listNetwork,
+	networkRequest,
+	startCapture,
+} from "./capture.js";
+import { sendCommand } from "./input/debugger.js";
+import { fill, press, type as typeText } from "./input/keyboard.js";
+import { click, drag, hover, scroll } from "./input/pointer.js";
+import { upload } from "./input/upload.js";
+import { evaluatePage } from "./page/evaluate.js";
+import { screenshotPage } from "./page/screenshot.js";
+import {
+	changesSince,
+	elementAt,
+	markBaseline,
+	snapshotPage,
+} from "./page/snapshot.js";
+import { waitFor } from "./page/waitFor.js";
+import { activateTab, closeTab, listTabs, navigateTab } from "./tabs.js";
+import { cleanupAutomation, createTarget, targetFor } from "./target.js";
+
+/** 需要一个标签 id 的动作。其余动作自己从 params 取会话信息。 */
+const TAB_ACTIONS = new Set([
+	"page.navigate",
+	"page.snapshot",
+	"page.inspect",
+	"page.evaluate",
+	"page.click",
+	"page.hover",
+	"page.drag",
+	"page.upload",
+	"page.type",
+	"page.fill",
+	"page.key",
+	"page.scroll",
+	"page.screenshot",
+	"page.waitFor",
+	"page.console.list",
+	"page.network.list",
+	"page.network.get",
+	"cdp.call",
+]);
+
+/** 结果要带变更量的动作。悬停不在里面：鼠标经过不改 DOM，拍两次快照只会白花时间。 */
+const CHANGED_ACTIONS = new Set([
+	"page.click",
+	"page.type",
+	"page.fill",
+	"page.key",
+	"page.drag",
+	"page.upload",
+	"page.scroll",
+]);
+
+export const routes = new Map([
+	[
+		"tab.version",
+		() => ({ extensionVersion: chrome.runtime.getManifest().version }),
+	],
+	[
+		"tab.list",
+		async ({ sessionKey } = {}) => ({ tabs: await listTabs({ sessionKey }) }),
+	],
+	[
+		"tab.new",
+		async ({ sessionKey, url, background } = {}) => ({
+			id: await createTarget({ sessionKey, url, background }),
+		}),
+	],
+	[
+		"tab.activate",
+		({ tabId, background } = {}) => activateTab({ tabId, background }),
+	],
+	["tab.close", ({ tabId } = {}) => closeTab({ tabId })],
+	[
+		"page.navigate",
+		({ tabId, url, initScript, timeoutMs } = {}) =>
+			navigateTab({ tabId, url, initScript, timeoutMs }),
+	],
+	[
+		"page.snapshot",
+		({ tabId, mode, query, ref, selector, maxElements, textChars } = {}) =>
+			snapshotPage({
+				tabId,
+				mode,
+				query,
+				ref,
+				selector,
+				maxElements,
+				textChars,
+			}),
+	],
+	[
+		"page.inspect",
+		({ tabId, ref, selector } = {}) => elementAt(tabId, { ref, selector }),
+	],
+	["page.evaluate", ({ tabId, js } = {}) => evaluatePage({ tabId, js })],
+	["page.click", async (params) => click(await atPoint(params))],
+	["page.hover", async (params) => hover(await atPoint(params))],
+	[
+		"page.drag",
+		async ({ tabId, from, to, steps } = {}) =>
+			drag({
+				tabId,
+				from: await locator(tabId, from),
+				to: await locator(tabId, to),
+				steps,
+			}),
+	],
+	[
+		"page.upload",
+		({ tabId, paths, timeoutMs } = {}) => upload({ tabId, paths, timeoutMs }),
+	],
+	[
+		"page.type",
+		async ({ tabId, text, replace, press: key } = {}) => {
+			const typed = await typeText({ tabId, text, replace });
+			if (key === undefined) return typed;
+			await press({ tabId, key });
+			return typed;
+		},
+	],
+	["page.fill", ({ tabId, fields } = {}) => fill({ tabId, fields })],
+	["page.key", ({ tabId, key } = {}) => press({ tabId, key })],
+	[
+		"page.scroll",
+		({ tabId, dx, dy, steps } = {}) => scroll({ tabId, dx, dy, steps }),
+	],
+	[
+		"page.screenshot",
+		({ tabId, format, fullPage } = {}) =>
+			screenshotPage({ tabId, format, fullPage }),
+	],
+	[
+		"page.console.list",
+		({ tabId, clear } = {}) => listConsole(tabId, { clear: clear === true }),
+	],
+	[
+		"page.network.list",
+		({ tabId, clear } = {}) => listNetwork(tabId, { clear: clear === true }),
+	],
+	[
+		"page.network.get",
+		({ tabId, requestId } = {}) => networkRequest(tabId, requestId),
+	],
+	[
+		"page.waitFor",
+		({ tabId, kind, value, timeoutMs } = {}) =>
+			waitFor({ tabId, kind, value, timeoutMs }),
+	],
+	[
+		"cdp.call",
+		async ({ tabId, method, params } = {}) => ({
+			result: await sendCommand(tabId, method, params),
+		}),
+	],
+	[
+		"automation.cleanup",
+		({ sessionKey, closeOwnTabs } = {}) =>
+			cleanupAutomation({ sessionKey, closeOwnTabs }),
+	],
+]);
+
+/**
+ * 路由一条命令。
+ * 动作名不在表里抛 `Unknown action: …`；在表里但实现没接抛 `… is not wired yet`。
+ * 需要标签 id 的动作先取 target 并开日志抓取，改元素的动作前后各拍一次快照比出变更量。
+ * @param {string} action 动作名
+ * @param {Record<string, unknown>} [params] 动作参数
+ * @returns {Promise<unknown>} 动作的结果
+ */
+export async function dispatch(action, params = {}) {
+	if (!routes.has(action)) throw new Error(`Unknown action: ${action}`);
+	const route = routes.get(action);
+	if (route === undefined) throw new Error(`${action} is not wired yet`);
+	if (!TAB_ACTIONS.has(action)) return await route(params);
+
+	const tabId = await tabIdOf(action, params);
+	await startCapture(tabId);
+	const withTab = { ...params, tabId };
+	if (!CHANGED_ACTIONS.has(action)) return await route(withTab);
+	await markBaseline(tabId);
+	const result = await route(withTab);
+	return { ...result, changed: await changesSince(tabId) };
+}
+
+/** 点名的标签 id 不合法就报错：退回会话 target 会作用到别的标签上。 */
+function requireTabId(tabId) {
+	if (!Number.isInteger(tabId))
+		throw new Error(`bad_args: tabId must be an integer, got ${tabId}`);
+	return tabId;
+}
+
+/**
+ * 命令作用的标签：调用方点了标签就用它，否则用本会话的自动化 target。
+ * @returns {Promise<number>} 标签 id
+ */
+async function tabIdOf(action, params) {
+	if (params.tabId !== undefined) return requireTabId(params.tabId);
+	return targetFor({
+		sessionKey: params.sessionKey,
+		action,
+		background: true,
+	});
+}
+
+/** 指针层的入参：ref 换成元素中心的视口坐标，其余原样。 */
+async function atPoint({ tabId, ...target }) {
+	return { tabId, ...(await locator(tabId, target)) };
+}
+
+/**
+ * 指针层认 selector 或坐标，ref 由快照解析成坐标。
+ * @returns {Promise<{ selector?: string, x?: number, y?: number }>} 定位
+ */
+async function locator(tabId, target = {}) {
+	const { ref, selector, x, y } = target;
+	if (typeof ref !== "string" || ref === "") return { selector, x, y };
+	const { element } = await elementAt(tabId, { ref });
+	const rect = element?.rect;
+	if (!rect) throw new Error(`page_error: ref ${ref} is not on the page`);
+	return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+}