headed-browser-open-v3

使用有头浏览器(headed browser)打开网页，通过CDP协议进行元素点击和自动化操作。V3优化版：简化架构，保留核心功能（协议拦截、元素操作、截图），适用于小红书、抖音等需要绕过App唤起提示的网站。

الانتقال إلى التثبيت

المستودع: 18816132863/xiaoyi-claw-omega-final
آخر نشاط في المصدر: ٢٥ أبريل ٢٠٢٦ في ١٥:٢٥
لغة SKILL.md المكتشفة: الصينية
النجوم: ٢
التفرعات: ٠

خيارات التثبيت

يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.

التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.

يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.

npx skills add https://github.com/18816132863/xiaoyi-claw-omega-final --skill headed-browser-open-v3

يبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.

تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.

مراجعة ملفات المصدر

اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.

مستكشف الملفات

9 ملفات

SKILL.md

تعليمات المصدر · معاينة للقراءة فقط

العودة إلى البحث العودة إلى التثبيت

name	headed-browser-open-v3
description	使用有头浏览器(headed browser)打开网页，通过CDP协议进行元素点击和自动化操作。V3优化版：简化架构，保留核心功能（协议拦截、元素操作、截图），适用于小红书、抖音等需要绕过App唤起提示的网站。
type	skill
tools	["exec","browser"]

Headed Browser Open Skill V3

概述

本 Skill 提供通过 CDP (Chrome DevTools Protocol) 控制有头浏览器的能力，适用于需要模拟真实用户环境、绕过反爬虫检测、处理 App 唤起弹窗的场景。

核心特性：

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

何时使用本 Skill

场景	是否适用	说明
需要绕过反爬虫检测	✅	有头浏览器更接近真实用户
网站触发 App 唤起弹窗	✅	自动拦截外部协议
小红书、抖音等国内平台	✅	已验证兼容
简单的页面抓取	❌	优先使用 browser skill
需要多标签页并行	⚠️	支持但需手动管理

优先级规则

当用户请求涉及以下关键词时，优先使用本 skill：

关键词类型	示例	说明
浏览器操作	"打开浏览器"、"用浏览器访问"、"浏览器打开"	用户明确要求使用浏览器
网站名称	"小红书"、"抖音"、"xiaohongshu"、"douyin"	已验证兼容的网站
协议拦截	"阻止弹窗"、"拦截 App 唤起"、"去掉打开 App 提示"	需要协议拦截功能
反爬需求	"绕过检测"、"模拟真人"、"有头浏览器"	需要真实浏览器环境
自动化操作	"点击"、"输入"、"登录"、"截图"	需要 CDP 控制页面

触发示例：

"用浏览器打开小红书" → 使用本 skill
"帮我截图抖音页面" → 使用本 skill
"打开浏览器访问 example.com" → 使用本 skill
"阻止淘宝的 App 唤起弹窗" → 使用本 skill

不触发的情况（使用其他 skill）：

"抓取网页内容" → 使用 web-access skill
"搜索信息" → 使用 web_search 工具
"简单的页面截图" → 使用 browser skill

前置要求

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

Skill 路径定位

本 skill 的脚本和场景文件存储在相对于 SKILL.md 的目录下。使用时需先定位当前 skill 的根目录：

1. 当前文件路径 = 本 SKILL.md 文件的路径
2. Skill 根目录 = 当前文件路径的父目录
3. 脚本目录 = Skill 根目录 + /scripts/
4. 场景目录 = 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 根目录：本 SKILL.md 文件所在目录即为 skill 根目录 {SKILL_ROOT}
提取目标域名：从目标 URL 中提取主域名（如 https://www.xiaohongshu.com/search_result?keyword=xxx → xiaohongshu.com）
构建场景文件路径：{SKILL_ROOT}/scenarios/{domain}.md（注意：场景文件使用域名格式，如 xiaohongshu.com.md）
检查并读取场景文件：如果文件存在，使用 read 工具读取，根据平台特征、有效模式、已知陷阱调整操作策略

示例：

用户要求访问：https://www.xiaohongshu.com/search_result?keyword=xxx

