拓冰网站定制 
Cate浏览器自动化架构剖析CDP、可访问性树与视觉回退的分层设计原理【免费下载链接】cateAn infinite zoomable canvas for coding. Editor, terminal, and browser panels in a spatial workspace.项目地址: https://gitcode.com/gh_mirrors/cate5/cateCate 是一款“无限缩放画布 编辑器 终端 浏览器”合一的空间化编程工作台其浏览器自动化子系统是它最有趣的部分之一。Cate 的浏览器自动化采用分层设计底层用 CDPChromium DevTools Protocol直连页面中层通过可访问性树Accessibility Tree生成结构化的语义观察上层则保留“截图 坐标”的视觉回退方案兜底。本文带你拆解这套分层架构的设计原理看看它如何让 AI Agent 和用户共享同一个浏览器视口并随时接管控制权。 三层分工为什么不能只用一种方式“看懂”网页浏览器 Agent 通常面临一个难题纯像素截图对表单和按钮不可靠纯 DOM 扫描又看不到“用户真正看见了什么”。Cate 的答案是分层路由官方研究文档 research/browser-agent-architecture.md 明确给出了这个层级模型层级观察与动作适用场景CDP 语义层可访问性树、角色/名称、可信输入事件表单、导航、大部分 UI 操作视觉回退层视口截图 鼠标坐标画布、地图、自定义控件开发检查层DOM、控制台、网络调试专用显式开启整个运行时的核心实现集中在 src/main/browser/ 目录下面逐层来看。 第一层CDP 直连 Electron 调试器Cate 没有引入额外的浏览器驱动而是直接附着在 Electron 的WebContents调试器上。每个浏览器标签页对应一个BrowserTargetRuntime它在初始化时完成 CDP 会话建立调用debugger.attach(1.3)挂载调试协议通过Target.setAutoAttach自动附着跨源 iframe 的子会话保证子框架里的元素同样可操作一次性启用Page、DOM、Runtime、Accessibility四个域。关键代码在 browserRuntime.ts 的attach()方法中。这一层最重要的设计是可信输入所有点击、键盘事件都通过Input.dispatchMouseEvent/Input.dispatchKeyEvent下发而不是往页面里注入合成 DOM 事件见 dispatchInput。合成事件无法通过页面的isTrusted校验而 CDP 输入在页面看来与真人操作无差别。另一个细节是用户抢占机制每当用户真实输入时运行时递增userInputEpochnoteUserInput正在执行的 Agent 操作会在下一步守卫检查中抛出browser-action-preempted-by-user队列保证同一标签页的动作严格串行enqueue。换句话说用户一动手Agent 立刻让路。 第二层可访问性树让 Agent 看见“按钮”而不是像素语义观察的实现是 browserAX.ts 中的readBrowserAX()对每个框架调用Accessibility.getFullAXTree拉取完整可访问性树只保留带backendNodeId且角色为交互式button、textbox、link、checkbox 等见 INTERACTIVE_ROLES的节点用最多 8 个并发工作器在隔离世界中执行可见性探测INSPECT_ELEMENT检查checkVisibility、视口相交、密码框类型输出带缩进层级、名称、状态checked/disabled/focused 等的文本树并给每个元素注册一个稳定的数字 ID。这套设计有几点值得注意密码框值一律打码未知类型按“失败关闭”原则处理绝不泄露受保护的值browserAX.ts视口外元素标记[offscreen]而非隐藏Agent 知道它存在但不在当前视野里数字 ID 是外部引用ID 映射到backendNodeId frameId导航后文档纪元documentEpoch变更旧 ID 自动失效Agent 无法拿“过期的引用”点到另一个元素。观察结果遵循 browserAutomation.ts 中定义的BrowserObservation契约kind: ax | image携带视口、滚动位置、viewport 缩放等元数据。为了让多轮对话不啰嗦运行时支持差分观察相比上一次基线只输出 新增 / - 消失的行observe()基线缓存由 browserObservationCache.ts 管理LRU 淘汰、8 MiB 上限、只保留差分文本而丢弃图片内存占用有硬边界。️ 第三层视觉回退截图加坐标的兜底方案并非所有 UI 都能用可访问性树描述——canvas 画布、地图、自绘控件没有语义信息。这时 Cate 切到视觉模式getScreenshot只返回视口像素不刷新数字元素 IDgetAXStateAndScreenshot则同时刷新两者方法集定义在 BROWSER_OBSERVATION_METHODS截图前会等待两帧requestAnimationFrame确保布局变更真正提交到合成器再调用capturePage并按视口尺寸裁剪captureViewport坐标只在“最新一张截图”上有效point()会校验文档纪元与视口状态一旦视口发生变化就抛出stale-browser-coordinates防止 Agent 用过时截图点到错误位置point()。视觉层的动作包括坐标点击、拖动10 步插值模拟真实拖拽drag 分支、滚轮滚动等。而语义层的点击则严格得多先scrollIntoViewIfNeeded两次采样框坐标确认目标稳定再做 hit-test 检查是否被遮挡clickElement——任何一步不满足都会以明确的错误名失败而不是“点了个寂寞”。️ 观察—行动闭环与沙箱边界分层的最后价值体现在闭环上每个动作都返回新鲜观察。executeBound()执行完动作后立刻重新observe()并把新状态带回给调用方executeBoundAgent 无需盲等后置条件校验setValue写完会读回值比对setChecked会验证勾选状态失败即报postcondition-failed等待是显式的waitFor支持文本、URL 通配、元素状态三类条件waitCondition代码沙箱Agent 通过 browserCodeSession.ts 在一次性、禁网、禁 Node 的隔离窗口里执行cua.*API单个单元格受 100 次调用、16 MB 输出、30 秒期限的硬限制超时即重置会话。这套边界保证了自动化永远“观察视口 → 行动 → 重新观察”用户随时可抢占Agent 永远拿不到过期的世界模型。 核心文件速查模块说明src/main/browser/browserRuntime.tsCDP 会话、动作执行、抢占与串行队列核心src/main/browser/browserAX.ts可访问性树读取与可见性探测src/main/browser/browserObservationCache.ts观察基线 LRU 缓存支撑差分输出src/main/browser/browserCodeSession.tsAgent 代码沙箱与cuaSDK 注入src/shared/browserAutomation.ts观察/动作协议契约与方法集定义research/browser-agent-architecture.md分层架构的完整设计论述总结Cate 浏览器自动化的精髓可以浓缩成一句话语义优先、视觉兜底、协议约束。CDP 提供可信输入与稳定的元素引用可访问性树把网页翻译成 Agent 能推理的结构截图坐标则覆盖语义的盲区而纪元检查、用户抢占和沙箱限额让这套能力始终跑在安全边界之内。如果你想深入研究不妨从BrowserTargetRuntime的attach()与executeBound()两个方法读起整个分层逻辑都会自然浮现出来。【免费下载链接】cateAn infinite zoomable canvas for coding. Editor, terminal, and browser panels in a spatial workspace.项目地址: https://gitcode.com/gh_mirrors/cate5/cate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cate浏览器自动化架构剖析：CDP、可访问性树与视觉回退的分层设计原理
Cate浏览器自动化架构剖析CDP、可访问性树与视觉回退的分层设计原理【免费下载链接】cateAn infinite zoomable canvas for coding. Editor, terminal, and browser panels in a spatial workspace.项目地址: https://gitcode.com/gh_mirrors/cate5/cateCate 是一款“无限缩放画布 编辑器 终端 浏览器”合一的空间化编程工作台其浏览器自动化子系统是它最有趣的部分之一。Cate 的浏览器自动化采用分层设计底层用 CDPChromium DevTools Protocol直连页面中层通过可访问性树Accessibility Tree生成结构化的语义观察上层则保留“截图 坐标”的视觉回退方案兜底。本文带你拆解这套分层架构的设计原理看看它如何让 AI Agent 和用户共享同一个浏览器视口并随时接管控制权。 三层分工为什么不能只用一种方式“看懂”网页浏览器 Agent 通常面临一个难题纯像素截图对表单和按钮不可靠纯 DOM 扫描又看不到“用户真正看见了什么”。Cate 的答案是分层路由官方研究文档 research/browser-agent-architecture.md 明确给出了这个层级模型层级观察与动作适用场景CDP 语义层可访问性树、角色/名称、可信输入事件表单、导航、大部分 UI 操作视觉回退层视口截图 鼠标坐标画布、地图、自定义控件开发检查层DOM、控制台、网络调试专用显式开启整个运行时的核心实现集中在 src/main/browser/ 目录下面逐层来看。 第一层CDP 直连 Electron 调试器Cate 没有引入额外的浏览器驱动而是直接附着在 Electron 的WebContents调试器上。每个浏览器标签页对应一个BrowserTargetRuntime它在初始化时完成 CDP 会话建立调用debugger.attach(1.3)挂载调试协议通过Target.setAutoAttach自动附着跨源 iframe 的子会话保证子框架里的元素同样可操作一次性启用Page、DOM、Runtime、Accessibility四个域。关键代码在 browserRuntime.ts 的attach()方法中。这一层最重要的设计是可信输入所有点击、键盘事件都通过Input.dispatchMouseEvent/Input.dispatchKeyEvent下发而不是往页面里注入合成 DOM 事件见 dispatchInput。合成事件无法通过页面的isTrusted校验而 CDP 输入在页面看来与真人操作无差别。另一个细节是用户抢占机制每当用户真实输入时运行时递增userInputEpochnoteUserInput正在执行的 Agent 操作会在下一步守卫检查中抛出browser-action-preempted-by-user队列保证同一标签页的动作严格串行enqueue。换句话说用户一动手Agent 立刻让路。 第二层可访问性树让 Agent 看见“按钮”而不是像素语义观察的实现是 browserAX.ts 中的readBrowserAX()对每个框架调用Accessibility.getFullAXTree拉取完整可访问性树只保留带backendNodeId且角色为交互式button、textbox、link、checkbox 等见 INTERACTIVE_ROLES的节点用最多 8 个并发工作器在隔离世界中执行可见性探测INSPECT_ELEMENT检查checkVisibility、视口相交、密码框类型输出带缩进层级、名称、状态checked/disabled/focused 等的文本树并给每个元素注册一个稳定的数字 ID。这套设计有几点值得注意密码框值一律打码未知类型按“失败关闭”原则处理绝不泄露受保护的值browserAX.ts视口外元素标记[offscreen]而非隐藏Agent 知道它存在但不在当前视野里数字 ID 是外部引用ID 映射到backendNodeId frameId导航后文档纪元documentEpoch变更旧 ID 自动失效Agent 无法拿“过期的引用”点到另一个元素。观察结果遵循 browserAutomation.ts 中定义的BrowserObservation契约kind: ax | image携带视口、滚动位置、viewport 缩放等元数据。为了让多轮对话不啰嗦运行时支持差分观察相比上一次基线只输出 新增 / - 消失的行observe()基线缓存由 browserObservationCache.ts 管理LRU 淘汰、8 MiB 上限、只保留差分文本而丢弃图片内存占用有硬边界。️ 第三层视觉回退截图加坐标的兜底方案并非所有 UI 都能用可访问性树描述——canvas 画布、地图、自绘控件没有语义信息。这时 Cate 切到视觉模式getScreenshot只返回视口像素不刷新数字元素 IDgetAXStateAndScreenshot则同时刷新两者方法集定义在 BROWSER_OBSERVATION_METHODS截图前会等待两帧requestAnimationFrame确保布局变更真正提交到合成器再调用capturePage并按视口尺寸裁剪captureViewport坐标只在“最新一张截图”上有效point()会校验文档纪元与视口状态一旦视口发生变化就抛出stale-browser-coordinates防止 Agent 用过时截图点到错误位置point()。视觉层的动作包括坐标点击、拖动10 步插值模拟真实拖拽drag 分支、滚轮滚动等。而语义层的点击则严格得多先scrollIntoViewIfNeeded两次采样框坐标确认目标稳定再做 hit-test 检查是否被遮挡clickElement——任何一步不满足都会以明确的错误名失败而不是“点了个寂寞”。️ 观察—行动闭环与沙箱边界分层的最后价值体现在闭环上每个动作都返回新鲜观察。executeBound()执行完动作后立刻重新observe()并把新状态带回给调用方executeBoundAgent 无需盲等后置条件校验setValue写完会读回值比对setChecked会验证勾选状态失败即报postcondition-failed等待是显式的waitFor支持文本、URL 通配、元素状态三类条件waitCondition代码沙箱Agent 通过 browserCodeSession.ts 在一次性、禁网、禁 Node 的隔离窗口里执行cua.*API单个单元格受 100 次调用、16 MB 输出、30 秒期限的硬限制超时即重置会话。这套边界保证了自动化永远“观察视口 → 行动 → 重新观察”用户随时可抢占Agent 永远拿不到过期的世界模型。 核心文件速查模块说明src/main/browser/browserRuntime.tsCDP 会话、动作执行、抢占与串行队列核心src/main/browser/browserAX.ts可访问性树读取与可见性探测src/main/browser/browserObservationCache.ts观察基线 LRU 缓存支撑差分输出src/main/browser/browserCodeSession.tsAgent 代码沙箱与cuaSDK 注入src/shared/browserAutomation.ts观察/动作协议契约与方法集定义research/browser-agent-architecture.md分层架构的完整设计论述总结Cate 浏览器自动化的精髓可以浓缩成一句话语义优先、视觉兜底、协议约束。CDP 提供可信输入与稳定的元素引用可访问性树把网页翻译成 Agent 能推理的结构截图坐标则覆盖语义的盲区而纪元检查、用户抢占和沙箱限额让这套能力始终跑在安全边界之内。如果你想深入研究不妨从BrowserTargetRuntime的attach()与executeBound()两个方法读起整个分层逻辑都会自然浮现出来。【免费下载链接】cateAn infinite zoomable canvas for coding. Editor, terminal, and browser panels in a spatial workspace.项目地址: https://gitcode.com/gh_mirrors/cate5/cate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考