BrowserSkill录制管线解析trace v1→v3协议演进与VOM语义图落地【免费下载链接】BrowserSkillLet AI agents use your real, logged-in browser without interrupting your work. CLI extension for browser automation across any shell-capable AI agent.项目地址: https://gitcode.com/GitHub_Trending/br/BrowserSkillBrowserSkill是一个让 AI 智能体Agent直接驱动你真实、已登录的浏览器完成自动化任务的开源项目由bskCLI、本地守护进程daemon和 Chromium 扩展三部分组成。它的录制管线Recording Pipeline能把真人操作的浏览器行为变成结构化的trace轨迹数据再交给 AI 学习复现。本文带你从零看懂 BrowserSkill 录制管线的核心trace 协议从初代到 v3 的演进以及VOM 语义图如何落地到每一次页面观察中。为什么录制管线值得了解普通脚本录制只关心点了哪个坐标而 BrowserSkill 的录制关心的是语义你点的是哪个按钮、填的是什么字段、页面在操作前后处于什么状态。一次完整的录制由三个 RPC 工具驱动定义见 record.rs工具作用tool.record_start开始录制可指定purpose目的描述、trace_version导出格式省略即 v2传3请求 v3tool.record_stop停止录制并返回完整 tracetool.record_await等待录制完成带超时trace 本身是页面状态 用户步骤两部分状态字典负责描述页面长什么样步骤列表负责描述你做了什么。trace 协议三阶段演进从 pages[] 到 states[]v2 遗留格式只有页面骨架初代逻辑 v2trace 没有顶层version字段页面字典是pages[]每个条目只有id、url、title三件套见 record_v2.rs步骤通过page字段引用页面 ID导航效果用effect.navigated_to单独标记目标元素描述TargetDescriptorV2只有tag、role、name、placeholder等零散属性没有稳定元素引用页面上看到了什么完全没有记录——AI 拿到 trace 后不知道当时的按钮长什么样、在什么位置。v3 格式状态-动作-状态日志Trace v3见 record_v3.rs把页面上下文升级为页面状态一次解决 v2 的三大短板states[]携带完整页面观察正文每个状态除id、url、title外还有body字段内容是前置元信息 VOM 正文 注解的完整观察可带truncated截断标记状态-动作-状态SAS结构每个步骤的公共字段变为idstate动作前状态result.state动作后状态页面怎么变化一目了然不再需要 v2 的effect补丁语义化目标描述TargetDescriptorV3引入稳定元素引用ref如e21加role、name、ctx上下文找不到匹配元素时显式标记unmatched: true。v3 还新增了switch_tab步骤、导航成因枚举user_typed/link/form_submit等 7 种NavigationCause、fill提交方式enter/suggestion/blur以及密码字段脱敏redacted标记值替换为***。版本如何识别与兼容协议层用联合体RecordedTrace/RecordedStep做分类record.rs有数字version字段→ 判定为 v3且禁止出现pages[]有pages[]无version→ 判定为 v2但禁止出现states[]混合字段直接报错保证新旧格式永远不会互相污染。对应 JSON Schema 也同步维护在 schema/trace_v3.json 与 schema/trace_v2.json方便任何语言做格式校验。VOM 语义图让 AI看懂页面的关键VOMvom 1格式是 v3 trace 状态正文的底层技术独立实现在 packages/vom/ 包中。VOM 解决什么问题浏览器原生可访问性树信息量爆炸直接喂给 AI 又贵又噪。VOM 渲染器render.ts做了几件聪明事只保留有意义的节点跳过generic、none等无语义角色聚焦 19 种交互角色button、textbox、link……与结构角色dialog、table、navigation……分配稳定 ref可交互元素获得e前缀引用trace 步骤里的target.ref正是来自这里形成观察到 → 操作到的闭环敏感值脱敏redactValues开启后表单值渲染为•••与 v3 的redacted步骤标记联动Token 预算控制maxTokens/maxDepth限制输出规模超长值截断到 200 字符视觉去噪过滤 HTML 注释、内联脚本、登录/开始类弱提示等噪声文本。遮挡层感知知道哪些元素点不到layers.ts 实现了遮挡检测一个fixed/absolute/sticky定位元素若覆盖视口 60% 以上或弹窗类元素覆盖 15% 以上就被判定为阻塞层并自动分类为modal模态弹窗或mask不透明蒙层。这意味着 AI 能理解现在有个弹窗盖住了页面底下的按钮暂时不可用而不是盲目点击失败。节点模型定义types.ts同时携带几何信息rect、paintOrder、交互状态inputState、disabled、inert和条件表面hover 后出现的菜单项CondSurface构成一张完整的页面语义图。录制运行时三步组装一条 v3 trace扩展侧的录制核心是 recording-runtime.ts 中的RecordingObservationRuntime每个被录制的标签页拥有独立上下文流程分为三步文档稳定Settle由 settle-controller.ts 等待页面加载与交互平息避免在页面动的瞬间抓取状态观察捕获Captureobservation-session.ts 通过 CDP 采集可访问性语义与 DOM 几何信息交给 VOM 渲染成vom 1正文并注册进全局状态登记表 state-registry.ts生成s1、s2这样的状态 ID轨迹组装Buildtrace-builder-v3.ts 把草稿步骤与前后状态 ID 拼装为TraceV3附带上recorder信息bsk 版本号 VOM 格式版本vom: 1最终经 daemon 回传给 CLI。配套还有步骤缓冲step-buffer.ts、草稿策略draft-policy.ts与 trace 归约器trace-reducer-v3.ts分别负责暂存用户操作、决定草稿步骤何时提交、以及把流式事件归约为合法 trace。关键文件导航 想深入源码这些路径是最快的入口模块路径职责trace 协议定义crates/bsk-protocol/src/tools/v2/v3 结构与版本分类协议 Schemacrates/bsk-protocol/schema/trace.json、trace_v2.json、trace_v3.json等VOM 渲染器packages/vom/src/render.ts、layers.ts、types.ts录制运行时apps/extension/src/lib/recording/状态登记、稳定等待、trace 组装系统架构docs/architecture.mdCLI / daemon / 扩展三端协作总览小结BrowserSkill 录制管线的演进逻辑非常清晰v2 只记录做了什么v3 补齐了当时看到什么。states[]state/result.state引用把轨迹变成严格的状态机日志VOM 语义图则让每次观察都紧凑、可读、可操作——这正是 AI Agent 能把人类演示可靠转化为自动化技能的数据基础。如果你正在做浏览器自动化方向的项目这条语义化 trace 语义图观察的路线非常值得参考。【免费下载链接】BrowserSkillLet AI agents use your real, logged-in browser without interrupting your work. CLI extension for browser automation across any shell-capable AI agent.项目地址: https://gitcode.com/GitHub_Trending/br/BrowserSkill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/21 15:09:33 · 阅读 1.2k BrowserSkill录制管线解析：trace v1→v3协议演进与VOM语义图落地
BrowserSkill录制管线解析trace v1→v3协议演进与VOM语义图落地【免费下载链接】BrowserSkillLet AI agents use your real, logged-in browser without interrupting your work. CLI extension for browser automation across any shell-capable AI agent.项目地址: https://gitcode.com/GitHub_Trending/br/BrowserSkillBrowserSkill是一个让 AI 智能体Agent直接驱动你真实、已登录的浏览器完成自动化任务的开源项目由bskCLI、本地守护进程daemon和 Chromium 扩展三部分组成。它的录制管线Recording Pipeline能把真人操作的浏览器行为变成结构化的trace轨迹数据再交给 AI 学习复现。本文带你从零看懂 BrowserSkill 录制管线的核心trace 协议从初代到 v3 的演进以及VOM 语义图如何落地到每一次页面观察中。为什么录制管线值得了解普通脚本录制只关心点了哪个坐标而 BrowserSkill 的录制关心的是语义你点的是哪个按钮、填的是什么字段、页面在操作前后处于什么状态。一次完整的录制由三个 RPC 工具驱动定义见 record.rs工具作用tool.record_start开始录制可指定purpose目的描述、trace_version导出格式省略即 v2传3请求 v3tool.record_stop停止录制并返回完整 tracetool.record_await等待录制完成带超时trace 本身是页面状态 用户步骤两部分状态字典负责描述页面长什么样步骤列表负责描述你做了什么。trace 协议三阶段演进从 pages[] 到 states[]v2 遗留格式只有页面骨架初代逻辑 v2trace 没有顶层version字段页面字典是pages[]每个条目只有id、url、title三件套见 record_v2.rs步骤通过page字段引用页面 ID导航效果用effect.navigated_to单独标记目标元素描述TargetDescriptorV2只有tag、role、name、placeholder等零散属性没有稳定元素引用页面上看到了什么完全没有记录——AI 拿到 trace 后不知道当时的按钮长什么样、在什么位置。v3 格式状态-动作-状态日志Trace v3见 record_v3.rs把页面上下文升级为页面状态一次解决 v2 的三大短板states[]携带完整页面观察正文每个状态除id、url、title外还有body字段内容是前置元信息 VOM 正文 注解的完整观察可带truncated截断标记状态-动作-状态SAS结构每个步骤的公共字段变为idstate动作前状态result.state动作后状态页面怎么变化一目了然不再需要 v2 的effect补丁语义化目标描述TargetDescriptorV3引入稳定元素引用ref如e21加role、name、ctx上下文找不到匹配元素时显式标记unmatched: true。v3 还新增了switch_tab步骤、导航成因枚举user_typed/link/form_submit等 7 种NavigationCause、fill提交方式enter/suggestion/blur以及密码字段脱敏redacted标记值替换为***。版本如何识别与兼容协议层用联合体RecordedTrace/RecordedStep做分类record.rs有数字version字段→ 判定为 v3且禁止出现pages[]有pages[]无version→ 判定为 v2但禁止出现states[]混合字段直接报错保证新旧格式永远不会互相污染。对应 JSON Schema 也同步维护在 schema/trace_v3.json 与 schema/trace_v2.json方便任何语言做格式校验。VOM 语义图让 AI看懂页面的关键VOMvom 1格式是 v3 trace 状态正文的底层技术独立实现在 packages/vom/ 包中。VOM 解决什么问题浏览器原生可访问性树信息量爆炸直接喂给 AI 又贵又噪。VOM 渲染器render.ts做了几件聪明事只保留有意义的节点跳过generic、none等无语义角色聚焦 19 种交互角色button、textbox、link……与结构角色dialog、table、navigation……分配稳定 ref可交互元素获得e前缀引用trace 步骤里的target.ref正是来自这里形成观察到 → 操作到的闭环敏感值脱敏redactValues开启后表单值渲染为•••与 v3 的redacted步骤标记联动Token 预算控制maxTokens/maxDepth限制输出规模超长值截断到 200 字符视觉去噪过滤 HTML 注释、内联脚本、登录/开始类弱提示等噪声文本。遮挡层感知知道哪些元素点不到layers.ts 实现了遮挡检测一个fixed/absolute/sticky定位元素若覆盖视口 60% 以上或弹窗类元素覆盖 15% 以上就被判定为阻塞层并自动分类为modal模态弹窗或mask不透明蒙层。这意味着 AI 能理解现在有个弹窗盖住了页面底下的按钮暂时不可用而不是盲目点击失败。节点模型定义types.ts同时携带几何信息rect、paintOrder、交互状态inputState、disabled、inert和条件表面hover 后出现的菜单项CondSurface构成一张完整的页面语义图。录制运行时三步组装一条 v3 trace扩展侧的录制核心是 recording-runtime.ts 中的RecordingObservationRuntime每个被录制的标签页拥有独立上下文流程分为三步文档稳定Settle由 settle-controller.ts 等待页面加载与交互平息避免在页面动的瞬间抓取状态观察捕获Captureobservation-session.ts 通过 CDP 采集可访问性语义与 DOM 几何信息交给 VOM 渲染成vom 1正文并注册进全局状态登记表 state-registry.ts生成s1、s2这样的状态 ID轨迹组装Buildtrace-builder-v3.ts 把草稿步骤与前后状态 ID 拼装为TraceV3附带上recorder信息bsk 版本号 VOM 格式版本vom: 1最终经 daemon 回传给 CLI。配套还有步骤缓冲step-buffer.ts、草稿策略draft-policy.ts与 trace 归约器trace-reducer-v3.ts分别负责暂存用户操作、决定草稿步骤何时提交、以及把流式事件归约为合法 trace。关键文件导航 想深入源码这些路径是最快的入口模块路径职责trace 协议定义crates/bsk-protocol/src/tools/v2/v3 结构与版本分类协议 Schemacrates/bsk-protocol/schema/trace.json、trace_v2.json、trace_v3.json等VOM 渲染器packages/vom/src/render.ts、layers.ts、types.ts录制运行时apps/extension/src/lib/recording/状态登记、稳定等待、trace 组装系统架构docs/architecture.mdCLI / daemon / 扩展三端协作总览小结BrowserSkill 录制管线的演进逻辑非常清晰v2 只记录做了什么v3 补齐了当时看到什么。states[]state/result.state引用把轨迹变成严格的状态机日志VOM 语义图则让每次观察都紧凑、可读、可操作——这正是 AI Agent 能把人类演示可靠转化为自动化技能的数据基础。如果你正在做浏览器自动化方向的项目这条语义化 trace 语义图观察的路线非常值得参考。【免费下载链接】BrowserSkillLet AI agents use your real, logged-in browser without interrupting your work. CLI extension for browser automation across any shell-capable AI agent.项目地址: https://gitcode.com/GitHub_Trending/br/BrowserSkill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考