“The only true wisdom is in knowing you know nothing.” — Socrates

Socrates的这句话道出了 AI Agent 在联网场景下的困境：AI 知道很多，但当它需要获取最新、最准确的信息时，它实际上”什么都不知道”。传统 Agent 的联网能力要么依赖搜索引擎的二手信息，要么根本无法访问需要登录态的网页。

web-access 这个 Skill（GitHub Stars 2800+），试图解决这个问题——让 Claude Code 拥有完整、可靠、可控的联网与浏览器操控能力。

web-access 概念图

1. 项目背景与核心定位

1.1 为什么需要 web-access

Claude Code 本身具备 WebSearch 和 WebFetch 能力，但这两个工具都有明显局限：

  • WebSearch：适合发现信息来源，但无法获取需要登录态的内容
  • WebFetch：适合拉取公开页面，但无法处理动态渲染页面，也无法操作网页界面

更关键的是，这两个工具之间没有调度策略——Agent 不知道何时该用搜索，何时该用抓取，何时又必须动用浏览器。

web-access 的核心定位是：给 AI Agent 装上一套完整的联网工具箱，包括智能调度、浏览器自动化和站点经验积累。

1.2 项目信息

项目 信息
GitHub eze-is/web-access
作者 一泽 Eze
版本 2.4.1
许可证 MIT
创建时间 2026-03-18
Stars 2800+

2. 技术原理：三层架构

web-access 的设计基于一个核心洞察：联网任务需要分层的抽象，而不是一个万能工具。

┌─────────────────────────────────────────────────────────┐
│                    web-access 三层架构                      │
├─────────────────────────────────────────────────────────┤
│  第一层：工具调度层    │ 根据场景自主选择最优联网工具              │
│                       │ WebSearch / WebFetch / curl /     │
│                       │ Jina / CDP，按需组合               │
├─────────────────────────────────────────────────────────┤
│  第二层：CDP 浏览器层  │ 直连用户 Chrome，携带登录态            │
│                       │ 支持动态页面、交互操作、视频截帧          │
├─────────────────────────────────────────────────────────┤
│  第三层：站点经验层    │ 按域名存储操作经验（URL 模式、平台特征、   │
│                       │ 已知陷阱），跨 session 复用          │
└─────────────────────────────────────────────────────────┘

2.1 第一层：工具调度层

这是 web-access 的”大脑”，负责根据任务性质选择最合适的联网工具。

场景 推荐工具 原因
搜索摘要或关键词，发现信息来源 WebSearch 适合信息发现
URL 已知，需提取特定信息 WebFetch 拉取网页内容，由小模型提取
URL 已知，需原始 HTML（meta、JSON-LD） curl 获取原始源码
非公开内容，或静态层无效的平台（小红书、微信公众号） 浏览器 CDP 直接跳过静态层
需要登录态或自由导航 浏览器 CDP 携带用户登录态

工具选择的哲学是：一手信息优于二手信息。搜索引擎是定位工具，不是证明工具——找到来源后，直接访问读取原文。

Jina 加速层：第三方服务，可将网页转为 Markdown，大幅节省 token。适合文章、博客、文档、PDF 等以正文为核心的页面。

2.2 第二层：CDP 浏览器层

这是 web-access 的”手”，通过 Chrome DevTools Protocol 直接操控用户的 Chrome 浏览器。

核心能力：

  • 直连用户日常 Chrome：天然携带登录态，无需启动独立浏览器
  • 后台 tab 操作：不影响用户已有标签页
  • 完整浏览器能力：支持动态页面渲染、交互操作、视频截帧

CDP Proxy 通过 WebSocket 直连 Chrome，提供 HTTP API 接口。启动后持续运行，所有操作通过 curl 调用。

2.3 第三层：站点经验层

这是 web-access 的”记忆”，按域名存储已验证的操作经验。

