Run any Skill in Manus with one click

Get Started

headed-browser-open-v3

使用有头浏览器(headed browser)打开网页，通过CDP协议进行元素点击和自动化操作。V3优化版：简化架构，保留核心功能（协议拦截、元素操作、截图），适用于复杂网页场景，特别是需要处理App唤起提示或特殊渲染的页面。

Run Skill in Manus

Overview

Install command

npx skills add https://github.com/18816132863/pigeon-king --skill headed-browser-open-v3

Copy and paste this command into Claude Code to install the skill

Source

18816132863/pigeon-king

Stars0

Forks0

UpdatedMay 3, 2026 at 14:59

File Explorer

13 files

SKILL.md

readonly

Headed Browser Open Skill V3

概述

本 Skill 提供通过 CDP (Chrome DevTools Protocol) 控制有头浏览器的能力，适用于需要模拟真实用户环境、处理 App 唤起弹窗、操作复杂交互页面的场景。

核心特性：

真实 Chrome 浏览器（非 headless），更接近真实用户环境
CDP 协议控制，支持元素查找、点击、输入、截图
自动拦截外部协议弹窗（weixin://, taobao:// 等）
Xvfb 虚拟显示支持，无需物理显示器

使用指南

何时使用本 Skill

场景	是否适用	说明
需要模拟真实浏览器环境	✅	有头浏览器更接近真实用户
网站触发 App 唤起弹窗	✅	自动拦截外部协议
复杂交互页面（登录、表单等）	✅	已验证兼容多种平台
简单的页面抓取	❌	优先使用 browser skill
需要多标签页并行	⚠️	支持但需手动管理

触发关键词：

浏览器操作："打开浏览器"、"用浏览器访问"
复杂页面："登录页面"、"表单填写"、"需要点击的页面"
协议拦截："阻止弹窗"、"拦截 App 唤起"
渲染问题："页面显示异常"、"需要真实浏览器"

前置要求

# Ubuntu/Debian
apt-get update
apt-get install -y xvfb google-chrome-stable python3-pip
pip3 install websocket-client

核心概念

路径定位

当前文件路径 = 本 SKILL.md 文件的路径
Skill 根目录 = 当前文件路径的父目录
脚本目录 = Skill 根目录 + /scripts/
场景目录 = Skill 根目录 + /scenarios/

示例：

当前文件: ~/.openclaw/workspace/skills/headed-browser-open-v3/SKILL.md
Skill 根目录: ~/.openclaw/workspace/skills/headed-browser-open-v3/
脚本目录: ~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/
场景目录: ~/.openclaw/workspace/skills/headed-browser-open-v3/scenarios/

场景文件机制

【强制】每次操作前必须读取场景文件：

确定 Skill 根目录
提取目标域名
构建场景文件路径：{SKILL_ROOT}/scenarios/{domain}.md
读取场景文件（存在则读取，不存在则读取 scenarios/generic.md）

场景文件索引：

文件	何时加载	说明
`scenarios/platform-type-a.md`	类型A网站	标准登录流程、DOM渲染
`scenarios/platform-type-b.md`	类型B网站	Canvas渲染处理
`scenarios/platform-type-c.md`	类型C网站	复杂交互、建议使用JS点击
`scenarios/generic.md`	通用参考	通用原则和最佳实践

支持多网站场景，根据访问的域名自动匹配对应的场景配置。

工具脚本

browser.sh - 浏览器管理

命令	说明	示例
`start [URL]`	启动浏览器，可选打开URL	`browser.sh start "https://example.com"`
`status`	检查运行状态	`browser.sh status`
`stop`	停止浏览器	`browser.sh stop`

环境变量：

变量	默认值	说明
`CDP_PORT`	18800	CDP 调试端口
`DISPLAY_NUM`	99	Xvfb 显示号
`SCREEN_WIDTH`	1920	屏幕宽度
`SCREEN_HEIGHT`	1080	屏幕高度

element.py - 元素操作

参数	说明	示例
`--list-tabs`	列出所有标签页	`--list-tabs`
`--find-tab URL`	根据URL查找标签页	`--find-tab "example.com"`
`--find TEXT`	查找包含指定文本的元素	`--find "登录,手机号"`
`--click X Y`	点击指定坐标	`--click 1077 586`
`--click-text TEXT`	点击包含指定文本的元素	`--click-text "获取验证码"`
`--js-click`	使用JavaScript点击（更可靠）	`--click-text "登录" --js-click`
`--type TEXT`	在当前焦点元素输入文本	`--type "13800138000"`
`--screenshot PATH`	截图保存	`--screenshot /tmp/page.png`
`--snapshot`	打印 Playwright 风格页面快照	`--snapshot`
`--full-content`	打印完整内容（主页面+所有iframe）	`--full-content`

