# Webclaw3 > 浏览器自动化 / 网页数据采集 / 爬虫抓取——用你自己的 Chrome 和已登录状态干活，不用重新登录、不用交账号密码、不怕反爬。所有需要操作浏览器的活都走这个 skill。 场景一（日常上网干活）：搜东西、看网页、查数据、抓列表、导表格、下载内容，或者在网站里动手操作——点按钮、填表单、发内容、和商家聊天；包括必须登录才能看的页面，如小红书、抖音、微博、推特(X)、知乎、B站、公众号、淘宝、拼多多、Shopify 后台等。 场景二（沉淀成 skill）：任务跑通了，用户说"帮我提炼""以后每天自动跑"，把这次探索固化成可反复运行、零 token 的本地脚本 skill，可配定时任务。 场景三（修复）：网站改版导致之前生成的 skill 跑失败了，用户来找修，本地直接修好。 (EN) Browser automation and web scraping that drives your own logged-in Chrome — explore once, distill it into a free, deterministic skill you can rerun daily. - Skill: `fatmind/webclaw3` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add fatmind/webclaw3` - Raw SKILL.md: https://api.skillmd.com/api/skills/fatmind/webclaw3/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: fatmind (https://skillmd.com/u/fatmind) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/fatmind/webclaw3 --- # webclaw3 — 浏览器自动化 · 用你自己的 Chrome 登录态 > 让 AI 用你**已经登录**的 Chrome 干活：搜索、抓数据、点按钮、发内容都行。跑通一次后说一句"帮我提炼"，它就变成零 token、每天能自动跑的本地 skill。 **能干什么（三个真实例子）** - 「把小红书搜索『显瘦连衣裙』前 50 条笔记的标题、点赞数、作者导成表格」——需要登录才能看的页面照样抓。 - 「每天早上 8 点把 SkillHub 下载热榜前 10 拉下来发我」——提炼成 skill 之后定时跑，零 token、毫秒级返回。 - 「打开我的 Shopify 后台，把昨天的订单整理成日报」——直接操作你已登录的后台，账号密码不用交给任何人。 **装起来要几步（先说清楚，别踩坑）**：三步、大约 5 分钟。① 装 Chrome 扩展（开发者模式加载一次）；② 到 [webclaw3.com](https://webclaw3.com) 领 Access Key（免费 10 次生成额度）；③ 对你的 Agent 说一句"帮我装 webclaw3 并检查环境"。装完就在对话框里说人话使唤它。 **和其它浏览器工具差在哪**：它不会另开一个干净浏览器让你重新登录，而是**接管你自己那个已经登录好的 Chrome**；另外自带**站点经验库**——别人探索过的站点结构你可以直接复用，生成更快、更稳。 --- > 以上是给人看的介绍。**Agent 从下面这一节开始读。** ## 四环节总览（先读这个） webclaw3 覆盖「探索 → 提炼 → 日常跑 → 修复」完整动线，四个环节： | 环节 | 什么时候进入 | 指引在哪 | |---|---|---| | ① 安装启动 | 首次使用，或前置检查不通过 | Read `references/setup.md` | | ② 探索 | 用户提出联网任务（高频，日常主体） | 本文正文 | | ③ 提炼 | 探索成功后，用户说"提炼成 skill / 以后自动跑" | Read `references/brief.md` | | ④ 问题修复 | 之前生成的 skill 运行失败 | Read `references/repair.md` | 用户动线：装好通道（①）→ 自然语言探索、拿到用户确认满意的结果（②）→ 一句"帮我提炼"变成可反复跑的 skill（③）→ skill 日常运行，出问题先本地修（④）。 ①③④ 低频，对应文件遇到场景时再 Read，不要提前加载。`references/` 目录与本文件同级。 > **和用户说话，永远用大白话（贯穿全程，极重要）** > 把用户当成一个不懂技术的普通人，不是程序员。无论转达 doctor 的建议、报错、还是进度，都要翻译成简短、口语化的人话，告诉他"下一步点哪、做什么"就够了。**不要**把原始 JSON、日志路径、端口号、tarball / npm / PATH 这类术语甩给用户。一次只说重点，能一句话讲清就别写三句。（文末还有一条同样的提醒。） ## 前置检查 本 skill 的 CLI 就在 skill 目录的 `scripts/` 下，用 node 直接跑——**不需要也不要做任何 PATH / npm link / 全局安装**，也不要向用户提议。下文所有 `webclaw3 <子命令>` 写法均指： ```bash node <本 skill 目录>/scripts/webclaw3.mjs <子命令> ``` skill 安装完成后、以及每次开始联网操作前，**直接跑下面这条，不用询问用户要不要检查**： ```bash node <本 skill 目录>/scripts/webclaw3.mjs doctor # → {"ok":true,...} 即可开始操作 ``` doctor 会自动拉起 relay；`ok:false` 时输出里有 advice（Chrome 没开 / 扩展未装 / 被禁用等），需要引导用户人工处理的场景 Read `references/setup.md`。 > 本 skill 的脚本（relay、cdp-proxy、webclaw3 CLI）全部在 skill 目录的 `scripts/` 下，自包含；Chrome 扩展是独立安装的 wc3-chrome（安装方式见 `references/setup.md`）。 ## 浏览哲学 **像人一样思考，兼顾高效与适应性的完成任务。** 执行任务时不会过度依赖固有印象所规划的步骤，而是带着目标进入，边看边判断，遇到阻碍就解决，发现内容不够就深入——全程围绕「我要达成什么」做决策。这个 skill 的所有行为都应遵循这个逻辑。 **① 拿到请求** — 先明确用户要做什么，定义成功标准：什么算完成了？需要获取什么信息、执行什么操作、达到什么结果？这是后续所有判断的锚点。 **② 选择起点** — 根据任务性质、平台特征、达成条件，选一个最可能直达的方式作为第一步去验证。一次成功当然最好；不成功则在③中调整。比如，需要操作页面、需要登录态、已知静态方式不可达的平台（小红书、微信公众号等）→ 直接用浏览器中继 **③ 过程校验** — 每一步的结果都是证据，不只是成功或失败的二元信号。用结果对照①的成功标准，更新你对目标的判断：路径在推进吗？结果的整体面貌（质量、相关度、量级）是否指向目标可达？发现方向错了立即调整，不在同一个方式上反复重试——搜索没命中不等于"还没找对方法"，也可能是"目标不存在"；API 报错、页面缺少预期元素、重试无改善，都是在告诉你该重新评估方向。遇到弹窗、登录墙等障碍，判断它是否真的挡住了目标：挡住了就处理，没挡住就绕过——内容可能已在页面 DOM 中，交互只是展示手段。 **条件不可达时重新评估，不死磕：** 当严格筛选条件下数据量确实不足（如"近一周+点赞>500"只有 3 条，目标要求 >=10），这不是技术问题而是数据现实。此时应主动向用户说明实际情况，并建议放宽条件（扩大时间范围、降低阈值），而不是在同一条件下反复翻页、换入口死磕。用户的验收标准是可以协商的，数据的客观存在量不是。 **④ 完成判断** — 对照定义的任务成功标准，确认任务完成后才停止，但也不要过度操作，不为了"完整"而浪费代价。 ## 联网工具选择 - **确保信息的真实性，一手信息优于二手信息**：搜索引擎和聚合平台是信息发现入口。当多次搜索尝试后没有质的改进时，升级到更根本的获取方式：定位一手来源（官网、官方平台、原始页面）。 | 场景 | 工具 | |------|------| | 搜索摘要或关键词结果，发现信息来源 | **WebSearch** | | URL 已知，需要从页面定向提取特定信息 | **WebFetch**（拉取网页内容，由模型直接提取，返回结果） | | URL 已知，需要原始 HTML 源码（meta、JSON-LD 等结构化字段） | **curl** | | 非公开内容，或已知静态层无效的平台（小红书、微信公众号等公开内容也被反爬限制） | **浏览器**（wc3-chrome 中继，跳过静态层） | | 需要登录态、交互操作，或需要像人一样在浏览器内自由导航探索 | **浏览器**（wc3-chrome 中继） | 浏览器中继不要求 URL 已知——可从任意入口出发，通过页面内搜索、点击、跳转等方式找到目标内容。WebSearch、WebFetch、curl 均不处理登录态。 > WebSearch / WebFetch 指宿主自带的搜索、网页读取工具。 ### 信息核实：定位一手来源 核实的目标是**一手来源**，而非更多的二手报道。多个媒体引用同一个错误会造成循环印证假象。 搜索引擎和聚合平台是**定位**信息的工具，不可用于直接**证明**真伪。找到来源后，直接访问读取原文。同一原则适用于工具能力/用法的调研——官方文档是一手来源，不确定时先查文档或源码，不猜测。 | 信息类型 | 一手来源 | |----------|---------| | 政策/法规 | 发布机构官网 | | 企业公告 | 公司官方新闻页 | | 学术声明 | 原始论文/机构官网 | | 工具能力/用法 | 官方文档、源码 | **找不到官网时**：权威媒体的原创报道（非转载）可作为次级依据，但需向用户说明："未找到官方原文，以下核实来自[媒体名]报道，存在转述误差可能。"单一来源时同样向用户声明。 ## 浏览器通道与 API 通过 Chrome 扩展走 WebSocket 中继到用户日常 Chrome，天然携带登录态，零授权弹窗，反检测隐身。 ### Relay API 通过 HTTP REST API 与 Relay 服务器交互（Relay 是已运行的 WebSocket 服务器，监听 ws://127.0.0.1:3459，同时暴露 HTTP 端口）： ```bash # 检查状态 curl -s http://127.0.0.1:3459/api/status # → {"extensionConnected":true,"wsPort":3459} # 通用调用格式：POST /api/call，body 为 JSON { "op": "操作名", "params": {...} } # 返回格式：{ "result": ... } 成功，{ "error": "..." } 失败 # 【硬性要求】任何浏览器操作（tab.create / page.* / site.*）之前，必须先 group.create 建本任务分组， # 并把返回的 groupId 带到后续所有 tab.create 与 page.* 调用，任务结束 group.close 整组关闭。 # 不建组的 tab 会混进共享默认组，与其他并行任务互相干扰。唯一例外：用户明确说不用分组。 # 记不住 groupId 时用 group.list 按组名找回（组名用任务主题命名）。详见「多任务隔离」一节。 # --- Tab 操作 --- curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"tab.list"}' curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"tab.list","params":{"groupId":GROUP_ID}}' # 只看某个任务组，隔离多任务 curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"tab.create","params":{"url":"https://example.com","active":false}}' curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"tab.create","params":{"url":"https://example.com","active":false,"groupId":GROUP_ID}}' # 建进指定任务组 curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"tab.setStatus","params":{"tabId":TAB_ID,"status":"running"}}' curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"tab.groupInfo"}' curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"tab.groupInfo","params":{"groupId":GROUP_ID}}' curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"tab.close","params":{"tabId":TAB_ID}}' # --- 任务分组（多任务隔离：每个任务一个分组）--- curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"group.create","params":{"name":"skillhub-trending"}}' # → {"groupId":...} curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"group.list"}' curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"group.setStatus","params":{"groupId":GROUP_ID,"status":"running"}}' curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"group.close","params":{"groupId":GROUP_ID}}' # 关闭该组所有 tab # --- 页面操作 --- # 动态 eval（核心，任意 JS 字符串）。page.* 都可带可选 groupId 做归属校验，防止误操作到别的任务的 tab curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"page.eval","params":{"tabId":TAB_ID,"code":"document.title","groupId":GROUP_ID}}' # Aria tree（DOM 遍历，ref_N 寻址） curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"page.ariaTree","params":{"tabId":TAB_ID,"filter":"interactive"}}' # 点击/滚动/填表（通过 ref_N 定位元素，React 安全） curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"page.click","params":{"tabId":TAB_ID,"ref":"ref_3"}}' curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"page.scrollTo","params":{"tabId":TAB_ID,"ref":"ref_5"}}' curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"page.fillForm","params":{"tabId":TAB_ID,"ref":"ref_2","value":"搜索内容"}}' # 关键词搜索页面元素 curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"page.search","params":{"tabId":TAB_ID,"query":"关键词"}}' # 等待元素出现 curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"page.waitForElement","params":{"tabId":TAB_ID,"selector":".item-card"}}' # 截图 curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"page.screenshot","params":{"tabId":TAB_ID}}' # 提取页面正文 curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"page.getText","params":{"tabId":TAB_ID}}' # 解除调试附加 curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"debug.detach","params":{"tabId":TAB_ID}}' ``` Node.js 脚本中用 fetch 封装： ```javascript const RELAY_URL = 'http://127.0.0.1:3459'; async function relayCall(op, params = {}, timeout = 30000) { const res = await fetch(`${RELAY_URL}/api/call`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ op, params, timeout }), }); const data = await res.json(); if (data.error) throw new Error(data.error); return data.result; } ``` ### 上下文集成变量（调用方声明时生效） 调用方可能在上文 `## 上下文变量` 里声明以下变量，从声明取值；未声明则忽略。 - **WC3_OPERATION_LOG**：operation_log 文件绝对路径。声明后，每个浏览器 API 调用都要带上 logFile 参数写入该文件： - Extension Relay：POST body 顶层加 `"logFile":"<声明的值>"` ```bash curl -s -X POST http://127.0.0.1:3459/api/call -d '{"op":"tab.create","params":{"url":"https://example.com"},"logFile":"<声明的值>"}' ``` - CDP HTTP 兜底：URL query 加 `?logFile=<声明的值>`（示例见 `references/cdp-fallback.md`） - 两个通道都会自动追加到同一文件；每条记录含 op / params / result / timestamp / channel / duration_ms。 （站点知识由下文 `## 站点知识` 节 + 声明的 `WC3_SITE_KNOWLEDGE` 覆盖，不在本节重复。） ### 错误处理 - 扩展未加载 → `/api/status` 返回 `extensionConnected: false`，跑 `webclaw3 doctor` 按 advice 引导用户（详见 `references/setup.md`） - 扩展被禁用/Service Worker 挂掉 → 第一次 op 返回错误，提示用户检查 `chrome://extensions/` - `page.eval` 抛错 → 直接拿到 JS 异常信息（含 className、message、stack），修复脚本重试 ### CDP 兜底通道 默认只用 Extension Relay。仅当 Extension 通道**整体**走不通（扩展未连、Service Worker 挂掉、eval 持续失败）时，回退 CDP HTTP 通道（`:3456`）继续操作——此时 Read `references/cdp-fallback.md`（启动、tab 映射、API、回退判定）。单次 `SyntaxError`、`tab not found` 属脚本问题，不回退。 ## 页面理解与数据提取 **`ariaTree` 和 `page.eval` 组合使用**，是理解和提取页面的两个核心能力： - **Aria 树做地图**：`page.ariaTree` 返回页面的压缩语义结构（role + name，~500 行 vs 原始 DOM ~10000 行）。进入新页面先看一次全貌——有哪些区域、多少数据项、分页结构、可交互元素，一次调用建立页面心智模型。**用于理解页面结构和定位交互元素，不用于提取结构化数据。** - **eval 做采矿**：`page.eval` 执行任意 JS，**是提取结构化数据的首选方式**——直接从 DOM 返回 JSON（name/href/price/downloads 等），保留完整属性，不受文本布局影响。同时覆盖 Aria 树触达不了的一切——穿透 SPA 框架数据层、操控 DOM 元素、执行复杂交互逻辑。 大多数任务都是 Aria 先看全貌、eval 再提取数据，两者交替推进。**先了解页面结构，再决定下一步动作**，不需要提前规划所有步骤。 ### Aria 树的格式与边界 **`ariaTree` 返回格式：** ``` [ref_1] heading "精选 TOP 50 AI Skills 榜单" [ref_2] list (options=8) [ref_3] listitem "Web Access ⭐ 1.4k ↓ 5.2k" [ref_4] listitem "DeepSearch ⭐ 892 ↓ 3.1k" [ref_13] button "下一页" [ref_14] textbox "搜索" ``` 每个节点有 `[ref_N]` 编号，可用于 `page.click(tabId, 'ref_N')` 和 `page.fillForm(tabId, 'ref_N', value)` 精确操作。 **Aria 的边界——什么时候该切 eval：** - Aria 树只有可见文本的语义摘要，不含 URL、隐藏属性、组件内部数据 - 动态弹出的面板（筛选、下拉菜单、模态框）可能不在 Aria 树中，click 会定位失败 - 展示文本（"31.7万"）和精确值（317000）不同，精确值要从数据层拿 ### 数据提取策略（page.eval 优先） **page.eval 是结构化数据提取的首选方式。** 扩展已通过 declarativeNetRequest 移除页面 CSP 头，page.eval 在绝大多数站点上可正常使用，正常情况下无需兜底到 CDP。直接从 DOM 提取结构化 JSON，不经过纯文本中间层——这样能保留 href、data-* 属性等 DOM 信息，且不受文本布局变化影响。（例外：若 Extension 通道整体不可用/持续失败，按 `references/cdp-fallback.md` 临时走 CDP 摸清页面结构，再切回 Relay。） `page.eval(code)` 在用户真实 Chrome 中执行任意 JS，用前记牢它的关键约束： - **支持任意 JS**：表达式、语句、async/await、throw、IIFE 都可以 - **绕过 CSP**：即使页面有 `unsafe-eval` 禁用也能跑 - **返回 JSON 可序列化值**：函数、DOM 节点、循环引用会失败 - **副作用在页面真实世界生效**（点击、表单提交、滚动、导航） | 层级 | 方法 | 适用场景 | |------|------|----------| | L1 | `page.eval` + CSS selector | **首选**——直接从 DOM 提取结构化数据（name/href/price 等），返回 JSON | | L2 | `page.ariaTree` 直读 | 只需看全貌、确认数据项数量/结构，或信息在可见文本中已足够 | | L3 | `page.eval` + 穿透框架数据层 | SPA 没有语义化 class，需要从 React fiber、Vue data、全局 store 等拿原始数据对象 | | L4 | 交互触发（`page.click`、翻页、滚动加载） | 数据需要交互才能出现 | L3 补充：很多 React/Vue SPA 的 class 是哈希值，DOM 层面无法可靠定位。React 的 `__reactFiber$` → `memoizedProps` 链路、Vue 的 `__vue__.$data`、以及 `window.__NEXT_DATA__` / `window.__INITIAL_STATE__` 等全局变量，都是穿透到原始数据的入口。具体怎么遍历需要根据目标页面的实际结构探索。 **媒体资源**：判断内容在图片里时，用 `page.eval` 从 DOM 直接拿图片 URL，再定向读取——比全页截图精准得多。 ### 渐进式提取工作流 面对陌生页面，提取分四步推进——先侦察、再定位、后取值、最后才决定要不要加工： ``` getText 侦察 page.eval 定位 textContent 取值 后处理决策 ──────────────── → ──────────────────── → ──────────────────── → ──────────────────── 拿整页纯文本 根据侦察结论 拿 DOM 节点原值 判断原值够不够用 理解页面结构 用 eval + DOM 位置定位 保留原始 textContent ├─ 够用 → 直接输出 找到数据在哪里 锁定目标节点 不做提前格式化 ├─ 需要拆 → split 哪些字段可取 ├─ 需要匹配 → regex └─ 需要理解 → LLM 总结 ``` 1. **getText 是合法的侦察手段**——面对陌生页面，`page.getText` 拿整页纯文本是最自然的"看一眼"方式，用来理解页面结构、确认数据在哪、有哪些字段可取。**但侦察 ≠ 提取**：侦察清楚后，真正取数据必须切到 `page.eval` 从 DOM 拿结构化 JSON。绝不要用 getText 拿纯文本再正则解析来提取结构化数据——那样丢失了所有 DOM 属性（href、class、data-*），只能靠文本布局匹配，极脆弱。 2. **textContent 原值优先**——`page.eval` 里先拿到原始字符串（如 `"99.7 万"`、`"43"`），再决定要不要进一步处理。不要在提取时就预设格式做转换。 3. **后处理是分层决策**——原值够用就直接输出；需要拆分用 `split`/`trim`；需要模式匹配才上 `regex`；需要"理解"内容（判断、归类、总结）才交给 LLM。不是所有场景都需要 regex。 > 边界提醒：这套工作流描述的是**人工浏览/交互过程**的推进方式。getText 侦察只发生在浏览探查期；**沉淀进可复用提取脚本的代码里只能有 page.eval**，不要把侦察用的 getText 调用抄进脚本。 ### 技术事实 - 页面中存在大量已加载但未展示的内容——轮播中非当前帧的图片、折叠区块的文字、懒加载占位元素等，它们存在于 DOM 中但对用户不可见。以数据结构（容器、属性、节点关系）为单位思考，可以直接触达这些内容。 - DOM 中存在选择器不可跨越的边界（Shadow DOM 的 `shadowRoot`、iframe 的 `contentDocument`等）。eval 递归遍历可一次穿透所有层级，返回带标签的结构化内容，适合快速了解未知页面的完整结构。 - `page.eval` 执行滚动到底部会触发懒加载，使未进入视口的图片完成加载。提取图片 URL 前若未滚动，部分图片可能尚未加载。 - 拿到媒体资源 URL 后，公开资源可直接下载到本地后用读取；需要登录态才可获取的资源才需要在浏览器内 navigate + screenshot。 - 短时间内密集打开大量页面（如批量 `tab.create`）可能触发网站的反爬风控。串行逐个处理是最安全的；如需并行，控制在 2-3 个 tab，避免短时间爆发。 - 平台返回的"内容不存在""页面不见了"等提示不一定反映真实状态，也可能是访问方式的问题（如 URL 缺失必要参数、触发反爬）而非内容本身的问题。 - 某些平台的 ID 中编码了时间戳（如小红书 note_id 前 8 位是 Unix 时间的十六进制）。当页面不直接展示时间字段时，可尝试从 ID 解码，避免逐个进详情页。 - 现代 Web 应用的输入框很多不是普通 `