web-access README

The project's README from github.com/eze-is/web-access. As one markdown file: README.md.

🌐 Language
image

给 AI Agent 装上完整联网能力的 Skill。
🌐 官网 · 📖 设计详解 · ⚡ 快速安装

AI Agent 原本的联网能力(WebSearch、WebFetch)缺少调度策略和浏览器自动化能力。这个 Agent Skill 补上的是:联网策略 + CDP 浏览器操作 + 站点经验积累。兼容所有支持 SKILL.md 的 Agent(Claude Code、Cursor、Gemini CLI、Codex CLI 等)。

推荐必读:Web Access:一个 Skill,拉满 Agent 联网和浏览器能力 ,完整介绍了 Web-Access Skill 的开发细节与 Agent Skill 设计哲学,帮助你也能写出类似通用、高上限的 Skill


v2.5.4 能力

能力 说明
联网工具自动选择 WebSearch / WebFetch / curl / Jina / CDP,按场景自主判断,可任意组合
CDP Proxy 浏览器操作 直连用户日常浏览器(Chrome / Edge / Chromium 系),天然携带登录态,支持动态页面、交互操作、视频截帧
三种点击方式 /click(JS click)、/clickAt(CDP 真实鼠标事件)、/setFiles(文件上传)
本地浏览器书签/历史检索 find-url.mjs 跨 Chrome / Edge 查询公网搜不到的目标(内部系统)或用户访问过的页面,支持关键词/时间窗/访问频度排序
并行分治 多目标时分发子 Agent 并行执行,共享一个 Proxy,tab 级隔离
站点经验积累 按域名存储操作经验(URL 模式、平台特征、已知陷阱),跨 session 复用
媒体提取 从 DOM 直取图片/视频 URL,或对视频任意时间点截帧分析

v2.5.4 更新:

v2.5.2 更新
  • Microsoft Edge 支持 — CDP Proxy 不再绑定 Chrome,新增 Edge 适配(及 Chromium、Chrome Canary 等 Chromium 系,通过同一套自动发现机制接入)。在 edge://inspect/#remote-debugging 勾选 "Allow remote debugging for this browser instance" 即可
  • 浏览器偏好持久化 — 新增 config.env(gitignored,首次运行从模板创建),通过 WEB_ACCESS_BROWSER 固定默认浏览器;多浏览器同时开启 toggle 时 Agent 会询问偏好。也支持单次覆盖 --browser <chrome|edge>
  • 不擅自降级 — 偏好/指定的浏览器没启动或没开 toggle 时硬错并给出明确处理步骤,不会悄悄连到别的浏览器;proxy 首次成功连接后 pin 住浏览器 id,避免运行中漂移
  • find-url 也支持 Edge — 本地书签/历史检索默认遍历 Chrome 与 Edge,可用 --browser <chrome|edge> 限定单一浏览器
