> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 浏览器自动化

> 让 Agent 浏览网页并自动化浏览器任务。

# 浏览器自动化

Myrm Agent 可自主浏览网页、填表、提取数据并执行操作。

## 浏览器引擎

**双隐身引擎（Patchright + Camoufox）** — 站点拦截默认 Chromium 路径时，Myrm 可热切换到基于 Firefox 的隐身引擎，**且不丢失登录 Cookie**，已认证工作流不会跳回登录页。

三层交互栈：

1. **无头 Chrome / Camoufox** — 完整渲染，含反爬回退
2. **DOM 解析器** — 结构化内容提取（自愈定位器、Shadow DOM）
3. **视觉** — 复杂 UI 的截图交互

### 12 层反检测隐身体系

Myrm 注入全方位反检测系统，让自动化浏览与真实用户无法区分。已通过 5 大主流反 bot 系统（BrowserScan、Fingerprint.com、CreepJS、Cloudflare、DataDome）验证，并在 10+ 高风控平台（微信公众号、微博、知乎、小红书、抖音、Twitter/X、Instagram、Facebook）生产环境中验证通过。

* **CDP 泄露修补** — Patchright 从协议层消除 `Runtime.enable`、`Console.enable`、`--enable-automation` 等检测向量
* **13 项 JS 隐身脚本** — `navigator.webdriver` 隐藏、`window.chrome` 伪造、插件/语言模拟、自动化工件清理、WeakMap `toString()` 伪装、反调试中和、Performance API 清理等
* **拟人化交互** — 随机打字延迟（30-100ms/字符）+ 随机点击延迟（50-150ms）+ 动态超时自适应
* **代理智能轮换与自愈** — 坏代理自动隔离、上下文热替换获取新 IP、跨引擎状态无缝迁移（Cookie + localStorage 在引擎切换时完整保留）

### 用户收益

| 无反检测        | Myrm 隐身体系                |
| ----------- | ------------------------ |
| 首页加载即被拦截    | 通过 Cloudflare 和 DataDome |
| 登录会话被平台撤销   | 跨会话保持登录状态                |
| 必须使用昂贵的住宅代理 | 标准代理即可工作                 |
| 手动管理浏览器配置   | 自动指纹管理                   |

## 页面理解 — 双路径 ARIA 快照

Myrm 使用**语义无障碍树**而非原始 DOM 来理解页面。Agent 像屏幕阅读器一样看到页面 — 结构化、无噪音、聚焦可交互元素。

### 工作原理

| 路径        | 使用场景   | 速度      | 方法                                       |
| --------- | ------ | ------- | ---------------------------------------- |
| **快速路径**  | 90% 页面 | 5-10ms  | Playwright 原生 `ariaSnapshot()` — 零 JS 注入 |
| **自定义路径** | 复杂边缘场景 | 20-50ms | JavaScript 遍历，支持深度控制                     |

### Agent 看到什么

取代数千个 DOM 节点，Agent 获得简洁的语义树：

```yaml theme={null}
- heading "登录" [level=1]
- textbox "邮箱" [ref=1]
- textbox "密码" [ref=2]
- button "登录" [ref=3]
- link "忘记密码?" [ref=4]
```

每个可交互元素获得稳定的 **ref ID**，Agent 用于精确定位 — 告别脆弱的 CSS 选择器。

### 内建韧性

* **Shadow DOM 穿透** — 自动穿越 Web Components
* **iframe 提取** — 跨域 iframe 内容纳入树中
* **范围过滤** — `full`、`interactive` 或 `focused` 视图控制 token 消耗
* **增量 diff** — 仅展示快照间的变化

### 为何不做遮挡检测？

某些工具（如 OpenCLI）用 `elementFromPoint` 逐个扫描元素来剪枝被遮挡节点。我们刻意不做，因为：

1. 每次快照增加 100-500ms（每个元素触发 reflow）
2. 可能误剪有效元素（下拉菜单、提示框）
3. Playwright 的 `click()` 已内建 actionability 检查，拒绝点击被遮挡元素
4. 点击失败时，**自愈定位器**以 O(1) 时间修复

最终效果：5-10ms 快照，比 DOM 方案节省 60-80% Token，零精度损失。

## 能力