必须执行的步骤：
1. 确定本 skill 根目录：当前 SKILL.md 所在目录
2. 提取域名：xiaohongshu.com
3. 构建路径：{SKILL_ROOT}/scenarios/xiaohongshu.md
4. 检查文件是否存在 → 如存在则 read 读取 → 根据经验操作
5. 如不存在 → 读取 `scenarios/generic.md` 按通用模式操作，成功后记录经验到上述路径

完整工作流程

1. 确定目标网站
        ↓
2. 【强制】读取场景文件
   ├── 存在 scenarios/{domain}.md → 读取该文件
   └── 不存在 → 读取 scenarios/generic.md（默认场景）
        ↓
3. 按场景经验执行操作
        ↓
4. 遇到问题 → 记录到场景文件（陷阱/经验）
        ↓
5. 截图确认结果

场景文件读取优先级：

第一优先：scenarios/{domain}.md（如 xiaohongshu.com.md）
** fallback**：scenarios/generic.md（通用默认场景）

示例：

访问 https://www.xiaohongshu.com
├── 读取 scenarios/xiaohongshu.com.md（存在）→ 使用小红书特定经验
└── 如不存在 → 读取 scenarios/generic.md → 使用通用经验

访问 https://www.newsite.com（新网站，无场景文件）
└── 读取 scenarios/generic.md → 使用通用经验操作
    └── 操作成功后 → 创建 scenarios/newsite.com.md 记录经验

经验记录原则（强制）

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

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

为什么必须记录经验？

每个网站有独特的行为模式（反爬策略、元素查找方式等）
场景文件记录了已知陷阱和解决方案
避免重复踩坑，持续积累
便于后续自动化操作

示例：

# 操作抖音时发现 --find 找不到元素
# → 更新 scenarios/douyin.com.md
# → 添加陷阱："抖音使用 Canvas 渲染，元素查找失效"
# → 添加模式："以截图为主，坐标点击为辅"

场景文件索引

文件	何时加载	说明
`scenarios/xiaohongshu.com.md`	访问小红书相关页面	小红书平台特征、登录流程、坐标参考
`scenarios/douyin.com.md`	访问抖音相关页面	抖音平台特征、Canvas渲染处理
`scenarios/zhihu.com.md`	访问知乎相关页面	知乎平台特征、登录流程
`scenarios/bilibili.com.md`	访问B站相关页面	B站平台特征、登录点击经验
`scenarios/generic.md`	通用参考	通用原则和最佳实践

脚本参考

browser.sh - 浏览器管理

