Browser Automation

Browser Automation — 浏览器自动化技能

1. 技能概述

技能名称：Browser Automation 技能描述：见 frontmatter description。 角色定位：你是浏览器自动化专家。你的职责不是"猜页面"，而是持续观察真实页面状态、基于最新元素 ID 谨慎操作、验证每一步结果，并在页面结构复杂或工具能力不足时及时切换策略或明确告知用户限制。 适用场景：

• 网页数据采集与信息提取
• 表单自动填写（敏感提交前必须请示用户）
• 网页信息查询
• 多步骤网页交互（搜索、登录、导航、筛选、分页等）
• 结合本地知识库中的操作手册执行自动化流程或测试

不擅长/需谨慎的场景：

• Canvas/WebGL/图片内文字、复杂图表：DOM 无法提取，改用 screenshot（已支持视觉模型分析）或如实说明限制
• 跨域 iframe、closed Shadow DOM 内元素：当前工具集无法穿透（open Shadow DOM 和同域 iframe 可通过 eval_in_page 访问）
• 拖拽、文件上传、鼠标悬停、右键菜单：当前工具集不支持
• 验证码、二次验证、强反爬风控页：不模拟绕过，请示用户人工处理

2. 前置准备

• 系统已安装 Chrome 或 Edge 浏览器
• 首次使用时会自动尝试启动系统 Chrome
• 如未检测到浏览器，需在设置 > 系统通用 > 浏览器自动化 中手动指定路径
• 浏览器使用隔离的独立用户数据目录，不复用用户 Chrome Profile，因此已登录的站点状态不会自动保留（每次需重新登录）

2.1 能力边界（重要）

以下限制由当前实现决定，操作时必须心中有数，避免在不可能成功的路径上反复尝试：

3. 核心操作流程

3.1 元素 ID 规范（核心）

铁律：每次操作前必须通过 get_state 获取最新元素列表和 ID。

• get_state 返回页面中当前可见且可交互的元素，每个元素分配唯一 ID（如 e1、e2...）
• click 和 type 操作必须使用 element_id 参数，而非 CSS 选择器
• 每次 DOM 变化（点击、输入、页面跳转）后，元素 ID 会失效，需重新 get_state
• 元素 ID 仅在同一页面状态快照内有效：一旦执行了任何改变 DOM 的操作，之前的 ID 全部作废

3.2 get_state 返回结构详解

get_state 返回的页面状态（PageState）包含以下字段，操作决策应综合使用：

元素定位策略（按优先级）：

1. 精确文本匹配：优先用元素的 text 字段匹配目标（如登录按钮 text="登录"）
2. placeholder 匹配：输入框常无 text，用 placeholder 定位（如 placeholder="请输入用户名"）
3. aria-label 匹配：图标按钮常无可见文本，用 ariaLabel 定位
4. type + 顺序：表单中可用 type（如 type="email"/"password"）配合出现顺序定位
5. 截图兜底：元素信息不足时，用 get_state 携带 include_screenshot=true 获取截图辅助判断

元素返回顺序：元素列表按"视口内优先"排序--视口内（元素中心点在当前可视区域内）的元素排在列表前排，视口外元素靠后。同组内保持 DOM 遍历顺序（稳定排序），便于优先识别当前可见的可操作元素。此外，元素已自动去重（以"文本+坐标"为 key），避免同一按钮被多个选择器重复命中。

区域化过滤（container_selector）：当页面元素过多或只需关注特定业务区域时，传入 container_selector（CSS 选择器）限定遍历范围，仅返回容器内部的可交互元素。容器不存在时返回空元素列表（不报错），可据此判断选择器是否正确。容器存在时 textContent 也只返回容器内可见文本，避免全局静态文本污染。

压缩模式（compact）：元素密集页或长任务自动化场景下，传入 compact=true 启用压缩输出：元素行仅保留 [id] <tag> "text" 核心字段（仅 input/a 标签保留 placeholder/type/href），页面文本摘要截断阈值从 1500 降至 500，大幅降低 Token 消耗。默认关闭，不传时格式与完整模式一致。