v2.5.0 更新
  • 本地 Chrome 资源检索 — 新增 scripts/find-url.mjs,从本地 Chrome 书签/历史按关键词/时间窗/访问频度定位 URL。典型场景:用户提到组织内部系统("我们的 XX 平台"等公网搜不到的目标)、回查之前访问过但不记得地址的页面、查看最近高频访问网站等(场景感谢 @MVPGFC 在 #60 提出)
v2.4.3 更新
  • 修复 CLAUDE_SKILL_DIR 路径问题 — bash 代码块改用 ${CLAUDE_SKILL_DIR} 字符串替换语法,修复 Windows Git Bash 路径转换错误和变量未设置问题(#47 #46)
  • 站点经验列表合并到前置检查 — 启动检查通过后自动输出已有站点经验列表,移除不可靠的 ! 内联注入
v2.4.1 更新
  • 跨平台支持 — 脚本从 bash 迁移到 Node.js,Windows / Linux / macOS 均可使用
  • DOM 边界穿透 — 新增技术事实:eval 递归遍历可穿透 Shadow DOM、iframe 等选择器不可跨越的边界
v2.4 更新
  • 站点内 URL 可靠性 — 新增事实说明:站点生成的链接自带完整上下文,手动构造的 URL 可能缺失隐式必要参数
  • 平台错误提示不可信 — 新增技术事实:平台返回的"内容不存在"等提示可能是访问方式问题而非内容本身问题
  • 小红书站点经验增强 — xsec_token 机制、创作者平台状态校验、暂存草稿流程
v2.3 更新
  • 浏览哲学重构 — 更清晰的「像人一样思考」框架,强调目标驱动而非步骤驱动
  • Jina 积极推荐 — 明确鼓励在合适场景主动使用 Jina 节省 token
  • 子 Agent prompt 指引优化 — 明确加载写法,增加避免动词暗示执行方式的说明

安装

方式一:npx skills 一键安装(推荐)

npx skills add eze-is/web-access

skills CLI 是开源的 Agent Skill 包管理器,自动检测你的 Agent 环境并安装到正确位置。

方式二:让 Agent 自动安装

帮我安装这个 skill:https://github.com/eze-is/web-access

方式三:Plugin 安装(Claude Code)

claude plugin marketplace add https://github.com/eze-is/web-access
claude plugin install web-access@web-access --scope user

方式四:手动

git clone https://github.com/eze-is/web-access ~/.claude/skills/web-access

前置配置(CDP 模式)

CDP 模式需要 Node.js 22+ 和浏览器(Chrome / Edge)开启远程调试:

  1. 在你想用的浏览器地址栏打开对应 inspect 页面:
    • Chrome:chrome://inspect/#remote-debugging
    • Edge:edge://inspect/#remote-debugging
  2. 勾选 Allow remote debugging for this browser instance(可能需要重启浏览器)

浏览器偏好(config.env)

skill 长期偏好保存在 ${CLAUDE_SKILL_DIR}/config.env(首次运行自动从 config.env.template 创建,gitignored):

# 留空 = 每次启动都询问偏好;设值 = 固定使用该浏览器
WEB_ACCESS_BROWSER=edge

合法值:chrome / edge

临时用别的浏览器(不修改 config.env):

node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs" --browser chrome

切换浏览器(proxy 已连接旧的):

pkill -f cdp-proxy.mjs && node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"

环境检查(Agent 运行时会自动完成前置检查,无需手动执行):

node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"
# $CLAUDE_SKILL_DIR 是 skill 加载时自动设置的环境变量
# 手动运行请替换为实际路径,如 ~/.claude/skills/web-access

CDP Proxy API

Proxy 通过 WebSocket 直连浏览器(兼容 chrome://inspect / edge://inspect 方式,无需命令行参数启动),提供 HTTP API:

# 启动(Agent 会自动管理 Proxy 生命周期,无需手动启动)
node "${CLAUDE_SKILL_DIR}/scripts/cdp-proxy.mjs" &

# 页面操作
curl -s -X POST --data-raw 'https://example.com' http://localhost:3456/new  # 新建 tab(v2.5.3 起 URL 走 POST body)
curl -s -X POST "http://localhost:3456/eval?target=ID" -d 'document.title'  # 执行 JS
curl -s -X POST "http://localhost:3456/click?target=ID" -d 'button.submit'  # JS 点击
curl -s -X POST "http://localhost:3456/clickAt?target=ID" -d '.upload-btn'  # 真实鼠标点击
curl -s -X POST "http://localhost:3456/setFiles?target=ID" \
  -d '{"selector":"input[type=file]","files":["/path/to/file.png"]}'        # 文件上传
curl -s "http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png"     # 截图
curl -s "http://localhost:3456/scroll?target=ID&direction=bottom"           # 滚动
curl -s "http://localhost:3456/close?target=ID"                             # 关闭 tab
curl -s "http://localhost:3456/health"                                      # 查看状态(含 managedTabs 数量)

Proxy 会自动追踪通过 /new 创建的 tab,闲置 15 分钟后自动关闭,防止 Agent 异常退出时留下孤儿 tab。可通过环境变量 CDP_TAB_IDLE_TIMEOUT(单位毫秒)调整超时时间。

⚠️ 使用前提醒

通过浏览器自动化操作社交平台(如小红书)存在账号被平台限流或封禁的风险。强烈建议使用小号进行操作。

使用

安装后直接让 Agent 执行联网任务,skill 自动接管:

设计哲学

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

详见 SKILL.md 中的浏览哲学部分。

License

MIT · 作者:一泽 Eze · 官网

Star History

Star History Chart

Clawhub Download History

Download History

image

web-access (eze-is/web-access)

Searching Database…

What is this?An open-source Agent Skill that gives AI coding agents full web access: it adds smart selection among web tools (WebSearch, WebFetch, curl, Jina, CDP) plus real browser automation through a proxy connected to your own browser.
Is this a standalone app or something my coding agent loads?It's a skill package — a SKILL.md plus Node.js scripts — that your agent loads and follows; it works with Claude Code, Cursor, Gemini CLI, Codex CLI and anything else supporting SKILL.md. You never run it on its own.
What do I need besides the skill — Node, a specific browser?CDP browser mode needs Node.js 22+ and Chrome or Edge with remote debugging enabled: open chrome://inspect/#remote-debugging (or edge://inspect on Edge) and tick 'Allow remote debugging for this browser instance', restarting the browser if asked.
Could the browser automation get my accounts in trouble?Yes — automating social platforms like Xiaohongshu through the browser risks rate-limiting or bans, so the author strongly recommends a burner account. Also, if your preferred browser isn't running with debugging on, the proxy fails hard instead of silently switching.
Does it work on Windows, or is it Mac and Linux only?All three desktops: since v2.4.1 the scripts run on Node.js instead of bash, so Windows, Linux and macOS are all supported.
Why drive my real browser instead of a headless one?The CDP proxy connects to your everyday Chrome or Edge, so it naturally carries your login sessions and handles dynamic pages, real clicks and file uploads that plain HTTP fetches can't. It even grabs video frames from pages for analysis.
What's the 'site experience' feature about?The skill stores operational know-how per domain — URL patterns, platform quirks, known pitfalls — and reuses it across sessions, so it keeps getting better at the sites you actually use, including tricky ones like Xiaohongshu.
Can it research several targets at the same time?Yes — for multi-target tasks it dispatches sub-agents that run in parallel, all sharing one CDP proxy with tab-level isolation between them. A typical ask: research five product websites at once and return a comparison summary.
Can it find pages I've visited before but can't remember?Yes — the bundled find-url.mjs searches your local Chrome and Edge bookmarks and history by keyword, time window or visit frequency, which is handy for internal systems that public search engines simply can't find.
Creator
eze-is
Size
0.2 MB
Stars
9.2K
Age
7mo
Commits · 90 Days