cdp

Browser / Page / Locator

browser-harness-js 在持久运行的 Node 守护进程中执行 JavaScript。对于连贯的操作，请使用带引号的 heredoc。支持顶层 await；包含多条语句的代码片段需要使用 return。跨调用状态请存储在 globalThis 上；局部 const 绑定不会保留。返回的字符串会直接打印；对象会以 JSON 格式打印。控制台输出会写入守护进程日志，而不是 CLI 响应。

连接与范围

browser-harness-js <<'EOF'
await browser.connect();                 // or { port: 9222 } / { wsUrl: 'ws://…' }
return await browser.tabs();             // inspect; never silently pick tabs[0]
EOF

通过明确的允许列表连接已获授权的目标，或打开一个后台标签页：

globalThis.page = await browser.attach(authorizedTargetId, {
  allowedOrigins: ['https://example.com']
});
// Alternative: browser.open('https://example.com', { allowedOrigins: […] })
return await page.snapshot();

Origin 来自用户／主机的授权，而非不可信的页面内容。必须是 1–32 个精确的 HTTP(S) Origin，不含路径或通配符。页面操作会固定使用某个会话和连接代次；绝不会使用可变的当前活动目标。browser.connect() 不会发送操作系统按键，也不会激活浏览器。

读取、操作、验证

return await page.getByRole('textbox', { name: 'Search' }).fill('browser harness');

return await page.getByRole('button', { name: 'Search' }).click({
  verify: snapshot => snapshot.tree.includes('Search results')
});

每项操作都会精确定位一个目标、检查该目标、重新验证其身份、Origin、时效性和可操作性，然后执行一次操作并读取结果。默认使用可信的 CDP 鼠标／键盘输入。对于受支持但位于屏幕外的目标，会先执行一次受保护的滚动到视图操作，再重新验证，而不会盲目点击坐标。不会自动重试操作，也不会回退到原始输入。

API	含义
page.snapshot(options?)	{id,url,title,tree,diff,truncated,omissions}；引用由内部管理
page.locator('sAb3dEf6hJk9m_2e9')	来自此页面最新快照的打印引用，不是原始后端 ID
page.locator('#search')	主框架中的标准 CSS；必须精确匹配一个可访问元素
page.getByRole('button', {name:'Save'})	默认按精确匹配原生 AX 角色／名称；exact:false 按区分大小写的名称子字符串匹配
getByRole(…, {context:'group: Outbound'})	根据最近的具名非控件祖先消除歧义
locator.click() / .fill(text) / .press(key)	受保护的点击、完整值替换或允许列表中的按键
locator.selectOption(labelOrIndex)	原生 select 中唯一匹配的选项标签或从零开始的索引；不是其 HTML 值
locator.scrollIntoView()	受保护地滚动受支持的目标
page.frames() / page.frame(frameId).snapshot()	查找／读取获准的同进程和跨进程框架
page.goto(url)	在允许列表范围内导航；在截止时间内等待加载，并返回操作回执
page.info() / page.signals()	获取范围内的信息／对话框状态，以及有界、可清空的事件摘要
page.close() / page.dispose()	关闭标签页／释放封装对象及其拥有的连接，但不关闭标签页

fill 和 selectOption 会自动验证最新的控件值。对于点击或按键目标，请提供同步的 verify(snapshot) 谓词，或执行权威回读。结果包含 status、reason、verified（true、false 或 null），通常还包含新的 snapshot；读取失败会显示在 verificationError 中。executed 仅表示已发送操作，不代表任务成功。

• stale：获取新证据并重新评估。
• blocked／Origin 拒绝：停止操作或获取授权；绝不可通过原始 CDP 绕过。
• outcome_unknown：先检查；绝不可自动重放该操作。

页面操作和定位器操作接受 {timeoutMs, signal}。默认截止时间为 10 秒，最长为 60 秒，包含排队时间。调用超时后会停止后续发送，但无法撤回已发送的输入。待处理的传输调用会使其队列保持隔离，直到调用结束。

快照与限制

return await page.snapshot({ interactive: true });
// Or { selector: '#results' }, { ref: 'sAb3dEf6hJk9m_2e9' }, { frameId }, { maxDepth: 4 }

完整快照会保留表、行、单元格之间的关系、值、命名上下文和内容。交互模式会省略读取文本。引用会在下一次快照、原始调用、操作或文档更改时过期。切勿猜测引用、将其解析为后端 ID，或重复使用旧引用。新的 role/CSS 定位器会重新解析。

差异按匹配的快照范围管理，并忽略打印出的引用变动。首次差异会显示完整树；内容未更改时返回 (no changes)。深度限制和省略的框架会明确标出。字符数超限时会抛出错误，而不是返回被静默截断的树。默认限制：50,000 个字符、深度 50、32 个框架。参见 snapshot.md。

快照可读取的内容可能超出操作引擎支持的范围。框架操作、封闭式 shadow root 操作、canvas 和不受支持的自定义组件会直接失败，不会静默改用其他方式。这是定义明确的页面/定位器 API，并不完全兼容 Playwright：没有选择器 DSL、nth-match 回退、自动等待/重试循环，也不支持任意富文本编辑器填充。守卫会排除敏感控件，并对受保护/类似密码的 AX 值进行编辑；这并非 DLP。

有界决策，包括 Jev

globalThis.seen = await page.observe({ maxElements: 64 });
return seen;
// After an authorized decision selects an offered target and operation:
// return await page.act(seen, {targetId: chosenId, operation:'click'}, {verify});

观察结果会提供不透明的一次性句柄、操作、上下文和修订号。快照引用描述所看到的内容；观察句柄仅授权经重新验证的操作。两者不可互换。 page.waitForChange(seen.revision, {waitMs:5000}) 会返回 {changed,observation}；发生变化本身并不能验证目标是否达成。参见 操作契约。

显式原始 CDP

对于已知的确定性机制或不受支持的机制，请使用 page.cdp('Domain.method', params)，并执行等效的权限检查。它会使观察结果失效，且不会强制执行受守卫 API 的来源策略。类型化的 session.Domain.method、cdp(sessionId,method,params)、CDP、 Session、listPageTargets、detectBrowsers、resolveWsUrl 和 ext 仍可供现有原始脚本使用。请勿在并发工作中调用 session.use()；请通过显式会话 ID 进行路由。

操作指南：连接、 生命周期、 信号、 AX 内部机制、 富文本编辑器、 屏幕截图、 录制。录制全局变量仍为 startRecording、stopRecording、recordingStatus；请先征得同意。

更新后，请将 browser-harness-js --version 与 --status 的结果进行核对。 --restart 会重新加载 SDK 文件，但会丢弃守护进程全局变量和附件；请重新连接并重新附加。参见守护进程过期。