* 导航到 URL
* 点击元素、填写表单
* 提取文本与结构化数据
* 截图
* 处理认证流程
* 智能处理浏览器弹窗

## 弹窗策略（自动处理弹窗）

JavaScript 弹窗（`alert`、`confirm`、`prompt`、`beforeunload`）若不处理会阻塞所有页面交互。Myrm 提供**四种可配置策略**，按智能体独立设置：

| 策略           | 行为                         | 适用场景       |
| ------------ | -------------------------- | ---------- |
| **智能**（默认）   | 接受 alert/confirm，关闭 prompt | 通用浏览       |
| **全部接受**     | 接受所有弹窗                     | 批量自动化、数据采集 |
| **全部关闭**     | 关闭所有弹窗                     | 数据提取、只读场景  |
| **等待 Agent** | 暂停让 AI 决策（超时自动回退）          | 关键确认操作     |

### 配置方式

在 **设置 → 智能体 → 能力配置 → 弹窗处理** 中为每个智能体设置策略。

智能体也可在运行时通过 `browser_manage` 工具的 `dialog_policy` 操作动态切换策略。

### 工作原理

* **智能模式**（默认）：Agent 不会被 Cookie 横幅或提示性弹窗卡住。
* **等待 Agent 模式**：弹窗内容会出现在下一次浏览器快照中，AI 拥有完整上下文来决策。超时后自动安全回退。
* 弹窗历史始终对 Agent 可见——它知道处理了哪些弹窗以及如何处理的。

## 凭证库（登录而不泄露密码）

需登录的站点与应用，在 **设置 → 凭证** 配置 **表单凭证库** 条目：

1. 添加**标签**（如 `company-admin`）、密码与可选 TOTP 种子。
2. 让 Agent 登录 — 仅引用标签。
3. Myrm 在浏览器 DOM 或桌面输入层注入凭证；值不出现在对话中。

**意义：** 工具参数与聊天历史持久化。通过 `type`/`fill` 传 `"hunter2"` 会把密码复制到日志、重试与上下文。基于标签的注入将秘密留在库边界内——与研究级浏览器库设计同原则，并扩展到桌面 Computer Use 与产品 GUI。

## 视觉验证（自动 QA）

每个浏览器操作都可自动验证——无需手动检查。

操作时传入 `verify_goal` 参数，Myrm 的 **3 层验证漏斗** 自动启动：

1. **dHash 检测**（\~2ms）— 感知哈希快速判断页面是否变化。无变化则跳过 LLM 调用，节省 Token。
2. **像素级 Diff** — Canvas API 对比 + YIQ 色彩空间 + 抗锯齿检测，精准定位变化区域。
3. **Vision LLM 评分** — 多模态 AI 对结果打分 1-5 并给出理由，确认目标是否达成。

### 示例

向 Agent 提问：*"点击'加入购物车'，验证购物车数量显示为 2"*

Agent 使用 `verify_goal="购物车数量显示为 2"`。点击后，系统自动截图并验证结果。评分低于 4 时，Agent 收到反馈并可自主重试。

### 隐私保护

密码输入框在截图时**自动遮蔽**——Vision LLM 不会看到敏感凭证。

## 搜索集成

7 意图搜索系统理解不同检索需求：

* 事实查询
* 导航请求
* 研究任务
* 价格对比
* 新闻动态
* 图片搜索
* 本地搜索

## Computer Use

通过 Computer Use 协议实现桌面自动化，跨 macOS/Windows/Linux 控制原生应用。

## 8 层全链路可视化排障系统

当 Agent 操作浏览器或桌面应用时，你不需要猜它在做什么——8 层可视化系统让你实时看到一切。

### 你能看到什么

