Web-Access Skill

Claude Code 联网增强 Skill — 三层通道调度 + CDP 浏览器自动化 + 站点经验积累

v2.4.1 1,800+ Stars MIT License by 一泽 Eze
5
联网通道
14
CDP API 端点
573
行核心代码
29
Commits
0
外部依赖

架构总览

用户指令
Claude Code
决策层
SKILL.md
通道选择
WebSearch / WebFetch
curl / Jina / CDP
浏览器层
cdp-proxy.mjs
目标
用户 Chrome

SKILL.md 提供策略哲学 → AI 自主推理选通道 → CDP Proxy 通过 WebSocket 直连 Chrome

核心能力

🔌 智能通道调度

根据任务场景自动选择最优联网方式:

  • WebSearch — 搜索摘要、关键词结果
  • WebFetch — 已知 URL 定向提取信息
  • curl — 需要原始 HTML/JSON-LD
  • Jina — 网页转 Markdown,省 token
  • CDP 浏览器 — 动态页面、登录态

🌐 CDP 浏览器操作

直连用户日常 Chrome,天然携带所有登录态。通过 HTTP API 提供:

  • 新建/关闭 Tab,导航、后退
  • 执行任意 JavaScript
  • JS 点击 + CDP 真实鼠标事件
  • 文件上传(绕过文件对话框)
  • 截图(含视频当前帧)
  • 滚动触发懒加载

⚡ 并行分治

多目标任务自动分发子 Agent 并行执行:

  • 共享一个 Chrome + Proxy
  • Tab 级隔离,无竞态风险
  • 抓取内容不进主 Agent 上下文
  • 总耗时 ≈ 单任务时长

📚 站点经验积累

按域名存储操作经验,跨 session 复用:

  • URL 模式、平台特征、已知陷阱
  • 小红书 xsec_token 机制
  • 自动匹配目标站点经验
  • 操作成功后自动更新经验

🎥 媒体提取

从 DOM 直取图片/视频 URL,或对视频进行定点截帧分析:

  • eval 操控 <video> 元素
  • seek 到任意时间点 + screenshot
  • 图片 URL 直接提取,无需全页截图

🔎 信息核实

追溯一手来源而非二手报道:

  • 政策法规 → 发布机构官网
  • 企业公告 → 公司官方页面
  • 学术声明 → 原始论文
  • 避免循环引证假象

📁 源码结构

web-access/
  SKILL.md ← 核心:联网策略 + 浏览哲学 + API 指引(371 行,AI 的"大脑")
  README.md ← 项目说明 + 安装指南
  scripts/
    cdp-proxy.mjs ← CDP Proxy 服务器(573 行 JS,零外部依赖)
    check-deps.sh ← 环境检查 + 自动启动 Proxy
    match-site.sh ← 站点经验匹配脚本
  references/
    cdp-api.md ← CDP API 详细参考文档
    site-patterns/ ← 站点经验文件(按域名存储)

🚀 CDP Proxy API — 14 个端点

Proxy 监听 localhost:3456,通过 WebSocket 直连 Chrome DevTools Protocol,所有操作通过 curl 调用。

端点方法功能
/healthGET健康检查,返回连接状态
/targetsGET列出所有已打开的页面 Tab
/new?url=GET创建新后台 Tab(自动等待加载完成)
/close?target=GET关闭指定 Tab
/navigate?target=&url=GET在已有 Tab 中导航(自动等待加载)
/back?target=GET后退一页
/info?target=GET获取页面 title / URL / readyState
/eval?target=POST执行任意 JS 表达式,支持 async
/click?target=POSTJS 层面点击(el.click())
/clickAt?target=POSTCDP 真实鼠标事件(绕过反自动化)
/setFiles?target=POST文件上传(绕过文件对话框)
/scroll?target=&y=GET滚动页面(触发懒加载,等待 800ms)
/screenshot?target=&file=GET截图保存到文件或返回二进制

💡 设计哲学

"Skill = 哲学 + 技术事实,不是操作手册。" 讲清 tradeoff 让 AI 自己选,不替它推理。

1

拿到请求

明确用户要做什么,定义成功标准:什么算完成?需要获取什么信息、达到什么结果?这是后续所有判断的锚点。

2

选择起点

根据任务性质、平台特征,选最可能直达的方式作为第一步去验证。需要登录态/动态页面 → 直接 CDP。

3

过程校验

每一步结果都是证据。对照成功标准更新判断。方向错了立即调整,不在同一方式上反复重试。

4

完成判断

对照成功标准确认完成后才停止。不为了"完整"而浪费代价,也不因为"差不多"而提前放弃。

对比:web-access vs 现有工具

已有

Claude Code 原生 + Playwright MCP + gptr

  • ✓ WebSearch / WebFetch 基础联网
  • ✓ Playwright 完整浏览器自动化
  • ✓ gptr 深度调研出报告
  • ✗ 每次启动全新浏览器,无登录态
  • ✗ 需手动判断该用哪个工具
  • ✗ 无站点经验积累
web-access 增量价值

CDP 直连 + 策略调度 + 经验复用

  • 直连用户 Chrome 登录态(核心差异)
  • ★ AI 自主选通道,无需手动指定
  • ★ 站点经验跨 session 复用
  • ★ 零外部依赖,573 行代码
  • ★ 子 Agent 并行分治
  • ★ 视频截帧分析能力

</> 技术亮点

🔌 零依赖设计

整个 CDP Proxy 仅使用 Node.js 原生模块:httpurlfsnetos。 Node 22+ 的原生 WebSocket 替代了 ws 模块,做到真正零 npm install

🔎 自动发现 Chrome 端口

不需要用户手动指定端口。自动读取 DevToolsActivePort 文件获取端口和 WebSocket 路径, 支持 macOS / Linux / Windows 三平台。回退扫描 9222、9229、9333 常用端口。

🛡 防重复启动

启动时先用 TCP 探测端口是否被占用。若已有实例运行且健康(/health 返回 ok),静默退出。 避免多个 Proxy 实例冲突。

📈 站点经验匹配

match-site.sh 读取用户输入,遍历 site-patterns/*.md 文件, 用域名 + aliases 做模式匹配,自动输出相关站点经验。跨会话积累,越用越聪明。

// cdp-proxy.mjs 核心连接逻辑(简化)
async function discoverChromePort() {
  // 1. 读 DevToolsActivePort 文件获取端口
  for (const p of possiblePaths) {
    const port = parseInt(fs.readFileSync(p));
    if (await checkPort(port)) return { port, wsPath };
  }
  // 2. 回退扫描常用端口 [9222, 9229, 9333]
}

// HTTP API → CDP WebSocket → Chrome
function sendCDP(method, params, sessionId) {
  ws.send(JSON.stringify({ id: ++cmdId, method, params, sessionId }));
}

📋 评估结论

适合安装的场景

  • 需要 Claude Code 操作已登录的网站(后台管理、社交平台、内部系统)
  • 经常访问反爬严格的站点(小红书、微信公众号等)
  • 希望联网操作更智能,不用手动选 WebFetch 还是 Playwright
  • 需要视频截帧分析或复杂的浏览器交互

不需要安装的场景

  • 现有 WebFetch + Playwright + gptr 已满足需求
  • 不需要操作需登录的网站
  • 主要做代码开发,联网需求少

核心价值:一句话总结 — web-access 的不可替代优势是直连用户 Chrome 登录态。 其余能力(搜索、抓取、浏览器操作)在现有工具链中已有覆盖,web-access 做的是更聪明的调度 + 更省心的体验