点击失败处理：

告知用户"点击失败，尝试使用JavaScript点击..."
使用 --js-click 参数重试
如仍失败，截图反馈当前状态

element_iframe.py - iframe 处理

参数	说明	示例
`--list-frames`	列出所有 frames	`element_iframe.py --list-frames`
`--iframe PATTERN`	指定 iframe (URL/name匹配)	`--iframe "x-URS"`
`--find-elements`	查找 iframe 内元素	`--iframe "163" --find-elements`
`--click-text TEXT`	点击 iframe 内元素	`--iframe "dl.reg" --click-text "登录"`
`--type TEXT`	在 iframe 输入框输入	`--iframe "x-URS" --type "email@163.com"`

Playwright 风格对比：

Playwright API	element_iframe.py 等效
`page.frames`	`--list-frames`
`page.frame_locator('iframe')`	`--iframe "pattern"`
`frame.locator('input').click()`	`--click-text "placeholder"`
`frame.fill('input', 'text')`	`--type "text"`

操作流程

标准流程：打开网页并截图

【重要】打开网页前先检查现有标签页：

# 1. 检查是否已有匹配的标签页
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --list-tabs
# 或使用 --find-tab 查找特定页面
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --find-tab "example.com"

# 2. 如果已有匹配标签页，直接操作现有页面
# 如果没有，再启动新浏览器
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/browser.sh start "https://example.com/login" &

# 3. 等待页面加载
sleep 3

# 4. 截图确认
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --screenshot /tmp/page.png

标准流程：查找并点击元素

# 1. 查找页面元素
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --find "登录,手机号"

# 2. 点击元素（坐标或文本）
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --click 1077 586
# 或
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --click-text "获取验证码" --js-click

# 3. 截图确认
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --screenshot /tmp/after_click.png

标准流程：输入文本

# 1. 点击输入框获取焦点
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --click 960 438

# 2. 输入文本
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --type "13800138000"

# 3. 截图确认
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --screenshot /tmp/after_type.png

重要提示

手机号登录流程（通用）

必须先勾选"我已阅读并同意"，再点击"获取验证码"！

顺序	操作	说明
1	输入手机号	在手机号输入框输入
2	勾选同意协议	⚠️ 必须先勾选
3	点击获取验证码	此时按钮才可点击

坐标定位技巧

获取坐标的方法：

先截图查看当前页面状态
使用图像编辑工具测量目标位置
或使用 --find 查看元素大致位置

常用分辨率坐标参考：

分辨率	元素类型	1920x1080	1366x768
高分辨率	复选框区域	(1077, 586)	(768, 420)
高分辨率	按钮区域	(1256, 438)	(896, 315)

强制截图要求

每次操作后必须截图确认

# 操作前截图
element.py --screenshot /tmp/before.png

# 执行操作
element.py --click 100 200

# 操作后截图
element.py --screenshot /tmp/after.png

二维码刷新注意事项

当用户要求"刷新二维码"时，注意区分以下情况：

情况	判断方法	操作方式
页面整体刷新	整个页面重新加载，URL 不变	使用 `browser.sh start <URL>` 重新打开
点击刷新按钮	二维码区域有刷新/换一张按钮	使用 `element.py --click-text "刷新"` 或 `--click` 点击按钮
二维码自动过期	页面提示二维码已过期	先截图确认，再点击刷新按钮

常见误区：

❌ 直接刷新整个页面（会丢失已填写的表单数据）
✅ 先截图确认页面状态，找到刷新按钮并点击

建议操作流程：

# 1. 先截图查看当前状态
element.py --screenshot /tmp/qr_status.png

# 2. 查找刷新按钮
element.py --find "刷新,换一张,重新加载"

# 3. 点击刷新按钮（而非刷新整个页面）
element.py --click-text "刷新"

# 4. 确认新二维码已生成
element.py --screenshot /tmp/qr_new.png

页面内容识别

为什么需要同时获取主页面和 iframe 内容？

现代网站广泛使用 iframe 来隔离内容（如登录框、支付表单、第三方嵌入）。仅查看主页面内容会遗漏关键信息：

场景	主页面可见	iframe 内容	示例
163 邮箱登录	空白或提示	完整的登录表单	登录 iframe
小红书授权	授权按钮	授权详情和确认	第三方登录
支付页面	订单信息	支付密码输入	支付 iframe

获取完整页面内容

使用 --full-content 参数同时获取主页面和所有 iframe 的内容：

~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --full-content

输出示例：

======================================================================
📄 完整页面内容分析
======================================================================

