Codeg浏览器自动化原理隔离世界ARIA树的跨导航元素引用安全设计详解【免费下载链接】codegCollaborative multi-agent AI coding workspace: aggregate sessions from Claude Code, Codex, OpenCode, Pi, Grok Build, etc. Desktop app, self-hosted server, or Docker.项目地址: https://gitcode.com/gh_mirrors/co/codegCodeg 是一款多智能体协作编程工作台其内置浏览器允许 Claude Code、Codex、OpenCode 等 AI 智能体在真实网页中看和操作。本文带你快速看懂 Codeg 浏览器自动化的底层原理它如何用**隔离世界Isolated World**建立一条页面看不见的自动化通道又如何用ARIA 树快照 双令牌元素引用让智能体在跨导航的网页环境下安全地点击、输入而不会点到错的元素。一、为什么浏览器自动化需要安全设计让 AI 智能体操作浏览器天然是高风险场景网页里的脚本可能伪装、劫持、注入恶意页面可以污染智能体看到的世界智能体持有的元素编号在页面跳转后可能悄悄指向完全不同的元素导致误点用户登录的页面包含敏感信息智能体不应默认拥有读取权。Codeg 的浏览器模块src-tauri/src/browser/mod.rs用三件法宝系统性解决了这些问题隔离世界、ARIA 树快照、跨导航失效的元素引用令牌。二、隔离世界一条页面看不见的自动化通道什么是隔离世界同一个网页引擎中其实可以并存多个JavaScript 世界。它们共享同一个 DOM但各自拥有独立的 JS 全局环境。Codeg 在每个浏览器标签页中于文档加载的最早时机document start注入一个助手脚本运行在名为codeg的隔离世界里平台隔离世界实现macOS / LinuxWebKitWKContentWorld codegWindowsWebView2CDP 隔离世界平台差异封装src-tauri/src/browser/shim/mod.rs这个设计带来一个关键安全性质隔离世界共享 DOM但有自己的 JavaScript 全局变量。也就是说即使某个恶意页面把自身的JSON、addEventListener全部改掉Codeg 助手脚本里用的这些函数依然是干净的原始版本见 src/browser-injected/helper.js 的文件头注释。反过来页面脚本也永远看不见__codegAgent这些智能体接口——页面无法读到注入脚本也无法篡改智能体的行为。通道里的消息全部视为不可信输入隔离世界的脚本通过一条原生消息处理器而非 JS 桥把 JSON 信封回传给 Rust 宿主。src-tauri/src/browser/channel.rs 对每条消息做了严格校验超过 64KB 的消息直接丢弃未知类型的消息被忽略手势类消息一律打上untrusted标记页面向宿主报告的地址、标题只用于触发权限检查永远不能反过来扩大权限。更彻底的是浏览器标签页的 webview 标签以browser-为前缀并且刻意不出现在任何 Tauri capability 配置中src-tauri/src/browser/mod.rs 里还有一个专门跑在测试里的断言保证任何 capability 都不许给浏览器页面授予 IPC 权限——页面脚本连调用宿主命令的入口都没有。三、ARIA树快照把网页变成Agent能读懂的元素清单用 Playwright 同款 ARIA 树智能体看页面不靠截图猜坐标而是靠可访问性ARIA树。Codeg 内置了一个快照引擎browser-agent/src/index.ts直接复用 Playwright 的ariaSnapshot实现并特意使用 Playwright MCP 的ai渲染模式——这样智能体读到的就是它在其他环境里已经熟悉的树形结构。宿主发起快照时会在隔离世界中求值一段表达式拿到形如 PageSnapshot 的结构generation元素引用的令牌后文详述url/title/viewport快照时刻的地址、标题与视口treeARIA 树文本每个可交互元素被编号为e1、e2、e3……truncated树是否因长度上限被截断。一个值得注意的细节这个快照引擎只在某次已授权的读取真正需要时才注入而不是页面加载时无脑装好src-tauri/src/browser/agent.rs。从未被分享过给任何智能体的标签页里面根本没有读页面的代码——授权检查并不是挡在智能体和页面之间的唯一屏障。四、跨导航元素引用为什么会失效这是整篇文章的核心问题。假设智能体在https://shop.example/cart上读到提交订单按钮是e8然后整页导航到别的地址旧文档消失但智能体手里的e8会在新页面上恰好解析到某个它从未见过的元素——静默地、点错目标SPA 同文档路由pushState/replaceState/ hash 变化文档没换、脚本世界还活着但页面内容已经变了e8可能指向新路由下的另一个按钮。难点在于SPA 的pushState没有任何原生事件可监听引擎的加载回调也感知不到它。browser-agent/src/index.ts 的注释写得很直白方向很重要宁可拒绝一些仍然安全的引用调用方少跑一趟也不能把一个错误的元素交给调用方用户损失的是他真实的页面操作。第一道防线generation 代际令牌快照引擎在文档启动时、早于任何页面脚本运行用crypto.getRandomValues生成一个随机代际令牌GENERATIONbrowser-agent/src/index.ts。新文档 ⇒ 新的隔离世界 ⇒ 新的代际令牌旧的e*引用自动作废令牌在页面够不到的世界里生成恶意页面既读不到也改不了它。第二道防线epoch 宿主纪元专治 A→B→A但代际令牌有个盲区同文档路由 A → B → A 之后地址又变回了快照时的地址纯地址比对会漏判。于是引入了宿主机Rust 侧维护的nav_epoch纪元号隔离世界里的 helper.js 通过事件 轻量轮询监听地址变化每次上报nav-state消息宿主确认地址变了就nav_epoch 1src-tauri/src/browser/channel.rs并顺带检查授权是否因此失效纪元号和代际令牌拼在一起组成快照的epoch混入引用令牌{generation}.{nav_epoch}。同文档导航里隔离世界还能额外盯住两样宿主管不到的东西browser-agent/src/index.tshistory.length每次pushState都会增长能捕捉A→B→A的往返popstate/hashchange事件在世界内正常触发能捕捉前进后退引擎支持 Navigation API 时用每次导航都重新铸造的currentEntry.id兜底连replaceState往返也能抓到。第三道防线旧引用被整体作废而非逐个回收元素引用表refs在每次快照时整体替换而不是累积上一代的引用只保留名字不保留元素对象这样宿主能向调用方精确解释一个失效引用到底是被你下一次快照作废了还是页面自己变了——智能体收到明确报错重新拍快照即可而不是猜browser-agent/src/index.ts。五、授权绑定 origin页面一走权限立刻收回引用令牌保证点得准而授权模型保证读得合规。Codeg 的规则只有一条src-tauri/src/browser/agent.rs一切都不自动授权。不按地址类别猜localhost可能是登录态的私有服务不按监听进程猜socat顶着端口一样有说服力唯一途径用户主动把标签页分享给智能体级别分None / Read / ControlGrantLevel。授权与分享那一刻的 origin 绑定。两条回收函数保证权限只收窄、不扩大场景机制页面离开授权 originrevoke_if_departed 在每次 origin 写入处调用导航即失权localhost端口被另一个程序顶替revoke_if_replaced 记录的是程序工作目录而非进程实例热重载的 dev server 重启不会被误伤一旦端口背后的程序变了授权立即收回并通知用户注意一个精妙的配合前文说同文档导航宿主感知偏晚所以它不适合当安全边界——但引擎会拒绝跨 origin 的pushState唯一宿主感知慢的那类导航恰好越不过 origin 边界。慢感知与授权边界在这里正好互补。六、操作页面每个动作都有活动条可查智能体拿到有效引用后通过act执行点击、悬停、输入、按键、选择等操作browser-agent/src/act.ts。宿主把每次尝试如实记到标签页的智能体活动条上读取、点击、运行代码Eval需用户对片段逐条批准……连被拒绝的尝试也会显示——一个从未被分享却反复被请求的页面正是用户最该看到的信息AgentOutcome。七、小结三层设计如何协同层解决什么关键机制隔离世界页面与智能体互相看不见注入于 document start共享 DOM 但独立全局环境无 IPC 入口ARIA 树快照智能体可靠地看懂页面Playwrightai模式 ARIA 树 e*引用编号引用令牌跨导航不误点随机 generation防整页导航 宿主 epoch防 SPA 路由 history/Navigation API 兜底Origin 授权敏感页面不被默读用户显式分享、origin 绑定、导航/换程序即回收这套设计的整体思路可以概括为一句话与其信任网页不如让信任过期即失效、越权不可见。这也是 Codeg 能把浏览器交给多个 AI 智能体安全共用的底气所在。如果你想动手研究入口文件是 src-tauri/src/browser/ 下的 Rust 宿主逻辑、browser-agent/src/index.ts 下的隔离世界引擎以及 src/browser-injected/helper.js 的导航感知助手。【免费下载链接】codegCollaborative multi-agent AI coding workspace: aggregate sessions from Claude Code, Codex, OpenCode, Pi, Grok Build, etc. Desktop app, self-hosted server, or Docker.项目地址: https://gitcode.com/gh_mirrors/co/codeg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考