企业官网建设流程全解析

Orbital 是一个开源的 AI agent 操作系统，其内置的浏览器自动化模块基于 Patchright（Playwright 的反检测增强分支），为 AI agent 提供 26 种浏览器操作，配合多层反检测指纹伪装、失败自愈与搜索引擎回退机制，让 agent 能稳定地浏览网页、填写表单、抓取内容，而不被反爬系统拦截。本文带你完整看懂这套浏览器自动化是怎么设计的。

三层架构：谁负责什么

Orbital 的浏览器能力拆成三层，职责清晰：

工具层最关键的设计是"snapshot + ref"工作流：agent 先调用snapshot获取页面可访问性树（accessibility tree），得到一份带编号（如e5）的元素清单，后续所有点击、输入都通过 ref 定位元素，而不是脆弱的 CSS 选择器。这套机制实现在 browser_refs.py 中。

26 种浏览器操作全拆解

完整 action 枚举见 browser.py L308-L316，按用途可以分为七组：

🧭 导航类（4 种）

🖱️ 交互类（9 种）

click、type、fill、press、hover、select、scroll、drag、upload_file。

• fill支持一次填充多个表单字段，且能识别<secret:gmail.email>这类占位符，自动从凭据库替换真实值，密码不会以明文进入对话记录（browser.py L727-L781）
• upload_file只允许上传工作区内的文件，路径越权会被直接拒绝
• 这 9 种属于"写操作"（BROWSER_WRITE_ACTIONS，见 browser.py L149-L152），在低自主模式下会触发人工审批

👁️ 观察类（5 种）

snapshot（可访问性树）、screenshot（截图，支持红框标注 ref 的 annotate 模式）、extract（纯文本抽取，1 万字符截断）、search_page（页内元素/文本搜索）、evaluate（执行任意 JS）。

⏳ 等待类（1 种 6 模式）

wait支持按秒数、文字出现、文字消失、CSS 选择器、URL 模式、加载状态六种条件等待（browser.py L1208-L1240），避免"页面没渲染完就操作"的经典 bug。

🔍 联网搜索与抓取（2 种）

search一次调用即完成"开新标签 → 搜索 → 抽取前 10 条结果 → 关标签"；fetch则是把某个网页的正文抽成纯文本（5 万字符截断），相当于一个带渲染能力的网页阅读器。

🗂️ 标签页管理（3 种）：tab_new、tab_switch、tab_close

📄 输出与收尾（2 种）：pdf（页面存为 PDF）、done（标记任务完成）

基于 Patchright 的反检测机制：为什么能绕过反爬

这是本文的重点。Orbital 用的是patchright而非原生 Playwright——它是 Playwright 的 drop-in 替代品，内置了反自动化检测补丁（见 browser_manager.py L27-L31）。在这之上还有三层主动伪装：

1. Stealth 注入脚本

每个页面加载时都会执行一段 stealth JS（_STEALTH_JS），覆盖 Patchright 没处理的指纹点：

• navigator.webdriver→undefined（最经典的自动化特征）
• navigator.plugins→ 模拟 5 个插件（无插件是 headless 的典型特征）
• 补齐window.chrome.runtime/chrome.app对象（真实 Chrome 才有）
• navigator.languages按启动 locale 动态填充，比如zh-CN环境就是["zh-CN", "zh", "en-US", "en"]——因为"中文界面却报英文语言列表"本身就是自动化指纹

2. 指纹自洽：locale 与时区必须互相吻合

一个常见坑是：浏览器上下文是zh-CN，时区却报美国东部——这种矛盾比单个错误更招摇。Orbital 的 时区检测链 会依次尝试 tzlocal → Windows 注册表 → UTC 偏移兜底，兜底值也跟随 locale（zh-CN必得Asia/Shanghai）。对应测试见 test_browser_anti_detection.py。

3. 干净的启动参数

Chrome flags 中显式带上--disable-blink-features=AutomationControlled、--disable-infobars等参数（CHROME_FLAGS），并在启动时丢弃默认的--enable-automation标志，从源头去掉自动化标识。

稳定干活的关键：失败不是终点，是信号

绕过检测只是第一步，真正"稳定干活"靠的是这套容错设计：

失败追踪 + 硬性熔断：_track_result 会记录每种操作的连续失败次数——连续失败 3 次就在结果里附加提醒，失败 5 次直接返回BLOCKED，强制 agent 换策略（直接访问 URL、改用search或fetch），而不是无限重试烧 token。

过期 ref 自动失效：元素定位超时时，_invalidate_stale_ref 会把失效的 ref 从映射表里删掉，让下次操作快速失败，逼 agent 重新 snapshot，避免拿着陈旧引用反复撞墙。

浏览器三级回退：启动时依次尝试系统 Chrome → 系统 Edge → 内置 Chromium（browser_manager.py L554-L570），任何一台机器都能跑起来。

搜索引擎双引擎回退：根据 locale 自动选主引擎——中国大陆环境用必应中国版（无需代理可达），其余环境用 Google；主引擎不可达时自动切到另一引擎，抽取选择器失效时还会降级为整页 snapshot 兜底（browser.py L261-L277）。

崩溃自愈：浏览器进程意外挂掉时，daemon 检测到 CDP 连接断开会自动重启并重建上下文，项目页面状态尽量保留。

安全护栏：自动化不等于失控

反爬能力越强，越需要缰绳。Orbital 内置了几道护栏：

• SSRF 防护：validate_url_pre_navigation 在导航前解析域名并拦截指向127.0.0.0/8、10.0.0.0/8、192.168.0.0/16等内网地址的 URL；导航后还会二次校验，防止开放重定向跳回内网
• 不信任内容包裹：网页正文属于不可信内容，wrap_untrusted_content会给它加上明确的边界标记，降低提示注入风险
• 审批分级：交互类写操作会按 autonomy preset 决定是否暂停等待用户批准，批量执行到写操作时自动PAUSED并挂起剩余动作（browser.py L1367-L1387）

配合定时任务：7×24 无人值守的浏览器工作流

浏览器自动化真正的价值在于"长期跑"。Orbital 的 Triggers 支持定时、文件监听等触发方式，把"每天早 9 点用浏览器抓一轮数据并汇总"这类任务写成自然语言 prompt 即可；配合 sub-agent 派发，浏览器任务可以委派给独立 worker 并行执行，主会话不被阻塞。

小结

• 26 种操作覆盖导航、交互、观察、等待、搜索、标签页全场景，snapshot + ref 机制替代脆弱选择器
• 三层反检测：Patchright 补丁 + stealth 注入 + locale/时区指纹自洽，从指纹层面降低被识别概率
• 稳定性靠设计：失败熔断、过期 ref 失效、浏览器三级回退、双搜索引擎兜底、崩溃自愈
• 安全兜底：SSRF 防护、内容隔离、写操作审批，自动化能力再强也踩不到红线

想进一步了解的读者可以从 browser.py、browser_manager.py 两个入口读起，整体浏览器能力介绍也可参考 README.zh-CN.md。