🌐 主页面: 示例网站
   URL: https://example.com

   🌳 无障碍树: 15 个元素
      [1] [heading] '欢迎登录'
      [2] [textbox] '请输入手机号'
      [3] [button] '获取验证码'

📦 发现 2 个 iframe:

   ┌─ iframe [1] login-frame
   │  URL: https://login.example.com/form
   │  标题: 安全登录
   │  内容: 请输入您的账号和密码...
   │  元素: 5 个
   │    [1] INPUT[text]: '邮箱/手机号'
   │    [2] INPUT[password]: '密码'
   │    [3] BUTTON: '登录'
   │    [4] A: '忘记密码'
   └─

   ┌─ iframe [2] captcha-frame
   │  URL: https://captcha.example.com/verify
   │  ⚠️  无法访问: 跨域限制
   └─

======================================================================

页面快照对比

参数	用途	适用场景
`--snapshot`	Playwright 风格快照（主页面无障碍树）	快速查看主页面结构
`--full-content`	主页面 + 所有 iframe 完整内容	识别登录框、嵌套表单
`--find TEXT`	搜索特定元素	定位已知元素

邮箱登录示例（含 iframe）

# 1. 打开登录页面
browser.sh start "https://example.com/mail" &
sleep 3

# 2. 获取完整内容（发现登录在 iframe 中）
element.py --full-content
# 输出显示：
# 📦 发现 3 个 iframe:
#    ┌─ iframe [3] login-frame...
#    │  URL: https://login.example.com/...
#    │  元素: INPUT[text]: '邮箱/手机号'
#    │         INPUT[password]: '密码'
#    │         BUTTON: '登录'

# 3. 在 iframe 中输入账号
element_iframe.py --iframe "login" --type "your_email@example.com"

# 4. 点击登录
element_iframe.py --iframe "login" --click-text "登录"

技术原理

协议拦截实现

通过 Chrome 启动参数 --inject-js 在页面加载前注入 blocker.js：