经验内容包括：

  • 平台特征：架构、反爬行为、登录需求、内容加载方式
  • 有效模式：已验证的 URL 模式、操作策略、选择器
  • 已知陷阱：什么会失败以及为什么

经验文件示例：

---
domain: xiaohongshu.com
aliases: [小红书]
updated: 2026-03-25
---
## 平台特征
需要登录态，xsec_token 机制，创作者平台有状态校验

## 有效模式
直接 CDP 访问主站，跳过静态层

## 已知陷阱
手动构造 URL 可能缺失隐式参数，触发反爬

3. CDP 浏览器控制详解

3.1 架构原理

CDP（Chrome DevTools Protocol）是 Chrome 内置的调试协议，web-access 通过 CDP Proxy 封装为 HTTP API：

Agent (curl) → CDP Proxy (Node.js WebSocket) → Chrome (CDP)

用户只需在 Chrome 中开启远程调试（chrome://inspect/#remote-debugging 勾选 Allow），无需其他配置。

3.2 核心 API

API 功能
GET /new?url=URL 创建新后台 tab
POST /eval?target=ID 执行 JavaScript，读取/写入 DOM
POST /click?target=ID JS 层点击（el.click()）
POST /clickAt?target=ID 真实鼠标事件（绕过部分反自动化检测）
POST /setFiles?target=ID 文件上传（绕过文件对话框）
GET /screenshot?target=ID 截图（捕获视频当前帧）
GET /scroll?target=ID 滚动触发懒加载
GET /close?target=ID 关闭 tab

3.3 三种点击方式

web-access 提供了三种点击策略，适用于不同场景：

方式 实现 适用场景
/click JS el.click() 大多数场景，速度快
/clickAt CDP Input.dispatchMouseEvent 需要真实鼠标事件（触发文件对话框、绕过反自动化）
/setFiles DOM.setFileInputFiles 文件上传，直接设置路径

3.4 页面内导航

两种方式打开页面内链接：

  • /click：在当前 tab 内点击，串行处理，适合需要连续操作的场景
  • /new + 完整 URL：在新 tab 中打开，适合需要并行访问多页面的场景

重要设计：站点自己生成的链接天然携带完整上下文（包含 token 等隐式参数），而手动构造的 URL 可能缺失这些参数。web-access 强调提取 URL 时应保留完整地址。

3.5 程序化 vs GUI 交互

浏览器内操作有两种方式：

  • 程序化方式（构造 URL 直接导航、eval 操作 DOM）：速度快、精确，但更容易触发反爬
  • GUI 交互（点击按钮、填写输入框）：为人设计，网站不会限制，确定性最高

当程序化方式受阻时，GUI 交互是可靠的兜底。

4. 与传统方案的对比

4.1 方案横向对比

方案 工具选择 登录态支持 动态页面 交互能力 站点经验
原生 WebSearch/WebFetch 单一工具 ❌ ❌ ❌ ❌
Selenium/Playwright 手动控制 需要启动独立浏览器 ✅ ✅ ❌
RPA 工具 录制+回放 需要配置 ✅ ✅ 有限
web-access 智能调度 ✅ 直连用户 Chrome ✅ ✅ ✅

4.2 核心优势

1. 智能调度而非一刀切 不是把所有任务都推向浏览器，而是根据场景选择最优工具。轻量查询用 WebSearch，需要登录态或交互时再升级到 CDP。

2. 用户 Chrome 天然携带登录态 不需要维护独立的浏览器实例或登录状态，用户日常使用的 Chrome 就是最完整的浏览器环境。

3. 站点经验跨 session 复用 每次成功操作的经验都被记录，下次遇到同类站点可以直接调用，而不需要从零开始摸索。

4. 并行分治提升效率 多目标调研时，分发给子 Agent 并行执行，共享一个 Chrome 实例，tab 级隔离，兼顾速度与安全。

4.3 适用边界

