jacardl web-access — qclaw 适配版
源自 eze-is/web-access，MIT 协议。
能力概览
| 场景 | 工具 | 说明 |
|---|---|---|
| 搜索摘要、关键词发现 | web_search |
搜索发现信息来源 |
| URL 已知，定向提取内容 | web_fetch |
拉取网页，由小模型提取，返回处理后结果 |
| 原始 HTML（meta、JSON-LD） | exec + curl |
获取结构化字段 |
| 非公开内容 / 反爬限制平台（小红书等） | CDP 浏览器 | 直连 Chrome，绕过静态层 |
| 需要登录态、交互操作 | CDP 浏览器 | 携带用户登录态操作页面 |
前提：环境检查
使用 CDP 之前，先检查 Node.js 和 Chrome 调试端口：
node --version # 需要 v22+
Chrome 调试端口检查（在 Chrome 地址栏打开）：
chrome://inspect/#remote-debugging
勾选 "Allow remote debugging for this browser instance"（可能需要重启浏览器）。
Windows 上常用调试端口：9222、9229、9333。
快速启动 CDP Proxy
CDP Proxy 脚本路径：
C:\Users\jacar\.qclaw\workspace\skills\web-access\scripts\cdp-proxy.mjs
启动命令：
node "C:\Users\jacar\.qclaw\workspace\skills\web-access\scripts\cdp-proxy.mjs"
Proxy 运行后通过 HTTP API 控制 Chrome，默认端口 3456。
浏览哲学
目标驱动，而非步骤驱动。 像人一样思考，兼顾高效与适应性。
- 明确目标 — 先定义成功标准：什么算完成了？需要获取什么信息、执行什么操作？
- 选择起点 — 根据任务性质选最可能直达的方式。一次不成功则调整方向。
- 过程校验 — 每一步结果都是证据。用结果对照目标：路径在推进吗？发现方向错了立即调整。
- 完成判断 — 对照成功标准确认完成，不要为"完整"而浪费代价。
CDP Proxy HTTP API
Proxy 地址：http://localhost:3456
端点列表
| 端点 | 方法 | 说明 |
|---|---|---|
/health |
GET | 健康检查，返回连接状态 |
/targets |
GET | 列出所有已打开的页面 tab |
/new?url=URL |
GET | 创建新后台 tab（自动等待加载） |
/close?target=ID |
GET | 关闭指定 tab |
/navigate?target=ID&url=URL |
GET | 在已有 tab 中导航（自动等待加载） |
/back?target=ID |
GET | 后退一页 |
/info?target=ID |
GET | 获取页面信息（title、url、readyState） |
/eval?target=ID |
POST | 执行 JavaScript（POST body 为 JS 代码） |
/click?target=ID |
POST | JS 层面点击（POST body 为 CSS 选择器） |
/clickAt?target=ID |
POST | 真实鼠标点击（CDP Input.dispatchMouseEvent） |
/setFiles?target=ID |
POST | 文件上传（POST body 为 JSON） |
/scroll?target=ID&y=3000 |
GET | 滚动页面（direction: down/up/top/bottom） |
/screenshot?target=ID&file=PATH |
GET | 截图（保存到本地文件） |
curl 调用示例
# 健康检查
curl -s http://localhost:3456/health
# 列出已打开的 tab
curl -s http://localhost:3456/targets
# 新建后台 tab 并打开网页
curl -s "http://localhost:3456/new?url=https://www.xiaohongshu.com"
# 执行 JS 读取页面标题
curl -s -X POST "http://localhost:3456/eval?target=TARGET_ID" -d "document.title"
# 点击元素
curl -s -X POST "http://localhost:3456/click?target=TARGET_ID" -d "button.submit"
# 真实鼠标点击（可触发文件对话框）
curl -s -X POST "http://localhost:3456/clickAt?target=TARGET_ID" -d "button.upload"
# 文件上传
curl -s -X POST "http://localhost:3456/setFiles?target=TARGET_ID" -d "{\"selector\":\"input[type=file]\",\"files\":[\"C:/path/to/file.png\"]}"
# 截图
curl -s "http://localhost:3456/screenshot?target=TARGET_ID&file=C:/tmp/shot.png"
# 滚动到页面底部
curl -s "http://localhost:3456/scroll?target=TARGET_ID&direction=bottom"
# 关闭 tab
curl -s "http://localhost:3456/close?target=TARGET_ID"
CDP 操作技巧
/eval — 核心操作
- 看：查询 DOM，发现页面上的链接、按钮、表单、文本内容
- 做：点击元素、填写输入框、提交表单
- 读：提取文字内容，判断图片/视频是否承载核心信息
判断用哪种工具
| 情况 | 推荐方式 |
|---|---|
| 程序化方式可行（URL 可直接访问） | web_fetch 或 exec + curl |
| 目标有反爬限制 | CDP 直接访问 |
| 需要登录态 | CDP（携带用户 Chrome 登录态） |
| 需要交互操作（点击、滚动、填表） | CDP |
| 需要视频当前帧截图 | CDP（天然捕获渲染状态） |
GUI vs 程序化
- 程序化（构造 URL 直接导航、eval 操作 DOM）：速度快、精确，但更容易触发反爬
- GUI 交互（点击按钮、填写输入框、滚动浏览）：确定性最高，是反爬场景的可靠兜底
根据实际情况判断，程序化受阻时回退到 GUI 交互。
常见陷阱
- 小红书等平台：内容可能被懒加载或需要滚动才展示，先
/scroll再提取 - 平台返回"内容不存在"：可能是访问方式问题（URL 缺失参数、触发反爬），不一定代表内容真的不存在
- 短时间内大量 /new：可能触发反爬风控，注意控制节奏
截取视频帧
Chrome 渲染 + /screenshot 可捕获当前视频帧。通过 /eval 操作 <video> 元素（获取时长、seek 到任意时间点），再截图可对视频进行离散采样分析。
站点经验积累
操作中积累的站点经验存储在：
C:\Users\jacar\.qclaw\workspace\skills\web-access\references\site-patterns\
格式：
---
domain: example.com
aliases: [示例]
updated: 2026-03-29
---
## 平台特征
架构、反爬行为、登录需求、内容加载方式等事实
## 有效模式
已验证的 URL 模式、操作策略、选择器
## 已知陷阱
什么会失败以及为什么
参考文档
| 文件 | 何时加载 |
|---|---|
references/cdp-api.md |
需要 CDP API 详细参考时 |
references/site-patterns/{domain}.md |
确定目标网站后，读取对应站点经验 |
本 Skill 内容源自 eze-is/web-access，MIT 协议。