From 7517e6a48cf7b6dcf35bdd9b9f03b7bb8b18cfd9 Mon Sep 17 00:00:00 2001 From: 3109406559-code <250573097+3109406559-code@users.noreply.github.com> Date: Sun, 5 Apr 2026 15:01:18 +0800 Subject: [PATCH] Add Codex-compatible web-access skill support --- README.md | 156 +++-------------- SKILL.md | 300 ++++++++++++++------------------- agents/openai.yaml | 4 + references/cdp-api.md | 131 +++++++------- scripts/cdp-proxy.mjs | 19 ++- scripts/check-deps.mjs | 7 +- scripts/list-site-patterns.mjs | 23 +++ 7 files changed, 274 insertions(+), 366 deletions(-) create mode 100644 agents/openai.yaml create mode 100644 scripts/list-site-patterns.mjs diff --git a/README.md b/README.md index 4abe79c..a6e7216 100644 --- a/README.md +++ b/README.md @@ -1,144 +1,40 @@ -
-
- 🌐 Language -
-
- English - | 简体中文 - | 繁體中文 - | 日本語 - | 한국어 - | Français - | Deutsch - | Español - | Português - | Русский -
-
-
-
+# web-access for Codex -image +This branch adds a Codex-native port of the upstream repository while preserving the existing browser-proxy workflow. -给 Claude Code 装上完整联网能力的 skill。 +- upstream repository: `https://github.com/eze-is/web-access` +- Codex install path: `~/.codex/skills/web-access` -Claude Code 原本有 WebSearch、WebFetch，但缺少调度策略和浏览器自动化能力。这个 skill 补上的是：**联网策略 + CDP 浏览器操作 + 站点经验积累**。 +## What is preserved -> 推荐必读：[Web Access：一个 Skill，拉满 Agent 联网和浏览器能力](https://mp.weixin.qq.com/s/rps5YVB6TchT9npAaIWKCw) ，完整介绍了 Web-Access Skill 的开发细节与 Agent Skill 设计哲学，帮助你也能写出类似通用、高上限的 Skill +- local Chrome CDP proxy +- authenticated browsing through the user's Chrome session +- site-pattern knowledge files +- browser-side extraction workflows +- parallel browser research guidance for independent targets ---- +## Codex-specific changes -## v2.4.1 能力 +- `SKILL.md` is rewritten for Codex skill triggering and tool routing +- shell examples use `~/.codex/skills/web-access/...` +- the CDP proxy now resolves Chrome's full `webSocketDebuggerUrl` through `/json/version` when needed +- `agents/openai.yaml` is added for Codex UI metadata -| 能力 | 说明 | -|------|------| -| 联网工具自动选择 | WebSearch / WebFetch / curl / Jina / CDP，按场景自主判断，可任意组合 | -| CDP Proxy 浏览器操作 | 直连用户日常 Chrome，天然携带登录态，支持动态页面、交互操作、视频截帧 | -| 三种点击方式 | `/click`（JS click）、`/clickAt`（CDP 真实鼠标事件）、`/setFiles`（文件上传） | -| 并行分治 | 多目标时分发子 Agent 并行执行，共享一个 Proxy，tab 级隔离 | -| 站点经验积累 | 按域名存储操作经验（URL 模式、平台特征、已知陷阱），跨 session 复用 | -| 媒体提取 | 从 DOM 直取图片/视频 URL，或对视频任意时间点截帧分析 | - -**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 指引优化** — 明确加载写法，增加避免动词暗示执行方式的说明 -
- -## 安装 - -**方式一：让 Claude 自动安装** - -``` -帮我安装这个 skill：https://github.com/eze-is/web-access -``` - -**方式二：Plugin 安装** - -```bash -claude plugin marketplace add https://github.com/eze-is/web-access -claude plugin install web-access@web-access --scope user -``` - -**方式三：手动** +## Start the proxy ```bash -git clone https://github.com/eze-is/web-access ~/.claude/skills/web-access +node ~/.codex/skills/web-access/scripts/check-deps.mjs ``` -## 前置配置（CDP 模式） - -CDP 模式需要 **Node.js 22+** 和 Chrome 开启远程调试： - -1. Chrome 地址栏打开 `chrome://inspect/#remote-debugging` -2. 勾选 **Allow remote debugging for this browser instance**（可能需要重启浏览器） - -环境检查（Agent 运行时会自动完成前置检查，无需手动执行）： - -```bash -node "$CLAUDE_SKILL_DIR/scripts/check-deps.mjs" -# $CLAUDE_SKILL_DIR 是 skill 加载时自动设置的环境变量 -# 手动运行请替换为实际路径，如 ~/.claude/skills/web-access -``` - -## CDP Proxy API - -Proxy 通过 WebSocket 直连 Chrome（兼容 `chrome://inspect` 方式，无需命令行参数启动），提供 HTTP API： - -```bash -# 启动（Agent 会自动管理 Proxy 生命周期，无需手动启动） -node "$CLAUDE_SKILL_DIR/scripts/cdp-proxy.mjs" & - -# 页面操作 -curl -s "http://localhost:3456/new?url=https://example.com" # 新建 tab -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 -``` - -## ⚠️ 使用前提醒 - -通过浏览器自动化操作社交平台（如小红书）存在账号被平台限流或封禁的风险。**强烈建议使用小号进行操作。** - -## 使用 - -安装后直接让 Agent 执行联网任务，skill 自动接管： - -- "帮我搜索 xxx 最新进展" -- "读一下这个页面：[URL]" -- "去小红书搜索 xxx 的账号" -- "帮我在创作者平台发一篇图文" -- "同时调研这 5 个产品的官网，给我对比摘要" - -## 设计哲学 - -> Skill = 哲学 + 技术事实，不是操作手册。讲清 tradeoff 让 AI 自己选，不替它推理。 - -详见 [SKILL.md](./SKILL.md) 中的浏览哲学部分。 - -## License - -MIT · 作者：[一泽 Eze](https://github.com/eze-is) +## Key scripts -## Star History +- `scripts/check-deps.mjs` +- `scripts/cdp-proxy.mjs` +- `scripts/match-site.mjs` +- `scripts/list-site-patterns.mjs` -[![Star History Chart](https://api.star-history.com/svg?repos=eze-is/web-access&type=Date)](https://star-history.com/#eze-is/web-access&Date) +## References -image +- `SKILL.md` +- `references/cdp-api.md` +- `references/site-patterns/` diff --git a/SKILL.md b/SKILL.md index bfe0659..f065649 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,248 +1,202 @@ --- name: web-access -license: MIT -github: https://github.com/eze-is/web-access -description: - 所有联网操作必须通过此 skill 处理，包括：搜索、网页抓取、登录后操作、网络交互等。 - 触发场景：用户要求搜索信息、查看网页内容、访问需要登录的网站、操作网页界面、抓取社交媒体内容（小红书、微博、推特等）、读取动态渲染页面、以及任何需要真实浏览器环境的网络任务。 +description: End-to-end web research and browser automation through Codex web tools, curl, and a local Chrome CDP proxy. Use when Codex needs to search the web, inspect or extract webpage content, access dynamic or authenticated sites, operate a real browser tab, reuse site-specific patterns, capture media, or coordinate parallel browser research across independent targets when the user explicitly asks for delegation or parallel work. metadata: - author: 一泽Eze - version: "2.4.1" + author: eze-is + version: "2.4.1-codex" --- -# web-access Skill +# Web Access for Codex -## 前置检查 +Use this skill as a Codex-native port of the upstream `eze-is/web-access` repository. +Preserve the upstream behavior and decision logic, but adapt the execution model to Codex: -在开始联网操作前，先检查 CDP 模式可用性： +- Codex reads `SKILL.md` first. +- Codex does not auto-run bundled `.mjs` files. +- Run bundled scripts explicitly through the shell when the workflow calls for them. -```bash -node "$CLAUDE_SKILL_DIR/scripts/check-deps.mjs" -``` - -未通过时引导用户完成设置： -- **Node.js 22+**：必需（使用原生 WebSocket）。版本低于 22 可用但需安装 `ws` 模块。 -- **Chrome remote-debugging**：在 Chrome 地址栏打开 `chrome://inspect/#remote-debugging`，勾选 **"Allow remote debugging for this browser instance"** 即可，可能需要重启浏览器。 +## Required startup for CDP work -检查通过后并必须在回复中向用户直接展示以下须知，再启动 CDP Proxy 执行操作： +Before any real-browser task, run: +```bash +node ~/.codex/skills/web-access/scripts/check-deps.mjs ``` -温馨提示：部分站点对浏览器自动化操作检测严格，存在账号封禁风险。已内置防护措施但无法完全避免，Agent 继续操作即视为接受。 -``` - -## 浏览哲学 - -**像人一样思考，兼顾高效与适应性的完成任务。** - -执行任务时不会过度依赖固有印象所规划的步骤，而是带着目标进入，边看边判断，遇到阻碍就解决，发现内容不够就深入——全程围绕「我要达成什么」做决策。这个 skill 的所有行为都应遵循这个逻辑。 - -**① 拿到请求** — 先明确用户要做什么，定义成功标准：什么算完成了？需要获取什么信息、执行什么操作、达到什么结果？这是后续所有判断的锚点。 -**② 选择起点** — 根据任务性质、平台特征、达成条件，选一个最可能直达的方式作为第一步去验证。一次成功当然最好；不成功则在③中调整。比如，需要操作页面、需要登录态、已知静态方式不可达的平台（小红书、微信公众号等）→ 直接 CDP +Use the script output as the source of truth. -**③ 过程校验** — 每一步的结果都是证据，不只是成功或失败的二元信号。用结果对照①的成功标准，更新你对目标的判断：路径在推进吗？结果的整体面貌（质量、相关度、量级）是否指向目标可达？发现方向错了立即调整，不在同一个方式上反复重试——搜索没命中不等于"还没找对方法"，也可能是"目标不存在"；API 报错、页面缺少预期元素、重试无改善，都是在告诉你该重新评估方向。遇到弹窗、登录墙等障碍，判断它是否真的挡住了目标：挡住了就处理，没挡住就绕过——内容可能已在页面 DOM 中，交互只是展示手段。 +- If it prints `proxy: ready`, proceed with CDP calls. +- If it says Chrome is not connected, fix Chrome remote debugging first. +- If it says the proxy is connecting, wait for it to report ready before issuing browser actions. -**④ 完成判断** — 对照定义的任务成功标准，确认任务完成后才停止，但也不要过度操作，不为了"完整"而浪费代价。 +Keep using the user's real Chrome instance whenever possible so existing login state remains available. -## 联网工具选择 +## Automation risk notice -- **确保信息的真实性，一手信息优于二手信息**：搜索引擎和聚合平台是信息发现入口。当多次搜索尝试后没有质的改进时，升级到更根本的获取方式：定位一手来源（官网、官方平台、原始页面）。 +Before automating social or authenticated platforms, state this warning plainly: -| 场景 | 工具 | -|------|------| -| 搜索摘要或关键词结果，发现信息来源 | **WebSearch** | -| URL 已知，需要从页面定向提取特定信息 | **WebFetch**（拉取网页内容，由小模型根据 prompt 提取，返回处理后结果） | -| URL 已知，需要原始 HTML 源码（meta、JSON-LD 等结构化字段） | **curl** | -| 非公开内容，或已知静态层无效的平台（小红书、微信公众号等公开内容也被反爬限制） | **浏览器 CDP**（直接，跳过静态层） | -| 需要登录态、交互操作，或需要像人一样在浏览器内自由导航探索 | **浏览器 CDP** | +`Some sites detect browser automation aggressively. Account restrictions are still possible even with safeguards. Continuing means accepting that risk.` -浏览器 CDP 不要求 URL 已知——可从任意入口出发，通过页面内搜索、点击、跳转等方式找到目标内容。WebSearch、WebFetch、curl 均不处理登录态。 +## Tool routing in Codex -**Jina**（可选预处理层，可与 WebFetch/curl 组合使用，由于其特性可节省 tokens 消耗，请积极在任务合适时组合使用）：第三方网络服务，可将网页转为 Markdown，大幅节省 token 但可能有信息损耗。调用方式为 `r.jina.ai/example.com`（URL 前加前缀，不保留原网址 http 前缀），限 20 RPM。适合文章、博客、文档、PDF 等以正文为核心的页面；对数据面板、商品页等非文章结构页面可能提取到错误区块。 +Choose the lightest tool that can reliably reach the goal. -进入浏览器层后，`/eval` 就是你的眼睛和手： +| Situation | Use | +|---|---| +| Public discovery, current information, search result exploration | Codex `web` search/open | +| Known URL, mostly static page, raw HTML or JSON-LD needed | shell `curl` | +| Article-like pages where markdown conversion saves tokens | Jina or other text reduction layer if helpful | +| Dynamic rendering, anti-bot barriers, login state, uploads, real clicks, scrolling, screenshots | local CDP proxy | -- **看**：用 `/eval` 查询 DOM，发现页面上的链接、按钮、表单、文本内容——相当于「看看这个页面有什么」 -- **做**：用 `/click` 点击元素、`/scroll` 滚动加载、`/eval` 填表提交——像人一样在页面内自然导航 -- **读**：用 `/eval` 提取文字内容，判断图片/视频是否承载核心信息——是则提取媒体 URL 定向读取或 `/screenshot` 视觉识别 +Do not default to CDP when simpler tools can prove the answer. +Do not stay on static tools after repeated failure against a dynamic or protected site. -浏览网页时，**先了解页面结构，再决定下一步动作**。不需要提前规划所有步骤。 +## Browser philosophy -### 程序化操作与 GUI 交互 +Operate toward the goal, not toward a fixed script. -浏览器内操作页面有两种方式： +1. Define success first. +2. Pick the shortest path that can actually reach the content. +3. Use every page result as evidence. +4. Change approach quickly when the current route is blocked. +5. Stop once the task is actually complete. -- **程序化方式**（构造 URL 直接导航、eval 操作 DOM）：成功时速度快、精确，但对网站来说不是正常用户行为，可能触发反爬机制。 -- **GUI 交互**（点击按钮、填写输入框、滚动浏览）：GUI 是为人设计的，网站不会限制正常的 UI 操作，确定性最高，但步骤多、速度慢。 +Treat the browser as a real environment, not as a screenshot machine. -根据对目标平台的了解来灵活选择方式。GUI 交互也是程序化方式的有效探测——通过一次真实交互观察站点的实际行为（URL 模式、必需参数、页面跳转逻辑），为后续程序化操作提供依据；同时当程序化方式受阻时，GUI 交互是可靠的兜底。 +## Recommended Codex workflow -**站点内交互产生的链接是可靠的**：通过用户视角中的可交互单元（卡片、条目、按钮）进行的站点内交互，自然到达的 URL 天然携带平台所需的完整上下文。而手动构造的 URL 可能缺失隐式必要参数，导致被拦截、返回错误页面、甚至触发反爬。 +### 1. Check for site-specific knowledge -## 浏览器 CDP 模式 - -通过 CDP Proxy 直连用户日常 Chrome，天然携带登录态，无需启动独立浏览器。 -若无用户明确要求，不主动操作用户已有 tab，所有操作都在自己创建的后台 tab 中进行，保持对用户环境的最小侵入。不关闭用户 tab 的前提下，完成任务后关闭自己创建的 tab，保持环境整洁。 - -### 启动 +Before doing CDP work for a known site, try to match existing site patterns: ```bash -node "$CLAUDE_SKILL_DIR/scripts/check-deps.mjs" +node ~/.codex/skills/web-access/scripts/match-site.mjs "" ``` -脚本会依次检查 Node.js、Chrome 端口，并确保 Proxy 已连接（未运行则自动启动并等待）。Proxy 启动后持续运行。 - -### Proxy API - -所有操作通过 curl 调用 HTTP API： +To list recorded site patterns: ```bash -# 列出用户已打开的 tab -curl -s http://localhost:3456/targets - -# 创建新后台 tab（自动等待加载） -curl -s "http://localhost:3456/new?url=https://example.com" - -# 页面信息 -curl -s "http://localhost:3456/info?target=ID" +node ~/.codex/skills/web-access/scripts/list-site-patterns.mjs +``` -# 执行任意 JS：可读写 DOM、提取数据、操控元素、触发状态变更、提交表单、调用内部方法 -curl -s -X POST "http://localhost:3456/eval?target=ID" -d 'document.title' +If a matching pattern exists, read it before browsing. -# 捕获页面渲染状态（含视频当前帧） -curl -s "http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png" +### 2. Use Codex web tools first when they are sufficient -# 导航、后退 -curl -s "http://localhost:3456/navigate?target=ID&url=URL" -curl -s "http://localhost:3456/back?target=ID" +For public pages: -# 点击（POST body 为 CSS 选择器）— JS el.click()，简单快速，覆盖大多数场景 -curl -s -X POST "http://localhost:3456/click?target=ID" -d 'button.submit' +- use Codex web search/open for discovery and verification +- prefer first-party sources over summaries +- move to `curl` when raw HTML or structured metadata matters -# 真实鼠标点击 — CDP Input.dispatchMouseEvent，算用户手势，能触发文件对话框 -curl -s -X POST "http://localhost:3456/clickAt?target=ID" -d 'button.upload' +### 3. Enter CDP mode only when needed -# 文件上传 — 直接设置 file input 的本地文件路径，绕过文件对话框 -curl -s -X POST "http://localhost:3456/setFiles?target=ID" -d '{"selector":"input[type=file]","files":["/path/to/file.png"]}' +Once CDP is required, interact with the proxy at `http://127.0.0.1:3456`. -# 滚动（触发懒加载） -curl -s "http://localhost:3456/scroll?target=ID&y=3000" -curl -s "http://localhost:3456/scroll?target=ID&direction=bottom" +Common flow: -# 关闭 tab -curl -s "http://localhost:3456/close?target=ID" +```bash +curl -s "http://127.0.0.1:3456/targets" +curl -s "http://127.0.0.1:3456/new?url=https://example.com" +curl -s -X POST "http://127.0.0.1:3456/eval?target=ID" -d "document.title" +curl -s "http://127.0.0.1:3456/close?target=ID" ``` -### 页面内导航 +Read [references/cdp-api.md](./references/cdp-api.md) when you need endpoint details or extraction patterns. -两种方式打开页面内的链接： +## CDP operating rules -- **`/click`**：在当前 tab 内直接点击用户视角中的可交互单元，简单直接，串行处理。适合需要在同一页面内连续操作的场景，如点击展开、翻页、进入详情等。 -- **`/new` + 完整 URL**：使用目标链接的完整地址（包含所有URL参数），在新 tab 中打开。适合需要同时访问多个页面的场景。 +- Create your own background tab with `/new`; do not hijack existing user tabs unless the user explicitly asks. +- Use `/eval` as the main way to inspect DOM state, extract structured data, and perform targeted interactions. +- Use `/click` for straightforward DOM clicks. +- Use `/clickAt` when the page needs a real mouse gesture. +- Use `/setFiles` for file uploads. +- Use `/scroll` to trigger lazy loading before extracting image or media URLs. +- Use `/screenshot` when visual confirmation is genuinely necessary. +- Close only the tabs you created. +- Leave the proxy running after the task; avoid forcing the user to re-authorize Chrome. -很多网站的链接包含会话相关的参数（如 token），这些参数是正常访问所必需的。提取 URL 时应保留完整地址，不要裁剪或省略参数。 +## Login judgment -### 媒体资源提取 +Do not ask for login preemptively. -判断内容在图片里时，用 `/eval` 从 DOM 直接拿图片 URL，再定向读取——比全页截图精准得多。 +1. Open the page. +2. Try to obtain the target content. +3. Only if the target content is unavailable and login would likely unblock it, ask the user to log in within Chrome. +4. After login, refresh and continue. Do not restart the proxy. -### 技术事实 -- 页面中存在大量已加载但未展示的内容——轮播中非当前帧的图片、折叠区块的文字、懒加载占位元素等，它们存在于 DOM 中但对用户不可见。以数据结构（容器、属性、节点关系）为单位思考，可以直接触达这些内容。 -- DOM 中存在选择器不可跨越的边界（Shadow DOM 的 `shadowRoot`、iframe 的 `contentDocument`等）。eval 递归遍历可一次穿透所有层级，返回带标签的结构化内容，适合快速了解未知页面的完整结构。 -- `/scroll` 到底部会触发懒加载，使未进入视口的图片完成加载。提取图片 URL 前若未滚动，部分图片可能尚未加载。 -- 拿到媒体资源 URL 后，公开资源可直接下载到本地后用读取；需要登录态才可获取的资源才需要在浏览器内 navigate + screenshot。 -- 短时间内密集打开大量页面（如批量 `/new`）可能触发网站的反爬风控。 -- 平台返回的"内容不存在""页面不见了"等提示不一定反映真实状态，也可能是访问方式的问题（如 URL 缺失必要参数、触发反爬）而非内容本身的问题。 +Phrase the login request concretely, for example: -### 视频内容获取 +`The target content is not accessible without login on . Please log in in your Chrome window, then I will continue.` -用户 Chrome 真实渲染，截图可捕获当前视频帧。核心能力：通过 `/eval` 操控 `