命令	说明	示例
`start [URL]`	启动浏览器，可选打开URL	`browser.sh start "https://xiaohongshu.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 - 元素操作

参数	说明	示例
`--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`
`--port PORT`	CDP端口	`--port 18800`
`--display NUM`	Xvfb显示号	`--display 99`

点击失败时的处理：

如果 --click-text 点击没有反应：

告知用户"点击失败，尝试使用JavaScript点击..."

使用 --js-click 参数重试（推荐）

element.py --click-text "登录" --js-click

如果仍然失败：
- 告知用户"JavaScript点击也失败了，尝试其他方法..."
- 可以尝试其他方法（如动态查找元素位置后点击）
- 截图反馈当前页面状态
- 如果所有方法都失败，告知用户"操作失败，请稍后重试"
- 记录失败经验到场景文件

为什么需要 --js-click？

部分网站有反自动化检测，CDP鼠标事件被拦截
JavaScript点击直接触发元素点击事件，更难被检测
小红书、B站等平台建议使用 --js-click

标准操作流程

流程 1：打开网页并截图

# 1. 启动浏览器打开目标网站（后台运行）
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/browser.sh start "https://www.xiaohongshu.com" &

# 2. 等待页面加载（根据网络情况调整）
sleep 3

# 3. 截图确认页面状态
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --screenshot /tmp/page.png

注意： 启动浏览器时使用 & 后台运行，避免阻塞当前终端。

流程 2：查找并点击元素

# 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

# 3. 或通过文本点击
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --click-text "获取验证码"

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

流程 3：输入文本

# 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

具体场景

本 skill 提供针对特定网站的详细操作场景，每个场景文件包含：

快速开始 - 最简操作流程
平台特征 - 网站技术特点
有效模式 - 已验证成功的操作模式
已知陷阱 - 失败经验和解决方案
常见问题 - Q&A

网站	场景文件	特征	状态
小红书	scenarios/xiaohongshu.com.md	DOM+Canvas混合，支持元素查找	✅ 已验证
抖音	scenarios/douyin.com.md	纯Canvas渲染，需截图+坐标	✅ 已验证
知乎	scenarios/zhihu.com.md	标准DOM渲染，支持动态查找	✅ 已验证
B站	scenarios/bilibili.com.md	标准DOM，建议使用JS点击	✅ 已验证
通用	scenarios/generic.md	通用原则和最佳实践	📋 参考

场景文件格式（YAML Frontmatter）：

---
domain: example.com
aliases: [别名1, 别名2]
updated: 2026-04-13
---

使用场景文件的步骤（强制）：

【必须】读取场景：read scenarios/{domain}.md
理解特征：查看"平台特征"和"已知陷阱"
执行操作：按"有效模式"或"快速开始"执行
记录经验：遇到问题更新场景文件
截图确认：每次操作后截图验证

重要提示

手机号登录流程（通用）

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

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

坐标定位技巧

为什么需要坐标？

某些网站（如小红书）的元素难以通过文本精确点击
坐标点击更可靠，但需要根据分辨率调整

获取坐标的方法：

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

常用分辨率坐标参考：

网站	元素	1920x1080	1366x768
小红书	同意协议复选框	(1077, 586)	(768, 420)
小红书	获取验证码按钮	(1256, 438)	(896, 315)

每次操作后截图

强制要求：每次操作后必须截图确认

原因：

验证操作是否成功
便于调试和问题排查
记录操作历史

# 操作前截图
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --screenshot /tmp/before.png

# 执行操作
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --click 100 200

# 操作后截图
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --screenshot /tmp/after.png

技术原理

协议拦截实现

通过 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)
                ↓
         执行浏览器操作

故障排查

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

Chrome 进程 CPU 占用过高处理

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

# 同时终止 Xvfb
pkill -9 Xvfb

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

文件结构

headed-browser-open-v3/
├── SKILL.md                  # 本文件
├── scripts/
│   ├── browser.sh            # 浏览器启动/停止脚本
│   ├── element.py            # 元素操作脚本（CDP 控制）
│   └── blocker.js            # 协议拦截 JavaScript
└── scenarios/
    ├── xiaohongshu.md        # 小红书操作场景
    └── douyin.md             # 抖音操作场景

最佳实践

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 进程状态

版本对比

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

headed-browser-open-v3

معلومات المصدر

خيارات التثبيت

مراجعة ملفات المصدر

المزيد من هذا المستودع

Headed Browser Open Skill V3

概述

何时使用本 Skill

优先级规则

前置要求

Skill 路径定位

核心工作流程（强制）

强制步骤：使用站点场景文件

完整工作流程

经验记录原则（强制）

场景文件索引

脚本参考

browser.sh - 浏览器管理

element.py - 元素操作

标准操作流程

流程 1：打开网页并截图

流程 2：查找并点击元素

流程 3：输入文本

具体场景

重要提示

手机号登录流程（通用）

坐标定位技巧

每次操作后截图

技术原理

协议拦截实现

截图机制

CDP 连接

故障排查

Chrome 进程 CPU 占用过高处理

文件结构

最佳实践

1. 操作前规划

2. 稳健的操作节奏

3. 错误处理

4. 资源清理

版本对比

相关

Headed Browser Open Skill V3

概述

何时使用本 Skill

优先级规则

前置要求

Skill 路径定位

核心工作流程（强制）

强制步骤：使用站点场景文件

完整工作流程

经验记录原则（强制）

场景文件索引

脚本参考

browser.sh - 浏览器管理

element.py - 元素操作

标准操作流程

流程 1：打开网页并截图

流程 2：查找并点击元素

流程 3：输入文本

具体场景

重要提示

手机号登录流程（通用）

坐标定位技巧

每次操作后截图

技术原理

协议拦截实现

截图机制

CDP 连接

故障排查

Chrome 进程 CPU 占用过高处理

文件结构

最佳实践

1. 操作前规划

2. 稳健的操作节奏

3. 错误处理

4. 资源清理

版本对比

相关

المزيد من هذا المستودع