berry-agent 0.1.0-alpha.1

package/dist/browser/install.js

@@ -0,0 +1,342 @@
+/**
+ * 引擎下载件（03 §10.3 引擎发现序条——`/browser install` 的下载原语）。
+ *
+ * - **下载原语不进模型工具面**（spec 明裁）：显式命令（TUI/CLI）专用，
+ *   模型不可触发 150MB 级下载。
+ * - **域白名单钉 Chromium for Testing 官方两域**：元数据
+ *   googlechromelabs.github.io + 工件 storage.googleapis.com——元数据给出
+ *   的下载 URL 同样过白名单（元数据被改也出不了白名单域）。
+ * - **流式落盘 + 摘要账本 TOFU 锚定**：首装计算 zip sha256 锚进
+ *   `dataDir/browser/engine/ledger.json`；同版本重装摘要不符即拒执行
+ *   （BROWSER_DIGEST_MISMATCH——fail-loud 不动盘）。
+ * - **手写 unzip 零新增依赖**：EOCD 反扫 → 中央目录遍历 → 本地头跳位 →
+ *   store/deflate 两法解压（zlib.inflateRawSync）；zip-slip 防御（拒绝
+ *   `..` 与绝对路径条目）+ unix 属性行 chmod（可执行位——macOS app 内
+ *   helper 二进制族需要）。
+ * - 平台映射 v1 收三席：mac-arm64 / mac-x64 / linux64（win32 与其余
+ *   诚实缺席——同发现序 win32 知名位缺席同律，指路显式 executablePath）。
+ */
+import { createHash } from 'node:crypto';
+import { inflateRawSync } from 'node:zlib';
+import { BaseError } from '../contracts/index.js';
+/* ---------------- 常量（域白名单与元数据单源） ---------------- */
+/** CfT「最后已知良好版本」元数据（Stable 通道 + 全平台下载位） */
+export const BROWSER_METADATA_URL = 'https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json';
+/** 下载域白名单（元数据域 + 工件域——两域之外一律拒） */
+export const BROWSER_DOWNLOAD_HOSTS = ['googlechromelabs.github.io', 'storage.googleapis.com'];
+/** 引擎安装根（数据目录下——发现序第③步消费） */
+export const BROWSER_ENGINE_DIRNAME = 'engine';
+/** 摘要账本文件名（发现序③与 TOFU 锚定共用） */
+export const BROWSER_LEDGER_NAME = 'ledger.json';
+/** zip 体积帽（1.5GiB——防元数据被改指向巨型载荷的 sanity 防线） */
+export const BROWSER_ZIP_MAX_BYTES = 1.5 * 1024 * 1024 * 1024;
+/* ---------------- 平台映射 ---------------- */
+/** 平台 + 架构 → CfT 工件名（v1 三席；缺席 = 平台不支持显式下载） */
+export function platformArtifact(platform, arch) {
+    if (platform === 'darwin') {
+        if (arch === 'arm64')
+            return 'mac-arm64';
+        if (arch === 'x64')
+            return 'mac-x64';
+        return undefined;
+    }
+    if (platform === 'linux' && arch === 'x64')
+        return 'linux64';
+    return undefined; // win32/其余：v1 诚实缺席（发现序同律——指路显式 executablePath）
+}
+/** 工件名 → zip 根目录内可执行相对位 */
+function executableRelOf(artifact) {
+    if (artifact === 'linux64')
+        return 'chrome-linux64/chrome';
+    // macOS：app bundle 内主二进制（CfT 命名「Google Chrome for Testing」）
+    return `chrome-${artifact}/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing`;
+}
+/* ---------------- 下载面（生产适配） ---------------- */
+/** 生产下载面（Node ≥22 全局 fetch——web 流转异步迭代） */
+export function defaultDownloadFace() {
+    return {
+        async fetchBinary(url) {
+            const res = await fetch(url);
+            if (res.body === null) {
+                // 无体应答（3xx 等）：空流形——状态码由调用方执法
+                return { status: res.status, bytes: (async function* () { })() };
+            }
+            const body = res.body;
+            return {
+                status: res.status,
+                // web ReadableStream 在 Node ≥22 可异步迭代（for await 直读）
+                bytes: (async function* () {
+                    for await (const chunk of body)
+                        yield chunk;
+                })(),
+            };
+        },
+    };
+}
+/** EOCD 签名与最小长（含注释最大反扫窗 64KiB + 22） */
+const EOCD_SIG = 0x06054b50;
+const EOCD_MIN = 22;
+const EOCD_SCAN = 65_557;
+const CD_SIG = 0x02014b50;
+const LFH_SIG = 0x04034b50;
+/** 小端读（Buffer.readUInt32LE 的直写形——偏移自校验由调用方保证） */
+const u16 = (b, o) => b.readUInt16LE(o);
+const u32 = (b, o) => b.readUInt32LE(o);
+/** 解析 EOCD → {中央目录偏移, 条目数}（ZIP64 形 v1 诚实不支持） */
+function parseEocd(zip) {
+    const scanStart = Math.max(0, zip.length - EOCD_SCAN);
+    for (let i = zip.length - EOCD_MIN; i >= scanStart; i--) {
+        if (u32(zip, i) !== EOCD_SIG)
+            continue;
+        const entryCount = u16(zip, i + 10);
+        const cdOffset = u32(zip, i + 16);
+        // 多卷/ZIP64 形拒收：盘号/目录盘非零，或条目数与目录偏移触 0xFFFF/
+        // 0xFFFFFFFF 上界标记（EOCD 布局——尾字段注释长是 u16，勿读 u32 越界）
+        if (u16(zip, i + 4) !== 0 || u16(zip, i + 6) !== 0 || entryCount === 0xffff || cdOffset === 0xffffffff) {
+            throw new Error('引擎 zip 含多卷/ZIP64 形——v1 不支持（Chromium for Testing 工件不应出现此形）');
+        }
+        return { cdOffset, entryCount };
+    }
+    throw new Error('引擎 zip 缺 EOCD（非 zip 形或截断）');
+}
+/** 遍历中央目录（条目子集抽取；签名不符即拒——坏形不猜） */
+function readCentralDirectory(zip) {
+    const { cdOffset, entryCount } = parseEocd(zip);
+    const entries = [];
+    let off = cdOffset;
+    for (let i = 0; i < entryCount; i++) {
+        if (off + 46 > zip.length || u32(zip, off) !== CD_SIG) {
+            throw new Error(`引擎 zip 中央目录坏形（第 ${i + 1} 条签名不符）`);
+        }
+        const method = u16(zip, off + 10);
+        const compressedSize = u32(zip, off + 20);
+        const nameLen = u16(zip, off + 28);
+        const extraLen = u16(zip, off + 30);
+        const commentLen = u16(zip, off + 32);
+        const externalAttrs = u32(zip, off + 38);
+        const localHeaderOffset = u32(zip, off + 42);
+        const name = zip.subarray(off + 46, off + 46 + nameLen).toString('utf8');
+        entries.push({ name, method, compressedSize, externalAttrs, localHeaderOffset });
+        off += 46 + nameLen + extraLen + commentLen;
+    }
+    return entries;
+}
+/** zip-slip 防御：条目名须为相对净形（拒 `..` 段与绝对形） */
+function safeEntryName(name) {
+    if (name.startsWith('/') || name.includes('\\')) {
+        throw new Error(`zip-slip 防御拒绝条目：${JSON.stringify(name)}（绝对形/反斜杠）`);
+    }
+    for (const seg of name.split('/')) {
+        if (seg === '..')
+            throw new Error(`zip-slip 防御拒绝条目：${JSON.stringify(name)}（.. 段）`);
+    }
+    return name;
+}
+/** 解压单条目（本地头跳位 → store/deflate → Buffer） */
+function extractEntry(zip, entry) {
+    const off = entry.localHeaderOffset;
+    if (off + 30 > zip.length || u32(zip, off) !== LFH_SIG) {
+        throw new Error(`引擎 zip 本地头坏形：${entry.name}`);
+    }
+    const nameLen = u16(zip, off + 26);
+    const extraLen = u16(zip, off + 28);
+    const dataStart = off + 30 + nameLen + extraLen;
+    const raw = zip.subarray(dataStart, dataStart + entry.compressedSize);
+    if (entry.method === 0)
+        return Buffer.from(raw); // store
+    if (entry.method === 8)
+        return inflateRawSync(raw); // deflate（raw 形）
+    throw new Error(`引擎 zip 条目用不支持压缩法 ${entry.method}：${entry.name}`);
+}
+/**
+ * 解压引擎 zip 到目标目录（手写最小 unzip——零依赖条款）。
+ * @returns 解出的文件条目数（目录条目不计）
+ */
+export async function unzipTo(zip, destDir, fs) {
+    let files = 0;
+    for (const entry of readCentralDirectory(zip)) {
+        const name = safeEntryName(entry.name);
+        const target = `${destDir}/${name}`;
+        if (name.endsWith('/')) {
+            await fs.mkdir(target, { recursive: true });
+            continue;
+        }
+        // 父目录链先建（中央目录目录条目不保证先行）
+        const parent = name.lastIndexOf('/') === -1 ? destDir : `${destDir}/${name.slice(0, name.lastIndexOf('/'))}`;
+        await fs.mkdir(parent, { recursive: true });
+        await fs.writeFile(target, extractEntry(zip, entry));
+        files += 1;
+        // unix 属性行 chmod（高 16 位 mode；常规文件位在场才算——可执行位保
+        // macOS app 内 helper 二进制族）。chmod 面缺席静默跳过（窄面可选）。
+        const attrs = entry.externalAttrs >>> 16;
+        const mode = attrs & 0o7777;
+        if (mode !== 0 && (attrs & 0o170000) === 0o100000) {
+            await fs.chmod?.(target, mode);
+        }
+    }
+    return files;
+}
+/* ---------------- 安装主流程 ---------------- */
+/** URL → 域（形态防御：非 http(s) 直拒） */
+function hostOf(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+            return '';
+        return parsed.host;
+    }
+    catch {
+        return '';
+    }
+}
+/** 读既有账本（缺席/坏形 → undefined——坏账本当未装过，重锚 TOFU） */
+async function readLedger(fs, path) {
+    try {
+        const raw = await fs.readFile(path, 'utf8');
+        const v = JSON.parse(raw);
+        if (typeof v.version === 'string' &&
+            typeof v.zipSha256 === 'string' &&
+            typeof v.executableRel === 'string' &&
+            v.version !== '' &&
+            v.zipSha256 !== '' &&
+            v.executableRel !== '') {
+            return {
+                version: v.version,
+                zipSha256: v.zipSha256,
+                executableRel: v.executableRel,
+                artifact: v.artifact ?? '',
+                installedAt: v.installedAt ?? '',
+                bytes: v.bytes ?? 0,
+            };
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 元数据 JSON → Stable 版本 + 本平台工件 URL（白名单外 URL 响亮拒） */
+function artifactUrlFromMetadata(raw, artifact) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('CfT 元数据非 JSON——上游形变或被劫持');
+    }
+    const channels = parsed.channels;
+    const stable = channels?.Stable;
+    const version = stable?.version;
+    const list = stable?.downloads?.chrome;
+    if (typeof version !== 'string' || !Array.isArray(list)) {
+        throw new Error('CfT 元数据缺 Stable.chrome 下载面——上游形变');
+    }
+    for (const item of list) {
+        if (item?.platform === artifact && typeof item.url === 'string') {
+            return { version, url: item.url };
+        }
+    }
+    throw new Error(`CfT 元数据无 ${artifact} 工件——平台工件缺席`);
+}
+/**
+ * 安装引擎（显式命令专用原语——/browser install 的执行体）。
+ *
+ * TOFU 语义：首装锚摘要；同版本重装摘要不符 = BROWSER_DIGEST_MISMATCH 拒
+ * 执行（不动盘）；同版本在装且可执行在场 = 幂等零下载。
+ */
+export async function installBrowserEngine(deps) {
+    const artifact = platformArtifact(deps.platform, deps.arch);
+    if (artifact === undefined) {
+        throw new Error(`当前平台（${deps.platform}/${deps.arch}）无 Chromium for Testing 工件——v1 显式下载缺席。` +
+            '替代路径：安装系统 Chrome（发现序②自动发现）或经 config browser.executablePath / BERRY_AGENT_BROWSER_PATH 显式指定');
+    }
+    const engineDir = `${deps.dataDir}/browser/${BROWSER_ENGINE_DIRNAME}`;
+    const ledgerPath = `${engineDir}/${BROWSER_LEDGER_NAME}`;
+    const executableRel = executableRelOf(artifact);
+    // 元数据取（域白名单第一执法位——常量本身钉白名单域）
+    const metadataUrl = deps.metadataUrl ?? BROWSER_METADATA_URL;
+    if (!BROWSER_DOWNLOAD_HOSTS.includes(hostOf(metadataUrl))) {
+        throw new Error(`元数据 URL 域不在白名单：${metadataUrl}`);
+    }
+    const metaRes = await deps.download.fetchBinary(metadataUrl);
+    if (metaRes.status !== 200)
+        throw new Error(`CfT 元数据取失败（HTTP ${metaRes.status}）`);
+    let metaRaw = '';
+    for await (const chunk of metaRes.bytes)
+        metaRaw += Buffer.from(chunk).toString('utf8');
+    const { version, url } = artifactUrlFromMetadata(metaRaw, artifact);
+    // 元数据给出的工件 URL 同过白名单（元数据被改也出不了白名单域）
+    if (!BROWSER_DOWNLOAD_HOSTS.includes(hostOf(url))) {
+        throw new Error(`工件 URL 域不在白名单：${url}（元数据可疑）`);
+    }
+    // TOFU 预检：同版本在装且可执行在场 → 幂等回执（零下载零写盘）
+    const existing = await readLedger(deps.fs, ledgerPath);
+    if (existing !== undefined && existing.version === version) {
+        const installed = `${engineDir}/${existing.executableRel}`;
+        try {
+            if ((await deps.fs.stat(installed)).isFile()) {
+                return {
+                    version,
+                    zipSha256: existing.zipSha256,
+                    executableRel: existing.executableRel,
+                    executablePath: installed,
+                    alreadyInstalled: true,
+                    bytes: 0,
+                };
+            }
+        }
+        catch {
+            // 可执行缺席（文件被删）——落修复安装腿（下载重验摘要）
+        }
+    }
+    // 流式下载 + 增量摘要（帽执法防巨型载荷）
+    const maxBytes = deps.maxZipBytes ?? BROWSER_ZIP_MAX_BYTES;
+    const res = await deps.download.fetchBinary(url);
+    if (res.status !== 200)
+        throw new Error(`引擎工件取失败（HTTP ${res.status}）`);
+    const hash = createHash('sha256');
+    const parts = [];
+    let bytes = 0;
+    for await (const chunk of res.bytes) {
+        const buf = Buffer.from(chunk);
+        bytes += buf.length;
+        if (bytes > maxBytes) {
+            throw new Error(`引擎 zip 超体积帽（> ${maxBytes} 字节）——中止下载`);
+        }
+        hash.update(buf);
+        parts.push(buf);
+    }
+    const zipSha256 = hash.digest('hex');
+    const zip = Buffer.concat(parts);
+    // TOFU 执法：同版本重装摘要不符 = 拒执行（fail-loud 不动盘）
+    if (existing !== undefined && existing.version === version && existing.zipSha256 !== zipSha256) {
+        throw new BaseError('BROWSER_DIGEST_MISMATCH', `同版本重装摘要不符（version ${version}：账本 ${existing.zipSha256} ≠ 实测 ${zipSha256}）——` +
+            'TOFU 锚定拒绝执行；既有安装未动。请核查网络通路或清除账本后重装（后果自担）');
+    }
+    // 落盘：解压 + 可执行位 + 账本
+    await deps.fs.mkdir(engineDir, { recursive: true });
+    const files = await unzipTo(zip, engineDir, deps.fs);
+    const executablePath = `${engineDir}/${executableRel}`;
+    let executableOk = false;
+    try {
+        executableOk = (await deps.fs.stat(executablePath)).isFile();
+    }
+    catch {
+        executableOk = false;
+    }
+    if (!executableOk) {
+        throw new Error(`解压后可执行缺席：${executablePath}（工件形与预期不符）`);
+    }
+    await deps.fs.chmod?.(executablePath, 0o755); // 主二进制显式可执行（属性行之外的双保险）
+    const ledger = {
+        version,
+        zipSha256,
+        executableRel,
+        artifact,
+        installedAt: new Date().toISOString(),
+        bytes,
+    };
+    await deps.fs.writeFile(ledgerPath, JSON.stringify(ledger, null, 2));
+    deps.logger?.info?.(`browser 引擎已安装：Chromium for Testing ${version}（${artifact}，${files} 文件，${bytes} 字节）→ ${executablePath}`);
+    return { version, zipSha256, executableRel, executablePath, alreadyInstalled: false, bytes };
+}

package/dist/browser/page.js

@@ -0,0 +1,321 @@
+/**
+ * 页面上下文件（03 §10.3——per-session BrowserContext 隔离 + 十操作面）。
+ *
+ * 会话层编舞：Target.createBrowserContext（cookies/storage/缓存会话间隔离，
+ * disposeOnDetach 兜底）→ createTarget（about:blank 挂入专属 context）→
+ * attachToTarget（flatten:true 取 sessionId）→ Page/Runtime enable（console
+ * 事件回流面）。事件按 sessionId 分流路由在 cdp 件，本件只筛本会话帧。
+ *
+ * a11y 快照 ref 模型：DOM.getDocument 全树行走采可交互节点，按文档序派
+ * `@eN` 锚——ref 表 per-snapshot（每次快照重建，过期 ref 查表即拒不猜）；
+ * click/type 查表后先 `DOM.scrollIntoViewIfNeeded` 滚入视口（折叠线外静默
+ * 假成功防线）再取盒模型中心点派输入事件。
+ *
+ * 安全卫生（SSRF 红线）：navigate 入口 URL 先经 web 件同一卫生单源预检
+ * （HEAD + consumer 'navigate'——第三消费位同一 execute 同一在飞门）；
+ * BaseError（WEB_ 族拦截）直传 fail-closed，普通网络失败不拦——两载体
+ * 网络面不同源，HEAD 不通不代表浏览器到不了。
+ */
+import { BaseError } from '../contracts/index.js';
+import { BROWSER_CONSOLE_RING_CAP, BROWSER_NAV_TIMEOUT_MS, BROWSER_SCREENSHOT_DIRNAME, BROWSER_SCREENSHOT_KEEP, } from './types.js';
+/** 可交互标签 → a11y 角色词（INPUT 按 type 分叉另判） */
+const INTERACTIVE_ROLES = {
+    A: 'link',
+    BUTTON: 'button',
+    SELECT: 'combobox',
+    TEXTAREA: 'textbox',
+    SUMMARY: 'button',
+    OPTION: 'option',
+};
+/** INPUT type → 角色词（缺席/未知 type 折 textbox） */
+const INPUT_ROLES = {
+    checkbox: 'checkbox',
+    radio: 'radio',
+    submit: 'button',
+    button: 'button',
+    reset: 'button',
+};
+/** 命名键定义（key/code/windowsVirtualKeyCode 三元组——Input.dispatchKeyEvent 派发用） */
+const NAMED_KEYS = {
+    Enter: { code: 'Enter', keyCode: 13, text: '\r' },
+    Tab: { code: 'Tab', keyCode: 9 },
+    Escape: { code: 'Escape', keyCode: 27 },
+    Backspace: { code: 'Backspace', keyCode: 8 },
+    Delete: { code: 'Delete', keyCode: 46 },
+    ArrowUp: { code: 'ArrowUp', keyCode: 38 },
+    ArrowDown: { code: 'ArrowDown', keyCode: 40 },
+    ArrowLeft: { code: 'ArrowLeft', keyCode: 37 },
+    ArrowRight: { code: 'ArrowRight', keyCode: 39 },
+    Home: { code: 'Home', keyCode: 36 },
+    End: { code: 'End', keyCode: 35 },
+    PageUp: { code: 'PageUp', keyCode: 33 },
+    PageDown: { code: 'PageDown', keyCode: 34 },
+    Space: { code: 'Space', keyCode: 32, text: ' ' },
+};
+/** 标签文本截断帽（快照行宽纪律——超长文本截断加省略记号） */
+const LABEL_CAP = 80;
+/** 平铺属性数组取值（DOM attributes = [name, value, name, value, …]） */
+function attrOf(attributes, name) {
+    if (attributes === undefined)
+        return undefined;
+    for (let i = 0; i + 1 < attributes.length; i += 2) {
+        if (attributes[i] === name)
+            return attributes[i + 1];
+    }
+    return undefined;
+}
+/** 子树文本拼合（text 节点 nodeValue 连接——标签面取材） */
+function textOf(node, depth = 0) {
+    if (depth > 24)
+        return ''; // 病态深树防爆栈
+    let out = node.nodeName === '#text' ? (node.nodeValue ?? '') : '';
+    for (const child of node.children ?? [])
+        out += textOf(child, depth + 1);
+    return out;
+}
+/** 标签截断（超帽截断加省略记号） */
+function clampLabel(text) {
+    const t = text.trim().replace(/\s+/g, ' ');
+    return t.length > LABEL_CAP ? `${t.slice(0, LABEL_CAP)}…` : t;
+}
+/**
+ * 组页面上下文（service 专用——不直接挂工具面）。失败即抛（引擎死态
+ * BROWSER_CONNECT_FAILED 由调用方决定降级重试）。
+ */
+export async function createBrowserPage(deps) {
+    const logger = deps.logger;
+    const navTimeoutMs = deps.navTimeoutMs ?? BROWSER_NAV_TIMEOUT_MS;
+    const now = () => deps.clock?.() ?? Date.now();
+    // 会话层编舞：专属 BrowserContext → 目标挂入 → flat 附着 → 域使能
+    const browserContext = (await deps.conn.send('Target.createBrowserContext', { disposeOnDetach: true }));
+    const target = (await deps.conn.send('Target.createTarget', {
+        url: 'about:blank',
+        browserContextId: browserContext.browserContextId,
+    }));
+    const attached = (await deps.conn.send('Target.attachToTarget', { targetId: target.targetId, flatten: true }));
+    const sessionId = attached.sessionId;
+    const send = (method, params, timeoutMs) => deps.conn.send(method, params, { sessionId, ...(timeoutMs !== undefined ? { timeoutMs } : {}) });
+    await send('Page.enable');
+    await send('Runtime.enable');
+    /* ---------------- console 回流（环形缓冲） ---------------- */
+    const ring = [];
+    const pushRing = (entry) => {
+        ring.push(entry);
+        if (ring.length > BROWSER_CONSOLE_RING_CAP)
+            ring.shift();
+    };
+    /** RemoteObject 折串（value 直取，缺席用 description/type 兜底） */
+    const renderArg = (arg) => {
+        const a = arg;
+        if (a?.value !== undefined && a.value !== null) {
+            return typeof a.value === 'string' ? a.value : JSON.stringify(a.value);
+        }
+        return a?.description ?? `<${a?.type ?? 'unknown'}>`;
+    };
+    const unsubscribe = deps.conn.onEvent((event) => {
+        if (event.sessionId !== sessionId)
+            return; // 只筛本会话帧
+        const params = event.params;
+        if (event.method === 'Runtime.consoleAPICalled') {
+            pushRing({
+                kind: 'console',
+                level: params.type ?? 'log',
+                text: (params.args ?? []).map(renderArg).join(' '),
+                timestamp: params.timestamp ?? now(),
+            });
+        }
+        else if (event.method === 'Runtime.exceptionThrown') {
+            const d = params.exceptionDetails;
+            const text = d?.exception?.description ??
+                (d?.exception?.value !== undefined ? renderArg(d.exception) : (d?.text ?? '未知异常'));
+            pushRing({ kind: 'exception', level: 'error', text, timestamp: now() });
+        }
+    });
+    /* ---------------- ref 表（per-snapshot） ---------------- */
+    let refTable = new Map();
+    let snapshotSeq = 0;
+    /** ref 查表（快照过期/幽灵 ref 拒——不猜节点；模型误用面走普通错非码族） */
+    const requireRef = (ref) => {
+        const entry = refTable.get(ref);
+        if (entry === undefined) {
+            throw new Error(`ref ${ref} 不在当前快照（快照过期或未取——先调 snapshot 再用其回执的 @eN 锚）`);
+        }
+        return entry;
+    };
+    /** 滚入视口（折叠线外静默假成功防线——交互前置统一动作） */
+    const scrollIntoView = (backendNodeId) => send('DOM.scrollIntoViewIfNeeded', { backendNodeId });
+    /** 截图序号（同刻多截图不撞名） */
+    let shotSeq = 0;
+    const page = {
+        sessionId,
+        async navigate(url) {
+            // SSRF 卫生预检：web 件同一 execute 第三消费位（同在飞门同卫生件）
+            try {
+                await deps.web.fetch(url, { method: 'HEAD', consumer: 'navigate' });
+            }
+            catch (err) {
+                if (err instanceof BaseError)
+                    throw err; // WEB_ 族拦截——fail-closed 直传
+                logger?.debug?.(`导航预检普通失败（放行浏览器载体）：${err instanceof Error ? err.message : String(err)}`);
+            }
+            const waitLoad = deps.conn.waitEvent('Page.loadEventFired', sessionId, navTimeoutMs);
+            await send('Page.navigate', { url }, navTimeoutMs);
+            await waitLoad;
+            // 终点 URL 从导航史读（服务端重定向落点——不信任请求原值）
+            const hist = (await send('Page.getNavigationHistory'));
+            const entry = hist.entries[hist.currentIndex];
+            return { url: entry?.url ?? url };
+        },
+        async back() {
+            return goHistory(-1);
+        },
+        async forward() {
+            return goHistory(1);
+        },
+        async snapshot() {
+            const doc = (await send('DOM.getDocument', { depth: -1, pierce: true }));
+            const next = new Map();
+            const lines = [];
+            let counter = 0;
+            /** 深度行走：可交互节点派锚（文档序）；病态深树防爆栈 */
+            const walk = (node, depth) => {
+                if (depth > 64)
+                    return;
+                const tag = node.nodeName ?? '';
+                let role;
+                if (tag === 'INPUT') {
+                    const type = attrOf(node.attributes, 'type') ?? 'text';
+                    role = INPUT_ROLES[type] ?? 'textbox';
+                }
+                else {
+                    role = INTERACTIVE_ROLES[tag];
+                }
+                if (role !== undefined && typeof node.backendNodeId === 'number') {
+                    counter += 1;
+                    const ref = `@e${counter}`;
+                    const label = clampLabel(textOf(node) ||
+                        attrOf(node.attributes, 'aria-label') ||
+                        attrOf(node.attributes, 'placeholder') ||
+                        attrOf(node.attributes, 'value') ||
+                        '');
+                    const extra = [];
+                    const href = attrOf(node.attributes, 'href');
+                    if (role === 'link' && href !== undefined)
+                        extra.push(clampLabel(href));
+                    const name = attrOf(node.attributes, 'name');
+                    if (name !== undefined)
+                        extra.push(`name=${clampLabel(name)}`);
+                    lines.push(`- ${role} ${JSON.stringify(label)}${extra.length > 0 ? `（${extra.join(' ')}）` : ''} [ref=${ref}]`);
+                    next.set(ref, { backendNodeId: node.backendNodeId, label });
+                }
+                for (const child of node.children ?? [])
+                    walk(child, depth + 1);
+            };
+            if (doc.root !== undefined)
+                walk(doc.root, 0);
+            refTable = next; // per-snapshot 重建（旧锚全数作废——不混表）
+            snapshotSeq += 1;
+            return [`# 页面快照 ${snapshotSeq}（可交互节点 ${counter} 个——交互用 [ref=@eN] 锚）`, ...lines].join('\n');
+        },
+        async click(ref) {
+            const entry = requireRef(ref);
+            await scrollIntoView(entry.backendNodeId);
+            const box = (await send('DOM.getBoxModel', { backendNodeId: entry.backendNodeId }));
+            const quad = box.model?.content;
+            if (quad === undefined || quad.length < 8) {
+                throw new Error(`ref ${ref}（${entry.label}）取不到盒模型——节点不可见或已离树，重新 snapshot`);
+            }
+            // content 八角（x,y×4）取包围盒中心
+            const xs = [quad[0], quad[2], quad[4], quad[6]];
+            const ys = [quad[1], quad[3], quad[5], quad[7]];
+            const x = (Math.min(...xs) + Math.max(...xs)) / 2;
+            const y = (Math.min(...ys) + Math.max(...ys)) / 2;
+            await send('Input.dispatchMouseEvent', { type: 'mousePressed', x, y, button: 'left', clickCount: 1 });
+            await send('Input.dispatchMouseEvent', { type: 'mouseReleased', x, y, button: 'left', clickCount: 1 });
+        },
+        async type(ref, text) {
+            const entry = requireRef(ref);
+            await scrollIntoView(entry.backendNodeId);
+            await send('DOM.focus', { backendNodeId: entry.backendNodeId });
+            await send('Input.insertText', { text });
+        },
+        async press(key) {
+            if (key.length === 1) {
+                // 单字符：rawKeyDown（key/code 推导，VK 码取大写 ASCII——字母键惯例）→ char（text 面）→ keyUp
+                const vk = key.toUpperCase().charCodeAt(0);
+                const code = key === ' ' ? 'Space' : `Key${key.toUpperCase()}`;
+                await send('Input.dispatchKeyEvent', { type: 'rawKeyDown', key, code, windowsVirtualKeyCode: vk });
+                await send('Input.dispatchKeyEvent', { type: 'char', key, text: key });
+                await send('Input.dispatchKeyEvent', { type: 'keyUp', key, code, windowsVirtualKeyCode: vk });
+                return;
+            }
+            const def = NAMED_KEYS[key];
+            if (def === undefined) {
+                throw new Error(`不支持的按键 ${JSON.stringify(key)}——命名键词表或单字符`); // schema 已收词表——此为防御位
+            }
+            await send('Input.dispatchKeyEvent', {
+                type: 'rawKeyDown',
+                key,
+                code: def.code,
+                windowsVirtualKeyCode: def.keyCode,
+            });
+            if (def.text !== undefined)
+                await send('Input.dispatchKeyEvent', { type: 'char', key, text: def.text });
+            await send('Input.dispatchKeyEvent', { type: 'keyUp', key, code: def.code, windowsVirtualKeyCode: def.keyCode });
+        },
+        async scroll(direction, amountPx) {
+            const metrics = (await send('Page.getLayoutMetrics'));
+            const vp = metrics.cssVisualViewport;
+            const x = (vp?.width ?? 1280) / 2;
+            const y = (vp?.height ?? 720) / 2;
+            // yDistance 正数向下（Chrome 惯例——synthesizeScrollGesture 滚动量）
+            await send('Input.synthesizeScrollGesture', {
+                x,
+                y,
+                yDistance: direction === 'down' ? amountPx : -amountPx,
+                speed: 800,
+            });
+        },
+        async screenshot() {
+            const shot = (await send('Page.captureScreenshot', { format: 'png' }));
+            const data = shot.data ?? '';
+            const bytes = Buffer.byteLength(data, 'base64');
+            const dir = `${deps.dataDir}/browser/${BROWSER_SCREENSHOT_DIRNAME}`;
+            await deps.fs.mkdir(dir, { recursive: true });
+            shotSeq += 1;
+            const path = `${dir}/shot-${now()}-${shotSeq}.png`;
+            await deps.fs.writeFile(path, Buffer.from(data, 'base64'));
+            // 滚动清理：超保留量弃最旧（文件名时序序——字典序即时间序）
+            const names = (await deps.fs.readdir(dir)).filter((n) => n.endsWith('.png')).sort();
+            for (const victim of names.slice(0, Math.max(0, names.length - BROWSER_SCREENSHOT_KEEP))) {
+                await deps.fs.unlink(`${dir}/${victim}`).catch(() => { }); // 清理失败不阻回执
+            }
+            logger?.debug?.(`browser 截图落盘（${bytes} 字节）：${path}`);
+            return { path, bytes };
+        },
+        async consoleLog(limit) {
+            return [...ring].slice(-limit);
+        },
+        async close() {
+            unsubscribe();
+            // 关停幂等吞错：引擎死态 send 快拒 BROWSER_CONNECT_FAILED——页面级
+            // 收口不因引擎已死而炸调用方（引擎级降级归 service）
+            await send('Target.closeTarget', { targetId: target.targetId }).catch(() => { });
+            await deps.conn
+                .send('Target.disposeBrowserContext', { browserContextId: browserContext.browserContextId })
+                .catch(() => { });
+        },
+    };
+    /** 导航史邻步（back/forward 共体——无邻步诚实 moved:false） */
+    async function goHistory(delta) {
+        const hist = (await send('Page.getNavigationHistory'));
+        const next = hist.entries[hist.currentIndex + delta];
+        if (next === undefined)
+            return { moved: false };
+        const waitLoad = deps.conn.waitEvent('Page.loadEventFired', sessionId, navTimeoutMs);
+        await send('Page.navigateToHistoryEntry', { entryId: next.id }, navTimeoutMs);
+        await waitLoad;
+        return { moved: true, url: next.url };
+    }
+    return page;
+}