/web-access

name: web-access
license: MIT
description: >
  所有联网操作必须通过此 skill 处理，包括：搜索、网页抓取、登录后操作、网络交互等。
  触发场景：用户要求搜索信息、查看网页内容、访问需要登录的网站、操作网页界面、抓取社交媒体内容（小红书、微博、推特等）、读取动态渲染页面、以及任何需要真实浏览器环境的网络任务。
metadata:
  author: 一泽Eze
  version: "2.6.0"
  github: https://github.com/eze-is/web-access

web-access Skill

前置检查

在开始联网操作前，先检查 CDP 模式可用性；已有连接优先复用：

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

**Node.js 22+** 必需（使用原生 WebSocket）。

脚本先读取 `/health`：已有服务且 `connected === true` 时，校验浏览器偏好后直接使用，不重新探测浏览器、不启动第二个 Proxy；已有服务但连接断开时，由原服务重新连接。只有没有可用服务时，才发现浏览器并启动后台 Proxy。

按脚本输出处理：

• `exit 0` → 直接调用 Proxy API，不再手动启动或重启 Proxy
• `exit 2` → 尚未设置浏览器、也没有可复用的共享服务，进入首次配置（见下）
• `exit 1` → 按 stdout 错误信息处理。若提示包含「Agent 处理顺序」，按其步骤执行（如先用系统命令打开浏览器后重跑），自动可解则不打扰用户；仍失败再向用户求助。「配置错误」只需改正配置，不要为此停止或重启共享服务

**浏览器 = 它的用户数据目录。** `~/.web-access/config.env` 的 `WEB_ACCESS_BROWSER` 存数据目录路径，即含 `Local State` 的那一层（如 `~/Library/Application Support/Dia/User Data`），任何 Chromium 内核浏览器都可以；旧值 `chrome` / `chrome-canary` / `chromium` / `edge` 仍有效，按平台对应到标准目录。日常运行只读该目录里的 `DevToolsActivePort`，连不上就报错，不换浏览器、不猜端口。`--browser <数据目录路径>` 表达本次临时覆盖（不写 config.env）。

**首次配置**：按 `exit 2` 的输出逐步做，步骤以脚本输出为准。要点：脚本只列出应用数据根目录的最外层文件夹名；由你从名字认出浏览器，再用 `browser-probe.mjs` 探测（它只接受根目录下的相对路径）；无论找到几个都要问用户，再把选定的数据目录写入配置。已有健康的共享服务时，前置检查优先复用它，不会进入首次配置。

若调试端口文件不可读，脚本会报告 `EPERM/EACCES`，不要当成浏览器未开启调试。可在 `config.env` 用 `WEB_ACCESS_CDP_PORT` 为日常浏览器显式指定已核对的端口；端口归属由配置提供，不自动猜测，另一浏览器的 `--browser` 不借用此端口。