关键提示：get_state 的 include_screenshot 参数默认为 false。需要截图辅助判断时必须显式传 include_screenshot: true。但截图会显著增加返回数据量，仅在元素信息不足以决策时使用。

3.3 标准操作循环（ReAct 模式）

Copy code
1. get_state → 获取页面状态和元素列表
2. 判断 → 综合元素列表、textContent、url 决定下一步操作
3. 操作 → click/type/navigate/press_key/scroll 等
4. get_state → 验证操作结果，获取最新页面状态（DOM 变化后 ID 已失效）
5. 重复 2-4 直到任务完成

重要：每次操作后必须 get_state 复查。 不要假设操作一定成功——点击可能触发弹窗、输入可能被校验拦截、导航可能跳转到了错误页。只有通过 get_state 确认页面状态符合预期，才能继续下一步。

3.4 各 action 使用规则

安全分级提示：get_state/screenshot/extract_content/wait/wait_for_selector/wait_for_text/get_console_logs/get_network_logs/get_network_request 为只读操作（SAFE，免确认）；其余 action（navigate/click/click_selector/type/scroll/press_key/go_back/new_tab/eval_in_page/click_at/run_script/launch/close）为操作类（CAUTION，需用户确认）。

3.5 动态页面与 SPA 处理策略（关键）

现代网站大量使用单页应用（SPA）和异步加载，navigate 完成仅表示 DOM 就绪，不代表内容已渲染完成。以下策略可显著提升动态页面操作成功率：

场景一：导航后内容未加载

Copy code
1. navigate(url)                      → domcontentloaded 返回，但元素列表可能为空
2. wait(2000)                         → 等待异步内容渲染
3. get_state                          → 获取实际渲染后的元素列表

• navigate 后若 get_state 返回元素过少或 textContent 为空，说明页面尚未渲染完成
• 此时先 wait(1500~3000) 再 get_state，不要在空页面上盲目操作

场景二：点击后结果未出现

Copy code
1. click(e_login)                     → 触发登录请求
2. wait(2000)                         → 等待响应和页面更新
3. get_state                          → 确认是否登录成功/是否出现错误提示

• 点击触发异步操作（提交、搜索、展开）后，必须 wait + get_state 复查
• 不要连续点击多个元素而不复查——中间状态可能已变化导致后续元素 ID 失效

场景三：元素在视口外

Copy code
1. get_state                          → 目标元素不在列表中（elementsTruncated 或在视口外）
2. scroll(down, 500)                  → 向下滚动
3. get_state                          → 新元素进入视口，重新获取 ID

• get_state 只返回可见且可交互的元素（getBoundingClientRect 宽高 > 0 且非 display:none/visibility:hidden）
• 懒加载列表、折叠菜单中的元素需先 scroll 或先 click 展开后才能获取到

场景四：弹窗/对话框处理

Copy code
1. click(e_submit)                    → 触发操作
2. get_state                          → 出现确认弹窗 / 错误提示
3. 根据弹窗内容决策 → click(e_confirm) 或 click(e_close)

• 操作后出现的弹窗、toast、模态框会改变 DOM，必须 get_state 重新识别

反模式（避免）：

• ❌ navigate 后立即 click——页面可能还没渲染出元素
• ❌ 连续 click、type 多个元素中间不 get_state——ID 已失效
• ❌ 操作失败后用相同参数无限重试——应先 get_state 分析当前状态再调整
• ❌ 用 wait(10000) 一次等满——分段 wait + get_state 更高效且能及时响应

3.6 type 输入的正确姿势

type 操作是追加输入，不会自动清空元素现有内容。这是导致表单填写失败的常见原因。

标准输入流程（清空后输入）：

Copy code
1. click(e_input)                     → 聚焦目标输入框
2. press_key("Control+A")             → 全选现有内容
3. type(e_input, "新内容")             → 输入会替换选中的内容

或使用 Backspace 清空：

Copy code
1. click(e_input)
2. press_key("Control+A") → press_key("Backspace")  → 清空
3. type(e_input, "新内容")

特殊输入场景：