| 层级                     | 功能                        | 你获得什么                                                                                                  |
| ---------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------ |
| **BrowserLiveView**    | 可拖拽侧面板 + 实时截图             | 实时看到浏览器页面，14 种元素角色 BBox 高亮可点击选择                                                                        |
| **DesktopLiveView**    | 桌面应用镜像面板                  | 桌面原生应用操作的实时截图预览                                                                                        |
| **ElementOverlay**     | 交互式 BBox 高亮               | 按钮/链接/输入框/复选框/下拉框全部高亮可选，悬浮显示角色和名称                                                                      |
| **OS 叠加层**             | 系统级红色高亮框 (Tauri 桌面端)      | **真实显示器上的红色边框**，即使聊天窗口被遮挡也能看到                                                                          |
| **ProgressSteps 树状进度** | 树状步骤追踪器                   | 工具图标 + Agent 标识 + 耗时 + 进度条 + 错误诊断 + 恢复按钮 + 终端输出                                                        |
| **HITL 审批**            | Approve/Deny + 编辑 payload | 执行前审阅操作，编辑参数，Monaco Editor 代码 Diff 对比                                                                  |
| **VNC 接管**             | 远程浏览器控制                   | Agent 卡住时 VNC 自动弹出，你可以远程操作解决问题                                                                         |
| **SSE 事件**             | 10+ 实时事件类型                | browser\_view\_update / desktop\_view\_update / locator\_self\_healed / captcha / tool lifecycle 全链路推送 |

### 竞品对比

所有竞品（OpenClaw、CoPaw、PilotDeck、Hermes、Claude Computer Use、Codex App）均不提供上述任何可视化追踪能力。竞品通常只有文字日志或简单进度条。

### 测试覆盖

196 项测试横跨 Rust（Tauri OS overlay）、Python（harness 事件、接管、CAPTCHA）、TypeScript（前端 ProgressSteps、SSE 处理）三层——全部通过。

## Schema 驱动结构化提取

无需将整页原始文本灌入对话（浪费上下文 Token），你可以传入 **JSON Schema**，提取工具直接返回验证过的结构化 JSON。

### 工作原理

1. Agent 调用 `browser_extract`，附带 `extraction_schema` 参数（JSON Schema 字符串）。
2. 工具提取页面文本，然后用 LLM 生成符合 Schema 的结构化输出。
3. 你得到干净、验证过的 JSON——而非数千 Token 的原始 HTML。

### 示例

向 Agent 提问：*"提取页面上所有产品名称和价格"*

Agent 使用如下 Schema：

```json theme={null}
{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "price": { "type": "string" }
    },
    "required": ["name", "price"]
  }
}
```

结果：仅包含你需要数据的干净 JSON 数组。

### 核心特性

* **对象和数组 Schema** — 提取单个对象或项目列表。
* **分页去重** — 传入 `already_collected` 避免跨页重复。
* **双策略可靠性** — 优先 `structured_output`，兼容性回退到原始 JSON 解析。
* **Token 节省** — 相比原始文本提取减少 70–97%。
* **Schema 复杂度保护** — 限制属性数量和嵌套深度，防止滥用。

## 临时会话隔离

每个浏览器上下文**默认为临时模式**——通过 `browser.new_context()` 创建，不使用持久化配置。会话结束时 Cookie、localStorage 和缓存自动销毁。Agent 永远无法访问你的真实浏览器配置，从根源杜绝会话泄露风险。

## 加密 Session 库（跨会话保持登录）

会话默认临时，但你可以为每个 Agent 配置 **auto\_restore\_domains**，在对话之间保持登录状态。

### 工作原理

1. **配置域名** — 在 Agent 设置 WebUI 中，将 `twitter.com`、`github.com` 等域名添加到 Agent 的 `auto_restore_domains` 列表。
2. **加密存储** — Cookie 和存储数据通过 AES-256-GCM 加密保存在 Session Vault 中。
3. **启动时自动恢复** — 每次 Agent 启动新浏览器会话时，已配置域名的登录态自动恢复。
4. **Agent 可显式管理** — Agent 也可通过 `browser_manage(action="save_session")` / `restore_session` / `list_sessions` / `delete_session` 进行精细控制。

### 架构亮点

* **AES-256-GCM 加密** — Session 数据落盘加密，绝不以明文存储。
* **O(1) LRU 内存缓存** — 热点 Session 直接从内存读取，无磁盘 I/O。
* **Singleflight 去重** — 并发请求同一域名时合并为一次解密操作。
* **TTL 自动过期** — 过期 Session 被自动垃圾回收。
* **全场景覆盖** — Web 对话、Channel 渠道、Cron 定时任务、Eval 评测均支持。

### 使用场景