用户数据（`config.env` 与站点经验）位于用户目录下的 `~/.web-access/`（Windows 为 `%USERPROFILE%\.web-access\`），不在 skill 目录内，升级 skill 不受影响。旧版本存放在 skill 目录内的数据，由前置检查首次运行时自动复制过来，并输出一行 `user-data:` 说明。

Proxy 是全体 Agent 共用的长驻服务。普通任务不因修改代码、连接等待或任务结束重启服务。维护和切换浏览器使用跨平台的 Node 命令（将路径替换为实际 skill 路径）：

node "${CLAUDE_SKILL_DIR}/scripts/proxy-maintenance.mjs" status
node "${CLAUDE_SKILL_DIR}/scripts/proxy-maintenance.mjs" restart

维护命令按实例身份停止服务；有执行中的请求、未完成的 CDP 命令、Agent 标签页或连接正在建立时会拒绝停止，等任务清理完再运行。切换浏览器时先执行 `proxy-maintenance.mjs stop`，成功后再运行 `check-deps.mjs --browser <数据目录路径>`（或改写 config.env 后运行）。旧版本没有维护接口时，命令会提示一次性迁移，不自动强杀。退出码与状态字段见 [API 参考](references/cdp-api.md)。

检查通过后并必须在回复中向用户直接展示以下须知，再执行站点操作：

温馨提示：部分站点对浏览器自动化操作检测严格，存在账号封禁风险。已内置防护措施但无法完全避免，Agent 继续操作即视为接受。

浏览哲学与工作流

**像人一样思考，兼顾高效与适应性的完成任务。**

执行任务时不会过度依赖固有印象所规划的步骤，而是带着目标进入，边看边判断，遇到阻碍就解决，发现内容不够就深入——全程围绕「我要达成什么」做决策。这个 skill 的所有行为都应遵循这个逻辑。

**① 拿到请求** — 先明确用户要做什么，定义成功标准：什么算完成了？需要获取什么信息、执行什么操作、达到什么结果？这是后续所有判断的锚点。

**② 选择起点** — 根据任务性质、平台特征、达成条件，选一个最可能直达的方式作为第一步去验证。一次成功当然最好；不成功则在③中调整。比如，需要操作页面、需要登录态、已知静态方式不可达的平台（小红书、微信公众号等）→ 直接 CDP

**③ 过程校验** — 每一步的结果都是证据，不只是成功或失败的二元信号。用结果对照①的成功标准，更新你对目标的判断：路径在推进吗？结果的整体面貌（质量、相关度、量级）是否指向目标可达？发现方向错了立即调整，不在同一个方式上反复重试——搜索没命中不等于"还没找对方法"，也可能是"目标不存在"；API 报错、页面缺少预期元素、重试无改善，都是在告诉你该重新评估方向。遇到弹窗、登录墙等障碍，判断它是否真的挡住了目标：挡住了就处理，没挡住就绕过——内容可能已在页面 DOM 中，交互只是展示手段。

**④ 完成判断** — 对照定义的任务成功标准，确认任务完成后才停止，但也不要过度操作，不为了"完整"而浪费代价。

联网工具选择

• **确保信息的真实性，一手信息优于二手信息**：搜索引擎和聚合平台是信息发现入口。当多次搜索尝试后没有质的改进时，升级到更根本的获取方式：定位一手来源（官网、官方平台、原始页面）。

| 场景 | 工具 | |------|------| | 搜索摘要或关键词结果，发现信息来源 | **WebSearch** | | URL 已知，需要从页面定向提取特定信息 | **WebFetch**（拉取网页内容，由小模型根据 prompt 提取，返回处理后结果） | | URL 已知，需要原始 HTML 源码（meta、JSON-LD 等结构化字段） | **curl** | | 非公开内容，或已知静态层无效的平台（小红书、微信公众号等公开内容也被反爬限制） | **浏览器 CDP**（直接，跳过静态层） | | 需要登录态、交互操作，或需要像人一样在浏览器内自由导航探索 | **浏览器 CDP** |

浏览器 CDP 不要求 URL 已知——可从任意入口出发，通过页面内搜索、点击、跳转等方式找到目标内容。WebSearch、WebFetch、curl 均不处理登录态。

**Jina**（可选预处理层，可与 WebFetch/curl 组合使用，由于其特性可节省 tokens 消耗，请积极在任务合适时组合使用）：第三方网络服务，可将网页转为 Markdown，大幅节省 token 但可能有信息损耗。调用方式为 `r.jina.ai/example.com`（URL 前加前缀，不保留原网址 http 前缀），限 20 RPM。适合文章、博客、文档、PDF 等以正文为核心的页面；对数据面板、商品页等非文章结构页面可能提取到错误区块。

进入浏览器层后，`/eval` 就是你的眼睛和手：

• **看**：用 `/eval` 查询 DOM，发现页面上的链接、按钮、表单、文本内容——相当于「看看这个页面有什么」
• **做**：用 `/click` 点击元素、`/scroll` 滚动加载、`/eval` 填表提交——像人一样在页面内自然导航
• **读**：用 `/eval` 提取文字内容，判断图片/视频是否承载核心信息——是则提取媒体 URL 定向读取或 `/screenshot` 视觉识别

浏览网页时，**先了解页面结构，再决定下一步动作**。不需要提前规划所有步骤。

页面就绪与完成判断

`/new` 或 `/navigate` 返回，只代表浏览器完成了当前文档的基础加载，不代表用户需要的内容已经出现。HTTP 200、`document.readyState === "complete"`、页面标题出现或导航调用成功，都不能单独作为任务完成标准。

导航后先用 `/eval` 检查目标内容。若目标内容尚未出现，而页面仍是空白、加载态、验证页、登录跳转或其它可能继续变化的中间状态，在默认 15 秒窗口内持续观察 URL、标题和 DOM；页面发生跳转或内容变化后重新判断。只有目标内容已经获取，或观察窗口结束后仍存在明确阻碍，才能继续提取或报告失败。

站点经验可以提供更精确的选择器、等待条件和已知中间状态，但只用于加速判断；即使没有站点经验，也必须遵循上述目标内容就绪规则。

补充：本地浏览器资源

用户指向**本人访问过的页面**（"我之前看的那个讲 X 的文章"、"上次打开过的 XX 面板"）或**组织内部系统**（"我们的 XX 平台"、"公司那个 YY 系统"等公网搜不到的目标）时，检索本地浏览器（Chrome / Edge）书签/历史：

node "${CLAUDE_SKILL_DIR}/scripts/find-url.mjs" [关键词...] [--only bookmarks|history] [--browser chrome|edge] [--limit N] [--since 1d|7h|YYYY-MM-DD] [--sort recent|visits]

（此处 `--browser` 是浏览器名，只支持 Chrome / Edge，与 check-deps 的数据目录写法不同。）

关键词空格分词、多词 AND，匹配 title + url（可省略）；默认遍历所有已安装的 Chromium 系浏览器（Chrome、Edge），`--browser` 限定单一来源；`--since` / `--sort` 仅作用于历史；默认按最近访问倒序，`--sort visits` 按访问次数排序（适合"高频访问的网站"这类场景）。

程序化操作与 GUI 交互

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

• **程序化方式**（构造 URL 直接导航、eval 操作 DOM）：成功时速度快、精确，但对网站来说不是正常用户行为，可能触发反爬机制。
• **GUI 交互**（点击按钮、填写输入框、滚动浏览）：GUI 是为人设计的，网站不会限制正常的 UI 操作，确定性最高，但步骤多、速度慢。

根据对目标平台的了解来灵活选择方式。GUI 交互也是程序化方式的有效探测——通过一次真实交互观察站点的实际行为（URL 模式、必需参数、页面跳转逻辑），为后续程序化操作提供依据；同时当程序化方式受阻时，GUI 交互是可靠的兜底。

**站点内交互产生的链接是可靠的**：通过用户视角中的可交互单元（卡片、条目、按钮）进行的站点内交互，自然到达的 URL 天然携带平台所需的完整上下文。而手动构造的 URL 可能缺失隐式必要参数，导致被拦截、返回错误页面、甚至触发反爬。

浏览器 CDP 模式

通过 CDP Proxy 直连用户日常浏览器（Chrome、Edge、Brave、Arc、Dia 等任意 Chromium 内核浏览器），天然携带登录态，无需启动独立浏览器。 若无用户明确要求，不主动操作用户已有 tab，所有操作都在自己创建的后台 tab 中进行，保持对用户环境的最小侵入。不关闭用户 tab 的前提下，完成任务后关闭自己创建的 tab，保持环境整洁。

启动

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

脚本检查 Node.js 后先复用已有 Proxy；没有可用服务时才检查浏览器调试端口、自动启动并等待连接。Proxy 以脱离当前命令会话的后台进程持续运行，没有运行时长或空闲退出计时器。前置检查的等待超时只结束本次检查，不停止 Proxy。

`/health` 的 `status: "ok"` 表示服务在运行，`connected: true` 表示浏览器连接仍有效。浏览器退出、重启或撤销远程调试权限后，服务可继续运行，但重新连接可能需要浏览器再次授权；不要把服务存活当成连接有效。

Proxy API

所有操作通过 curl 调用 HTTP API：

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

# 创建新后台 tab（自动等待加载）— URL 走 POST body，避免目标 URL 含 query 时被切分
curl -s -X POST --data-raw 'https://example.com' http://localhost:3456/new

# 页面信息
curl -s "http://localhost:3456