web-access 不是银弹，以下场景可能不适合：

  • 完全禁用 JavaScript 的环境：静态 HTML 抓取更高效
  • 需要严格隔离的自动化测试：应该用独立的浏览器实例
  • 高频短时请求：CDP 开销相对较大，不适合极高频调用

5. 应用场景

5.1 信息核实与调研

场景：用户要求核实”某公司最新公告”或”某政策文件”

web-access 的处理流程：

  1. WebSearch 定位信息来源
  2. 直接访问官方页面（CDP 携带登录态）
  3. 读取原文，提取关键信息
  4. 对照用户提供的声明，判断一致性

一手来源优于二手报道——这是信息核实的核心原则。

5.2 社交媒体操作

场景：用户要求”去小红书搜索某关键词账号”或”在创作者平台发布内容”

对于小红书、微信公众号等反爬严格的平台：

  • 静态抓取无效 → 直接 CDP 访问
  • 需要登录态 → 直连用户 Chrome，自动携带
  • 平台有特殊机制（如 xsec_token）→ 站点经验已记录

5.3 视频内容分析

场景：用户要求”分析某视频的内容”

web-access 通过截图捕获视频当前帧，配合 /eval 操作 <video> 元素（获取时长、seek 到任意时间点），可对视频内容进行离散采样分析。

5.4 多目标并行调研

场景：用户要求”同时调研这 5 个产品的官网，给我对比摘要”

web-access 支持子 Agent 分治策略：

  • 主 Agent 分析任务，分发给多个子 Agent
  • 每个子 Agent 创建独立 tab，并行抓取
  • 主 Agent 只接收摘要，节省上下文 token

5.5 表单填写与文件上传

场景：用户要求”帮我在某平台上传图片并提交表单”

通过 /setFiles 直接设置文件路径，绕过文件对话框；通过 /click 或 /clickAt 提交表单，全程无需用户介入。

6. 设计哲学

web-access 的设计哲学浓缩在一句话中：

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

这意味着：

  • 目标驱动而非步骤驱动：告诉 AI 要什么，而不是一步步教它怎么做
  • 工具自主选择：提供场景和工具特点，AI 根据实际情况判断
  • 经验可累积：成功的策略被记录，失败的陷阱被标注

浏览哲学的核心是“像人一样思考”——带着目标进入，边看边判断，遇到阻碍就解决，不在错误的方式上反复重试。

璞奇启示

web-access 对学习类产品的启示在于“工具分层与智能调度”。

第一，工具需要分层，不是一个万能按钮

web-access 的三层架构揭示了一个重要道理：不同任务需要不同工具，强行用单一工具处理所有任务要么低效，要么脆弱。

学习类产品同样如此——不同的知识点、不同的学习阶段，需要不同的练习形式。刷题适合巩固记忆，但不适合建立理解；案例分析适合深度理解，但不适合快速自测。璞奇如果能根据用户的薄弱点自动选择最合适的练习形式，效果会比”一种形式打天下”好得多。

第二，学习经验需要跨 session 积累

web-access 按域名存储站点经验，让 AI 每次访问都能站在上次成功的基础上。

璞奇的用户学习数据同样需要”跨 session 积累”——用户上次做错的题，下次应该自动避坑；用户在某类知识点上反复出错，说明需要更多同类练习。这种经验驱动的自适应，比简单的”推荐相似题目”更有价值。

第三，一手信息优先

web-access 强调一手来源优于二手报道，直接访问原文比搜索引擎更可靠。

学习场景中，”直接理解概念”比”看别人的解读”更有效。当用户遇到难点时，璞奇应该引导用户回到原始概念（官方文档、原始论文）去理解，而不是在二手解释中打转。

信息说明

  • web-access GitHub 仓库：https://github.com/eze-is/web-access
  • CDP Proxy 基于 Node.js 22+ 和 Chrome 远程调试
  • 项目创建时间：2026-03-18
  • 文章内容基于 v2.4.1 版本