| 场景              | 建议                                          |
| --------------- | ------------------------------------------- |
| 一次性浏览           | 默认（临时模式）——无需配置                              |
| 频繁访问需认证的网站      | 添加到 `auto_restore_domains`                  |
| Agent 工作流中途需要登录 | Agent 调用 `save_session` / `restore_session` |
| 多 Agent 共享凭证    | 每个 Agent 独立配置域名列表                           |

### Session–Memory Bridge（零成本会话感知）

当记忆系统启用时，已保存的浏览器会话**自动出现在 Agent 上下文中**——无需额外工具调用。

* **工作原理：** 每次保存或删除 session 时，`SessionMemoryBridge` 自动更新 Agent 的 `active_browser_sessions` Profile 属性。该属性通过 memory context middleware 注入到每轮 LLM 上下文中。
* **效果：** 当用户说"帮我发推文"时，Agent 已知道 `twitter.com` 可用——直接调用 `restore_session("twitter.com")`，**跳过 `list_sessions` 步骤，节省 1 次 LLM 推理**。
* **Prompt Cache 安全：** Profile 属性仅在 save/delete 时变更（极低频），不影响缓存命中率。

| 无 Bridge                                                                      | 有 Bridge                                                      |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------- |
| 用户："帮我发推文" → Agent 调用 `list_sessions` → 发现 twitter.com → 调用 `restore_session` | 用户："帮我发推文" → Agent 上下文已有 twitter.com → 直接调用 `restore_session` |
| 2 次工具调用 + 2 次 LLM 推理                                                          | 1 次工具调用 + 1 次 LLM 推理                                          |

## CAPTCHA 检测 & 人类接管

Agent 在浏览网页时遇到验证码或需要人工介入的场景，系统自动处理：

### 自动 CAPTCHA 检测

系统自动识别 10 种验证码类型（Cloudflare Turnstile、reCAPTCHA、hCaptcha 等）。检测到时：

1. Agent 通过 LangGraph `interrupt()` 暂停执行
2. VNC 面板自动打开，展示浏览器画面
3. 顶部显示暂停原因通知
4. 你手动完成验证码
5. Agent 自动恢复继续执行任务

### Agent 主动请求人类接管

对于验证码之外的场景——短信验证、支付网关、专有表单——Agent 可以主动请求你帮助：

1. Agent 判断自己无法继续（如"需要短信验证码"）
2. 调用 `browser_ask_human`，附带清晰的说明
3. VNC 面板弹出，展示原因
4. 你直接在浏览器中完成操作
5. 点击"完成"——Agent 捕获新页面状态并继续

### 对比竞品

| 没有 Myrm           | 有了 Myrm        |
| ----------------- | -------------- |
| Agent 在验证码上无限循环   | 自动检测、暂停、通知     |
| Agent 在 2FA 上静默失败 | 主动请求帮助         |
| 用户必须时刻盯着          | 仅在真正需要时才打断     |
| 人工操作后上下文丢失        | 捕获操作后的页面状态并自适应 |

## 浏览器扩展桥接（Extension Bridge）

当你需要 Agent 在你的**真实浏览器**中操作——保留现有登录态、扩展程序和浏览上下文时，Myrm 支持 Chrome 扩展桥接方案。

### 适用场景

| 场景                      | 推荐方案                                |
| ----------------------- | ----------------------------------- |
| 全新的自动化浏览                | 默认方案（临时引擎）                          |
| 复用特定登录会话                | SessionVault `auto_restore_domains` |
| 需要完整浏览器指纹一致性            | **Extension Bridge**                |
| Agent 需要看到你真实的标签页/书签/扩展 | **Extension Bridge**                |
| SaaS 模式远程控制用户浏览器        | **Extension Bridge**                |

### 工作原理

1. **安装 Myrm 扩展** — 一个轻量级 Chrome MV3 扩展，维持与 Myrm 服务器的 WebSocket 连接。
2. **授权域名** — 在设置 → 集成 → Extension Bridge 中添加允许 Agent 控制的域名（如 `github.com`、`*.google.com`）。支持通配符模式。
3. **Agent 连接** — 当任务需要访问已授权域名时，Agent 通过 CDP（Chrome DevTools Protocol）代理连接到你的真实浏览器。

### 安全模型