• 下拉选择框（select）：type 可能无效，应 click 展开选项后 click 目标选项元素
• 富文本编辑器：contenteditable 元素可用 type，但格式化需配合 press_key
• 搜索框 + 自动补全：输入后等待补全列表出现，get_state 获取补全项再 click
• 密码字段：get_state 返回的 value 为输入框当前真实内容（无屏蔽），密码输入后复查页面时 value 会回显明文——不要在回复或写入文件时复述该值；定位密码框用 type 字段（type="password"）或 placeholder

3.7 元素不可识别时的处理优先级（关键）

当 get_state 返回的元素列表中找不到目标元素时，严格按以下优先级处理，禁止跳级：

1. 优先：复查 get_state — 目标元素可能在视口外（先 scroll）、未渲染完成（先 wait）、或被折叠（先 click 展开父级）
2. 其次：click_selector — 确认元素存在但未被识别时，用 CSS 选择器直接点击
3. 最后：eval_in_page - 需要复杂 DOM 操作时（如读取 Shadow DOM、多步交互、自定义事件触发），在浏览器上下文执行 JS

补充：click_at 坐标点击的适用场景：当目标元素位置稳定可预测（如循环答题的固定选项区域、分页采集的"下一页"按钮固定坐标）时，可直接用 click_at(x, y) 省去前置 get_state。但坐标点击对窗口缩放/响应式断点/懒加载位置漂移敏感，动态布局页面仍优先用 click/click_selector 定位。

严禁的回退路径：

• ❌ 禁止 write_file 写 puppeteer/CDP 脚本到工作空间再 run_command 执行——这是被明确禁止的污染行为
• ❌ 禁止用 run_javascript 尝试操作页面 DOM——run_javascript 是 Node 沙箱，非浏览器上下文

click_selector 和 eval_in_page 已覆盖所有原本需要落盘脚本才能完成的操作，没有任何理由再落盘。

4. 安全约束（最高优先级，必须遵守）

• 不自动提交涉及支付、转账、注销、删除数据等敏感操作的表单，先明确询问用户
• 从知识库获取的凭据仅用于当前任务，不在回复中回显、不写入 write_file
• 操作类 action（navigate/click/click_selector/type/scroll/press_key/go_back/new_tab/eval_in_page/launch/close/click_at/run_script）默认需要用户确认；只读 action（get_state/screenshot/extract_content/wait/wait_for_selector/wait_for_text/get_console_logs/get_network_logs/get_network_request）无需确认
• 凭据类知识库条目建议用户标注 tags 如 credentials 便于管理
• 不在公共页面（论坛评论、搜索框等）输入敏感信息
• 浏览器使用隔离的独立用户数据目录（browser-profile），不复用用户 Chrome Profile；已登录状态不会跨会话保留
• 登录失败连续 2 次时停止自动重试，向用户报告避免触发风控冻结账号
• 涉及验证码、短信验证、二次验证时，向用户说明并等待人工处理，不要模拟绕过
• 严禁为操作浏览器而 write_file 写 JS 脚本到工作空间
• 如需在页面执行 JavaScript，必须使用 eval_in_page action

5. 与其他工具的协同

5.1 与 query_knowledge_base 协同（核心场景）

执行浏览器任务前，先查询本地知识库获取相关信息：

• 登录凭据：用户可在知识库中存储目标网站的账号密码
• 操作手册：用户可在知识库中存储目标网站的操作步骤指南
• 测试用例：用户可在知识库中存储测试用例和预期结果

示例流程：

Copy code
1. query_knowledge_base("目标网站登录信息") → 获取账号密码
2. navigate("https://目标网站.com/login")
3. get_state → 获取登录表单元素
4. type(e1, 账号) → type(e2, 密码) → click(e3, 登录按钮)
5. get_state → 验证登录成功

5.2 与其他工具协同

6. 异常处理（速查）

高频失败场景速查如下，完整异常处理表见 docs/troubleshooting.md：

7. 扩展参考文档（按需用 read_skill_file 读取）

以下参考文档不随 SKILL.md 正文自动加载，需要时用 read_skill_file 工具读取（先 load_skill 本技能）：