web-access 联网能力指南

定位：给 AI Agent 装上「完整联网能力」的 Skill —— 补齐原生 WebSearch/WebFetch 缺的三件事：联网策略 + CDP 浏览器操作 + 站点经验积累。

• 仓库：eze-is/web-access（⭐9k+，MIT）
• 官网：https://web-access.eze.is
• 本机状态：已安装 v2.5.4 → ~/.agents/skills/web-access
• 兼容：所有支持 SKILL.md 的 Agent（Codex、Claude Code、Cursor、Gemini CLI 等）

一、它解决什么问题

二、前置配置（已就绪）

开启浏览器调试（用之前必须做一次）：

1. 打开日常用的 Chrome
2. 地址栏输入：chrome://inspect/#remote-debugging
3. 勾选：Allow remote debugging for this browser instance
4. 弹出授权确认时点「允许」

Edge 用户把地址换成 edge://inspect/#remote-debugging。

固定浏览器偏好（可选，编辑 ~/.agents/skills/web-access/config.env）：

WEB_ACCESS_BROWSER=chrome    # 或 edge
# 留空 = 每次询问

三、核心能力

四、怎么用

方式一：自然语言（推荐）

技能自动触发，直接用业务语言描述需求即可：

帮我搜索 XXX 的最新进展，整理成表格
打开我们公司的内部系统，把今天的订单导出来
去小红书搜「露营装备」，把前 10 篇笔记标题和链接整理给我
读取这篇文章的正文并总结

方式二：CDP Proxy API（精细控制）

Proxy 默认监听 http://localhost:3456，常用接口：

# 列出已打开的 tab
curl -s "http://localhost:3456/targets"

# 新建后台 tab（URL 走 POST body，避免 query 被切分）
curl -s -X POST --data-raw 'https://example.com' http://localhost:3456/new

# 执行任意 JS（读写 DOM、提取数据、提交表单、调用内部方法）
curl -s -X POST "http://localhost:3456/eval?target=ID" -d 'document.title'

# 截图（含视频当前帧）
curl -s "http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png"

# 导航 / 后退
curl -s -X POST "http://localhost:3456/navigate?target=ID" --data-raw 'https://example.com'
curl -s "http://localhost:3456/back?target=ID"

# JS 点击（快速，覆盖大多数场景）
curl -s -X POST "http://localhost:3456/click?target=ID" -d 'button.submit'

# 真实鼠标点击（算用户手势，可触发文件对话框）
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/scroll?target=ID&y=3000"

# 关闭 tab
curl -s "http://localhost:3456/close?target=ID"

# 健康检查
curl -s "http://localhost:3456/health"

Proxy 会自动追踪 /new 创建的 tab，闲置 15 分钟自动关闭，避免留下孤儿标签页（可用 CDP_TAB_IDLE_TIMEOUT 调整）。

五、典型使用场景

六、⚠️ 注意事项与风险

1. 社交平台有封号风险：部分站点对自动化检测严格（内置防护但无法完全避免）。建议用小号操作——Agent 操作即视为接受此风险。
2. 浏览器调试是安全敏感操作：开启远程调试后，本机的程序可完全控制该浏览器（含所有登录态）。建议用完关闭开关，或专用一个浏览器实例。
3. 凭据边界：CDP 直连你的浏览器意味着 Agent 有能力访问你已登录的一切站点（网银、邮箱等）。请确保只在可信会话中使用。
4. 本机已做安全审查：脚本无外发数据、无读取 SSH/密钥行为；sqlite3/spawn 仅用于读取浏览器历史、启动 proxy。Snyk 标记的 "Critical Risk" 属于能力判定（能读浏览器数据+控制浏览器），非恶意代码。

七、故障排查

八、与其他联网工具的分工

相关

• 主库文档：Codex Skills 完整清单（技能全景）
• 仓库地址：https://github.com/eze-is/web-access
• 设计详解：https://mp.weixin.qq.com/s/rps5YVB6TchT9npAaIWKCw