* **域名级授权** — 仅显式授权的域名可被控制。Agent 无法访问授权列表外的任何标签页。
* **Token 认证** — 扩展使用密钥令牌向服务器认证，防止未授权连接。
* **Service Worker 保活** — MV3 扩展使用 `chrome.alarms` 实现持久连接和指数退避重连。
* **重连时域名同步** — 扩展重新连接时立即与服务器同步授权域名列表。

### 前端管理

Extension Bridge 设置面板（设置 → 集成）提供：

* **一键复制 WebSocket URL** — 根据当前部署模式自动生成正确的连接地址，带复制按钮和提示反馈
* **Auth Token 状态** — 显示服务器是否已配置 `EXTENSION_AUTH_TOKEN`（不暴露 token 明文）
* **可复制扩展路径** — 显示 `~/.myrm/myrm-agent/myrm-agent-extension`，一键复制用于 Chrome「加载已解压的扩展程序」
* **分步引导** — 扩展未连接时显示：加载扩展 → 复制 URL → 连接
* **实时连接状态** — 已连接/断开指示器，含扩展版本和浏览器名称
* **域名授权管理** — 添加、删除，支持通配符模式
* **可用标签页列表** — 按授权域名过滤，标记活跃标签

### 架构

Extension Bridge 跨越 5 层：

1. **Harness 协议层** (`ExtensionBridge`) — 在框架层定义契约
2. **Server 服务层** (`ExtensionBridgeService`) — 管理 WebSocket 生命周期、心跳和 CDP 代理
3. **API 路由层** — WebSocket + REST 端点，服务扩展和前端
4. **Chrome 扩展** — MV3 Service Worker，具备 CDP 附加能力
5. **前端面板** — React 设置组件，用于状态和域名管理

## Per-Agent 浏览器来源配置

每个智能体可以独立选择如何访问浏览器。可在智能体设置中配置（创建智能体时，或在聊天窗口的 per-chat 配置面板中）。

### 可用模式

| 模式         | 行为                            | 适用场景             |
| ---------- | ----------------------------- | ---------------- |
| **自动**（默认） | 系统根据可用性自动决定                   | 通用场景——无需手动设置     |
| **扩展**     | 通过 Extension Bridge 使用用户真实浏览器 | 购物、社交媒体、需要登录态的任务 |
| **启动**     | 启动一个全新的托管浏览器实例                | 调研、数据抓取、测试       |

### 配置方式

1. **创建智能体时**：设置 → 智能体 → 创建/编辑 → 浏览器来源
2. **聊天时覆盖**：点击聊天窗口中的智能体配置图标 → 浏览器来源

### 池隔离

当不同智能体使用不同浏览器来源时，浏览器池保持严格隔离：

* 扩展来源的浏览器（非托管）绝不会分配给启动模式的智能体
* 启动来源的浏览器（托管）绝不会分配给扩展模式的智能体
* 防止不同信任级别的智能体之间的会话交叉污染

## 浏览器引擎零配置安装

首次在全新的 Myrm 桌面端上使用浏览器工具时，浏览器引擎（Chromium）会自动下载安装——**无需打开终端输入任何命令**。

### 工作原理

1. Agent 的任务需要使用浏览器
2. 检测到 Chromium 未安装
3. 后台自动下载并安装浏览器引擎
4. 安装完成后任务无缝继续

如果自动安装失败（无网络、磁盘空间不足等），Myrm 会提供清晰的诊断信息和具体的修复指引。

### 智能失败处理

* **冷却保护** — 安装失败后等待 30 分钟再重试，避免阻塞正常使用
* **并发安全** — 多个任务同时请求浏览器时自动串行化，避免冲突
* **诊断信息** — 准确显示失败原因（磁盘空间、网络、权限）及修复方法
* **Doctor 自动修复** — 运行 `myrm doctor` 可一键诊断并修复浏览器问题

### 对比竞品

| 其他 Agent 工具                           | Myrm         |
| ------------------------------------- | ------------ |
| 必须在终端运行 `playwright install chromium` | 自动完成，直接使用    |
| Windows 依赖错误令非开发者用户困惑                 | 清晰的诊断信息和修复指引 |
| 浏览器功能在手动安装前不可用                        | 首次使用即可工作     |