// 劫持 window.location
Object.defineProperty(window, 'location', {
    set: function(url) {
        if (url && !url.match(/^https?:\/\//i)) {
            console.log('[Blocker] Blocked:', url);
            return; // 阻止非 HTTP 协议
        }
        window.location.href = url;
    }
});

拦截范围：

window.location setter
window.open()
<a> 标签点击事件

截图机制

--screenshot 执行流程：
1. 尝试 CDP 截图 (Page.captureScreenshot)
2. 成功 → 保存退出
3. 失败 → 回退到 Xvfb 截图 (import -window root)
4. 都失败 → 报错退出

CDP 连接

element.py → WebSocket → Chrome CDP (port 18800)
                ↓
         执行浏览器操作

iframe 处理原理

Frame 树获取：

CDP Page.getFrameTree
    ↓
返回: { frame, childFrames: [ { frame, childFrames... } ] }
    ↓
递归遍历得到所有 frames

163 邮箱 iframe 结构示例：

https://mail.163.com/ (主页面)
├── iframe: frameforlogin (about:blank)
├── iframe: frameJS6 (preload6.htm)
└── iframe: x-URS-iframe... (dl.reg.163.com) ← 登录表单
    ├── input: 邮箱/手机号
    ├── input: 密码
    ├── input: 验证码
    └── checkbox: 十天内免登录

故障排查

问题	可能原因	解决方案
浏览器启动失败	Xvfb 未安装	`apt-get install xvfb`
CDP 连接失败	浏览器未启动或端口冲突	检查 `browser.sh status`，更换 `CDP_PORT`
元素找不到	页面未加载完成	增加 `sleep` 等待时间
点击无反应	坐标不正确	先截图确认元素位置，调整坐标
输入文本失败	输入框未获得焦点	先点击输入框再输入
截图失败	CDP 和 Xvfb 都不可用	检查 `DISPLAY` 环境变量
Chrome CPU 占用高	页面卡死或内存泄漏	`pkill -9 chrome` 强制终止

强制终止 Chrome

# 强制终止所有 Chrome 进程
pkill -9 chrome

# 同时终止 Xvfb
pkill -9 Xvfb

# 检查残留进程
ps aux | grep -E "chrome|Xvfb" | grep -v grep

空闲自动回收

默认行为： 浏览器启动后，如果 1 小时内没有任何操作，会自动停止浏览器和 Xvfb 以释放资源。

触发操作（会重置计时器）：

任何 element.py 操作（点击、输入、截图等）
列出标签页 (--list-tabs)
查找元素 (--find)

手动控制空闲超时：

# 设置 30 分钟超时（默认 1 小时）
export IDLE_TIMEOUT=1800
browser.sh start

# 禁用自动回收（不推荐）
export IDLE_TIMEOUT=0

监控日志：

# 查看空闲监控日志
tail -f /tmp/idle-monitor.log

最佳实践

1. 操作前规划

明确目标：需要打开什么页面？执行什么操作？
检查是否有对应场景文件
预估操作步骤和等待时间

2. 稳健的操作节奏

# 好：每步操作后等待并截图
browser.sh start URL
sleep 3
element.py --screenshot step1.png
element.py --click 100 200
sleep 1
element.py --screenshot step2.png

# 不好：连续操作不等待
browser.sh start URL
element.py --click 100 200
element.py --type "text"  # 可能页面还没加载完

3. 错误处理

操作失败后先截图查看当前状态
检查浏览器是否仍在运行
必要时重启浏览器

4. 资源清理

任务完成后执行 browser.sh stop 清理资源
长时间运行的任务定期检查 Chrome 进程状态

5. 经验记录

操作中发现新问题 → 立即更新场景文件：

失败经验 → 添加到"已知陷阱"章节
成功经验 → 添加到"有效模式"章节
坐标/参数调整 → 更新对应表格

文件结构

headed-browser-open-v3/
├── SKILL.md                          # 本文件
├── scripts/
│   ├── browser.sh                    # 浏览器启动/停止脚本
│   ├── element.py                    # 元素操作脚本
│   ├── element_iframe.py             # iframe 处理脚本
│   ├── idle-monitor.sh               # 空闲监控和资源回收
│   ├── blocker.js                    # 协议拦截 JavaScript
│   └── playwright_iframe_demo.py     # Playwright iframe 示例
└── scenarios/
    ├── platform-type-a.md            # 类型A网站场景
    ├── platform-type-b.md            # 类型B网站场景
    ├── platform-type-c.md            # 类型C网站场景
    └── generic.md                    # 通用场景

附录

Playwright iframe 处理

脚本位置： scripts/playwright_iframe_demo.py

运行示例：

# 安装依赖
pip3 install playwright
playwright install chromium

# 运行示例
cd ~/.openclaw/workspace/skills/headed-browser-open-v3
python3 scripts/playwright_iframe_demo.py

API 对比：

功能	CDP (本 skill)	Playwright
获取 frame 树	`Page.getFrameTree`	`page.main_frame` + `frame.child_frames`
进入 iframe	手动切换 context	`page.frame_locator(selector)`
操作 iframe 元素	`Runtime.evaluate`	`frame_locator.locator().click()`
跨域处理	需创建独立 session	自动处理

版本对比

特性	V2	V3
核心功能	✅	✅
代码复杂度	较高	简化
场景文件	强制使用	参考使用
架构	复杂	精简
维护性	一般	更好

name	headed-browser-open-v3
description	使用有头浏览器(headed browser)打开网页，通过CDP协议进行元素点击和自动化操作。V3优化版：简化架构，保留核心功能（协议拦截、元素操作、截图），适用于复杂网页场景，特别是需要处理App唤起提示或特殊渲染的页面。
type	skill
tools	["exec","browser"]

headed-browser-open-v3

More from this repository

Headed Browser Open Skill V3

概述

使用指南

何时使用本 Skill

前置要求

核心概念

路径定位

场景文件机制

工具脚本

browser.sh - 浏览器管理

element.py - 元素操作

element_iframe.py - iframe 处理

操作流程

标准流程：打开网页并截图

标准流程：查找并点击元素

标准流程：输入文本

重要提示

手机号登录流程（通用）

坐标定位技巧

强制截图要求

二维码刷新注意事项

页面内容识别

为什么需要同时获取主页面和 iframe 内容？

获取完整页面内容

页面快照对比

推荐识别流程

邮箱登录示例（含 iframe）

技术原理

协议拦截实现

截图机制

CDP 连接

iframe 处理原理

故障排查

强制终止 Chrome

空闲自动回收

最佳实践

1. 操作前规划

2. 稳健的操作节奏

3. 错误处理

4. 资源清理

5. 经验记录

文件结构

附录

Playwright iframe 处理

版本对比

相关链接

Headed Browser Open Skill V3

概述

使用指南

何时使用本 Skill

前置要求

核心概念

路径定位

场景文件机制

工具脚本

browser.sh - 浏览器管理

element.py - 元素操作

element_iframe.py - iframe 处理

操作流程

标准流程：打开网页并截图

标准流程：查找并点击元素

标准流程：输入文本

重要提示

手机号登录流程（通用）

坐标定位技巧

强制截图要求

二维码刷新注意事项

页面内容识别

为什么需要同时获取主页面和 iframe 内容？

获取完整页面内容

页面快照对比

推荐识别流程

邮箱登录示例（含 iframe）

技术原理

协议拦截实现

截图机制

CDP 连接

iframe 处理原理