【内置浏览器】【观察协议】实现 AX Tree 剪枝 DOM、稳定 RefMap 与分层快照

[CavinHuang]

关联主问题：#251
依赖：#260

类型

观察协议 / 剪枝 DOM / 元素引用

背景

当前 DOMSnapshot.captureSnapshot 在复杂页面可超过 1 MB，超过 150 KB 后只返回截断提示，Agent 因而失去页面结构。截图和模型猜测 selector 无法替代稳定的结构化观察。

参考实现

参考 agent-browser 的 native snapshot：

• Accessibility.getFullAXTree 作为主体
• DOM 批量扫描补充 cursor:pointer、onclick、tabindex、contenteditable 等 AX Tree 遗漏节点
• 清理 ignored/generic/冗余结构
• iframe 与 Shadow DOM 纳入同一语义树
• 可操作节点映射到 backendDOMNodeId，并生成 @en

锁定方案

• 默认返回完整的紧凑语义树；interactive_only 为可选模式
• RefMap 绑定 sessionId、tabId、snapshotId、navigationGeneration、frameId、backendDOMNodeId、role/name/nth
• Ref 在 BrowserSession 内单调递增且不复用
• backendDOMNodeId 失效时仅允许同 Tab、同导航代次、同 Frame、语义完全一致且候选唯一的安全重绑定
• 真正隐藏元素不进入快照；可滚动到的 offscreen 元素保留并标记
• 大型树完整保留在宿主，模型通过 scope/cursor 分层读取，禁止整体截断
• 动作后根据结果返回完整树、局部变化树或目标最新状态
• annotated screenshot 使用相同 refs；坐标操作绑定 screenshotId 和视口代次

验收标准

• 百度等大型页面不再返回 DOM too large 空提示
• 快照能稳定暴露输入框、按钮、标题、结果链接和控件状态
• iframe/Shadow DOM 中的 ref 可直接用于动作，不要求模型切 Frame
• 旧 ref 永远不会在新快照中指向另一个元素
• scope/cursor 过期时返回 STALE_SNAPSHOT_CURSOR
• 截图滚动、缩放或布局变化后旧坐标返回 STALE_SCREENSHOT

[CavinHuang]

AX Tree 剪枝 DOM 与稳定 RefMap 的首个实现已提交 PR #266：使用 Accessibility.getFullAXTree，支持 interactive_only 与宿主 cursor 分页。该 PR 暂不关闭本问题，DOM 交互属性增强和更细粒度 scope/diff 将继续补齐。

[CavinHuang]

进展（PR #266，提交 7ec6717）：@en 动作已从 role/name/nth 二次查询改为宿主 RefMap 精确解析。Sidecar 发送 ref + snapshotId；桌面运行时按 browserSessionId 读取 backendDOMNodeId，并校验 tabId、navigationGeneration、snapshotId、可见/可用状态及中心点遮挡。旧快照 ref 立即返回 stale_target，不再进入自动等待后模糊重试。Electron 集成已通过精确点击与旧 snapshot 拒绝断言，随后停在另一个开放 PR #270 已修复的既有 WebMCP 归一化问题。iframe/Shadow DOM 补树和 cursor:pointer DOM 补充仍待继续。

[CavinHuang]

补充进展（PR #266）：提交 6e3a408 已把所有可访问 Frame 的 AX Tree 合并到同一快照，AX nodeId 按 frameId 命名空间隔离，RefMap 保存 frameId + backendDOMNodeId，Electron 集成验证跨域 iframe 的 ref 可直接点击。提交 afbe023 又按 agent-browser 的思路，在每个 Frame 隔离世界批量补充 cursor:pointer、onclick、tabindex、contenteditable 节点，去重原生/ARIA 交互节点与继承 pointer 子节点，并验证自定义 div ref 可精确动作。当前主要未完成项缩小为 annotated screenshot 与更细粒度 scope/diff；核心观察和动作链已闭环。

[CavinHuang]

继续补齐观察协议：PR #266 新增 screenshot(annotated=true)，在隔离内存画布中用最新语义快照的同一组 @eN 标注主 Frame 可见元素，不修改页面 DOM；新增 snapshot(scope_ref=@eN)，绑定当前 snapshot_id 并直接切片宿主缓存树，不重新抓 AX Tree、不失效当前 refs，切片后仍支持 cursor。真实 Electron 回归已通过 scope 子树、标注截图及同源 ref 断言；完整套件继续停在 PR #270 对应的既有 WebMCP 归一化用例。